在 nginx 中配置 websocket 长连接超时,核心是同时设置 http 升级握手阶段的代理超时和 tcp 连接的 keepalive 超时。你需要将 proxy_read_timeout、proxy_send_timeout 和 proxy_connect_timeout 设置为一个较大的值(如 3600s),并配合 keepalive_timeout 来维持底层 tcp 连接。这样既保证了握手成功,又防止了空闲连接被中间网络设备或 nginx 自身切断。

如何区分 WebSocket 握手与数据转发阶段的超时控制
Nginx 处理 WebSocket 连接时,会先经历一个 HTTP 到 WebSocket 的协议升级过程,随后进入全双工的数据传输阶段。这两个阶段对超时的敏感度不同:握手阶段需要快速响应,而数据传输阶段可能长时间无交互。因此,必须针对这两个阶段分别配置超时参数,确保握手不被误杀,且长连接能持续存活。

server {
listen 80;
server_name ws.example.com;
location /ws/ {
proxy_pass http://backend_server;
# 1. 基础 WebSocket 头透传
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
# 2. 握手阶段超时 (HTTP 代理超时)
# 这些参数在握手完成后通常不再起作用,除非发生错误
proxy_connect_timeout 5s; # 建立后端连接的时间
proxy_send_timeout 5s; # 向后端发送请求头的时间
proxy_read_timeout 5s; # 等待后端响应的时间
# 3. 长连接存活超时 (TCP Keepalive)
# 这是保持 WebSocket 长连接不断的关键
proxy_read_timeout 3600s; # 读取后端数据的超时时间
proxy_send_timeout 3600s; # 向后端发送数据的超时时间
# 4. 客户端连接超时
keepalive_timeout 3600s;
}
}
上述配置中,前三个 proxy_*_timeout 用于确保握手快速失败或成功。后两个 proxy_read_timeout 和 proxy_send_timeout 覆盖了之前的值,专门用于 WebSocket 数据传输阶段。如果只设置握手超时而不设置数据转发超时,Nginx 会在默认 60 秒后切断空闲连接。通过将其设为 3600 秒,可以允许连接在长达一小时内无任何数据交换。
为什么需要单独配置 keepalive_timeout 和 proxy 超时
很多开发者混淆了 Nginx 的 keepalive_timeout 和 proxy_read_timeout。前者控制的是 Nginx 与客户端之间的 TCP 连接保持时间,后者控制的是 Nginx 与后端服务器之间的数据交互超时。对于 WebSocket,两者都需要适当调大,但作用点不同。keepalive_timeout 防止 Nginx 主动断开与浏览器的连接,而 proxy_read_timeout 防止 Nginx 认为后端“死掉”而断开与后端的连接。
可水平扩展的 WebSocket 中心模式,支持懒加载 Redis 订阅、连接注册表和优雅关闭。适用于构建可跨多实例扩展的实时 WebSocket 服务器。

# 在后端应用层实现心跳检测 (Node.js 示例)
const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });
wss.on('connection', (ws) => {
// 设置心跳定时器
const heartbeatInterval = setInterval(() => {
if (ws.readyState === WebSocket.OPEN) {
ws.ping(); // 发送 Ping 帧
} else {
clearInterval(heartbeatInterval);
ws.terminate();
}
}, 30000); // 每 30 秒发送一次心跳
ws.on('pong', () => {
console.log('Client is alive');
});
ws.on('close', () => {
clearInterval(heartbeatInterval);
});
});
即使 Nginx 配置了长超时,网络中的防火墙或负载均衡器也可能有独立的空闲超时限制(通常为 5-10 分钟)。因此,仅靠 Nginx 配置是不够的。最佳实践是在应用层实现心跳机制,如上面的 Node.js 代码所示,定期发送 WebSocket Ping/Pong 帧。这不仅能穿透中间设备的空闲超时,还能及时发现断开的连接。Nginx 的 proxy_read_timeout 应设置为大于应用层心跳间隔的值,例如心跳 30 秒,Nginx 超时设为 3600 秒,这样既安全又高效。
当 WebSocket 连接意外中断时如何排查
如果配置了长超时但连接仍然中断,通常是因为中间网络设备(如云厂商的 LB)或应用层未发送心跳。排查时,首先检查 Nginx 错误日志中的 upstream timed out 或 client timed out 记录。其次,确认后端服务是否在处理大量并发时触发了自身的资源限制。最后,验证应用层心跳是否正常发送,可以通过 Wireshark 抓包查看 TCP 层面的 ACK 和 WebSocket 帧。
# 查看 Nginx 错误日志定位超时原因
$ tail -f /var/log/nginx/error.log | grep -E "timed out|websocket"
# 使用 curl 测试 WebSocket 升级是否成功
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
-H "Host: ws.example.com" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
-H "Sec-WebSocket-Version: 1.1" http://ws.example.com/ws/
通过日志分析,你可以确定超时发生在哪个阶段。如果是 upstream timed out,说明 Nginx 与后端之间的问题,需检查后端性能或 proxy_read_timeout 设置。如果是 client timed out,则需检查 keepalive_timeout 或客户端网络。结合应用层心跳日志,可以全面定位问题根源。










