当前正式版:
v2.8.8提供原生 780 采票、分组模型限制和账号质量检测更新。780 采票默认关闭,票长与模型声明不代表能力保证;详见发布说明。
欢迎正在部署、使用或维护 Sub2API 的朋友加入 QQ 群「中转技术交流」(群号 1004036018),交流部署实践、协议兼容、出口代理和功能改进。也欢迎参与问题复现、测试、文档补充和 Pull Request,一起维护这个独立分支。
加入 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 反向代理 Sub2API(或 CRS 服务)并搭配 Codex CLI 使用时,需要在 Nginx 配置的 http 块中添加:
underscores_in_headers on;Nginx 默认会丢弃名称中含下划线的请求头(如 session_id),这会导致多账号环境下的粘性会话功能失效。
管理员后台的 系统设置 -> 网关服务 -> OpenAI Fast/Flex 策略 只负责处理请求体中的 service_tier,不会修改 Codex 客户端的模型目录,也不会让 Codex UI 自动出现 Speed 或 /fast 选项。
策略支持以下处理方式:
pass:保留客户端传入的service_tier;fast会规范为上游使用的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脚本会自动:
- 检测系统架构
- 下载最新版本
- 安装二进制文件到
/opt/sub2api - 创建 systemd 服务
- 配置系统用户和权限
# 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 部署,包含 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-compose.local.yml(脚本部署)以便更轻松地管理数据。
如需启用管理后台“数据管理”,需要额外部署宿主机数据管理进程 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 芯片 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.0config.yaml 还支持以下安全相关配置:
cors.allowed_origins配置 CORS 白名单security.url_allowlist配置上游/价格数据/CRS 主机白名单security.url_allowlist.enabled可关闭 URL 校验(慎用)security.url_allowlist.allow_insecure_http关闭校验时允许 HTTP URLsecurity.url_allowlist.allow_private_hosts允许私有/本地 IP 地址security.response_headers.enabled可启用可配置响应头过滤(关闭时使用默认白名单)security.csp配置 Content-Security-Policybilling.circuit_breaker计费异常时 fail-closedsecurity.trust_forwarded_ip_for_api_key_acl控制旧版原始转发头接管(为升级兼容默认开启);关闭后严格使用server.trusted_proxies,其中只应填写直接连接 Sub2API 的精确代理 CIDRsecurity.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 作为第一层防护,服务端限流与响应读取上限作为第二层兜底;两层同时保留,避免旁路流量与误配置风险。
当 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.yaml,setup 向导在首次启动时会被跳过:服务检测到 config 已存在,会直接进入正常模式,此时 users 表为空,首次登录会返回 invalid email or password。
创建管理员的两种方式:
-
推荐——让向导自动生成
config.yaml: 跳过上面的第 5 步(不要执行cp)。直接运行./sub2api,访问http://localhost:8080,向导会引导你完成数据库、Redis 和管理员账号配置,并自动写出config.yaml。 -
如果你已经创建了
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后端明文端口默认支持 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支持 gpt-image-2.5-flare、gpt-image-2.5-sunburst 及其 2026-09-08 日期快照,可通过 /v1/images/generations、/v1/images/edits 调用。quality 支持 xhigh、max、auto,合法自定义尺寸和图片 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(或 YAMLsimple_mode.auto_create_default_groups: false)可关闭。关闭不删除已有分组,也不改变运行时自动绑定或管理员并发配置。 - 功能差异:隐藏 SaaS 相关功能,跳过计费流程
- 安全注意事项:生产环境需同时设置
SIMPLE_MODE_CONFIRM=true才允许启动 - 可选密钥窗口:设置
SIMPLE_MODE_KEY_RATE_LIMIT_ENABLED=true后,按每个 API Key 配置的 5 小时、1 天、7 天消费窗口进行限制,默认关闭;启用后仍跳过余额和订阅扣费。 - 窗口限制以数据库为准,在请求完成后记账;并发请求可能超过窗口上限,历史用量不会自动补算。
Sub2API 支持 Antigravity 账户,授权后可通过专用端点访问 Claude 和 Gemini 模型。
| 端点 | 模型 |
|---|---|
/antigravity/v1/messages |
Claude 模型 |
/antigravity/v1beta/ |
Gemini 模型 |
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 支持一下!

