Sub2API 部署实战：把订阅额度收进一个自建网关，以及它的合规边界

1 查看Sub2APIAI网关自建部署Docker Compose账号池

Sub2API 是把 Claude、OpenAI、Gemini 订阅统一成 API 入口的开源网关。本文记录 v0.2.0 从零装起来的全过程：Docker Compose 与二进制两条路线、安装向导四步、进后台前必须手打的合规确认、账号池和分组怎么配，以及为什么这个项目的作者自己在 README 第一段就写了封号风险。

先把最重要的一句放在最前面：Sub2API 的作者在 README 的第一个小节就写了「使用本项目可能违反 Anthropic 等上游供应商的服务条款，风险由使用者自行承担」。 这不是我加的免责声明，是项目自己写的。后面还有一条「从未授权任何个人或组织基于本项目进行任何形式的商业运营」。

我把这段前置，是因为这个项目在中文社区的讨论里，「拼车」「分摊成本」这些词出现的频率远高于风险提示，很容易让人以为装上就是白赚。它的实际定位是：一个把 AI 产品订阅额度转成 API 配额并分发出去的[网关](/wiki/ai-gateway)——技术上做得相当扎实，用途上的边界需要你自己划。

本文记录的是 v0.2.0（2026-09-02 发布）从零装到能进后台的完整过程。项目仓库 Wei-Shaw/sub2api 用 LGPL-3.0 开源，后端 Go + Gin + Ent，前端 Vue 3 + Vite，依赖 PostgreSQL 15+ 和 Redis 7+，核对时约 4 万 star。

它和一般的 AI 网关差在哪

成员 A 的 Key GW 成员 B 的 Key 内部服务 调度层分组 · 粘性会话 · 并发与限流 账号池 Claude 订阅账号 OpenAI 账号 Gemini 账号 PostgreSQL 用量与计费Redis 会话与限流

图 1：请求路径。下游拿到的是网关签发的 Key，上游账号被收进一个池子里由调度层挑选；每次转发的 token 用量都会记进 PostgreSQL。

和 LiteLLM 那种「面向应用」的网关比，Sub2API 的重心明显偏向运营：它有用户体系、分组套餐、兑换码、促销码、内置支付（易支付、支付宝、微信、Stripe），后台菜单里「充值」相关的项比「模型」相关的还多。这套东西对个人自用是纯负担，对想开一个内部服务的人则是现成的。

另一个关键差别是账号池加粘性会话。上游是订阅账号而不是 API Key，同一段对话中途换账号会导致上下文错乱，所以调度层要保证一次会话粘在同一个账号上，同时还要在账号被限速时切走。这是这类项目真正的技术难点。

两条部署路线

官方给了四种装法，实际值得考虑的是两种。

路线适合代价
Docker Compose绝大多数情况，一条脚本连 PostgreSQL、Redis 一起起需要能拉到 Docker Hub 镜像
二进制 + systemd已有独立的 PG/Redis，或者拉不动镜像数据库和 Redis 要自己准备
Apple containermacOS 26 上的原生容器栈无常驻守护，重启后要手动 up
源码编译要改代码Go 1.27 + pnpm 全套工具链

路线一：Docker Compose

mkdir -p sub2api-deploy && cd sub2api-deploy
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

这个脚本会下载 docker-compose.local.yml 和 .env.example，自动生成 JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD 三个密钥写进 .env，并建好数据目录。把它打印出来的凭据存好，尤其是数据库密码。

管道执行远程脚本这件事，稳妥的做法是先下下来读一遍再跑：

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh -o docker-deploy.sh
less docker-deploy.sh
chmod +x docker-deploy.sh && ./docker-deploy.sh

然后启动：

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

为什么是 `docker-compose.local.yml` 而不是 `docker-compose.yml`：前者把数据放在当前目录的 data/、postgres_data/、redis_data/ 三个文件夹里，迁移时 tar 打包整个目录就完事；后者用 Docker 命名卷，搬家得走 docker 命令导出。官方也推荐前者。

没设 ADMIN_PASSWORD 的话，管理员密码是自动生成的，在日志里：

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

路线二：二进制

Linux 服务器上一条命令：

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash
sudo systemctl enable --now sub2api

脚本会识别架构、拉 Release、装到 /opt/sub2api、生成 systemd 单元。前提是 PostgreSQL 15+ 和 Redis 7+ 已经跑起来了。

Releases 页面同时提供 darwin_arm64 / darwin_amd64 的包，我这次就是用它在 macOS 上跑的——拉不动 Docker Hub 镜像的时候，这是个可行的退路：

tar xzf sub2api_0.2.0_darwin_arm64.tar.gz
./sub2api -version
# Sub2API 0.2.0 (commit: aa236488..., built: 2026-09-02T03:13:57Z)
./sub2api

首次启动没有配置文件时，它会进向导模式：

