Sub2API – 开源 AI API 中转网关平台，支持多账户管理

1. Sub2API是什么

Sub2API是一款开源的AI API网关平台，用于分发和管理AI产品订阅的API配额，由开发者 Wesley Liddick 主导开发。通过平台生成的API Key，用户可将Claude、OpenAI、Gemini、Antigravity等主流AI服务的订阅账号统一接入到单一网关，由平台负责鉴权、计费、负载均衡和请求转发。其核心价值在于通过"拼车共享"模式分摊昂贵的订阅成本，并内置支付系统、智能调度、Token级精准计费等精细化管控能力，已开源至GitHub并收获30.9k Star，适合个人开发者或团队搭建私有的AI API分发系统。

技术定位与领域： Sub2API属于AI服务管理与分发领域，主要应用于跨平台的AI服务集成与成本优化，旨在解决多账号管理混乱、订阅成本分摊不透明、API密钥分发难统一管控的问题。其在AI网关赛道以"订阅配额分发"为核心定位，区别于一般的多模型代理中转。

研发背景： 项目由开发者 Wesley Liddick 主导，托管于 GitHub（github.com/Wei-Shaw/sub2api），目前已发展为拥有30.9k Star、6.3k Fork、1.5k+ Issues 的活跃开源项目，并登上 Trendshift 趋势榜。项目采用LGPL-3.0或更高版本开源协议授权，明确声明禁止任何形式的未授权商业化运营，强调合规使用与服务条款风险由用户自担。

核心价值： Sub2API通过多账号管理、智能调度和Token级别精准计费，帮助用户在不违反自身账号已获授权范围的前提下降低AI服务订阅成本，同时提供统一的API接入方式、内置支付充值和Web管理后台，将"多账号运维 + 计费 + 分发 + 监控"打包为一站式私有网关方案。

技术特点： 后端采用 Go 1.25.7 + Gin + Ent 框架，前端采用 Vue 3.4+ + Vite 5+ + TailwindCSS，数据库依赖 PostgreSQL 15+ 与 Redis 7+。支持OAuth与API Key多种鉴权、粘性会话（Sticky Session）、用户级与账号级双层并发与速率限制，并默认提供HTTP/2(h2c)能力与HTTP/1.1回退，兼顾反向代理链路性能与旧客户端兼容。

2. 主要功能

• 多账号管理： 支持OAuth和API Key多种认证方式，统一接入Claude、OpenAI、Gemini、Antigravity等主流AI服务的上游账号，可集中查看账号健康状态、配额与授权情况，避免账号资源散落在多个团队成员手中，提升上游账号的统一治理能力。
• API Key分发： 为下游用户生成和管理独立的API Key，支持自定义前缀（如sk-），通过权限与额度隔离保证访问控制的安全性，方便为团队成员或下游客户按需签发、吊销和轮转密钥而不触碰上游账号本身。
• 精确计费： 提供Token级别的用量追踪和实时成本计算，将每个请求的prompt/completion token消耗映射到配置的上游价格表，并按下游Key/用户聚合统计，确保多人共享订阅场景下的费用分摊透明、可审计。
• 智能调度： 通过智能算法在多上游账号间选择最优账号，并支持粘性会话（Sticky Session），将同一会话ID固定路由到同一上游账号，保证多步Agent工具调用、文件上传、长对话等场景的上下文连续性，避免轮询切换导致链路中断。
• 并发控制： 支持用户级和账号级双层并发限制，通过独立信号量在全局、上游账号、下游Key三个维度隔离资源，防止单一用户或账号过载拖垮整体服务，请求可根据策略排队或快速失败，保护上游服务的Session限额。
• 速率限制： 平台可灵活配置请求频率（QPS）和Token消耗速率，帮助用户规避触发上游服务商的风控机制；同时提供/auth/register、/auth/login、/auth/login/2fa、/auth/send-verify-code等服务端兜底限流，Redis故障时采取fail-close策略。
• 内置支付系统： 支持EasyPay易支付、支付宝官方、微信官方、Stripe四种主流支付渠道，用户可自助完成余额充值，无需独立部署支付服务，极大简化商业化或半商业化场景的运营门槛，配置细节见官方docs/PAYMENT_CN.md指南。
• 管理后台： 提供功能完善的Vue 3 Web管理界面，支持实时监控、数据统计、账号管理、Key管理、配额与计费规则配置，内置在线"检测更新"功能（自动检测新版本、一键下载应用、支持回滚），并可嵌入工单等外部系统扩展能力。
• 外部系统集成： 支持通过iframe嵌入工单、客服、计费等外部系统，搭建统一运营台，避免在多个后台间频繁切换；配合sub2api-mobile等生态项目，还能在移动端进行用户管理、账号管理与监控看板操作。

