系统接口502错误怎么解决

线上接口突然开始零星或大面积返 502，业务方催、日志里又只有一句「Bad Gateway」，第一反应往往是把锅甩给上游模型服务。这篇不讨论协议怎么写、客户端怎么配，只讲工程落地：怎么在几分钟内判断是网关、连接池还是上游的问题，怎么用一次请求的字段把范围缩到最小，以及止血之后该补哪些配置。

线上突然开始零星或大面积返 502，业务方在群里催，日志里翻来覆去只有一句 Bad Gateway。很多人的第一反应是把问题推给上游模型服务，但真正的原因往往出在网关配置、连接复用或者连接池上。这篇不讨论协议细节，只讲工程落地：怎么在几分钟内判断问题出在哪一层，怎么用一次请求把范围缩到最小，以及止血之后该补哪些配置。

负责排查的人通常是运维和后端两个角色，所以下面的顺序是按「谁都能上手」来写的：先确认是谁返的码，再切链路，再看日志字段，最后才是改配置。中间任何一步拿到确定结论，都可以直接跳到对应的处理动作。下面涉及的阈值类数字，都以你当前环境实测和历史监控为准，站内也有对应的工具页可以交叉验证。

先认清 502 是谁返给你的

502 是网关或反向代理替你连上游时，没拿到合法响应才回给你的措辞。它只说明「中间那一跳失败了」，不说明失败发生在谁身上。所以第一步永远不是去看上游，而是确认返这个码的那一层到底是谁。本机 Nginx、云负载均衡、服务网格 sidecar 都会返 502，日志位置和排查入口各不相同，先看清楚再动手，能省掉大量无效翻日志的时间。

• 502 和 504 的区别：能连上但等超时通常走 504，连不上、连一半断了、上游返回残缺才更容易出 502，先按这个粗判。
• 先确认返 502 的那一层是谁：本机网关、云负载均衡、服务网格 sidecar，各自看日志的地方不同。
• 不适用的情况：客户端本地 DNS 或代理写错时也会看到 502，这类要先在纯终端里直连验证，别在服务端折腾。
• 如果链路里既有网关又有负载均衡，先在负载均衡侧看后端健康状态，很多 502 是后端已被摘掉但缓存还在指过去。

把链路切段，先缩小到一段

排查 502 最怕的是一上来就盯着应用日志看，因为应用可能根本没收到请求。正确做法是在脑子里画一条最短链路：客户端 → 网关 → 应用 → 上游接口，每两段之间找一个能独立发请求的入口。然后从中间往两头打，看哪一段开始复现。这样做的好处是不依赖任何监控面板，用一台能连通的机器就够了。

1. 从网关所在机器直打上游用 curl 带上真实请求头直接请求上游地址，绕开应用层。如果这里就 502 或连不上，问题在上游或网络，不在应用。
2. 从应用服务器打网关在应用机器上请求网关的对外地址，看返回什么。如果这里正常、刚才直连上游异常，说明问题在应用和网关之间。
3. 再从网关打上游两步结果不一致，就说明问题夹在中间那一段。记录每段的耗时和状态码，才能判断是一直失败还是高峰才失败。
4. 固定下来当模板把这三条命令存成脚本，下次出问题直接跑，不用重新想从哪开始。

切段的时候要顺手记录时间点。因为 502 经常是间歇性的，单次请求成功不代表问题不存在。拿同一组命令在业务低峰和高峰各跑几轮，把耗时和成功率记下来，后面判断是容量问题还是配置问题时，这些记录就是依据。

日志里必须有能定位 502 的几个字段

很多团队的日志只有一句请求失败加一个状态码，这种日志出了 502 基本只能靠猜。要定位到具体哪一跳出问题，日志里至少要有能把一次请求串起来的字段。网关和应用两侧要用同一个请求 id，否则只能靠时间戳去对齐，误差一大就白干。字段不够时，先临时加日志再复现，比盲目改配置快得多。

请求 id

一次请求在网关、应用、上游之间共享的标识，用来把多侧日志串成一条链。

上游地址

这次请求实际打到了哪个后端节点，用来判断是不是某台机器的问题。

连接耗时与首字节耗时

区分是连不上还是连上了但等太久，两者处理方向完全不同。

上游返回码

上游真实回了什么，注意它可能和应用层看到的码不一样。

是否复用连接

标记这次用的是新连接还是连接池里的旧连接，排查半开连接时很关键。

• 上游返回体不要整段打，截断保存即可，避免把敏感内容写进日志。
• 网关和应用两侧用同一个请求 id，否则只能靠时间戳猜，误差一大就没法用。
• 没有这些字段时，先临时加日志再复现问题，不要一边猜一边改线上配置。
• 日志保留时间要覆盖一个完整的业务周期，否则高峰期出的问题第二天就查不到了。

日志字段补全之后，你会发现自己判断故障的速度明显变快。同一类 502 再来一次，先看请求 id 对应的那几行，基本一眼就能判断是哪一段断的，不用再去翻好几台机器的日志。

超时是分层设的，别只调一个数

超时设置最容易犯的错是只盯着一个值调。实际上连接超时、读取超时、整体超时是三件事：连不上是连接超时，连上了但等不到响应是读取超时，整个请求从发出到放弃是整体超时。把这三个混成一个值，真实瓶颈就会被掩盖，调大之后看着是好了，其实是把失败推到了更上层。

