Sub2API 搭建教程：Docker Compose 部署 AI API 网关平台

Sub2API 是 Wei-Shaw 开源的 AI API 网关平台，用来管理 AI 产品订阅配额、API Key、用户用量、账号调度和请求转发。它不是一个单纯的转发脚本，而是带有后台管理、计费、并发限制、速率限制、支付集成和多账号调度能力的完整网关系统。

这篇文章根据 Sub2API 官方中文 README，整理一条适合普通服务器部署的路线：先理解它适合什么场景，再用 Docker Compose 起服务，最后补上域名、HTTPS、备份、升级和安全配置。

先说清楚风险：Sub2API 可能涉及上游服务商的服务条款、账号风控和合规问题。请只在符合法律法规和相关服务条款的场景下使用，不要把未经授权的账号或订阅资源公开售卖。本文只讨论技术部署流程。

Sub2API 适合做什么

Sub2API 的核心定位是 AI API Gateway，也就是把多个上游账号或 API Key 统一到一个平台里，再由平台生成自己的 API Key 给用户或内部工具调用。平台负责鉴权、计费、负载均衡、账号选择和请求转发。

多账号管理：支持 OAuth、API Key 等不同上游账号类型。
API Key 分发：为用户生成和管理独立 API Key。
Token 级用量追踪：用于统计成本、余额和调用记录。
智能调度：支持账号选择、分组和粘性会话。
并发和速率限制：可以限制用户级、账号级请求压力。
管理后台：通过 Web 界面管理用户、账号、监控和配置。

如果你只是想学习 AI API 网关、给团队内部统一接入、测试 Claude Code / Codex / Gemini CLI / OpenAI-compatible 客户端，那么 Sub2API 很适合研究。如果你的目标是零运维、零风控、零服务器维护，那它可能偏重。

部署前准备

官方 README 提供了脚本安装、Docker Compose 和源码编译三种方式。个人和小团队最容易上手的是 Docker Compose，因为它可以把 Sub2API、PostgreSQL 和 Redis 放在同一套 compose 里启动。

建议准备：

一台 Linux 服务器，amd64 或 arm64 均可。
Docker 20.10+。
Docker Compose v2+。
一个已经解析到服务器的域名。
开放 80、443 端口；测试阶段可临时开放 8080。
正式使用前准备 HTTPS，不建议长期裸露 HTTP 入口。

如果你选择官方脚本安装而不是 Docker Compose，需要提前准备 PostgreSQL 15+、Redis 7+ 和 root 权限。本文主线使用 Docker Compose。

不熟悉服务器怎么办

如果你本来就熟悉 Linux、Docker、Nginx 和域名证书，可以跳过这一节，直接往下看部署命令。

如果你不熟悉服务器，最省心的办法不是一边看命令一边猜，而是先在服务器上安装 Codex 或 Claude Code，然后把下面的提示词交给它，让它在你的服务器环境里一步一步检查、安装和部署 Sub2API。

可以先参考这两篇安装教程：服务器上安装 Codex CLI 看 Codex CLI 安装指南，服务器上安装 Claude Code 看 Claude Code CLI 安装指南。

如果你没有 OpenAI 或 Claude 官方账号，也可以使用中转站。这里推荐 YYLX.IO 鱼鱼连线。通过中转站配置 Codex 可以看 Codex CLI Base URL 与 API Key 配置教程，通过中转站配置 Claude Code 可以看 Claude Code Base URL 与 API Key 配置教程。

把 Codex 或 Claude Code 装好后，可以在服务器上新建一个空目录，然后把这段提示词发给它：

请帮我在这台 Linux 服务器上部署 Sub2API。

