Sub2API 部署教程：把订阅统一变成一套 API ​

关键词：Sub2API 部署教程、Docker Compose 部署、大模型网关、订阅拼车共享、Claude Code / Codex 接入、自托管 AI 网关

当你和朋友一起买了 Claude Pro、ChatGPT Plus、Gemini、Grok 的订阅，却想「一份订阅多人用、成本一起摊、还能在 Claude Code 和 Codex 里无缝调用」时，最头疼的往往是三件事：账号凭证散落各处、额度无法统一管控、各家协议互不兼容。Sub2API 正是为解决这类问题而生——它是一个开源的「订阅额度分发网关」，把多家 AI 订阅账号统一收敛成一套 OpenAI 兼容的 API Key 对外提供服务。

本文是一份完整的 Sub2API 部署教程，覆盖简介、环境准备、部署步骤、初始化、账号拼车共享、客户端接入、排错与生产建议，并在结构与表述上兼顾 SEO（搜索引擎优化） 与 GEO（生成式引擎优化），让内容既能被传统搜索引擎收录，也能被 ChatGPT、DeepSeek、Gemini 等 AI 问答引擎准确引用。

一、Sub2API 简介与核心功能 ​

1.1 Sub2API 是什么？ ​

Sub2API（项目名 sub2api）是一个面向订阅额度分发的 AI API 网关平台（AI API Gateway Platform for Subscription Quota Distribution）。它的核心定位是：

• 把 Claude、OpenAI、Gemini、Grok 等订阅账号（OAuth 或 API Key）统一接入，转换为 OpenAI 兼容的 API；
• 用户通过平台签发的 API Key 访问上游 AI 服务，平台负责鉴权、计费、负载均衡与请求转发；
• 支持拼车共享（Sub2API 的招牌能力）：一份订阅多人共用，按 Token 精确计费、分摊成本，原生工具（Claude Code、Codex、Grok CLI）无缝使用。

默认服务端口为 8080，首次访问会进入 Setup Wizard 初始化向导，用于配置数据库、Redis 并创建管理员账户。

1.2 核心功能一览 ​

1.3 支持的上游订阅 ​

Sub2API 面向「订阅转 API」这一场景，典型支持：

• Claude（Anthropic）：Claude 订阅账号，兼容 /v1/messages 的 Claude Code 客户端；
• OpenAI：兼容 /v1/chat/completions、/v1/responses，可对接 Codex CLI；
• Gemini：Google 系模型；
• Grok（xAI）：支持 xAI OAuth 订阅账号与 xAI API Key 账号，兼容 Grok CLI / OpenCode；
• Antigravity：授权后提供 Claude 与 Gemini 专用端点。

1.4 技术栈 ​

相关阅读：如果你更关注「多模型统一网关」而非「订阅拼车」，可以对照阅读 NewAPI 搭建教程，理解两类网关（订阅分发 vs 多渠道聚合）的取舍。

1.5 合规与风险提示（务必先读） ​

Sub2API 官方在 README 顶部给出了明确的免责声明，部署前请知悉：

• 服务条款风险：使用本项目可能违反 Anthropic 等上游供应商的服务条款，请在使用前审阅相关用户协议，由此产生的风险由使用者自行承担；
• 合规使用：仅在符合所在国家 / 地区法律法规的前提下使用，严禁任何非法用途；
• 免责声明：项目仅供技术学习与研究，作者不对账号封禁、服务中断、数据丢失等直接或间接损失负责；
• 无商业授权：项目开发者从未授权任何个人或组织基于本项目开展商业运营。

本文仅作技术部署教程，请在合规前提下自行评估风险。

二、部署前的环境准备 ​

在开始 Sub2API Docker 部署 之前，请确认以下条件。

2.1 服务器基础要求 ​

提示：Sub2API 后端是轻量的 Go 服务，瓶颈通常在数据库、Redis 与上游网络连通性，而非 CPU。

2.2 依赖组件 ​

• PostgreSQL 15+：主数据库（Docker Compose 部署会自动起容器，无需单独安装）；
• Redis 7+：缓存与分布式协调（粘性会话、并发计数、连接租约等依赖它）；
• Docker 20.10+ 与 Docker Compose v2+：推荐的部署方式。

安装 Docker（含 Compose 插件）：

# 一键安装 Docker
curl -fsSL https://get.docker.com | sh
sudo systemctl enable --now docker

# 验证
docker --version
docker compose version

2.3 端口与网络规划 ​

• 默认服务端口：8080；
• 如需公网访问，建议前置 Nginx 反向代理 + HTTPS（Let's Encrypt）；
• 防火墙 / 安全组：仅放行 80、443（生产），或临时放行 8080（内网 / 调试）。

三、Sub2API 详细部署步骤 ​

