Sub2API 部署与账号导入教程：把订阅账号统一转换成 API Key

如果你手里有 Claude、OpenAI、Gemini 等 AI 产品订阅账号，想统一管理额度、分组、API Key 和调用入口，可以试试 Sub2API。

Sub2API 是一个开源 AI API 网关平台，作用是把上游 AI 账号或订阅能力统一接入到一个后台里，再通过平台生成的 API Key 对外提供调用。它可以负责鉴权、账号分组、负载均衡、请求转发、额度统计等工作，比较适合自用、多账号管理，或者团队内部统一接入。

提醒：本文仅用于管理自己合法持有的账号和订阅资源。请遵守对应平台的服务条款，不要用于违规共享、倒卖或滥用。

项目地址：

https://github.com/Wei-Shaw/sub2api

一、部署前准备

本文推荐使用 Docker Compose 部署，由于这种方式会自动拉起 Sub2API、PostgreSQL 和 Redis，配置最省心，也方便后续备份和迁移。

服务器提议：

• 系统：Ubuntu 20.04+ 服务器
• Docker：20.10+
• Docker Compose：v2+
• 端口：默认使用 8080
• 权限：提议使用 root 用户，或具备 sudo 权限的用户

如果你使用的是一键二进制脚本部署，则需要提前自行准备 PostgreSQL 和 Redis。新手提议直接走 Docker Compose。

二、安装 Docker 和 Docker Compose

如果你的服务器已经安装过 Docker，可以先检查版本：

docker --version
docker compose version

如果没有安装，可以按下面步骤安装 Docker 官方源和 Compose 插件。下面命令以 Ubuntu 为例，Debian 用户需要把 Docker 源地址换成 Debian 对应地址。

apt update
apt install -y ca-certificates curl gnupg

mkdir -p /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg 
  | gpg --dearmor -o /etc/apt/keyrings/docker.gpg

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

apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

启动 Docker，并设置开机自启：

systemctl start docker
systemctl enable docker

再次检查版本：

docker --version
docker compose version

三、部署 Sub2API

创建一个单独的部署目录：

mkdir -p sub2api-deploy
cd sub2api-deploy

运行官方 Docker 部署准备脚本：

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/ 等本地数据目录

然后启动服务：

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

查看运行日志：

docker compose -f docker-compose.local.yml logs -f sub2api

看到服务正常启动后，就说明部署基本完成。

四、访问后台

浏览器打开：

http://你的服务器IP:8080

如果服务器有防火墙或云安全组，记得放行 8080 端口。

打开后可以看到 Sub2API 的前端界面：

五、获取后台管理员密码

默认管理员账号是：

admin@sub2api.local

管理员密码会在首次启动时自动生成，可以在服务器上执行下面命令查看：

docker compose -f docker-compose.local.yml logs sub2api | grep "admin password"

如果你的环境里没有使用 docker-compose.local.yml，也可以尝试：

docker logs sub2api | grep "admin password"

日志里出现的密码就是后台初始密码。

登录后台后，第一件事提议先修改管理员邮箱和密码，避免默认账号长期暴露。

六、创建账号分组

导入上游账号之前，提议先创建分组。

分组可以理解为“账号池”。你准备反代哪一类账号，就创建对应的分组，例如：

• claude
• openai
• gemini
• codex
• team

后面创建 API Key 时，可以把 Key 绑定到指定分组。这样不同用户、不同客户端、不同场景就能走不同的账号池。

七、导入上游账号

进入后台的账号管理页面，点击导入账号。

不同上游类型需要填写的信息不完全一样，按页面提示操作即可。一般流程是：

1. 选择账号类型或上游渠道。
2. 选择前面创建好的分组。
3. 填入账号凭证，例如 Token、Cookie、OAuth 信息或 API Key。
4. 保存账号。
5. 测试账号状态，确认可用。

提议一次先导入 1 个账号测试，确认调用正常后，再批量导入更多账号。这样排错会简单许多。

八、创建 API Key

账号导入完成后，就可以创建对外使用的 API Key。

进入 API Key 管理页面，创建新的 Key，并按需配置：

• Key 名称：方便自己识别用途
• 可用分组：选择刚才导入账号所在的分组
• 额度限制：按需设置
• 过期时间：自用可以不设置，给别人用提议设置
• 启用状态：确认打开

创建完成后，复制生成的 API Key。

九、在客户端里使用

Sub2API 部署完成后，客户端一般需要填写两个核心信息：

Base URL：http://你的服务器IP:8080
API Key：后台生成的 Key

如果你已经配置了域名和反向代理，也可以改成：

Base URL：https://你的域名
API Key：后台生成的 Key

例如在 Codex、Cherry Studio 或其他支持自定义 API 地址的客户端里，填入上面的 Base URL 和 API Key，就可以通过 Sub2API 调用后端账号池了。

总结

整体流程可以概括为：

安装 Docker -> 部署 Sub2API -> 登录后台 -> 创建分组 -> 导入账号 -> 创建 API Key -> 客户端接入

对新手来说，Docker Compose 是最省事的部署方式。它会把 Sub2API、PostgreSQL 和 Redis 一起跑起来，后续备份和迁移也比较清晰。

部署完成后，把上游账号导入到对应分组，再创建 API Key，就可以在 Codex、Cherry Studio 等客户端里统一使用了。