在 linux 中 nginx 代理 websocket 出现 502 bad gateway，通常是因为 nginx 配置中缺少 websocket 协议升级所需的 http 头设置，导致连接被拒绝或无法建立。解决该问题的核心做法是在 nginx 的 `location` 块中正确配置 `proxy_set_header upgrade` 和 `proxy_set_header connection`，并将后端服务地址指向正确的 ip 和端口。
Nginx 配置中必须包含哪些 WebSocket 升级头
必须包含 Upgrade 和 Connection 两个头部字段。Nginx 默认不转发这些头部，如果不显式设置，后端服务器（如 Node.js、Go 或 Python 应用）将无法识别客户端发起的 WebSocket 握手请求，从而返回错误或直接关闭连接。
server {
listen 80;
server_name example.com;
location /ws/ {
proxy_pass http://127.0.0.1:3000;
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_http_version 1.1; 是必须的，因为 WebSocket 握手依赖于 HTTP/1.1 的持久连接特性。如果未设置此项，Nginx 可能使用 HTTP/1.0 进行通信，导致握手失败。$http_upgrade 变量会捕获客户端发送的 Upgrade: websocket 值，而 Connection "upgrade" 则强制建立升级通道。当客户端发起请求时，Nginx 会将这两个头部原样传递给后端 127.0.0.1:3000，后端据此完成握手并切换至 WebSocket 协议。
为什么后端服务正常但 Nginx 仍报 502
即使后端服务本身运行正常且能处理普通 HTTP 请求，若 Nginx 配置了错误的 proxy_pass 地址或防火墙阻断了本地回环接口，也会触发 502 错误。此外，超时设置不当也可能导致长连接被意外切断，表现为间歇性的 502 或连接重置。
# 检查后端服务是否监听在预期端口
ss -tlnp | grep :3000
# 测试从 Nginx 所在机器到后端的连通性
curl -i -N -H "Connection: Upgrade" \
-H "Upgrade: websocket" \
-H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
-H "Sec-WebSocket-Version: 13" \
http://127.0.0.1:3000/ws/
通过 ss -tlnp 命令可以确认后端进程是否正在监听 :3000 端口。如果输出为空，说明后端未启动或绑定到了其他地址。接着使用 curl 模拟 WebSocket 握手请求，直接访问后端地址。如果 curl 返回 101 Switching Protocols，说明后端配置无误，问题出在 Nginx 与客户端之间的链路；如果返回 400 或连接超时，则需检查后端日志或网络策略。确保 proxy_pass 中的 URL 不包含多余的路径前缀，例如 proxy_pass http://127.0.0.1:3000/ws/; 会将请求路径保留，而后端可能期望根路径 /，此时应改为 proxy_pass http://127.0.0.1:3000; 以去除前缀。
如何验证 WebSocket 连接是否真正建立成功
可以通过浏览器开发者工具的网络面板查看 WebSocket 连接的初始状态码是否为 101，并在 Nginx 错误日志中搜索是否有 upstream prematurely closed connection 或 no live upstreams 等报错信息。若日志中出现此类错误，通常意味着后端在握手完成后立即断开了连接，或者 Nginx 未能正确维持长连接。
在实际开发中，建议在后端应用中添加简单的日志打印，记录握手成功的时间点。同时，调整 Nginx 的 proxy_read_timeout 和 proxy_send_timeout 参数，避免在长时间无数据传输时被误判为空闲连接而断开。例如，设置为 proxy_read_timeout 3600s; 可确保连接在一天内保持活跃。结合 proxy_next_upstream 指令，可以配置在特定错误发生时重试其他后端节点，提高系统的容错能力。
