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 Gateway | Nginx 无法从上游获得有效响应:连接被拒、上游异常关闭、返回了非法响应 | 上游没起、端口写错、进程崩溃、keepalive 连接被对端关闭 |
| 504 Gateway Timeout | 上游在超时时间内没有返回 | 后端慢查询、上游依赖(DB/第三方)卡住、超时设得太短 |
| 500 | Nginx 内部/配置错误 | 配置写错、模块缺失 |
| 499 | 客户端在 Nginx 返回前主动断开(非标准码) | 用户取消、前端超时设置过短 |
先看 error_log:把级别开到 warn 或 error(生产别长期开 debug),502/504 的原因几乎都会写在里面。
1 | |
二、超时层级
Nginx 与上游之间有三个关键超时,默认都是 60s:
| 指令 | 默认 | 覆盖阶段 |
|---|---|---|
proxy_connect_timeout | 60s | 与上游建立 TCP 连接 |
proxy_send_timeout | 60s | 向上游发送请求(两次写操作之间) |
proxy_read_timeout | 60s | 读取上游响应(两次读操作之间) |
客户端侧还有 client_header_timeout、client_body_timeout、send_timeout,以及连接保活 keepalive_timeout(默认 75s)。排障时先确认"卡在哪一段":建连慢看 connect,发请求慢看 send,等响应慢看 read。
1 | |
注意:proxy_read_timeout 是两次读操作之间的超时,不是整个响应的总时长;只要后端在持续吐数据,长响应不会被它掐断。
三、502 的常见原因
- 上游服务没启动 / 端口写错:日志出现
connect() failed (111: Connection refused)。从 Nginx 所在机器curl -v http://127.0.0.1:3000/直接验证。 - 防火墙 / 安全组:本机端口被
iptables/ufw/云安全组拦掉,表现同样是 connection refused 或 timeout。 - 上游进程崩溃:看上游自己的日志与进程状态,
systemctl status/pm2 list。 - keepalive 连接被对端关闭:日志
upstream prematurely closed connection。后端keepalive_timeout比 Nginx 短时,Nginx 复用了一条已被后端关闭的连接。处理:调大后端 keepalive 超时,或调小 Nginx 的upstream keepalive数量,或接受偶发重试。 - DNS 解析失败:
proxy_pass写域名时,日志会有 resolver 相关错误;配resolver或改用固定 IP。 - 返回了非法响应头:
upstream sent too big header,见第五节缓冲。
四、504 的常见原因
- 后端真的慢:慢 SQL、同步调用第三方、大计算。先在上游侧确认耗时,再决定是优化还是调大超时。
- 上游依赖卡住:数据库连接池耗尽、Redis 超时、下游 API 无响应——这些会表现为 Nginx 等满
proxy_read_timeout。 - 超时设得太短:某些导出/生成类接口天然超过 60s,针对性调大该 location 的
proxy_read_timeout,而不是全局放大。 - 客户端已放弃:前端/浏览器超时短于 Nginx,客户端断开(499),但 Nginx 可能仍继续等待上游。
五、重试与上游健康
1 | |
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 | |
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 header | proxy_buffer_size 不够;调大或让上游精简响应头 |
SSL_do_handshake() failed | Nginx 与上游之间 TLS 握手失败(proxy_ssl_* 配置) |
recv() failed (104: Connection reset by peer) | 上游 reset 连接 |
open() "... failed (13: Permission denied) | 静态文件/证书权限问题 |
八、分层排查顺序
- 配置层:
nginx -t、nginx -T确认 upstream、listen、proxy_pass 正确; - 网络层:在 Nginx 机器上
curl -v http://<upstream>/、telnet <ip> <port>,确认可达; - 上游层:进程在不在、端口监听、上游日志有没有收到请求;
- 应用层:慢查询、依赖超时、GC/内存;
- 客户端层:是否 499(客户端先放弃)、前端超时设置。
先定位"哪一层",再决定调哪个参数;把 proxy_read_timeout 从 60s 调到 600s 往往只是掩盖后端的问题。
参考链接
- Nginx 官方文档:ngx_http_proxy_module ——
proxy_connect_timeout/proxy_read_timeout/proxy_next_upstream/ 缓冲指令; - Nginx 官方文档:ngx_http_upstream_module ——
max_fails/fail_timeout/backup/keepalive; - Nginx 官方文档:ngx_core_module(error_log) —— 日志级别;
- RFC 9110 §15.6.3:502 Bad Gateway、§15.6.5:504 Gateway Timeout —— 状态码语义;
- 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
