Sub2API 号池中转站运维手册#

基于开源项目 Wei-Shaw/sub2api（中文说明 README_CN）整理。
定位：订阅转 API / 号池调度——把 ChatGPT Plus、Claude、各类 Coding Plan 等订阅账号池化为统一 API，支持负载均衡、粘性会话、配额分摊。
本项目中角色：副站，作为主站 NewAPI 的一条上游渠道；对外只暴露主站。
默认端口：8080 · 依赖：PostgreSQL + Redis
编码场景默认：ChatGPT Pro 号池（如 Pro20x）+ 每账号独立静态家宽代理。

0 · 文档说明与合规#

合规要点（必读）

• 仅池化自有、合法授权的订阅与账号；共享/拼车须符合各上游服务条款，商用风险自负
• 强烈建议内网部署（NAS / 内网机），仅主站 IP 可访问，避免 Key 与账号泄露
• 生产务必设置强 POSTGRES_PASSWORD、JWT_SECRET、TOTP_ENCRYPTION_KEY，并开 2FA
• 号池生产务必 1 账号 1 静态家宽代理，禁止多号共机房 IP 裸奔（见 §4.4）

副站机器：可与 NewAPI 同机（起步）或独立海外机（日/美）；不要公网裸奔。VPS 规格与港/日分工见架构 §8；出口信誉靠 每号家宽，不靠把 VPS 买很大。

1 · 系统架构#

核心能力（官方）

• 多账号管理（OAuth / API Key 多种上游类型）
• API Key 分发与精确计费（token 级用量）
• 智能调度（账号选择 + 粘性会话）
• 并发控制、限流（按用户 / 按账号）
• IP 管理：为账号绑定 HTTP/SOCKS 等代理出口
• 内置支付（易支付 / 支付宝 / 微信 / Stripe）、管理面板

2 · 核心概念：账号 · 分组 · API Key · 池#

配置规则：分组类型（平台）必须与账号平台一致；API Key 绑定分组——所以要先规划分组，再建账号与 Key。代理在加号时一并绑定。

3 · 部署（Docker Compose）#

官方推荐 Docker Compose（自带 PostgreSQL + Redis）。生产建议用 docker-compose.local.yml（本地目录存数据，便于备份迁移）。

3.1 一键部署（推荐）#

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

# 下载并运行准备脚本（自动生成 .env 与密钥、创建数据目录）
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

# 启动
docker compose up -d

# 查看日志（含自动生成的管理员密码）
docker compose logs -f sub2api

脚本会：下载 docker-compose.local.yml + .env.example、生成 JWT_SECRET / TOTP_ENCRYPTION_KEY / POSTGRES_PASSWORD、建 data/ postgres_data/ redis_data/、打印凭证。

3.2 手动部署#

git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy
cp .env.example .env
chmod 600 .env

# 生成密钥
JWT_SECRET=$(openssl rand -hex 32)
TOTP_ENCRYPTION_KEY=$(openssl rand -hex 32)
echo "JWT_SECRET=${JWT_SECRET}" >> .env
echo "TOTP_ENCRYPTION_KEY=${TOTP_ENCRYPTION_KEY}" >> .env

mkdir -p data postgres_data redis_data
docker compose -f docker-compose.local.yml up -d
docker compose -f docker-compose.local.yml logs -f sub2api

3.3 .env 关键项#

POSTGRES_PASSWORD=强密码           # 必需
JWT_SECRET=hex32                  # 登录态跨重启保持
TOTP_ENCRYPTION_KEY=hex32         # 2FA 跨重启保留
ADMIN_EMAIL=admin@example.com     # 可选
ADMIN_PASSWORD=强密码              # 可选
SERVER_PORT=8080                  # 可选，自定义端口

3.4 初始化管理员#

• 首次访问 http://服务器IP:8080 进入 setup 向导，配置数据库/Redis/管理员
• 若密码自动生成：docker compose logs sub2api | grep "admin password"
• 注意：管理员只能由向导创建；若已存在 config.yaml 会跳过向导，导致 users 表为空、无法登录——此时先移走 config.yaml 触发向导

3.5 部署版本对比#

| 版本 | 数据存储 | 迁移 | 适用 | | --- | --- | --- | | docker-compose.local.yml | 本地目录 | 打包目录即可 | 生产、频繁备份（推荐） | | docker-compose.yml | 命名卷 | 需 docker 命令 | 简单场景 |

3.6 副站落点建议#

4 · 上游账号配置（实操）#

平台类型要选对：调用什么模型就按其接口协议选平台（OpenAI / Anthropic）。

4.1 ChatGPT（OAuth）#

