连接断开通常是因为 nginx 默认配置未开启 websocket 所需的 http/1.1 升级机制,导致握手失败或长连接被超时切断。要解决这个问题,需要在 nginx 的 location 块中设置 proxy_http_version 1.1;,并手动添加 upgrade 和 connection 请求头,同时确保 proxy_read_timeout 足够长以维持空闲连接。

Nginx 代理 WebSocket 需要哪些关键配置参数?
必须配置 proxy_set_header Upgrade 和 proxy_set_header Connection 来传递升级信号,并将 proxy_http_version 设为 1.1。这些参数告诉上游服务器客户端希望建立持久连接,Nginx 才会将 TCP 通道保持打开状态而不进行传统的 HTTP 短连接处理。

server {
listen 80;
server_name 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_read_timeout 3600s;
proxy_send_timeout 3600s;
}
}
上述配置中,$http_upgrade 变量来自客户端请求头。如果客户端发起的是普通 HTTP 请求,该变量为空,此时 Connection 设置为 upgrade 可能不会触发升级,但通常 WebSocket 客户端会发送明确的 Upgrade: websocket 头。关键在于 proxy_http_version 1.1,因为 HTTP/1.0 默认使用 Connection: close,这会强制 Nginx 在响应后关闭连接。
为什么即使配置了升级,连接仍可能在一段时间后断开?
除了握手阶段,连接维持阶段受 proxy_read_timeout 和 proxy_send_timeout 控制。如果这两个值过小(默认通常为 60 秒),而 WebSocket 连接处于空闲状态(没有数据收发),Nginx 会认为连接超时并主动关闭它。此外,中间网络设备如负载均衡器或防火墙也可能有独立的空闲超时策略。

# 检查 Nginx 全局或 server 级别的超时设置
# 如果未显式设置,默认为 60s
# 对于长连接的 WebSocket,建议设置为更大的值或根据业务需求调整
# 示例:在 location 块中覆盖默认超时
location /ws {
proxy_read_timeout 86400s; # 设置为 24 小时
proxy_send_timeout 86400s;
# ... 其他配置 ...
}
在实际部署中,还需要注意操作系统层面的 TCP 超时设置。Linux 内核的 net.ipv4.tcp_keepalive_time 等参数会影响底层连接的保活行为。如果 Nginx 与后端服务之间的链路较长,可能需要启用 TCP Keepalive 或在应用层实现心跳包(Heartbeat)来检测连接状态并刷新空闲计时器。
如何验证 WebSocket 连接是否成功建立并保持稳定?
可以通过查看 Nginx 访问日志中的状态码来初步判断。成功的 WebSocket 握手应返回 101 Switching Protocols。如果返回 400 或 502,则说明配置有误或上游服务不可用。连接建立后,可以使用浏览器开发者工具的网络面板观察 WS 帧的收发情况,或使用 wscat 等命令行工具进行连通性测试。
# 使用 wscat 测试连接 wscat -c ws://example.com/ws # 如果连接成功,终端将进入交互模式 # 如果断开,通常会显示 "error: socket hang up" 或类似信息 # 查看 Nginx 错误日志排查具体原因 tail -f /var/log/nginx/error.log
在测试时,确保客户端和服务端都支持标准的 WebSocket 协议。某些旧版 Nginx 版本可能存在对 Upgrade 头处理的 Bug,建议升级到最新稳定版。同时,检查后端应用是否正确处理了 Sec-WebSocket-Accept 响应头,这是握手成功的关键标志。











