Claude 订阅怎么分给团队用？Sub2API 自建配额网关实战

源微信页常触发验证码拦截。正文不以那篇「搭建指南」为底稿照抄，而是按官方仓库 Wei-Shaw/sub2api 的中文 README 与部署脚本重组：把 Sub2API 定位成「订阅配额分发」型 AI API 网关——上游接 OAuth / API Key，平台给成员发独立 Key，自己管鉴权、计费、负载与转发。

本地已有 CC-Switch（配置切换面板）、CliRelay（CLI Session→OpenAI 协议代理）等文章；本篇只写 Sub2API 这一整套带 PostgreSQL + Redis + Web 后台的网关，角度是团队配额与自建运维，不重复本地 CLI 换皮代理。

封面：订阅转 API 配额网关

一、它解决什么：不是再套一层转发器

很多「中转」工具只做一件事：把请求转到上游。Sub2API 的官方定位是 AI API Gateway Platform for Subscription Quota Distribution——面向订阅额度的分发与管理：

能力	解决什么问题
多账号管理	上游可挂 OAuth、API Key 等多种账号类型
API Key 分发	给成员发独立 Key，而不是共享上游密钥
Token 级计费	按 token 追踪用量与成本
智能调度	多账号选择，支持粘性会话
并发 / 速率限制	用户级、账号级限流，避免把账号打挂
管理后台	Web UI 看用户、账号、请求与用量
内置支付（可选）	EasyPay / 支付宝 / 微信 / Stripe 等自助充值

技术栈也很直接：后端 Go + Gin + Ent，前端 Vue 3 + Vite，数据 PostgreSQL 15+，缓存/队列 Redis 7+，并提供 Docker 一键部署。

适合：3–10 人小团队共享 Claude / Codex / Gemini 相关订阅、要看得见每个人烧了多少 token、要把数据路径留在自己服务器。
不适合：完全不会 Docker / 域名 / HTTPS 的新手；只想「省钱」却不愿承担运维与账号风控；准备公开卖服务却没想过上游条款与合规。

服务条款风险：官方 README 明确提醒，使用本项目可能违反 Anthropic 等上游服务条款；账号封禁、服务中断等风险由使用者自担。本文仅做技术部署说明，不鼓励违规转售。

二、最小架构：客户端 → HTTPS → Sub2API → 上游

Claude Code / Codex / Gemini CLI / IDE 插件
              │
              ▼
     HTTPS 域名（Nginx / Caddy）
              │
              ▼
           Sub2API (:8080)
         ┌────┴────┐
         ▼         ▼
    PostgreSQL   Redis
         │
         ▼
  Claude / OpenAI / Gemini / Antigravity …

个人或内部团队建议：Docker Compose + HTTPS + 管理后台不裸奔公网。别一上来就开公开注册、支付和套餐。

三、Docker Compose 一键部署（推荐）

官方提供自动化脚本，会拉齐 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 up -d
docker compose logs -f sub2api

脚本会下载 docker-compose.local.yml（保存为 docker-compose.yml）与 .env.example，并自动生成 JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD 等凭证——请立刻抄到密码管理器，日志里也可能打印初始管理员密码。

手工部署（更可控）

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

cp .env.example .env
chmod 600 .env

.env 至少确认这些项（示例均为占位符）：

POSTGRES_PASSWORD=your_secure_password_here
JWT_SECRET=your_jwt_secret_here
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 / TOTP / Postgres

启动（推荐本地目录版，备份迁移更简单）：

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

浏览器打开 http://你的服务器IP:8080，走完初始化向导。生产环境不要长期把 8080 直接暴露公网，应挂到 HTTPS 反代后面。

Compose 版本	数据存储	迁移	场景
`docker-compose.local.yml`	本地目录	打包整个目录即可	生产 / 常备份
`docker-compose.yml`	Docker 命名卷	需 docker volume 命令	快速试用

四、Nginx 反代：别让粘性会话悄悄失效

搭配 Codex CLI 或多账号粘性会话时，Nginx 默认会丢弃带下划线的 Header（如 session_id），导致 sticky session 失效。官方要求在 http 块加：

underscores_in_headers on;

极简 HTTPS 反代骨架：

http {
  underscores_in_headers on;

  server {
    listen 443 ssl http2;
    server_name relay.example.com;

    ssl_certificate     /etc/letsencrypt/live/relay.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/relay.example.com/privkey.pem;

    client_max_body_size 50m;

    location / {
      proxy_pass http://127.0.0.1:8080;
      proxy_http_version 1.1;
      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;
      proxy_buffering off;   # 流式输出别缓冲
    }
  }
}

用 Caddy 也可以，但要确认不会吞 Header、不会缓冲 SSE/流式响应。

架构：配额分发与粘性会话