层级之间要有长短关系：网关侧超时应当比应用侧略长，应用侧又要比上游读取超时略长。这样失败会先在离问题最近的那一层暴露出来，日志里能看到真实原因。反过来排，永远是上层先断，下层什么记录都没有，排查起来只能靠猜。

调整超时之后一定要盯连接池占用，很多人把超时放长，结果连接被占满，502 没少反而更多。判断标准很简单：改完之后成功率上去了但连接池使用率一直贴着上限，说明只是把问题换了个地方，还得回头处理容量或上游。

连接复用与连接池是 502 的高发区

连接复用出问题时的现象很典型：上游其实已经主动关掉了长连接，网关这边还拿着旧连接去发请求，于是拿到一个半开连接，直接报 502。这类问题不会一直出现，往往是一批连接集中过期的时候才冒出来，所以看单次请求很难判断。检查方法是确认网关的 keepalive 存活时间跟上游保持一致，并观察上游断连后网关有没有及时淘汰旧连接。

连接池打满也很常见，但表现可能既是 502 又是超时，关键要分清是「连不上」还是「没得用」。池子触顶时新请求排队或被拒绝，接口就会成片失败。排查顺序建议是先看连接池指标有没有顶到上限，再看上游有没有主动断连的记录，最后才怀疑网络链路。

• 确认 keepalive 存活时间与上游一致，避免复用已经关闭的连接。
• 检查连接池上限和当前占用，池子打满时优先扩容或限流，不是加超时。
• DNS 缓存过久会打到已下线的节点，检查解析缓存和节点摘除是否及时。
• 把连接池使用率加进监控，别等 502 出现才发现池子早满了。
• 如果只有某几个后端节点报 502，优先怀疑节点本身或摘除机制，而不是整条链路。

这一节涉及的具体数值，比如池子上限、存活时间、缓存时长，都要按你当前环境的实测来定。站内的速度测试和连通性工具可以帮你确认某段时间的实际表现，但要记住测出来的是当时的状态，不能直接当成长期配置的依据。相关工具在 /tools/speed-test 可以找到。

上游本身的问题怎么确认

确认是上游的问题，靠的是探针接口而不是业务接口。用一个不经过业务逻辑的健康检查地址单独打上游，如果探针是好的但业务接口 502，说明上游整体在线、只是某个能力不可用。反过来探针也挂，那就是上游整体不可用，处理方向完全不同。注意健康检查要能反映真实依赖，只返回一个固定 ok 的探针等于没探。

还有一种容易被忽略的情况：上游返回的响应格式不符合网关预期，网关解析失败也会抛 502。这时抓一次原始响应看格式，比反复重启服务有用得多。确认是上游原因之后，优先做降级和限流，而不是无限重试。

重试、降级、熔断的落地顺序

重试是双刃剑。上游已经扛不住的时候，大量同步重试会把失败放大成一波更大的流量，本来只是零星失败，重试之后变成整片挂掉。所以重试只对幂等请求开，限制次数和总时长，并且一定要加退避和抖动，让重试分散在不同时刻，而不是同一秒集中打过去。

1. 先判断请求是否幂等只有幂等的读类请求才允许自动重试，写类请求靠重试可能造成重复提交。
2. 限制次数与总时长重试次数和总等待时间都要有上限，超过就直接返回失败，别让请求一直挂着。
3. 加退避和抖动每次重试之间拉开间隔并加入随机量，避免同一时刻的失败被放大成一波流量。
4. 准备好降级路径切换备用上游、返回缓存结果、或明确告知暂不可用，都比一直挂着强。
5. 熔断打开要有人知道配告警通知，否则故障恢复了熔断还开着，等于持续人为制造不可用。

降级和熔断的顺序也要想清楚：先限流保证核心接口，再降级非核心能力，最后才是熔断。熔断适合已经确认上游短时间恢复不了的情况，一旦打开就要有人盯着，恢复后及时关掉。这些策略的具体参数要结合你的业务容忍度来定，不能照搬别人的配置。

止血之后要补的清单

故障恢复不代表事情结束。502 这类问题的价值在于它能暴露出链路里某个环节没有可观测性或者配置从来没对齐过。把这次的排查过程整理成固定顺序，下次照着做，比每次重新摸索省事得多。补的东西不用多，但每一项都要能落到具体的面板、告警或文档上。

• 把排查顺序写成固定流程：确认返码层、切链路、查日志字段、看连接与超时、再看上游。
• 补关键指标：成功率、连接池使用率、上游耗时分布、重试次数，缺哪个补哪个。
• 给 502 单独建告警，按失败比例触发而不是按绝对值，避免单次抖动打扰值班。
• 复盘时区分配置问题和容量问题，两者的整改动作完全不同，混在一起会改错方向。
• 把这次用到的 curl 命令和日志字段整理成文档，交给下个值班的人。

配置问题和容量问题要分开看：配置问题是改一次就长期有效的，容量问题则要靠扩容、限流或架构调整。如果每次都当成配置问题来改超时，短期内看着恢复了，下一个高峰还会照样出问题。判断标准是看故障跟流量高低有没有明显相关性，有相关性的基本就是容量问题。