Sub2API：一站式开源 AI API 网关，统一管理你的 AI 订阅配额

前言：为什么需要 Sub2API？

在 AI 大爆发的时代，我们往往同时订阅了多个 AI 服务——Claude Pro、ChatGPT Plus、Gemini Advanced、Grok……每个平台都有独立的账号、配额和 API 接入方式。管理起来繁琐不说，想要通过 API 统一调用更是难上加难。

Sub2API 就是为解决这个问题而生的。它是一个一站式开源 AI API 网关平台，能够将多个 AI 产品的订阅配额统一接入和管理，支持账号拼车共享、成本分摊，并通过统一的 API Key 实现无缝调用。截至目前，该项目在 GitHub 上已获得超过 30,000+ Star，是当下最活跃的 AI API 网关开源项目之一。

▲ Sub2API GitHub 项目主页，Star 数超过 30k

一、项目介绍

1.1 Sub2API 是什么？

Sub2API（Subscription to API）是一个将 AI 订阅转化为标准 API 接口的网关平台。它的核心理念是：你只需要维护一个 Sub2API 实例，就能通过统一的 API Key 访问所有已接入的 AI 服务。

官方定位为 “AI API Gateway Platform for Subscription Quota Distribution”，即面向订阅配额分发的 AI API 网关平台。

1.2 支持的 AI 平台

1.3 技术栈

二、核心功能特性

2.1 多平台统一管理

在一个管理后台中管理所有 AI 平台的账号和订阅配额，无需在多个平台之间来回切换。支持批量导入账号、批量刷新凭证、批量更新等操作。

2.2 统一 API Key 访问

为用户或团队生成统一的 API Key（默认 sk- 前缀），通过 Sub2API 网关转发请求到上游 AI 平台。客户端只需对接 Sub2API 的 API 端点，无需关心后端是 Claude 还是 OpenAI。

2.3 配额分配与路由

管理员可以为每个用户设置余额、并发数、RPM 限制，并按平台（Anthropic/OpenAI/Gemini/Grok）分配日/周/月配额。智能路由算法自动选择可用账号，避免配额超限。

2.4 渠道与渠道监控

支持创建多个渠道（Channel），每个渠道可绑定不同的账号组和路由策略。内置渠道监控功能，默认每 60 秒检测一次渠道健康状态，自动剔除不可用渠道。

2.5 用户与分组管理

支持多用户体系，每个用户可设置独立的余额、并发数、允许的分组和 RPM 限制。用户可分配到不同分组，实现团队隔离和资源分配。

2.6 多种 OAuth 登录

原生支持以下第三方登录方式：

• LinuxDo OAuth
• 钉钉（DingTalk）OAuth
• 微信 OAuth（开放平台 + 公众号 + 移动端）
• GitHub OAuth
• Google OAuth
• OIDC 通用协议

2.7 实时监控与运营

• 仪表盘：实时展示请求数、QPS、错误率、账号使用情况
• 运营监控：WebSocket 实时 QPS 推送
• 错误透传：可配置是否将上游错误信息透传给客户端
• 请求日志：完整的请求记录和错误追踪

2.8 安全与合规

• TLS 指纹配置：自定义 TLS 指纹配置文件，防止指纹检测
• 风险控制：内置风控模块，支持异常请求拦截
• 管理员合规承诺：首次登录管理后台需确认合规承诺，确保部署者了解法律风险
• TOTP 两步验证：可选启用 TOTP 增强管理员账号安全

2.9 其他功能

• 数据备份与恢复：内置数据管理模块，支持备份和回滚
• 优惠码与兑换码：支持促销码和余额兑换码
• 支付集成：可选启用支付功能（微信支付等）
• 推广联盟： affiliate 推广返利系统
• 定时测试：定期测试账号可用性

三、Docker Compose 部署教程

Sub2API 官方推荐使用 Docker Compose 进行部署，这也是最简单的方式。下面我们一步步来完成部署。

3.1 环境准备

确保你的服务器已安装 Docker 和 Docker Compose：

# 检查 Docker 版本
docker --version
# Docker version 27.x+

# 检查 Docker Compose 版本
docker compose version
# Docker Compose version v2.x+