五、Simple Mode：内部自用先别上 SaaS

内部团队多数只想「自己人稳定用、看得见用量、别互相抢额度」。官方提供简易模式：

RUN_MODE=simple
SIMPLE_MODE_CONFIRM=true

隐藏完整 SaaS / 计费流程，适合个人或小团队快速上手
生产环境必须同时设 SIMPLE_MODE_CONFIRM=true 才允许启动

建议：先 Simple Mode 跑通 Claude Code，再决定要不要开放注册、余额与支付。

六、接入 Claude Code / Codex / Gemini

不同上游与客户端环境变量不完全相同，以下为官方 README 常见形态（请换成你的 HTTPS 域名与平台生成的 Key）。

Claude Code（Anthropic 兼容路径）

export ANTHROPIC_BASE_URL="https://relay.example.com"
export ANTHROPIC_API_KEY="sk-your-sub2api-key"

claude

Antigravity 专用端点

Sub2API 支持 Antigravity 账户，授权后可用专用路径访问 Claude / Gemini：

端点	模型
`/antigravity/v1/messages`	Claude
`/antigravity/v1beta/`	Gemini

export ANTHROPIC_BASE_URL="http://localhost:8080/antigravity"
export ANTHROPIC_AUTH_TOKEN="sk-your-api-key-here"

隔离警告：Anthropic Claude 与 Antigravity Claude 不能混在同一会话上下文；请用分组（groups）隔开。开启混合调度后，通用 /v1/messages 也会调度该账户——更要小心上下文污染。

OpenAI 兼容 / Codex 类工具

export OPENAI_BASE_URL="https://relay.example.com/v1"
export OPENAI_API_KEY="sk-your-sub2api-key"

有的客户端读 OPENAI_API_BASE，以工具文档为准。

接入：Claude Code 与 API Key 分发

七、排坑清单：密钥、管理员、升级与备份

1. 管理员只能靠 Setup 向导创建

源码编译场景下，若你提前 cp 了 config.yaml，首次启动会跳过向导，users 表为空，登录会报 invalid email or password。官方推荐：不要预置 config，先跑二进制让向导写配置；或临时移走 config 触发向导后再恢复。

Docker 脚本路径一般会生成管理员凭证，务必在日志中检索：

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

2. 生产安全最低线

1. 强制 HTTPS，禁止公网明文传 API Key 与代码上下文

2. 后台限 IP / 内网 / 强密码 + 2FA，别裸奔

3. .env、备份、日志包禁止进 Git

4. 日志脱敏：别长期存完整 Prompt、代码片段、上游 Key

5. 内部使用先关公开注册与支付

6. 给用户与上游账号设合理 RPM / TPM / 并发上限

7. 收紧 security.url_allowlist：生产别随意允许任意 HTTP 上游

3. 升级与迁移

# 升级
docker compose -f docker-compose.local.yml pull
docker compose -f docker-compose.local.yml up -d

# 整目录备份（先 down）
docker compose -f docker-compose.local.yml down
cd ..
tar czf sub2api-complete.tar.gz sub2api-deploy/

生产更建议定期做 PostgreSQL 逻辑备份，而不是只靠整目录 tar。

4. 和同类工具怎么选（避免写重）

方案	更适合
Sub2API	订阅额度分发、用户 Key、账号池、计费、多工具统一入口
CC-Switch	本机多 CLI 配置可视化切换 / 健康探测
CliRelay / CRS 类	把 Claude Code / Gemini CLI Session 变成本地 OpenAI 兼容端口
OneAPI / New API	通用多模型聚合与应用开发路由
商业中转站	不想运维，开箱即用

本篇只覆盖 Sub2API；若你只需要本机一个端口给 Cursor 用，轻量 CLI Relay 可能更合适。

八、建议落地顺序（别一口气上线）

1. 干净 VPS，只开 80/443，后台端口不公网暴露

2. Docker Compose 拉起 Sub2API + PG + Redis

3. 配 HTTPS，确认流式输出正常

4. 管理员强密码，关闭公开注册

5. 添加一个上游账号或 API Key

6. 给自己发一枚内部 Key

7. 用 Claude Code 跑一个低风险小任务验证

8. 配用户级限流与并发

9. 观察用量 1–2 天再拉队友

九、小结

Sub2API（Wei-Shaw/sub2api）把「Claude / OpenAI / Gemini 订阅」收成带鉴权与计费的内部 API 入口：Docker 能快速起，难点在 HTTPS、粘性会话 Header、账号隔离与安全加固。先 Simple Mode 内部自用，再谈 SaaS 化——比照抄一篇「搭建指南」更不容易踩坑。

仓库：https://github.com/Wei-Shaw/sub2api
配套练习目录：practice/（占位，便于后续补 compose 片段与探测脚本）