要求：
1. 先检查系统版本、CPU 架构、内存、磁盘空间、Docker 和 Docker Compose 是否已安装。
2. 如果 Docker 或 Compose 不存在，请按当前系统的推荐方式安装，并设置 Docker 开机自启。
3. 使用 Sub2API 官方 Docker Compose 部署方式：创建 sub2api-deploy 目录，运行官方 docker-deploy.sh 准备脚本，然后 docker compose up -d 启动服务。
4. 启动后检查 docker compose ps 和 sub2api 日志，确认 PostgreSQL、Redis、Sub2API 都正常运行。
5. 告诉我浏览器应该访问哪个地址完成初始化，例如 http://服务器IP:8080。
6. 如果服务器已有 Nginx 或 Caddy，请先不要覆盖现有配置，只给出反向代理和 HTTPS 配置建议。
7. 不要删除已有数据，不要执行 rm -rf，不要改动与 Sub2API 无关的服务。
8. 最后总结部署目录、常用启动/停止/日志命令，以及后续配置域名和 HTTPS 的下一步。

安装 Docker 和 Compose

新服务器可以先安装 Docker。Ubuntu / Debian 常见安装方式如下：

curl -fsSL https://get.docker.com | bash
systemctl enable docker
systemctl start docker

确认 Docker 和 Compose 都能正常运行：

docker --version
docker compose version

Docker Compose 快速部署

Sub2API 官方 README 推荐使用部署准备脚本。这个脚本会下载 Docker Compose 文件和环境变量模板，自动生成 JWT、TOTP、PostgreSQL 密码，并创建本地数据目录。

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 ps

查看 Sub2API 日志：

docker compose logs -f sub2api

浏览器访问：

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

如果管理员密码由脚本自动生成，可以在日志里查找：

docker compose logs sub2api | grep "admin password"

手动 Docker Compose 部署

如果你想手动控制配置，也可以克隆仓库后自己编辑环境变量：

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

cp .env.example .env
nano .env

至少建议配置这些变量：

POSTGRES_PASSWORD=your_secure_password_here
JWT_SECRET=your_jwt_secret_here
TOTP_ENCRYPTION_KEY=your_totp_key_here
[email protected]
ADMIN_PASSWORD=your_admin_password
SERVER_PORT=8080

密钥不要随手写简单字符串，可以用 OpenSSL 生成：

openssl rand -hex 32

创建数据目录并启动本地目录版 compose：

mkdir -p data postgres_data redis_data

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

docker compose -f docker-compose.local.yml ps

为什么推荐本地目录版

Sub2API 官方 README 对比了两种 Docker Compose 数据存储方式：命名卷简单，但迁移时需要用 docker 命令导出；本地目录版把数据放在项目目录下，更适合备份和迁移。

如果你准备长期使用，推荐使用 docker-compose.local.yml 或官方脚本生成的本地目录结构。这样迁移服务器时可以直接打包整个部署目录。

初始化后台

服务启动后，第一次访问 http://服务器IP:8080 会进入设置向导。通常需要完成数据库配置、Redis 配置和管理员账号创建。Docker Compose 脚本部署时，数据库和 Redis 已在同一个 compose 网络里，按向导填写即可。

初始化完成后建议立刻做三件事：修改管理员密码、关闭不需要的注册入口、检查默认用户额度和 API Key 前缀。

配置域名和 HTTPS

生产环境不建议直接暴露 http://IP:8080。更稳妥的方式是用 Nginx、Caddy 或其他反向代理把域名转发到本机 8080 端口，并配置 HTTPS。

如果使用 Nginx 反向代理 Sub2API，并搭配 Codex CLI 使用，官方 README 特别提醒需要在 Nginx 配置的 http 块中加入：

underscores_in_headers on;

原因是 Nginx 默认会丢弃名称中含下划线的请求头，例如 session_id。在多账号环境下，这会导致粘性会话失效。

一个简化的 Nginx 反代示例：

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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;
    }
}

正式使用 API Key、账号授权和用户后台时，请务必配置 HTTPS。可以使用 Certbot、acme.sh 或 Caddy 自动签发证书。

启用数据管理功能

