ENTERPRISE TROUBLESHOOTING

企业网关常见问题排查

按员工工具、企业 sub2api 和 RootFlowAI 上游定位登录、认证、权限、余额、模型路由、限流与流式超时问题。

请求链路为:员工工具 → 企业 sub2api → RootFlowAI → 模型服务。排查时先确定失败发生在哪一层,再修改对应配置。

本地停用 Key 后实际返回 HTTP 401、API_KEY_DISABLED、请求 ID 和检查时间,错误发生在企业网关认证层

图 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 已分发给不应持有它的人员,还需要评估轮换。

提示余额不足,但另一边还有余额

逐项核对四处:

  1. sub2api 员工用户余额。
  2. 当前员工 Key 的总额度、5 小时/日/7 日消费窗口和有效期。
  3. RootFlowAI 上游 Key 的额度、状态和权限。
  4. 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。日志中若包含业务输入内容,先按企业制度脱敏。

返回企业团队接入总览,查看日常管理与维护。