ghcr.io/wei-shaw/sub2api:0.2.7

Sub2API

面向订阅配额分发的 AI API 网关平台

English | 中文 | 日本語

⚠️ 重要须知

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

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

❤️ 赞助商

想要在此处展示？

感谢 CCTK.AI 对本项目的赞助！CCTK.AI 是一款专注于稳定性与性价比的 AI API 网关，为 Claude、OpenAI、Gemini 等主流模型提供高速中转服务。它可与 Claude Code、Codex 等主流编码工具无缝适配，以远低于官方的成本提供同等的模型能力。通过此链接注册即可获得更快、更稳定、更实惠的 AI API 访问体验。

一个 API 接口，覆盖所有主流模型！OpenModel 是生产级高可用 AI API 网关，可让您的应用真正实现高速稳定运行：内置自动故障转移、智能路由选择性能最优通道，提供生产级 SLA 保障。其 SLA 标准远超任何单一服务商，让稳定性成为您的核心竞争优势，可直接对接 Claude Code、Codex 与 Gemini CLI。通过此链接注册即可开始使用。

感谢 ETok.ai 对本项目的赞助！ETok.ai 致力于打造一站式 AI 编程工具服务平台，提供专业级 Claude Code 套餐与技术社区服务，同时支持 Google Gemini 与 OpenAI Codex。通过精心设计的方案与专业技术社区，为开发者提供可靠的服务保障与持续技术支持，让 AI 辅助编程真正成为生产力工具。点击此处即可注册！

感谢 APIKEY.FUN 对本项目的赞助！APIKEY.FUN 是 sub2api 开源项目的核心贡献者之一，致力于提供开放、稳定、高性价比的 AI API 访问服务。平台支持 Claude、OpenAI、Gemini 等主流模型的 API 中转服务，资费最低仅为官方原价的 7%。通过专属链接注册：APIKEY，所有充值订单最高可享 5% 折扣。

感谢 AIGoCode 对本项目的赞助！AIGoCode 是一款集成了 Claude Code、Codex 与最新 Gemini 模型的一站式平台，为您提供稳定、高效且极具性价比的 AI 编程服务。平台提供灵活的订阅方案，无账号封禁风险，无需 *** 即可直接访问，响应速度极快。AIGoCode 为 sub2api 用户准备了专属福利：通过此链接注册，首次充值将额外获得 10% 的赠金。

以 OpenAI 3% 的价格使用真正的 GPT-5.6 系列产品——CodexEverywhere 正在为全球开发者普及前沿模型的访问权限。我们秉持透明诚信的运营理念，模型质量经过社区数月的持续监督验证，支持***与加密货币支付。立即前往 codex-everywhere.com 即可获得价值 20 ***的免费试用额度。

非常感谢 BmoPlus 对本项目的赞助！BmoPlus 是专为重度 AI 用户与开发者打造的高可靠性 AI 账号服务商，提供稳定即用的 *** Plus / *** Pro（全保）/ Claude Pro / Super Grok / Gemini Pro 账号与官方充值服务。通过 BmoPlus - Premium AI Accounts & Top-ups 注册下单，用户可享官方 GPT 订阅价一折的超高优惠。

感谢 Bestproxy 对本项目的赞助！Bestproxy 提供高纯度住宅 IP，支持一号一专用 IP 配置。通过真实家庭网络与指纹隔离技术，实现链接环境隔离，降低被关联风控的概率。

感谢 PatewayAI 对本项目的赞助！PatewayAI 是面向重度 AI 开发者打造的高端 API 中转服务，提供 100% 源自官方渠道的全系列 Claude 与 Codex 模型，采用透明的 Token 级计费模式。企业套餐支持高并发、专属管理、合同与发票服务。现在注册即可获得 3 ***试用赠金，充值低至四折，推荐奖励最高可达 150 ***。

感谢 PPToken.cc 对本项目的赞助！PPToken.cc 专注于 GPT 模型 API 中转服务，支持 Codex、Claude Code、OpenAI 兼容客户端与 Gemini CLI 集成。充值比例为 1:1（1 元***可兑换 1 额度），GPT 模型倍率低至 0.16，总成本约为官方定价的 2.2%，首 Token 延迟约 1 秒，是追求低成本、高速度访问 GPT 模型能力开发者的理想选择。技术支持：提供 7×24 小时真人响应服务（无机器人），在群聊中 @tech 即可在 10 分钟内获得回复。赞助福利：通过专属注册链接注册并输入优惠码 SUB2API 的前 200 名用户，可领取免费的 Codex / Claude Code 试用额度，无最低消费要求，无需绑定。

