281 lines
19 KiB
Markdown
281 lines
19 KiB
Markdown
|
# Sub2API 模块分析汇总报告
|
|||
|
|
|
|||
|
|
## 一、项目概述
|
|||
|
|
|
|||
|
|
Sub2API是一个AI API网关平台，用于分发和管理AI产品订阅的API配额。用户通过平台生成的API Key访问上游AI服务（Claude、OpenAI、Gemini等），平台负责认证、计费、负载均衡和请求转发。
|
|||
|
|
|
|||
|
|
## 二、模块架构总览
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 前端 (Vue 3 + TypeScript) │
|
|||
|
|
├─────────────────────────────────────────────────────────────────┤
|
|||
|
|
│ API Gateway 核心模块 │
|
|||
|
|
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ │
|
|||
|
|
│ │ 路由分发 │ │ 账号选择 │ │ 请求转发 │ │ 故障转移 │ │
|
|||
|
|
│ └─────────┘ └─────────┘ └──────────┘ └──────────┘ │
|
|||
|
|
├─────────────────────────────────────────────────────────────────┤
|
|||
|
|
│ 认证与授权模块 │
|
|||
|
|
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ │
|
|||
|
|
│ │ JWT认证 │ │API Key │ │OAuth登录 │ │ TOTP │ │
|
|||
|
|
│ └─────────┘ └─────────┘ └──────────┘ └──────────┘ │
|
|||
|
|
├─────────────────────────────────────────────────────────────────┤
|
|||
|
|
│ 用户与API Key管理模块 │
|
|||
|
|
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ │
|
|||
|
|
│ │ 用户管理 │ │ API Key │ │ 分组管理 │ │
|
|||
|
|
│ └─────────┘ └─────────┘ └──────────┘ │
|
|||
|
|
├─────────────────────────────────────────────────────────────────┤
|
|||
|
|
│ 账户管理模块 │
|
|||
|
|
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ │
|
|||
|
|
│ │ 账号CRUD│ │ 账号测试│ │ 状态管理 │ │ 分组管理 │ │
|
|||
|
|
│ └─────────┘ └─────────┘ └──────────┘ └──────────┘ │
|
|||
|
|
├─────────────────────────────────────────────────────────────────┤
|
|||
|
|
│ 计费与配额模块 │
|
|||
|
|
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ │
|
|||
|
|
│ │ 用量记录│ │ 计费计算│ │ 速率限制 │ │ 余额管理 │ │
|
|||
|
|
│ └─────────┘ └─────────┘ └──────────┘ └──────────┘ │
|
|||
|
|
├─────────────────────────────────────────────────────────────────┤
|
|||
|
|
│ 调度与负载均衡模块 │
|
|||
|
|
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ │
|
|||
|
|
│ │ 负载感知│ │ 故障转移│ │ 粘性会话 │ │
|
|||
|
|
│ └─────────┘ └─────────┘ └──────────┘ │
|
|||
|
|
├─────────────────────────────────────────────────────────────────┤
|
|||
|
|
│ 用量统计与日志模块 │
|
|||
|
|
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ │
|
|||
|
|
│ │ 用量记录│ │ 数据分析│ │ 数据导出 │ │
|
|||
|
|
│ └─────────┘ └─────────┘ └──────────┘ │
|
|||
|
|
├─────────────────────────────────────────────────────────────────┤
|
|||
|
|
│ 订阅与兑换码模块 │
|
|||
|
|
│ ┌─────────┐ ┌─────────┐ │
|
|||
|
|
│ │ 订阅管理│ │ 兑换码 │ │
|
|||
|
|
│ └─────────┘ └─────────┘ │
|
|||
|
|
├─────────────────────────────────────────────────────────────────┤
|
|||
|
|
│ 运营与监控模块 │
|
|||
|
|
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ │
|
|||
|
|
│ │ 系统监控│ │ 告警管理│ │ 运维日志 │ │ 备份恢复 │ │
|
|||
|
|
│ └─────────┘ └─────────┘ └──────────┘ └──────────┘ │
|
|||
|
|
├─────────────────────────────────────────────────────────────────┤
|
|||
|
|
│ Sora与媒体模块 │
|
|||
|
|
│ ┌─────────┐ ┌─────────┐ │
|
|||
|
|
│ │ 视频生成│ │ 媒体存储│ │
|
|||
|
|
│ └─────────┘ └─────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 三、模块依赖关系
|
|||
|
|
|
|||
|
|
### 3.1 详细依赖图
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 请求入口 │
|
|||
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|||
|
|
│ │ /v1/messages│ │/v1/chat/ │ │ /v1beta/ │ │ /sora/ │ │
|
|||
|
|
│ │ (Claude) │ │completions │ │ generateContent│ │ v1/creative│ │
|
|||
|
|
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
|
|||
|
|
└──────────┼────────────────┼────────────────┼────────────────┼───────────────┘
|
|||
|
|
│ │ │ │
|
|||
|
|
▼ ▼ ▼ ▼
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 认证中间件层 │
|
|||
|
|
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
|||
|
|
│ │ api_key_auth.go │ │
|
|||
|
|
│ │ APIKeyService ──► BillingCacheService ──► SubscriptionService │ │
|
|||
|
|
│ │ (Key验证) (余额检查) (订阅验证) │ │
|
|||
|
|
│ └─────────────────────────────────────────────────────────────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 网关核心层 (gateway_service.go) │
|
|||
|
|
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
|||
|
|
│ │ GatewayService │ │
|
|||
|
|
│ │ │ │
|
|||
|
|
│ │ SelectAccountWithLoadAwareness() ──► ConcurrencyService │ │
|
|||
|
|
│ │ (负载感知选择) (并发槽位控制) │ │
|
|||
|
|
│ │ │ │ │
|
|||
|
|
│ │ ▼ │ │
|
|||
|
|
│ │ RecordUsage() ──► BillingService ──► BillingCacheService │ │
|
|||
|
|
│ │ (用量记录) (计费) (缓存) │ │
|
|||
|
|
│ └─────────────────────────────────────────────────────────────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 下游服务层 │
|
|||
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|||
|
|
│ │BillingService│ │Concurrency │ │Identity │ │RateLimit │ │
|
|||
|
|
│ │ │ │Service │ │Service │ │Service │ │
|
|||
|
|
│ └──────┬───────┘ └──────┬───────┘ └──────────────┘ └──────┬───────┘ │
|
|||
|
|
│ │ │ │ │
|
|||
|
|
│ ▼ ▼ ▼ │
|
|||
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|||
|
|
│ │UserRepo │ │AccountRepo │ │Redis Cache │ │HTTPUpstream │ │
|
|||
|
|
│ │(余额/费率) │ │(账号选择) │ │(实时数据) │ │(上游调用) │ │
|
|||
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.2 模块依赖矩阵
|
|||
|
|
|
|||
|
|
| 模块 | 被依赖 | 依赖 | 共享数据 |
|
|||
|
|
|------|--------|------|----------|
|
|||
|
|
| **认证模块** | Gateway | UserRepo | User, APIKey |
|
|||
|
|
| **账户模块** | Gateway, Billing | AccountRepo, GroupRepo | Account, Group |
|
|||
|
|
| **计费模块** | Gateway | BillingService, UserRepo | Balance, Usage |
|
|||
|
|
| **用户模块** | Auth, Gateway | UserRepo, APIKeyRepo | User, APIKey |
|
|||
|
|
| **订阅模块** | APIKey Auth | SubscriptionRepo | Subscription |
|
|||
|
|
| **网关模块** | Handler | 所有服务 | Request Context |
|
|||
|
|
|
|||
|
|
### 3.3 高风险修改影响
|
|||
|
|
|
|||
|
|
| 修改内容 | 影响模块 | 风险 |
|
|||
|
|
|---------|---------|------|
|
|||
|
|
| `APIKeyService.ValidateKey()` | 所有 API | 🔴 认证失效 |
|
|||
|
|
| `BillingService.CalculateCost()` | 所有请求 | 🔴 计费错误 |
|
|||
|
|
| `SelectAccountWithLoadAwareness()` | 所有请求 | 🔴 负载不均 |
|
|||
|
|
| `BillingCacheService.CheckBalance()` | Gateway | 🟡 误拒绝请求 |
|
|||
|
|
| `ConcurrencyService` | Gateway | 🟡 并发失控 |
|
|||
|
|
|
|||
|
|
## 四、核心数据流
|
|||
|
|
|
|||
|
|
### 4.1 请求处理流程
|
|||
|
|
|
|||
|
|
1. **请求入口**：用户通过API Key发起请求
|
|||
|
|
2. **认证验证**：验证API Key有效性、权限、配额
|
|||
|
|
3. **账号选择**：根据负载和策略选择上游账号
|
|||
|
|
4. **请求转发**：将请求转发到上游AI服务
|
|||
|
|
5. **响应处理**：接收响应，记录用量，计算费用
|
|||
|
|
6. **结果返回**：将响应返回给用户
|
|||
|
|
|
|||
|
|
### 4.2 数据持久化
|
|||
|
|
|
|||
|
|
- **PostgreSQL**：用户、账号、API Key、订阅、用量日志
|
|||
|
|
- **Redis**：缓存、实时统计、会话、限流计数
|
|||
|
|
|
|||
|
|
## 五、安全架构
|
|||
|
|
|
|||
|
|
### 5.1 认证层
|
|||
|
|
|
|||
|
|
- JWT Token：用户会话认证
|
|||
|
|
- API Key：程序化访问认证
|
|||
|
|
- OAuth：第三方登录（Anthropic、Google、OpenAI、Linux.do）
|
|||
|
|
- TOTP：双因素认证
|
|||
|
|
|
|||
|
|
### 5.2 授权层
|
|||
|
|
|
|||
|
|
- 分组隔离：用户/账号分组
|
|||
|
|
- 权限控制：角色（用户/管理员/超级管理员）
|
|||
|
|
- IP白名单：API Key级别IP限制
|
|||
|
|
|
|||
|
|
### 5.3 审计层
|
|||
|
|
|
|||
|
|
- 登录日志
|
|||
|
|
- 操作日志
|
|||
|
|
- 用量日志
|
|||
|
|
|
|||
|
|
## 六、配置管理
|
|||
|
|
|
|||
|
|
### 6.1 主要配置项
|
|||
|
|
|
|||
|
|
| 配置类别 | 配置项 |
|
|||
|
|
|----------|--------|
|
|||
|
|
| 服务 | 端口、模式、信任代理 |
|
|||
|
|
| 数据库 | PostgreSQL连接 |
|
|||
|
|
| 缓存 | Redis连接 |
|
|||
|
|
| 安全 | JWT密钥、TOTP密钥、CORS、URL白名单 |
|
|||
|
|
| 网关 | 重试策略、超时、粘性会话 |
|
|||
|
|
| 计费 | 模型定价、缓存策略 |
|
|||
|
|
| 限流 | 用户/API Key/IP限流规则 |
|
|||
|
|
|
|||
|
|
## 七、修改与扩展指南
|
|||
|
|
|
|||
|
|
### 7.1 常见修改场景
|
|||
|
|
|
|||
|
|
1. **添加新上游支持**
|
|||
|
|
- 添加账号类型常量
|
|||
|
|
- 实现请求转换器
|
|||
|
|
- 注册路由
|
|||
|
|
|
|||
|
|
2. **调整计费规则**
|
|||
|
|
- 修改定价配置
|
|||
|
|
- 调整限流参数
|
|||
|
|
|
|||
|
|
3. **自定义工作流**
|
|||
|
|
- 添加中间件
|
|||
|
|
- 实现Hook
|
|||
|
|
|
|||
|
|
### 7.2 注意事项
|
|||
|
|
|
|||
|
|
1. 线程安全：注意并发访问
|
|||
|
|
2. 事务一致性：关键操作使用事务
|
|||
|
|
3. 配置验证：修改配置需要测试
|
|||
|
|
|
|||
|
|
## 八、安全审计发现
|
|||
|
|
|
|||
|
|
### 8.1 已验证的安全措施
|
|||
|
|
|
|||
|
|
- JWT使用HS256/384/512（无none算法漏洞）
|
|||
|
|
- 密码bcrypt哈希存储
|
|||
|
|
- Ent ORM防止SQL注入
|
|||
|
|
- 多级限流防护
|
|||
|
|
- URL白名单保护
|
|||
|
|
|
|||
|
|
### 8.2 需要注意的问题
|
|||
|
|
|
|||
|
|
1. **跨实例使用风险**：激活码和API Key未包含系统标识
|
|||
|
|
- 建议：在Key生成时嵌入实例ID
|
|||
|
|
|
|||
|
|
2. **配置安全**：生产环境需启用所有安全选项
|
|||
|
|
- URL白名单
|
|||
|
|
- HTTPS强制
|
|||
|
|
- 强JWT密钥
|
|||
|
|
|
|||
|
|
## 九、模块文档索引
|
|||
|
|
|
|||
|
|
| 模块 | 文档 |
|
|||
|
|
|------|------|
|
|||
|
|
| API Gateway | `MODULE_01_API_GATEWAY.md` |
|
|||
|
|
| 认证与授权 | `MODULE_02_AUTH.md` |
|
|||
|
|
| 账户管理 | `MODULE_03_ACCOUNT.md` |
|
|||
|
|
| 用户与API Key | `MODULE_04_USER_APIKEY.md` |
|
|||
|
|
| 计费与配额 | `MODULE_05_BILLING.md` |
|
|||
|
|
| 调度与负载均衡 | `MODULE_06_SCHEDULING.md` |
|
|||
|
|
| 用量统计 | `MODULE_07_USAGE.md` |
|
|||
|
|
| 订阅与兑换码 | `MODULE_08_SUBSCRIPTION.md` |
|
|||
|
|
| 运营与监控 | `MODULE_09_OPS.md` |
|
|||
|
|
| Sora与媒体 | `MODULE_10_SORA.md` |
|
|||
|
|
| 前端架构 | `MODULE_11_FRONTEND.md` |
|
|||
|
|
|
|||
|
|
## 十、部署与问题排查
|
|||
|
|
|
|||
|
|
| 文档 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| `WINDOWS_DEPLOYMENT_TROUBLESHOOTING.md` | Windows 本地部署问题排查指南 |
|
|||
|
|
| `MODIFICATION_GUIDE.md` | 代码修改准备指南 |
|
|||
|
|
| `SECURITY_ISSUE_CROSS_INSTANCE.md` | 跨实例安全漏洞分析 |
|
|||
|
|
| `ADMIN_TEST_REPORT.md` | 管理后台测试报告（Playwright E2E） |
|
|||
|
|
| `FULL_TEST_REPORT.md` | 全面测试报告（Go + Vitest + Playwright） |
|
|||
|
|
| `tests/` | 独立测试体系目录（E2E + 集成测试 + 工具脚本） |
|
|||
|
|
|
|||
|
|
## 十一、审查与更新记录
|
|||
|
|
|
|||
|
|
| 日期 | 版本 | 更新内容 |
|
|||
|
|
|------|------|----------|
|
|||
|
|
| 2025-01 | 1.0 | 初始版本 |
|
|||
|
|
| 2026-03-23 | 1.1 | 审查修正：MODULE_01/05/06 文件路径、算法描述、配额检查流程 |
|
|||
|
|
| 2026-03-24 | 1.2 | 添加 Windows 部署问题排查文档 |
|
|||
|
|
| 2026-03-24 | 1.3 | 添加管理后台测试报告（23/23 Playwright E2E 测试通过） |
|
|||
|
|
| 2026-03-24 | 1.4 | 添加全面测试报告（Go 200+测试 / Vitest 301测试 / 通过率 98.5%） |
|
|||
|
|
| 2026-03-24 | 1.5 | 修复前端测试失败用例，建立独立测试体系目录 |
|
|||
|
|
|
|||
|
|
> 📋 **审查报告**：`REVIEW_AND_DEPENDENCIES.md` - 包含详细的模块交叉依赖分析和修改影响评估
|
|||
|
|
> 📋 **测试报告**：
|
|||
|
|
> - `ADMIN_TEST_REPORT.md` - Playwright E2E 自动化测试结果
|
|||
|
|
> - `FULL_TEST_REPORT.md` - 全栈测试结果汇总
|
|||
|
|
> 📋 **测试体系**：`tests/` - 完整的测试框架和工具脚本
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
*文档版本：1.4*
|
|||
|
|
*最后更新：2026-03-24*
|
|||
|
|
*分析基于：Sub2API v0.1.104*继续
|