Claude Code、Codex、Gemini CLI 和 Grok 等 AI 编程工具越来越多地采用产品订阅、OAuth 登录或专属客户端协议，而不是只提供传统的按量 API Key。对于拥有多份合法订阅或多种上游凭据的个人与团队，真正困难的往往不是单次调用，而是如何管理账号状态、分配配额、控制并发、保持会话连续，并向不同使用者发放可撤销、可计量的访问凭据。
Sub2API 是一套面向这一场景的开源 AI API 网关平台。它把上游订阅账号、OAuth 凭据、API Key 或兼容上游组织成账号池，再向下游用户签发平台 API Key；请求进入后，系统负责鉴权、账号调度、粘性会话、并发与速率限制、协议适配、用量记录和计费。简单地说，它试图把分散的“订阅配额”变成可统一治理的 API 能力。
截至 2026 年 8 月 13 日，GitHub API 快照显示该项目约有 3.68 万个 Star、7590 多个 Fork，采用 LGPL-3.0-or-later 许可证；当时最新正式 Release 为同日发布的 v0.1.176。该版本新增 Grok 4.6、分组逐模型定价、长上下文阶梯开关和 /x_search，并修复了多实例备份、定价缓存、Responses 探测与 Realtime 音频计费等问题。动态数据只代表核对时状态，不构成稳定性或安全保证。
Sub2API 是什么？
Sub2API 的官方定位是“用于订阅配额分发的 AI API 网关平台”。管理员先添加自己有权使用的上游账号或凭据，再创建分组、定价和调度规则。普通用户通过平台获得 API Key，把 Claude Code、Codex、Gemini CLI 或兼容客户端的 Base URL 指向 Sub2API，便可在权限和额度范围内调用对应能力。
它与通用模型聚合网关有明显区别。传统网关的重点通常是管理多家厂商的官方 API Key，并把模型路由到不同渠道；Sub2API 更关注产品订阅账号的配额池化，以及订阅协议、OAuth 生命周期、账号可用窗口和客户端会话的处理。当然，它也支持 API Key、透传上游、AWS Bedrock 和 Google Service Account 等账号类型，因此并不局限于 OAuth 订阅。
这种能力的技术价值很直接，但授权边界也更敏感。项目 README 明确提醒：使用方式可能违反 Anthropic 等上游服务商的服务条款，存在账号封禁、服务中断和数据损失风险；项目仅供技术学习与研究，开发者也未授权任何个人或组织基于项目开展商业运营。部署者必须先确认订阅是否允许自动化调用、共享、转售或转换为 API，不能把开源软件提供的功能理解为上游授权。
核心工作流程
一次典型请求会经过以下环节：
- 下游鉴权：系统验证平台 API Key、用户状态、分组权限、余额或订阅配额。
- 请求识别：根据端点、模型与可选强制平台信息，判断目标平台和所需能力。
- 准入控制：检查用户并发、账号并发、RPM、Token 速率、风险控制及可选内容审计。
- 账号调度：从可用账号池中选出账号，考虑健康度、负载、配额窗口与粘性会话。
- 协议转发：补充或转换请求字段，刷新 OAuth 凭据，并向实际上游发送请求。
- 响应与计费：转发流式或非流式响应，记录 Token、缓存、模型、账号、延迟和费用。
这种设计将上游高敏感凭据留在服务器端，下游只持有受限的平台代理 Key。管理员可以撤销某个用户的 Key，而无需轮换整个账号池；也可以下线异常账号，而不要求所有客户端改配置。
支持的平台与账号类型
当前源码定义了 Anthropic、OpenAI、Gemini、Antigravity、Grok 和 Composite 六类平台。它们大致对应 Claude/Claude Code、OpenAI/Codex、Google Gemini/Gemini CLI、Antigravity 提供的 Claude 与 Gemini 能力、xAI Grok，以及可以按模型解析到多个实际平台的复合分组。
账号层支持多种凭据形式：
- OAuth：保存并刷新授权令牌，适用于相应产品账号。
- Setup Token：面向特定推理授权流程的凭据类型。
- API Key：接入供应商提供的标准 API 凭据。
- Upstream：通过 Base URL 与 API Key 转发到兼容上游。
- Bedrock：通过 AWS SigV4 或支持的 API Key 方式连接 Bedrock。
- Service Account：使用 Google Service Account 连接 Vertex AI 等服务。
并非每种账号类型都适用于每个平台，也不是所有上游能力都能互换。添加账号时要按实际授权方式选择类型，并使用测试功能确认模型列表、配额、流式响应和工具调用，而不能只看“账号状态正常”。
API 协议与客户端兼容
Sub2API 提供 Anthropic Messages、OpenAI Responses、OpenAI Chat Completions 和 Gemini 原生风格等入口，并包含多种协议转换代码。这样，Claude Code、Codex、Gemini CLI 以及兼容这些协议的客户端可以使用平台生成的 Key。复合分组还可以根据模型名称把请求解析到 Anthropic、OpenAI、Gemini、Antigravity 或 Grok 等目标。
协议转换最容易在高级功能上出现差异。思考内容、工具调用配对、内置搜索、图片与文件块、缓存字段、流式事件生命周期、错误码和 Token 统计都不是简单改字段名。项目为 Chat Completions、Responses 与 Anthropic 之间维护了大量转换和测试，但生产接入仍应覆盖真实工作负载，包括多轮工具调用、长上下文、流式中断和错误重试。
截至本文核对时，官方中文 README 特别注明 Sora 相关功能因上游接入和媒体链路问题暂不可用。即使界面、路由或配置中仍能看到相关选项，也不应写入服务承诺。功能恢复后还需重新核对 Release Notes 与媒体存储安全配置。
账号池与智能调度
负载感知的账号选择
多个账号加入同一分组后，调度器会根据账号状态、可调度标记、当前并发、配额窗口、错误与限流信息选取上游。账号达到并发或速率上限时，请求可以等待、切换候选账号或返回受控错误。管理员能够查看账号用量、容量、今日统计和测试结果，并执行批量编辑与重新授权。
调度不能凭空创造容量。订阅套餐的动态限制、地区限制、上游风控与服务变更都可能让历史经验失效。账号池规模越大，凭据管理和关联风控越复杂。应使用有明确授权的独立账号，控制重试与切换频率，并监控实际配额，而不是依赖界面中的静态套餐名称。
粘性会话
AI 编程会话通常包含缓存、服务端状态、思考签名或与特定账号有关的上下文。Sub2API 的粘性会话会尽量把同一会话连续路由到相同账号，从而改善上下文一致性和缓存命中。若绑定账号不可用，系统可以按策略切换，并清理不能跨账号复用的字段，例如 Gemini 的某些 thought signature。
官方文档提醒，Nginx 默认会丢弃带下划线的请求头，例如 session_id，这会破坏 Codex 等客户端的粘性路由。使用 Nginx 反向代理时，需要在 http 块启用：
underscores_in_headers on;修改后应通过实际客户端验证同一会话是否稳定命中预期账号。不要仅根据 HTTP 200 判断粘性功能正常。
复合分组
Composite Group 是管理端的跨平台路由层。一个下游 Key 可以绑定复合分组，系统再按请求模型解析到具体平台和分组。它适合让用户通过一把 Key 访问 Claude、GPT、Gemini 与 Grok 等不同模型，同时保持统一的额度与日志入口。
复合分组也增加了定价和权限复杂度。管理员需要为每个模型建立明确的目标平台、定价来源和允许范围，处理名称冲突，并防止未知模型落到错误渠道。最新版本提供分组逐模型定价和长上下文阶梯开关，就是为了避免统一倍率掩盖不同平台的真实成本。
并发、速率和配额控制
Sub2API 同时控制用户侧与账号侧资源。用户并发可以防止单个 Key 占满平台容量；账号并发则保护上游订阅不被瞬时请求压垮。RPM 与 Token 速率限制用于约束请求频率和吞吐，平台配额、余额与分组规则进一步决定请求能否进入调度。
限流参数应来自负载测试和上游允许范围。设置过松会触发上游风控或造成账号拥塞，设置过紧则让闲置容量无法使用。流式请求占用并发槽的时间远长于普通 HTTP 调用，长上下文和工具链也会扩大差异，因此不能只用“每分钟请求数”估算容量。
精确计费与用量分析
平台记录输入、输出、缓存、模型、用户、账号和请求耗时等维度，并按定价规则计算费用。管理员可以查看全局看板、用户和分组分布、Token 趋势、错误请求与账号统计；普通用户可以查看自己的 Key、使用明细、余额、订阅和可用渠道。
计费链可能包含内置价格、渠道价格、分组逐模型价格、倍率、长上下文阶梯和按次能力。v0.1.176 修复了多个价格缓存和零计费边界，说明这部分需要持续测试。内部账目应定期与上游用量抽样核对，价格变更要保留生效时间，不宜把网关估算当作供应商最终账单。
支付、订阅与简易模式
项目内置 EasyPay、支付宝官方、微信支付、Stripe 和 Airwallex 等支付相关实现，并提供充值、套餐、订单、兑换码、推广与余额管理界面。技术上可以构建从注册、购买到 API 调用的完整流程，但官方 README 同时明确表示没有授权商业化运营。任何公开收费行为都必须先解决项目声明、上游服务条款、支付商户协议、税务、退款、实名和消费者权益等问题。
对于个人或内部团队，Sub2API 提供“简易模式”，可以隐藏 SaaS 相关功能并跳过计费流程。若目标只是集中管理自己有权使用的账号，简易模式通常能降低攻击面和运维复杂度。没有业务需求时，不应仅因为功能存在就启用注册、支付、推广或公开购买页面。
管理后台与运维能力
Vue 管理后台覆盖用户、API Key、分组、账号、代理、订阅、兑换码、用量、渠道监控、审计日志、风险控制、提示词审计、支付订单和系统设置。用户端则提供看板、Key 管理、用量、订阅、订单与个人资料。移动端生态项目还可连接多个 Sub2API 后端进行基础管理。
后台支持检测更新、应用新版本和回滚。在线升级方便，但生产环境仍应固定版本、备份数据库与配置，并在预发布实例验证迁移。可选的 datamanagementd 通过宿主机 Unix Socket 提供数据管理能力，权限明显高于普通容器；只有确有需要时才应部署，并严格限制 Socket 所有权和可访问容器。
技术架构
后端采用 Go、Gin 和 Ent，前端使用 Vue 3、Vite 与 Tailwind CSS。PostgreSQL 15+ 保存用户、账号、分组、Key、订单和用量等持久数据，Redis 7+ 负责会话、缓存、调度协同、限流与队列相关状态。构建后的前端可由后端提供，因此一个应用入口即可承载控制台与网关 API。
账号凭据和 TOTP 种子属于高敏感数据。项目通过 JWT 处理登录状态，并要求稳定的 TOTP 加密密钥；若这些密钥在重启后变化，用户会话或双因素认证数据可能失效。多实例必须共享一致配置，同时保证 PostgreSQL、Redis 与备份只在受控网络和权限下可访问。
Docker Compose 部署
官方提供 Linux 安装脚本、Docker Compose、Apple container 和源码编译等方式。对大多数服务器，Compose 会同时部署 Sub2API、PostgreSQL 与 Redis。官方推荐使用本地目录持久化版本，便于整体备份和迁移。
mkdir -p sub2api-deploy
cd sub2api-deploy
# 下载部署准备脚本前先阅读其内容，再在受控环境执行
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh -o docker-deploy.sh
less docker-deploy.sh
bash docker-deploy.sh
docker compose up -d
docker compose ps
docker compose logs --tail=200 sub2api准备脚本会下载 Compose 与环境变量示例，生成 JWT_SECRET、TOTP_ENCRYPTION_KEY 和 PostgreSQL 密码，并创建持久化目录。自动生成并不代表可以忽略保管：应把密钥放入权限受限的配置或密钥系统，避免进入 Git、聊天记录、工单和容器镜像。
如果手动部署，至少需要设置强随机的数据库密码、JWT 密钥和 TOTP 加密密钥，并可选设置初始管理员邮箱、密码和服务端口。服务默认使用 8080 端口。首次初始化应在本机、VPN 或防火墙限制下完成，不要先公开管理入口再创建管理员。
首次配置建议
- 选择运行模式：个人或内部使用优先评估简易模式，关闭不需要的注册、支付和推广功能。
- 创建管理员：使用独立高强度密码，启用受支持的双因素或通行密钥能力，并限制管理入口。
- 添加单个测试账号：只使用明确有权接入的凭据，先验证授权刷新、模型和配额查询。
- 建立测试分组：配置平台、允许模型、定价、并发和速率限制，避免直接使用宽松默认值。
- 签发受限 Key：为测试用户设置有限额度和权限，通过真实客户端进行端到端调用。
- 核对会话与账目：检查粘性账号、Token、缓存、费用和错误日志是否符合预期。
- 逐步扩容：再加入其他账号和复合分组，模拟限流、掉线、令牌过期与故障切换。
生产安全要点
保护凭据与数据库
上游 OAuth Token、API Key、Service Account、支付密钥、JWT Secret 和 TOTP 加密密钥都应按生产密钥管理。限制后台导出与日志访问，数据库备份加密保存并定期恢复演练。离职、设备丢失或权限变更时，应能撤销下游 Key 和重新授权受影响账号。
收紧 URL 与网络访问
项目支持 URL Allowlist 等安全配置。README 指出，关闭 Allowlist 时只执行最小校验且默认允许 HTTP，更适合开发环境；生产应优先只允许 HTTPS，并限制可访问主机、端口和私有网段，防止自定义 URL、媒体回源或代理配置形成 SSRF。WAF/CDN 可以作为第一层防护，但服务端限流、响应读取上限和地址校验仍要保留。
审计提示词与隐私
可选提示词审计与风险控制能够在请求进入上游前检查内容，但审计系统本身也会接触用户输入。启用前应明确处理位置、保留时间、误判策略和谁能查看。错误日志、用量明细和审计记录不应保存完整凭据；涉及源码、个人信息或客户数据时，还要确认每个实际上游是否获准接收。
固定版本并监控
不要在生产环境无条件追随最新镜像或直接点击升级。固定经过验证的版本，阅读 Release Notes，备份 PostgreSQL、Redis 持久数据和配置后再升级。监控至少覆盖请求量、错误率、首字延迟、流式连接、账号可用性、OAuth 刷新、并发槽、Redis、数据库、磁盘与异常计费。
许可证与服务条款边界
Sub2API 使用 GNU LGPL v3.0 或更高版本。修改、分发、链接方式和向用户提供源码的义务取决于实际使用方式，商业产品部署前应阅读 LICENSE 并咨询专业人士。更重要的是，开源许可证只约束项目代码，不会授予 Anthropic、OpenAI、Google、xAI 或其他上游账号与订阅的使用权。
项目作者关于“无商业授权”的声明与 LGPL 代码许可证需要结合具体文本和适用法律理解，但至少传递了明确风险信号：不能使用项目名称暗示官方背书，也不能假设订阅配额允许拼车、转售或公开 API 服务。技术部署之前，应分别完成代码许可证、上游条款、数据保护和支付运营审查。本文不构成法律意见。
优势与局限
优势：围绕订阅账号池提供了较完整的调度体系；支持多类凭据和 Claude、Codex、Gemini、Grok 等协议；具备粘性会话、并发、限速、计费、复合分组、监控和管理后台；Compose 部署和简易模式覆盖了从个人研究到团队内部使用的不同复杂度。
局限：高度依赖上游未公开或快速变化的产品行为；订阅共享和协议转换可能违反服务条款并触发封号；OAuth 凭据集中存储扩大了安全影响面；高级协议转换无法保证完全无损；计费和账号容量需要持续校准；快速迭代意味着升级与回滚都必须测试。
适合谁使用？
Sub2API 更适合研究 AI 产品订阅网关、拥有明确授权账号并需要内部统一分配的开发者或团队，以及希望学习多账号调度、粘性会话和精确计费实现的人。采用简易模式、限制在内网、使用自己的合法账号，是比直接搭建公开服务更可控的起点。
如果你只调用一家供应商的官方 API，或无法持续维护 OAuth、数据库、Redis、监控与安全策略，直接使用官方接口通常更可靠。若计划向公众收费、共享个人订阅，或者绕过供应商限制，风险显著高于普通 API 网关，不应仅凭项目能运行就投入使用。
总结
Sub2API 的核心价值，在于把多个 AI 产品账号和凭据组织成可调度的配额池，再通过平台 API Key 向下游提供统一鉴权、会话绑定、并发控制、计量与管理。它不是简单的请求转发器，而是一套围绕订阅配额生命周期构建的网关与运营后台。
也正因为它触及订阅账号、OAuth、请求内容和计费，正确使用比部署成功更重要。应先核对上游授权，从单账号和受限 Key 开始，在内网验证协议、粘性和账目；随后再配置账号池、备份、审计、监控与升级流程。任何公开共享或商业运营，都需要独立完成服务条款、许可证与合规评估。
资料说明：本文依据 Sub2API 官方 GitHub 仓库、中文 README、Compose 与配置示例、源代码、法律与支付文档、GitHub API 及 v0.1.176 Release 在 2026 年 8 月 13 日可见的内容整理。项目更新频繁，版本、接口、上游支持和风险提示可能变化，请以官方仓库及最新 Release 为准。
