侧边栏壁纸
  • 累计撰写 273 篇文章
  • 累计收到 2 条评论

线上接口偶发 504 Gateway Time-out?排查 Nginx 反代超时与 Upstream 调优我踩过的几个坑

2026-11-17 / 0 评论 / 8 阅读
AI 摘要由 AI 生成

文章介绍了如何排查和解决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。

实际发生的逻辑是:

  1. 某个边缘接口写了一条慢 SQL,把数据库行锁占住了十几秒;
  2. 高峰期并发进来的正常请求,全在排队等待获取 HikariCP 连接池里的空闲连接;
  3. 连接池获取超时设了 30s,重试或级联等待之后耗尽了 60 秒;
  4. 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 切换到下一个可用节点,能有效避免用户端感知到长达一分钟的卡顿。

评论一下?

OωO
取消