WebSocket长连接在Nginx反向代理中的常见痛点

WebSocket协议与普通HTTP请求不同，其连接建立后需要长时间保持双向通信。当通过Nginx反向代理转发WebSocket流量时，默认配置下Nginx会在60秒内关闭无活动的连接，导致业务出现异常断连、消息推送失败等问题。这并非业务代码缺陷，而是代理层超时策略与长连接业务不匹配所致。

核心参数：proxy_read_timeout与proxy_send_timeout

Nginx处理WebSocket反向代理时，最关键的超时参数是proxy_read_timeout和proxy_send_timeout。前者定义Nginx等待后端服务器响应数据的超时时间，后者定义Nginx向后端发送请求数据的超时时间。默认均为60秒，对长连接业务而言明显不足。

合理取值建议

超时时间需根据业务心跳机制确定。若客户端每30秒发送一次心跳，建议将超时设置为心跳间隔的2~3倍，即60~90秒；若业务存在长时间无消息推送（如静默通知），可设置300秒甚至更长。通用配置示例：

proxy_read_timeout 300s;
proxy_send_timeout 300s;

其他必须协同调整的参数

proxy_http_version与Upgrade头

必须显式设置HTTP/1.1及Upgrade头，否则WebSocket握手无法完成：

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

proxy_connect_timeout

该参数控制与后端建立TCP连接的超时时间，默认60秒通常足够，无需过度调整，避免因后端异常导致连接长时间挂起。

keepalive与连接复用

若后端为多个Nginx实例或负载均衡层，可启用上游keepalive连接池减少TCP握手开销：

upstream websocket_backend {
    server 192.168.1.10:8080;
    keepalive 32;
}
server {
    location /ws/ {
        proxy_pass http://websocket_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

按业务类型差异化调整

• 即时聊天：依赖心跳，通常180~300秒足够，需确保心跳报文不被Nginx日志刷屏。
• 股票行情推送：推送频繁，但极端行情下可能出现延迟，建议600秒以上并配合业务层重连机制。
• 物联网设备长连接：设备可能数小时无消息，建议设置3600秒，同时借助Nginx的map模块按不同路径分发不同超时策略。

验证与监控

调整参数后，应通过高并发长连接模拟测试，观察Nginx错误日志中upstream timed out是否消失。同时建议开启Nginx stub_status或集成Prometheus监控连接数，及时掌握连接生命周期。若业务允许，可配合客户端自动重连机制作为兜底，避免单点超时造成不可用。

小结

Nginx反向代理WebSocket的调优本质是让代理层的超时策略匹配业务心跳与消息推送的真实节奏。合理设置proxy_read_timeout和proxy_send_timeout，并确保Upgrade头配置正确，即可大幅减少长连接异常断开的概率。建议每次变更后先灰度测试，再逐步推广到全量节点。