Sub2API 项目详细总结

一、项目概述

Sub2API 是一个开源的 AI API 网关平台（AI API Gateway Platform for Subscription Quota Distribution），核心功能是将 Claude、OpenAI、Gemini、Grok、Antigravity 等主流 AI 服务的订阅账号统一接入管理，通过平台生成的 API Key 对外提供调用服务。平台负责鉴权、计费、负载均衡和请求转发，实现订阅额度的"拼车共享"模式，高效分摊成本。

基本信息	详情
GitHub 仓库	https://github.com/Wei-Shaw/sub2api
官方网站	https://www.sub2api.com
Stars	33,600+
Forks	6,900+
开源协议	LGPL-3.0
主语言	Go
创建时间	2025-12-18
最近更新	2026-07-22（活跃维护中）

GitHub Topics: 2api, antigravity2api, cc2api, claude, claude-code, codex, crs, crs2, gemini

二、核心定位

Sub2API 不是普通的 OpenAI 兼容转发器，而是一个偏"订阅配额分发"的 AI API Gateway。它的设计目标是：

将手中多种 AI 产品订阅账号的额度统一接入到一个后台
通过平台生成 API Key 对外提供调用
平台负责认证、计费、负载均衡和请求转发
支持拼车共享，高效分摊订阅成本
原生客户端工具（如 Claude Code、Codex CLI）可无缝使用

一句话概括：Sub2API 适合内部团队自用，不适合新手拿来无脑公开商业化。

三、核心功能

功能	说明
多账号管理	支持多种上游账号类型（OAuth、API Key），统一接入 Claude、OpenAI、Gemini、Grok、Antigravity 等服务
API Key 分发	为下游用户生成和管理独立的 API Key，支持自定义前缀（如 sk-），实现安全的访问控制
Token 级精准计费	按 token 追踪用量和成本计算，确保费用分摊透明准确
智能调度	智能算法选择最优账号，支持粘性会话（Sticky Session），保证同一对话始终路由到同一上游账号
并发控制	按用户和按账号设置并发限制，防止单一用户或账号过载
速率限制	灵活配置请求频率（RPM）和 Token 消耗速率（TPM）
内置支付系统	支持 EasyPay、支付宝、微信支付、Stripe 自助充值，无需单独的支付服务
管理后台	Web 界面实时监控用户、账号、请求和用量，支持嵌入外部系统（如工单系统）
异步图片任务	长时间图片生成/编辑通过异步接口提交，轮询获取结果
Simple Mode	个人/内部团队快速接入模式，跳过 SaaS 功能和计费流程

四、技术栈

组件	技术
后端	Go 1.25.7, Gin, Ent ORM
前端	Vue 3.4+, Vite 5+, TailwindCSS
数据库	PostgreSQL 15+
缓存/队列	Redis 7+
容器	Docker Ready

五、项目结构

sub2api/
├── backend/                  # Go 后端服务
│   ├── cmd/server/           # 应用入口
│   ├── internal/             # 内部模块
│   │   ├── config/           # 配置
│   │   ├── model/            # 数据模型
│   │   ├── service/          # 业务逻辑
│   │   ├── handler/          # HTTP 处理器
│   │   └── gateway/          # API 网关核心
│   └── resources/            # 静态资源
│
├── frontend/                 # Vue 3 前端
│   └── src/
│       ├── api/              # API 调用
│       ├── stores/           # 状态管理
│       ├── views/            # 页面组件
│       └── components/       # 可复用组件
│
└── deploy/                   # 部署文件
    ├── docker-compose.yml    # Docker Compose 配置
    ├── .env.example          # 环境变量示例
    ├── config.example.yaml   # 完整配置文件
    └── install.sh            # 一键安装脚本

六、支持的上游服务

上游服务	接入方式	说明
Claude (Anthropic)	OAuth / API Key	支持 Claude Code、Anthropic Messages API
OpenAI	OAuth / API Key	支持 Codex CLI、Chat Completions、Responses API、WebSocket
Gemini (Google)	OAuth / API Key	支持 Gemini CLI、v1beta 接口
Grok (xAI)	OAuth / API Key	支持 Grok CLI、Responses API、Chat Completions、图片/视频生成
Antigravity	OAuth	专用端点 `/antigravity/v1/messages`（Claude）和 `/antigravity/v1beta/`（Gemini）

Grok/xAI 特殊支持

支持 Grok 订阅账户（xAI OAuth）和标准 xAI API Key 账户
支持 OpenAI 兼容 Responses 流量转发到 xAI
支持 Claude 兼容接口（/v1/messages）转换为 xAI Responses
支持 Codex CLI 风格 Responses WebSocket 接入
支持文本模型（grok-4.5, grok-4.3 等）和媒体模型（grok-imagine 系列图片/视频生成）

