文章介绍了如何排查和解决Nginx反向代理504超时问题。分析了错误日志,区分了502和504错误的本质,指出修改proxy_read_timeout可能导致问题升级,并强调了全面审查整个请求链路的重要性。
线上监控报警群里突然跳出几条 504 Gateway Time-out,刷新一下页面又恢复正常;或者某个带复杂查询的报表导出接口,转圈转满整整一分钟后直接弹一个白屏 504。
这种偶发性报错排查起来很磨人。业务研发跑过来说代码本地跑只要两三秒,运维看 Nginx 发现 CPU 和内存都在 20% 以下。504 本质是网关层面的超时:Nginx 作为反向代理在规定的时间内,没有等到上游服务(Upstream)返回响应数据。
但很多时候大家顺手去改 proxy_read_timeout,改完上线发现超时依然在报,甚至带崩了上游的数据库连接池。这里把排查 Nginx 反代超时和 Upstream 调优过程中,踩过的几个典型场景和对应的解决办法理一遍。
502 与 504:先看 error.log 第一行分清责任链
排查网关问题,第一步永远是翻 Nginx 的 error.log,不要只盯 access.log 里的状态码。很多人容易把 502 和 504 混在一起:
- 502 Bad Gateway:Nginx 向上游发起连接时被拒绝(Connection refused),或者上游服务进程挂了直接断开连接(Connection reset by peer)。上游压根没正常接客。
- 504 Gateway Time-out:TCP 连接顺利建上了,但上游处理太慢,或者网络中间断流,Nginx 等得不耐烦主动掐断了请求。
在 Nginx 错误日志里,504 通常会对应两种截然不同的记录:
# 典型场景 A:连接上游超时(握手超时)
2026/05/10 14:20:01 [error] 14521#0: *84510 upstream timed out (110: Connection timed out) while connecting to upstream, client: 192.168.1.10, server: api.example.com, request: "GET /api/v1/orders HTTP/1.1", upstream: "http://10.0.0.12:8080/api/v1/orders"
# 典型场景 B:读取上游响应超时(后端算得太慢)
2026/05/10 14:22:01 [error] 14521#0: *84512 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 192.168.1.10, server: api.example.com, request: "POST /api/v1/export HTTP/1.1", upstream: "http://10.0.0.12:8080/api/v1/export"
看到 while connecting to upstream,说明网络链路不通、上游主机防火墙丢包、或者上游服务的 TCP 全连接队列(backlog)被打爆导致 SYN 丢包;看到 while reading response header from upstream,才说明上游服务已经拿到了请求,只是在业务逻辑或数据库查询里卡住了。把这个关键分界线看清楚,后面定位问题就少走大半弯路。
坑一:只给长耗时接口改了 proxy_read_timeout,整条链路其实还在掐表
项目里有个导出几十万行流水数据的接口,平时跑十几秒,月底账期数据量翻倍,耗时冲到 70 秒,前端准时报 504。
当时第一反应很简单:Nginx 默认的 proxy_read_timeout 是 60s,改成 300s 不就行了?
location /api/v1/export {
proxy_pass http://backend_servers;
proxy_read_timeout 300s;
proxy_connect_timeout 60s;
proxy_send_timeout 300s;
}
改完 nginx -s reload,重新点导出,结果等了 60 秒还是 504。
排查链路才发现,我们生产环境并不是客户端直连单层 Nginx,而是:
客户端 -> SLB 负载均衡 -> 边界 Nginx -> 微服务网关 (Spring Cloud Gateway) -> 业务微服务 (Tomcat / Netty)。
Nginx 的超时确实放宽到了 300 秒,但云负载均衡器默认配了 60 秒空闲超时;微服务网关里同样配了严格的超时限制:
spring:
cloud:
gateway:
httpclient:
response-timeout: 60s
connect-timeout: 5000
甚至 Tomcat 内部配置的 connectionTimeout 也是 60 秒。
遇到链条很长的反向代理架构,超时时间完全由整条链路上最小的那个节点决定。只改边缘 Nginx 相当于只开了外门,内门依然按时反锁。
针对批量导出这种异步长任务,改大 HTTP 超时其实治标不治本。一个 HTTP 请求挂在连接池里占 5 分钟,并发一来整机连接池全被拖死。更稳妥的做法是把导出接口改造成异步轮询:前端请求立即返回任务 ID,后端丢进队列异步生成,完成后写对象存储,前端凭 ID 轮询进度再下载。
坑二:Upstream 缺少 keepalive,高并发瞬间压爆上游 TIME_WAIT
很多朋友的 Nginx 配置里,upstream 都是这么写的:
upstream backend_cluster {
server 10.0.0.11:8080 weight=5;
server 10.0.0.12:8080 weight=5;
}
在中小流量下,这套配置没有任何异常。但到了压测或者流量高峰期,Nginx 就会偶发出现一小批 504 超时,报错显示 while connecting to upstream。
去后端服务机器上一查:
ss -s
# 或者
netstat -n | awk '/^tcp/ {++S[$NF]} END {for(a in S) print a, S[a]}'
后端机器上堆了几万个 TIME_WAIT 连接,临时端口几乎耗尽。
Nginx 的 upstream 默认使用的是短连接。每次转发客户端请求,Nginx 都会向上游后端新建一个 TCP 连接,请求拿到响应后立即断开。在高并发场景下,每秒几千次频繁握手和挥手,无论是 Nginx 机器还是后端机器,TCP 端口资源和 socket 缓存都会被迅速吃光。遇到端口分配不出来或者 SYN 队列拥堵,新的连接握手直接超时,前端自然就收到了 504。
解决办法是在 upstream 块里加上 keepalive 连接池配置:
upstream backend_cluster {
server 10.0.0.11:8080 weight=5 max_fails=3 fail_timeout=10s;
server 10.0.0.12:8080 weight=5 max_fails=3 fail_timeout=10s;
# 为每个 worker 进程保留最多 64 个空闲长连接
keepalive 64;
}
这里的 keepalive 64 针对的是空闲连接,指的是每个 worker 进程保留最多 64 个存活的长连接,而不是把总连接上限卡死在 64。有了长连接池,后续请求复用已有链路,省掉了高频的三次握手开销。
坑三:加了 keepalive 却漏掉 Connection 标头,长连接根本没生效
改完上面的 keepalive,满心以为高枕无忧了。结果再跑一轮压测,后端 TIME_WAIT 一点都没减少,连接超时报警依然断断续续。
抓包分析才发现:Nginx 发往后端服务的 HTTP 请求头里,赫然带着 Connection: close。
这是 Nginx 一个很容易被忽略的静默规则:
Nginx 转发 upstream 请求时,默认采用 HTTP/1.0 协议;而 HTTP/1.0 默认不开启持久连接。即使你显式指定了 proxy_http_version 1.1;,客户端如果传了 Connection: close,Nginx 也会直接透传给上游。
要想让 upstream 的 keepalive 真正生效,必须在 location 块里配齐两行核心指令:
location /api/ {
proxy_pass http://backend_cluster;
# 1. 强制使用 HTTP/1.1 协议
proxy_http_version 1.1;
# 2. 清除 Connection 头部信息,防止传递 close
proxy_set_header Connection "";
# 基础传递标头
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
把 Connection "" 清空后,Nginx 才能向上游发送合规的 HTTP/1.1 Keep-Alive 握手。
配置上线后验证长连接是否生效,可以在后端应用机器上执行:
watch -n 1 "ss -ant | grep :8080 | grep ESTAB | wc -l"
如果长连接生效,ESTABLISHED 连接数会在稳定水位维持波动,而不再是随着每次请求产生剧烈的建连与断连抖动。
坑四:Upstream 域名解析缓存死锁,动态 IP 漂移后狂报 504
现在很多服务部署在私有云或容器平台(如 K8s Headless Service 或云 RDS / 容器微服务),upstream 填写的往往是内网域名而不是死 IP:
upstream internal_service {
server service-user.internal.net:8080;
}
微服务有次滚动发布,Pod 销毁后重新在另外两台宿主机拉起,IP 从 10.0.2.15 漂移到了 10.0.4.88。
几秒钟后,全站关于该模块的接口全部报 504。
登上 Nginx 一看日志,全是 upstream timed out while connecting to upstream,而连接的目标 IP 依然是旧的 10.0.2.15。
原因在于:Nginx 只在启动(或 reload)加载配置文件时做一次 DNS 解析。解析出的 IP 会被缓存在内存数据结构中,只要进程不 reload,即使内网 DNS 已经更新了数条 A 记录,Nginx 也绝不会主动去重新解析。旧 IP 对应的容器或虚拟机一旦下线,Nginx 发送 SYN 包自然只能在黑洞里超时。
解决这个问题,可以将域名赋值给变量,再通过 proxy_pass 引用,强制触发 resolver 的动态解析机制:
server {
listen 80;
server_name api.example.com;
# 指定内网 DNS 服务器地址,valid 设置缓存时间,ipv6=off 避免无谓查询
resolver 10.96.0.10 valid=10s ipv6=off;
resolver_timeout 3s;
location /user/ {
# 用变量接收域名,绕过启动时单次解析锁定
set $upstream_user "service-user.internal.net:8080";
proxy_pass http://$upstream_user;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
设置了 valid=10s 之后,Nginx 每 10 秒就会主动找内网 DNS 刷新一次域名对应的实际 IP,节点发生漂移时最多在窗口期内快速收敛,不会一直卡死在失效节点上。
坑五:后端连接池耗尽导致排队假死,超时不能盲目调大
排查 504 时最忌讳的盲区是把问题全推给网关配置。很多次排障到最后,发现 Nginx 完全是替罪羊。
典型现象是:白天流量平稳时接口秒开,傍晚高峰期偶发十几条 504。Nginx 日志记录显示 while reading response header from upstream,耗时刚好卡在 60 秒。
这时候去看后端微服务监控,CPU 使用率可能只有 15%,内存也很正常。但如果你通过命令看一眼应用层连接池指标(以 Java HikariCP 或 Go sql.DB 为例):
# 查看后端应用线程状态
jstack <pid> | grep -A 10 "HikariPool"
经常会抓到大面积类似堆栈:
java.sql.SQLTransientConnectionException: HikariPool-1 - Connection is not available, request timed out after 30000ms。
实际发生的逻辑是:
- 某个边缘接口写了一条慢 SQL,把数据库行锁占住了十几秒;
- 高峰期并发进来的正常请求,全在排队等待获取 HikariCP 连接池里的空闲连接;
- 连接池获取超时设了 30s,重试或级联等待之后耗尽了 60 秒;
- Nginx 的
proxy_read_timeout到了,主动向前端返回 504。
如果这时候为了“解决 504”,盲目把 Nginx 的 proxy_read_timeout 从 60s 改成 120s,结果就是排队积压的请求在连接池里憋得更久,拖垮整机可用线程,引发灾难性的雪崩。
遇到这类读取超时,必须配合 APM 工具(如 SkyWalking 或 Arthas)抓链路耗时,把数据库慢查询、未命中的 Redis 缓存、外部三方依赖卡顿这几个真正堵塞源头拔除,而不是在代理层做无脑延时。
常用超时与连接池参数速查
在生产环境的 nginx.conf 中,一套兼顾性能与安全性的反向代理通用配置参考如下:
http {
# 客户端连接相关
client_header_timeout 15s;
client_body_timeout 15s;
send_timeout 20s;
keepalive_timeout 65s;
upstream backend_api {
server 10.0.0.21:8080 max_fails=3 fail_timeout=15s;
server 10.0.0.22:8080 max_fails=3 fail_timeout=15s;
# 保持连接池
keepalive 64;
}
server {
listen 80;
server_name api.example.com;
location / {
proxy_pass http://backend_api;
# 启用 HTTP/1.1 长连接并清除 close 标头
proxy_http_version 1.1;
proxy_set_header Connection "";
# 标头透传
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# 超时阈值精准控制
proxy_connect_timeout 5s; # 建连超时设短一点,快速转移
proxy_send_timeout 30s; # 发送请求体超时
proxy_read_timeout 60s; # 读取上游响应超时
# 缓冲与重试
proxy_next_upstream error timeout http_502 http_503;
proxy_next_upstream_tries 2;
proxy_next_upstream_timeout 10s;
}
}
}
其中 proxy_connect_timeout 建议设得相对激进(例如 3s 到 5s)。在局域网内,正常建连一般在几个毫秒内就能搞定;如果 5 秒都握不上手,上游大概率已经宕机或网络分区,尽早触发 proxy_next_upstream 切换到下一个可用节点,能有效避免用户端感知到长达一分钟的卡顿。
文章标题:线上接口偶发 504 Gateway Time-out?排查 Nginx 反代超时与 Upstream 调优我踩过的几个坑
文章链接:https://www.llbbs.cn/jishujaocheng/333.html
本站文章均为原创,未经授权请勿用于任何商业用途
评论一下?