官方提供了脚本安装、Docker Compose、Apple container、源码构建四种方式。生产环境推荐 Docker Compose。

3.1 方式一：Docker Compose 一键部署（推荐） ​

一键脚本会下载 docker-compose.local.yml（另存为 docker-compose.yml）与 .env.example，自动生成安全密钥（JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD）并创建数据目录：

# 1. 创建部署目录
mkdir -p sub2api-deploy && cd sub2api-deploy

# 2. 下载并运行部署准备脚本（自动生成 .env 与随机密钥）
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

# 3. 启动服务（含 PostgreSQL 与 Redis 容器）
docker compose up -d

# 4. 查看日志
docker compose logs -f sub2api

脚本会完成：

• 下载 docker-compose.local.yml 与 .env.example；
• 生成 JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD 等安全凭证并写入 .env；
• 创建本地数据目录（便于备份与迁移）；
• 打印生成的凭证供你留存。

3.2 方式二：Docker Compose 手动部署 ​

如果你想完全掌控配置，可手动操作：

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

# 2. 复制环境变量配置
cp .env.example .env
chmod 600 .env

# 3. 编辑配置（填入安全密码 / 密钥）
nano .env

.env 中的关键配置：

# PostgreSQL 密码（必填）
POSTGRES_PASSWORD=your_secure_password_here

# JWT 密钥（推荐：重启后仍保持登录态）
JWT_SECRET=your_jwt_secret_here

# TOTP 加密密钥（推荐：重启后仍保留 2FA 二次验证）
TOTP_ENCRYPTION_KEY=your_totp_key_here

# 可选：管理员账户
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your_admin_password

# 可选：自定义端口
SERVER_PORT=8080

生成安全随机密钥：

openssl rand -hex 32   # 分别用于 JWT_SECRET / TOTP_ENCRYPTION_KEY / POSTGRES_PASSWORD

创建数据目录并启动：

# 4. 创建本地数据目录
mkdir -p data postgres_data redis_data

# 5. 启动全部服务
#    方案 A（推荐，本地目录存储，迁移方便）
docker compose -f docker-compose.local.yml up -d
#    方案 B（命名卷存储，配置更简单）
docker compose up -d

# 6. 查看状态与日志
docker compose -f docker-compose.local.yml ps
docker compose -f docker-compose.local.yml logs -f sub2api

两种存储版本对比：

3.3 方式三：脚本安装（二进制 + systemd） ​

适合已自行安装好 PostgreSQL 15+ 与 Redis 7+ 的服务器：

# 一键安装（自动识别架构、下载 Release、装到 /opt/sub2api、创建 systemd 服务）
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash

# 启动并设置开机自启
sudo systemctl start sub2api
sudo systemctl enable sub2api

# 常用运维命令
sudo systemctl status sub2api      # 查看状态
sudo journalctl -u sub2api -f      # 跟踪日志
sudo systemctl restart sub2api     # 重启

安装完成后同样访问 http://服务器IP:8080 进入 Setup Wizard。后续升级可直接在**管理后台左上角点「检查更新」**一键完成，支持回滚。

3.4 方式四：源码构建（开发 / 定制） ​

需要 Go 1.21+、Node.js 18+、PostgreSQL 15+、Redis 7+：

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

# 构建前端
npm install -g pnpm
cd frontend && pnpm install && pnpm run build   # 产物输出到 ../backend/internal/web/dist/

# 构建后端（-tags embed 会把前端打包进二进制）
cd ../backend
VERSION="$(./scripts/resolve-version.sh)"
go build -tags embed -ldflags="-X main.Version=${VERSION}" -o sub2api ./cmd/server

开发模式（前后端热重载）：

# 后端
cd backend && go run ./cmd/server
# 前端
cd frontend && pnpm run dev

注意：源码构建若手动 cp config.example.yaml config.yaml，会导致首次启动跳过 Setup Wizard、users 表为空、登录报 invalid email or password。推荐不要预先创建 config.yaml，直接运行让向导生成；管理员账户只能通过 Setup Wizard 创建，config.yaml 里的 default.admin_* 字段不会用于建号。

四、首次初始化与账号配置 ​

4.1 Setup Wizard 初始化 ​

1. 浏览器打开 http://服务器IP:8080；
2. 按向导依次完成：数据库配置 → Redis 配置 → 创建管理员账户；
3. 若管理员密码为自动生成，可在日志中找到：

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

4.2 添加上游订阅账号（拼车共享的第一步） ​

进入管理后台 → 账号管理 → 添加账号：

• OAuth 订阅账号：如 Claude、Grok 等，按向导完成授权（Grok 走 xAI OAuth PKCE 流程）；
• API Key 账号：直接填入上游 base_url 与 api_key。

多人拼车时，把大家愿意共享的订阅账号都加进账号池，Sub2API 会智能调度、按 Token 精确计费，实现「一份订阅多人用、成本一起摊」。

