直接答案
502 表示充当网关的服务没有从上游取得有效响应；关键是找到哪一跳生成 502，并确认请求是否到达后端。
这篇内容解决什么问题
解决 Bad Gateway、upstream connect error、上游响应无效和代理返回 HTML 502。
先确认症状与影响范围
请求返回 502 Bad Gateway，响应体可能是代理生成的 HTML，也可能是 API 网关的 JSON。HTML 中的品牌、响应头和 server 字段有助于确认生成 502 的代理层。
只有大请求、长响应或流式连接失败时，可能是上游连接、响应头或代理缓冲问题；全部轻量请求也失败则更像服务链路不可用。
- 保存响应头和 Content-Type，确认 502 来自哪一层。
- 比较
/models、最小生成请求和完整业务请求。 - 记录是否只在某个模型、网络出口或代理环境出现。
常见原因与责任边界
502 通常涉及至少两跳服务。客户端看到的网关可能是 CDN、企业代理、CodeNodex 或自建反向代理，不能把所有 502 都归因于模型上游。
- 边缘代理无法连接 API 网关，或 DNS/连接池出现异常。
- 网关无法连接模型上游，或上游提前关闭连接。
- 上游返回无效 HTTP 响应、过大的响应头或不受支持的协议。
- 自建代理的 upstream、SNI、Host 或超时配置错误。
按层执行最小诊断
从最靠近客户端的一跳开始：记录最终主机和响应头，然后在不经过可选企业代理的受控环境做对照。不能绕过组织策略时，由网络管理员完成该对照。
最小请求成功但流式请求 502 时，重点检查代理是否支持长连接、SSE 和禁用不当缓冲。
- 01识别生成层使用响应头、HTML 品牌、request ID 和 server 字段定位。
- 02测试轻量路径先请求模型列表，再执行最小非流式生成。
- 03测试流式路径仅在非流式稳定后检查 SSE 与代理缓冲。
- 04关联服务日志按 UTC 时间和 request ID 查询网关与上游日志。
curl -sS -D /tmp/api-502.headers -o /tmp/api-502.body -w 'remote=%{remote_ip} status=%{http_code} total=%{time_total}
' 'https://<your-api-host>/v1/models' -H "Authorization: Bearer ${API_KEY:?set API_KEY first}"
sed -n '1,30p' /tmp/api-502.headers
针对根因完成修复
客户端只能对瞬时 502 做有限退避；自建代理应修正 upstream、TLS SNI、Host、连接和流式转发配置。托管网关异常则提供证据等待服务恢复或按已验证策略降级。
- 01修正 upstream确认协议、主机、端口、SNI 和 Host 与上游要求一致。
- 02校准连接设置合理连接池、连接超时和空闲连接生命周期。
- 03支持 SSE避免代理缓冲完整响应，保持流式连接和正确 Content-Type。
- 04有限退避只对可安全重放请求重试，并设置熔断。
验证修复而不是只看一次成功
分别验证模型列表、非流式和流式请求，并在每层保存 request ID。若只有绕过某代理才成功，应修复代理而不是把绕过方案作为长期配置。
- 轻量、非流式与流式路径均通过。
- 响应来自预期 API，而不是代理 HTML 页面。
- 代理日志可关联一次完整的客户端到上游请求。
安全边界与升级证据
不要通过关闭 TLS、信任任意证书或转发完整 Authorization 日志处理 502。网络对照测试必须遵守组织策略，并在完成后撤销临时访问。
- 不禁用证书验证。
- 不把 API Key 写入代理 access log。
- 不把未知公共代理作为故障绕过路径。
官方来源与核验范围
本文以协议规范和客户端官方文档为事实依据。错误文案、重试头和配置字段可能随服务或客户端版本变化；执行前请核对来源，并对日志与请求样例脱敏。
查看技术核验方法