线上出现 502 Bad Gateway 或 504 Gateway Timeout 时，很多团队第一反应是重启 Nginx，或者把所有 timeout 都调大。这个做法通常只能短暂缓解，不能定位真正故障点。
在云服务器环境里，请求链路往往不是"用户直连 Nginx"这么简单，而是：浏览器或 App → CDN/WAF → 云负载均衡 → Nginx 反向代理 → 应用进程 → 数据库/缓存/第三方接口。502 和 504 的根因可能出现在任何一层。
这篇文章给一套生产可执行的排障顺序：先判断错误由哪一层返回，再看连接、超时、应用日志和资源瓶颈，最后再决定是否调整 Nginx、负载均衡或应用配置。
一、先区分 502 和 504
502 更像"上游返回了坏响应"或"上游连接失败"。常见原因包括：应用进程没启动、端口不通、Unix Socket 权限错误、后端主动断开、Nginx 配置指向错误端口。
504 更像"网关等太久没等到上游响应"。常见原因包括：应用执行时间过长、数据库慢查询、第三方接口卡住、负载均衡 idle timeout 小于应用处理时间、Nginx proxy_read_timeout 过短。
先看状态码含义，可以避免把 504 当成 Nginx 本身故障，也避免把 502 当成单纯的超时问题。
二、第一步：确认错误是谁返回的
先用 curl 看响应头。不同层返回的 Server、Via、X-Cache、X-Amzn-Trace-Id、X-Request-Id 等头信息不同。
bash
curl -I https://example.com/api/health
curl -v https://example.com/api/slow 2>&1 | tee /tmp/curl-debug.log如果响应头显示来自 CDN 或 WAF，要去查 CDN/WAF 访问日志；如果来自负载均衡，要查负载均衡目标组健康状态和访问日志；如果来自 Nginx，要查 Nginx error.log 和 upstream 连接情况。
三、第二步：看 Nginx error.log
Nginx 的 error.log 往往直接给出方向。
bash
sudo tail -n 200 /var/log/nginx/error.log
sudo grep -E "upstream|timed out|connect\(\)|recv\(\)" /var/log/nginx/error.log | tail -n 50典型关键字可以这样判断：
- connect() failed：Nginx 连不上上游，优先查应用端口、监听地址、安全组、防火墙；
-
- upstream timed out：上游响应慢，优先查应用耗时、数据库、第三方接口；
-
- upstream prematurely closed connection：上游进程提前断开，优先查应用崩溃、超时退出或内存 OOM；
-
- no live upstreams：upstream 配置的后端都不可用，优先查健康检查和 upstream 配置。
四、第三步：确认上游应用是否真的可达
在 Nginx 所在机器上直接访问上游，比从外网访问更能定位问题。
bash
curl -I http://127.0.0.1:8080/health
curl -I http://10.0.1.23:8080/health
ss -lntp | grep 8080
systemctl status your-app
journalctl -u your-app -n 100 --no-pager如果本机访问上游都失败，就不要继续调 Nginx timeout，先修应用进程、端口监听或网络策略。
五、第四步：检查 timeout 链是否一致
很多 504 是 timeout 链配置不一致导致的。例如云负载均衡 idle timeout 是 60 秒，Nginx proxy_read_timeout 是 120 秒，应用接口实际要跑 90 秒。此时用户可能先被负载均衡断开，而 Nginx 和应用还在等待。
常见 Nginx 配置示例：
nginx
location /api/ {
proxy_pass http://backend;
proxy_connect_timeout 5s;
proxy_send_timeout 30s;
proxy_read_timeout 60s;
proxy_next_upstream error timeout http_502 http_503 http_504;
}
~~~
这里不是建议把所有 timeout 都调很大。更合理的做法是按业务接口分类：健康检查和普通 API 要短；导出、AI 推理、批处理等长任务要异步化，或单独走更长超时的路由。
## 六、第五步：排查资源瓶颈
如果 error.log 指向 upstream timed out，要继续看应用服务器资源。
~~~bash
top
free -h
df -h
iostat -xz 1
sar -n TCP,ETCP 1 5CPU 跑满、内存不足、磁盘 IO 高、连接数耗尽、数据库慢查询，都会表现为 Nginx 等不到上游响应。
七、生产排障顺序
- 看用户报错时间和范围：全站、单接口、单地区、单机房；
-
- 用 curl -I 判断返回层级；
-
- 查 Nginx access.log 和 error.log；
-
- 在 Nginx 机器上直连上游应用；
-
- 查应用日志、系统资源、数据库慢查询；
-
- 对齐 CDN、负载均衡、Nginx、应用的 timeout；
-
- 修复后补监控：5xx 比例、 upstream_response_time、request_time、目标组健康状态。
八、建议加上的日志格式
Nginx 默认日志不一定够用，建议加入 upstream 相关字段。
nginx
log_format main_ext "$remote_addr $request $status "
"rt=$request_time urt=$upstream_response_time "
"uct=$upstream_connect_time uht=$upstream_header_time "
"ua=$upstream_addr";
access_log /var/log/nginx/access.log main_ext;
~~~
有了 request_time 和 upstream_response_time，才能判断是客户端慢、Nginx 慢、上游慢，还是某个后端实例异常。
## 九、结论
502/504 不要先重启，也不要先盲目调大 timeout。正确顺序是：确认返回层级、读 error.log、直连上游、看应用和资源、对齐 timeout、补日志和监控。
如果你的线上服务经常出现 502/504，建议先把链路图、日志字段和超时矩阵补齐。排障不是靠经验猜，而是靠证据把故障层级逐步缩小。
参考资料：NGINX 官方文档、AWS Elastic Load Balancing 504 错误文档、Amazon CloudFront 504 文档、Linux man pages。