感谢 Veilx 对本项目的赞助！Veilx CDN 专为大规模 AI API 流量场景设计，针对 OpenAI、Claude、Gemini 的中转服务与调用链路，以及对话、图像生成、向量嵌入、流式输出等场景进行深度优化，在高并发场景下可实现更低延迟与更高稳定性。同时提供中国境内三大运营商的优化回源线路，是全球 AI 中转平台、海外 AI SaaS 项目与跨境高并发部署场景的理想选择。

感谢 RoxyBrowser 对本项目的赞助！RoxyBrowser 是 Sub2API 的完美搭档：内置原生 Roxy AI Agent 与高品质原生住宅 IP，支持通过简易命令实现批量自动化操作，可大幅提升多账号管理的安全性与效率！点击此链接注册即可领取免费住宅 IP 套餐，同时享受终身 10% 折扣优惠。

感谢 Proxy4Free 对本项目的赞助！Proxy4Free 是面向开发者与 AI 应用的数据代理服务提供商，为网页抓取、浏览器自动化、AI Agent 等场景提供住宅代理、静态住宅代理、ISP 代理与数据中心代理服务。依托全球 IP 资源、稳定连接与灵活切换能力，它可帮助开发者提升数据采集成功率，降低 IP 封禁风险。点击该链接注册即可开始使用，轻松搭建更稳定高效的自动化工作流。

感谢 Aimzoon 对本项目的赞助！Aimzoon 提供稳定高性价比的 AI API 接入服务，让开发者可以快速将主流 AI 服务接入 Codex、Claude Code、Gemini CLI 等编码工具。无需复杂配置，接入流程更快捷、调用更稳定、使用成本更低。平台当前正在进行促销活动，包含 Codex 折扣费率与专属定价，注册即送免费试用额度，助你将 AI 编码融入日常工作流。点击此处注册试用！

Nagora 是面向开发者与团队打造的多模型 AI API 网关。你只需使用一个账号与 API Key，即可通过统一接口访问 26 款主流文本与图像模型。它兼容 OpenAI、Anthropic、Gemini 协议，可与 Claude Code、Codex、Gemini CLI 等开发工具无缝集成。该平台提供智能路由、自动故障转移、透明定价与统一账单功能，同时支持预算管理、限流与并发控制，让个人开发、团队协作与生产环境下的 AI 使用更可靠、更易管控。你无需修改现有应用，仅需替换 Base URL 与 API Key，最快 1 分钟即可完成集成。

感谢七牛 AI 对本项目的赞助！七牛 AI 是七牛云（02567.HK）旗下的企业级大模型 MaaS 平台，提供一站式接入全球 150+ 主流模型的服务，兼容全球主流模型厂商协议，覆盖文本、图像、音频、视频、文件处理等全模态能力，已服务超 169 万家企业与开发者。七牛 AI 为 Sub2API 用户提供专属福利：通过该链接注册，企业用户可获得 1200 万免费 token，个人开发者可获得 300 万免费 token。

感谢 FennoAI 对本项目的赞助！FennoAI 是面向企业研发团队与开发者的高稳定性、高性能 API 中转服务商，兼容 OpenAI 与 Anthropic 协议，可与 Codex、Claude Code、OpenCode 等主流 AI 编码工具无缝集成。平台具备企业级稳定性，支持每日百亿级 token 调用量，同时支持境内外主体的对公结算与开票，满足企业研发与采购需求。Sub2API 用户专属福利：通过专属链接购买订阅服务，仅需 1.99 ***即可获得价值 50 ***的编码计划额度。平台还设有推荐奖励机制：邀请好友购买最高可获得 20% 佣金，多邀多得。

感谢 LanoX AI 对本项目的赞助！LanoX AI 为开发者、团队与企业提供稳定高性价比的全球模型接入服务。🎁 新用户福利——领取数百万免费 token，外加 500+ 款免费模型，轻松实现低成本测试、验证与部署 🧠 全球主流模型——涵盖 GPT、Claude、Gemini、通义千问、Grok 等 🎬 多模态创作——支持 Seedance 2.0、GPT Image、Gemini Nano Banana 🛡️ 企业级可靠性——高可用 💎 原生能力输出 💎 无智能降质 💎 无模型混合 💎 用量与账单全透明 💎 💰 更低 API 使用成本——顶级模型最低仅为官方定价的 10%，文档清晰、集成简单、支持开票，可满足企业级大规模使用需求 🏢 企业首选——非常适合高模型调用量的 AI 产品、Agent、内容平台与研发团队使用

