AI API 返回 502 Bad Gateway 怎么排查

错误含义与用户可见现象

常见现象包括请求立即返回HTML错误页、JSON错误对象、流式连接中途断开后由网关改写为502，或同一请求在部分节点成功。RFC 9110把502定义为网关或代理从入站上游取得了无效响应；它与上游响应过慢导致的504不同。

最小日志示例

至少保留时间、目标主机、路径、网关状态、上游状态、连接/首字节/总耗时、request ID和响应Content-Type。密钥、Authorization头、用户输入和完整输出必须脱敏。

2026-08-23T14:02:11Z status=502 upstream_status=- connect=0.031s ttfb=- total=0.082s request_id=req_xxx

分层原因

客户端层可能使用错误base URL或错误协议；本地代理可能缓冲或提前关闭流；网关层可能解析到无效响应头、连接被重置或上游池无健康节点；上游服务可能进程崩溃、TLS握手失败或返回不符合协议的数据。若只有某个请求触发，还要检查输入大小和特定功能路径。

十分钟快速排查

第1分钟保存脱敏响应和request ID；第2—3分钟用同环境最小请求复现；第4分钟检查状态页；第5—6分钟区分自有与厂商网关；第7分钟查看上游连接日志；第8分钟比较非流式请求；第9分钟降低并发；第10分钟决定有限重试、降级或联系服务方。

curl -sS -D headers.txt -o body.txt --max-time 30 https://api.example.com/health
curl -sS -v --max-time 60 https://api.example.com/v1/test

重试是否安全

仅当故障被判断为瞬时且操作可重放时重试。读取类请求通常风险较低；创建资源、触发工具、扣费或外部写入可能已经在上游执行，只是响应在网关处丢失。应使用幂等键或先查询原请求状态，采用有上限的指数退避与随机抖动，禁止无限循环。

临时恢复与长期预防

临时可降低并发、暂停非关键任务、切换已验证的健康上游或关闭流式功能。长期应设置健康检查、连接池与合理超时，记录upstream_status和request ID，建立按网关节点与上游实例分组的502告警，并演练幂等重试和降级。

厂商差异与升级条件

不同厂商可能把内部过载、模型启动或边缘节点错误统一映射为502，也可能返回自定义错误码，必须以当前官方文档和响应体为准。持续超过服务状态页窗口、多个区域复现、携带同一request ID或最小请求仍失败时，应提交时间范围、脱敏请求、响应头和追踪信息给服务方。

按证据定位责任边界

先画出客户端、企业出口、CDN或负载均衡、自有反向代理、API网关、模型服务六个节点，并在同一UTC时间轴上对齐日志。若自有网关 access log 为502且 upstream_status为空，优先调查名称解析、连接建立和健康节点；若 upstream_status也是502，则继续查看下一跳响应。若直连已授权上游成功而经自有代理失败，证据更指向代理配置。不要仅凭浏览器错误页判断厂商宕机，也不要把一次成功当成问题已经消失。每个结论都应附时间范围、样本数和request ID。

响应头、TLS与流式请求检查

保存Server、Via、Date、Content-Type和追踪头可以帮助判断错误由哪一层生成，但头字段也可能被网关改写，只能作为线索。连接阶段检查SNI、证书链、上游主机名和协议版本；HTTP/2或长连接问题可用受控的HTTP/1.1短请求对照。流式接口还要区分握手前502与已返回200后连接中断：后者通常不能再改写为标准502，需要检查客户端收到的事件、代理缓冲、空闲读取超时和上游结束标记。测试不得绕过生产权限或暴露密钥。

恢复决策表与验证

若错误只在单节点出现，先摘除该节点并保留现场；若随并发升高，降低并发并检查连接池和端口；若随特定载荷出现，最小化输入并核对大小限制；若所有区域和最小请求均失败，查状态页并升级服务方。修复后至少验证健康检查、普通非流式请求、流式请求、并发小样本和失败降级五类路径，连续记录一段观察窗口内的502率、P95耗时和上游连接错误。观察窗口与通过阈值由业务SLO确定，本文不伪造固定结论。

复盘与防止再次发生

复盘应回答首个异常时间、检测延迟、用户影响、错误生成层、触发条件、扩大因素、缓解动作和永久措施。将request ID贯穿入口与上游，统一UTC时钟，给连接失败、无效响应头、上游重置和无健康实例设置不同错误标签。变更代理超时、缓冲或连接复用前先在预发布环境回放脱敏流量。告警既看502比例也看请求量，避免低流量单次错误误报；同时设置绝对数量门槛，避免总流量下降掩盖大面积故障。

面向用户的错误呈现

前端应显示可重试但不保证成功的提示、追踪ID和安全的下一步，不展示上游主机、堆栈或原始HTML。后台把502按生成层分类，客服可用request ID查询状态。批量任务保留未完成项目并允许用户确认后续重试，不能把连接断开显示为任务已完成。状态恢复后通知只基于真实监控，不提前承诺。

502 可以无限重试吗？

不可以，无界重试会放大故障；必须限制次数、总时长并确认请求可安全重放。