在 nginx 中配置 websocket 心跳保活,核心在于利用 `proxy_read_timeout` 和 `proxy_send_timeout` 参数维持连接活跃,防止中间网络设备因长时间无数据传输而切断连接。具体做法是在 `location` 块中设置这两个超时时间大于等于客户端的心跳间隔,并确保 `upgrade` 和 `connection` 头正确透传。这样当客户端发送心跳包时,nginx 会将其视为有效数据流,从而重置空闲计时器,保持长连接不断开。

Nginx 如何透传 WebSocket 升级请求
Nginx 必须正确识别并转发 WebSocket 的 HTTP 升级请求,才能建立双向通信通道。这需要在 `location` 块中显式设置 `Upgrade` 和 `Connection` 头部变量,将客户端的请求头原样传递给后端服务。如果缺少这些配置,Nginx 会将 WebSocket 握手视为普通 HTTP 请求,导致连接无法升级或立即关闭。

server {
listen 80;
server_name ws.example.com;
location /ws {
proxy_pass http://backend_server;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
上述配置中,`proxy_http_version 1.1` 是必须的,因为 WebSocket 协议基于 HTTP/1.1。`proxy_set_header Upgrade $http_upgrade` 将客户端的 `Upgrade: websocket` 头传递给后端。`proxy_set_header Connection "upgrade"` 确保连接被标记为升级模式。后端服务收到这些头后,会执行握手流程并返回 101 Switching Protocols 响应。Nginx 接收到该响应后,会将 TCP 连接转换为 WebSocket 连接,并开始代理数据帧。
如何设置超时以维持心跳连接
为了防止连接空闲超时断开,需要合理设置 `proxy_read_timeout` 和 `proxy_send_timeout`。这两个参数定义了 Nginx 等待后端响应或向后端发送数据的最大时间。如果设置为默认的 60 秒,而客户端心跳间隔为 30 秒,则连接可能因超过 60 秒无数据而被 Nginx 主动关闭。因此,应将超时时间设置为略大于心跳间隔的值。
可水平扩展的 WebSocket 中心模式,支持懒加载 Redis 订阅、连接注册表和优雅关闭。适用于构建可跨多实例扩展的实时 WebSocket 服务器。

server {
listen 80;
server_name ws.example.com;
location /ws {
proxy_pass http://backend_server;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# 设置超时时间为 5 分钟,大于心跳间隔 30 秒
proxy_read_timeout 300s;
proxy_send_timeout 300s;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
在上述配置中,`proxy_read_timeout 300s` 表示 Nginx 等待后端发送数据的超时时间为 5 分钟。`proxy_send_timeout 300s` 表示 Nginx 向后端发送数据的超时时间也为 5 分钟。只要客户端每 30 秒发送一次心跳包,Nginx 就会认为连接活跃,不会触发超时断开。需要注意的是,`proxy_read_timeout` 不仅影响 WebSocket 连接,还影响其他 HTTP 请求。如果同一 `server` 块中包含普通 HTTP 接口,可能需要使用 `map` 指令或单独 `location` 块来区分处理,避免普通请求因超时时间过长而影响性能。
WebSocket 连接中断时的重连机制如何处理
即使配置了心跳保活,网络波动或服务器重启仍可能导致 WebSocket 连接意外中断。此时,客户端需要实现自动重连机制,以确保连接的可用性。常见的做法是使用 JavaScript 的 `WebSocket` API,监听 `onclose` 事件,并在一定延迟后尝试重新连接。同时,服务端应支持快速重连,避免因频繁重连造成资源浪费。
const ws = new WebSocket('ws://ws.example.com/ws');
ws.onopen = () => {
console.log('Connected');
// 启动心跳
const heartbeatInterval = setInterval(() => {
if (ws.readyState === WebSocket.OPEN) {
ws.send(JSON.stringify({ type: 'ping' }));
}
}, 30000);
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.type === 'pong') {
console.log('Pong received');
}
};
ws.onclose = (event) => {
console.log('Disconnected', event.code, event.reason);
// 延迟 5 秒后重连
setTimeout(() => {
console.log('Reconnecting...');
// 创建新的 WebSocket 实例
// 注意:实际项目中应管理连接状态,避免重复创建
}, 5000);
};
ws.onerror = (error) => {
console.error('WebSocket Error:', error);
};
上述代码展示了客户端的基本心跳和重连逻辑。在 `onopen` 事件中,启动一个定时器,每 30 秒发送一次 `ping` 消息。在 `onmessage` 事件中,处理服务端返回的 `pong` 消息。在 `onclose` 事件中,记录断开原因,并延迟 5 秒后尝试重新连接。这种机制确保了在网络不稳定时,客户端能够自动恢复连接,保持业务的连续性。服务端只需简单回应 `pong` 即可,无需复杂的状态管理。

