First run detected, starting setup wizard...
Setup wizard available at http://127.0.0.1:8080

安装向导四步

Sub2API 安装向导第一步的界面，顶部是 Database Configuration、Redis Configuration、Admin Account、Ready to Install 四个步骤指示，下方是主机、端口、用户名、密码、数据库名和 SSL 模式的表单，底部是 Test Connection 按钮

Sub2API 安装向导第一步的界面，顶部是 Database Configuration、Redis Configuration、Admin Account、Ready to Install 四个步骤指示，下方是主机、端口、用户名、密码、数据库名和 SSL 模式的表单，底部是 Test Connection 按钮

图 2：向导第一步。每一步都有独立的连通性测试，别跳过 Test Connection——这里失败比装完之后再排查便宜得多。

四步分别是数据库、Redis、管理员账号、确认安装，界面上的按钮背后就是 /setup/test-db、/setup/test-redis、/setup/install 三个接口。填完点安装，它会建表、跑迁移、写出 config.yaml，然后提示服务将自动重启。

这里有个只在非 Linux 上出现的行为：日志会打一行

Service restart via exit only works on Linux with systemd

也就是说 macOS 上它不会真的重启，得自己 Ctrl-C 再起一次。Linux + systemd 环境下由 systemd 接管，不用管。

官方 README 里那个坑，真的会踩

源码编译或手工准备配置的人特别容易中招：如果你在第一次启动前就把 `config.example.yaml` 复制成了 `config.yaml`，向导会被跳过。 程序检测到配置存在就直接进正常模式，而 users 表是空的，于是第一次登录必然报 invalid email or password。

config.yaml 里那两个 default.admin_email / default.admin_password 字段是历史遗留，不会被用来创建管理员。解法是把配置挪开让向导跑一次：

mv config.yaml config.yaml.bak
./sub2api          # 向导跑完会写一份新的 config.yaml
# Ctrl-C 停掉
mv config.yaml.bak config.yaml
./sub2api          # 用刚建的管理员登录

Docker 路线不会遇到这个，因为 compose 里设了 AUTO_SETUP=true，初始化全自动。

进后台前，先手打一段话

登录之后不会直接看到控制台，而是一道合规确认：

Sub2API 后台的部署与运营合规确认页，标题为 Deployment and Operation Compliance Acknowledgment，上方是黄色警告条，下方要求逐字输入确认短语，页面中央叠着一个介绍核心功能的欢迎弹窗

Sub2API 后台的部署与运营合规确认页，标题为 Deployment and Operation Compliance Acknowledgment，上方是黄色警告条，下方要求逐字输入确认短语，页面中央叠着一个介绍核心功能的欢迎弹窗

图 3：进控制台前的合规确认。必须逐字输入指定短语才能通过，协议版本变更后还要再确认一次。图中央是可以跳过的功能引导弹窗。

需要一字不差地输入一句话，才能点亮「Acknowledge and Continue」。这个设计我觉得值得夸一句：它不是勾选框，是强制你至少把那段话读一遍。文档版本（页面上标的是 v2026.06.10）更新后，所有控制台用户要重新确认。

从产品角度这是作者在给自己做风险隔离，从使用者角度它传达的信息很明确——这个项目的合规责任在部署方身上，不在作者身上。

后台在管什么

Sub2API 管理后台首页，顶部一排统计卡片显示 API Keys、Accounts、Today Requests、Users、Today Tokens、Total Tokens、Performance 与 Avg Response，下方是快捷操作和按小时粒度的用量图表，因为是全新实例所以数据均为零

Sub2API 管理后台首页，顶部一排统计卡片显示 API Keys、Accounts、Today Requests、Users、Today Tokens、Total Tokens、Performance 与 Avg Response，下方是快捷操作和按小时粒度的用量图表，因为是全新实例所以数据均为零

图 4：全新实例的管理后台首页。左侧菜单从 Dashboard、Users、Groups、Channels 一直排到 Redeem Codes、Promo Codes、Audit Logs——运营向的功能占了大半。

真正要理解的是三层数据模型：

  • Accounts（账号）：上游的订阅或 API Key，是成本来源。
  • Groups（分组）：套餐层。把若干账号编成一组，定价格、限速、可用模型，再把用户放进组里。VIP 组用好账号、试用组用便宜账号，这层就是干这个的。
  • Users / API Keys：下游。每个用户拿到自己的 Key，用量和额度按人算。

想跳过整套 SaaS 功能的话，有个开关：

RUN_MODE=simple
SIMPLE_MODE_CONFIRM=true   # 生产环境必须一起设，否则拒绝启动

Simple Mode 会藏掉计费、套餐这些东西，只保留网关本身。个人自用或小团队内部用，从这个模式起步更清爽。

加账号：平台和接入方式是两个维度