3.2 下载部署文件

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

# 下载 Docker Compose 配置文件
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-compose.local.yml -o docker-compose.yml

# 下载环境变量模板
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/.env.example -o .env.example

# 一键部署脚本（可选，自动生成 .env）
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh -o docker-deploy.sh

3.3 配置 .env 文件

复制模板并修改配置，生成安全密钥：

# 复制模板
cp .env.example .env

# 生成安全密钥
JWT_SECRET=$(openssl rand -hex 32)
TOTP_KEY=$(openssl rand -hex 32)
PG_PASSWORD=$(openssl rand -hex 16)

# 写入 .env（关键配置项）
cat >> .env << EOF
# 服务端口（默认 8080，如被占用可改为其他端口）
SERVER_PORT=8080

# PostgreSQL
POSTGRES_USER=sub2api
POSTGRES_PASSWORD=${PG_PASSWORD}
POSTGRES_DB=sub2api

# 管理员账号
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=YourStrongPassword

# JWT 密钥
JWT_SECRET=${JWT_SECRET}
JWT_EXPIRE_HOUR=24

# TOTP 加密密钥
TOTP_ENCRYPTION_KEY=${TOTP_KEY}
EOF

3.4 启动服务

# 创建数据持久化目录
mkdir -p data postgres_data redis_data

# 拉取镜像并启动
docker compose up -d

# 查看容器状态
docker compose ps

启动后你会看到三个容器：

# 等待服务就绪（约 10-30 秒）
docker compose logs -f sub2api
# 看到 "server started" 即表示启动成功

3.5 访问 Web UI

在浏览器中访问 http://你的服务器IP:8080，即可看到 Sub2API 的首页：

▲ Sub2API 首页，简洁现代的界面设计

3.6 登录管理后台

点击首页的 Login 按钮，输入你在 .env 中配置的管理员邮箱和密码：

▲ Sub2API 登录页面

3.7 管理员合规确认

首次登录管理后台时，系统会要求管理员完成合规承诺确认。这是 Sub2API 的安全机制，确保部署者了解相关法律风险。你需要输入以下确认短语：

我已阅读、理解并同意 Sub2API 部署与运营合规承诺

输入后点击确认，即可进入管理后台。

四、管理后台介绍

进入管理后台后，你将看到功能丰富的仪表盘和左侧导航菜单：

▲ Sub2API 管理后台仪表盘

4.1 功能模块总览

4.2 系统设置要点

在「系统设置」页面中，有几个关键配置值得注意：

• 默认余额与并发：新用户默认余额为 0，默认并发数为 5，可根据需求调整
• 渠道监控间隔：默认 60 秒检测一次渠道健康状态
• API Key 前缀：默认 sk-，可自定义
• OAuth 登录：支持按登录来源（邮箱/GitHub/Google/微信/钉钉/LinuxDo/OIDC）配置不同的默认余额和并发数
• 平台配额：可为 Anthropic/OpenAI/Gemini/Grok/Antigravity 分别设置日/周/月配额

五、使用示例

5.1 通过 API Key 调用

在管理后台创建 API Key 后，你可以像使用 OpenAI API 一样调用 Sub2API：

curl https://your-domain:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

5.2 兼容原生工具

Sub2API 兼容以下原生 AI 工具的 API 接入：

• Claude Code：设置 API Base URL 为 Sub2API 地址即可
• Codex CLI：支持 Codex CLI 客户端指纹识别
• Gemini CLI：通过 Sub2API 代理 Gemini API 请求

六、总结

Sub2API 是一个功能完善、设计现代的 AI API 网关平台。它的核心价值在于：

1. 统一管理：一个后台管理所有 AI 平台的订阅和配额
2. 灵活分配：支持多用户、多分组、多渠道的精细化管理
3. 安全合规：内置合规承诺、TLS 指纹、风控等安全机制
4. 部署简单：Docker Compose 一键部署，数据持久化便于迁移
5. 开源活跃：30k+ Star，社区活跃，持续迭代

如果你有多个 AI 订阅需要统一管理，或者想和朋友拼车共享 AI 配额，Sub2API 是目前最值得尝试的开源方案。