七、部署方式

方式一：脚本安装（推荐单机部署）

适用场景：想用 systemd 管理单机服务的用户。

前置条件： - Linux 服务器（amd64 或 arm64） - PostgreSQL 15+（已安装并运行） - Redis 7+（已安装并运行） - Root 权限

安装步骤：

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

脚本会自动：检测系统架构 → 下载最新 release → 安装到 /opt/sub2api → 创建 systemd 服务 → 配置用户和权限。

安装后：

sudo systemctl start sub2api
sudo systemctl enable sub2api

# 浏览器打开安装向导
# http://YOUR_SERVER_IP:8080

升级：直接在管理后台点击"检查更新"按钮，一键下载并应用更新，支持回滚。

方式二：Docker Compose（推荐大多数用户）

适用场景：大多数自建用户，官方推荐方式。

前置条件： - Docker 20.10+ - Docker Compose v2+

一键部署：

# 创建部署目录
mkdir -p sub2api-deploy && cd sub2api-deploy

# 下载并运行部署准备脚本（自动生成密钥和配置）
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

# 启动服务
docker compose up -d

# 查看日志
docker compose logs -f sub2api

脚本会自动： - 下载 docker-compose.local.yml 和 .env.example - 生成安全凭证（JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD） - 创建 .env 文件 - 创建数据目录

手动部署：

git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy
cp .env.example .env
chmod 600 .env
nano .env

# 生成安全密钥
openssl rand -hex 32  # JWT_SECRET / TOTP_ENCRYPTION_KEY / POSTGRES_PASSWORD

# 启动
mkdir -p data postgres_data redis_data
docker compose -f docker-compose.local.yml up -d

.env 关键配置：

POSTGRES_PASSWORD=your_secure_password
JWT_SECRET=your_jwt_secret
TOTP_ENCRYPTION_KEY=your_totp_key
ADMIN_EMAIL=[email protected]
ADMIN_PASSWORD=your_admin_password
SERVER_PORT=8080

两个 Docker Compose 版本对比：

版本	数据存储	迁移	适用
docker-compose.local.yml	本地目录	容易（tar 整个目录）	生产环境，频繁备份
docker-compose.yml	Named volumes	需要 docker 命令	简单安装

升级：

docker compose -f docker-compose.local.yml pull
docker compose -f docker-compose.local.yml up -d

迁移：

# 源服务器
docker compose -f docker-compose.local.yml down
cd ..
tar czf sub2api-complete.tar.gz sub2api-deploy/

# 新服务器
tar xzf sub2api-complete.tar.gz
cd sub2api-deploy/
docker compose -f docker-compose.local.yml up -d

方式三：Apple Container（macOS）

适用于 Apple Silicon Mac（macOS 26+），使用 Apple container 1.1.0+：

git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy
./apple-container.sh init
./apple-container.sh up
./apple-container.sh status

方式四：源码编译

适用场景：需要二次开发的用户。

前置条件：Go 1.21+, Node.js 18+, PostgreSQL 15+, Redis 7+

git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api

# 构建前端
cd frontend
npm install -g pnpm
pnpm install
pnpm run build  # 输出到 ../backend/internal/web/dist/

# 构建后端（嵌入前端）
cd ../backend
VERSION="$(./scripts/resolve-version.sh)"
go build -tags embed -ldflags="-X main.Version=${VERSION}" -o sub2api ./cmd/server

# 创建配置文件
cp ../deploy/config.example.yaml ./config.yaml
nano config.yaml

# 运行
./sub2api

关键配置示例（config.yaml）：

server:
  host: "0.0.0.0"
  port: 8080
  mode: "release"

database:
  host: "localhost"
  port: 5432
  user: "postgres"
  password: "your_password"
  dbname: "sub2api"

redis:
  host: "localhost"
  port: 6379

jwt:
  secret: "change-this-to-a-secure-random-string"
  expire_hour: 24

default:
  user_concurrency: 5
  user_balance: 0
  api_key_prefix: "sk-"
  rate_multiplier: 1.0

重要提示：管理员账号只能通过 Setup Wizard（首次运行时 http://:8080）创建。config.yaml 中的 admin_email/admin_password 字段不会用于创建管理员。如果预先创建了 config.yaml，Setup Wizard 会被跳过，需要暂时移走 config.yaml 让 Wizard 触发。

八、客户端接入

Claude Code

export ANTHROPIC_BASE_URL="https://relay.example.com"
export ANTHROPIC_API_KEY="sk-you...-key"
claude

如果使用 Antigravity 专用端点：

