Sub2API 部署与使用完全指南
一款开源的 AI API 网关，助你集中管理多平台 AI 订阅账号
📌 项目简介
如果你同时拥有 Claude、OpenAI、Gemini 等多个 AI 产品的订阅账号，Sub2API 可以帮你解决账号分散管理的困扰。
核心功能
| 功能模块 | 说明 |
|---|---|
| 🔐 统一鉴权 | 集中管理所有上游 AI 账号的认证信息 |
| 📊 负载均衡 | 自动分配请求，避免单一账号过载 |
| 📈 额度统计 | 实时追踪各账号的使用情况 |
| 🔀 请求转发 | 智能路由，将请求转发至最优账号 |
| 👥 分组管理 | 按平台或用途划分账号池 |
⚠️ 温馨提醒：本文仅适用于管理本人合法持有的账号和订阅资源。请务必遵守对应平台的服务条款，禁止用于违规共享、倒卖或滥用。
🔗 项目地址：https://github.com/Wei-Shaw/sub2api
🛠️ 一、动手前的准备
推荐部署方式：Docker Compose
这种方式会自动拉起 Sub2API、PostgreSQL 和 Redis 三个服务，配置最省心，后续备份和迁移也方便。
服务器配置要求
| 项目 | 要求 |
|---|---|
| 操作系统 | Ubuntu 20.04+（或 Debian 11+） |
| Docker | 20.10 以上版本 |
| Docker Compose | v2 及以上 |
| 开放端口 | 8080 |
| 账户权限 | root 或具备 sudo 权限 |
💡 新手建议：直接走 Docker Compose 部署，少踩坑。若使用一键二进制脚本，需自行准备 PostgreSQL 和 Redis。
🐳 二、安装 Docker 与 Docker Compose
1. 检查是否已安装
docker --version
docker compose version2. 安装 Docker（Ubuntu 示例）
# 更新系统并安装依赖
apt update
apt install -y ca-certificates curl gnupg
# 创建密钥目录
mkdir -p /etc/apt/keyrings
# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
| gpg --dearmor -o /etc/apt/keyrings/docker.gpg
# 添加 Docker 软件源
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo $VERSION_CODENAME) stable" \
| tee /etc/apt/sources.list.d/docker.list > /dev/null
# 安装 Docker 及 Compose 插件
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin📝 Debian 用户：将软件源地址中的
ubuntu替换为debian即可。
3. 启动并设置开机自启
systemctl start docker
systemctl enable docker4. 验证安装
docker --version
docker compose version🚀 三、部署 Sub2API
1. 创建部署目录
mkdir -p sub2api-deploy
cd sub2api-deploy2. 执行官方部署脚本
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash该脚本会自动完成：
- ✅ 拉取
docker-compose.local.yml配置文件 - ✅ 生成
.env环境变量文件 - ✅ 自动生成数据库密码、JWT 密钥等
- ✅ 创建
data/、postgres_data/、redis_data/等数据目录
3. 启动服务
docker compose -f docker-compose.local.yml up -d4. 查看运行日志
docker compose -f docker-compose.local.yml logs -f sub2api看到服务正常启动的提示，即表示部署成功 ✅
🌐 四、访问后台
在浏览器中打开：
http://你的服务器IP:8080⚠️ 记得在防火墙或云安全组中 放行 8080 端口。
🔑 五、获取管理员密码
系统默认管理员账号：
admin@sub2api.local查看初始密码
# 使用 docker-compose.local.yml 部署的
docker compose -f docker-compose.local.yml logs sub2api | grep "admin password"
# 或直接使用 docker logs
docker logs sub2api | grep "admin password"🔐 安全提示：登录后请 立即修改 管理员邮箱和密码，避免使用默认账号。
📁 六、创建账号分组
在导入上游账号之前，建议先创建分组。分组可以理解为 “账号池”。
常用分组示例
| 分组名称 | 用途 |
|---|---|
claude | Claude 系列账号 |
openai | OpenAI 系列账号 |
gemini | Google Gemini 账号 |
codex | Codex 相关账号 |
team | 团队共享账号池 |
💡 创建 API Key 时，可将其绑定到指定分组，实现不同客户端走不同的账号池。
📥 七、导入上游账号
进入后台的 账号管理 页面，点击 导入账号。
操作流程
选择上游类型 → 选定分组 → 填入凭证 → 保存 → 测试可用性常见凭证类型
- 🔑 API Key
- 🍪 Cookie / Token
- 🔐 OAuth 信息
💡 建议：先导入 1 个账号 测试，确认调用正常后再批量导入，排错更轻松。
🔐 八、创建 API Key
账号导入完成后，进入 API Key 管理 页面，新建 Key。
配置项说明
| 配置项 | 说明 | 建议 |
|---|---|---|
| Key 名称 | 方便识别用途 | 如 my-claude-key |
| 可用分组 | 绑定已导入账号的分组 | 按需选择 |
| 额度限制 | 调用次数或 Token 限制 | 可选 |
| 过期时间 | Key 有效期 | 自用可不设 |
| 启用状态 | 是否可用 | 保持开启 ✅ |
创建完成后，立即复制并保存 生成的 API Key。
💻 九、在客户端中接入
客户端通常只需配置两个核心信息：
| 配置项 | 示例值 |
|---|---|
| Base URL | http://你的服务器IP:8080 |
| API Key | 后台生成的 Key |
支持接入的客户端
- Codex
- Cherry Studio
- 其他支持自定义 API 地址的 AI 客户端
🌐 如果配置了域名和反向代理，可改用
https://你的域名作为 Base URL。
📋 十、部署流程速查表
| 步骤 | 操作 | 关键命令/位置 |
|---|---|---|
| ① | 安装 Docker | apt install docker-ce |
| ② | 部署 Sub2API | curl ... \| bash + docker compose up -d |
| ③ | 访问后台 | http://IP:8080 |
| ④ | 获取密码 | docker logs sub2api \| grep "admin password" |
| ⑤ | 创建分组 | 后台「分组管理」页面 |
| ⑥ | 导入账号 | 后台「账号管理」→「导入账号」 |
| ⑦ | 生成 API Key | 后台「API Key 管理」→「新建」 |
| ⑧ | 客户端配置 | Base URL + API Key |
流程示意图
安装 Docker → 部署 Sub2API → 登录后台 → 创建分组 → 导入账号 → 创建 API Key → 客户端接入🎯 总结
Sub2API 的核心价值在于：
- 统一入口：一个 API 网关对接多个 AI 平台
- 智能调度：自动负载均衡，提高账号利用率
- 简化管理：分组、额度、鉴权一站式搞定
- 易于扩展：支持多种上游类型和客户端
对于有 多账号管理需求 的个人或团队，Sub2API 提供了一个 开源、可控、易于部署 的解决方案。Docker Compose 方式尤其适合新手快速上手，后续维护和迁移也清晰明了。
📖 本文为技术实践分享，仅供合法合规使用。请勿将本工具用于任何违反服务条款的行为。