Sub2API 实战：把你散落的 AI 订阅拧成一根管子

手里同时挂着 Claude Pro、ChatGPT Plus、Gemini Advanced 的开发者，最近两年越来越多。订阅费一个月烧出去几百块，但额度大概率用不完——白天写代码主要用 Claude Code，晚上偶尔切 GPT 调一下，Gemini 那份订阅可能只是为了 Antigravity 留着。

这种「订阅孤岛」催生了一波开源中转网关项目。Sub2API 是其中讨论度最高的一个，GitHub 上 3.4K star，作者 Wei-Shaw 在 6 月初又推了一版升级，把账号调度和会话保持那一块重写了一遍。今天就拿它当主角，把从部署到接客户端的完整链路走一遍，顺便把 new-api、UniAPI、OpenAI Router 这几个常被拿来对比的方案也一并梳理清楚。

一、Sub2API 到底解决什么问题

先把定位说清楚，免得跟 new-api 那种纯 API Key 聚合工具混为一谈。

new-api / one-api 走的是「拿一堆官方 API Key 做负载均衡」的路子，前提是你有 API Key。Sub2API 不一样，它瞄准的是订阅账号——也就是 Claude Pro、ChatGPT Plus 这种网页端登录的会员，原本只能在 Claude Code、Codex CLI 这些官方客户端里用，没有标准 REST 接口。

Sub2API 做的事情，是把 OAuth token、Session Key 或者标准 API Key 这三种凭证一起池化，对外暴露一个统一的 OpenAI 兼容端点。下游不管是 Cursor、Cline 还是你自己写的脚本，只要改一下 base_url 就能用。

这里面有几个值得拎出来的设计：

• 会话粘性（session stickiness）：Claude Code 这种工具对上下文连续性敏感，请求一旦在多个上游账号之间乱跳，对话就废了。Sub2API 通过 Header 里的 session_id 把请求锁在固定账号上，跑长任务不会断。
• 限流自动避让：某个账号撞到 5 小时窗口的 Rate Limit，调度器直接把它从池子里摘出去，等冷却完再放回来。
• 内置计费：拼车场景下，多人共享一个池子怎么分账？Sub2API 把支付网关直接做进了后台，省掉了对接 Stripe 或者别的轮子。

这第三点其实是它跟 new-api 拉开差距的地方。new-api 走的是「企业 API 网关」的思路，鉴权、配额、审计做得很重，但计费要自己接。Sub2API 默认就是冲着「拼车头子」的场景去的。

二、把它跑起来：Docker Compose 最省事

官方推荐 Docker Compose，原因很直接——它要拖一个 PostgreSQL 和一个 Redis，手动装不如让 compose 一把梭。

准备一台 Linux 机器（CX11 这种最小规格够用），Docker Engine 20.10+，然后执行一键脚本：

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

脚本会拉镜像、生成默认的 .env、起服务。如果你想自己掌控环境变量，那就走手动路径：

mkdir -p sub2api-deploy && cd sub2api-deploy
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash
docker compose -f docker-compose.local.yml up -d

服务默认起在 8080 端口，浏览器打开 http://服务器IP:8080，初始账号 admin@sub2api.com / admin123——第一件事就是改密码，别问我怎么知道有人忘了改然后被陌生人薅羊毛的故事。

几个一定要固定下来的环境变量：

• POSTGRES_PASSWORD：数据库密码，丢了等于数据丢了
• JWT_SECRET：登录 token 签名密钥，重启后变了所有人都要重新登录
• TOTP_ENCRYPTION_KEY：双因素认证用的，变了 2FA 全部失效
• ADMIN_PASSWORD：管理员初始密码

这四个建议先用 openssl rand -hex 32 生成好写进 .env，别用默认值。

Windows 用户的小坑

如果你打算在 Windows 本地用 WSL 跑——linux.do 上有篇热门的保姆教程就是讲这个的——记得在 Docker Desktop 的 Settings → Resources → WSL Integration 里把对应的 WSL 发行版打开。不开的话进 WSL 终端执行 docker 直接报 command not found，是初学者最常卡的一步。

三、把订阅塞进池子

部署只是搭好了空壳子，真正的活儿在接账号。

以 Claude Pro 订阅为例，Sub2API 支持三种接入方式：

1. OAuth 授权：在后台点「添加账号」，跳到 Claude 官网授权，回调后自动存 token。这个最省事，但要求服务器能被 Claude 回调到，本地部署需要 ngrok 或者反代。
2. Session Key 模式：从浏览器开发者工具里把 sessionKey 拷出来粘进去。野路子，但够用。
3. 标准 API Key：如果你买的是 Anthropic 官方 API Key，直接填，跟 new-api 一个用法。

OpenAI 和 Gemini 同理。值得一提的是 Sub2API 最近加了 Antigravity 的支持——就是 Google 那个 IDE Agent，订阅模式跟 Gemini Advanced 绑在一起，能把它的 token 接进来意味着你的 Gemini 订阅终于能在 Cursor 里用了。

账号接进来之后，去「API Keys」页面生成下游 Key，按用途分开命名：

desktop-cursor
cli-claude-code
laptop-cline

这么分的好处是后续翻日志、停用某把 Key、限速都好操作。把一把 Key 走遍所有客户端是图省事，但出问题排查会很痛苦。

四、客户端怎么接

绝大部分兼容 OpenAI 协议的工具，本质上只要两样东西：base_url 和 api_key。把它们指到 Sub2API：

base_url: http://你的服务器:8080/v1
api_key: sk-xxxxxxxxxxxx（后台生成的那把）

