tokens-reef/deploy/docs-backup/SUMMARY.md

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继续