export ANTHROPIC_BASE_URL="https://relay.example.com/antigravity"
export ANTHROPIC_AUTH_TOKEN="sk-you...-key"

OpenAI 兼容客户端 / Codex

export OPENAI_BASE_URL="https://relay.example.com/v1"
export OPENAI_API_KEY="sk-you...-key"

注意：有些工具读取 OPENAI_API_BASE，有些读取 OPENAI_BASE_URL，按具体工具文档来。

Gemini CLI

Gemini 相关客户端可能使用 Google 原生路径，也可能通过兼容层接入。Antigravity 账号有 /v1beta/ Gemini 端点。注意 Claude 和 Gemini 的路径、账号组和上下文需要隔离。

Grok CLI

在 Sub2API 管理后台的 API Key 页面，点击"Use Key"并选择"Grok CLI"，系统会自动生成配置文件。手动配置示例（~/.grok/config.toml）：

[models]
default = "grok"
web_search = "grok"

[model."grok"]
model = "grok-4.5"
base_url = "https://your-sub2api.example.com/v1"
name = "Grok 4.5"
api_key = "sk-you...-key"
api_backend = "responses"
context_window = 1000000
supports_backend_search = true

九、Nginx 反向代理注意事项

使用 Nginx 反代时，必须在 http block 中添加：

underscores_in_headers on;

Nginx 默认丢弃带下划线的 header（如 session_id），这会破坏多账号场景下的 sticky session 路由。

极简反代示例：

http {
  underscores_in_headers on;

  server {
    listen 443 ssl http2;
    server_name relay.example.com;

    ssl_certificate /etc/letsencrypt/live/relay.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/relay.example.com/privkey.pem;

    client_max_body_size 50m;

    location / {
      proxy_pass http://127.0.0.1:8080;
      proxy_http_version 1.1;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_buffering off;  # 重要：SSE streaming 需要
    }
  }
}

十、Simple Mode（内部自用模式）

适合个人开发者或内部团队快速接入，不启用完整 SaaS 功能和计费流程。

启用方式：

RUN_MODE=simple
SIMPLE_MODE_CONFIRM=true  # 生产环境必须确认

建议：内部团队先用 Simple Mode 跑通，再决定是否开放注册、余额、支付和套餐。

十一、安全配置

Sub2API 提供丰富的安全配置选项：

配置	说明
`cors.allowed_origins`	CORS 允许列表
`security.url_allowlist`	上游/定价/CRS 主机白名单
`security.url_allowlist.allow_insecure_http`	是否允许 HTTP URL（生产环境应为 false）
`security.response_headers.enabled`	响应头过滤
`security.csp`	Content-Security-Policy 头
`billing.circuit_breaker`	计费错误时熔断
`security.trust_forwarded_ip_for_api_key_acl`	信任转发 IP 的 ACL
`server.trusted_proxies`	信任的代理 CIDR
`turnstile.required`	Turnstile 验证

生产环境务必： - 启用 HTTPS，禁止 HTTP 传输 API Key - 后台限制 IP 或加 Basic Auth - 密钥不入 Git - 日志脱敏 - 限制注册和充值

十二、生态项目

项目	说明
Sub2ApiPay	~~自助支付系统~~ 已内置 — 支付已集成到 Sub2API，无需单独部署
sub2api-mobile	移动端管理控制台，跨平台 App（iOS/Android/Web），用户管理、账号管理、监控仪表盘，基于 Expo + React Native
S2A-Manager	Sub2API 站长运维管理面板

GitHub Topics 下还有多个社区衍生项目。

十三、竞品对比

对比维度	Sub2API	One API	New API	AI Gateway
开源协议	LGPL-3.0	MIT	MIT	部分开源/商业版
部署方式	脚本/Docker/源码	Docker/源码	Docker/二进制	Docker/云服务
支持模型	Claude/OpenAI/Gemini/Grok/Antigravity	OpenAI/Claude/文心/通义等	OpenAI/Claude/Gemini 等	OpenAI/Anthropic/自建模型
核心定位	订阅配额分发与拼车共享	多模型统一接入与转发	高性价比 API 中转	企业级 API 管理与安全
计费精度	Token 级精准计费	Token 级计费	按次或 Token 计费	Token 级计费
账号管理	多账号智能调度+粘性会话	多渠道负载均衡	多 Key 轮询	企业级账号池管理
用户系统	完整 SaaS 用户体系	简单用户管理	基础用户管理	企业级 RBAC 权限
特色功能	拼车成本分摊、Simple Mode	渠道重试、优先级控制	低价中转、高并发	审计日志、安全合规

