Runbook：429、5xx、超时与流式中断

这类故障通常来自上游容量、网络、Proxy 或长连接配置。先判断是单账号、单供应商、单模型，还是整个入口链路。

上游 429

检查：

• account_id 是否集中。
• rate limit reset 时间和剩余窗口。
• 账号并发是否高于上游允许值。
• 多个 Account 是否实际共用同一上游项目/额度。
• 5h/7d、RPM/TPM 或日 quota 是否耗尽。
• 是否有突发重试放大流量。

处置：让调度使用独立额度的备用账号；等待 reset；降低并发或入口流量。Clear Rate Limit 只清本地状态，不会恢复真实上游额度。

5xx、529 和过载

• 单账号：摘除并测试同供应商其他账号。
• 同供应商全部失败：切备用供应商，保留上游 request ID。
• 全部供应商失败：检查反向代理、出口网络、DNS 和应用。
• 仅特定模型失败：检查模型状态、payload 和能力兼容。

不要把上游 5xx 自动解释为 Sub2API 崩溃。使用 error_source、upstream status 和 latency 区分。

超时定位

现象	优先检查
未连接上游就超时	DNS、Proxy、TLS、allowlist
上游首字节慢	模型排队、TTFT、上游容量
流式中途断开	proxy_read_timeout、CDN、出口连接、上游断流
客户端先断开	客户端超时、移动网络、用户取消
全部响应最后一次返回	Nginx/CDN buffering

结合 auth、routing、upstream、response latency 判断慢在哪一段。

SSE 最后一次性返回

Nginx 至少确认：

proxy_buffering off;
proxy_cache off;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

同时检查 CDN 是否缓存/缓冲 API 路径。更多配置见反向代理与 HTTPS。

WebSocket 失败

• 反向代理传递 Upgrade/Connection。
• 外部 HTTPS 对应 wss://。
• Ops 实时监控软开关已启用。
• 代理允许 Sec-WebSocket-Protocol，管理员 JWT 不应放在 URL 查询参数。
• 空闲超时高于实际会话时长。

第三方兼容上游

文本请求成功但工具、流式或 usage 失败，通常是“部分兼容”：

• OpenAI 上游是否支持 Responses，还是只支持 Chat Completions。
• Anthropic SSE 事件名、usage 和 beta header 是否完整。
• Gemini 是否真的是原生 v1beta，而不是 OpenAI 兼容接口。
• Base URL 是否导致重复 /v1 或 /v1beta。
• 模型映射后是否仍支持工具、thinking 和图片。

不要通过吞掉解析错误来上线；这会把协议问题转化为计费问题。

恢复验证

验证非流式、SSE 第一事件时间、完整结束事件、客户端主动断开、usage、并发释放和故障切换。至少观察一个原告警窗口。