Wei-Shaw/sub2api

# Sub2API ## 演示 在线试用 Sub2API：**https://demo.sub2api.org/** 演示凭据（共享演示环境；**非**自托管安装自动创建）： | 邮箱 | 密码 | |-------|----------| | admin@sub2api.com | admin123 | ## 概述 Sub2API 是一个 AI API 网关平台，旨在分发和管理来自 AI 产品订阅（如 Claude Code $200/月）的 API 配额。用户可以通过平台生成的 API Keys 访问上游 AI 服务，平台负责处理身份验证、计费、负载均衡和请求转发。 ## 功能特性 - **多账户管理** - 支持多种上游账户类型（OAuth、API Key） - **API Key 分发** - 为用户生成和管理 API Keys - **精确计费** - Token 级别的使用追踪和成本计算 - **智能调度** - 结合粘性会话的智能账户选择 - **并发控制** - 针对每个用户和每个账户的并发限制 - **速率限制** - 可配置的请求和 Token 速率限制 - **管理仪表盘** - 用于监控和管理的 Web 界面 ## 技术栈 | 组件 | 技术 | |-----------|------------| | 后端 | Go 1.25.7, Gin, Ent | | 前端 | Vue 3.4+, Vite 5+, TailwindCSS | | 数据库 | PostgreSQL 15+ | | 缓存/队列 | Redis 7+ | ## 文档 - 依赖安全性：`docs/dependency-security.md` - 管理员支付集成 API：`docs/ADMIN_PAYMENT_INTEGRATION_API.md` ## 部署 ### 方式 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://YOUR_SERVER_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 -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. 克隆 repository 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 Secret (推荐 - 在重启后保持用户登录状态) JWT_SECRET=your_jwt_secret_here # TOTP Encryption Key (推荐 - 在重启后保留 2FA) 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：Named volumes 版本（设置简单） 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://YOUR_SERVER_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/ ``` ### 方式 3：从源码构建 从源代码构建并运行，用于开发或自定义。 #### 前置条件 - Go 1.21+ - Node.js 18+ - PostgreSQL 15+ - Redis 7+ #### 构建步骤 ``` # 1. 克隆 repository 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. 构建嵌入了前端的 backend cd ../backend go build -tags embed -o sub2api ./cmd/server # 5. 创建配置文件 cp ../deploy/config.example.yaml ./config.yaml # 6. 编辑配置 nano config.yaml ``` **`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 ``` ### Sora 状态（暂时不可用） `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` 用于在计费错误时熔断 - `server.trusted_proxies` 用于启用 X-Forwarded-For 解析 - `turnstile.required` 用于在生产模式下要求 Turnstile **⚠️ 安全警告：HTTP URL 配置** 当 `security.url_allowlist.enabled=false` 时，系统默认执行最小 URL 验证，**拒绝 HTTP URL** 并仅允许 HTTPS。要允许 HTTP URL（例如用于开发或内部测试），您必须显式设置： ``` security: url_allowlist: enabled: false # Disable allowlist checks allow_insecure_http: true # Allow HTTP URLs (⚠️ INSECURE) ``` **或通过环境变量：** ``` SECURITY_URL_ALLOWLIST_ENABLED=false SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=true ``` **允许 HTTP 的风险：** - API keys 和数据以**明文**传输（易受拦截攻击） - 容易受到**中间人 (MITM) 攻击** - **不适用于生产**环境 **何时使用 HTTP：** - ✅ 使用本地服务器进行开发/测试 (http://localhost) - ✅ 具有可信端点的内部网络 - ✅ 在获取 HTTPS 之前测试账户连通性 - ❌ 生产环境（仅使用 HTTPS） **未设置此项时的错误示例：** ``` Invalid base URL: invalid url scheme: http ``` 如果您禁用 URL 验证或响应头过滤，请加强您的网络层： - 对上游域名/IP 实施出站白名单 - 阻止私有/环回/链路本地地址范围 - 强制仅 TLS 出站流量 - 在代理处剥离敏感的上游响应头 ``` # 6. 运行应用程序 ./sub2api ``` #### 开发模式 ``` # Backend (带热重载) cd backend go run ./cmd/server # Frontend (带热重载) 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](https://antigravity.so/) 账户。授权后，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/` 也会将请求路由到 Antigravity 账户。 ### 已知问题 在 Claude Code 中，Plan Mode 无法自动退出。（通常使用原生 Claude API 时，规划完成后，Claude Code 会弹出选项供用户批准或拒绝计划。） **解决方法**：按 `Shift + Tab` 手动退出 Plan Mode，然后输入您的回复以批准或拒绝计划。 ## 项目结构 ``` sub2api/ ├── backend/ # Go backend service │ ├── cmd/server/ # Application entry │ ├── internal/ # Internal modules │ │ ├── config/ # Configuration │ │ ├── model/ # Data models │ │ ├── service/ # Business logic │ │ ├── handler/ # HTTP handlers │ │ └── gateway/ # API gateway core │ └── resources/ # Static resources │ ├── frontend/ # Vue 3 frontend │ └── src/ │ ├── api/ # API calls │ ├── stores/ # State management │ ├── views/ # Page components │ └── components/ # Reusable components │ └── deploy/ # Deployment files ├── docker-compose.yml # Docker Compose configuration ├── .env.example # Environment variables for Docker Compose ├── config.example.yaml # Full config file for binary deployment └── install.sh # One-click installation script ``` ## 许可证 MIT License

标签：AI API 网关, API 代理, API 分发, Claude API, DNS解析, Docker, EVTX分析, EVTX分析, Gemini API, Go 语言, OpenAI API, PE 加载器, PostgreSQL, Redis, SaaS 工具, Vue.js, 中转服务, 令牌配额, 多账户管理, 安全防御评估, 并发控制, 开源项目, 拼车服务, 搜索引擎查询, 效率工具, 日志审计, 流量中转, 测试用例, 计费系统, 订阅管理, 请求拦截, 请求转发, 负载均衡, 账号共享