故障排查

故障排查

错误码速查

错误响应格式详见 错误码与重试。

HTTP	错误码	含义	排查方向
401	UNAUTHORIZED	认证失败	检查 API Key 是否正确、是否已删除
403	ACCESS_DENIED	IP 被封禁或角色权限不足	检查 IP 黑名单；USER 角色访问管理端点需 ADMIN 授权
403	ACCESS_DENIED	应用未授权该渠道	检查 Key 绑定的应用渠道授权
404	NOT_FOUND	路径或资源不存在	核对端点路径（Anthropic 为 /anthropic/v1/messages）
429	RATE_LIMIT_EXCEEDED	限流	降低请求频率或调整限流配置
500	INTERNAL_ERROR	网关内部异常	记录日志中的 traceId 反馈
502	UPSTREAM_ERROR 等错误类型名	上游不可用	检查上游 Provider Key 健康状态、网络
502	MODEL_NOT_FOUND	上游无此模型	检查 model 名拼写、是否已配置该模型渠道（触发自动废弃检测）
503	UPSTREAM_ERROR	熔断器 OPEN	等待熔断恢复，或强制恢复端点

常见问题

401 认证失败

• OpenAI 端点：确认 Authorization: Bearer sk-xxx 格式正确
• Anthropic 端点：确认使用 x-api-key 头（非 Bearer）+ anthropic-version: 2023-06-01
• Key 是否已删除或禁用：在 密钥管理 查询

502 且错误码为 MODEL_NOT_FOUND（模型不存在）

• 检查请求的 model 字段拼写（如 gpt-4o 而非 gpt4o）
• 确认管理后台已配置该模型的渠道（见 渠道管理）
• 确认 Key 绑定的应用已授权访问该模型所在渠道
• 该错误会被模型生命周期自动探测捕获，多次出现后模型实例会被标记 DEPRECATED

429 限流

网关对 API Key 级做令牌桶限流。降低请求频率，或联系管理员调整限流配置。

502 上游不可用

• 在 渠道管理 检查渠道健康状态：POST /api/v1/channels/{id}/health-check
• 确认上游 Provider Key 未过期、未失效
• 检查网关到上游的网络连通性
• 配置多个上游 Key + 故障转移（FAIL_OVER 策略）可提升可用性，见 容灾方案

调用很慢

• 检查是否启用了流式（stream: true），首 token 延迟更低
• 检查应用级超时配置（Application.timeout）
• 查看转移事件流是否有频繁故障转移：GET /api/v1/resilience/events

启动失败

端口被占用

修改 SERVER_PORT 环境变量，或释放占用 8080 的进程。

数据库连接失败

• PostgreSQL 模式：检查 DB_URL / DB_USERNAME / DB_PASSWORD，确认库 llm_gateway 已创建
• 详见 安装部署

Flyway 迁移失败

• 检查数据库版本兼容性（PostgreSQL 14+）
• 查看启动日志的 Flyway 错误，常见为手动修改过表结构与迁移脚本冲突