Nginx WebSocket 反向代理配置与连接失败排查

Nginx 普通 HTTP 请求成功，不代表 WebSocket 握手和长连接也正常。排查时应先验证普通请求，再检查 HTTP/1.1、Upgrade 头、upstream 和超时设置，最后观察 Nginx 日志与断线原因。

Nginx 在 WebSocket 代理链路中负责什么

先画出客户端、代理 IP、反向代理和目标服务的链路，确认每一跳使用的协议、主机、端口和认证。本文重点是 Nginx 的 WebSocket 反向代理；如果客户端还配置了代理 IP，应把客户端到 Nginx、Nginx 到 upstream 分开验证。

如何配置并验证 Nginx WebSocket 反向代理

设置 HTTP/1.1 和连接升级请求头

从最小可复现配置开始，确认 proxy_http_version 1.1，并正确传递 Upgrade 和 Connection 头。例如：

```nginx
location /socket {
proxy_pass http://websocket_upstream;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 300s;
}
```

先运行 nginx -t，再 reload，最后用 WebSocket 客户端验证握手和长连接。

确认 location、upstream 和请求路径一致

核对 location 匹配规则、upstream 地址、端口和目标路径，避免普通 HTTP 正常但 WebSocket 请求被转发到错误位置。

用 proxy_read_timeout 保持长连接

根据业务连接时长设置 proxy_read_timeout，再验证握手、长连接和断线重连。高并发或连接池问题可参考并发、QPS 与连接池。

从 access log 和 error log 判断故障位置

记录 Nginx access/error log、状态码、响应头、连接时长和关闭原因，用于区分客户端、Nginx 与上游服务问题。

Nginx WebSocket 连接失败时怎么排查

如果无法判断问题来自网络出口还是 Nginx 配置，可先用代理 IP 故障排查中心区分故障层级。

握手失败或返回 407 时检查什么

握手失败先查 Upgrade 头和目标路径；如果 407 来自客户端到前置代理的连接，优先核对代理认证信息和端口。Nginx 反向代理 upstream 本身通常不负责这层代理认证。

TLS 报错时检查 SNI、证书和客户端版本

TLS 错误检查证书、SNI、目标域名和客户端版本，确认 upstream 使用的协议正确。连接拒绝、TLS 或超时问题可继续参考timeout、connection refused、TLS 错误排查。

返回 502 或 504 时检查 upstream

502 先查 upstream 地址、端口、TLS 和连接拒绝；504 重点查上游响应时间与 proxy_read_timeout。

连接建立后立即断开时检查超时和上游日志

检查超时、反向代理缓冲、上游主动关闭和客户端关闭码，不要因为代理 IP 可连就推断 WebSocket 一定兼容。

返回 WebSocket 通用排障流程

如需先确认通用握手、长连接和代理链路，可返回 WebSocket 代理父页；Nginx 具体配置再按本文的 Upgrade、upstream 和超时顺序复核。

版本前提、最小配置与官方指令

适用前提：Nginx 1.24+。先运行 nginx -t，再执行 nginx -s reload，最后用 wscat 验证并保存 access/error log。官方依据：WebSocket、proxy_http_version、proxy_read_timeout。

FAQ

1. Nginx 普通请求成功，为什么 WebSocket 仍然失败？

普通请求不需要完整的连接升级流程，WebSocket 还依赖 HTTP/1.1、Upgrade 头和正确的 upstream。

2. Nginx 配置修改后需要重载服务吗？

需要按部署方式 reload 或重启配置，并确认新配置已经生效。

3. Nginx WebSocket 问题应该先看哪类日志？

握手和路由问题先看 access log；upstream、TLS 和超时问题重点看 error log。

4. Nginx 能自动解决上游 WebSocket 兼容问题吗？

不能。Nginx 只能转发和保持连接，上游服务仍需支持 WebSocket。