上游账号池运维

账号池是 Sub2API 最需要持续维护的资源。账号“测试成功”只说明当时能完成测试请求，不代表它在所有 Group、模型和流量条件下都可用。

接入方式怎么选

手上的资源	后台选择	主要维护项
官方或兼容 API	对应平台 → API Key	Key 轮换、余额、Base URL、usage
Claude/Codex/Gemini 订阅授权	OAuth/Setup Token	过期、刷新、账号风控、订阅窗口
AWS Bedrock	Bedrock	IAM、region、临时凭证、模型权限
Google Vertex	Service Account	JSON key、project、location、quota
Antigravity/Sub2API 上游	Antigravity → API Key	上游根地址、模型映射、级联故障

第三方兼容服务通常也保存为 apikey：先按接口协议选择 OpenAI、Anthropic 或 Gemini，再填写 Base URL 和 API Key。不要根据模型品牌选平台，例如“通过 OpenAI 协议提供 Gemini 模型”仍应选择 OpenAI。

更完整的 Base URL 拼接规则可参阅上游凭证接入参考。

账号状态不是一个开关

排障时要同时看这些维度：

状态	含义	常见来源	处理方式
status=active	持久状态正常	管理员或自动恢复	继续检查下面的运行时状态
status=error	持久错误	凭证或不可恢复错误	修复根因、测试、再恢复
schedulable=false	手动不参与调度	摘流、维护、到期	确认后手动恢复
temp unschedulable	暂时不可调度	自定义错误规则、刷新失败等	等待到期或修复后清除
rate limited	限流冷却	上游 429/窗口限制	等 reset，谨慎手动清除
overloaded	上游过载	529/503 或平台信号	让调度切换，观察恢复
quota auto-pause	用量达到阈值	5h/7d 等窗口	等窗口滚动或调整策略

一个账号只有在持久状态、手动调度开关和运行时状态都允许时，才是可用候选。

开发者需要修改错误策略、恢复按钮或调度过滤时，先读账号状态机与恢复语义；其中列出了每个动作实际清理的数据库和 Redis 状态。

新账号上线流程

1. 记录来源、负责人、付款主体、到期时间和上游项目。
2. 创建账号，初始并发保守设置为 1～3。
3. 同步模型或检查可用模型。
4. 执行账号测试，记录测试模型和时间。
5. 加入测试 Group，验证真实客户端协议。
6. 核对 requested/upstream/billing model 和 usage。
7. 加入生产 Group，但先设置较低优先级或较小流量。
8. 观察 24 小时的 401、429、TTFT、成功率和费用。
9. 达到预期后再逐步提高容量。

API Key 轮换

推荐“双账号切换”，不要直接覆盖后立即撤销旧 Key：

上游创建新 Key
  → Sub2API 新建 Account
  → 测试 Group 验证
  → 加入生产池并观察
  → 旧 Account 关闭调度
  → 等活跃请求结束
  → 上游撤销旧 Key
  → 删除或归档旧 Account

这样出现 Base URL、权限或 Key 错误时可以快速恢复旧账号。

OAuth 与 Setup Token

Sub2API 保存的是 token，不是网站登录密码。日常检查：

• access token 到期时间。
• refresh token 是否能够刷新。
• 最近 401/403 是否集中在某个账号。
• 上游订阅 plan、5h/7d 或日窗口剩余量。
• 账号使用的 Proxy 地区和登录地区是否稳定。
• 多实例是否通过共享 Redis 锁避免并发刷新。

持续 401 时先关闭该账号调度，再重新授权。不要让生产流量不断触发失败刷新。

手动恢复动作怎样选

后台提供的动作作用不同：

• 测试账号：发起真实测试；成功后会尝试恢复可恢复的运行时状态。
• Recover State：统一清理可恢复状态，并使 OAuth token 缓存失效。
• Clear Error：清除持久错误；OAuth 账号同时失效 token 缓存。
• Clear Rate Limit：清除账号级限流、overload、模型限流、部分 quota scope 和临时摘除；不会增加真实上游额度。
• Clear Temp Unschedulable：清临时摘除及模型级限流，不清持久 error、人工摘流和账号级限流。
• Refresh：刷新 OAuth 凭证；不适用于普通 API Key。
• Schedulable：人工控制是否进入调度池。

推荐恢复顺序：

先修复 Key/OAuth/Proxy/模型
  → 测试账号
  → 必要时 Recover State
  → 确认状态和可用模型
  → 恢复 schedulable
  → 在测试 Group 发真实请求

批量操作的风险

批量更新账号、清错、刷新和修改凭证会同时改变账号池容量。操作前：

• 用筛选条件导出受影响账号 ID。
• 确认至少保留一组健康账号。
• 分批执行，先 5%～10%。
• 观察错误率、切换率和队列。
• 准备原配置导出和回退列表。

不要同时批量改 Base URL、模型映射、并发和代理，否则出现问题时无法归因。

到期与下线

账号设置 expires_at 并不能替代负责人制度。至少提前 7 天告警：

1. 补充替代容量。
2. 验证替代账号和价格。
3. 将到期账号关闭调度。
4. 等待活跃和粘性会话自然迁移。
5. 撤销上游凭证。
6. 保留必要的用量和变更记录。