Skip to content
 
 

Repository files navigation

当前正式版:v2.8.8 提供原生 780 采票、分组模型限制和账号质量检测更新。780 采票默认关闭,票长与模型声明不代表能力保证;详见发布说明。

Sub2API Logo

Sub2API

Go Vue PostgreSQL Redis Docker

tosky.io 维护的 Sub2API 独立分支

按需同步上游更新,扩展实用功能,独立发布生产版本。

平台 · 使用文档 · 版本下载 · 问题反馈

中文 | English | 日本語

社区交流群

欢迎正在部署、使用或维护 Sub2API 的朋友加入 QQ 群「中转技术交流」(群号 1004036018),交流部署实践、协议兼容、出口代理和功能改进。也欢迎参与问题复现、测试、文档补充和 Pull Request,一起维护这个独立分支。

QQ 群:中转技术交流,群号 1004036018
加入 QQ 群「中转技术交流」
赞赏码:如果帮到大家可以打赏咖啡
如果帮到大家可以打赏咖啡!

二维码长期有效。需要长期留档、报告问题或讨论具体改动时,请使用 Issues

本仓库的维护方向

基于 Wei-Shaw/sub2api 持续维护,按需 cherry-pick 上游更新,同时保留并迭代自己的功能。默认分支为 production,发布版本和更新源均使用本仓库。

  • DeepSeek 与 Codex 适配:支持 Responses 到 Chat Completions 的转换、工具调用历史和上下文压缩兼容。配置模型映射后,可通过切换 API Key 分组使用 DeepSeek,沿用客户端配置。操作教程
  • Codex ticket 管理:提供后台采集、注入、模型选择及账号状态展示;相关开关和采集代理由管理员配置。
  • Mihomo 出口管理:集成采集出口管理、票据刷新策略和节点状态操作,日常业务代理与采集出口分别配置。
  • 独立发布与升级:使用 ranxi2001/sub2api 的 Release、安装资源和容器镜像,具体版本变化见 更新说明

项目概述

Sub2API 是一个 AI API 网关平台,用于分发和管理 AI 产品订阅的 API 配额。用户通过平台生成的 API Key 调用上游 AI 服务,平台负责鉴权、计费、负载均衡和请求转发。

