Sub2API：AI API 订阅中转与拼车共享开源项目

Sub2API 一站式开源中转服务，让 Claude、Openai 、Gemini、Grok订阅统一接入，支持拼车共享，更高效分摊成本，原生工具无缝使用。

Sub2API

AI API 网关平台用于订阅配额分配

英文 |中文|日本

⚠️ 重要通知

使用本项目前请仔细阅读以下内容：

• 🚨 服务条款风险：使用本项目可能违反Anthropic及其他上游服务商的服务条款。使用前请仔细阅读相关服务商的用户协议;使用过程中产生的所有风险均由用户自行承担。
• ⚖️ 合规使用：仅在遵守您所在国家或地区的法律法规下使用本项目。严禁任何非法使用。
• 📖 免责声明：本项目仅供技术学习和研究目的。作者不承担因使用本项目而导致的账户封禁、服务中断、数据丢失或其他直接或间接损害的责任。
• 🚫 无商业授权：本项目开发商从未授权任何个人或组织基于本项目进行任何形式的商业运营。以本项目名义或基于本项目进行的任何商业活动与本项目及其开发商无关，所有由此产生的争议、损失和法律责任均由进行该活动的一方单独承担。

❤️ 赞助商

想在这里出现吗？

概述

Sub2API 是一个 AI API 网关平台，旨在分发和管理 AI 产品订阅的 API 配额。用户可以通过平台生成的 API 密钥访问上游 AI 服务，而平台则负责认证、计费、负载均衡和请求转发。

特色

• 多账户管理- 支持多种上游账户类型（OAuth，API 密钥）
• API 密钥分发- 为用户生成和管理API密钥
• 精确计费- 代币级使用跟踪和成本计算
• 智能调度- 智能账户选择，支持粘贴会话
• 并发控制- 每个用户和每个账户的并发限制
• 速率限制- 可配置的请求和令牌速率限制
• 内置支付系统- 支持EasyPay、支付宝、微信支付和Stripe，实现用户自助充值，无需单独支付服务（配置指南)
• 管理仪表盘- 用于监控和管理的网页界面
• 综合组- 管理路由层，将请求的模型解析为多提供者组的具体提供者（操作员指南)
• 外部系统集成- 通过iframe嵌入外部系统（例如工单），以扩展管理仪表盘

生态系统

扩展或集成Sub2API的社区项目：

技术栈

Nginx 反向代理说明

当使用 Nginx 作为 Sub2API（或 CRS）的 Codex CLI 反向代理时，请在http在你的Nginx配置中：

underscores_in_headers on;

Nginx 默认会丢弃包含下划线的头部（例如session_id），这会破坏多账户设置中的粘性会话路由。

部署

方法1：脚本安装（推荐）

一键安装脚本，可从GitHub Releases下载预构建的二进制文件。

前提条件

• Linux服务器（amd64 或 arm64）
• PostgreSQL 15+（已安装并运行）
• Redis 7+（已安装并运行中）
• 根权限

安装步骤

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

剧本将：

1. 检测你的系统架构
2. 下载最新版本
3. 安装二进制文件到/opt/sub2api
4. 创建系统服务
5. 配置系统用户和权限

安装后

# 1. Start the service
sudo systemctl start sub2api

# 2. Enable auto-start on boot
sudo systemctl enable sub2api

# 3. Open Setup Wizard in browser
# http://YOUR_SERVER_IP:8080

设置向导将引导你完成：

• 数据库配置
• Redis 配置
• 管理员账户创建

升级

你可以直接从管理仪表盘点击请查看最新消息左上角的按钮。

网页界面将：

• 自动检查新版本
• 一键下载并应用更新
• 如有需要，支持回滚

实用命令

# Check status
sudo systemctl status sub2api

# View logs
sudo journalctl -u sub2api -f

# Restart service
sudo systemctl restart sub2api

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

方法2：Docker Compose（推荐）

