Sub2API

项目概述

Sub2API 是一个面向 AI 订阅额度分发与管理的 API 网关平台。用户通过平台生成的 API Key 调用上游 AI 服务，平台负责统一的鉴权、计费、负载均衡与请求转发。

核心特性

• 多账户管理：支持 OAuth、API Key 等多种上游账户类型
• API Key 分发：为用户生成与管理独立的访问密钥
• 精准计费：基于 Token 级别用量追踪与费用核算
• 智能调度：支持粘性会话的账户选择策略
• 并发控制：按用户与按账户两级并发上限
• 速率限制：可配置的请求速率与 Token 速率限制
• 内置支付：集成易付、支付宝、微信支付、Stripe，支持用户自助充值，无需额外部署支付服务
• 管理后台：提供 Web 界面进行监控与运维
• 复合分组：管理员可在路由层将请求模型解析到具体 Provider，实现多 Provider 分组
• 外部系统集成：通过 iframe 嵌入工单等外部系统，扩展管理后台能力

技术架构

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

Nginx 反向代理注意事项

在使用 Nginx 为 Sub2API 做反向代理时，需在 http 块中添加以下配置：

underscores_in_headers on;
# Nginx 默认会丢弃包含下划线的请求头（如 session_id），
# 这会导致多账户场景下的粘性会话路由失效。

部署方式

方式一：一键脚本安装

适用于已部署 PostgreSQL 15+ 与 Redis 7+ 的 Linux 服务器（amd64/arm64），需要 root 权限。

# 下载并执行安装脚本（自动检测架构、下载 Release、注册 systemd 服务）
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash

# 启动服务并设置开机自启
sudo systemctl start sub2api
sudo systemctl enable sub2api

安装完成后访问 http://YOUR_SERVER_IP:8080，通过初始化向导完成数据库、Redis 与管理员账户的配置。

常用运维命令：

sudo systemctl status sub2api       # 查看服务状态
sudo journalctl -u sub2api -f       # 实时查看日志
sudo systemctl restart sub2api      # 重启服务

升级可通过管理后台左上角的「检查更新」按钮完成，支持一键升级与回滚。

方式二：Docker Compose（推荐）

需要 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
# 查看日志
docker compose logs -f sub2api

脚本会自动生成 JWT_SECRET、TOTP_ENCRYPTION_KEY、POSTGRES_PASSWORD 等安全凭据，并写入 .env 文件。

手动部署时，关键环境变量示例：

POSTGRES_PASSWORD=your_secure_password    # 必填
JWT_SECRET=your_jwt_secret                # 推荐，重启后保持登录态
TOTP_ENCRYPTION_KEY=your_totp_key         # 推荐，保留 2FA 配置
ADMIN_EMAIL=admin@example.com             # 可选
ADMIN_PASSWORD=your_admin_password        # 可选
SERVER_PORT=8080                          # 可选

可通过 openssl rand -hex 32 生成各类密钥。推荐使用 docker-compose.local.yml，数据持久化到本地目录，便于通过 tar 整体迁移。

方式三：Apple 容器（macOS）

在装有 macOS 26 及 Apple container 1.1.0+ 的 Apple Silicon Mac 上可运行完整栈：

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

该方式为本地运维流程，生产环境仍推荐 Docker Compose。

方式四：源码编译

需要 Go 1.21+、Node.js 18+、pnpm。流程为克隆仓库 → 安装 pnpm → 构建前端（输出至 backend/internal/web/dist/）→ 构建后端并嵌入前端资源。