Sub2API：一个把订阅配额变成可分发 API Key 的开源网关

核心判断：Sub2API 解决的是多用户共享订阅配额时的鉴权、计费和调度问题，中转代理只是它的外层形态。

一句话版本

Sub2API 是一个 AI API 网关平台——用户把自己的 AI 订阅账号（如 Claude Code、Codex）接入平台，平台为每个终端用户生成独立的 API Key，替这些用户完成身份鉴权、流量调度、计费扣款，最后把请求发往上走的 AI 服务商。

它本质上是一层订阅共享层，远超代理中转层。

为什么需要 Sub2API

AI 产品的订阅模式天然存在一个问题：一个订阅账号的配额只能给一个人用。

以 Claude Code 为例，官方订阅为每账号每月有限的额度。但如果是团队使用、独立开发者想把额度分享给客户，或者提供 SaaS 服务商想要多租户管理——原生的订阅体系无法支持。

常见的解法有几种：

Sub2API 的核心逻辑：平台持有账号池，终端用户拿 API Key 访问，按量计费。这不是简单的请求转发，是一整套配额管理系统。

架构总览

                    终端用户请求
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                    Sub2API Gateway                       │
│                                                          │
│   ┌─────────┐    ┌─────────┐    ┌──────────────────┐    │
│   │ API Key │───▶│  鉴权   │───▶│  流量调度器      │    │
│   │  管理   │    │  服务   │    │  (粘性会话/负载) │    │
│   └─────────┘    └─────────┘    └──────────────────┘    │
│        │                                │                 │
│        │                                ▼                 │
│        │                         ┌──────────────────┐    │
│        │                         │   上游账号池     │    │
│        │                         │  (OAuth/API Key) │    │
│        │                         └──────────────────┘    │
│        │                                │                 │
│        ▼                                ▼                 │
│   ┌─────────┐                   ┌───────────────┐        │
│   │ 计费系统 │                   │  Claude Code  │        │
│   │ Token级 │                   │  Codex        │        │
│   │ 扣费    │                   │  Gemini       │        │
│   └─────────┘                   └───────────────┘        │
└─────────────────────────────────────────────────────────┘

Sub2API 内部主要分为四层：

1. 接入层：接收终端请求，验证 API Key
2. 调度层：根据负载均衡、粘性会话、并发控制等策略选择上游账号
3. 账号池层：管理多个上游账号（OAuth 授权或 API Key 接入）
4. 计费层：Token 级用量追踪和成本计算

数据流向：API Key 验证 → 用户认证 → 账号选择 → 请求转发 → 响应回传 → 计费记录

核心机制详解

2.1 API Key 体系

用户不是用上游 AI 平台的账号密码接入，而是从 Sub2API 平台获取一个 API Key（格式默认 sk- 前缀，可配置）。

平台维护两张表：

• 用户表：终端用户的 API Key、余额、并发限制
• 账号池表：上游 AI 服务的实际账号（OAuth Token 或 API Key）

API Key 的作用是解耦：终端用户不需要知道平台背后有多少个上游账号，平台也不需要暴露上游凭据。

2.2 智能调度策略

Sub2API 支持两种调度模式：

普通调度：请求来了从账号池里选一个可用账号，适用于无状态请求。

粘性会话（Sticky Session）：同一个对话上下文（session_id）始终路由到同一个上游账号。这是因为 Claude/Antigravity 等服务对同一会话内的账号有限制——不同账号的上下文不能混用。

⚠️ Nginx 用户注意：Nginx 默认会丢弃含下划线的请求头（如 session_id），需要在配置里加 underscores_in_headers on;，否则粘性会话会失效。

2.3 并发控制

Sub2API 实现了两级并发限制：

当某个上游账号达到并发上限，新请求会等待或调度到其他账号。

2.4 速率限制

可配置的请求速率限制（Rate Limiting），防止用户超出预算。限制可以针对：

• 每分钟请求数
• 每分钟 Token 数
• 或者两者组合

2.5 Token 级计费

Sub2API 的计费精确到每个 Token。当一次请求完成后，平台会解析响应中的 Token 用量，按配置的成本参数计算费用，从用户余额中扣除。

计费参数在配置文件中定义：

default:
  user_concurrency: 5        # 用户最大并发
  user_balance: 0            # 新用户初始余额
  api_key_prefix: "sk-"     # API Key 前缀
  rate_multiplier: 1.0       # 费率倍率

