ENTERPRISE TROUBLESHOOTING
企业网关常见问题排查
按员工工具、企业 sub2api 和 RootFlowAI 上游定位登录、认证、权限、余额、模型路由、限流与流式超时问题。
请求链路为:员工工具 → 企业 sub2api → RootFlowAI → 模型服务。排查时先确定失败发生在哪一层,再修改对应配置。

图 S16:本地网关对已停用 Key 的实际响应,整理为脱敏检查记录。401 / API_KEY_DISABLED 表示先检查员工 Key 状态;本次请求在企业网关认证层被拒绝,没有发往 RootFlowAI。保留时间和返回的 request ID,方便定位日志。查看清晰原图。
按现象快速定位
| 现象 | 先检查什么 | 谁处理 |
|---|---|---|
| 企业网站打不开 | DNS、证书、Nginx、容器健康和入站网络 | 企业管理员或运维 |
| 登录失败 | 企业域名、员工邮箱、账号状态和登录密码 | 员工与企业管理员 |
| 没有可选分组 | 员工分组授权、分组是否启用、是否选错订阅类型 | 企业管理员 |
401 或认证失败 | 员工 Key、认证方式、有效期;再查上游 Key | 企业管理员 |
403 或权限不足 | 用户状态、分组授权、模型白名单、上游权限 | 企业管理员 |
| 余额或额度不足 | 员工余额、Key 限额、消费窗口、RootFlowAI 上游余额 | 企业管理员 |
404、模型不存在或协议不匹配 | 企业 API 地址、模型 ID、所选平台、实际请求端点 | 企业管理员 |
429、并发或限流 | 员工并发与 RPM、上游账号限制及整体上游容量 | 企业管理员 |
无可用账号或 503 | 账号启用状态、所属分组、冷却与上游可用性 | 企业管理员 |
502、504、流式中断 | 反向代理、出站连接、超时和流式缓冲 | 企业运维 |
相同状态码可能来自不同层级。结合错误正文、发生时间和日志判断,不要只凭状态码认定 RootFlowAI 或企业网关故障。
企业平台打不开
在服务器运行:
cd /opt/company-ai
docker compose -f docker-compose.local.yml ps
docker compose -f docker-compose.local.yml logs --tail=100 sub2api
curl -I http://127.0.0.1:8080
sudo nginx -t本机应用可访问、企业域名不可访问时,优先检查 Nginx、证书、DNS 和防火墙。本机应用也不可访问时,先查看应用和数据库启动日志。
数据库刚恢复时可能需要等待就绪;如果出现认证失败、迁移失败、磁盘已满等明确错误,应按日志处理。不要通过删除数据目录来“重新初始化”。
员工登录成功,但创建 Key 时没有分组
检查该员工是否已获得专属分组授权,以及分组是否处于启用状态。使用本教程余额模式时,确认分组订阅类型为标准 standard。
订阅分组需要相应订阅授权,仅增加用户余额不能替代订阅。初次配置建议回到员工与预算教程核对授权,不要同时混用两种模式排查。
如何区分员工 Key 错误与上游 Key 错误
员工工具使用企业平台域名和员工 Key;sub2api 上游账号使用 RootFlowAI 地址和上游 Key。
先检查员工 Key 是否被停用、过期、选错分组或达到限制。若这些正常,再由管理员检查上游账号中的 RootFlowAI Key、模型权限和额度。
员工不需要把上游 Key 填到工具里。发现两套 Key 用反时,应修正配置;如果上游 Key 已分发给不应持有它的人员,还需要评估轮换。
提示余额不足,但另一边还有余额
逐项核对四处:
- sub2api 员工用户余额。
- 当前员工 Key 的总额度、5 小时/日/7 日消费窗口和有效期。
- RootFlowAI 上游 Key 的额度、状态和权限。
- RootFlowAI 企业账户的可用余额。
给员工增加内部余额,不会增加上游余额;给 RootFlowAI 账户补充余额,也不会自动给员工增加内部预算。以错误实际发生的层级处理,不要反复创建 Key。
模型列表里有模型,但调用失败
模型列表只能帮助确认配置范围,还需检查实际请求协议和权限:
- Claude Code 对应 Messages;Codex 对应 Responses。
- Gemini 原生路径与 OpenAI Chat Completions 不是同一个端点。
- 模型 ID 必须与上游接受的名称一致,不能把显示名称当作模型 ID。
- 复合分组需要有该平台的可用上游账号,别名需要正确路由。
- 路由预览成功不代表已有上游权限或已配置正确价格。
先用一个平台、一个准确模型完成短请求,再扩展其他平台。地址填写见接入 RootFlowAI。
为什么会出现重复路径
上游账号 Base URL 和员工客户端 Base URL 的用途不同。按接入教程填写上游根地址,按员工快速开始填写工具地址。
常见错误包括:把 /login 当作 API 路径、在 Anthropic 根地址后又手动追加 /v1、将完整 /v1/responses 填进会自动补路径的客户端。
核对实际请求地址时,隐藏 Key、认证头和含凭证的查询参数。无需为了排查而把所有安全校验关闭。
请求能返回,但流式卡住或经常超时
检查企业网关前的 Nginx、CDN、WAF 和负载均衡:
- 是否对流式接口启用了响应缓冲或缓存。
- 是否存在比应用更短的读取或空闲超时。
- 使用 WebSocket 的客户端是否获得正确升级转发。
- 企业服务器到 RootFlowAI 的连接是否稳定。
先在同一网络和相同模型下对比短请求与流式请求,再调整相关超时。长任务超时不应直接触发无限重试,部分任务可能已经执行并产生上游消耗。
为什么内部费用与 RootFlowAI 不一致
核对时间范围、时区、模型价格、分组倍率、缓存单价和记录延迟。sub2api 的内部计价规则与 RootFlowAI 实际采购计价不一定相同。
员工请求可能经过网关重试或协议转换,不能只按成功请求数推算实际费用。需要精确分摊时,应保留请求 ID、usage 和价格依据,按同一口径对账。
向谁提供哪些信息
企业员工先联系内部管理员。管理员确认问题位于 RootFlowAI 上游时,可通过 RootFlowAI 服务支持提交:
- 发生时间和时区。
- sub2api 版本、所用协议和模型 ID。
- 脱敏错误正文、HTTP 状态码和请求 ID。
- 是否只有某名员工、某个 Key 或某个模型失败。
- 已检查的余额、授权、地址和复现条件。
不要提交完整 API Key、登录密码、数据库密码或未经处理的 .env。日志中若包含业务输入内容,先按企业制度脱敏。