1. 账号管理 → 添加账号 → 名称（如「ChatGPT 主号」）→ 平台 OpenAI → 类型 OAuth
2. 打开弹出的登录地址，登录后得到 http://localhost... 回调地址
3. 完整复制回调地址填回；Team 账号务必选对工作空间
4. 绑定该号专用代理（§4.4）；OAuth 登录与日常调用尽量同一出口
5. 「测试连接」无报错即可用；面板会显示各账号剩余配额

4.2 第三方中转站（API Key）#

• 平台按 Key 对应模型选（Claude → Anthropic；GPT → OpenAI）
• 类型 API Key，填该中转站 Base URL 与 KEY，测试连接
• 若该 Key 本身已是中转，一般不必再套一层家宽（按上游要求）

4.3 云厂商 Coding Plan / 百炼（示例）#

具体 Base URL / 模型名以各厂商最新文档为准；添加后清空默认模型并手动填该账号支持的模型。

4.4 每账号独立家宽 / 住宅代理 IP（强烈推荐）#

号池风控的核心不是「副站 VPS 在哪」，而是 上游看到的出口 IP。Pro / Claude 类订阅对 机房 IP、多号共 IP、IP 乱跳 更敏感。生产建议：

原则：1 账号 ↔ 1 条固定静态家宽（或低共享住宅）代理，禁止多号挤同一出口。

主站 NewAPI →（内网）→ 副站 Sub2API（VPS 可机房 IP）
                            ├─ 账号 A + 代理 A（家宽静态）→ 上游
                            ├─ 账号 B + 代理 B（家宽静态）→ 上游
                            └─ 账号 C + 代理 C（家宽静态）→ 上游

副站机器本身可以是美西/日本普通 VPS；OpenAI/Anthropic 侧看到的是各账号绑定的代理出口，不是 VPS 网卡 IP（账号已绑代理时）。

在 Sub2API 中的配置步骤#

1. 管理端 → IP 管理：添加代理（协议常见 HTTP / SOCKS5，填主机、端口、用户名密码）。
2. 账号管理 → 编辑账号 → 选择该号专用代理（不要只靠系统全局 http_proxy 打全部号）。
3. 可选：环境变量/全局代理仅作兜底；Pro20x 池必须逐号绑定。
4. 维护台账：账号 ID ↔ 代理 ID ↔ 出口 IP ↔ 到期日，避免重复绑定。
5. 代理失效时：先停用该账号，禁止静默回退到 VPS 本机 IP 裸奔。

社区确认：账号勾选代理后出网来源为代理 IP（见上游仓库 IP 管理相关讨论）。批量「IP 池自动一对一分配」以你部署版本面板能力为准；无自动分配则手工/脚本保证不重复。

代理选型#

运维纪律#

• 粘性会话开启：同一对话粘同一账号 → 自然粘同一家宽，避免一轮对话换号又换 IP。
• OAuth 登录 / 日常调用同一出口：绑号与跑量尽量同一条代理，减少环境漂移。
• 并发：单号并发按订阅能力限制；同时受代理商并发与家宽带宽约束。
• 预期：独立家宽是 降风险标配，不是永封免疫；支付渠道、用量、客户端/TLS 特征仍会影响风控。
• 成本：N 个 Pro ≈ N 条静态家宽，这是号池主要固定成本之一。

5 · 分组与 API Key#

5.1 建分组（池）#

• 分组类型 = 账号平台（OpenAI 账号进 OpenAI 分组，Anthropic 进 Anthropic 分组）
• 示例：ChatGPT池(OpenAI)、chatgpt-pro20x(OpenAI)、Claude池(Anthropic)、腾讯Coding(Anthropic)…
• 建完分组后，回账号管理，编辑每个账号，拉到底把它加入对应分组（否则池是空的）

5.2 建 API Key#

• API Key 绑定分组：key-openai → ChatGPT 池；key-pro20x → Pro20x 池；key-claude → Claude 池
• 这把 Key 就是发给主站 NewAPI（或客户端）的凭证
• 可设配额、并发、限流

5.3 编码场景：Pro20x 号池（推荐默认）#

写代码 / Cursor / Agent 等场景，本方案 默认走 ChatGPT Pro 号池（如 Pro20x），而不是自建 Azure 官价渠道：

IDE / Agent → NewAPI（coding 令牌）
                → Priority 高：Sub2API Pro20x 池
                → Priority 低：三方中转（可选 fallback）

并发粗估：有效号数 × 单号可同时会话数（再受家宽/代理限制），不是 Azure TPM 提额模型。

合规：仅池化自有合法授权订阅；共享/商用须自行评估上游条款风险。

