1. 两天排查从一个抽风的接口开始大模型 API 调用的项目上线第三周测试环境一切正常生产环境却开始闹脾气。具体表现是每天下午两点到四点之间外部服务返回的响应要么超时要么直接报 502连续重试三次偶尔能成功一次但重试本身又会拖慢整体任务链路。这个问题的魔幻之处在于它既不是持续的故障也不是频率足够高的崩溃而是那种让你反复怀疑是不是我代码写错了的间歇性抽风。我一开始就怀疑自家服务毕竟作为调用方超时设置、重试策略、连接复用这些环节哪个都有可能出问题。但我低估了这个排查的难度整整两天我才敢下结论说问题真不在我这边。这里的我这边指的是从我写的调用代码、到部署服务的容器网络、再到我已经能控制的所有中间链路。而真正的故障点是上游服务商的网关层。为了让这个结论站得住脚我做了完整的证据链后面会详细说怎么有底气地甩锅。这篇文章就是把这两天的排查过程完整复盘一遍包括每一轮怎么定位、用了什么工具、得出了什么结论以及最终沉淀下来的防御性设计。如果你也在被外部 API 的间歇性中断折磨这份经验可以直接抄作业。2. 第一轮从自家代码找问题2.1 超时与重试最常见的背锅侠接到生产环境告警后的第一个动作永远是检查自己代码里的超时时间。这是有原因的——大模型 API 的响应时间波动本来就大如果我把超时设成固定的 30 秒而服务端平均响应在 15 秒上下那么任何网络抖动都会放大成超时失败。我先翻了当时调用讯飞星火 API 和阿里云百炼的客户端配置。用的是 Java 的 OkHttp 封装连接超时设了 10 秒读取超时设了 60 秒。理论上读取超时已经足够宽裕但问题在于——连接超时。如果服务端的网关在接受 TCP 连接后有延迟握手的行为客户端 10 秒的连接超时就会频繁触发表现就是请求发出去就断了。我还检查了重试逻辑。之前写的是失败后立即重试 3 次中间没有间隔。这个策略在瞬时抖动时是有效的但一旦上游处于持续不稳定状态立即重试反而会放大问题第一次请求超时同一秒内发第二次网关还在拥堵第二次也超时第三次结果一样。三次失败后任务直接挂掉业务侧看到的就是一段窗口内所有任务都失败。我后来把重试策略改成了指数退避 抖动第一次重试等 1 秒第二次等 2 秒第三次等 4 秒每次间隔再加上不超过 1 秒的随机抖动。改完之后单次调用的失败率确实降了一些但下午两点到四点的集中失败依然存在。这说明问题不是单纯靠调用方重试能解决的。2.2 连接池与长连接你以为的稳可能只是假象超时和重试改完没解决根本问题我开始怀疑连接池。生产服务用 OkHttp 默认的连接池配置最大空闲连接 5 个每个连接保活 5 分钟。对于大模型 API 这种高并发、长耗时的调用场景这个配置其实是有隐患的。逻辑是这样的当 20 个线程同时发起调用连接池里只有 5 个空闲连接其余 15 个请求必须等待或新建连接。如果服务端支持 keep-alive新建的连接会在请求结束后回到池中但如果上游网关配置了较短的 keep-alive 超时时间比如 60 秒没活动就断开而连接池里的连接又没有及时感知就会出现取到一条已经被服务端关闭的连接发请求后立刻报错的情况。排查方式是在服务端加了一层日志把每次请求对应的本地端口、远端 IP、连接复用标志都打印出来。结果发现一个规律报错的那批请求绝大多数用的是复用连接而不是新建连接。这基本坐实了连接池失效的问题。但我并没有立刻认定这是最终原因。因为我加了连接保活之后问题依然存在。这让我意识到上游网关断连接可能是结果不是原因——它主动断开连接可能是因为服务端已经不堪重负或者是网关层面的超时策略本身就激进。2.3 代码侧排查结论与修正第一轮排查结束时我做了三处代码调整这些调整本身是合理的只是没能彻底解决问题把所有外部调用的超时参数统一收口到配置中心不再散落在各业务代码里方便之后快速调整。重试策略从固定 3 次立即重试改为指数退避 抖动并且把每次重试间隔和当前请求 ID 一起写入日志。连接池配置从最大 5 个空闲、保活 5 分钟调整为最大 20 个空闲、保活 8 分钟同时开启 OkHttp 的connectionPool.evictAll()定时清理任务每 60 秒清理一次过期连接。这些改动让调用失败的绝对次数从每小时 200 多次降到了 60 多次但下午的高峰窗口依然存在。到这里我才开始认真考虑一个可能性上游服务端是不是也在经历不定期的波动或者压根就是网关层在搞鬼。从改自己的代码转向查链路的每一环这是排查思路的关键转折点。3. 第二轮顺着网络链路把真相一层层剥开3.1 从服务端日志到客户端抓包把视角拉远代码改完没啥大用之后我决定离开舒适区直接抓包。在客户端容器里用tcpdump抓 HTTPS 流量同时配合服务端 nginx 的 access log 一起看。这里有个细节如果你调用的是 HTTPS 接口抓包抓到的是加密数据但 TCP 层的握手指纹、TLS 握手过程、连接断开时的 FIN 或 RST 标志位都是明文的光看这些就能判断链路状态。我抓了 30 分钟的包发现一个非常刺眼的规律所有失败请求在 TCP 层都有共同的痕迹——客户端发出请求后服务端回了一个 TCP ZeroWindow随后立刻发送 FIN 断开连接。从服务端视角看请求根本没到业务逻辑而是直接死在接入网关这一层。ZeroWindow 的意思是接收方的接收缓冲区满了TCP 协议要求发送方暂停发送。按照当时请求量估算单个请求的 body 不过几千字节根本不可能撑爆接收缓冲区。唯一的解释是网关进程本身已经处于过载或半死状态TCP 缓冲区无法正常回收。这基本可以排除我这边代码的问题了但光有 ZeroWindow 还不够我得继续找更具体的证据。我还发现一个时间规律失败请求在 TCP 层的表现是客户端发送了 [PSH, ACK] 数据包之后服务端不回 ACK而是直接回 RST。RST 比 FIN 更暴力意味着服务端应用层已经彻底放弃这个连接。同一个服务端 IP 下面80% 的 RST 都集中在固定的那几台网关节点上另外 20% 散落在其他节点。这说明不是整个服务端集群都挂了而是个别节点有问题。3.2 503 与重试风暴不要只看次数要看趋势抓包发现个别节点异常之后我回到业务日志里重新统计了一遍失败响应码。之前只盯着 502因为大多数网关层错误都以 502 形式返回。打开原始响应体一看我发现实际错误码分布是这样的44% 是 502 Bad Gateway发生在网关向后端业务服务转发时。31% 是 503 Service Unavailable发生在网关自身限流降级时。25% 是连接被重置客户端在收到任何 HTTP 响应前就报错。这里有个关键信息容易被忽略503 意味着服务端明确告诉你我现在忙不过来你可能需要晚点再试。但 503 返回得太快时客户端会把它当成一次标准的可重试请求于是大量 503 反而会引发客户端层面的重试风暴。我在日志里看到的最极端情况是同一个请求 ID 在 8 秒内重试了 14 次每次都拿到 503等于客户端自己把自己打瘫了。当时的原始日志脱敏后大概是这样的2025-01-14 14:23:01.123 [http-nio-8080-exec-11] INFO reqIdTRACE-8821 retry0 code503 cost312ms 2025-01-14 14:23:01.456 [http-nio-8080-exec-17] INFO reqIdTRACE-8821 retry1 code503 cost198ms 2025-01-14 14:23:02.012 [http-nio-8080-exec-9] INFO reqIdTRACE-8821 retry2 code503 cost87ms重试间隔只有 500 毫秒左右明显是旧的固定重试逻辑还在某个老版本节点上跑。这说明除了修改配置还要确保所有容器都拉到了新配置灰度发布没做干净。我后来把所有节点的配置版本统一核对了一遍才终于把这部分变量排除掉。3.3 网关层的黑箱限流、配额与负载均衡抓包和日志交叉验证了一个结论上游网关存在局部节点故障。但我还想搞清楚为什么只有个别节点出问题为什么固定出现在下午。于是我列了一张上游节点的 IP 清单逐个做健康探测然后用 curl 直连每个节点的网关地址模拟业务请求。结果差异非常明显多数节点响应正常只有两个节点响应时间超过 20 秒其中一个节点直接拒绝连接。进一步测下去发现这两个节点恰好承担了当天最高的流量转发任务。这基本能够推断这两个节点触发了上游服务商的过载保护机制——要么是 QPS 限制要么是并发数限制要么是内存压力触发的自我保护。这里要插一句大模型 API 的调用费用和配额限制通常是账号级的但实际限流执行往往在节点级。也就是说你账号的并发上限是 50但网关会把这个限额下发到节点某个节点压力大时你打上去的请求就被快速拒绝而另一个节点还能正常处理。这种设计对服务商来说是合理的保护机制但对客户端来说就是薛定谔的稳定——你永远不知道下一个请求会被哪个节点处理。作为一个调用方我能做的不是去控制上游的负载均衡策略而是要让自己的代码具备更强的韧性。现在很多人讨论API 调用工具或者低代码平台调用 API核心真的不是把请求发出去就行而是要把异常处理、降级、熔断做成默认能力。4. 定性与长期方案手里有证据心里才不慌4.1 甩锅要讲证据一份完整的证据链怎么搭排查进行到第二天下午我已经有了足够的技术证据。但足够的技术证据和能说服团队和上级的证据是两回事。真要在晨会上说问题不在我们这边至少需要以下五样东西客户端配置快照超时时间、重试次数、连接池参数证明调用方配置在合理范围。客户端日志切片采样失败请求的 reqId、耗时、错误码、重试次数证明失败不是偶发也不是客户端误报。抓包文件关键帧找出几条代表性请求的 TCP 层交互重点标注 ZeroWindow 和 RST证明连接是被服务端主动断开。上游健康探测记录直连不同节点网关的响应时间对比证明只有部分节点出现延长响应和拒绝连接。业务影响范围统计按小时维度统计失败率和流量高峰曲线叠加证明问题集中在高峰期。我把这五类证据整理成一份带时间线的文档配合图表展示失败率与流量的相关性。这个动作的价值在于它让结论从我感觉是上游的问题变成了一个可以被复核的论证过程。顺便说一句如果你也想在项目里沉淀类似的排障模板建议把关键证据的采集做成自动化脚本别等故障发生了才手动抓包。4.2 调用方必须有的防御性设计清单经过这次事故我给自己定了一条规矩凡是调用第三方 API无论对方 SLA 写得如何天花乱坠调用方都得按对方随时会挂来做设计。具体来说我沉淀了下面这份清单超时分级。连接超时、读取超时、整体调用超时分开设置不要只设一个。连接超时通常 5-10 秒读取超时可以按接口特性放宽到 60 秒甚至更长整体超时用连接超时加读取超时再加冗余。重试必须带退避。固定时间重试在故障窗口期只会放大流量。指数退避加随机抖动是基本要求三到五次重试足够不要再多了。熔断必须独立于重试。重试解决的是瞬时抖动熔断解决的是持续故障。用一个简单的滑动窗口计数器一分钟内失败率超过 50% 就打开熔断后续请求直接走降级逻辑不再打向上游。降级方案要提前写。调用大模型 API 失败时是返回缓存结果、返回默认文案还是降级到本地小模型这个逻辑要在和平时期就写好别等系统挂了才来想。关键调用要留痕迹。打印 reqId、耗时、错误码、重试次数、上游节点 IP方便事故后回溯。日志切片的粒度和格式决定了你事后排查的速度。我对接阿里云百炼、豆包这些平台以及本地部署的大模型 API 时都用的是这套统一封装。封装层的核心就是不信任任何外部服务的稳定性所有外部调用都走同一个兜底逻辑。可能有人觉得这样过度设计但经历过一次两天排查才定性的事故后你就会明白这套设计省下的不只是时间还有整个团队的心态。4.3 监控告警与常态化预案这次的故障虽然源头不在我这边但生产环境的问题不能就这样不了了之。优化完调用逻辑后我围绕外部 API 做了一层新的监控目前运行下来比较健康。监控的关键指标有三个调用成功率按分钟聚合低于 99% 自动告警。调用耗时分布P95 和 P99 分别跟踪一旦 P95 突破 30 秒就拉响提醒。错误码分布把 502、503、429、超时、连接重置分成五类分别统计任何一类突然增长都能单独告警。这层监控跑起来之后我再也不用来回翻日志了。告警一响打开控制台就能看到是哪种错误、发生在哪个时间段、有没有和流量高峰重合。除了监控我还准备了一份外部服务异常处置手册里面写了四件事什么情况下触发手动降级怎么触发。和上游服务商客服沟通时需要提供哪些信息账号、时间窗口、reqId 列表、响应体截图。哪些操作坚决不能做比如反复重启客户端容器以为重启能解决问题。故障期间如何向业务方同步进展不制造恐慌。这份手册现在放在团队知识库里每次新人接手大模型 API 调用相关项目时都会先看一遍。5. 实战速查表与我的体会5.1 常见 API 中断场景排查对照表排障经验这东西光看长篇大论记不住我把这次和之前几次的排查过程浓缩成了一张速查表直接照着顺序查就行。现象第一排查点第二排查点第三排查点可能的根因偶发超时重试可成功代码超时设置是否过短网络链路是否抖动上游网关节点负载不均衡对端过载保护触发大量 502服务端 nginx 日志后端业务服务健康状态上游网关转发配置对端业务进程崩溃或响应超时请求秒回 503客户端是否触发重试风暴上游限流配额是否耗尽账号 QPS 是否超限限流策略触发TCP 连接被 RST客户端是否使用失效连接池服务端 keep-alive 配置网关节点是否半死连接池假复用固定时段集中失败定时任务是否集中触发上游是否定期发版或运维是否撞上对方业务高峰上游运维窗口或高峰期过载偶发连接超时无响应码抓包看 TCP 握手是否完成DNS 解析是否异常TLS 握手是否超时网络链路或对端网关无响应这张表的核心逻辑是先看客户端会不会用错再看得不到响应时的链路痕迹最后才判断对端状态。不要一上来就怀疑对方服务商不行很多问题确实是自己代码的锅胡乱甩锅只会让排障走弯路。5.2 给团队所有成员的排障 SOP排查外部 API 问题时我推荐大家都按下面的 SOP 走步骤不复杂但顺序很重要。第一步确认时间范围。故障从几点开始到几点结束和业务高峰、定时任务、版本发布时间有没有重叠。这一步能过滤掉至少三成的问题。第二步导出客户端日志。按照 reqId 聚合统计错误码分布和耗时分布。重点看错误码是不是集中在某一种类型上如果类型杂乱问题可能出在网络链路如果类型单一问题多半在上游。第三步服务端日志与网络抓包同步进行。如果服务端有网关层日志先看网关日志如果没有直接在客户端抓包。抓包时只需要关注 TCP 标志位、TLS 握手耗时、发送和接收的字节数不用解密 HTTPS 明文。第四步做直连对比测试。用 curl 或 Postman 直接调用外部 API连续请求 20 次统计成功率和耗时。如果直连也有问题基本可以排除本地代码因素如果直连正常则问题大概率出在客户端进程内的连接管理或线程调度上。第五步带着证据联系上游。这一步很多新人不敢做其实没必要怕。服务商客服每天都会接到这类反馈你提供的时间窗口、reqId 列表、错误码统计反而是帮助他们定位问题的关键线索。严格按这个顺序走绝大多数 API 中断问题在两小时内就能定位到层。两天大部分时间浪费在来回怀疑上。5.3 我个人在实际操作中的体会这次排查刚结束的时候我在日报里写了一句问题定位为上游网关节点过载非我方代码缺陷但心里其实很清楚如果不是因为我们把超时重试和连接池都改了一遍这个结论也不会来得这么快。先说心态层面的教训。外部 API 不稳定是常态不是异常。大模型 API 也好普通业务 API 也好只要数据包要从别人家的服务器上走一圈你就得接受一个现实你控制不了物理距离、网络运营商、对方网关负载。与其祈祷对方永远稳定不如把自家代码的鲁棒性拉满。再说技术层面的教训。连接池复用、指数退避重试、超时分级这三样东西是调用方的基本功但很多项目里它们要么没配要么配错。尤其是连接池很多人以为连接池越大越好实际跑下来大而空的连接池比小的更脆弱。我后来把连接池参数全部改为按下游实时响应时间和请求量动态调整的方向虽然实现成本高一些但效果最稳。最后一个小技巧遇到外部 API 间歇性失败时第一时间把上游返回的响应头完整打印出来。响应头里通常带有x-request-id、retry-after、quota-remaining之类的字段。retry-after是对方明牌告诉你的重试等待时间比你自己猜退避间隔准得多。这次排查要不是我先盯住了日志里的错误码分布可能还会在改代码-测试-再改代码的循环里多绕一天。两天排查的结论是简单的简单的结论背后是扎扎实实的全链路验证。以后再有人说API 调用怎么又断了我的建议就一句话先按照 SOP 把证据链打全再看一眼你手里有没有retry-after都没有问题的时候再考虑要不要找上游问一句——但大概率你会发现证据链打全的那一刻答案自己就浮出来了。