排障指南

出问题时最容易犯的错，是同时改五样东西，然后不知道是哪一步修好的。

这一页的顺序是：从最外层往里收，每步只验证一件事。

第一步：确认网络通不通

bash

curl -s -o /dev/null -w "%{http_code}\n" https://api.syuan.org/api/status

返回 200：服务是活的，网络也没问题
返回别的或超时：先换一个入口域名再试

渊站有三个入口，任选一个：

https://api.syuan.org
https://ai.syuan.org
https://aiapi.syuan.org

三个是同一套服务。某个不通就换一个，这是最省事的容灾。

第二步：确认 Key 本身可用

bash

curl https://api.syuan.org/v1/models \
  -H "Authorization: Bearer sk-你的密钥"

结果	结论
返回一堆模型	Key 没问题，往下走
`401`	Key 有问题，去报错怎么读
返回空列表	Key 能用，但账号没分到任何分组

第三步：确认模型名对得上

把上一步返回的 id 跟你在客户端里填的模型名逐字比对。

常见的手滑：

你填的	真实的名字
`gpt-5.5`	✅ 就是这个
`gemini-3.8-flash`	尾部多了空格
`claude-sonnet-5.5`	应该是 `claude-sonnet-5-5`
`deepseek-flash`	✅ 正确

一个小技巧

先别管客户端，用 curl 拿同一个模型名发一次。通了就是客户端的问题，不通就是模型名的问题。这一步能砍掉一半的排查时间。

第四步：确认协议对得上

客户端发的是什么	路径应该是
OpenAI 协议	`/v1/chat/completions`
Claude 原生	`/v1/messages`
Gemini 原生	`/v1beta/models/xxx:generateContent`

请求体格式不能混用。把 OpenAI 的 body 发给 /v1/messages，会得到一个看起来莫名其妙的 500。

第五步：确认超时够长

很多客户端默认超时 30 秒。

生图：通常 30~120 秒
长文本推理：可能 60 秒以上
流式输出：第一句很快，但要保证连接不被掐断

超时表现成「请求失败」或「连接被重置」，很容易被误判成服务挂了。先把超时调到 120 秒再判断。

第六步：分开「慢」和「失败」

这两件事处理方式完全不同：

现象	含义	怎么办
等了很久，最后成功了	只是慢	不用修，或换更快的小模型
等很久，然后报错超时	上游卡住	换分组 / 换模型重试
立刻报错	配置问题	回第二、三、四步

拿到证据再找人

如果自己排查到这里还不行，把这些整理好发给管理员：

入口域名：api.syuan.org
模型：gpt-5.5
分组：Plus
请求体：
{ ... }
错误信息全文（含 request id）：
{ ... }

有了这些，基本能一次定位。只发一句「用不了」，两边都要来回猜。

最后

排不掉也别急。这些问题大多不是你的错——分组调整、上游波动、模型下线，都可能发生。

排障指南 ​

第一步：确认网络通不通 ​

第二步：确认 Key 本身可用 ​

第三步：确认模型名对得上 ​

第四步：确认协议对得上 ​

第五步：确认超时够长 ​

第六步：分开「慢」和「失败」 ​

拿到证据再找人 ​

最后 ​