Nginx 工程实践 -- 10. 502/504 与超时排障手册

502/504 是反向代理最常见的两类故障:一个是"连不上/被挂断",一个是"等不到"。它们几乎都不是 Nginx 本身的问题,而是 Nginx 与上游之间某个环节的缩影。排障的关键是先分清错误码语义,再按超时层级逐层定位,而不是上来就调大超时。

flowchart TD
    A["502 / 504"] --> B["配置层
nginx -t / -T"] B --> C["网络层
curl / telnet 上游"] C --> D["上游层
进程 / 端口 / 日志"] D --> E["应用层
慢查询 / 依赖"] E --> F["客户端层
499 / 超时"]

一、错误码到底在说什么

状态码含义典型场景
502 Bad GatewayNginx 无法从上游获得有效响应:连接被拒、上游异常关闭、返回了非法响应上游没起、端口写错、进程崩溃、keepalive 连接被对端关闭
504 Gateway Timeout上游在超时时间内没有返回后端慢查询、上游依赖(DB/第三方)卡住、超时设得太短
500Nginx 内部/配置错误配置写错、模块缺失
499客户端在 Nginx 返回前主动断开(非标准码)用户取消、前端超时设置过短

先看 error_log:把级别开到 warn 或 error(生产别长期开 debug),502/504 的原因几乎都会写在里面。

1
error_log /var/log/nginx/error.log warn;

二、超时层级

Nginx 与上游之间有三个关键超时,默认都是 60s:

指令默认覆盖阶段
proxy_connect_timeout60s与上游建立 TCP 连接
proxy_send_timeout60s向上游发送请求(两次写操作之间)
proxy_read_timeout60s读取上游响应(两次读操作之间)

客户端侧还有 client_header_timeout、client_body_timeout、send_timeout,以及连接保活 keepalive_timeout(默认 75s)。排障时先确认"卡在哪一段":建连慢看 connect,发请求慢看 send,等响应慢看 read。

1
2
3
4
5
6
location /api/ {
proxy_pass http://backend;
proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
}

注意:proxy_read_timeout 是两次读操作之间的超时,不是整个响应的总时长;只要后端在持续吐数据,长响应不会被它掐断。

三、502 的常见原因

  1. 上游服务没启动 / 端口写错:日志出现 connect() failed (111: Connection refused)。从 Nginx 所在机器 curl -v http://127.0.0.1:3000/ 直接验证。
  2. 防火墙 / 安全组:本机端口被 iptables/ufw/云安全组拦掉,表现同样是 connection refused 或 timeout。
  3. 上游进程崩溃:看上游自己的日志与进程状态,systemctl status / pm2 list。
  4. keepalive 连接被对端关闭:日志 upstream prematurely closed connection。后端 keepalive_timeout 比 Nginx 短时,Nginx 复用了一条已被后端关闭的连接。处理:调大后端 keepalive 超时,或调小 Nginx 的 upstream keepalive 数量,或接受偶发重试。
  5. DNS 解析失败:proxy_pass 写域名时,日志会有 resolver 相关错误;配 resolver 或改用固定 IP。
  6. 返回了非法响应头:upstream sent too big header,见第五节缓冲。

四、504 的常见原因

  1. 后端真的慢:慢 SQL、同步调用第三方、大计算。先在上游侧确认耗时,再决定是优化还是调大超时。
  2. 上游依赖卡住:数据库连接池耗尽、Redis 超时、下游 API 无响应——这些会表现为 Nginx 等满 proxy_read_timeout。
  3. 超时设得太短:某些导出/生成类接口天然超过 60s,针对性调大该 location 的 proxy_read_timeout,而不是全局放大。
  4. 客户端已放弃:前端/浏览器超时短于 Nginx,客户端断开(499),但 Nginx 可能仍继续等待上游。

五、重试与上游健康

1
2
3
4
5
6
7
8
9
10
11
12
upstream backend {
server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;
server 127.0.0.1:3001 backup;
}

location /api/ {
proxy_pass http://backend;

proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 3;
proxy_next_upstream_timeout 60s;
}
  • max_fails(默认 1)+ fail_timeout(默认 10s):在 fail_timeout 内失败达到 max_fails 次,该 server 在这段时间内不再分配请求;
  • 单 server 的 upstream 组永远不会被标记为不可用(max_fails/fail_timeout 被忽略),所以单点故障只能靠监控发现;
  • proxy_next_upstream 默认是 error timeout,显式加上 http_502/503/504 才有重试机会;
  • 幂等性:默认情况下,请求体一旦开始发送给上游,nginx 不会重试非幂等方法(POST/PUT/DELETE 等);需要时可加 non_idempotent 参数,但必须先确认重试不会造成重复副作用;
  • proxy_next_upstream_tries / _timeout 限制重试次数与总耗时,避免把一个坏请求放大成多倍上游压力。

六、缓冲相关

1
2
3
4
5
proxy_buffering        on;
proxy_buffer_size 4k; # 读上游响应第一段(含响应头)的缓冲
proxy_buffers 8 4k; # 读响应的缓冲数量与大小
proxy_busy_buffers_size 8k;
proxy_max_temp_file_size 1024m;
  • proxy_buffer_size 太小而上游响应头很大时,报 upstream sent too big header while reading response header from upstream;
  • 响应体超过内存缓冲会落临时文件,proxy_max_temp_file_size 限制落盘量;
  • 实时性要求高(SSE、流式)的场景,按需 proxy_buffering off,并理解它对背压的影响。

七、常见错误日志速查

日志关键字含义 / 处理
connect() failed (111: Connection refused)上游没监听该端口;查进程与监听
upstream timed out (110: Connection timed out)connect 或 read 超时;查上游负载与网络
no live upstreams while connecting to upstream组内所有 server 都不可用;查 max_fails 与上游状态
upstream prematurely closed connection while reading response header上游提前关连接;多为 keepalive 复用或上游崩溃
upstream sent too big headerproxy_buffer_size 不够;调大或让上游精简响应头
SSL_do_handshake() failedNginx 与上游之间 TLS 握手失败(proxy_ssl_* 配置)
recv() failed (104: Connection reset by peer)上游 reset 连接
open() "... failed (13: Permission denied)静态文件/证书权限问题

八、分层排查顺序

  1. 配置层:nginx -t、nginx -T 确认 upstream、listen、proxy_pass 正确;
  2. 网络层:在 Nginx 机器上 curl -v http://<upstream>/、telnet <ip> <port>,确认可达;
  3. 上游层:进程在不在、端口监听、上游日志有没有收到请求;
  4. 应用层:慢查询、依赖超时、GC/内存;
  5. 客户端层:是否 499(客户端先放弃)、前端超时设置。

先定位"哪一层",再决定调哪个参数;把 proxy_read_timeout 从 60s 调到 600s 往往只是掩盖后端的问题。

参考链接

  1. Nginx 官方文档:ngx_http_proxy_module —— proxy_connect_timeout / proxy_read_timeout / proxy_next_upstream / 缓冲指令;
  2. Nginx 官方文档:ngx_http_upstream_module —— max_fails / fail_timeout / backup / keepalive;
  3. Nginx 官方文档:ngx_core_module(error_log) —— 日志级别;
  4. RFC 9110 §15.6.3:502 Bad Gateway、§15.6.5:504 Gateway Timeout —— 状态码语义;
  5. Nginx 官方文档:ngx_http_proxy_module(proxy_next_upstream 的 non_idempotent)。

小结

  • 502 偏"连接/响应无效",504 偏"等不到";先看 error_log 再动手;
  • 三个代理超时(connect/send/read)默认 60s,含义是"两次操作之间",不是总时长;
  • 502 优先查:上游进程、端口、防火墙、keepalive 复用;504 优先查:后端耗时、依赖、超时设置;
  • 重试要显式配 proxy_next_upstream,并认真对待非幂等请求;
  • 单 server 的 upstream 不会自动摘除,单点可靠性靠冗余与监控;
  • 按"配置→网络→上游→应用→客户端"分层定位,别用调大超时掩盖问题。

系列导航


Nginx 工程实践 -- 10. 502/504 与超时排障手册
https://bubao.github.io/posts/a9b7c8d0.html
作者
一念
发布于
2026年11月21日
许可协议