RapidProxy 是面向开发者打造的数据采集代理解决方案，提供稳定可靠的住宅代理服务。平台拥有 9000 万+ 全球住宅 IP，覆盖 200+ 国家与地区，支持智能轮换与精准地理定位，能够帮助网页抓取、AI 数据训练、SEO 监控、电商数据分析等场景下的项目突破访问限制，提升数据采集效率。它兼容 Playwright、Selenium、Puppeteer 等主流自动化框架，资费低至 0.65 ***/GB，立即开启免费测试。

hao.ai 是面向开发者与团队的高速稳定统一大模型 API 网关。你仅需一个 API Key 与统一接口，即可访问 GPT、Claude、xAI Grok 等主流模型，兼容 OpenAI、Anthropic 等通用协议与 SDK。平台提供模型路由、故障转移、团队管理与完整请求日志能力，模型资费最低仅为官方参考定价的 15%，帮助用户更简单、可靠、低成本地搭建 AI 应用。

Swiftproxy 是面向开发者打造的高性能代理解决方案，提供稳定可靠的住宅代理与静态住宅代理服务。平台拥有 9000 万+ 纯净住宅 IP，覆盖全球，支持灵活轮换与精准地理定位，能够帮助网页抓取、AI 自动化、浏览器自动化、SEO 监控、多账号管理等项目突破访问限制，提升工作流效率。它支持 HTTP(S) 与 SOCKS5 协议，可与 Playwright、Selenium、Puppeteer 等热门自动化工具集成，动态代理流量用不完永不失效，还提供免费测试额度，立即开启免费测试！

DuckIP — 覆盖 195+ 国家和地区的 9000 万+ 全球住宅网络资源，提供轮换与会话保持能力，适用于公开数据采集、RAG 更新、模型评估与多区域数据工作负载场景。🟢 住宅代理 — 限时 8 折；🟢 静态住宅代理 — 每 IP 低至 50.00 元起；🟢 不限量住宅代理 — 每小时低至 19.8 元起。✅ 领取 500M 免费测试额度。

感谢 APIMart 对本项目的赞助！APIMart 是面向 AI 图像与视频生成的低成本 API 平台——GPT-Image-2 单张图像资费低至 0.006 ***，1 ***可生成 160+ 张图像。仅需一个异步 API 即可同时覆盖图像与视频生成场景：提交任务获取 ID，通过轮询或回调方式拉取结果，可批量处理数万张图像而无超时风险，切换模型无需修改代码。按量付费，无月度最低消费，点击此处注册即可开始使用。

感谢 AxisNow 对本项目的赞助！AxisNow 可为网站与 API 提供安全防护与加速能力，在中国大陆及全球范围内带来最优访问体验，同时还可通过客户端 SDK 将加速与安全能力拓展至原生/移动应用场景，提供自托管私有部署 CDN、支持 DDoS 防护的付费 CDN 服务，以及自主可控、灵活组合的 CDN 网络。

PP.dog 是一款源码级 API 网关，内置海量账号池，专为下游中转站点和高频开发者打造作为上游中继服务，帮你免去自行搭建、维护账号池的繁琐工作：✅ 直连源头：自营账号池，无中间商加价；🧧 成本极低：综合倍率低至 0.03x，仅为官方定价的 0.35%；🚀 极速响应：首包延迟极低。立即开始使用 PP.dog

ColaProxy 提供专为网页爬虫、自动化操作与多账号管理场景打造的高品质住宅代理服务。可领取永久不过期的免费试用流量，资费低至 0.3 ***/GB，支持无限制并发连接，搭配智能 IP 轮换机制，带来更流畅稳定的代理体验。使用优惠码 COLA10 可享受 9 折优惠，即刻通过可靠的住宅代理服务推进项目规模化落地。立即开始使用 ColaProxy

概述

Sub2API 是一款 AI API 网关平台，用于分发与管理来自各类 AI 产品订阅的 API 配额。用户可使用平台生成的 API Key 访问上游 AI 服务，而认证、计费、负载均衡与请求转发均由平台统一处理。

功能特性

