Sub2API: 统一 AI 订阅网关

1. 项目概述

Sub2API 是一个基于 Go 的开源 API 网关，它将 Claude、OpenAI、Gemini、Grok 和 Antigravity 的订阅整合为统一的 OpenAI/Anthropic 兼容 API 端点，使团队能够通过单一自托管服务来池化和共享订阅配额。

2. 背景与定位

个人 AI 订阅（如 Claude Pro/Max、ChatGPT Plus、Gemini Advanced 等）主要针对单用户浏览器使用进行定价，但开发者越来越希望通过原生 CLI 工具和 SDK 获得编程式访问权限。Sub2API 旨在弥合这一差距：它将一个或多个订阅账户转化为 API 兼容网关，以便团队或社区可以共享配额、按 Token 跟踪使用情况，并在不同账户和提供商之间智能路由请求。

与主要转发 API 密钥流量的通用 LLM 代理或路由器项目相比，Sub2API 专注于基于订阅的账户（通过 OAuth 认证的消费级计划），增加了账户池化、粘性会话调度和内置计费/支付功能，从而使共享访问可以作为小型托管服务运营，而不仅仅是一个个人脚本。

3. 功能类别

🔑 账户与访问管理 — 4 项核心能力，例如 OAuth 账户绑定、API Key 账户绑定、动态 API Key 发放、按 Key 的生命周期控制。目的：从单一仪表板接入和管理大量上游订阅账户及下游用户 Key。

⚖️ 调度与流量控制 — 4 项核心能力，例如智能账户选择、粘性会话、按用户并发限制、按账户并发限制、可配置请求/Token 速率限制。目的：在池化账户间均匀分配负载，同时保护每个账户免受上游服务的限流或标记。

💳 计费与变现 — 4 项核心能力，例如 Token 级用量计量、内置支付集成（EasyPay、支付宝、微信支付、Stripe）、自助充值、计费熔断器。目的：让运营商能够以准确、可审计的用量核算来运行成本分摊或付费访问组。

🧩 多提供商路由 — 支持 5 个提供商：Claude (Anthropic)、OpenAI (包括 Codex)、Gemini (Google)、Grok/xAI 和 Antigravity (混合调度)。目的：在一致且熟悉的 API 形状背后暴露异构的上游提供商。

🖥️ 管理控制台与运维 — 4 项核心能力，例如 Vue 3 Web 控制台、实时监控、Codex CLI 的 WebSocket 入口管理、异步图像任务轮询。目的：让操作员无需日常接触命令行即可获得可视性和控制权。

4. 关键亮点

订阅池化（“拼车”） — 将多个 Claude/OpenAI/Gemini/Grok 账户组合到一个网关中，以便在团队或用户群中共享配额成本。
原生工具兼容性 — 设计目标是使针对 Anthropic/OpenAI 风格 API 构建的现有 CLI 工具和 SDK 能够以最少或无需更改的方式工作。
精确到 Token 的计费 — 每个请求都按 Token 级别计量，实现公平的成本分配和按需充值。
粘性会话智能调度 — 在需要时将对话固定在上游的同一账户上，避免在多轮工具会话中出现上下文丢失。
复合提供商组 — 跨多个提供商或账户路由单个逻辑模型端点，以实现冗余和负载均衡。
多种部署路径 — 一行安装脚本、Docker Compose、Apple Container (macOS/Apple Silicon) 或从源代码构建，涵盖快速试用和生产部署。

5. 角色用例

普通开发者：通过一个一致的 API 端点和 API Key 访问 Claude、OpenAI、Gemini 和 Grok，无需为每个提供商单独处理 SDK 或凭据。
DevOps/SRE：通过 Docker Compose 部署 PostgreSQL 和 Redis，配置速率限制、可信代理和熔断器，以保持共享网关在高负载下的稳定性。
社区/团队运营商：在群组内分摊订阅成本，发行单独的 API Key，并使用内置支付集成来管理共享或付费访问。
项目经理：使用管理控制台监控组织内的用量、支出和账户健康状况，无需工程支持即可进行常规监督。

