Runbook：401、403 与 OAuth 失效

401/403 可能发生在 Sub2API 入口，也可能来自上游。两者处理方式完全不同，必须先看错误的 phase、owner、source 和 account_id。

如果是管理员网页登录失败，先确认数据库中的管理员记录。部署变量 ADMIN_PASSWORD 只参与首次初始化，容器重启后不会覆盖 users.password_hash，详见启动、配置与事实来源。

入口 401/403

表现：请求通常还没有 account_id 或 upstream endpoint。

检查：

客户端是否传入 Sub2API Key，而不是上游 Key。
Authorization 格式和 Base URL 是否指向正确实例。
Key 是否禁用、过期、删除或 IP 受限。
用户是否 active，是否还有余额/订阅/平台 quota。
Key 绑定 Group 和用户授权是否一致。
多实例 API Key L1/L2 缓存是否已失效。

处理：修正客户端或用户/Key 配置。不要刷新上游 OAuth，因为请求尚未到达上游。

上游 401/403：API Key 账号

表现：错误详情有 account_id、upstream endpoint 和 provider/upstream 归因。

检查：

Key 是否在供应商后台被撤销、过期或限制项目。
Base URL 是否属于该 Key 的服务。
账号级 Header override 是否覆盖了 Authorization/x-api-key。
URL allowlist、Proxy 或 WAF 是否返回伪装的 403。
模型是否需要额外项目权限。

处理流程：关闭调度 → 在供应商侧验证/新建 Key → 新账号测试 → 灰度加入生产 → 撤销旧 Key。

OAuth 401/403

检查：

access token 过期时间。
refresh token 是否存在、是否 rotation 失效。
account/project ID 和 plan 是否变化。
多实例 Redis 锁是否工作。
Proxy 地区、设备或上游风控是否变化。
最近刷新日志和 job heartbeat。

推荐动作：

schedulable=false，防止持续失败。
保存第一次失败的错误和 token 元数据，禁止复制明文 token 到工单。
尝试后台 Refresh；失败时走 Re-Auth/OAuth。
账号测试通过后使用 Recover State，使旧 token 缓存失效。
恢复调度并观察一个刷新周期。

403 不一定是凭证错误

还可能是：

模型/区域无权限。
上游内容策略或账户风控。
Cloudflare/WAF/Proxy 拒绝。
privacy/训练退出要求不满足。
客户端类型或最低版本策略。
URL allowlist 拒绝自定义上游。

看上游响应 body、request ID 和 error owner 后再决定是否换 Key。

批量 401 的处理

如果多个账号同时 401：

先查共同 Base URL、Proxy、上游项目和最近批量变更。
不要逐个清错制造请求风暴。
保留一两个账号做隔离测试，其余先摘流。
若是共享 OAuth client/secret 变化，先修复全局配置。
若疑似泄漏，按安全事件轮换并审计访问。

验收

新 token/Key 完成真实请求。
旧凭证已撤销或明确保留到切换结束。
token refresh heartbeat 正常。
账号没有立即再次进入 error/temp unscheduled。
错误日志中不再出现同一 account 的上游 401/403。