Nginx反向代理：WebSocket代理与长连接保持

理解Nginx中的WebSocket反向代理与长连接机制

WebSocket协议的设计初衷是为了在浏览器与服务器之间建立全双工通信通道。由于WebSocket握手阶段复用HTTP协议，客户端会发送一个包含Upgrade: websocket和Connection: Upgrade请求头的HTTP请求。Nginx作为反向代理，默认行为是处理标准的HTTP请求-响应模型，即收到请求后转发给后端，拿到完整响应后立即关闭连接。若要支持WebSocket，Nginx必须识别握手阶段的Upgrade头，将连接协议从HTTP/1.1切换为WebSocket，并在握手成功后保持底层TCP连接不中断，实现双向数据帧的透明转发。与普通HTTP代理不同，WebSocket代理不关心应用层报文内容，而是维持长连接状态，持续转发二进制或文本帧。这意味着Nginx不能像处理普通HTTP那样设置短超时或立即释放连接，而需要专门配置以维持连接活跃，否则长连接会在代理层被意外切断。

配置Nginx实现WebSocket代理与长连接保持

在Nginx中配置WebSocket代理，核心在于正确传递升级头并调整超时参数。首先，在server块中定义location匹配WebSocket路径，例如location /ws/。使用proxy_pass将请求转发至后端服务地址。关键步骤是设置proxy_http_version 1.1;，因为WebSocket握手依赖HTTP/1.1的持久连接特性。接着，必须通过proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection upgrade;将客户端的升级请求头原样透传给后端。若客户端未发起升级请求，Nginx需降级处理，可使用map指令动态设置Connection头：map $http_upgrade $connection_upgrade { default upgrade; '' close; }。最后，调整proxy_read_timeout和proxy_send_timeout，例如设为3600s或更长，避免Nginx因默认60秒超时主动断开空闲的长连接。完整配置需将上述指令组合，确保代理层不干预WebSocket帧结构，仅做TCP层面的数据透传。

验证连接是否正常：握手、持续通信与断线测试

配置完成后，需通过多维度验证WebSocket连接的稳定性。首先检查握手状态：在浏览器开发者工具的Network面板中，筛选WS请求，观察状态码是否为101 Switching Protocols，并确认Response Headers中包含Upgrade: websocket。若返回200或400，说明升级头未正确传递或后端未启用WebSocket。其次，验证持续通信：在面板的Messages标签页中，可实时查看客户端与服务器交换的文本或二进制帧，也可使用wscat -c ws://your-domain/ws/命令行工具手动发送心跳包，观察是否持续收到响应。针对断线问题，需结合Nginx访问日志与错误日志排查。在access.log中，WebSocket连接通常记录为单次长请求，耗时极长；若频繁出现499状态码，代表客户端主动断开。在error.log中搜索upstream timed out或client closed connection，可定位是代理超时设置过短，还是后端服务异常重启导致连接中断。

常见避坑：超时、连接头、HTTPS与负载均衡

实际生产环境中，WebSocket长连接常因配置疏漏而中断。首要陷阱是超时参数：Nginx默认proxy_read_timeout为60秒，若业务心跳间隔大于此值，Nginx会误判连接空闲并强制关闭，需根据业务心跳周期合理调大该值，或启用proxy_next_upstream off避免重试干扰。其次，请求头配置错误极为常见，若遗漏Connection头或拼写错误，后端将无法识别升级请求，导致降级为普通HTTP。在HTTPS环境下，前端必须使用wss://协议发起连接，且Nginx需配置SSL证书，否则浏览器会因混合内容安全策略拦截请求。最后，在负载均衡场景下，若后端为多节点集群，必须配置ip_hash或基于Cookie的会话保持（sticky），否则WebSocket握手与后续数据帧可能被路由至不同节点，导致连接状态丢失或消息乱序。此外，长连接会占用大量文件描述符，需同步调高worker_connections与系统ulimit限制。