使用 Docker Compose 部署，包括 PostgreSQL 和 Redis 容器。

前提条件

• Docker 20.10+
• Docker Compose v2+

快速启动（一键部署）

使用自动部署脚本以便轻松设置：

# Create deployment directory
mkdir -p sub2api-deploy && cd sub2api-deploy

# Download and run deployment preparation script
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

# Start services
docker compose up -d

# View logs
docker compose logs -f sub2api

剧本的作用：

• 下载docker-compose.local.yml（保存为docker-compose.yml）.env.example
• 生成安全凭证（JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD）
• 创作.env带有自动生成秘密的文件
• 创建数据目录（使用本地目录以便备份/迁移）
• 显示生成的凭证供你参考

手动部署

如果你更喜欢手动设置：

# 1. Clone the repository
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy

# 2. Copy environment configuration
cp .env.example .env
chmod 600 .env

# 3. Edit configuration (generate secure passwords)
nano .env

在.env:

# PostgreSQL password (REQUIRED)
POSTGRES_PASSWORD=your_secure_password_here

# JWT Secret (RECOMMENDED - keeps users logged in after restart)
JWT_SECRET=your_jwt_secret_here

# TOTP Encryption Key (RECOMMENDED - preserves 2FA after restart)
TOTP_ENCRYPTION_KEY=your_totp_key_here

# Optional: Admin account
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your_admin_password

# Optional: Custom port
SERVER_PORT=8080

生成安全机密：

# Generate JWT_SECRET
openssl rand -hex 32

# Generate TOTP_ENCRYPTION_KEY
openssl rand -hex 32

# Generate POSTGRES_PASSWORD
openssl rand -hex 32

# 4. Create data directories (for local version)
mkdir -p data postgres_data redis_data

# 5. Start all services
# Option A: Local directory version (recommended - easy migration)
docker compose -f docker-compose.local.yml up -d

# Option B: Named volumes version (simple setup)
docker compose up -d

# 6. Check status
docker compose -f docker-compose.local.yml ps

# 7. View logs
docker compose -f docker-compose.local.yml logs -f sub2api

部署版本

推荐：用途docker-compose.local.yml（通过脚本部署）以便更便捷的数据管理。

交通

开门http://YOUR_SERVER_IP:8080在你的浏览器里。

如果管理员密码是自动生成的，可以在日志中找到：

docker compose -f docker-compose.local.yml logs sub2api | grep "admin password"

升级

# Pull latest image and recreate container
docker compose -f docker-compose.local.yml pull
docker compose -f docker-compose.local.yml up -d

简单迁移（本地目录版本）

使用docker-compose.local.yml，轻松迁移到新服务器：

# On source server
docker compose -f docker-compose.local.yml down
cd ..
tar czf sub2api-complete.tar.gz sub2api-deploy/

# Transfer to new server
scp sub2api-complete.tar.gz user@new-server:/path/

# On new server
tar xzf sub2api-complete.tar.gz
cd sub2api-deploy/
docker compose -f docker-compose.local.yml up -d

实用命令

# Stop all services
docker compose -f docker-compose.local.yml down

# Restart
docker compose -f docker-compose.local.yml restart

# View all logs
docker compose -f docker-compose.local.yml logs -f

# Remove all data (caution!)
docker compose -f docker-compose.local.yml down
rm -rf data/ postgres_data/ redis_data/

方法三：苹果容器（macOS）

运行macOS 26的苹果硅Mac可以运行完整的Sub2API、PostgreSQL和Redis协议栈。container1.1.0或更新版本：

git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy
./apple-container.sh init
./apple-container.sh up
./apple-container.sh status

这是一个由操作员管理的本地工作流;Docker Compose 仍然是推荐的生产路径。参见部署/APPLE_CONTAINER.MD用于生命周期命令、持久化、升级和运行时限制。

方法4：从源头构建

从源代码构建并运行，用于开发或定制。