6. 入门指南

查找所需内容 — 从仓库 README（英文和中文）以及 deploy/README.md 开始获取特定于部署的指导：

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

安装/集成 — 最快的路径是 Linux 的一行安装脚本：

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

或者使用 Docker Compose 进行完全容器化的设置（包括 PostgreSQL 和 Redis）：

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

贡献代码 — Fork 仓库，向 main 分支提交 Pull Request，并使用 GitHub Issues 报告错误或提议新功能：

gh repo fork Wei-Shaw/sub2api --clone

7. 项目结构

sub2api/
├── backend/     # Go 服务：配置、模型、请求处理器、提供商网关逻辑
├── frontend/    # Vue 3 + Vite + TailwindCSS 管理控制台
├── deploy/      # Docker Compose 文件、环境变量模板、安装/升级脚本
└── openspec/    # 暴露的网关端点的 OpenAPI 规范

backend/cmd/server — Go 二进制文件的主入口点。
deploy/install.sh / deploy/docker-deploy.sh — 用于基于脚本和基于 Docker 部署的一行安装程序。
frontend/ — 用于账户、Key、计费和监控管理的 Web 控制台。

8. 相关生态

上游依赖：后端使用 Go 1.25.7、Gin Web 框架和 Ent ORM；前端使用 Vue 3.4+、Vite 5+ 和 TailwindCSS；存储使用 PostgreSQL 15+，缓存和队列使用 Redis 7+。
上游订阅提供商：Anthropic (Claude)、OpenAI (包括 Codex)、Google (Gemini) 和 xAI (Grok) — Sub2API 位于这些服务之前作为网关，而非替代它们。
配套项目：sub2api-mobile，一个跨平台的移动管理控制台，用于随时随地管理已部署的实例。

9. 许可证

Sub2API 根据 GNU 宽通用公共许可证 v3.0 (LGPL-3.0) 发布。

✅ 可免费使用、研究和修改源代码，包括用于内部或教育目的。
✅ 可免费自托管用于个人或团队使用，包括在私人群组内共享订阅成本。
❌ 项目明确指出未授权任何个人或组织将其作为商业服务运营。
ℹ️ 使用 Sub2API 访问上游提供商可能与这些提供商自己的服务条款冲突；维护者将该项目描述为旨在用于技术学习和研究目的，运营商需自行负责合规性和账户风险。

10. 常见问题

问：Sub2API 支持哪些 AI 提供商？
答：Claude (Anthropic)、OpenAI (包括 Codex)、Gemini (Google)、Grok/xAI 和 Antigravity，统一在兼容的 API 端点之后。请参阅 README 获取当前列表。

问：尝试它的最佳方式是什么？
答：使用 Docker Compose 快速启动，它会自动配置 PostgreSQL 和 Redis 以及网关：

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

问：在我的订阅账户上运行 Sub2API 是否违反提供商的规则？
答：维护者指出这可能与上游提供商的服务条款冲突，并对账户封禁不承担责任；请在部署前查看 README 中的许可证和免责声明。

问：我可以使用 Sub2API 为他人运行付费服务吗？
答：该项目内置了支付集成（EasyPay、支付宝、微信支付、Stripe），用于群组内的成本分摊，但维护者尚未授权该项目的商业运营——请先检查许可证条款。

问：我在哪里报告错误或请求功能？
答：通过主仓库上的 GitHub Issues。

11. 快速链接

仓库：https://github.com/Wei-Shaw/sub2api
中文 README：README_CN.md
部署指南：deploy/README.md
问题/社区讨论：GitHub Issues
版本发布：GitHub Releases

12. 总结

Sub2API 将分散的 AI 订阅账户转化为一个单一的、可管理的、API 兼容的网关，具备 Token 级计费、智能调度和完整的管理控制台。它最适合那些希望共享订阅成本并通过一致界面访问 Claude、OpenAI、Gemini 和 Grok 的开发者和小型团队，前提是在部署前仔细审查上游服务条款和许可影响。