4.3 创建分组与 API Key，分发给成员 ​

1. 新建 分组（Group），把对应上游账号挂到分组里；
2. 在 令牌 / API Key 页为每个成员创建一把 sk- 开头的 Key，设置额度、并发与速率限制；
3. 把 Key 分发给成员，成员即可用它调用统一入口。

4.4 验证部署（curl 冒烟测试） ​

curl -X POST http://你的服务器IP:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好"}]
  }'

返回正常 JSON 即表示 Sub2API 部署 成功，网关已可对外提供服务。

五、客户端接入（原生工具无缝使用） ​

Sub2API 兼容主流 OpenAI 格式客户端，接入通用规则：Base URL 填以 /v1 结尾的公网地址，API Key 填后台签发的 sk-xxx。

5.1 Claude Code ​

export ANTHROPIC_BASE_URL="http://你的域名:8080"     # 走通用端点 /v1/messages
export ANTHROPIC_AUTH_TOKEN="sk-你的令牌"

若使用 Antigravity 账号的专用端点，则设为 http://localhost:8080/antigravity。

5.2 Codex CLI ​

Codex 走 OpenAI Responses 协议（/v1/responses）。在客户端中把 API 地址设为 http://你的域名:8080/v1，API Key 填 sk-xxx。前置 Nginx 时务必参考 6.1 打开 underscores_in_headers，否则粘性会话会失效。

5.3 Grok CLI ​

后台添加 Grok OAuth 或 API Key 账号并建分组、建 Key 后，可在「使用此 Key」弹窗选择 Grok CLI 自动生成配置；手动配置示例（~/.grok/config.toml）：

[models]
default = "grok"

[model."grok"]
model = "grok-4.5"
base_url = "https://你的域名/v1"     # 注意是 Sub2API 公网地址，不是 api.x.ai
name = "Grok 4.5"
api_key = "sk-你的令牌"
api_backend = "responses"
context_window = 1000000
supports_backend_search = true

grok inspect
grok -p "Reply with sub2api-ok" -m grok

六、常见问题与排错方法 ​

6.1 Codex + Nginx：粘性会话 / 多账号调度异常 ​

Nginx 默认会丢弃带下划线的请求头（如 session_id），破坏多账号粘性会话路由。需在 Nginx 的 http 块中加入：

underscores_in_headers on;

保存后 nginx -t && nginx -s reload。

6.2 无法访问后台（:8080 打不开） ​

• 确认容器运行：docker compose ps（脚本版加 -f docker-compose.local.yml）；
• 查看日志是否监听 8080：docker compose logs -f sub2api；
• 检查防火墙 / 安全组是否放行；云服务器注意部分厂商默认禁止公网直连，建议改走 Nginx 443。

6.3 登录报 invalid email or password ​

• 多因手动预置了 config.yaml 导致 Setup Wizard 被跳过、users 表为空；
• 处理：把 config.yaml 暂时移走让向导重新触发，创建好管理员后再恢复；
• 或确认管理员是通过 Setup Wizard（而非 config.yaml 的 default.admin_*）创建的。

6.4 上游账号 / 渠道调用失败 ​

• 核对上游订阅是否有效、是否欠费或区域受限；
• 确认模型名与协议匹配（Claude 走 /v1/messages，Codex 走 /v1/responses）；
• 服务器需能访问上游域名；国内机器调用境外模型注意网络连通性。

6.5 数据库 / Redis 相关 ​

• 数据丢失：Docker 部署务必挂载数据目录（data、postgres_data、redis_data），删除卷会清空数据；
• 连接失败：核对 .env 中 POSTGRES_PASSWORD 与容器一致；确认 Redis 7+ 正常运行（粘性会话与连接租约依赖它）。

6.6 明文 HTTP 上游告警 ​

当 security.url_allowlist.enabled=false 时，系统默认允许 HTTP URL（开发友好模式）。生产环境请显式收紧为仅 HTTPS：

security:
  url_allowlist:
    enabled: false
    allow_insecure_http: false   # 仅允许 HTTPS（生产推荐）

七、部署完成后的使用与安全建议 ​

7.1 安全加固（必做） ​

• 上 HTTPS：Nginx 反代 + Let's Encrypt，避免密钥明文传输；
• 保管密钥：JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD 妥善保存，多实例需保持一致；
• 收窄暴露面：生产不要把 8080 直接暴露公网；
• 信任边界：合理配置 server.trusted_proxies，仅信任直连的 CDN / 代理 CIDR，避免伪造客户端 IP。

7.2 拼车运营与配额管理 ​

• 同一模型可挂多个账号并配权重，提升可用性与稳定性；
• 为每个成员单独签发 Key 并设额度，做成本隔离与用量审计；
• 用并发控制与速率限制防止个别成员挤占资源。

