Sub2API 进阶指南：把订阅额度经营成一台可靠的 API 网关

Sub2API 是一个开源的 AI API 网关：把 Claude、OpenAI、Gemini、Grok 等订阅账号统一接入，转换成可分发的 API Key，由平台负责鉴权、计费、负载均衡和请求转发。入门教程网上已经很多——装 Docker、跑容器、加账号、发 Key，五步走完就能用。

所以这篇不重复入门，只讲中间那段路——从「能跑起来」到「经营得好」。全文以官方 README（LGPL-3.0 开源）为基准写成，配置项名称都可直接对照。

⚠️ 先说清楚：这类工具的使用可能违反上游服务商的用户协议，账号被封的风险自担。本文只谈技术，请务必遵守你所在地区的法规与上游条款。

一、部署：选对姿势，少一半坑

Sub2API 技术栈是 Go + Vue 3 + PostgreSQL 15+ + Redis 7+，官方给了四条部署路线：

方式	适合谁	一句话点评
脚本安装（systemd）	有现成 PG/Redis 的 Linux 老手	二进制 + systemd，升级靠面板一键
Docker Compose	绝大多数人	连 PG/Redis 一起编排，最省心
Apple container	macOS 26 + Apple Silicon	本地折腾用，生产仍推荐 Compose
源码编译	二次开发	`-tags embed` 才会内嵌前端

选 Compose 的话，强烈建议用 docker-compose.local.yml 这一份（一键脚本默认就是它）：数据全部落在本地目录（data/、postgres_data/、redis_data/），备份和迁移就是打包一个文件夹的事：

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

脚本会自动生成 JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD 并写进 .env。手动部署的话，这三个值记得自己生成：

openssl rand -hex 32   # 每个密钥来一次

两个高频坑，提前绕开：

管理员账号只能由 Setup Wizard 创建。首次启动时访问 http://服务器IP:8080 完成初始化向导。如果你手动预置了 config.yaml，向导会被跳过，首次登录必然报 invalid email or password——把配置文件临时挪开、让向导跑完再恢复即可。另外 ADMIN_EMAIL 别图省事写成 admin@example.com，这是爆破工具的第一词典。
Nginx 反代必须加 underscores_in_headers on;。Nginx 默认丢弃带下划线的请求头（比如 session_id），而 Sub2API 的多账号粘性会话恰好靠它——不加这行，你会遇到「明明有多个账号，会话却频繁切换」的灵异现象。

二、账号池治理：从「能用」到「稳定」

账号支持 OAuth 和 API Key 两种接入，进阶的关键不在「加进来」，而在调度健康度：

Sub2API 管理控制台：用量统计、模型分布与 Token 趋势

并发限制双层生效：默认每个用户 user_concurrency: 5，账号维度还有独立上限。拼车场景务必压低账号并发——它直接决定上游风控视角下你的「体感」。
理解平台的错误处理策略，这决定了你该怎么配账号：401 会把凭证失效的账号临时摘出调度；403 被视为权益问题而不是「刷新令牌能解决的事」，别对着它反复重试；429 按 Retry-After 或短冷却摘除。看到账号频繁 429，正确的动作是加账号或降并发，而不是换 IP 硬刚。
粘性会话（sticky session）是朋友：同一会话固定走同一账号，对上游的缓存命中和风控都更友好。这就是第一节的 Nginx 配置如此重要的原因。

一个经验法则：账号池的正确扩张信号是「429 频率持续上升」，而不是「总觉得不够快」。

三、分组与路由：复合分组是灵魂

普通分组就是账号池：一组账号服务一组模型。
复合分组（Composite Groups） 是管理员的「路由层」：把请求里声明的模型解析到具体的上游供应商，适合多供应商混跑的场子——一个 Key 对外，后面几路账号各司其职。
Antigravity 混合调度要小心：开启后通用端点也会把请求路由到 Antigravity 账号，但官方明确警告——Anthropic Claude 和 Antigravity Claude 不能混在同一个会话上下文里。解法就一个字：分组隔离，别让两种来源接力同一段对话。
个人用户看看 Simple Mode：RUN_MODE=simple 隐藏 SaaS 功能、跳过计费流程，适合个人或内部团队。注意两点：生产环境启动需要 SIMPLE_MODE_CONFIRM=true 确认；SIMPLE_MODE_KEY_RATE_LIMIT_ENABLED=true 可以启用每个 Key 的 5 小时 / 每日 / 7 日消费窗口——这是防止单个 Key 失控烧额度的好开关。