平台也内置了支付系统（Stripe/Alipay/WeChat Pay），用户可以自助充值。

2.6 支持的上游服务

Sub2API 目前支持：

⚠️ Sora 相关功能目前暂时不可用，不建议在生产环境依赖。

一次完整请求的任务流

以「用户 A 通过 API Key 发起一次 Claude Code 请求」为例，完整流程如下：

1. 用户A 发送请求
   POST /v1/messages
   Authorization: Bearer sk-userA-xxxxx

2. Sub2API 鉴权层验证
   - 检查 sk-userA-xxxxx 是否有效
   - 检查用户余额是否充足
   - 检查用户并发是否超限

3. 调度层选择上游账号
   - 如果是会话请求（带 session_id）：
     → 查找该 session_id 之前路由到的账号
     → 检查该账号是否仍在线、并发是否允许
     → 如允许则继续使用该账号（粘性）
     → 如不可用则重新选择
   - 如果是无状态请求：
     → 从账号池选择负载最低、并发未满的账号

4. 请求转发
   - 将请求发往选定的上游账号
   - 请求头中附加必要鉴权信息

5. 接收响应
   - 解析响应体
   - 提取 Token 用量

6. 计费记录
   - 按 Token 用量 × 费率计算费用
   - 从用户A 余额中扣除

7. 响应返回
   - 将 AI 服务商的响应原样返回给用户A

整个过程对终端用户透明——用户只感知到自己发了一个 API 请求、付了费用，账号调度和并发管理全部由平台处理。

技术栈解析

Go 后端是 Sub2API 架构中最关键的选择——高并发下的 goroutine 调度比 Python/Node.js 更稳定，而 Gin 提供了足够轻量的 HTTP 路由层，不引入过度抽象。

部署方式对比

方式一：一键脚本（推荐新手）

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash

脚本自动完成：二进制下载 → systemd 服务安装 → 初始化配置。前置条件需要已有 PostgreSQL 和 Redis。

方式二：Docker Compose（适合有容器经验的用户）

cd deploy
docker-compose up -d

自带 PostgreSQL 和 Redis，适合快速尝鲜或小型部署。

方式三：源码开发（适合二次开发）

# 后端热重载
cd backend && go run ./cmd/server

# 前端热重载
cd frontend && pnpm run dev

源码部署需要手动配置数据库连接和运行参数。

适用场景与边界

适合使用 Sub2API 的场景

1. 团队内共享 AI 订阅：多人共用一个 Claude Code 订阅，各自独立计费
2. SaaS 服务提供：想把 AI 能力以 API 方式提供给客户，按量收费
3. 多租户管理平台：需要管理多个终端用户的配额和额度
4. 成本优化需求：订阅价远低于官方 API，需要配额共享方案

不适合使用 Sub2API 的场景

1. 需要官方 SLA 保障：订阅账号本身没有 SLA，中转服务也没有
2. 金融、医疗等强合规场景：需要完整的审计日志和合规证明
3. 高频大规模商用：需要与 AI 服务商谈官方企业协议

谁可以先用

• 个人开发者、小团队：直接从官方赞助商处获取中转服务，或自建 Sub2API
• 独立 SaaS 开发者：用 Sub2API 构建 AI API 服务，按量向用户收费
• 有一定运维能力的团队：自建部署，自管理账号池

已知限制与风险

⚠️ 安全提醒：禁用 URL 白名单检查后，系统会放行 HTTP 请求，这在生产环境中是不推荐的——API Key 和数据将以明文传输，存在被中间人攻击的风险。

快速开始

1. 安装前置服务

• PostgreSQL 15+（已启动）
• Redis 7+（已启动）

2. 运行安装脚本

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash

3. 启动服务并访问管理后台

sudo systemctl start sub2api
sudo systemctl enable sub2api
# 然后访问 http://你的服务器IP:8080

4. 配置第一个上游账号

在管理后台中填入上游 AI 服务的凭据（OAuth 或 API Key），平台会自动创建 API Key 给终端用户使用。

相关资源

• GitHub：Wei-Shaw/sub2api
• 在线 Demo：https://demo.sub2api.org/（账号：admin@sub2api.org / admin123）
• 赞助商列表：官方中转服务提供商，可直接使用免自建
• 生态项目：sub2api-mobile（移动端管理控制台）

文档信息 难度：⭐⭐⭐ | 类型：进阶分析 | 更新日期：2026-05-25 | 预计阅读时间：15 分钟