AI API 连不上怎么排查？DNS、TLS、中转代理与超时分层诊断指南

“AI API 调用失败”可能表现为域名解析失败、连接超时、TLS 握手错误、代理返回 502、流式响应中途断开，或者只有某个办公网络无法访问。若一开始就反复换 Key、换模型，很容易把网络问题误判成账号问题。

高效排障应遵循两条原则：从底层到上层逐层验证；每一步保存时间、出口环境和请求标识。本文是通用网络方法，不涉及任何模型的易变版本、价格或性能数据。

先画清真实链路

使用 AI API 中转站时，请求通常不止“客户端到模型”一跳。至少列出：

应用 -> 系统代理/企业网关 -> CDN/WAF -> 中转站 -> 上游供应商

服务端调用和浏览器调用也可能走不同链路。排查前记录运行位置、目标 baseURL、是否配置 HTTP_PROXY、是否经过容器或 Serverless 出口、故障开始时间及影响范围。不要在截图里暴露 API Key。

第一层：DNS 解析

先确认故障机器实际解析到了什么，而不是在个人电脑上查询后就下结论。

dig +short api.example.com
nslookup api.example.com

如果不同网络返回不同结果，检查本地缓存、公司内网 DNS、分流规则和域名是否刚发生变更。仅能解析不代表地址可访问；同一个域名也可能返回多条地址，因此要记录每个地址的结果。

常见误区是直接把 IP 写进 baseURL。HTTPS 证书通常校验域名，手工替换 IP 可能制造新的证书错误。需要定向测试时，应保留原域名并用客户端解析覆盖能力完成。

第二层：TCP 与 TLS

DNS 正常后，验证端口连接与 TLS 握手。curl -v 能同时展示解析、连接、证书和 HTTP 阶段：

curl -v --connect-timeout 5 \
  https://api.example.com/v1/models \
  -H "Authorization: Bearer $AI_API_KEY"

生产排障日志应删除认证头。若连接超时，优先检查出口防火墙、路由和端口；若 TLS 失败，检查系统时间、证书链、SNI、企业 HTTPS 检查代理和运行时信任库。不要用关闭证书校验作为正式修复，它只适合在受控环境里帮助定位，而且测试后必须恢复。

可用以下命令查看服务端返回的证书链：

openssl s_client \
  -connect api.example.com:443 \
  -servername api.example.com </dev/null

-servername 很重要，因为同一地址可能承载多个 HTTPS 域名。

第三层：HTTP 与代理

能完成 TLS 握手后，再看 HTTP 状态、响应头和正文格式。区分谁返回了错误：企业代理、CDN、中转站还是上游。保留响应中的请求 ID、网关标识和时间信息，但对 Cookie 与鉴权字段脱敏。

检查环境变量是否意外影响请求：

env | grep -iE '^(http|https|all|no)_proxy='

NO_PROXY 配置错误可能让内网域名绕到公网，也可能让本应经过代理的请求直连失败。容器、进程管理器和 CI 环境中的变量与交互终端不一定相同，应在真实运行进程中核对。

如果健康检查成功而生成接口失败，比较请求体大小、方法、路径、超时和 WAF 规则。不要把 /v1/models 成功视为所有接口都正常。

第四层：应用超时与连接池

应用报告超时，不代表网络在同一阶段失败。至少拆分：DNS、连接、TLS、首字节、流式空闲和总任务时限。AI 生成可能长时间保持一个响应，因此普通 REST 接口的单一超时配置往往不够表达真实需求。

Node.js 中可以记录阶段与总耗时，并在用户取消时传播 AbortSignal：

const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 60_000);

try {
  const res = await fetch(process.env.AI_BASE_URL + "/chat/completions", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      authorization: `Bearer ${process.env.AI_API_KEY}`,
    },
    body: JSON.stringify(payload),
    signal: controller.signal,
  });
  console.log(res.status, res.headers.get("x-request-id"));
} finally {
  clearTimeout(timer);
}

这里的时限只是示例，不应直接复制到所有业务。短分类和长视频任务应采用不同策略，异步任务还需要状态查询与回调机制。

第五层：SSE 流式响应

流式接口要额外检查：响应类型是否正确、代理是否缓冲、是否定期收到数据、结束标记是否完整、断开由哪一端发起。可以用禁止客户端缓冲的方式观察原始分片：

curl -N https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-model","stream":true,"messages":[{"role":"user","content":"ping"}]}'

若非流式正常而流式异常，重点检查 CDN 缓冲、反向代理读取超时、压缩、连接复用和空闲连接策略。重复重连前要确认接口是否支持安全续传，否则可能产生两次生成和两笔费用。

做一张最小对照矩阵

不要一次改变多个变量。用相同请求依次比较：

• 本地网络与服务器网络
• 官方入口与候选中转入口
• IPv4 与 IPv6 路径
• 直连与企业代理
• 非流式与流式
• 小请求与真实大小请求

每次只改变一个条件，记录时间、解析地址、状态、阶段耗时和请求号。对照矩阵通常比“再试几次”更快找到故障边界。

联系中转站支持前准备什么

提供脱敏后的 request_id、发生时间与时区、接口路径、状态码、是否流式、客户端地区、可复现步骤和 curl -v 的关键阶段。不要发送完整 Key、用户 Prompt、身份证明或整个环境变量文件。供应商若无法根据请求号定位，也应计入生产选型风险。

总结

AI API 网络排障应从 DNS、连接、TLS、HTTP、应用超时到流式传输逐层推进。先判断失败发生在哪一层，再决定改 DNS、证书、代理、超时还是中转路由，能够避免无效重试和盲目换模型。

如果需要准备多条备用 API 路径，可前往 openairouter.net 查看中转站对比与排行榜。上线前用同一套诊断脚本测试候选平台，并把请求追踪、流式稳定性与技术支持能力一起纳入评分。