四、API Key 运营：Key 就是你的产品

对外分发的每个 Key 都是可运营的对象：

Token 级计费：每个请求的输入、输出、缓存读写分开计量，成本一目了然（见上面仪表盘截图的模型分布与 Token 趋势）。
rate_multiplier 倍率：给不同用户组设置计费倍率，是「拼车分摊」的核心旋钮。
双层限流：请求数速率 + Token 速率都可以按 Key 配置，先限流再谈信任。
内置支付：EasyPay、支付宝、微信、Stripe 都能接，用户自助充值——但这是「有一点规模之后」的事，三五好友拼车用 Simple Mode 足够，别一上来就把运维复杂度拉满。

五、客户端接入速查

Claude Code：

export ANTHROPIC_BASE_URL="https://你的域名"
export ANTHROPIC_AUTH_TOKEN="sk-你的sub2api密钥"

Grok CLI：在用户 API Key 页点「使用 Key」选 Grok CLI，会自动生成 ~/.grok/config.toml；手写的话核心是 base_url 指向你的 Sub2API 地址加 /v1，model 填 grok-4.5 这类上游模型名。
Codex / Responses 走 WebSocket 老是重连？ 这是上游 WS 不稳的典型症状，全局兜底开关了解一下：
```
# .env 里持久化，别只在容器里改
GATEWAY_OPENAI_WS_FORCE_HTTP=true
```
它把 OpenAI Responses 上游流量切到 HTTP/SSE，客户端协议不变。

六、安全清单：发车前最后一遍检查

Sub2API 系统设置的安全认证页：管理员 API Key、开放注册、邮箱白名单与 2FA

（截图来自网络教程，仅作示意。）

生产环境关掉 HTTP 上游：security.url_allowlist.allow_insecure_http: false。默认配置对开发友好、允许明文——API Key 裸奔在公网上等着被中间人截胡。
trusted_proxies 只填直连的代理网段，并关掉 legacy 转发头接管（security.trust_forwarded_ip_for_api_key_acl），否则客户端 IP 可以被伪造，限流和风控形同虚设。
开 2FA。这就是 .env 里 TOTP_ENCRYPTION_KEY 的意义所在——不设它，服务一重启双因素就失效。
管理员 API Key 当核武器管理（见截图顶部）：能调系统级接口，非必要不签发。
注册端收紧：对外开放注册时，配邮箱域名白名单 + Turnstile 人机验证；纯自用直接关掉开放注册。
8080 别裸奔：套一层 Nginx/Caddy 做 TLS，.env 记得 chmod 600。

七、运维：升级、备份、迁移

升级：脚本安装的面板左上角有「检查更新」，一键升级还支持回滚；Compose 则是 docker compose pull && docker compose up -d 两条命令的事。
备份：docker-compose.local.yml 版本下，停服 → tar czf sub2api.tar.gz sub2api-deploy/ → 完事。数据库、Redis、配置、密钥全在里面。
迁移到新机：tar 包传过去解压、docker compose up -d，十分钟内满血复活。
看日志：systemd 用 journalctl -u sub2api -f，Compose 用 docker compose logs -f sub2api。

写在最后

Sub2API 这类工具把「搭网关」的门槛降到了零，但网关真正的成本在上线之后：账号健康度要盯、配额要规划、安全习惯要养。工具负责把流量变成账单，而把账单变成可持续的经营，仍然要靠人。

参考与延伸： Wei-Shaw/sub2api（GitHub） · 官方 README 内含 Payment 配置指南、Operator Guide 与 EDGE_SECURITY 文档 · 配图来自公开网络教程，版权归原作者所有。