• 多账号管理 - 支持 OAuth、API Key 等多种上游账号类型
• API Key 分发 - 为用户生成并管理 API Key
• 精准计费 - 基于 Token 粒度的使用量追踪与成本计算
• 智能调度 - 支持会话黏滞的智能账号选择机制
• 并发控制 - 可配置单用户与单账号的并发上限
• 速率限制 - 支持对请求数与 Token 量配置速率限制规则
• 内置支付系统 - 支持易支付、***、***与 Stripe，用户可自助充值，无需额外部署独立支付服务（详见配置指南）
• 管理后台面板 - 提供用于监控与管理操作的 Web 界面
• 复合分组 - 管理员专属路由层，可为多供应商分组将请求的模型解析至具体的服务供应商（详见操作指南）
• 外部系统集成 - 可通过 iframe 嵌入外部系统（如工单系统）扩展管理后台的功能

生态

以下为可扩展或接入 Sub2API 的社区项目：

技术栈

---

Nginx 反向代理注意事项

当使用 Nginx 为 Sub2API（或 CRS）做反向代理并对接 Codex CLI 时，请在 Nginx 配置的 http 块中添加以下配置项：

underscores_in_headers on;

[!NOTE] Nginx 默认会丢弃名称含下划线的请求头（例如 session_id），这会破坏多账号部署场景下的黏滞会话路由功能。

---

部署

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

一键安装脚本，自动从 GitHub Releases 下载预构建二进制包完成部署。

前置要求

• Linux 服务器（架构为 amd64 或 arm64）
• PostgreSQL 15+（已安装并处于运行状态）
• Redis 7+（已安装并处于运行状态）
• Root 权限

安装步骤

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/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 配置
• 管理员账号创建

升级操作

你可以直接在管理后台面板点击左上角的检查更新按钮完成升级。

Web 界面将自动执行以下操作：

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

常用命令

# 查看服务状态
sudo systemctl status sub2api

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

# 重启服务
sudo systemctl restart sub2api

# 卸载服务
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+

快速开始（一键部署）

使用自动化部署脚本可快速完成配置：

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

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

# 启动所有服务
docker compose up -d

# 查看 sub2api 服务日志
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 https://github.com/Wei-Shaw/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@example.com 这类易被猜测的值，它们会成为暴力破解的攻击目标
ADMIN_EMAIL=
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 部署（脚本默认使用该配置），以获得更便捷的数据管理体验。

访问服务

在浏览器中打开 http://YOUR_SERVER_IP:8080 即可访问服务。

如果管理员***（登录用户名）或密码是自动生成的，可以通过以下命令从日志中获取：

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

升级服务

# 拉取最新镜像并重建容器
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/

---

方法 3：Apple 容器（macOS）

搭载 Apple 芯片、运行 macOS 26 的设备，可使用 1.1.0 或更高版本的 Apple container 运行完整的 Sub2API、PostgreSQL 和 Redis 技术栈：

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 仍然是推荐的生产部署方案。关于生命周期管理命令、数据持久化、升级操作和运行限制的详细信息，请参考 deploy/APPLE_CONTAINER.md。

---

方法 4：从源码构建

可基于源码构建并运行服务，适用于开发或自定义修改场景。

前置依赖

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

构建步骤

# 1. 克隆代码仓库
git clone https://github.com/Wei-Shaw/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

[!NOTE] -tags embed 参数的作用是将前端资源嵌入到后端二进制文件中。如果不添加该参数，生成的二进制文件将无法提供前端 UI 服务。

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：在 URL 校验关闭时允许使用 HTTP 地址
• security.url_allowlist.allow_private_hosts：允许使用私有/本地 IP 地址
• security.response_headers.enabled：启用可自定义的响应头过滤功能（禁用时使用默认白名单）
• security.csp：配置 Content-Security-Policy 响应头
• billing.circuit_breaker：开启计费故障时的熔断保护，执行失败降级策略
• security.trust_forwarded_ip_for_api_key_acl：启用旧版直接解析转发头获取客户端 IP 的逻辑（为兼容旧版本升级默认开启）；建议关闭该选项，转而配置 server.trusted_proxies，其中仅需填写直接连接 Sub2API 的代理节点的精确 CIDR 网段
• security.forwarded_client_ip_headers：可配置最多 16 个第三方 CDN 自定义客户端 IP 头名称，仅在旧版转发解析逻辑开启时，这些头会在内置默认头之前按顺序被优先检测
• turnstile.required：在生产模式下强制启用 Cloudflare 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。

[!WARNING] URL 配置安全提示

当 security.url_allowlist.enabled=false 时，系统会执行最低程度的 URL 校验，默认允许 HTTP 地址（该模式为开发友好模式，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 的适用场景：