3. 如何使用

1. 环境要求： 脚本安装需Linux服务器（amd64或arm64），已预先安装PostgreSQL 15+与Redis 7+并具备Root权限；Docker Compose部署需Docker 20.10+与Docker Compose v2+；源码编译还需Go 1.21+、Node.js 18+与pnpm，后端推荐Go 1.25.7。
2. 安装部署： 推荐脚本一键安装：curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash，脚本会自动检测架构、下载二进制并安装到/opt/sub2api、创建systemd服务与配置权限；或使用Docker Compose一键脚本docker-deploy.sh自动生成安全凭证与.env配置。
3. 初始化配置： 启动后访问http://服务器IP:8080进入设置向导，完成数据库连接、Redis配置和管理员账号创建，向导会自动写出生成的config.yaml；如自行预先创建config.yaml，需临时将其移走以触发向导（管理员账号只能通过向导创建，default.admin_email不会自动建号）。
4. 上游账号授权： 在管理后台"账号管理"中添加Claude、OpenAI、Gemini、Antigravity等AI服务账号并完成OAuth或API Key授权；Antigravity账号支持专用端点/antigravity/v1/messages与/antigravity/v1beta/，并可开启混合调度模式让通用端点也调度该账户。
5. 下发Key与计费： 为下游用户/成员生成独立API Key，按需设置额度、计费规则、并发与速率限制；如启用内置支付，配置EasyPay/支付宝/微信/Stripe后，用户可在前台自助充值，所有计费基于Token级实时成本归集。
6. 安全与反向代理： 生产环境建议在反向代理层开启HTTPS、WAF/CDN作为第一层防护，并配置underscores_in_headers on;（Nginx默认丢弃含下划线的session_id请求头，会导致粘性会话失效），同时通过security.url_allowlist仅允许HTTPS出站以避免API密钥明文传输风险。

4. 优缺点分析

5. 同类工具对比

选型建议： 对于个人开发者和小型团队希望通过"拼车共享"模式分摊Claude Pro / ChatGPT Plus等订阅成本，并需要Token级精准计费与内置支付的场景，Sub2API是当前最匹配的开源方案，尤其是其粘性会话与订阅配额分发能力对Agent工具调用类应用尤为关键。对于仅需多模型统一代理、不强调订阅分摊与计费的轻量场景，One API上手更简单、社区插件更丰富。对于追求低价中转与按量计费的商业化部署，New API及其Fork版在渠道聚合与Midjourney接入等方面更具优势。企业级需要严格权限管理与合规审计的场景，建议在Sub2API基础上结合WAF/CDN与可信代理配置，或评估商业AI Gateway方案。

6. 编辑点评

Sub2API凭借"订阅配额分发"这一独特定位，在AI网关赛道中走出了一条与众不同的路线。其核心价值不在于新增了多少模型适配，而在于把"多账号运维 + 计费 + 分发 + 支付 + 监控"打包为一站式私有网关，让"五个朋友拼一台Claude Max"这样的需求从灰色操作变为可审计、可计费、可运营的工程化方案。后端Go 1.25.7 + Gin + Ent的组合保证了高并发与类型安全，前端Vue 3.4+ + TailwindCSS提供了现代化管理体验，HTTP/2(h2c)与粘性会话等细节则体现了对生产链路的深入思考。

但需要清醒认识的是，项目的合规风险与上游服务条款冲突是绕不开的议题——官方README顶部的"重要提醒"章节已明确将账户封禁、服务中断等责任划归用户，使用前应充分阅读Anthropic、OpenAI等上游条款并获得合规/法务签字。总体而言，Sub2API是一款在工程实现与产品定位上都极具创新性的工具，其30.9k Star与登上Trendshift趋势榜也印证了市场对这类私有AI网关的强烈需求。

7. 应用场景