前提条件

• Go 1.21+
• Node.js 18+
• PostgreSQL 15+
• Redis 7+

构建步骤

# 1. Clone the repository
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api

# 2. Install pnpm (if not already installed)
npm install -g pnpm

# 3. Build frontend
cd frontend
pnpm install
pnpm run build
# Output will be in ../backend/internal/web/dist/

# 4. Build backend with embedded frontend
cd ../backend
VERSION="$(./scripts/resolve-version.sh)"
go build -tags embed -ldflags="-X main.Version=${VERSION}" -o sub2api ./cmd/server

# 5. Create configuration file
cp ../deploy/config.example.yaml ./config.yaml

# 6. Edit configuration
nano config.yaml

注：该-tags embedflag 将前端嵌入到二进制文件中。没有这个标志，二进制文件就无法服务于前端界面。

密钥配置config.yaml:

server:
  host: "0.0.0.0"
  port: 8080
  mode: "release"

database:
  host: "localhost"
  port: 5432
  user: "postgres"
  password: "your_password"
  dbname: "sub2api"

redis:
  host: "localhost"
  port: 6379
  username: ""
  password: ""

jwt:
  secret: "change-this-to-a-secure-random-string"
  expire_hour: 24

default:
  user_concurrency: 5
  user_balance: 0
  api_key_prefix: "sk-"
  rate_multiplier: 1.0

还有更多与安全相关的选项config.yaml:

• cors.allowed_origins对于CORS允许名单
• security.url_allowlist用于上游/定价/CRS主机允许列表
• security.url_allowlist.enabled禁用URL验证（请谨慎使用）
• security.url_allowlist.allow_insecure_http在验证被禁用时允许HTTP URL
• security.url_allowlist.allow_private_hosts允许私有/本地IP地址
• security.response_headers.enabled启用可配置响应头过滤（禁用时使用默认允许列表）
• security.csp用于控制内容-安全-策略头部
• billing.circuit_breaker因账单错误关闭失败
• security.trust_forwarded_ip_for_api_key_acl启用传统RAW转发头部接管（默认启用以实现升级兼容性）;禁用以强制执行server.trusted_proxies该CIDR应仅包含直接连接到Sub2API的精确代理CIDR
• security.forwarded_client_ip_headers配置最多16个第三方CDN客户端IP头部名称;仅在启用遗留接管时，先按顺序检查，先于内置头部检查
• turnstile.required需要在释放模式下使用Turnstile

自定义客户端-IP头部可以在YAML中设置，或作为逗号分隔的环境变量：

SECURITY_FORWARDED_CLIENT_IP_HEADERS=True-Client-IP,X-CDN-Client-IP

头部名称会被验证、规范化并去重。管理员安全设置可以在不重启的情况下更新列表;新安装会保留 YAML/环境默认值，现有安装则会补填缺失的数据库值。

当禁用遗留接管时，所有自定义和内置的原始转发头部都会被忽略，Gin 仅使用server.trusted_proxies.在启用接管期间，将起始地址与CDN/代理地址设置防火墙，并让边缘覆盖所有受信任的客户端IP头部。

参见deploy/EDGE_SECURITY.md用于完善迁移和信托边界规则。

⚠️ 安全警告：HTTP URL 配置

当security.url_allowlist.enabled=false系统执行最小的URL验证，且默认允许HTTP URL（开发友好模式;Docker Compose 部署使用相同的默认设置。）对于生产环境，明确将此限制为仅支持 HTTPS：

security:
  url_allowlist:
    enabled: false                # Disable allowlist checks
    allow_insecure_http: false    # HTTPS only (recommended for production)

或者通过环境变量：

SECURITY_URL_ALLOWLIST_ENABLED=false
SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=false

允许HTTP的风险：

• API 密钥和传输的数据明文（易被拦截）
• 易感中间人攻击（MITM）
• 不适合制作环境

