Wei-Shaw/sub2api · 上手攻略

仓库：Wei-Shaw/sub2api
链接：https://github.com/Wei-Shaw/sub2api
分类：llm-infra
作者：Tom
更新：2026-07-05

⚠️ 阅读警告

Sub2API 是一个存在明确服务条款风险的开源项目。仓库 README 开篇即写明：

"使用本项目可能违反 Anthropic 等上游服务商的服务条款。请仔细阅读相关服务商的用户协议，所有风险由用户自行承担。"

在部署和使用前，请充分评估法律风险。 本攻略仅做技术说明，不构成使用建议。

这是什么

Sub2API 是一个自托管 AI API 网关，用于将 AI 产品订阅账号（如 Claude、OpenAI、Gemini、Grok）的配额以 API Key 形式分发给多个用户。

从功能上看，它是一个多租户 API 代理 + 计费系统：

你（或你的团队）拥有上游 AI 服务账号（通过官方订阅或第三方经销商购入）
Sub2API 给你一个统一的 API 端点，背面连接多个上游账号
你可以为不同用户生成 API Key，设置额度限制和计费规则
用户（甚至是你自己团队的开发者）通过这个网关调用 AI，完全透明，上游账号信息不暴露

典型使用图：

用户请求 ──→ Sub2API 网关 ──→ 上游 AI 供应商（Claude / OpenAI / Gemini / Grok）
              │
              ├── 鉴权（API Key 检查）
              ├── 计费（Token 级用量记录）
              ├── 负载均衡（多账号轮询/粘性会话）
              └── 限速（用户级 / 账号级并发控制）

解决什么问题

问题一：订阅账号无法共享给团队

AI 服务的官方订阅（Claude Pro、Grok 等）都是单人账号，不能多 Key 并发。Sub2API 让你把一个订阅账号的用量拆分给多个人使用。

问题二：无法精细控制 API 成本

Token 级计费、多租户限速、用量仪表盘——这些是 Sub2API 内置的，对需要对 AI 调用收费或分摊成本的用户很有用。

问题三：多账号管理复杂

有多个来源的上游账号（官方订阅、多个经销商渠道），Sub2API 提供统一接入层，自动选择最优账号（粘性会话、故障转移）。

问题四：缺乏支付集成

Sub2API 内置了支付系统（支付宝、微信、Stripe、EasyPay），支持用户自助充值——这对商业化运营 AI API 服务来说是开箱即用的。

技术架构

组件	技术	作用
后端	Go 1.25.7 + Gin + Ent ORM	API 网关核心逻辑
前端	Vue 3.4+ + Vite + TailwindCSS	管理后台 UI
数据库	PostgreSQL 15+	用户、账号、计费记录存储
缓存/队列	Redis 7+	限速、缓存、会话管理
部署	Docker Compose	一键部署

API 兼容性格式：Sub2API 兼容 OpenAI 格式（https://your-domain/v1/chat/completions），因此可以无缝对接支持 OpenAI SDK 的客户端（Claude Code、OpenAI 客户端等）。

快速安装

前置条件

Linux 服务器（amd64 或 arm64）
Docker 和 Docker Compose
PostgreSQL 15+、Redis 7+（Docker Compose 会自带）
上游 AI 账号（官方订阅或第三方经销商）

方式一：脚本一键安装（推荐）

# SSH 到你的 Linux 服务器
# 下载官方安装脚本（需要从 GitHub Releases 获取最新版本）
curl -fsSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/scripts/install.sh | bash

# 安装过程中会要求配置：
# - 域名 / HTTPS 证书
# - PostgreSQL / Redis 连接信息
# - 管理员账号

注：安装脚本的具体 URL 和参数可能随版本变化，建议直接查看 GitHub Releases 页面获取最新安装命令。版本号需以 GitHub 发布页为准，不确定时不要指定版本，可去掉 --version 参数使用最新版。

方式二：Docker Compose 手动部署

# 克隆仓库
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api

# 配置文件（参考 docker-compose.yml 和环境变量说明）
cp .env.example .env
# 编辑 .env，填写数据库密码、管理员密码等

# 启动所有服务（PostgreSQL + Redis + 后端 + 前端）
docker compose up -d

# 检查服务状态
docker compose ps

方式三：从源码构建

# 后端编译（需要 Go 1.25.7+）
cd sub2api
go build -o sub2api ./cmd/server

# 前端构建（需要 Node.js 18+）
cd web
npm install
npm run build

核心配置与使用

1. 添加上游 AI 账号

登录管理后台（默认 http://your-domain:3000），在"账号管理"中添加上游账号：