Sub2API 的 Create Account 弹窗，第一步选择授权方式：Platform 一行列出 Anthropic、OpenAI、Gemini、Antigravity、Grok、Kimi、Zhipu GLM、DeepSeek，Account Type 一行列出 Claude Code、Claude Console、AWS Bedrock、Vertex 四种，最下面是 OAuth 与 Setup Token 两种添加方式

Sub2API 的 Create Account 弹窗，第一步选择授权方式：Platform 一行列出 Anthropic、OpenAI、Gemini、Antigravity、Grok、Kimi、Zhipu GLM、DeepSeek，Account Type 一行列出 Claude Code、Claude Console、AWS Bedrock、Vertex 四种，最下面是 OAuth 与 Setup Token 两种添加方式

图 5：加账号的第一步。选完平台之后，Account Type 那一排会跟着变——同样是 Anthropic，走 Claude Code 订阅、Claude Console 的 API Key、AWS Bedrock 还是 Vertex，是四条完全不同的路。

这张图基本把这个项目的能力边界画出来了：平台覆盖 Anthropic、OpenAI、Gemini、Antigravity、Grok、Kimi、智谱 GLM、DeepSeek；Anthropic 一侧支持 Claude Code 的 OAuth 与 Setup Token、Claude Console 的 API Key、AWS Bedrock 和 Vertex 四种接入。订阅类走 OAuth，标准 API 类填 Key，这是两类完全不同的凭据，混在一个池子里就需要靠分组隔离。

Antigravity 账号还有专用端点，Claude Code 这样接：

export ANTHROPIC_BASE_URL="http://localhost:8080/antigravity"
export ANTHROPIC_AUTH_TOKEN="sk-你的网关key"

官方明确警告过：Anthropic 原生 Claude 和 Antigravity 的 Claude 不能在同一段对话上下文里混用，必须用分组隔开，否则会话会乱。

上生产之前必须处理的几件事

启动日志里那几条 WARN 不是噪音，每一条都对应一个待办：

Warning: JWT secret auto-generated. Consider setting a fixed secret for production.
Warning: CORS allowed_origins not configured; cross-origin requests will be rejected.
Warning: server.trusted_proxies is not configured
payment encryption/signing key is not explicitly configured; set TOTP_ENCRYPTION_KEY

对应的处理：

  1. `JWT_SECRET` 和 `TOTP_ENCRYPTION_KEY` 必须固定。 自动生成意味着每次重启都换——用户全被登出，两步验证也会失效。openssl rand -hex 32 生成后写进 .env。
  2. `trusted_proxies` 要按你的反代拓扑填。 不填的话限流和审计记到的都是反代的 IP，等于按 IP 做的所有策略全废。
  3. Nginx 反代要加 `underscores_in_headers on;`（放在 http 块）。Nginx 默认会丢掉带下划线的请求头，而多账号粘性会话依赖 session_id 这个头——不加这一行，Codex CLI 的会话会在账号之间乱跳，而且这种故障非常难查。
  4. 不要把 8080 直接暴露到公网。 前面挂反代 + HTTPS，管理后台的路径最好再加一层访问控制。
  5. `.env` 权限设 600。 里面是数据库密码和所有密钥。

谁适合用，谁应该绕开

适合：需要在一个团队或一个小圈子内部统一管理多个上游账号、并且要求用量可归因的人。它的账号池调度、粘性会话、分组定价、审计日志这一套，自己写要花不少时间。

应该绕开：

  • 只有自己一个人用的——这套东西太重了。装 PostgreSQL 和 Redis 只为了自己调 API，性价比很低，看 9Router 或 LiteLLM。
  • 打算靠它对外卖号或做「拼车」生意的——作者已经明说没有授权任何商业运营，上游厂商的条款也普遍禁止账号共享。技术能跑通不代表这件事没有后果，被封的是你的账号，不是仓库作者的。
  • 在合规要求严格的公司里——把员工个人订阅接进公司系统，是一个需要法务先看一眼的决定。

另外提醒一句：README 里写明官方只使用 sub2api.org 和 pincc.ai 两个域名，其他打着这个名义的站点与项目无关。GitHub 上同名 fork 也不少，装之前确认仓库归属。

替代方案

  • [LiteLLM](/articles/litellm-gateway-deployment-guide)：面向应用的网关，虚拟 Key、预算、路由策略都更工程化，但不支持用订阅账号的 OAuth 当上游。
  • New API / One API：同样有用户体系和充值，中文生态成熟，上游以标准 API Key 为主。见中转站搭建指南。
  • 各厂商的官方团队版：Anthropic、OpenAI 都有正规的团队/企业方案，贵一些，但没有条款风险，也不用自己运维。真要给团队用，先把这条算过再说。

参考来源与核对方式

界面截图、启动日志和向导流程来自 2026-09-04 在本机跑通的 v0.2.0。版本号、支持的平台名单、合规文档版本和环境变量清单都是易变信息——这个项目的发版频率是以天计的，照抄本文命令前请先看一眼你下载的那一版的 README。