选型建议： - 要「内部团队统一入口 + 成本统计 + 账号池调度」→ Sub2API - 要「接入很多模型做应用开发」→ OneAPI / New API - 只服务 Claude Code → 更轻的 CRS 类项目也可能够用 - 不想运维 → 商业中转站或官方托管服务

十四、应用场景

AI 订阅拼车共享：多人共同分摊 Claude Pro、OpenAI Plus 等昂贵订阅费用，通过 Token 级精准计费实现公平成本分摊
团队 AI 资源统一管理：企业或团队集中管理多个 AI 服务账号，统一生成和分配 API Key，避免直接共享账号密码
个人多账号聚合：将散落在不同平台的 AI 账号整合到单一入口，一个界面内统一调用
AI 服务二次分发：搭建私有 API 中转站，为下游用户提供稳定的 AI 接口服务，实现轻量级 SaaS 化运营
开发测试环境隔离：为开发和测试环境提供独立的 AI 接口访问通道，与生产环境隔离

十五、适合谁，不适合谁

适合

小团队（3-10 人）内部共享 AI 订阅额度
想做成本分摊和用量追踪
重视数据路径安全，不想把代码和 prompt 交给第三方
需要多账号池调度和并发控制
想把多个 AI 编程工具统一接入同一网关

不适合

完全没有服务器维护经验（至少要会 Linux、Docker、域名、HTTPS、备份）
只是想省钱（自建有服务器、域名、维护、安全、账号风险等真实成本）
想公开卖服务但不懂合规（可能违反上游服务条款，需搞清合规要求）

十六、最小落地路线

准备一台干净 VPS，开放 80/443，后台端口不公网暴露
用 Docker Compose 部署 Sub2API
配置 HTTPS 反向代理，确认 streaming 正常
创建管理员账号，关闭公开注册
添加一个上游账号或 API Key
给自己生成一个内部 API Key
用 Claude Code 或 Codex 跑一个低风险测试任务
配置用户级限流和并发
观察日志和用量统计 1-2 天
再邀请团队成员接入

十七、风险提醒

风险类型	说明
上游条款风险	使用本项目可能违反 Anthropic 等上游服务条款。是否允许订阅额度转 API、是否允许共享/转售，以官方条款为准
账号风控风险	多用户共享、异常并发、跨地域流量、频繁切换上下文，都可能触发上游风控
数据安全风险	自建网关能减少第三方中转站风险，但网关管理员仍可能看到请求内容
运维风险	Redis/PostgreSQL/Docker/Nginx/HTTPS/备份任何一环出问题，都可能导致团队不可用
商业化风险	公开售卖需承担用户数据、支付、发票、客服、退款、合规和上游账号稳定性责任

项目官方免责声明：本项目仅供技术学习和研究目的。作者不对因使用本项目而导致的账号封禁、服务中断、数据丢失等直接或间接损害承担责任。开发者从未授权任何个人或组织基于本项目进行任何形式的商业运营。

十八、常用运维命令

# Docker Compose 版本
docker compose -f docker-compose.local.yml ps       # 查看状态
docker compose -f docker-compose.local.yml logs -f sub2api  # 查看日志
docker compose -f docker-compose.local.yml restart   # 重启
docker compose -f docker-compose.local.yml down      # 停止
docker compose -f docker-compose.local.yml pull       # 拉取最新镜像
docker compose -f docker-compose.local.yml up -d     # 启动/升级

# 脚本安装版本
sudo systemctl status sub2api        # 查看状态
sudo journalctl -u sub2api -f        # 查看日志
sudo systemctl restart sub2api        # 重启

# 卸载
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash -s -- uninstall -y

十九、官方链接

链接类型	URL
GitHub 仓库	https://github.com/Wei-Shaw/sub2api
官方网站	https://www.sub2api.com
官方域名	sub2api.org
GitHub Topics	https://github.com/topics/sub2api

总结

Sub2API 是目前 GitHub 上最热门的 AI API 网关项目之一（3.3万+ Stars），专注于解决"AI 订阅配额统一分发管理"这一痛点。它通过 OAuth/API Key 方式接入上游 AI 订阅账号，生成独立的 API Key 分发给团队成员，并提供 Token 级精准计费、智能调度、并发控制、速率限制等企业级功能。技术栈采用 Go + Vue3 + PostgreSQL + Redis，支持脚本安装、Docker Compose、源码编译、macOS Apple Container 四种部署方式。内置支付系统支持 SaaS 化运营，同时提供 Simple Mode 适合内部团队快速使用。项目活跃维护中，生态丰富，有移动端管理 App 等社区衍生项目。

本文由时空原创，采用 CC BY-NC-SA 4.0 许可协议，转载请注明出处。

Sub2API 项目详细总结：开源 AI API 网关平台