Sub2API 的管理后台里有“数据管理”功能，但 Docker 场景下不是默认无条件可用。官方 README 说明，如需启用该功能，需要额外部署宿主机数据管理进程 datamanagementd。

关键点是：主进程会固定探测 /tmp/sub2api-datamanagement.sock。只有这个 socket 可连通时，数据管理功能才会开启。Docker 场景还需要把宿主机 socket 挂载到容器内同一路径。

这部分建议上线前单独阅读官方 deploy/DATAMANAGEMENTD_CN.md，不要只靠复制 compose 文件就以为数据管理已经启用。

简易模式

Sub2API 还提供简易模式，适合个人开发者或内部团队快速使用。启用方式是设置环境变量：

RUN_MODE=simple

简易模式会隐藏部分 SaaS 相关功能，并跳过计费流程。官方 README 同时提醒，生产环境如果要使用简易模式，需要设置：

SIMPLE_MODE_CONFIRM=true

这相当于明确确认你知道自己在生产环境使用的是简化功能集。

Antigravity 端点

Sub2API 支持 Antigravity 账户，授权后可以通过专用端点访问 Claude 和 Gemini 模型。官方 README 给出的端点是：

/antigravity/v1/messages：Claude 模型。
/antigravity/v1beta/：Gemini 模型。

Claude Code 配置示例：

export ANTHROPIC_BASE_URL="http://localhost:8080/antigravity"
export ANTHROPIC_AUTH_TOKEN="sk-xxx"

需要注意的是，Anthropic Claude 和 Antigravity Claude 不应在同一上下文中混合使用。实际部署时应通过分组功能做好隔离。

升级 Sub2API

Docker Compose 部署后，升级通常是拉取最新镜像并重建容器：

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

如果是脚本安装方式，官方 README 说明可以在管理后台左上角点击“检测更新”进行在线升级，并支持回滚。无论哪种方式，升级前都建议先备份数据库和配置。

备份和迁移

使用本地目录版 compose 时，迁移比较直接。源服务器停止服务后打包整个部署目录：

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

备份时不要漏掉 .env、PostgreSQL 数据、Redis 数据和 Sub2API 配置。它们一起决定了用户、余额、账号、密钥和调用记录能否恢复。

上线前安全检查

Sub2API 会处理 API Key、账号授权、用户余额、调用日志和管理后台权限，不应该裸奔上线。至少建议做到：

启用 HTTPS，禁止长期明文传输 API Key。
限制后台访问，尽量只允许固定 IP、VPN 或内网访问。
配置用户级和账号级并发限制，避免单个 Key 打满上游账号。
设置合理的请求速率和 Token 速率限制。
定期备份数据库、Redis、.env 和配置文件。
保管好 JWT_SECRET、TOTP_ENCRYPTION_KEY、数据库密码和上游账号凭据。
公开服务前确认服务条款、商业授权和本地法律法规风险。

适合自建吗

Sub2API 很适合有服务器经验、愿意维护数据库和账号池、需要内部统一 API 网关的人。它的优势是可控、功能完整、可观察性更强，也适合学习 AI API 网关的真实架构。

但自建不只是运行一条命令。你还要处理服务器、域名、HTTPS、备份、升级、账号风控、上游兼容、用户额度和日志安全。如果只是想稳定使用 Claude Code、Codex、Gemini CLI、Cline、Roo Code 等工具，不想维护网关，也可以了解 YYLX.IO 鱼鱼连线这类现成的 AI API 服务。

总结

搭建 Sub2API，推荐路线是 Docker Compose：准备服务器和 Docker，运行官方 docker-deploy.sh，访问 8080 端口完成初始化，再用 Nginx 或 Caddy 配置域名和 HTTPS。

真正上线前，请重点检查合规风险、后台权限、HTTPS、备份、并发限制、速率限制和上游账号安全。Sub2API 是一个完整的 AI API 网关平台，装起来只是第一步，后续稳定运维才是长期工作。

参考资料：Sub2API 官方中文 README。