上游账号接入与维护实操

本页直接回答两个问题：配置账号时到底填什么，以及上线后如何维护。

先给结论

Sub2API 通常不保存上游网站的登录账号和密码。后台“账号”指一份可以调用上游 API 的凭证记录，主要有：

1. 官方 API Key。
2. OAuth 授权得到的 access token / refresh token。
3. Anthropic Setup Token。
4. 第三方兼容上游的 Base URL + API Key。
5. AWS Bedrock 凭证。
6. Google Service Account。

最终用户也不直接使用这些凭证。正确关系是：

上游 API Key / OAuth / 云凭证
             │
             ▼
       Sub2API Account
             │ 加入
             ▼
       Sub2API Group
             │ 绑定
             ▼
      用户的 Sub2API Key
             │
             ▼
    Claude Code / Codex / SDK

我应该选哪一种

你的资源	后台账号类型	需要填什么	维护难度	推荐度
OpenAI/Anthropic/Gemini 官方或协议兼容 API	apikey	Base URL + API Key	低到中	首次部署最推荐
Claude/OpenAI/Gemini 订阅账号	oauth 或 setup-token	通过后台授权或导入 token	高	明确接受风险后使用
第三方 API 中转	通常仍是 apikey	先选兼容平台，再填 Base URL + API Key	中	取决于协议完整度
AWS Bedrock	bedrock	IAM key/secret/session 或 Bedrock API Key、region	中	企业云环境推荐
Google Vertex AI	service_account	Service Account JSON、project、location	中	企业 GCP 环境推荐

不要把 upstream 当成通用创建类型

当前管理后台为 OpenAI、Anthropic、Gemini 第三方兼容服务提供的实际入口是“对应平台 + API Key + 自定义 Base URL”，保存后的账号类型是 apikey。upstream 主要是历史兼容类型；Antigravity 创建界面虽然在内部把该选项称为 upstream，最终也会创建成 apikey。

推荐的起步方案

第一次部署建议：

1 个官方 API Key Account
  → 1 个同平台测试 Group
  → 1 个测试用户
  → 1 个 Sub2API Key

先验证鉴权、流式响应、用量和计费。不要一开始就导入几十个 OAuth 账号、多个代理和复杂模型映射，否则失败时很难确定是哪一层的问题。

方案一：API Key（官方或协议兼容上游）

这是最简单、最稳定的方式。

什么时候使用

• 你在 OpenAI、Anthropic、Gemini AI Studio 或兼容平台拥有正式 API Key。
• 希望按 Token 透明计费。
• 希望减少 token 刷新、订阅窗口和账号风控维护。
• 需要相对明确的商业使用边界。

后台怎么添加

进入：

管理后台 → 账号管理 → 创建账号

填写：

字段	示例	说明
名称	openai-api-prod-01	不要直接写完整 Key
平台	openai	必须与上游协议一致
类型	apikey	官方或兼容 API Key
API Key	sk-...	上游真实 Key
Base URL	官方默认或自定义	官方地址一般使用默认
并发	2 或 3	初次保守设置
优先级	50	数值越小通常越优先
代理	可选	上游访问需要固定出口时绑定

保存后点击“测试账号”，再加入测试分组。

怎么维护

• 每月检查上游账单、余额和限额。
• Key 泄漏或人员变动时在上游轮换。
• 轮换时先创建新账号并测试，再下线旧账号。
• 不要直接覆盖旧 Key 后立即删除旧凭证，先观察请求和费用。
• 对 API Key 设置最小权限、项目隔离和上游预算告警。
• Base URL 变化后重新测试 HTTP、SSE、模型和 usage。

优缺点

优点：稳定、维护简单、计费清晰、适合生产。

缺点：通常按量付费，不会自动利用 Plus/Pro/Max 等订阅额度。

方案二：OAuth 或订阅账号

这类账号利用平台登录授权或订阅额度，但运维复杂度更高。

不要直接填网站密码

正确流程通常是：

管理后台选择平台 OAuth
  → 跳转或生成授权地址
  → 在官方页面登录并授权
  → Sub2API 获得 token
  → 保存 access/refresh token

用户名和密码仍只提交给官方登录页面。Sub2API 维护的是 token，不是密码。

如果某个导入工具要求浏览器 cookie、会话 token 或完整凭证，要单独评估安全性和服务条款，不能与标准 OAuth 等同。

Anthropic

可能使用：

• oauth：包含 profile + inference scope。
• setup-token：偏 inference-only。

Setup Token 不等于账号密码，也不等于普通 API Key。它的权限、刷新和用量查询能力与 OAuth 可能不同。

OpenAI / Codex