核心功能

  • 多账号管理 - 支持多种上游账号类型(OAuth、API Key)
  • API Key 分发 - 为用户生成和管理 API Key
  • 精确计费 - Token 级别的用量追踪和成本计算
  • 智能调度 - 智能账号选择,支持粘性会话
  • 并发控制 - 用户级和账号级并发限制
  • 速率限制 - 可配置的请求和 Token 速率限制
  • 内置支付系统 - 支持 EasyPay 易支付、支付宝官方、微信官方、Stripe,用户自助充值,无需独立部署支付服务(配置指南
  • 管理后台 - Web 界面进行监控和管理
  • 外部系统集成 - 支持通过 iframe 嵌入外部系统(如工单等),扩展管理后台功能

技术栈

组件 技术
后端 Go 1.27.0, Gin, Ent
前端 Vue 3.4+, Vite 5+, TailwindCSS
数据库 PostgreSQL 15+
缓存/队列 Redis 7+

Nginx 反向代理注意事项

通过 Nginx 反向代理 Sub2API(或 CRS 服务)并搭配 Codex CLI 使用时,需要在 Nginx 配置的 http 块中添加:

underscores_in_headers on;

Nginx 默认会丢弃名称中含下划线的请求头(如 session_id),这会导致多账号环境下的粘性会话功能失效。

Codex Fast/Flex 策略说明

管理员后台的 系统设置 -> 网关服务 -> OpenAI Fast/Flex 策略 只负责处理请求体中的 service_tier,不会修改 Codex 客户端的模型目录,也不会让 Codex UI 自动出现 Speed 或 /fast 选项。

策略支持以下处理方式:

  • pass:保留客户端传入的 service_tierfast 会规范为上游使用的 priority
  • filter:移除 service_tier,按普通优先级请求。
  • block:拒绝匹配的 Fast/Flex 请求。
  • force_priority:将匹配请求强制设置为 priority,会按 Priority/Fast 价格计费。为避免升级后改变既有规则语义,all 只匹配显式存在的 tier;如需让省略 service_tier 的 OpenAI 请求也强制升级,必须新增 service_tier=missing + force_priority 规则。非 OpenAI 平台不会执行缺省 tier 注入。这种方式可以让请求实际使用 Fast,但 Codex UI 仍可能不显示 Fast 状态。

Codex 的 Fast 入口由客户端模型目录驱动。只有当前模型目录声明了 additional_speed_tiers: ["fast"] 和对应的 service_tiers,Codex 才会显示 /fast。通过 API Key 或自定义模型提供商连接 Sub2API 时,如果模型目录没有这些字段,即使后台配置了 force_priority,重启 Codex 后也不会出现 Speed 选项。

客户端可在 ~/.codex/config.toml 中直接指定默认请求级别:

service_tier = "fast"

[features]
fast_mode = true

其中 service_tier = "fast" 会让请求携带 Fast 设置;features.fast_mode 只启用客户端 Fast 功能。模型目录没有声明 Fast 能力时,/fast 仍可能不显示。可通过 Sub2API 使用记录确认最终 service_tier 是否为 priority


部署方式

方式一:脚本安装(推荐)

一键安装脚本,自动从 GitHub Releases 下载预编译的二进制文件。

前置条件

  • Linux 服务器(amd64 或 arm64)
  • PostgreSQL 15+(已安装并运行)
  • Redis 7+(已安装并运行)
  • Root 权限

安装步骤

curl -sSL https://raw.githubusercontent.com/ranxi2001/sub2api/production/deploy/install.sh | sudo bash

脚本会自动:

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

安装后配置

# 1. 启动服务
sudo systemctl start sub2api

# 2. 设置开机自启
sudo systemctl enable sub2api

# 3. 在浏览器中打开设置向导
# http://你的服务器IP:8080

设置向导将引导你完成:

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

升级

可以直接在 管理后台 左上角点击 检测更新 按钮进行在线升级。

网页升级功能支持:

  • 自动检测新版本
  • 一键下载并应用更新
  • 支持回滚

常用命令

# 查看状态
sudo systemctl status sub2api

# 查看日志
sudo journalctl -u sub2api -f

# 重启服务
sudo systemctl restart sub2api

# 卸载
curl -sSL https://raw.githubusercontent.com/ranxi2001/sub2api/production/deploy/install.sh | sudo bash -s -- uninstall -y

方式二:Docker Compose(推荐)

使用 Docker Compose 部署,包含 PostgreSQL 和 Redis 容器。

前置条件

  • Docker 20.10+
  • Docker Compose v2+

快速开始(一键部署)

使用自动化部署脚本快速搭建:

# 创建部署目录
mkdir -p sub2api-deploy && cd sub2api-deploy

# 下载并运行部署准备脚本
curl -sSL https://raw.githubusercontent.com/ranxi2001/sub2api/production/deploy/docker-deploy.sh | bash

# 启动服务
docker compose up -d

# 查看日志
docker compose logs -f sub2api

脚本功能:

  • 下载 docker-compose.local.yml(本地保存为 docker-compose.yml)和 .env.example
  • 自动生成安全凭证(JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD)
  • 创建 .env 文件并填充自动生成的密钥
  • 创建数据目录(使用本地目录,便于备份和迁移)
  • 显示生成的凭证供你记录

手动部署

如果你希望手动配置:

# 1. 克隆仓库
git clone --branch production https://github.com/ranxi2001/sub2api.git
cd sub2api/deploy

# 2. 复制环境配置文件
cp .env.example .env
chmod 600 .env

# 3. 编辑配置(生成安全密码)
nano .env

.env 必须配置项:

# PostgreSQL 密码(必需)
POSTGRES_PASSWORD=your_secure_password_here

# JWT 密钥(推荐 - 重启后保持用户登录状态)
JWT_SECRET=your_jwt_secret_here

# TOTP 加密密钥(推荐 - 重启后保留双因素认证)
TOTP_ENCRYPTION_KEY=your_totp_key_here

# 可选:管理员账号
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your_admin_password

# 可选:自定义端口
SERVER_PORT=8080

生成安全密钥:

# 生成 JWT_SECRET
openssl rand -hex 32

# 生成 TOTP_ENCRYPTION_KEY
openssl rand -hex 32

# 生成 POSTGRES_PASSWORD
openssl rand -hex 32
# 4. 创建数据目录(本地版)
mkdir -p data postgres_data redis_data

# 5. 启动所有服务
# 选项 A:本地目录版(推荐 - 易于迁移)
docker compose -f docker-compose.local.yml up -d

# 选项 B:命名卷版(简单设置)
docker compose up -d

# 6. 查看状态
docker compose -f docker-compose.local.yml ps

# 7. 查看日志
docker compose -f docker-compose.local.yml logs -f sub2api

部署版本对比

版本 数据存储 迁移便利性 适用场景
docker-compose.local.yml 本地目录 ✅ 简单(打包整个目录) 生产环境、频繁备份
docker-compose.yml 命名卷 ⚠️ 需要 docker 命令 简单设置

推荐: 使用 docker-compose.local.yml(脚本部署)以便更轻松地管理数据。

启用“数据管理”功能(datamanagementd)

如需启用管理后台“数据管理”,需要额外部署宿主机数据管理进程 datamanagementd

关键点:

  • 主进程固定探测:/tmp/sub2api-datamanagement.sock
  • 只有该 Socket 可连通时,数据管理功能才会开启
  • Docker 场景需将宿主机 Socket 挂载到容器同路径

详细部署步骤见:deploy/DATAMANAGEMENTD_CN.md

访问

在浏览器中打开 http://你的服务器IP:8080

如果管理员密码是自动生成的,在日志中查找:

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

升级

# 拉取最新镜像并重建容器
docker compose -f docker-compose.local.yml pull
docker compose -f docker-compose.local.yml up -d

轻松迁移(本地目录版)

使用 docker-compose.local.yml 时,可以轻松迁移到新服务器:

# 源服务器
docker compose -f docker-compose.local.yml down
cd ..
tar czf sub2api-complete.tar.gz sub2api-deploy/

# 传输到新服务器
scp sub2api-complete.tar.gz user@new-server:/path/

# 新服务器
tar xzf sub2api-complete.tar.gz
cd sub2api-deploy/
docker compose -f docker-compose.local.yml up -d

常用命令

# 停止所有服务
docker compose -f docker-compose.local.yml down

# 重启
docker compose -f docker-compose.local.yml restart

# 查看所有日志
docker compose -f docker-compose.local.yml logs -f

# 删除所有数据(谨慎!)
docker compose -f docker-compose.local.yml down
rm -rf data/ postgres_data/ redis_data/

方式三:Apple container(macOS)

Apple 芯片 Mac 在 macOS 26 上可使用 Apple container 1.1.0 或更高版本运行完整的 Sub2API、PostgreSQL 和 Redis:

git clone --branch production https://github.com/ranxi2001/sub2api.git
cd sub2api/deploy
./apple-container.sh init
./apple-container.sh up
./apple-container.sh status

该方式面向本地开发和人工运维,不提供持续重启监管;生产部署仍推荐 Docker Compose。生命周期命令、持久化、升级和运行时限制见 deploy/APPLE_CONTAINER.md


方式四:源码编译

从源码编译安装,适合开发或定制需求。

前置条件

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

编译步骤

# 1. 克隆仓库
git clone --branch production https://github.com/ranxi2001/sub2api.git
cd sub2api

# 2. 安装 pnpm(如果还没有安装)
npm install -g pnpm

# 3. 编译前端
cd frontend
pnpm install
pnpm run build
# 构建产物输出到 ../backend/internal/web/dist/

# 4. 编译后端(嵌入前端)
cd ../backend
VERSION="$(./scripts/resolve-version.sh)"
go build -tags embed -ldflags="-X main.Version=${VERSION}" -o sub2api ./cmd/server

# 5. 创建配置文件
cp ../deploy/config.example.yaml ./config.yaml

# 6. 编辑配置
nano config.yaml

注意: -tags embed 参数会将前端嵌入到二进制文件中。不使用此参数编译的程序将不包含前端界面。

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
  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 配置 Content-Security-Policy
  • billing.circuit_breaker 计费异常时 fail-closed
  • security.trust_forwarded_ip_for_api_key_acl 控制旧版原始转发头接管(为升级兼容默认开启);关闭后严格使用 server.trusted_proxies,其中只应填写直接连接 Sub2API 的精确代理 CIDR
  • security.forwarded_client_ip_headers 最多配置 16 个第三方 CDN 客户端 IP 请求头;仅在旧版接管开启时按顺序优先于内置请求头解析
  • turnstile.required 在 release 模式强制启用 Turnstile

自定义客户端 IP 请求头可通过 YAML 配置,也可使用逗号分隔的环境变量:

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

请求头名称会经过合法性校验、规范化和大小写无关去重。管理员可在安全设置中动态更新列表,无需重启;新安装会持久化 YAML/环境变量默认值,旧安装缺少数据库字段时会自动回填。关闭旧版接管后,自定义头和内置原始转发头均被忽略,只使用 server.trusted_proxies。开启接管时必须限制源站仅允许 CDN/代理访问,并确保边缘代理覆盖所有受信客户端 IP 请求头。完整迁移规则和信任边界见 deploy/EDGE_SECURITY.md

网关防御纵深建议(重点)

  • gateway.upstream_response_read_max_bytes:限制非流式上游响应读取大小(默认 8MB),用于防止异常响应导致内存放大。
  • gateway.proxy_probe_response_read_max_bytes:限制代理探测响应读取大小(默认 1MB)。
  • gateway.gemini_debug_response_headers:默认 false,仅在排障时短时开启,避免高频请求日志开销。
  • /auth/register/auth/login/auth/login/2fa/auth/send-verify-code 已提供服务端兜底限流(Redis 故障时 fail-close)。
  • 推荐将 WAF/CDN 作为第一层防护,服务端限流与响应读取上限作为第二层兜底;两层同时保留,避免旁路流量与误配置风险。

⚠️ 安全警告:HTTP URL 配置

security.url_allowlist.enabled=false 时,系统仅执行最小 URL 校验,且默认允许 HTTP URL(开发友好模式,Docker Compose 部署的默认值一致)。生产环境建议显式收紧为仅允许 HTTPS:

security:
  url_allowlist:
    enabled: false                # 禁用白名单检查
    allow_insecure_http: false    # 仅允许 HTTPS(生产环境推荐)

或通过环境变量:

SECURITY_URL_ALLOWLIST_ENABLED=false
SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=false

允许 HTTP 的风险:

  • API 密钥和数据以明文传输(可被截获)
  • 易受中间人攻击 (MITM)
  • 不适合生产环境

适用场景:

  • ✅ 开发/测试环境的本地服务器(http://localhost)
  • ✅ 内网可信端点
  • ✅ 获取 HTTPS 前测试账号连通性
  • ❌ 生产环境(仅使用 HTTPS)

设置 allow_insecure_http: false 后,HTTP URL 会返回如下错误:

Invalid base URL: invalid url scheme: http

如关闭 URL 校验或响应头过滤,请加强网络层防护:

  • 出站访问白名单限制上游域名/IP
  • 阻断私网/回环/链路本地地址
  • 强制仅允许 TLS 出站
  • 在反向代理层移除敏感响应头

⚠️ 重要:创建管理员账号

初始管理员账号只能通过 setup 向导创建(首次启动时访问 http://<host>:8080)。config.yaml 中的 default.admin_email / default.admin_password 字段不会被用来创建管理员——它们只是出于历史原因保留在模板里。

由于上面第 5 步预先创建了 config.yamlsetup 向导在首次启动时会被跳过:服务检测到 config 已存在,会直接进入正常模式,此时 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        # 向导在 http://localhost:8080 启动,并生成新的 config.yaml
    # 向导完成后 Ctrl+C 停服,再恢复你的配置:
    mv config.yaml.bak config.yaml
    ./sub2api        # 重启进入正常模式,用刚创建的管理员登录
# 6. 运行应用
./sub2api

HTTP/2 (h2c) 与 HTTP/1.1 回退

后端明文端口默认支持 h2c,并保留 HTTP/1.1 回退用于 WebSocket 与旧客户端。浏览器通常不支持 h2c,性能收益主要在反向代理或内网链路。

反向代理示例(Caddy):

transport http {
	versions h2c h1
}

验证:

# h2c prior knowledge
curl --http2-prior-knowledge -I http://localhost:8080/health
# HTTP/1.1 回退
curl --http1.1 -I http://localhost:8080/health
# WebSocket 回退验证(需管理员 token)
websocat -H="Sec-WebSocket-Protocol: sub2api-admin, jwt.<ADMIN_TOKEN>" ws://localhost:8080/api/v1/admin/ops/ws/qps

开发模式

# 后端(支持热重载)
cd backend
go run ./cmd/server

# 前端(支持热重载)
cd frontend
pnpm run dev

代码生成

修改 backend/ent/schema 后,需要重新生成 Ent + Wire:

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

OpenAI 图片模型

支持 gpt-image-2.5-flaregpt-image-2.5-sunburst 及其 2026-09-08 日期快照,可通过 /v1/images/generations/v1/images/edits 调用。quality 支持 xhighmaxauto,合法自定义尺寸和图片 usage 明细保持透传。

OAuth / Setup Token 图片请求使用 Responses 主控模型调用 image_generation 工具,默认主控为 gpt-5.6-luna。可设置 SUB2API_IMAGES_MAIN_MODEL 切换为账号支持的文本模型;Docker Compose 用户修改 .env 后执行 docker compose up -d 重建容器。该配置不会替换所选图片模型,也不会覆盖 /v1/responses 请求中已经提供的文本主控模型。

升级后,无模型限制的账号自动支持新模型。已有显式账号映射或分组白名单需要加入两个 2.5 模型(日期快照按需加入);升级不会自动扩大管理员设置的模型权限。新模型内置价格包含官方文本输入、图片输入和图片输出 token 费率,远端价格表尚未更新时使用内置 2.5 价格;实际按次或按 token 计费仍由既有分组/渠道配置决定。

简易模式

简易模式适合个人开发者或内部团队快速使用,不依赖完整 SaaS 功能。

  • 启用方式:设置环境变量 RUN_MODE=simple
  • 默认每次启动创建缺失的默认分组;设置 SIMPLE_MODE_AUTO_CREATE_DEFAULT_GROUPS=false(或 YAML simple_mode.auto_create_default_groups: false)可关闭。关闭不删除已有分组,也不改变运行时自动绑定或管理员并发配置。
  • 功能差异:隐藏 SaaS 相关功能,跳过计费流程
  • 安全注意事项:生产环境需同时设置 SIMPLE_MODE_CONFIRM=true 才允许启动
  • 可选密钥窗口:设置 SIMPLE_MODE_KEY_RATE_LIMIT_ENABLED=true 后,按每个 API Key 配置的 5 小时、1 天、7 天消费窗口进行限制,默认关闭;启用后仍跳过余额和订阅扣费。
  • 窗口限制以数据库为准,在请求完成后记账;并发请求可能超过窗口上限,历史用量不会自动补算。

Antigravity 使用说明

Sub2API 支持 Antigravity 账户,授权后可通过专用端点访问 Claude 和 Gemini 模型。

专用端点

端点 模型
/antigravity/v1/messages Claude 模型
/antigravity/v1beta/ Gemini 模型

Claude Code 配置示例

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

混合调度模式

Antigravity 账户支持可选的混合调度功能。开启后,通用端点 /v1/messages/v1beta/ 也会调度该账户。

⚠️ 注意:Anthropic Claude 和 Antigravity Claude 不能在同一上下文中混合使用,请通过分组功能做好隔离。


项目结构

sub2api/
├── backend/                  # Go 后端服务
│   ├── cmd/server/           # 应用入口
│   ├── internal/             # 内部模块
│   │   ├── config/           # 配置管理
│   │   ├── model/            # 数据模型
│   │   ├── service/          # 业务逻辑
│   │   ├── handler/          # HTTP 处理器
│   │   └── gateway/          # API 网关核心
│   └── resources/            # 静态资源
│
├── frontend/                 # Vue 3 前端
│   └── src/
│       ├── api/              # API 调用
│       ├── stores/           # 状态管理
│       ├── views/            # 页面组件
│       └── components/       # 通用组件
│
└── deploy/                   # 部署文件
    ├── docker-compose.yml    # Docker Compose 配置
    ├── .env.example          # Docker Compose 环境变量
    ├── config.example.yaml   # 二进制部署完整配置文件
    └── install.sh            # 一键安装脚本

⚠️ 重要提醒

使用本项目前,请务必仔细阅读以下内容:

  • 🚨 服务条款风险:使用本项目可能违反 Anthropic 等上游服务商的服务条款。请在使用前仔细阅读相关服务商的用户协议,由此产生的一切风险由用户自行承担。
  • ⚖️ 合规使用:请在符合您所在国家或地区法律法规的前提下使用本项目,严禁将其用于任何违法违规用途。
  • 📖 免责声明:本项目仅供技术学习与研究使用,作者不对因使用本项目导致的账户封禁、服务中断、数据丢失或其他任何直接或间接损失承担责任。
  • 🚫 无商业授权:本项目从未授权任何个人或组织基于本项目开展任何形式的商业化运营。任何以本项目名义或基于本项目从事的商业行为均与本项目及其开发者无关,由此产生的一切纠纷、损失和法律责任由行为主体自行承担。

许可证

本项目基于 GNU 宽通用公共许可证 v3.0(或更高版本)授权。

Copyright (c) 2026 Wesley Liddick


如果觉得有用,请给个 Star 支持一下!

About

基于 Sub2API 由多位站长持续维护的独立分支,更加适合中转站长使用,按需同步上游更新,扩展实用功能并发布生产版本。

Resources

Stars

165 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages