凌晨两点四十监控群里弹出一条告警核心下单接口 504 GATEWAY_TIMEOUT 占比冲到 12%错误正文里统一跟着一句Response took longer than timeout: PT30000。当时的第一个念头很朴素——把 timeout 调大不就完了。但我在这上面栽过跟头数字调大通常只是把问题往后推两个小时真正要弄明白的是三件事这条 504 是谁发出来的、报错里的 PTxxx 对应哪一层的哪条配置、请求究竟卡在哪一跳。这篇就把我自己处理这类超时问题的完整思路写下来从读报错、切链路、算超时预算到六类最常见的真实根因最后是验证和防复发。如果你手上正好有一堆 504、gateway timeout、timeout 参数怎么调都别扭的问题这篇可以当成一份排查手册直接用。1. 那条 504 到底是谁发的PTxxx 又代表什么1.1 一次请求要经过的完整链路很多人拿到 504 的第一反应是去翻业务服务的日志翻了半天发现业务日志里什么错都没有请求甚至跑完了只是结果没人接。原因在于 504 的产生位置和你想象的相反。一条典型请求的链路是这样的客户端App、浏览器、脚本→ DNS 解析 → 负载均衡层 → 接入层网关 → 业务服务 → 依赖服务RPC 服务、数据库、缓存、第三方接口。504 GATEWAY_TIMEOUT 的定义是某一跳在等待它的上游返回响应时超过了它自己配置的等待上限于是它主动生成一个 504 返回给下游。注意这个动作的方向——发出 504 的那一层是等待方被等待的那一层是超时方。所以 504 不代表最里面的业务服务挂了恰恰相反业务服务很可能还活着、还在跑、最后也跑完了只是它的结果已经没有人接收了。这就解释了一个很常见的困惑为什么业务日志里查询执行成功、耗时 8 秒的记录赫然在目而网关那边返回的是 504——因为网关在 3 秒的时候就已经放弃等待并切断了连接。把这个因果关系立住排查方向就对了顺着链路从外往内数找到第一个报超时的等待方然后再去看它的上游为什么慢。1.2 报错里的 PTxxx先把它当成一把钥匙Response took longer than timeout: PT30000这种文案不同框架、不同网关的措辞会略有差异但它传递的信息结构是一致的一个超时判定被触发了触发阈值的配置项缩写是 PT值是 30000单位通常是毫秒也就是 30 秒。PT 在不同系统里的展开不太一样常见的有 Per-request Timeout、Path Timeout、Policy Timeout、Proxy Timeout 这几类含义具体是哪一个要看你的网关/框架文档。我一般不去纠结缩写的字面含义而是把它当作检索用的钥匙按下面的顺序找直接在配置仓库里全局搜索PT加上那个数值比如搜PT30000或30000或者搜timeout相关的配置键往往能定位到具体的配置文件行。如果搜到的是一份路由/策略配置就顺着这份配置找到它作用在哪个路由、哪个服务名、哪个接口上。用这个路由信息去反查立刻就能知道谁在等谁。提示报错里带上配置项名和阈值是网关做得很贴心的一种设计很多自研网关会把这段上下文丢掉只剩一句干巴巴的 504那时候排查难度会高一个量级。如果你在维护网关强烈建议把超时参数名和值写进错误响应体。还有一个容易被忽略的点30000 这个数字经常是默认值而不是有心设置的值。30 秒、60 秒、15 秒、5 秒这几个数字在各类网关和服务框架里出现频率极高。看到一个整整齐齐的 30 秒八成意味着这一层从来没被人认真配置过用的是出厂默认。这类默认值超时往往是最坑的因为它既不符合业务的真实耗时分布又在出问题时最先发作。1.3 504 与 502、499、408、524 的边界划分这几个状态码经常被混着报理清边界能省掉大量误判时间。状态码产生方本质含义典型诱因504等待方网关/中间层等到了上限还没拿到上游响应上游慢、连接池排队、下游挂起502等待方网关/中间层上游连接失败或返回了非法响应上游进程挂了、端口不通、协议不匹配499网关自身记录客户端在网关回包前主动断开用户关页面、客户端超时更短、手机切网408服务端等请求头没等到客户端网络差、上传慢524平台侧封装平台层等待超时的自定义码平台自身有固定的等待上限这里最值得说一句的是 499。我见过不少团队对着 504 大刀阔斧地优化最后发现真正的用户投诉来自 499——因为客户端比如 App 的 axios 或者 SDK自己设了 2 秒超时网关还在等上游的 8 秒用户在 2 秒时已经看到失败弹窗并且断了连接。这种情况下网关侧的超时其实永远不会触发504 只是顺带出现主角是客户端超时太短。所以看到 504 堆叠的时候务必顺手统计一下同时间段的 499 数量两者的比例往往能直接告诉你问题在客户端还是在服务端。2. 定位超时发生在哪一跳2.1 用 trace id 把网关日志与上游日志焊在一起排查超时的第一原则不要靠时间戳去对日志。同一秒可能有几千条请求靠时间对日志就是碰运气。要有一个贯穿全链路的请求标识。如果你们已经有链路追踪系统OpenTelemetry、SkyWalking、Jaeger 之类直接拿 trace id 查这一步可以跳过。如果没有最经济的替代方案是在网关生成 X-Request-Id 并透传下去业务服务在日志里原样打印。nginx 侧可以这样配置日志格式把关键的耗时字段一次性带上log_format upstream_time $remote_addr - $request_id $request status$status upstream$upstream_addr urt$upstream_response_time urct$upstream_connect_time urht$upstream_header_time rt$request_time; access_log /var/log/nginx/access.log upstream_time;这几个字段的语义要分清它们的组合能直接告诉你超时卡在哪一段urctupstream_connect_time与上游建连耗时。这个值大说明是网络层或上游 accept 队列的问题跟业务逻辑无关。urhtupstream_header_time从建连完成到收到上游响应头的耗时。这个值等于你应用真正的处理时间是排查超时最核心的指标。urtupstream_response_time从建连到上游响应体接收完毕的耗时。它和 urht 的差值就是传输响应体的时间差值很大说明响应体特别大。rtrequest_time网关看到的整条请求总耗时包含与客户端交互的时间。我的经验是只看 rt 会误判只看 urt 会漏判。真正的诊断价值在 urht 和 urt 的差值上。有一次线上 504urt 显示 3.2 秒看起来是上游慢但 urht 只有 0.05 秒——也就是说上游 50 毫秒就把响应头吐出来了剩下 3 秒多全花在传响应体上。最后查出来是一个接口在报错时把整张表的错误明细塞进了响应体光序列化加传输就三秒。如果当时只盯着上游慢去优化业务逻辑永远找不到答案。2.2 分段计时把一次请求切片成可度量的几段在没有链路追踪的情况下用 curl 手工切一次链路仍然是最快的手段。把请求分成 DNS、建连、TLS、首字节、总耗时五段curl -o /dev/null -s -w \ dns%{time_namelookup} conn%{time_connect} tls%{time_appconnect} \ ttfb%{time_starttransfer} total%{time_total}\n \ -H X-Request-Id: manual-check-001 \ https://api.example.com/api/order/detail?id123跑两次很关键一次经过网关一次直连上游。直连上游耗时 8 秒、经网关耗时 8 秒多 → 问题在上游本身。直连上游 200 毫秒、经网关 3 秒 504 → 问题在网关到上游之间重点查连接池、DNS、路由策略。两次都很快但线上还是 504 → 说明是并发条件下的问题单次复现没意义要去查负载和排队。这里有个实操细节手工验证一定要带上真实的请求头和请求体大小。我踩过一次坑用 curl 发了个几十字节的 GET 去验证一个实际上传 2MB JSON 的接口当然是秒回最后发现超时原因是包体太大导致上游解析慢。验证的参数要贴近真实流量否则测了个寂寞。2.3 从路由与端口反查配置项确定是网关侧超时之后接下来就是找到到底哪条配置在起作用。这一步经常出岔子原因是配置有覆盖关系全局有一份默认值某个 server 块有一份某个 location 又覆盖了一份实际生效的是最内层那份。反查的方法是用报错里带的路径和上游地址做主键grep -rn location /api/order /etc/nginx/conf.d/ grep -rn 30000\|30s /etc/nginx/conf.d/如果用的是 Kubernetes Ingress 或者服务网格配置被转译过一层就要去看注解annotation和对应的 Ingress Controller 文档别直接去改 nginx 的配置文件改了也会被覆盖回去。我见过有人手动改了容器里的 nginx.conf重启之后一切都恢复原样排查了半天的配置不生效其实是这个原因。注意排查时把当前生效的配置完整导出一份存档。超时类问题经常在改完配置之后看起来好了过几天又冒出来那时候如果没有旧配置做对比很难判断到底是哪次改动起了作用。3. 超时预算为什么单改网关的数字没用3.1 一条请求上同时跑着好几个计时器这是超时问题里最反直觉的一件事一条请求上并不是只有一个超时而是有一串超时它们同时在倒计时谁先到点谁说了算。按从外到内排一下客户端超时App 的 axios、SDK 的 read timeout、浏览器的等待上限负载均衡层空闲超时idle timeout接入层网关的连接超时与读取超时业务服务里 HTTP 客户端的连接超时与读取超时RPC 框架的调用超时数据库连接的获取超时等连接池数据库语句执行超时缓存、消息队列客户端各自的超时一份完整的排查里这七八个数字都要看一遍。而绝大多数改了没用的情况原因就是改了其中一层但更外层或者更内层的那个先到点了。比如你把网关从 3 秒调到 10 秒结果客户端 5 秒就断了用户看到的还是失败或者你把业务层的 RPC 超时调到 5 秒网关还是 3 秒那 3 秒到了照样 504。3.2 各层超时参数对照与取值计算先把常用参数列出来不同技术栈的名字不一样但角色是一一对应的。位置典型参数名作用常见坑客户端readTimeout / timeout等响应的上限按默认值设得特别短接入层keepalive_timeout空闲连接保持时间与长连接接口冲突接入层proxy_connect_timeout与上游建连上限设得过大掩盖网络问题接入层proxy_read_timeout等上游响应上限只改这个忘了外层应用侧调用connectTimeout / readTimeout调下游的上限用单值超时糊过去数据源connectionTimeout借连接排队上限设得比 SQL 超时还大数据库statement_timeout / socketTimeout单条语句上限长期未设任其跑取值不是拍脑袋有个简单可算的公式用你的真实耗时分布去推不要用感觉去推。假设某个下游接口在正常压力下的 P99 是 800 毫秒应用侧允许重试 1 次希望给足冗余应用侧读取超时 P99 × 1.2 的安全系数 ≈ 1 秒考虑重试 1 次设 2 秒比较合理。接入层网关超时 应用侧超时 × (1 重试次数) 序列化与网络余量 ≈ 2 秒 0.5 秒 2.5 秒向上取 3 秒。客户端超时要比网关再大一点比如 5 秒确保客户端能看到网关返回的干净错误而不是自己先断连。这个链条上的每个数字都必须比它内层的数字大越小越内、越大越外方向不能错。3.3 内层超时必须小于外层的三层理由有人会问为什么不干脆所有层都设 60 秒反正谁先到点都是失败这个想法我试过结果是灾难性的。第一外层先超时内层的补救逻辑永远执行不到。你精心写的重试、降级、返回缓存兜底全都在 60 秒之后才轮到而外层 60 秒已经切断了连接这些代码跑了也没人看。第二等于把线程和连接都焊死了。每一个卡住的请求都会占用一个工作线程、一个数据库连接、一个上游连接。全部设成 60 秒意味着在故障期间资源被占满的时间是原来的 20 倍本来只是慢最后变成彻底不可用。第三超时时间过大等于取消了这个机制。超时的本质是在不确定的情况下给一个确定的截止点让系统在慢的时候还能部分可用。所有层都设一样大等于把止损机制废掉了。顺手说一个重试放大的计算如果每一层都配置了 3 次重试一共三层那么最坏情况下一次用户请求会放大成 27 次下游调用3×3×3。上游本来就慢你再去放大 27 倍流量结果就是彻底压垮。重试次数要在整条链路上统一规划不能每层各配各的。4. 把上游拖到超时的六类真实原因4.1 慢查询、锁等待与事务里的远程调用数据库是超时问题的头号嫌疑对象。判断方法很直接看慢查询日志和当前正在执行的语句。-- 找出运行时间过长的语句 SELECT pid, now() - query_start AS duration, state, left(query, 120) FROM pg_stat_activity WHERE state idle ORDER BY duration DESC LIMIT 20;三类问题最常见。第一类是索引缺失或索引失效导致的全表扫描数据量涨到某个临界点之后突然开始超时而代码一行没改——这类数据驱动型故障最容易让人误判成发版引起的。第二类是锁等待一个长事务持有行锁后面所有请求排队等锁等到超时。第三类是事务里做远程调用事务开着去调第三方接口网络一抖就把数据库连接占住几秒钟。我的做法是在事务边界上做硬约束任何远程调用一律移出事务。这条规矩听起来简单但真正在代码评审里卡住能省掉后面一半以上的超时工单。4.2 连接池与工作线程排队连接池的坑在于排队时间会被算进响应时间但你从业务日志里看不到。业务代码里打印的是查询执行耗时 300 毫秒然而请求在进入业务代码之前已经在池子门口排了 4 秒的队。spring: datasource: hikari: maximum-pool-size: 20 connection-timeout: 800 # 借连接排队上限必须小于网关超时 validation-timeout: 1000 leak-detection-threshold: 10000 # 超时怀疑连接泄漏时打开几个取值经验池子大小不是越大越好它应该匹配下游数据库的承载能力硬堆到 200 只会把数据库连接数打满connection-timeout必须明显小于网关超时这样在连接排队时就快速失败并返回明确错误而不是一直等leak-detection-threshold平时别开会带来额外开销但怀疑连接泄漏时可以临时打开它会打印出连接是在哪一行代码被借走没还的。工作线程池同理。Web 容器的线程数被打满之后新请求连进入业务逻辑的机会都没有表现就是所有接口一起变慢而不是某个接口慢。如果一个服务所有接口同时开始 504先去看线程数和 CPU 负载别去看单个接口的代码。4.3 重试放大与级联挂起级联挂起的典型剧本是这样的某个非核心依赖比如推荐服务开始变慢 → 调用它的业务线程被挂住 → 线程池被占满 → 该服务的所有接口开始变慢 → 上游网关等待超时返回 504 → 网关按配置重试 → 请求量翻倍 → 依赖服务彻底崩掉 → 整条链路雪崩。这个链条里每一个环节单独看都是合理的合起来就是灾难。破法有几个给非核心依赖设极短的超时并配降级拿不到推荐就返回空列表别让它拖住主流程熔断器在错误率超过阈值后直接快速失败不要继续打重试只对幂等接口开放并且限制在链路的一层上。4.4 流式接口下的空闲超时这个场景对应那句很常见的报错stream disconnected before completion: idle timeout waiting for SSE。流式接口SSE 之类的特点是完全不适用总时长超时的模型——一个事件流可能正常持续十几分钟一直不停有数据往下发。真正会杀掉它的是空闲超时连接建立后一段时间内没有任何字节流动就被判定为死连接并切断。两件事要同时做。第一让服务端定期发送心跳保持连接上始终有字节在动# 每 15 秒发一次心跳注释行SSE 规范里以冒号开头的行会被客户端忽略 def heartbeat(): while not closed: yield : ping\n\n time.sleep(15)第二网关侧要针对流式路由单独放开缓冲和超时location /api/stream { proxy_http_version 1.1; proxy_set_header Connection ; proxy_buffering off; # 关键不缓冲才能边生成边下发 proxy_cache off; proxy_read_timeout 300s; # 空闲上限要大于心跳间隔的若干倍 proxy_send_timeout 300s; }提示proxy_read_timeout在 nginx 里并不总是总时长它衡量的是两次成功读到数据之间的间隔。所以只要心跳间隔明显小于它长连接就能一直活着。这个语义经常被误解成流最多只能开 300 秒。如果流式接口偶发中断我一般先确认三个数字心跳间隔、网关空闲超时、客户端 SDK 的 idle timeout。三者中最小那个决定了流的实际寿命而且通常客户端那个是默认值没人注意过。4.5 GC 停顿、DNS 解析与握手开销有几类停顿在应用日志里完全看不到因为整个进程当时都没在跑。长时间垃圾回收停顿是典型代表。表现特征是所有接口同时出现周期性的尖刺尖刺出现的时间点整齐规律。排查手段是打开 GC 日志观察停顿时间的最大值。jstat -gcutil pid 1000 30DNS 解析也常常被忽略。容器环境里如果有大量短连接每次都要走一次解析而解析超时通常长到离谱几秒级。可以用下面的命令观察解析耗时time getent hosts api.internal.example.com如果发现每次解析都要几百毫秒先去看/etc/resolv.conf里的ndots设置和 nameserver 数量把服务名用完整限定名来访问能省掉多次尝试。TLS 握手同理短连接下每次请求都要握手在高并发时这笔账很可观解决办法是把连接池打开并设置合理的空闲连接数。4.6 数据量超出预期最后一类接口本身没问题、逻辑也没问题就是返回的数据实在太大。常见于列表接口没做分页、导出接口直接全量查、报错响应把堆栈和明细一股脑塞回来。判断方法看前面提到的 urht 和 urt 差值——响应头很快就回来了但响应体传不完那就是这个原因。处置手段是加分页、加流式导出、限制单次返回条数。这类问题在测试环境永远复现不了因为测试库只有几千行数据。5. 一次从告警到收尾的完整排查过程5.1 现象收敛与第一轮试探回到开头那个凌晨的告警。现象下单详情接口 504 占比 12%错误文案Response took longer than timeout: PT30000同时段 499 占比 3%说明客户端也在断连。业务服务本身没有重启、没有发版CPU 和内存都正常。第一轮我做了件看起来最省事的事把网关的超时从 30 秒改到 60 秒观察十分钟。结果 504 占比从 12% 降到了 4%但上游接口的 P99 从 400 毫秒涨到了 9 秒请求堆积开始出现数据库连接数逼近上限。这就是典型的把问题往后推——错误少了系统更危险了。所以立刻回滚回到正经排查。5.2 二分法切链路先证明是哪一层慢第二步是切链路。我在网关所在机器上直连上游业务服务绕开网关curl -o /dev/null -s -w ttfb%{time_starttransfer} total%{time_total}\n \ http://order-svc:8080/api/order/detail?id123结果 ttfb 就接近 8 秒。证明慢在上游跟网关配置无关回到业务服务继续往下切。接着在业务服务内部拆这个接口调了两个依赖一个订单主表查询一个用户信息 RPC。我在日志里加了分段计时跑一轮后发现主表查询耗时从平时的 30 毫秒涨到 7.5 秒用户 RPC 正常。根因范围一下子缩到一条 SQL 上。再看数据库侧pg_stat_activity里排在前面的全是同一条查询状态是active等待事件显示为锁。再查锁持有者发现是一个批量更新任务的事务因为数据量扩大后执行时间从几分钟涨到了二十多分钟整个期间持有的锁把在线查询全挡在了门外。5.3 根因落地与修复动作清单根因清晰之后修复动作分三层同时推进数据库层给在线查询补上缺失的联合索引把查询计划从全表扫描改成索引扫描把批量更新任务拆成小批次分批提交每批之间主动让出锁。应用层给这条查询加语句超时比如 2 秒并明确它是可降级查询超时后返回缓存的旧数据而不是继续等把连接池的排队超时设成 800 毫秒让排队的请求快速失败。网关层把超时从 30 秒收敛到 3 秒同时配置幂等接口的一次重试重试只在这一层做。顺带把重试次数在整条链路上捋了一遍发现中间还有一层也配了重试属于重复放大一并去掉。5.4 验证阶段看什么指标改完不是看504 是不是没了就完事要按顺序看四组数据上游接口的 P99 和 P999 是否回落到正常量级这次从 9 秒回到 420 毫秒。网关日志里 urht 的分布确认绝大多数请求在 1 秒内完成。504 与 499 的比例确认客户端侧不再提前断连。连接池的活跃连接数和等待队列长度确认排队消失。最后做一次压测把并发提到日常峰值的 1.5 倍观察 P99 是否仍然在超时预算之内。压测的价值不是看能不能扛住而是看超时预算在压力下还有多少余量。6. 让 504 不再反复出现的工作习惯6.1 把超时预算表写进设计文档每次做完一次超时排查我都会顺手把这条链路的超时数字整理成一张表放进设计文档里。表里只有四列层、参数名、当前值、依据。第三列的依据必须写清楚是下游 P99 × 1.2还是厂商默认值待评估——凡是写不出依据的数字都是下一次故障的种子。这张表还有个附带好处新人接手时不用再去猜某个 30 秒为什么是 30 秒。6.2 让错误响应自带上下文我坚持让网关在超时响应里带上三样东西trace id、触发超时的配置项名与阈值、上游服务标识。用户在客服那边报问题时一句 trace id 就能定位不用再靠大概几点几分去大海捞针。这个改动的成本极低收益极高属于性价比最高的稳定性投入之一。注意错误响应里不要带内部主机名、内网地址这类信息带上服务标识和 trace id 就足够了。6.3 长任务的异步化与降级路径凡是天然超过超时预算的活儿——批量导出、报表生成、大文件处理——不该指望靠调大超时来解决。正确做法是异步化接口先返回 202 和一个任务号客户端轮询或者用推送拿结果。这样请求在毫秒级就结束了任务慢慢跑跑多久都不影响网关。同时每个关键接口都要想清楚一个问题如果下游超时了我能返回什么。能返回缓存返回缓存能返回部分结果返回部分结果实在不行返回一个明确的稍后重试而不是让用户干等 30 秒。降级路径要在代码里写死而不是等出事时临时想。6.4 上线前的超时演练最后分享一个我认为很值的小习惯每个季度挑一个非核心依赖人为把它的响应时间拉长到超时阈值附近观察整条链路的表现。看四件事——哪一层先报错、报的是 504 还是自定义错误、降级是否生效、错误响应里有没有 trace id。这种演练做两三次之后团队对自家系统的超时行为会形成肌肉记忆真出事时第一反应就不是去把 timeout 调大了。我个人在实际操作中的体会是超时问题的难点从来不在配置本身而在于有没有一个清晰的分层模型和一套能快速把请求切片的手段这两样东西一旦建立起来同样的排查从半天缩短到二十分钟是常事。