• AI订阅拼车共享： 多人共同分摊Claude Pro、ChatGPT Plus等昂贵订阅费用，通过Token级精准计费实现公平的成本分摊，并配合内置支付系统让成员自助充值，降低个人开发者使用顶级AI模型的门槛。
• 团队AI资源统一管理： 企业或团队集中管理多个AI服务账号，统一生成和分配API Key给工程师使用，通过双层并发限制与粘性会话保护上游账号配额，提供集中监控与额度审计能力。
• 个人多账号聚合： 个人用户将散落在不同平台的Claude、OpenAI、Gemini、Antigravity账号整合到单一入口，通过分组隔离避免Anthropic Claude与Antigravity Claude在同一上下文混合使用，简化多平台管理。
• AI服务二次分发： 技术爱好者或小型服务商可搭建私有API中转站，结合内置EasyPay/支付宝/微信/Stripe支付，为下游用户提供稳定的AI接口服务与自助充值，支持自定义计费策略和额度管理。
• 开发/测试环境对齐： 将本地OpenAI兼容SDK指向Sub2API网关，让工程师在本地、预发与生产使用相同的上游路由池，减少"我的Key能用而上线失败"的链路漂移问题，提升多环境一致性。

8. 常见问题FAQ

Q：Sub2API是否免费开源？采用什么协议？
A：项目开源至 github.com/Wei-Shaw/sub2api，基于GNU宽通用公共许可证v3.0（LGPL-3.0）或更高版本授权，代码可免费获取与研究。但官方README明确声明从未授权任何个人或组织基于本项目开展商业化运营，任何以本项目名义从事的商业行为均与开发者无关；使用前请阅读服务条款风险、合规使用、免责声明、无商业授权四条重要提醒，账户封禁等风险由用户自担。

Q：Sub2API支持哪些AI上游服务？
A：目前支持Claude、OpenAI、Gemini、Antigravity等主流AI服务的OAuth与API Key接入。Antigravity账号授权后可通过专用端点/antigravity/v1/messages访问Claude模型、/antigravity/v1beta/访问Gemini模型，并支持可选混合调度模式让通用端点也调度该账户。新的上游适配通过PR合入，建议使用前查阅GitHub最新Release Notes确认目标服务商是否已支持。

Q：如何实现Token级精准计费？
A：网关会解析每个请求的provider usage字段（prompt/completion tokens），映射到在管理后台预先配置的上游成本表，并按下游API Key/用户维度聚合统计。配合内置的EasyPay/支付宝/微信/Stripe支付系统，用户可自助充值，所有计费基于Token级实时成本归集，并通过billing.circuit_breaker在计费异常时fail-closed，避免错误扣费。

Q：Sub2API支持哪些部署方式？推荐哪种？
A：提供三种部署方式。方式一脚本安装（推荐）：curl -sSL .../install.sh | sudo bash自动下载预编译二进制并配置systemd服务，支持后台在线检测更新与回滚。方式二Docker Compose（推荐）：通过docker-deploy.sh一键脚本自动生成JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD等安全凭证，推荐使用docker-compose.local.yml本地目录版便于备份迁移。方式三源码编译：适合开发定制，需注意-tags embed参数将前端嵌入二进制，缺少该参数构建的程序不含Web界面。

Q：如何创建管理员账号？为什么首次登录提示invalid email or password？
A：初始管理员账号只能通过首次启动时的setup向导创建（访问http://<host>:8080），config.yaml中的default.admin_email/default.admin_password字段不会被用来创建管理员，仅是历史保留字段。如果预先创建了config.yaml，setup向导会被跳过并直接进入正常模式，此时users表为空导致登录失败。推荐方案：跳过cp config.example.yaml config.yaml步骤，让向导自动生成配置；或临时将config.yaml移走触发向导，完成后再恢复配置文件并重启。

Q：Sub2API的并发控制与速率限制如何实现？
A：平台支持用户级和账号级双层并发限制，通过独立信号量在全局、上游账号、下游Key三个维度隔离资源，请求可根据策略排队或快速失败。速率限制可配置请求QPS和Token消耗速率，并对/auth/register、/auth/login、/auth/login/2fa、/auth/send-verify-code等服务端关键端点提供兜底限流，Redis故障时采用fail-close策略。配合gateway.upstream_response_read_max_bytes等响应大小上限，可防止异常响应导致内存放大。

Q：使用Nginx反向代理时粘性会话失效怎么办？
A：在Nginx配置的http块中添加underscores_in_headers on;。Nginx默认会丢弃名称中含下划线的请求头（如session_id），这会导致多账号环境下的粘性会话功能失效。同时建议在反向代理层开启HTTPS与WAF/CDN作为第一层防护，服务端限流与响应读取上限作为第二层兜底，生产环境通过security.url_allowlist.allow_insecure_http: false仅允许HTTPS出站，避免API密钥明文传输风险。

9. 项目地址

• GitHub仓库： https://github.com/Wei-Shaw/sub2api
• 支付配置指南： https://github.com/Wei-Shaw/sub2api/blob/main/docs/PAYMENT_CN.md
• 中文README： https://github.com/Wei-Shaw/sub2api/blob/main/README_CN.md