• ✅ 与本地服务器（http://localhost）配合的开发/测试场景
• 拥有可信端点的内部网络
• 获取 HTTPS 证书之前的账号连通性测试
• ❌ 生产环境（仅允许使用 HTTPS）

当设置 allow_insecure_http: false 时，HTTP URL 可能触发的示例错误：

Invalid base URL: invalid url scheme: http

如果禁用了 URL 验证或响应头过滤，请强化网络层防护：

• 添加上游域名/IP 的出口访问白名单
• 拦截私有/环回/链路本地地址段
• 强制所有出站流量仅使用 TLS
• 在代理层剥离上游响应中的敏感头

OpenAI 响应式 WebSocket 入站限制

gateway.openai_ws 用于约束面向客户端的 Responses WebSocket 会话的生命周期与总数量。这些防护机制独立于每轮用户与账号并发槽位（会话轮次间隙会释放这类槽位）运行。

gateway:
  openai_ws:
    # 接收并解压第一条客户端消息的总时长
    client_first_message_timeout_seconds: 30
    # 关闭轮次完成后处于空闲状态的客户端套接字；设置为 0 将禁用该防护
    ingress_inter_turn_idle_timeout_seconds: 300
    # 面向活跃客户端入站会话的分布式 API 密钥限制；设置为 0 将禁用该限制
    max_ingress_connections_per_api_key: 64

第一条消息超时是全局读取截止时间。如果部署场景需要在低带宽链路上传输大上下文或包含大量图片的请求，可以将该值上调至 120-300 秒。该超时会在 HTTP 桥接路由阶段之前触发，因此桥接模式不会覆盖该限制。

连接上限通过 Redis 协同实现，使用有效期 60 秒的租约，每 20 秒自动刷新一次。如果某个进程在完整租约周期内都无法确认持有租约，它将关闭本地 WebSocket 连接，避免超出全局连接上限。

在选择 http_bridge 这类账号级 WebSocket 模式之前，需要先启用 v2 模式路由器：

gateway:
  openai_ws:
    mode_router_v2_enabled: true

也可以在环境变量中设置 GATEWAY_OPENAI_WS_MODE_ROUTER_V2_ENABLED=true。当进行灰度发布或需要缓解上游 WebSocket 相关问题时，可使用 http_bridge 实现「客户端使用 WebSocket、上游使用 HTTP」的运行模式。

强制 OpenAI 上游使用 HTTP/SSE

当出口代理或网络环境频繁导致 OpenAI Responses WebSocket 连接断开时，可以在持久化部署配置中设置全局回退规则：

gateway:
  openai_ws:
    force_http: true

对于 Compose 与 Apple 容器部署场景，等效的 .env 配置项为：

GATEWAY_OPENAI_WS_FORCE_HTTP=true

该配置会让原本使用 WebSocket 的 OpenAI 上游 Responses 流量改用 HTTP/SSE 传输。它不会改变面向客户端的协议，也不会强制使用 HTTP/1.1；如果代理与 HTTP/2 不兼容，请单独配置 gateway.openai_http2.enabled（或设置 GATEWAY_OPENAI_HTTP2_ENABLED=false）。与账号级 http_bridge 模式不同，该全局回退规则无需启用 mode_router_v2_enabled 即可生效。请将该配置保存在部署的持久化 .env 或 config.yaml 文件中，而非运行中的容器内部，这样在镜像更新或容器重建后配置仍能被正确读取。

[!IMPORTANT] 创建管理员账号 初始管理员账号仅能通过首次运行时在 http://<ip>:8080 提供的配置向导创建。config.yaml 中的 default.admin_email / default.admin_password 字段不会被用于创建管理员账号，这些字段仅因历史原因保留在模板中。

由于前文第 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 # 向导将在 http://localhost:8080 运行并生成全新的 config.yaml
# 向导完成后按下 Ctrl+C 停止服务器，再恢复原有配置：
mv config.yaml.bak config.yaml
./sub2api # 以正常模式重启，使用刚创建的管理员账号登录即可

# 6. 运行应用
./sub2api

开发模式

# 后端（支持热重载）
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

---

简易模式

简易模式面向个人开发者或不需要完整 SaaS 功能的内部团队，提供快速上手的使用体验。