:::warning 生图 / 4K 不要默认走 Pro20x 号池是 ChatGPT 订阅会话能力，不是完整 Images API。实测与社区反馈：4K 生图支持差（参数丢失、降采样、超时）。

• 文本编码 → 本池
• 生图（尤其 4K） → Adobe Firefly 网关或 AZ，见架构 §11.5、§12；NewAPI §16.6
• coding 分组 Models 不要填 gpt-image* / 4K 图像模型
  :::

6 · 作为副站对接主站 NewAPI#

推荐拓扑：客户端 → 主站 NewAPI →（内网）副站 Sub2API → 订阅账号池（每号独立家宽代理）。

对接步骤：

1. 在 Sub2API：IP 管理加齐代理 → 建分组/账号 → 每账号绑定独立代理（§4.4）→ 生成给主站用的 API Key
2. 在 NewAPI 新建渠道：
   • 类型：按 Sub2API 分组协议选（OpenAI / Anthropic 兼容）
   • Base URL：副站地址，建议内网（如 http://10.0.0.5:8080），勿公网裸奔
   • Key：Sub2API 发放的 API Key
   • 模型：与该分组账号支持的模型对齐
3. NewAPI 用优先级/权重/分组编排：
   • 编码默认：Pro20x 号池 Priority 高（§5.3）
   • 可选：三方中转低优先级兜底；真 AZ/官方 Key 作后续稳仓
   • 故障时自动切换（NewAPI 渠道禁用 / 重试）

6.1 编码默认对接（Pro20x）#

编码用户令牌只放 coding 分组。号池侧必须已完成 §4.4 每号代理绑定。

详见《AI 中转站架构方案》§10、§11 与《New API 中转站运维手册》「对接 Sub2API 号池渠道」一节。

生图不走本副站：gpt-image-2 / Adobe Firefly 生图见《AI 中转站架构方案》§12 与 NewAPI §16.6；Sub2API 专注文本/订阅号池（Pro20x 等）。

7 · 升级 / 迁移 / 备份#

升级#

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

迁移（本地目录版）#

# 源机
docker compose -f docker-compose.local.yml down
cd .. && tar czf sub2api-complete.tar.gz sub2api-deploy/
scp sub2api-complete.tar.gz user@new-server:/path/
# 新机
tar xzf sub2api-complete.tar.gz && cd sub2api-deploy/
docker compose -f docker-compose.local.yml up -d

常用命令#

docker compose -f docker-compose.local.yml ps
docker compose -f docker-compose.local.yml restart
docker compose -f docker-compose.local.yml logs -f
# 删除全部数据（谨慎！）
docker compose -f docker-compose.local.yml down && rm -rf data/ postgres_data/ redis_data/

8 · 安全与运维要点#

• 内网优先：面板与 API 只在内网 / 白名单开放；公网必须反代 + HTTPS + 限制来源 IP
• 反代注意：保留带下划线的请求头（Nginx underscores_in_headers on;），否则鉴权/回调可能异常
• 密钥隔离：Sub2API 的 DB / JWT / TOTP 密钥与主站分离；副站被打穿不牵连主站用户体系
• 2FA：管理员开启 TOTP；TOTP_ENCRYPTION_KEY 妥善保存
• 每号独立代理：见 §4.4；代理凭证与账号台账同等保密
• 账号健康：无配额账号先「调度」临时禁用，有配额再放出；关注封号/验证码；代理挂了先停号
• 粘性会话：编码/Agent 务必开启，避免同会话跳号跳 IP
• 备份：定期 tar 打包 data/ postgres_data/；升级前先备份

9 · 故障排查速查#

10 · 上线最小路径#

1. Compose 一键部署（PostgreSQL + Redis + sub2api）
2. 向导建管理员，改密，开 2FA
3. IP 管理：按号数量准备并添加静态家宽代理（1 号 1 条）
4. 规划并创建分组（编码用 chatgpt-pro20x）
5. 添加账号：加入分组 + 绑定独立代理 + 逐个「测试连接」（确认出口为家宽）
6. 创建绑定分组的 API Key（仅给主站）
7. （内网）在主站 NewAPI 新增 sub2api-pro20x-coding 渠道，Priority 高
8. 编码令牌走 coding 分组；可选三方中转低优先级兜底
9. 联调 chat/completions；开粘性会话；设单号并发
10. 反代 + 限制来源 IP + 账号/代理台账 + 备份计划

11 · 参考链接#

本文结合 Sub2API 公开文档与社区教程整理，项目迭代较快，具体字段与 Base URL 以你部署的版本与各上游最新文档为准。