字段	说明
供应商类型	OpenAI / Anthropic / Google / Grok 等
认证方式	API Key 或 OAuth
Base URL	供应商的 API 端点
权重/优先级	多账号轮询时的权重
并发限制	该账号允许的最大并发

2. 创建用户并分发 API Key

在管理后台的"用户管理"中： 1. 创建用户 2. 设置余额或套餐 3. 生成 API Key（类似 sk-sub2-xxxxxxxx） 4. 将 Key 分发给用户

3. 客户端调用（OpenAI 兼容格式）

# 示例：通过 Sub2API 调用 Claude（需上游账号支持）
curl https://your-domain/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-sub2-xxxxxxxxxxxx" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": false
  }'

4. 配置速率限制

# 在管理后台配置用户级限速
rate_limit:
  requests_per_minute: 60
  tokens_per_minute: 100000
  concurrent_limit: 5

5. Nginx 反向代理注意

通过 Nginx 反向代理 Sub2API 时，必须在 http 块添加：

underscores_in_headers on;

否则含下划线的请求头（如 session_id）会被 Nginx 丢弃，导致多账号粘性会话失效。

典型适用场景

场景一：团队内部 AI 资源分摊

团队多人都想用 Claude，但只有一个 Pro 账号。通过 Sub2API 分发 API Key，精确控制每人用量，防止单人过度消耗。

场景二：AI API 服务转售（需评估法律风险）

自己有低价渠道账号，想以 API 形式提供服务给其他人。Sub2API 提供完整的计费和支付系统，可以实现充值余额制、按量计费。

场景三：多渠道账号聚合

同时使用多个渠道的 Claude 订阅（官方 + 多家经销商），Sub2API 统一接入，自动选优并处理故障转移。

场景四：成本分析与监控

Sub2API 提供详细用量仪表盘，可以看到每个模型、每个用户、每个时间段的 Token 消耗，用于优化成本结构。

坑与注意

⚠️ 服务条款风险（最重要）：Anthropic、OpenAI 等官方均不允许通过第三方代理转售或共享账号配额。使用 Sub2API 可能导致上游账号被封禁。强烈建议仅在明确被允许的场景下使用（如内部技术研究、自建合规 AI 服务）。
Go 版本要求高：README 标注 Go 1.25.7，这是一个相当新的版本。如果你的服务器上 Go 版本过低，需要升级，否则编译会失败。
PostgreSQL 和 Redis 必须：Sub2API 强依赖这两者，不能用其他替代品。务必确保它们稳定运行，否则网关会中断。
支付集成需要额外配置：内置支付系统（支付宝/微信/Stripe）需要自行申请对应商户账号并配置回调地址，比纯技术部署复杂。
API 兼容性格式限制：Sub2API 对 OpenAI 格式的兼容程度取决于上游供应商是否提供对应接口。Claude 的 Function Calling 格式可能与 OpenAI 有所差异，实际调用时需测试。
PR 已被禁用：作者明确说明不接受 Pull Request，有 bug 或功能需求只能通过 Issue 反馈，不确定issue 回复速度如何。
备份策略：生产环境务必做好 PostgreSQL 的定期备份，Sub2API 没有内置的灾难恢复机制。

与同类对比

方案	定位	特点	优势	劣势
Sub2API	自托管 API 网关	多租户 + 计费 + 支付	开源、自托管、功能完整	法律风险、运维成本高
One API	开源 API 中转	简单中转 + 额度管理	轻量、易部署	无支付系统、功能较基础
New API	One API fork	增强版 One API	更多供应商支持	社区驱动、更新不稳定
Cloudflare AI Gateway	官方 API 网关	跨供应商聚合 + 缓存	无法律风险、CDN 加速	不支持账号共享、商业订阅
各平台官方 SDK	直连	官方支持	合规、稳定	无法共享、不支持多账号管理

一句话推荐结论

Sub2API 技术架构完整、功能开箱即用，是目前开源方案中最接近"商业 AI API 平台"的产品——但其核心用途（AI 订阅共享/转售）存在明确的服务条款冲突，部署前请务必做法律风险评估，切勿在生产环境对非合规场景轻率使用。

参考来源

GitHub README（英文）：https://github.com/Wei-Shaw/sub2api
GitHub README（中文）：https://github.com/Wei-Shaw/sub2api/blob/main/README_CN.md
支付配置文档：docs/PAYMENT_CN.md（仓库内路径）
安装脚本：scripts/install.sh（仓库内路径）
技术栈：Go 1.25.7 + Vue 3.4+ + PostgreSQL 15+ + Redis 7+（来源：README badge）