Nginx 反向代理 502/504 排查清单：从日志到配置一步步定位

线上服务突然返回 502 Bad Gateway 或 504 Gateway Timeout，是使用 Nginx 做反向代理时最常见的故障。两者含义不同：502 表示 Nginx 连上游失败或上游返回了无效响应，504 表示上游响应超时。下面按排查顺序整理一份清单。

1. 先看 Nginx 错误日志

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

几条典型报错对应的原因：

• connect() failed (111: Connection refused)：上游服务没启动或端口不对。
• upstream prematurely closed connection：上游进程崩溃或主动断开。
• upstream timed out (110: Connection timed out)：上游处理太慢，对应 504。
• no live upstreams：upstream 里所有节点都被标记为不可用。

2. 确认上游服务真的在监听

ss -lntp | grep 8080
curl -v http://127.0.0.1:8080/health

在 Nginx 所在机器上直接 curl 上游地址，能排除网络、防火墙和安全组问题。容器部署时注意 127.0.0.1 指的是容器自己，要用服务名或宿主机 IP。

3. 检查超时配置（504 的主要原因）

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

proxy_read_timeout 默认 60 秒，导出报表、大文件处理这类慢接口很容易超时。建议只对慢接口单独调大，不要全局放大，否则故障时连接会长时间堆积。

4. 检查缓冲区与响应头大小

上游返回的 Cookie 或响应头过大时会报 upstream sent too big header，返回 502：

proxy_buffer_size 16k;
proxy_buffers 4 32k;

5. 检查 PHP-FPM / 应用进程池是否耗尽

PHP-FPM 场景下，pm.max_children 太小会导致请求排队直到超时；Java、Node 等应用则要看线程池、连接池和 CPU/内存是否打满：

top -o %CPU
grep -i "max_children" /var/log/php*-fpm.log

6. 长连接与 keepalive

高并发下频繁新建上游连接会耗尽本地端口（大量 TIME_WAIT）。开启 upstream keepalive：

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

小结

排查顺序建议：错误日志 → 上游是否存活 → 超时配置 → 缓冲区 → 应用资源 → 连接复用。修改配置后先执行 nginx -t 校验，再 nginx -s reload 平滑生效。