何时使用 HTTP：

• ✅ 使用本地服务器进行开发/测试（http://localhost)
• ✅ 拥有可信端点的内部网络
• ✅ 在获得 HTTPS 之前测试账户连接
• ❌ 生产环境（仅使用 HTTPS）

HTTP URL 的示例错误allow_insecure_http: false设定为：

Invalid base URL: invalid url scheme: http

如果你禁用了URL验证或响应头部过滤，请加固你的网络层：

• 为上游域名/IP强制执行出口允许列表
• 阻断私有/环回/链路-本地范围
• 强制执行仅限TLS的出站流量
• 在代理处剥离敏感的上游响应头

OpenAI 响应 WebSocket 入口限制

gateway.openai_ws限制面向客户端的响应WebSocket会话的生命周期和总计数。这些保护措施独立于每回合用户和账户并发槽，后者在回合间释放。

gateway:
  openai_ws:
    # Total time to receive and decompress the first client message.
    client_first_message_timeout_seconds: 30
    # Close a client socket idle between completed turns; 0 disables this safeguard.
    ingress_inter_turn_idle_timeout_seconds: 300
    # Distributed API-key limit for live client ingress sessions; 0 disables it.
    max_ingress_connections_per_api_key: 64

首次消息超时是总的读取截止时间。接受大型上下文或图像密集请求且链路较慢的部署，超时时间可延长至120-300秒。该超时时间在HTTP桥路由前到期，因此桥模式不会覆盖该限制。

连接上限通过 Redis 协调，使用一个 60 秒的租用期，每 20 秒刷新一次。无法确认完整租约期限的进程会关闭其本地 WebSocket，而不是继续超出全局限制。

在选择账户级WS模式（如http_bridge:

gateway:
  openai_ws:
    mode_router_v2_enabled: true

或者说是GATEWAY_OPENAI_WS_MODE_ROUTER_V2_ENABLED=true在环境中。用途http_bridge用于在推出或缓解上游WebSocket问题时的客户端WebSocket/上游HTTP操作。

⚠️ 重要提示：创建管理员账户

初始管理员账户是仅通过设置向导创建（服役地点http://:8080首次播出时）。该default.admin_email/default.admin_password场config.yaml是未使用过为了创造它——他们存在于模板中，出于历史原因。

因为上面的第5步是预先创建的config.yaml，设置向导将为第一次就跳过了：服务器检测到已有配置后，直接启动到正常模式，并设置空users因此，第一次登录尝试失败，invalid email or password.

创建管理员账户有两种方式：

1. 推荐——让法师生成config.yaml:跳过第5步（不要运行cp).开始./sub2api直接;设置向导在http://localhost:8080带你完成数据库、Redis和管理员账户设置，然后写作config.yaml给你。
2. 如果你已经创建了config.yaml:暂时把它移到一边，让法师第一次触发，然后再恢复：

   mv config.yaml config.yaml.bak
   ./sub2api        # wizard runs at http://localhost:8080 and writes a fresh config.yaml
   # stop the server (Ctrl+C) once the wizard completes, then restore your config:
   mv config.yaml.bak config.yaml
   ./sub2api        # restart in normal mode and log in with the admin you just created
   

# 6. Run the application
./sub2api

开发模式

# Backend (with hot reload)
cd backend
go run ./cmd/server

# Frontend (with hot reload)
cd frontend
pnpm run dev

代码生成

编辑时backend/ent/schema，再生耳鸣+线：

cd backend
go generate ./ent
go generate ./cmd/server

简单模式

简单模式为个人开发者或内部团队设计，希望快速访问但不包含完整SaaS功能。

• 启用：设置环境变量RUN_MODE=simple
• 区别：隐藏SaaS相关功能并跳过计费流程
• 安全提示：在生产环境中，你还必须设置SIMPLE_MODE_CONFIRM=true允许启动

异步图像任务

