Nginx 报 502 / 504？先分清是“上游死了”还是“上游太慢”

502 和 504 看起来都是“网关出问题”，但指向的环节完全不同：502 是 Nginx 连上游时就失败了，或者上游返回了坏响应；504 是 Nginx 连上了上游、却在规定时间内没等到响应。一个是“连不上 / 响应坏了”，一个是“等太久”。先分清，再动手，少走一半弯路。

一、先看报错和日志，定方向

先确认两件事：浏览器看到的到底是 502 还是 504，以及 Nginx 错误日志里那一行写的是什么。

tail -n 100 /var/log/nginx/error.log

• 日志里是 connect() failed (111: Connection refused) while connecting to upstream：上游根本没在监听，502 的典型成因。
• 日志里是 upstream timed out (110: Connection timed out) while reading response header from upstream：上游接了请求但响应太慢，504 的典型成因。
• 日志里是 upstream sent invalid header 或 upstream prematurely closed connection：上游返回了 Nginx 无法理解的响应，也会报 502。

只看浏览器状态码不够，日志里那一行才是分流依据。

二、502：上游没起来，或者响应坏了

按从近到远的顺序查：

systemctl status php-fpm --no-pager   # 以实际后端为准：php-fpm、gunicorn、node、java 进程都一样
ss -tlnp | grep -E '9000|8000|8080'  # 上游到底在监听哪个端口 / 套接字
curl -v http://127.0.0.1:8080/        # 绕过 Nginx，直接问上游

• 进程没跑：先看它为什么挂掉，journalctl -u php-fpm --since "30 minutes ago" --no-pager，修好原因再启动，只重启不治本。
• 进程在跑但端口不对：核对 Nginx 里 proxy_pass / fastcgi_pass 指向的地址，和上游实际监听的地址是不是同一个。改过端口、换过套接字路径后最容易在这里错位。
• 直接 curl 上游也报错：问题在上游本身，不在 Nginx，先修上游。
• 直接 curl 上游正常、经 Nginx 就 502：再查 Nginx 这一侧——proxy_pass 有没有写错、SELinux / 防火墙有没有挡住 Nginx 到上游的本地连接、磁盘满了有没有导致套接字写不进去。

三、504：上游太慢，或者超时配得太短

504 不等于上游死了，很多时候是上游在干重活：慢查询、大文件处理、外部接口拖延。先确认慢在哪一层：

curl -o /dev/null -s -w '总耗时 %{time_total}s，首字节 %{time_starttransfer}s\n' http://127.0.0.1:8080/慢接口

• 直接问上游也慢：去上游侧定位——慢 SQL、缺索引、外部 API 超时、进程数被打满（php-fpm 的 pm.max_children 到顶后新请求只能排队）。
• 直接问上游很快、经 Nginx 就 504：看 Nginx 的超时是不是比上游实际耗时短：

proxy_connect_timeout 5s;
proxy_send_timeout    60s;
proxy_read_timeout    60s;

只把超时调大是掩盖问题，不是修问题：先确认这个接口本来就该这么慢（报表、大文件导出），再按实际耗时放宽；如果是不该慢的接口，先修慢查询和外部依赖。

四、几个容易误判的点

• 刚上线就 502：先查部署有没有真的完成——新进程没起来、旧进程占着端口、配置文件 reload 没生效（nginx -t && systemctl reload nginx），都比“代码 bug”常见。
• 间歇性 502/504：看是不是上游进程数到顶、连接池耗尽，或者后端在滚动重启。upstream 配了多个节点时，逐个直接 curl 每个节点，别只看负载均衡后的结果。
• 大响应 502：上游返回的响应头过大时，调大缓冲前先确认是不是上游在异常地吐超大 Cookie 或响应头：

proxy_buffer_size       16k;
proxy_buffers           4 32k;
proxy_busy_buffers_size 64k;

• 改完配置没生效：Nginx 改配置要 reload，php-fpm 改配置要重启对应服务，只保存文件是不生效的。

五、排查清单（收藏版）

1. 是 502 还是 504？错误日志那一行写的是什么？
2. 绕过 Nginx 直接 curl 上游：上游本身通吗、快吗？
3. 502：进程在跑吗？监听地址和 proxy_pass 对得上吗？响应头合法吗？
4. 504：慢在哪一层？上游慢就修慢查询和外部依赖，超时配得短再按实际耗时放宽。
5. 间歇性问题：逐个节点查，别只看负载均衡后的结果。
6. 改配置后 reload / 重启了吗？

502 查“连通和响应”，504 查“耗时和超时”，分清再动手，大多数 Nginx 网关报错都能在半小时内定位到具体一层。