Cursor、Cline、Aider、OpenWebUI 都是这套。Claude Code 稍微特殊，它原生走 Anthropic 协议，Sub2API 在 /anthropic/v1/messages 路径上做了原样转发，配置 ANTHROPIC_BASE_URL 环境变量就行：

export ANTHROPIC_BASE_URL=http://你的服务器:8080/anthropic
export ANTHROPIC_API_KEY=sk-xxxxxxxx

这里有个细节，如果你前面套了 Nginx 反代，一定要开 underscores_in_headers on;。Anthropic 的 SDK 会在 Header 里塞 x-api-key 这种带下划线的字段，Nginx 默认会把这种 Header 干掉，结果就是后端永远收不到鉴权信息。这个坑踩过的人不少。

五、同类项目横向对比

聚合网关赛道现在卷得厉害，挑几个有代表性的对照着看：

new-api（30.1K star）

生态最大的那个，背靠 one-api 的老用户群。优势是渠道丰富、模型映射规则灵活、审计日志全。劣势是它假设你有 API Key，对订阅账号的支持几乎没有。如果你是公司团队，账上充了一堆 Azure OpenAI、火山引擎、阿里百炼的 Key 要统一管，闭眼选 new-api。如果你是个人手握订阅想拼车，它帮不上你。

UniAPI（1.7K star）

定位很有意思——它是个**「中转的中转」**。把 new-api、Sub2API、AnyRouter 这些中转站再聚合一次，做模型自动发现和智能路由。TypeScript + Fastify 写的，桌面端跨平台。对于已经在用多个中转站的人来说，UniAPI 解决的是「不想每次切换 base_url」的问题。

Quotio（3.9K star）

这个不算网关，是个额度可视化工具。把你各家 AI 账号的剩余 quota 在一个面板里展示出来。配合 Sub2API 用挺香的，一边管入口一边看预算。

Grok2API（3.9K star）

专门给 Grok 写的 OpenAI 兼容层。Grok 官方 API 现在已经放开了，这个工具的存在感在下降，但如果你只想用 Grok 订阅、不想付额外的 API 费用，它仍然有用武之地。

OpenAI Router

更轻量的路子，零配置、SQLite 持久化，主要给后端服务做 vLLM、SGLang、Ollama 这些自托管推理后端的统一入口。跟 Sub2API 不是一个赛道，它服务的是「我自己跑了一堆开源模型，怎么对外暴露」。

一句话总结这几个工具的选型：

| 需求 | 推荐 | |------|------| | 团队用 API Key 做企业级管理 | new-api | | 个人/小团队拼订阅、拼车分账 | Sub2API | | 多中转站再聚合一层 | UniAPI | | 自建推理服务做统一入口 | OpenAI Router | | 单纯想看每个账号还剩多少额度 | Quotio |

六、自建之外，还有更省心的选项

实话说，自建这套东西的乐趣在于折腾本身。维护、备份、上游 API 变化跟进，每一项都是隐性成本。

个人开发者如果只是想要「一个 Key 调所有主流模型」、不想自己维护账号池，直接用 OpenAI Hub（openai-hub.com）这类聚合平台是更现实的选择。OpenAI Hub 走 OpenAI 兼容格式，GPT、Claude、Gemini、DeepSeek 这些主流模型都在，国内直连不用折腾代理，新模型上线节奏也很快——上周 Anthropic 那波更新两天内就同步上了。

两种思路并不互斥：拼车场景、想把闲置订阅榨干，自建 Sub2API；要 API 稳定调用、不想为运维操心，走聚合平台。混合用也行，在 Sub2API 里把 OpenAI Hub 当成一个上游 Channel 接进去，相当于给你的订阅池兜个底——主用订阅，超量自动落到付费 API 上。

七、几个容易踩的坑

最后把社区里反馈最多的几个问题列出来：

• JWT_SECRET 没固定：用默认值或者每次重启重新生成，导致登录态丢失，重新登录时 2FA 又解不开。解决方案就是部署前先把这个写死。
• 数据库没备份：Sub2API 把账号 token、Key、计费记录全存在 PostgreSQL 里，一旦容器删了或者宿主机挂了，数据全没。pg_dump 加个 crontab，五分钟的活儿别省。
• OAuth 回调地址配错：本地部署的同学最容易在这里栽，Claude 的 OAuth 要求 HTTPS 回调，纯 IP + 8080 端口不行。要么挂 Cloudflare Tunnel，要么直接用 Session Key 模式绕过。
• 拿来公网卖：法律风险和上游条款风险都很大，Anthropic、OpenAI 的 ToS 都明确禁止订阅账号转售。自用没问题，对外卖账号别想了。

写在最后

Sub2API 这类工具的真正价值，不在于「省了多少钱」，而在于它把 AI 订阅的使用方式从「绑定官方客户端」解耦成了「我自己说了算」。Claude Pro 的额度可以在 Cursor 里用，ChatGPT Plus 的 token 可以喂给 Aider，Gemini Advanced 的能力可以塞进自己写的 Agent——这种自由度是聚合 API 给不了的。

但代价就是你要自己当运维。账号封了、上游接口变了、PostgreSQL 磁盘满了，这些问题最终都会落到你头上。

如果你愿意为这点自由付出维护成本，Sub2API 是目前开源方案里完成度最高的一个。如果不愿意，那就老老实实用 API Key——这两条路本来就是分给不同人的。

---

参考来源

• Sub2API GitHub 仓库 — 项目源码、部署脚本和官方文档
• linux.do：保姆级教程手把手教你本地搭建 sub2api 中转站 — Windows + WSL 环境下的完整部署步骤，初学者友好
• 知乎专栏：GitHub 热榜项目日榜 — Sub2API 上榜时期的项目介绍与功能盘点