长期运行的OpenAI/Grok图像生成和编辑可以通过以下方式提交/v1/images/generations/async或/v1/images/edits/async，随后在/v1/images/tasks/{task_id}无需保持 CDN 连接开启。

参见异步图像任务用于请求和响应示例。

Grok / xAI 支持

Sub2API 支持通过 xAI OAuth 的 Grok 订阅账户和标准的 xAI API 密钥账户。这两种账户类型都会将兼容 OpenAI 的响应流量转发给 xAI。

支持范围

• 站台名称：grok
• 账户类型：OAuth 订阅账户和 xAI API 密钥账户
• 公众响应目标：/v1/responses,/responses， 和/backend-api/codex/responses转发到 OAuth 账户的 Grok 订阅代理，或https://api.x.ai/v1/responses对于API密钥账户
• 公共兼容Claude的目标：/v1/messages转换为 xAI 响应，并作为 Anthropic Messages 输出返回给 Claude CLI 风格客户端
• 公开聊天完成目标：/v1/chat/completions以及/chat/completions，转发到上游的账户类型专用xAI
• Codex CLI 风格的响应 WebSocket 入口被响应目标接受，并桥接到 xAI HTTP/SSE 响应上游
• 文本模型：grok-4.5,grok-4.3,grok-build-0.1,grok-composer-2.5-fast,grok-4.20-0309-reasoning,grok-4.20-0309-non-reasoning， 和grok-4.20-multi-agent-0309
• Grok团体的媒体目标：/v1/images/generations,/images/generations,/v1/images/edits,/images/edits,/v1/videos/generations,/videos/generations,/v1/videos/edits,/videos/edits,/v1/videos/extensions,/videos/extensions,/v1/videos/{request_id}， 和/videos/{request_id}.生成、编辑和扩展请求需要组的图像生成权限。
• 媒体模式：grok-imagine,grok-imagine-image-quality,grok-imagine-image,grok-imagine-image-2.0,grok-imagine-edit,grok-imagine-video， 和grok-imagine-video-1.5
• JSON 图像编辑和视频生成请求接受图像引用image,images,reference_images， 和mask对象。使用url对于兼容xAI的有效载荷;遗产image_url场保持接受，并归一化为url然后转发。
• 该服务提供者超出权限范围：TTS、转录、浏览器自动化、Cookie和Grok网页抓取

OAuth 配置

Grok OAuth 流程使用 PKCE，无需提交私有秘密。默认客户端细节遵循兼容客户端使用的公共 xAI OAuth 流程，且每个值都可以被环境变量覆盖：

管理员可以从仪表盘创建 Grok OAuth 或 API 密钥账户。OAuth 授权和重新授权也可以通过管理 API 获得：

OAuth 凭据存储可重用现有账户 JSON 字段：access_token,refresh_token,token_type,expires_at,base_url， 可选email， 可选subscription_tier， 和entitlement_status.OAuth 推断默认为https://cli-chat-proxy.grok.com/v1;存储旧https://api.x.ai/v1默认节点在运行时被重定向到订阅代理。

显式自定义上游保持不变。

对于 API 密钥账户，选择Grok → API Key在创建账户对话框中。官方基础URL默认为https://api.x.ai/v1;凭据使用现有的base_url以及api_key账户字段。

OAuth 账户继续使用上述订阅流程。

Grok Build CLI 配置

1. 在Sub2API管理仪表盘中，添加以下任一grokOAuth 账户并完成 xAI 授权，或者添加一个 Grok API 密钥账户。
2. 创建一个Grok组，将账户绑定到该组，然后为该组创建Sub2API API密钥。
3. 在用户API密钥页面，点击使用密钥并选择Grok CLI.该模态生成适用于macOS/Linux或Windows的正确文件和基础URL。它还提供OpenCode配置OpenCodeTab。
4. 如果手动配置，请保存以下内容为~/.grok/config.toml（Windows：%USERPROFILE%\.grok\config.toml):

