sub2api/README_CN.md

Sub2API

AI API 网关平台 - 订阅配额分发管理

English | 中文

---

在线体验

体验地址：https://v2.pincc.ai/

演示账号（共享演示环境；自建部署不会自动创建该账号）：

邮箱	密码
admin@sub2api.com	admin123

项目概述

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

核心功能

• 多账号管理 - 支持多种上游账号类型（OAuth、API Key）
• API Key 分发 - 为用户生成和管理 API Key
• 精确计费 - Token 级别的用量追踪和成本计算
• 智能调度 - 智能账号选择，支持粘性会话
• 并发控制 - 用户级和账号级并发限制
• 速率限制 - 可配置的请求和 Token 速率限制
• 管理后台 - Web 界面进行监控和管理

技术栈

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

---

文档

• 依赖安全：docs/dependency-security.md

---

OpenAI Responses 兼容注意事项

• 当请求包含 function_call_output 时，需要携带 previous_response_id，或在 input 中包含带 call_id 的 tool_call/function_call，或带非空 id 且与 function_call_output.call_id 匹配的 item_reference。
• 若依赖上游历史记录，网关会强制 store=true 并需要复用 previous_response_id，以避免出现 “No tool call found for function call output” 错误。

---

部署方式

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

一键安装脚本，自动从 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 配置
• 管理员账号创建

升级

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

网页升级功能支持：

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

常用命令

# 查看状态
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

---

方式二：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 -f docker-compose.local.yml up -d

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

脚本功能：

• 下载 docker-compose.local.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

# 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（脚本部署）以便更轻松地管理数据。

访问

在浏览器中打开 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/

---

方式三：源码编译

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

前置条件

• 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
go build -tags embed -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
• server.trusted_proxies 启用可信代理解析 X-Forwarded-For
• turnstile.required 在 release 模式强制启用 Turnstile

⚠️ 安全警告：HTTP URL 配置

当 security.url_allowlist.enabled=false 时，系统默认执行最小 URL 校验，拒绝 HTTP URL，仅允许 HTTPS。要允许 HTTP URL（例如用于开发或内网测试），必须显式设置：

security:
  url_allowlist:
    enabled: false                # 禁用白名单检查
    allow_insecure_http: true     # 允许 HTTP URL（⚠️ 不安全）

或通过环境变量：

SECURITY_URL_ALLOWLIST_ENABLED=false
SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=true

允许 HTTP 的风险：

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

适用场景：

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

未设置此项时的错误示例：

Invalid base URL: invalid url scheme: http

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

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

# 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
• 功能差异：隐藏 SaaS 相关功能，跳过计费流程
• 安全注意事项：生产环境需同时设置 SIMPLE_MODE_CONFIRM=true 才允许启动

---

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 不能在同一上下文中混合使用，请通过分组功能做好隔离。

已知问题

在 Claude Code 中，无法自动退出Plan Mode。（正常使用原生Claude Api时，Plan 完成后，Claude Code会弹出弹出选项让用户同意或拒绝Plan。） 解决办法：shift + Tab，手动退出Plan mode，然后输入内容 告诉 Claude Code 同意或拒绝 Plan

项目结构

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            # 一键安装脚本

许可证

MIT License

---

如果觉得有用，请给个 Star 支持一下！