项目概览
Sub2API 是一个面向 AI API 额度分发与运营的网关平台。管理员把上游账号或 API Key 接入系统，创建可用渠道和分组；用户通过 Sub2API 生成的 API Key 调用统一入口，系统负责鉴权、路由、并发控制、协议转换、计费和用量记录。
如果只把它理解为“反向代理”，会低估它的职责。它同时包含数据面和管理面：
- 数据面：接收模型请求、选择账号、访问上游并返回流式或非流式结果。
- 管理面：维护用户、API Key、账号、渠道、分组、套餐、订单、风控和运行状态。
使用前先确认合规要求
项目 README 明确提醒：共享或分发上游订阅额度可能违反服务商条款。部署者需要自行确认账号来源、使用方式、当地法律和上游服务条款。
适合哪些场景
- 团队统一管理多个 AI 平台凭证。
- 将不同上游包装为稳定、统一的 API 入口。
- 按用户、API Key、分组或订阅套餐管理额度。
- 需要账号池调度、故障切换、并发限制和用量审计。
- 构建包含充值、套餐和管理后台的自托管 AI API 服务。
不适合哪些场景
- 只需要把一个固定 API Key 转发到一个固定上游。
- 不愿维护 PostgreSQL、Redis、备份和安全配置。
- 无法确认上游账号共享或转售是否合规。
- 希望系统完全无状态，或不接受计费数据的运维责任。
支持能力
上游平台
当前代码中的核心平台类型包括：
| 平台 | 典型接入方式 | 主要兼容能力 |
|---|---|---|
| Anthropic | OAuth、Setup Token、API Key、上游地址 | Messages、Count Tokens、SSE |
| OpenAI | OAuth、API Key、兼容上游 | Responses、Chat Completions、Embeddings、Images、WebSocket |
| Gemini | OAuth、API Key、Service Account | Gemini 原生 API、Claude/OpenAI 兼容转换 |
| Antigravity | OAuth、API Key、上游地址 | Claude/Gemini 兼容调用 |
| Grok | OAuth、API Key | Responses、图片与视频相关接口 |
| AWS Bedrock | SigV4 或 API Key | Anthropic 模型调用与流式响应 |
具体能力仍取决于账号类型、分组配置、目标模型和当前版本。
平台功能
- 用户注册、登录、第三方 OAuth 与 TOTP。
- API Key 创建、禁用、额度和分组限制。
- 多账号调度、粘性会话、模型映射和故障切换。
- 用户、API Key 和账号级并发控制。
- Token、缓存、图片、视频和按次计费。
- 余额、订阅套餐、兑换码、推广与支付订单。
- 渠道监控、账号测试、错误统计、告警与运维看板。
- 数据备份、用量清理、在线升级和历史版本回退。
技术栈
| 层级 | 技术 |
|---|---|
| 后端 | Go 1.26.5、Gin、Wire |
| 数据访问 | Ent、SQL migrations |
| 前端 | Vue 3、Vite、Pinia、Tailwind CSS |
| 数据库 | PostgreSQL |
| 缓存与协调 | Redis |
| 交付 | 单二进制、Docker 镜像、Docker Compose、systemd |
发布镜像会把前端静态资源嵌入 Go 二进制，因此生产环境只需要对外提供一个应用端口。
两种运行模式
| 模式 | 用途 | 行为 |
|---|---|---|
standard | 正常运营部署 | 启用余额、订阅、计费和配额检查 |
simple | 内部可信环境 | 隐藏部分 SaaS 功能，并跳过计费和余额检查 |
除非是明确的内部使用场景，否则保持 RUN_MODE=standard。
下一步
它解决的核心问题
直接把上游 API Key 发给每个使用者，看似简单，但很快会遇到下面的问题：
| 问题 | 直接共享上游 Key | Sub2API 的处理方式 |
|---|---|---|
| 凭证泄漏 | 每个客户端都拿到真实凭证 | 用户只拿到平台生成的 API Key |
| 多账号切换 | 客户端手动切换 | 服务端统一调度和故障切换 |
| 并发冲突 | 多人争用同一个订阅账号 | 用户、API Key、账号多级并发控制 |
| 用量统计 | 依赖各上游后台 | 统一记录模型、Token、费用和延迟 |
| 权限隔离 | 一个 Key 可以访问全部能力 | 通过分组、模型范围、IP ACL 和配额限制 |
| 计费运营 | 需要另建用户和订单系统 | 内置余额、套餐、兑换码与支付 |
| 运行状态 | 失败后靠用户反馈 | 渠道监控、账号测试、错误日志和告警 |
因此，Sub2API 的真正价值不是改变一个 URL，而是把“上游账号资源”变成可以控制、分配、观察和结算的服务能力。
三类使用者
平台管理员
管理员负责资源供给与系统安全：
- 添加上游账号、API Key、代理和 OAuth 凭证。
- 创建分组并配置账号池、模型范围和计费规则。
- 管理用户、订阅、余额和 API Key。
- 查看错误、并发、账号可用率和渠道监控。
- 处理升级、备份、支付对账和安全事件。
API 使用者
使用者登录 Web 后台创建自己的 Sub2API Key，查看可用渠道、使用记录、余额和订阅，再把 Key 配置给 Claude Code、Codex、Gemini CLI、SDK 或自建应用。
使用者不需要知道请求最终落到哪个真实账号，也不应该接触上游凭证。
二次开发者
开发者通常会扩展：
- 新的上游账号类型或 OAuth 流程。
- 新的协议转换和模型能力。
- 自定义支付、用户属性或外部系统嵌入。
- 调度、计费、监控和内容审核策略。
在动手前建议先读代码目录与模块边界和请求处理链路，因为网关热路径横跨 Handler、Service、Repository 和多个协议包。
产品界面地图
用户侧
| 页面 | 用户可以做什么 |
|---|---|
| 仪表盘 | 查看余额、今日用量、趋势和订阅摘要 |
| API Keys | 创建、修改、删除 Key，选择分组和查看使用方式 |
| 使用记录 | 按时间、模型、端点和状态查询请求 |
| 可用渠道 | 查看平台、模型、价格和渠道状态 |
| 订阅与购买 | 查看套餐、发起支付、查询订单 |
| 兑换 | 使用兑换码获得余额或订阅 |
| 个人资料 | 修改登录信息、通知邮箱和 TOTP |
管理员侧
| 模块 | 管理对象 |
|---|---|
| 用户 | 状态、角色、余额、并发、分组权限和平台配额 |
| 账号 | 上游凭证、代理、模型、并发、优先级和调度状态 |
| 分组 | 平台、账号池、倍率、配额、模型路由和功能开关 |
| 渠道 | 面向用户展示的模型能力、价格和状态 |
| 订阅/支付 | 套餐、订单、支付实例、促销和兑换码 |
| 风控 | 内容审核配置、触发日志和封禁状态 |
| 运维 | 请求指标、错误、账号健康、任务心跳和告警 |
| 系统 | 注册、OAuth、邮件、更新、备份和运行参数 |
完整功能拆解见功能地图。
从安装到完成第一次请求
一套最小可用配置通常按以下顺序建立：
- 部署应用、PostgreSQL 和 Redis。
- 创建管理员并完成基础安全设置。
- 添加代理（如果上游访问需要固定出口）。
- 添加至少一个上游账号并通过账号测试。
- 创建与账号平台一致的分组。
- 把账号加入分组，设置模型范围和倍率。
- 创建普通用户或开放注册。
- 为用户授权分组，创建用户 API Key。
- 使用
/v1/models查看模型列表。 - 发送一次最小请求，并核对用量和费用。
如果缺少账号、分组或用户授权中的任意一环，API Key 即使鉴权成功，也可能返回“无可用账号”或“未分配分组”。
网关入口速览
| 客户端协议 | 主要入口 | 说明 |
|---|---|---|
| Anthropic Messages | POST /v1/messages | 根据分组平台原生转发或转换 |
| Anthropic Count Tokens | POST /v1/messages/count_tokens | 部分平台不支持 |
| OpenAI Responses | POST /v1/responses | 支持流式与子路径 |
| OpenAI Responses WS | GET /v1/responses | WebSocket 入口 |
| Chat Completions | POST /v1/chat/completions | 根据平台选择原生或桥接 |
| Embeddings | POST /v1/embeddings | 当前要求 OpenAI 分组 |
| Images | /v1/images/generations、/v1/images/edits | OpenAI/Grok 能力 |
| Gemini 原生 | /v1beta/models/* | Gemini SDK/CLI 兼容 |
| Codex 直连 | /backend-api/codex/* | 模型清单、Responses、WS |
| Antigravity 专用 | /antigravity/v1/*、/antigravity/v1beta/* | 强制只调度 Antigravity |
更完整的端点和能力差异见支持平台与接口。
需要提前知道的边界
Redis 是运行依赖
Redis 不只是加速页面。并发槽位、限流、粘性会话、刷新锁和后台任务选主都依赖它。Redis 长时间不可用时，系统不能被视为完全健康。
计费是一条跨组件链路
请求前检查余额与订阅，请求后根据 usage 计算费用，最后更新缓存和 PostgreSQL。生产环境必须监控异步用量队列、数据库写入错误和计费去重状态。
账号凭证属于最高敏感数据
数据库中会保存上游 API Key、OAuth token 和 refresh token。数据库、备份、日志、管理后台和运维人员权限都必须按凭证系统的级别保护。
回退程序不等于回退数据库
数据库迁移是向前执行的。升级前备份，比“后台有版本回退按钮”更重要。