OAuth 账号通常保存 access token、refresh token、account ID、plan 等信息。它可能使用 ChatGPT/Codex 专用端点，而不是普通 api.openai.com/v1 API Key 路径。

Gemini / Antigravity / Grok

通过各自 OAuth 流程添加，可能还需要项目 ID、OAuth client secret、quota policy 或账号元数据。

怎么维护

每天或自动监控：

• token 是否接近过期。
• refresh success/failure。
• 401/403 和重新授权需求。
• 订阅窗口用量、reset time 和 quota。
• plan 类型是否变化。
• privacy/训练退出状态。
• 账号是否被临时限流或风控。
• 代理出口是否变化。

出现持续 401 时，不要反复让所有请求触发刷新。先把账号设为不可调度，手动重新授权并测试，再恢复。

风险

• 上游可能限制订阅账号用于 API 中转或多人共享。
• refresh token rotation 失败会使账号失效。
• 同一账号跨地区/代理登录可能触发风控。
• 订阅额度存在窗口和模型限制，不等于无限 API。
• 上游协议可能随客户端版本变化。

部署者必须自行确认服务条款和账号来源。

方案三：第三方兼容上游

可以接入，但“兼容”必须对应 Sub2API 已实现的平台协议，不能把任意 HTTP API 地址填进来。

当前后台应该怎么选

第三方服务实现的协议	创建账号时选择	保存类型	上游至少需要兼容
OpenAI 兼容	OpenAI → API Key	apikey	Bearer 鉴权、模型列表，以及 Responses 或 Chat Completions
Anthropic 兼容	Anthropic → API Key	apikey	x-api-key、Messages 请求、Anthropic SSE/usage
Gemini 原生兼容	Gemini → API Key	apikey	x-goog-api-key、v1beta/models、generateContent/streamGenerateContent
另一套 Antigravity/Sub2API 上游	Antigravity → API Key	apikey	上游的 /antigravity Claude/Gemini 路由

例如，供应商声明兼容 OpenAI：

平台:     OpenAI
账号类型: API Key
Base URL: https://vendor.example.com
API Key:  vendor-key

不要因为供应商提供了 Key，就随意选择平台。平台决定 Sub2API 如何拼 URL、加认证 Header、转换请求和解析流式响应。

Base URL 到底填到哪一层

平台	推荐填写	Sub2API 的典型拼接行为
OpenAI	https://vendor.example.com 或供应商明确给出的版本根地址，如 .../v1、.../v4	自动补 /v1/models、/v1/responses 或 /v1/chat/completions；版本段存在时不会重复补 /v1
Anthropic	API 根地址，不要直接填到 /v1/messages	转发时追加 /v1/messages
Gemini	服务根地址，通常不要带 /v1beta/models	转发时追加 /v1beta/models/{model}:generateContent 或 :streamGenerateContent
Antigravity	上游 Sub2API 的根地址	API Key 账号会先追加 /antigravity，再访问其 Messages/Gemini 路由

以供应商文档为最终依据。如果供应商给的是完整 endpoint，而不是 Base URL，先确认去掉末尾 endpoint 后的根地址；否则可能出现 /v1/v1/messages 或重复 /v1beta/models。

它不等于“100% 能用”

只兼容最简单的文本请求还不够。上线前至少确认：

• 模型列表接口和真实模型名可用。
• 非流式请求、SSE 分块和结束事件格式正确。
• 工具调用、thinking/reasoning、图片等所需能力可用。
• 响应含可解析的 usage；否则本地计费和统计可能不完整。
• 错误码能正确区分鉴权失败、限流、临时故障和参数错误。
• 模型映射后的上游模型存在，价格表中的 billing model 也正确。
• 自定义域名已加入 security.url_allowlist.upstream_hosts；生产环境优先使用 HTTPS。

推荐验证顺序

1. 新建一个只用于验证的账号，不要立即加入生产分组。
2. 执行“同步模型”或“测试账号”，确认 Base URL、Key 和模型。
3. 加入独立测试 Group，创建一枚测试用 Sub2API Key。
4. 分别测试非流式、流式、工具调用和目标模型。
5. 检查 Usage Log 中的 requested model、upstream model、token 和费用。
6. 人为测试错误 Key、未知模型和限流，确认不会造成错误扣费或无限重试。
7. 观察稳定后再加入生产 Group，并保留官方或第二供应商作为故障切换来源。

怎么维护

• 监控供应商 SLA、余额、价格和协议变更。
• 保留多个独立供应商，避免全部账号指向同一上游。
• 对不同供应商使用独立 Group，先分别验证计费。
• Key 轮换时新增账号、测试、切流，再撤销旧 Key。
• Base URL 或模型列表变化后重新执行全套协议验证。
• 不要仅凭“接口兼容”就假设模型、工具、usage 和价格一致。

