Nginx 反向代理常见故障排查：从 502 到 WebSocket 断开

用 Nginx 做反向代理几乎每个项目都会遇到，但出问题时的表现往往很模糊：502、504、连接直接断掉。这篇按实际排障顺序整理三类最常见故障的定位方法。

一、502 Bad Gateway：上游没接住

502 的本质是 Nginx 连上了上游，但上游返回了非法响应或直接关闭连接。排查顺序：

# 1. 上游进程是否存活
curl -v http://127.0.0.1:8080/health
# 2. Nginx 错误日志的真实原因
tail -50 /var/log/nginx/error.log

日志里出现 connect() failed (111: Connection refused) 就是上游没起；出现 upstream prematurely closed connection 则是上游进程自己崩了或主动断连。

二、504 Gateway Timeout：等太久

默认 proxy_read_timeout 是 60 秒。长任务接口必须先改这个值，但更常见的问题是：上游其实很快，慢在 DNS 解析或连接建立。

location /api/ {
    proxy_pass http://backend;
    proxy_connect_timeout 5s;
    proxy_send_timeout 30s;
    proxy_read_timeout 120s;
}

注意 proxy_pass 后面带变量时 Nginx 会每请求重新解析 DNS，不带变量则只在启动时解析一次。容器环境里后端 IP 会变，这点很关键。

三、WebSocket 一连接就断

这是最容易被忽略的一类。WebSocket 需要协议升级，Nginx 默认不做升级转发，表现是握手返回 200 而不是 101，前端报连接失败。

location /ws/ {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}

三个关键点：http_version 1.1 必须有（1.0 不支持升级）；Upgrade 和 Connection 两个头都要传；proxy_read_timeout 要放大，否则空闲 60 秒后连接被断开，看起来像「随机掉线」。

四、几个排查习惯

• 永远先看 error.log，不要靠猜。Nginx 的错误日志已足够定位 90% 的问题
• 用 curl -v 直连上游端口，区分是上游问题还是 Nginx 配置问题
• 改完配置先 nginx -t 再 reload，语法错误会导致 reload 失败而旧配置继续跑
• 排查完顺手确认 proxy_set_header Host $host，缺这行时上游拿到的 Host 是上游地址，很多框架会因此生成错误的重定向 URL

反向代理的问题几乎都能归结为「上游没起来」「等太久」「协议没升级」三类，按这个顺序查比乱试快得多。