Nginx 反向代理 502/504 排查思路：从日志到超时参数

现象与区分

反向代理场景下，502 与 504 的含义不同，排查方向也不同：

• 502 Bad Gateway：Nginx 连不上上游，或上游返回了非法响应（进程挂掉、端口不对、连接被重置）。
• 504 Gateway Timeout：Nginx 连上了上游，但在超时时间内没等到响应（慢查询、上游线程耗尽、超时配置过小）。

先看错误日志，不要凭感觉改配置：

tail -n 200 /var/log/nginx/error.log
# 常见关键字
# connect() failed (111: Connection refused) while connecting to upstream
# upstream timed out (110: Connection timed out) while reading response header from upstream
# upstream prematurely closed connection while reading response header from upstream

日志路径以你的安装方式为准，可用 nginx -V 2>&1 | grep -o 'error-log-path=[^ ]*' 确认。

502 的排查步骤

1. 确认上游进程与端口

ss -lntp | grep 8080
curl -sv http://127.0.0.1:8080/health -o /dev/null

Connection refused 说明上游没监听或监听在其它地址（例如只监听了 127.0.0.1 而 Nginx 代理到了内网 IP）。

1. 检查 proxy_pass 写法：域名在 Nginx 启动时只解析一次，上游 IP 变更后需要 reload，或使用 resolver 配合变量。
2. 上游崩溃重启：prematurely closed connection 往往是上游进程异常退出，去查应用日志、dmesg | grep -i oom 判断是否被 OOM Killer 杀掉。
3. SELinux（CentOS/RHEL 系）：Nginx 无法连接网络端口时，检查 getsebool httpd_can_network_connect。

504 的排查步骤

1. 在日志里加入上游耗时字段，定位慢请求：

log_format timing '$remote_addr "$request" $status '
                  'rt=$request_time urt=$upstream_response_time uct=$upstream_connect_time';
access_log /var/log/nginx/access.log timing;

urt 接近 proxy_read_timeout（默认 60s）说明上游确实慢；uct 很大则是建连慢，多为网络或上游 backlog 满。

1. 按需调整超时，但只针对确有长耗时的接口：

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

1. 不要全局把超时调到很大：这会让上游线程被慢请求长期占住，故障被放大。真正的修复是优化慢接口、加缓存或改异步任务。

长连接与重试

上游启用 keepalive 可减少建连开销，也能避免高并发下端口耗尽：

upstream backend {
    server 10.0.0.11:8080;
    server 10.0.0.12:8080;
    keepalive 32;
}
location / {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
}

proxy_next_upstream 默认对 error 和 timeout 重试下一台。注意非幂等请求（如 POST 下单）重试有重复提交风险，需要时显式限制。

前面还有负载均衡或 CDN 时

如果 Nginx 前面还有云上负载均衡或 CDN，它们也有各自的空闲/回源超时。出现 504 时先确认是哪一层返回的：对比响应头和各层访问日志的时间点，具体超时上限以对应产品控制台和文档为准。

检查清单

• 先分清 502 与 504，再读 error.log。
• 502：查进程、端口、监听地址、OOM、SELinux。
• 504：查 upstream_response_time，定位慢接口，再针对性调超时。
• 修改后用 nginx -t 校验，再 nginx -s reload。
• 保留一份带耗时字段的 access_log，下次排查省一半时间。