方案四：AWS Bedrock

账号类型为 bedrock，认证可以是：

• AWS access key ID + secret access key。
• 临时 session token。
• Bedrock API Key 模式。

还需要 region、模型映射和可选的 global inference 设置。

维护建议

• 使用独立 IAM 用户/角色和最小 Bedrock 权限。
• 优先短期凭证或受控 secret rotation。
• 不要使用云账号 root key。
• 监控 region 配额和模型可用区域。
• 轮换 key 时先创建新凭证测试。

方案五：Google Service Account

账号类型为 service_account，用于 Vertex AI。需要 Service Account JSON，以及 project/location 等信息。

维护建议

• Service Account 只授予需要的 Vertex 权限。
• JSON key 进入数据库和备份后按最高敏感级别保护。
• 定期轮换 key，并删除 GCP 中的旧 key。
• 检查项目预算、区域和模型 quota。
• 有条件时使用工作负载身份，减少长期 JSON key。

账号、分组和渠道应该怎么组织

按平台分组

anthropic-api-prod
openai-api-prod
openai-oauth-codex
gemini-api-prod
vertex-prod

不要把 API Key、OAuth、第三方 relay 和不同成本结构全部混在一个大分组里。

按质量和价格分组

openai-official-premium
openai-relay-standard
openai-oauth-internal

这样可以分别配置用户权限、倍率、模型和告警。

命名规则

建议：

平台-来源-套餐/协议-区域-序号

示例：

openai-official-api-us-01
openai-codex-oauth-sg-02
anthropic-setup-token-us-01
gemini-vertex-apac-01

备注中记录购买主体、到期日、代理、上游项目和负责人，不要记录明文密码。

一个真实维护流程

新增账号

1. 在上游准备 API Key/OAuth/云凭证。
2. 如需代理，先创建并测试 Proxy。
3. 创建 Account，初始并发设小。
4. 执行账号测试和额度查询。
5. 加入仅管理员可用的测试 Group。
6. 验证非流式、SSE、工具和费用。
7. 再加入生产 Group。
8. 观察 24 小时错误、延迟和用量。

轮换 API Key

1. 在上游创建新 Key。
2. 在 Sub2API 新建 Account，不直接覆盖旧账号。
3. 加入相同测试 Group 并验证。
4. 加入生产 Group，优先级暂时设低。
5. 观察新账号请求。
6. 把旧账号设为 schedulable=false。
7. 等待活跃请求结束。
8. 在上游撤销旧 Key，再软删除旧账号。

OAuth 重新授权

1. 先把问题账号临时取消调度。
2. 保留错误和旧 token 状态用于排查。
3. 使用后台 Re-Auth/OAuth 流程。
4. 测试 token refresh 和模型请求。
5. 清除相关 401/403 冷却状态。
6. 恢复调度并观察。

账号到期下线

1. 提前设置 expires_at 和到期提醒。
2. 补充替代账号并验证容量。
3. 从高流量 Group 逐步移除。
4. 确认没有 sticky/active request。
5. 撤销上游凭证并保留审计记录。

日常维护周期

每日

• 无可用账号和错误账号数量。
• OAuth refresh failure。
• 429/529、401/403 和代理错误。
• 账号并发、队列和 TTFT。
• 订阅窗口和即将耗尽账号。

每周

• 账号测试与代理延迟。
• 模型白名单、映射和价格。
• 即将到期账号/代理。
• 未使用账号和异常成本。
• 上游账单与本地 account cost。

每月

• API Key、云 key 和 OAuth 权限审查。
• 上游账号负责人和付款状态。
• 凭证轮换计划。
• 备份恢复和数据库访问审计。
• 分组容量、成本和供应商集中度。

你看到的“密码输入框”是什么

账号编辑页面会用 type=password 隐藏 API Key、AWS secret、session token 等敏感字段。这只是一种前端遮罩，不代表这里应该填写网站登录密码。

只有字段明确写着 API Key、Secret Access Key、Token 等时，才填写对应凭证。

最终建议

如果你现在只是准备把系统部署起来：

1. 先使用官方 API Key，不使用账号密码。
2. 一个凭证建立一个 Account。
3. Account 加入一个同平台测试 Group。
4. 用户只使用 Sub2API Key。
5. 流程稳定后，再根据需要引入 OAuth 订阅账号和多个代理。

OAuth 账号不是更高级的 API Key，而是另一套更复杂、风险更高的凭证运维体系。