故障排查

先区分：请求没到网关、网关拒绝、没有匹配渠道、上游失败、客户端解析错误。每次只改变一个主要变量，并保存脱敏的失败信息。

控制台打不开

1. 用 docker compose ps 或 docker ps 查看容器状态。
2. 在宿主机访问 http://127.0.0.1:3000/api/status。
3. 本机成功、域名失败时检查 DNS、证书和反向代理。
4. 本机也失败时查看启动日志、监听端口与数据库连接。

容器里的 localhost 不是宿主机或另一个容器，尤其要检查代理、数据库和工作流服务的地址。

401：凭据或登录异常

模型 API 使用网关令牌，不是上游服务商密钥。检查令牌是否完整、是否停用或到期，以及请求头是否正确。

控制台登录异常则检查 HTTPS、可信 Origin、Cookie 和各节点密钥一致性。不要用关闭安全校验来掩盖正式域名配置错误。旧教程的 Gin session 或用户编号请求头不是当前面板鉴权模型。

403 或权限限制

核对用户状态、实际权限、可用分组和令牌限制。管理 API 与模型 API 凭据不同；不要为了排障直接把普通应用账号提升为管理员。

没有可用渠道或模型不可用

按顺序检查：客户端模型名 → 令牌模型限制 → 用户与令牌分组 → 渠道模型与分组 → 渠道启用状态 → 映射目标 → 上游权限。

渠道测试成功但用户调用失败，通常还需要检查用户权益、定价与上述权限交集。模型列表中出现某个名称不保证上游授权可用。

429：限流

确认来自网关还是上游，检查返回错误与命中渠道。根据调用方实际配置做有上限的退避，不要用多个令牌绕过限制。多节点使用独立 Redis 或内存限流时，计数可能按节点分别计算。

400：参数或协议不支持

先用本文档的最小请求验证。移除无关参数，再逐项恢复工具、多模态、推理字段或输出格式。n、长度与时长等字段受网关和上游双重限制，不应通过换格式绕过。

404 / 501：路径错误或功能未实现

检查重复 /v1、模型别名、原生协议路径和插件是否安装。Files、fine-tunes 和 image variations 等占位接口未实现，不是增加额度就能修好。

Gemini :countTokens 与 Claude count_tokens 当前也不能当作可用能力。OpenAPI 出现路径不等于代码已经实现。

普通请求成功，流式失败

检查客户端是否按 SSE 解析、代理是否缓冲、是否启用缓存，以及 CDN 空闲超时。用 curl -N 从宿主机与正式域名分别测试，缩小网络层次。

RELAY_RESPONSE_HEADER_TIMEOUT 只限制等待上游响应头的阶段；STREAMING_TIMEOUT 约束流式无响应时间。两者不能互相替代。

费用或任务结果不符合预期

查看最终日志、命中模型、定价规则、用户权益与任务状态。超时不意味着任务停止；先查任务再重试。计费问题应保留关联标识与脱敏上下文，避免直接修改数据库消耗字段。

寻求帮助时提供

版本或提交、部署方式、数据库类型、路径与模型、失败时间、HTTP 状态、最小复现步骤，以及脱敏错误。移除密钥、Cookie、验证码、完整 DSN 和私有产物访问链接。