账号、代理与凭证
账号代表 Sub2API 实际用于访问 AI 上游的身份。账号质量、额度和网络出口直接决定网关可用性。
如果你还在判断应该填 API Key、OAuth 还是“账号密码”，先阅读运维指南中的上游账号池运维。
账号类型
| 类型 | 典型凭证 | 说明 |
|---|---|---|
apikey | Base URL + API Key | 官方 API 或第三方协议兼容 API；当前新建兼容上游的主要类型 |
oauth | access/refresh token | 需要刷新和分布式锁 |
setup-token | Setup Token | Anthropic inference scope |
upstream | Base URL + Key | 历史兼容类型，主要保留给旧 Antigravity 数据和导入；新建时通常使用 apikey |
bedrock | AWS key/secret/session 或 Bedrock key | SigV4 或专用认证 |
service_account | Google JSON key | Vertex AI |
同一平台内，不同账号类型也可能走完全不同的 URL、Header、模型名和流事件。
“第三方兼容上游”的操作方法见上游账号池运维，详细 Base URL 规则仍可查阅上游凭证接入参考。
核心字段
| 字段 | 对调度的影响 |
|---|---|
| platform / type | 决定协议 Service 和认证方式 |
| credentials | 真实上游凭证 |
| extra | 模型映射、上游能力和平台元数据 |
| proxy_id | 指定网络出口 |
| concurrency | 账号最大同时请求数 |
| load_factor | 调整负载计算 |
| priority | 候选排序，数值越小通常越优先 |
| status | active/error/disabled 等持久状态 |
| schedulable | 是否允许调度器选择 |
| expires_at | 凭证或账号业务到期时间 |
| rate_multiplier | 账号成本统计倍率 |
账号还有大量平台专用字段，例如 quota、session window、privacy status、模型白名单、TLS profile 和临时错误状态。
凭证保存与安全
账号 credentials 会持久化到 PostgreSQL JSONB。部署者应按“数据库中保存生产密钥”设计安全措施：
- PostgreSQL 只允许应用和受控运维账号访问。
- 禁止把数据库暴露公网。
- 备份必须加密并限制下载。
- 管理员账号启用 TOTP。
- 日志和错误响应保持凭证脱敏。
- 不给日常分析人员直接查询 accounts.credentials 的权限。
当前部署不能只依赖磁盘加密解决全部问题，因为数据库管理员和逻辑备份仍能读取字段。
OAuth token 刷新
OAuth 账号通常保存 access token、refresh token 和 expires_at。刷新流程需要：
- 判断 token 是否接近到期。
- 获取账号级分布式刷新锁。
- 再次检查是否已被其他实例刷新。
- 调用平台 token endpoint。
- 持久化新 token，并失效相关缓存。
- 释放锁并更新账号状态。
没有锁时，多个请求或实例可能同时使用同一个 refresh token，导致 token rotation 冲突。
持久状态与临时状态
持久状态
管理员禁用、凭证错误、账号到期等写入 PostgreSQL。
临时状态
上游 429、529、内部 500、超时、模型限流等通常写入 Redis，带冷却时间。到期后账号可以自动恢复，不需要管理员手动启用。
排查账号为什么没被调度时，要同时查看两类状态。
代理模型
Proxy 一般包含：
- HTTP/HTTPS/SOCKS 协议和 URL。
- 状态、备注和分组信息。
- 延迟、质量和最近测试结果。
- 到期时间和到期 fallback。
账号绑定代理后，上游 HTTP client 会根据连接池隔离策略复用连接。
连接池隔离
gateway.connection_pool_isolation 支持：
| 值 | 隔离键 | 适用情况 |
|---|---|---|
proxy | 代理 | 少量代理、很多账号，资源更省 |
account | 账号 | 账号出口和会话需要严格隔离 |
account_proxy | 账号 + 代理 | 默认，隔离最细 |
隔离越细，连接池数量和文件描述符越多；隔离越粗，不同账号共享网络连接的概率越高。
代理失败策略
AI 账号关键路径的代理初始化失败应返回错误，不应静默直连。配置中的 proxy_fallback.allow_direct_on_error 只针对更新检查、定价下载等辅助服务，不应该被理解为账号网关直连开关。
这能避免代理配置错误时泄漏服务器真实出口 IP。
TLS 指纹
部分上游对 TLS ClientHello、ALPN 或浏览器特征敏感。系统允许为账号或代理使用 TLS fingerprint profile，配置 GREASE、cipher suite、curve、signature algorithms 等。
不要在没有明确问题时随意复制未知指纹配置。错误的 TLS profile 可能导致握手失败、HTTP/2 不兼容或更明显的异常特征。
账号并发如何工作
账号槽位存储在 Redis ZSET，member 是 request ID，score 使用 Redis 服务器时间。获取脚本会：
- 删除超过 TTL 的槽位。
- 如果 request ID 已存在则刷新。
- 检查 ZCARD 是否低于上限。
- 原子添加槽位并设置 TTL。
进程崩溃后无法执行 release，TTL 会最终清除残留槽位。因此 TTL 应覆盖最长合法请求，但不能长到故障后长期阻塞账号。
添加账号后的验收
- 在后台执行账号测试。
- 查看账号能否获取模型/额度信息。
- 确认代理出口和目标区域。
- 把账号加入测试分组。
- 发送最小非流式请求。
- 测试流式和目标工具能力。
- 核对账号并发、用量和成本统计。
- 最后再加入正式分组。
典型问题
| 现象 | 常见原因 |
|---|---|
| 测试成功但不调度 | 未加入分组、模型不匹配、schedulable=false |
| 周期性 401 | refresh token 竞争或 OAuth 客户端配置错误 |
| 某模型总是失败 | 模型映射、账号白名单、区域能力 |
| 并发远低于配置 | 上游窗口限制、用户槽位、等待策略 |
| 切换代理后仍走旧连接 | 连接池缓存未刷新或实例配置不一致 |
| 代理故障影响全部账号 | 多账号共用同一代理，缺少出口冗余 |