Sub2API 是一款专为 AI 产品订阅配额分发和集中管理而设计的一站式开源 API 网关平台。随着大型语言模型（如 Claude、OpenAI、Gemini 等）的广泛普及，企业团队或个人开发者在面对多种大模型订阅时，往往面临账号管理分散、订阅费用高昂和调用难以被统一统计的核心问题。Sub2API 从根本上解决了这一痛点，它通过将各类不同协议的上游账号（如 OAuth 授权、原生 API Key 等）进行底层桥接与统一接入，并在平台内部动态生成标准化的二级 API Key 供客户端使用。
在用户无感知的前提下，Sub2API 完美接管了权限验证、精准到 Token 级别的计费、请求智能路由与负载均衡。它原生集成微信、支付宝及 Stripe 等聚合支付，并具备高并发控制与严格的频率限制功能。管理员可通过直观的可视化仪表盘实时监控流量、阻断恶意请求并分配额度。该平台极大地降低了多模型聚合调用的维护门槛，是开发团队统筹 AI 算力、二次开发 SaaS 服务以及个人 AI 接口合租拼车的首选基础设施。
功能列表
- 多账号统筹接入与管理：深度兼容多种上游大模型账号类型（包括 OAuth 授权、API Key 和 Antigravity 订阅等），集中管理分发 Claude、OpenAI 和 Gemini 等生态节点。
- 标准化 API Key 分发体系：为平台用户生成独立、隔离且受控的 API 密钥，客户端仅需替换 Base URL 即可无缝调用。
- 极度精准的计费追踪：基于底层的 Token 消耗机制统计实时用量，自动换算成本核算，支持不同模型配置独立倍率与计费规则。
- 智能请求调度与会话保持：多渠道账号智能选取与轮询负载均衡，支持会话保持（Sticky Sessions），确保多轮上下文对话连贯且不触发上游封控。
- 高阶并发与限流控制：支持细粒度的用户级与单一账号级并发阈值控制，灵活配置每秒请求数（RPM/RPS）及 Token 消耗速率限制。
- 内置免签聚合支付系统：底层原生集成易支付（EasyPay）、支付宝、微信支付和 Stripe，无需部署独立的充值中控系统，用户即可自助付款兑换额度。
- 现代化可视化管理后台：提供直观的 Web UI 仪表盘，全方位掌控全站 API 流量大盘、异常请求日志、上游账号健康度与平台财务收入状况。
- 极简模式与外挂系统集成：支持单机或内部团队一键开启“极简模式”（Simple Mode）跳过冗杂计费；同时支持通过 iframe 无缝嵌入外部工单或客服等运营系统。
Sub2API 详细安装、配置与使用指南
欢迎使用 Sub2API！为了让您能够获得最佳的使用体验并快速搭建起属于自己的 AI 中转分发网关，我们编写了这份极其详尽的操作指南。本指南将从底层环境准备、安装流程到平台核心运营配置进行全方位拆解。
⚙️ 一、 服务器环境准备
在开始部署之前，请确保您的服务器满足以下基础条件：
- 操作系统：主流 Linux 发行版（推荐 Ubuntu 20.04/22.04、Debian 11+），支持 amd64 或 arm64 架构。
- 运行环境：需要安装 Docker（版本 20.10+）及 Docker Compose（版本 v2+）。
- 网络状态：确保服务器开放了您所需要的访问端口（如默认的
8080），并确保网络能够正常访问官方的 AI 接口或具备代理环境。
🚀 二、 自动化部署安装流程（强烈推荐）
为了避免配置数据库（PostgreSQL 15+）和缓存组件（Redis 7+）所带来的繁琐步骤，Sub2API 官方提供了 Docker Compose 自动化部署脚本，可实现真正意义上的“一键拉起”。
1. 创建部署独立目录并进入
mkdir -p sub2api-deploy && cd sub2api-deploy
2. 下载并运行环境初始化脚本
执行以下命令，脚本将自动拉取部署模板文件，并使用安全算法自动生成环境所需的各类高强度密钥（如数据库密码、JWT 安全密钥、TOTP 双因素加密密钥等）：
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash
3. 后台启动容器集群
确认脚本运行成功且文件已生成完毕后，直接启动容器群，所有数据默认保存在当前的本地目录下，极大地方便了后期的整站迁移与备份：
docker compose up -d
4. 提取管理员初始密码
系统在第一次初始化时会为您生成默认的管理员密码。您可以通过查看控制台日志获取该安全密码：
docker compose logs -f sub2api | grep "admin password"
(注意：如果您是手动挂载使用 docker-compose.local.yml，请在指令中带入 -f docker-compose.local.yml 参数)
💻 三、 核心管理后台操作指南
当程序正常启动后，请在浏览器中访问网关管理面板：http://您的服务器IP:8080，并使用获取到的管理员邮箱和密码进行登录。
1. 接入上游算力（渠道管理）
作为网关，必须先将上游接口挂载到系统中，才能供下游调用：
- 操作路径：左侧菜单栏 ->
渠道管理/上游账号-> 点击新增渠道。 - 参数配置：
- 渠道类型：选择你需要接入的平台商（支持 OpenAI、Claude、Gemini 以及第三方聚合网关）。
- 凭证填入：输入官方提供的
API Key，或是 OAuth 授权所分配的Token。如果你使用的是其它反代站点，则需要将Base URL修改为对应的代理地址。 - 权重与调度：当存在多个相同的模型通道时，您可以分配不同的权重（决定流量倾斜）。务必开启 “会话保持（Sticky Session）”，以保证单名用户连续的上下文对话请求始终落在同一个节点账号上。
2. 用户管理与 API 令牌发放
完成渠道配置后，您需要为您的终端使用者生成独立的密钥：
- 用户分发：在
用户管理界面，您可以直接点击新建账号（或在系统配置开启允许全网公开自助注册）。 - 生成令牌：点击进入某位用户的详情页面，点击
生成新令牌（Tokens），系统将下发一串以sk-开头的密钥。 - 额度划拨：您可以在此页面手动调整用户的余额数字。只有当用户余额大于零，且并发次数未达上限时，对应的请求才会被网关成功放行。
3. 聚合支付自动化充值配置（商业化核心）
如果您希望向外部团队或个人有偿分享您的 API 配额，只需配置系统内置的支付网关，即可彻底解放双手：
- 操作路径：进入
系统设置->支付配置。 - 接口绑定：选择启用的服务商（例如接入易支付免签接口，或者具备资质的 Stripe / 微信 / 支付宝）。填入对应的商户号
Merchant ID以及通信回调密钥。 - 兑换比例配置：定义您的结算汇率（例如 1 CNY 等于多少平台虚拟额度），保存并重启生效。
- 最终效果：普通用户登录他们各自的客户端后台，点击“充值中心”即可使用扫码完成付款。资金到账的瞬间，系统会自动为该用户账户累加调用额度。
4. 高并发防刷与安全加固
在面向公网服务时，一定要防止被恶意刷单消耗：
- 并发控制：在安全设置中设置
单用户最大并发数。 - 请求频率（Rate Limit）：严格定义每一分钟内单一用户最多允许发起的连接次数，避免因为下游滥用而导致你珍贵的上游账号受到官方处罚。
- 关闭不安全的 HTTP 访问：在生产环境中，请在
config.yaml或系统配置内确保security.url_allowlist.allow_insecure_http设置为false，强制所有上游分发与外部接入走高安全性的 HTTPS 协议。
🌐 四、 客户端代码/工具接入方式
您的用户在拿到您平台下发的 API Key 后，在任何主流的 AI 聊天工具（如 Chatbox、LobeChat、NextChat）及代码开发插件中都可以轻松接入：
- 接口地址 (Base URL)：填入您部署的 Sub2API 服务器公网地址，例如
https://api.yourdomain.com。 - API Key：填入 Sub2API 生成的
sk-xxxxxx。 - 模型名称 (Model)：保持官方名称即可（如
gpt-4o或claude-3-opus-20240229），系统将根据模型名全自动在后台执行精确路由匹配。
(注：本帮助文档旨在提供最清晰快捷的操作路径，如遇任何疑难杂症可通过部署管理后台的“一键查看日志”排查相关网络连接错误。)
应用场景
- AI接口合租与拼车共享
由于目前 GPT-4 或 Claude Opus 等旗舰级 AI 模型的官方订阅费用较为昂贵（通常每月需二十美金），独立开发者个人承担压力极大。通过 Sub2API 可以将少数官方大号接入系统，生成多把 API Key 碎片化地分发给数名合租的朋友或网友。平台完善的用量计费模型可以极为公正地按照每个人的真实消耗扣除积分，彻底解决了“均摊费用不合理、使用频次差异大”的拼车痛点。 - 研发团队企业内网算力统管
企业内部开发、产品设计和营销部门对于 AI 模型的算力均有大量需求。如果任由员工使用个人渠道申请调用，往往会导致企业数据泄露的合规风险以及无法监控部门 IT 成本开销。部署内网版 Sub2API 网关后，IT 运维部可以只维护几个高额的官方主控号，然后利用系统下发受到严格请求并发控制与配额上限管理的子账号供各部门使用，最终可利用平台财务报表精准审计各部门的 AI 资源成本投入。 - 二次开发的大模型中转 SaaS 服务
平台内置了极其完备的账单机制、智能多点路由调度和免签聚合支付回调逻辑。这使它具备了成为商业化接口平台的基础设施。创业者和开发者可以将本网关部署于海外稳定节点，通过采购多个可靠廉价的上游 API，利用此系统向C端用户或小B端企业重新售卖优质且统一标准格式的 AI 接口调用额度，通过低买高卖和提供稳定的高并发保障来赚取服务差价。
QA
- Sub2API 可以兼容和接入哪些类型的上游平台？
系统目前支持接入所有采用标准协议访问机制的大型语言模型服务商，其中原生深度适配了 OpenAI（GPT 全系列）、Anthropic（Claude 系列）以及 Google Gemini 等平台。无论是使用原生的 API 密钥绑定，还是基于 OAuth 的鉴权形式乃至第三方代理协议，均能通过平台内置引擎平滑转换。 - 当上游的某一个账号达到调用极限或被封禁时，会影响到我的用户吗？
基本不会。系统自带“智能请求调度网关”。当某一条上游渠道因为请求额度耗尽、触发服务器频繁拦截而返回非正常状态码时，调度引擎会在毫秒级别将当前请求无缝切换并路由到同权重的健康备用账号中，在用户毫无感知的情况下保障业务继续运行。 - 我可以使用本地的 Nginx 对系统进行反向代理并绑定域名吗？
完全可以。由于直接对外暴露 8080 端口并不安全，我们强烈建议使用 Nginx 对服务进行反代并配置 SSL 证书。特别需要注意的是：当您针对 Codex CLI 进行反向代理时，请务必在您的 Nginx 配置文件中的http块内加入一行underscores_in_headers on;，否则 Nginx 将会默认抛弃所有带有下划线的 Header（例如session_id），直接导致平台会话保持功能失效。 - 平台的极简模式（Simple Mode）是什么概念？
如果您只是希望将平台作为一套单机开发辅助工具，供个人或内部几个同事使用，不想看到复杂的充值面板和支付网关页面，可以在环境变量中开启RUN_MODE=simple。系统会进入极简状态，完全跳过繁琐的计费流程、金额核算以及充值模块，只保留最纯粹的模型代理转发和简单的账号管理功能。