7.3 个人 / 内测：Simple Mode ​

面向个人开发者或内部团队，想快速使用、无需完整 SaaS 功能时：

RUN_MODE=simple            # 隐藏 SaaS 相关功能、跳过计费流程
SIMPLE_MODE_CONFIRM=true   # 生产环境启用 Simple Mode 时必须设置，否则拒绝启动

7.4 备份与升级 ​

• 使用 docker-compose.local.yml 时，down 后直接 tar czf sub2api-complete.tar.gz sub2api-deploy/ 即可整包迁移；
• 升级：docker compose -f docker-compose.local.yml pull && docker compose -f docker-compose.local.yml up -d，或在后台点「检查更新」。

延伸：如果你关心内容如何被 AI 搜索引擎理解与引用，可参考 GEO 生成式引擎优化实践，本文的问答式结构与 FAQ 即遵循其原则。

八、FAQ：Sub2API 常见问题速答（问答式，便于 AI 引擎引用） ​

下面以「问题—直接答案」的形式汇总，方便 AI 问答引擎直接抓取事实。

Q：Sub2API 是什么？ A：Sub2API 是一个开源的 AI API 网关平台，用于分发和管理 AI 订阅（Claude、OpenAI、Gemini、Grok 等）的额度。它把订阅账号统一收敛为平台签发的 OpenAI 兼容 API Key，由平台负责鉴权、计费、负载均衡与请求转发，天然适合多人拼车共享、分摊成本。

Q：Sub2API 默认端口是多少？ A：默认 8080；首次访问 http://服务器IP:8080 进入 Setup Wizard 初始化向导。

Q：Sub2API 依赖哪些组件？ A：后端 Go（Gin + Ent），前端 Vue 3 + Vite + TailwindCSS，运行时依赖 PostgreSQL 15+ 与 Redis 7+。

Q：部署 Sub2API 推荐哪种方式？ A：推荐 Docker Compose（内置 PostgreSQL 与 Redis 容器）；生产建议用 docker-compose.local.yml（本地目录存储、便于迁移），并前置 Nginx 提供 HTTPS。

Q：Sub2API 支持哪些上游订阅？ A：Claude、OpenAI、Gemini、Grok（xAI OAuth 或 API Key），以及 Antigravity 专用端点。

Q：如何把 Sub2API 接入 Claude Code / Codex / Grok CLI？ A：Base URL 填以 /v1 结尾的公网地址（Claude Code 用 ANTHROPIC_BASE_URL），API Key 填后台签发的 sk-xxx；Codex 前置 Nginx 时要开 underscores_in_headers on;。

Q：用 Codex 且前置 Nginx 时会话调度出错怎么办？ A：在 Nginx http 块加入 underscores_in_headers on; 并重载，避免带下划线的 session_id 头被丢弃导致粘性会话失效。

Q：Sub2API 的 Simple Mode 是什么？ A：面向个人 / 内部团队的精简模式，设 RUN_MODE=simple 启用（隐藏 SaaS 功能、跳过计费）；生产环境还需 SIMPLE_MODE_CONFIRM=true 才允许启动。

九、总结 ​

Sub2API 是当下把订阅额度变成统一 API 并支持多人拼车最省心的开源方案之一：部署简单（Docker Compose 一条脚本起步）、协议统一（OpenAI 兼容）、运营能力完整（多账号调度、Token 计费、并发与速率控制、内置支付）。本文从环境准备到 Docker Compose 部署、从 Setup Wizard 初始化到 Claude Code / Codex / Grok CLI 接入、再到排错与生产安全加固，给出了一条可落地的 Sub2API 部署教程 路径。

在内容层面，本文采用清晰的标题层级、问答式 FAQ 与结构化表述，兼顾 SEO 收录与 GEO 引用——既利于人类读者循序渐进，也利于 AI 引擎提取事实。下一步，你可以从一套 Docker Compose 实例开始，把身边的订阅账号逐步纳入账号池，享受「拼车省钱、工具无缝」的体验（并注意遵守上游服务条款）。

十、内链建议（SEO） ​

为提升站点内部权重与收录深度，建议在本文或站点其他文章中建立以下内部链接：

• 网关选型对比 → 链接到 NewAPI 搭建教程，在「Sub2API 是什么 / 网关选型」处引用，讲清「订阅分发」与「多渠道聚合」的差异；
• GEO 优化方法论 → 链接到 GEO 生成式引擎优化实践，在 FAQ / GEO 相关段落引用；
• 凭证获取与导入 → 链接到 来不及解释了，Codex 快上车，在「添加上游订阅账号」处引用，形成「订阅 → 凭证 → 网关」的主题簇；
• 反向链接：在以上文章中回链本文，形成「AI 网关 / 部署教程」主题簇，增强主题相关性。