[models]
default = "grok"
web_search = "grok"

[model."grok"]
model = "grok-4.5"
base_url = "https://your-sub2api.example.com/v1"
name = "Grok 4.5"
api_key = "sk-your-sub2api-key"
api_backend = "responses"
context_window = 1000000
supports_backend_search = true

备份现有的config.toml在合并该条目之前。该文件包含 Sub2API API 密钥，因此应保持私密，并在支持的情况下限制其权限。验证有效配置并发送烟雾请求：

grok inspect
grok -p "Reply with sub2api-ok" -m grok

该base_url上面是公共的Sub2API URL，结尾为/v1，不是api.x.ai或者内部的 xAI OAuth 代理 URL。

使用情况与配额显示

xAI 配额是被动的。Sub2API 不创造订阅配额值;它会记录 xAI 发送成功或速率限制上游响应的白名单 xAI 速率限制头。在第一个可用上游响应之前，仪表盘显示配额为未知，仍显示本地 Sub2API 使用统计数据。

401回复会暂时将凭证无效的账户从排程中移除。403响应被视为访问失败或权限失败，而非令牌刷新循环。429响应的使用Retry-After或者短暂的冷却时间，暂时将账户从排程中移除。

新的Grok图像和视频生成请求使用媒体特定的资格检查。API密钥账户仍具资格。OAuth账户需要xAI计费探测的正面付费权利证据;免费、禁止、缺失、格式错误和不确定的计费观察被排除在新媒体生成之外。

未被观察的OAuth账户在首个媒体请求转发前会被探查，导入时会主动运行计费优先配额探查。聊天请求和视频状态查询不受此仅限媒体隔离的影响。

如果无符合资格的账户，媒体端点返回HTTP503错误类型grok_media_no_eligible_account.

管理员可以通过账户创建/更新 API 设置自动媒体资格extra.grok_media_eligible到false（排除）或true（强制力合格）。更新时，设置为null移除覆盖并恢复自动探测行为;省略字段则保持当前覆盖。

仅仅每周允许期不被视为付费层信号。成功的图像响应必须至少包含一个实际图像输出;空HTTP200响应会触发账户故障切换，而不是被计入并作为成功世代返回。

反重力支撑

Sub2API 支持反重力账户。授权后，Claude 和 Gemini 型号可使用专用端点。

专用端点

Claude 代码配置

export ANTHROPIC_BASE_URL="http://localhost:8080/antigravity"
export ANTHROPIC_AUTH_TOKEN="sk-xxx"

混合调度模式

反重力账户支持可选混合调度.启用后，通用端点/v1/messages以及/v1beta/也会将请求路由到反重力账户。

⚠️ 警告：拟人克劳德与反重力克劳德不能在同一对话语境中混合.用小组来正确隔离他们。

项目结构

sub2api/
├── backend/                  # Go backend service
│   ├── cmd/server/           # Application entry
│   ├── internal/             # Internal modules
│   │   ├── config/           # Configuration
│   │   ├── model/            # Data models
│   │   ├── service/          # Business logic
│   │   ├── handler/          # HTTP handlers
│   │   └── gateway/          # API gateway core
│   └── resources/            # Static resources
│
├── frontend/                 # Vue 3 frontend
│   └── src/
│       ├── api/              # API calls
│       ├── stores/           # State management
│       ├── views/            # Page components
│       └── components/       # Reusable components
│
└── deploy/                   # Deployment files
    ├── docker-compose.yml    # Docker Compose configuration
    ├── .env.example          # Environment variables for Docker Compose
    ├── config.example.yaml   # Full config file for binary deployment
    └── install.sh            # One-click installation script

星级历史

许可

该项目授权在GNU 宽松通用公共许可证 v3.0（或者更晚）。

版权所有 （c） 2026 韦斯利·利迪克

如果你觉得这个项目有用，请给它一个星！