• 启用方式：设置环境变量 RUN_MODE=simple
• 默认分组会在每次启动时自动初始化。如果希望自行管理分组，可设置 SIMPLE_MODE_AUTO_CREATE_DEFAULT_GROUPS=false（或在 YAML 中配置 simple_mode.auto_create_default_groups: false）。默认值为 true；禁用该配置不会删除已有分组，也不会改变运行时自动绑定规则或管理员并发配置。
• 特性差异：隐藏所有 SaaS 相关功能，跳过计费流程
• 可选密钥窗口：设置 SIMPLE_MODE_KEY_RATE_LIMIT_ENABLED=true 可对每个 API 密钥强制执行配置好的 5 小时、每日、7 天消费窗口限制。默认值为 false；即使启用该限制，余额与订阅扣款流程仍会被绕过。
• 窗口限制机制以数据库作为唯一可信数据源，仅记录各 API 密钥的窗口使用量。该限制为请求后的软上限，并发飞行中的请求最终产生的费用可能会小幅超出上限。简易模式的历史使用数据不会被回溯补全。
• 安全说明：在生产环境中，还必须设置 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 兼容的 Responses 流量转发至 xAI 服务。

支持范围

镜像名称：ghcr.io/wei-shaw/sub2api 参考标签：latest

• 平台名称：grok
• 账户类型：OAuth 订阅账户与 xAI API 密钥账户
• 公开 Responses 目标端点：/v1/responses、/responses 与 /backend-api/codex/responses，OAuth 账户的请求会被转发至 Grok 订阅代理，API 密钥账户的请求则转发至 https://api.x.ai/v1/responses
• 公开 Claude 兼容目标端点：/v1/messages，请求会被转换为 xAI Responses 格式，最终以 Anthropic Messages 输出格式返回，适配 Claude CLI 风格客户端
• 公开聊天补全目标端点：/v1/chat/completions 与 /chat/completions，请求会根据账户类型转发至对应的 xAI 上游服务
• 支持 Codex CLI 风格的 Responses WebSocket 入口，可在 Responses 目标端点接收请求并桥接至 xAI HTTP/SSE Responses 上游
• 文本模型：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 对象中传入图像引用。xAI 兼容载荷请使用 url 字段；同时保留对旧版 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 的 OAuth 账户会在运行时自动重定向至订阅代理，显式自定义上游地址的账户不受影响。

对于 API 密钥账户，在创建账户对话框中选择 Grok → API Key 即可。官方默认基础 URL 为 https://api.x.ai/v1；凭证信息使用现有账户的 base_url 与 api_key 字段存储。OAuth 账户仍沿用上述订阅流程。

Grok Build CLI 配置

1. 在 Sub2API 管理面板中，添加一个 grok OAuth 账户并完成 xAI 授权，或是直接添加 Grok API 密钥账户。
2. 创建 Grok 群组，将账户关联至该群组，随后新建一个分配至该群组的 Sub2API API 密钥。
3. 在用户 API 密钥页面点击 使用密钥 并选择 Grok CLI。弹出窗口会自动生成适配 macOS/Linux 或 Windows 的正确配置文件与基础 URL，同时可在 OpenCode 标签页获取 OpenCode 配置。
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

[!NOTE] 上述 base_url 应为以 /v1 结尾的公开 Sub2API URL，请勿填写 api.x.ai 或内部 xAI OAuth 代理地址。

用量与配额展示

xAI 配额信息为被动获取模式。Sub2API 不会自行生成订阅配额数值，仅会在 xAI 响应成功或触发限流时，从上游响应中记录已放行的 xAI 限流头部。在收到第一条可用上游响应前，面板会将配额显示为未知，但仍会展示本地 Sub2API 的用量统计数据。

当返回 401 响应时，系统会临时将凭证无效的账户从调度队列中移除。403 响应会被判定为访问或权限校验失败，不会触发令牌刷新循环。429 响应会使用 Retry-After 头部或短冷却时间将对应账户临时移出调度队列。

新的 Grok 图像与视频生成请求会执行媒体专属的可用性校验：API 密钥账户默认保持可用；明确标记为免费或存在计费异常的 OAuth 账户会被排除出媒体生成队列。缺失或格式错误的计费观测结果会在请求下发前完成探测：为保证向后兼容，成功返回但计费信息不完整的响应会被标记为 billing_inconclusive，对应账户仍保持可用状态——未知的计费规则不能作为账户不具备媒体权限的依据。运维人员可通过设置 extra.grok_media_eligible=false 将已知异常账户隔离，也可设置为 true 强制启用已验证账户的媒体权限。导入账户时系统会主动执行计费优先的配额探测。聊天请求与视频状态查询不受该媒体专属隔离机制影响。若没有可用的媒体账户，媒体端点将返回 HTTP 503，错误类型为 grok_media_no_eligible_account。