Nginx WebSocket：proxy_http_version升级

键盘旁的猫

发布时间：2026-09-09 | 3人浏览过

原创

理解WebSocket连接升级与Nginx代理机制

WebSocket协议的设计初衷是在单个TCP连接上实现全双工通信。其建立过程始于一次标准的HTTP请求，客户端通过发送包含Upgrade: websocket和Connection: Upgrade请求头的GET报文发起握手。当服务端认可该请求时，会返回101 Switching Protocols状态码，随后底层TCP连接不再遵循HTTP的请求-响应模型，而是转为持久化的双向数据流。在Nginx作为反向代理的场景中，默认情况下Nginx使用HTTP/1.0协议与上游服务器通信，且会主动过滤掉Upgrade和Connection这类逐跳请求头。如果不进行特殊配置，Nginx会将WebSocket握手请求降级为普通HTTP请求转发，导致后端无法识别升级意图，连接随即断开。因此，必须显式告知Nginx使用HTTP/1.1协议，并原样透传关键升级头，才能确保代理层正确桥接长连接。

展示真实Nginx反向代理WebSocket架构或配置场景，突出浏览器、Nginx、WebSocket后端之间的HTTP Upgrade握手和长连接数据流。 — 展示客户端经Nginx反向代理向WebSocket后端发起HTTP/1.1 Upgrade握手，并通过101 Switching Protocols建立长连接。

配置proxy_http_version与WebSocket升级请求头

在Nginx中配置WebSocket代理，核心在于location块内的指令组合。标准配置需包含proxy_http_version 1.1，该指令强制Nginx与上游使用HTTP/1.1通信，这是维持长连接和正确处理分块传输的基础。配合proxy_set_header Upgrade $http_upgrade与proxy_set_header Connection upgrade，负责将客户端的升级请求头映射并转发给后端。生产环境中更推荐使用map指令动态处理Connection头，例如定义map $http_upgrade $connection_upgrade { default upgrade; '' close; }，随后在location中配置proxy_set_header Connection $connection_upgrade，以避免非WebSocket请求被错误标记。与普通HTTP反向代理相比，常规代理通常依赖默认的HTTP/1.0，请求结束后连接立即关闭，且无需处理Upgrade头；而WebSocket代理必须保持TCP通道开放，任何对协议版本或请求头的遗漏都会直接导致握手失败。

展示真实Nginx配置文件或Linux终端中的WebSocket反向代理配置，清晰看到proxy_http_version 1.1和Upgrade、Connection相关指令。 — 展示Nginx WebSocket代理配置中的proxy_http_version 1.1以及Upgrade、Connection请求头设置。

验证WebSocket握手与长连接是否正常

验证WebSocket代理是否生效，最直观的方式是通过浏览器开发者工具。打开Chrome DevTools，切换至Network面板并勾选WS过滤器，刷新页面或触发连接。若配置正确，首条请求的状态码将显示为101 Switching Protocols。点击该请求查看Headers标签，Request Headers中必须包含Upgrade: websocket和Connection: Upgrade，Response Headers中同样会返回这两个字段。随后切换至Frames标签，即可实时观察客户端与服务端双向收发的文本或二进制帧数据。若需通过命令行验证，可使用curl -i -N -H Connection: Upgrade -H Upgrade: websocket -H Sec-WebSocket-Version: 13 -H Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== http://your-domain/ws，终端应直接打印101响应头并保持连接不退出。也可借助wscat -c ws://your-domain/ws进行交互式消息收发测试，确认长连接在空闲状态下不会异常中断。

排查升级失败、超时与生产环境常见坑

生产环境中WebSocket代理失败多由配置疏漏或参数不当引起。若未设置proxy_http_version 1.1，Nginx默认使用HTTP/1.0，后端会因协议不匹配返回400或200而非101，导致握手失败。若遗漏Upgrade或Connection头，后端无法识别升级意图，连接会立即断开。超时问题极为常见，Nginx默认的proxy_read_timeout为60秒，若WebSocket在60秒内无数据交互，Nginx会主动切断连接并记录upstream timed out错误，需在location中显式调大该值。此外，location路径匹配错误会导致请求落入默认HTTP代理块。对于WSS场景，需确保Nginx已正确配置SSL证书，且proxy_pass指向后端的协议与后端实际监听协议一致。排查时优先检查error.log中的502 Bad Gateway或504 Gateway Time-out，结合tcpdump抓包分析握手阶段的TCP三次握手与HTTP Upgrade报文，可快速定位是Nginx拦截还是后端拒绝。