442 lines
12 KiB
Markdown
442 lines
12 KiB
Markdown
# sub2api-merge 项目差异文档
|
|
|
|
> 本文档记录 sub2api-merge 项目相对于官方 sub2api 仓库的所有自定义修改和新增功能。
|
|
> 用于每周合并官方库时参考，确保自定义功能不被覆盖。
|
|
|
|
## 仓库信息
|
|
|
|
| 仓库 | URL |
|
|
|------|-----|
|
|
| 官方仓库 (origin) | https://github.com/Wei-Shaw/sub2api.git |
|
|
| 目标仓库 (tksea) | https://www.tksea.top/pham/tokens-reef.git |
|
|
|
|
---
|
|
|
|
## 一、后端新增功能
|
|
|
|
### 1.1 Prometheus 指标包 (新增)
|
|
|
|
**路径**: `backend/internal/prommetrics/`
|
|
|
|
独立于 routes 包的 Prometheus 指标注册和更新模块，避免循环依赖。
|
|
|
|
| 文件 | 说明 |
|
|
|------|------|
|
|
| `metrics.go` | 指标定义和注册，包含 DB/Redis 连接数、QPS/TPS、健康评分等 |
|
|
| `metrics_test.go` | 单元测试 |
|
|
|
|
**暴露的指标**:
|
|
- `sub2api_http_requests_total` - HTTP 请求总数
|
|
- `sub2api_http_request_duration_seconds` - HTTP 请求延迟
|
|
- `sub2api_db_connections_active/idle` - 数据库连接数
|
|
- `sub2api_redis_connections_total/idle` - Redis 连接数
|
|
- `sub2api_accounts_active_total` - 活跃账户数
|
|
- `sub2api_ops_health_score` - 系统健康评分
|
|
- `sub2api_error_rate` / `sub2api_success_rate` - 错误/成功率
|
|
- `sub2api_qps` / `sub2api_tps` - QPS/TPS
|
|
|
|
**使用方式**:
|
|
```go
|
|
import "github.com/Wei-Shaw/sub2api/internal/prommetrics"
|
|
|
|
prommetrics.SetDBConnections(active, idle)
|
|
prommetrics.SetRedisConnections(total, idle)
|
|
prommetrics.SetQPS(100.0)
|
|
```
|
|
|
|
---
|
|
|
|
### 1.2 运维监控服务 (新增)
|
|
|
|
**路径**: `backend/internal/service/ops_*.go`
|
|
|
|
完整的运维监控模块，包含错误日志、仪表盘、告警等功能。
|
|
|
|
| 文件 | 说明 |
|
|
|------|------|
|
|
| `ops_service.go` | 核心服务，提供数据摄入和查询 API |
|
|
| `ops_settings.go` | 邮件/Webhook 通知配置管理 |
|
|
| `ops_metrics_collector.go` | 指标收集器，定时更新 Prometheus 指标 |
|
|
| `ops_alert_evaluator_service.go` | 告警规则评估服务 |
|
|
| `ops_aggregation_service.go` | 数据聚合服务 |
|
|
| `ops_cleanup_service.go` | 数据清理服务 |
|
|
| `ops_realtime.go` | 实时数据推送 (WebSocket) |
|
|
| `ops_scheduled_report_service.go` | 定时报告服务 |
|
|
|
|
**关键功能**:
|
|
- 错误日志记录与查询
|
|
- 请求重试 (客户端/上游模式)
|
|
- 告警规则配置与评估
|
|
- 邮件/Webhook 通知
|
|
- 实时仪表盘数据
|
|
|
|
---
|
|
|
|
### 1.3 Webhook 告警通知服务 (新增)
|
|
|
|
**路径**: `backend/internal/service/webhook_service.go`
|
|
|
|
支持通过 Webhook 发送告警通知。
|
|
|
|
**功能**:
|
|
- 发送告警事件到配置的 Webhook URL
|
|
- 支持 HMAC-SHA256 签名验证
|
|
- 告警恢复通知
|
|
|
|
---
|
|
|
|
### 1.4 Sora 视频生成服务 (新增)
|
|
|
|
**路径**: `backend/internal/service/sora_*.go`
|
|
|
|
完整的 Sora 视频生成服务模块。
|
|
|
|
| 文件 | 说明 |
|
|
|------|------|
|
|
| `sora_gateway_service.go` | Sora API 网关服务 |
|
|
| `sora_generation_service.go` | 视频生成服务 |
|
|
| `sora_quota_service.go` | 用户配额管理 |
|
|
| `sora_account_service.go` | 账户服务 |
|
|
| `sora_s3_storage.go` | S3 存储集成 |
|
|
| `sora_media_storage.go` | 媒体存储抽象 |
|
|
| `sora_media_cleanup_service.go` | 媒体文件清理 |
|
|
| `sora_models.go` | 数据模型定义 |
|
|
| `sora_client.go` | Sora API 客户端 |
|
|
| `sora_sdk_client.go` | SDK 客户端 |
|
|
|
|
---
|
|
|
|
### 1.5 管理员 API Handler (新增)
|
|
|
|
**路径**: `backend/internal/handler/admin/`
|
|
|
|
| 文件 | 说明 |
|
|
|------|------|
|
|
| `sora_handler.go` | Sora 管理接口：系统统计、用户统计、生成记录 |
|
|
| `ops_handler.go` | 运维监控入口 |
|
|
| `ops_dashboard_handler.go` | 仪表盘数据 |
|
|
| `ops_alerts_handler.go` | 告警管理 |
|
|
| `ops_realtime_handler.go` | 实时数据 |
|
|
| `ops_ws_handler.go` | WebSocket 连接 |
|
|
| `ops_system_log_handler.go` | 系统日志 |
|
|
| `data_management_handler.go` | 数据管理配置 |
|
|
|
|
---
|
|
|
|
### 1.6 运维监控数据仓库 (新增)
|
|
|
|
**路径**: `backend/internal/repository/ops_repo*.go`
|
|
|
|
| 文件 | 说明 |
|
|
|------|------|
|
|
| `ops_repo.go` | 基础仓库 |
|
|
| `ops_repo_dashboard.go` | 仪表盘数据查询 |
|
|
| `ops_repo_alerts.go` | 告警数据 |
|
|
| `ops_repo_preagg.go` | 预聚合数据 |
|
|
| `ops_repo_trends.go` | 趋势数据 |
|
|
| `ops_repo_metrics.go` | 指标数据 |
|
|
| `ops_repo_realtime_traffic.go` | 实时流量 |
|
|
| `ops_repo_request_details.go` | 请求详情 |
|
|
| `ops_repo_openai_token_stats.go` | OpenAI Token 统计 |
|
|
|
|
---
|
|
|
|
### 1.7 健康检查增强 (修改)
|
|
|
|
**路径**: `backend/internal/server/routes/common.go`
|
|
|
|
**修改内容**:
|
|
- `/health` 端点增加数据库和 Redis 健康检查
|
|
- `/ready` 端点增加就绪检查
|
|
- `/live` 端点增加存活检查
|
|
- `/metrics` 端点暴露 Prometheus 指标
|
|
|
|
**新增接口**:
|
|
```
|
|
GET /health -> 检查 DB/Redis 状态，返回组件健康信息
|
|
GET /ready -> 检查服务是否就绪
|
|
GET /live -> 检查服务是否存活
|
|
GET /metrics -> Prometheus 指标端点
|
|
```
|
|
|
|
---
|
|
|
|
## 二、前端新增功能
|
|
|
|
### 2.1 运维监控仪表盘 (新增)
|
|
|
|
**路径**: `frontend/src/views/admin/ops/`
|
|
|
|
完整的运维监控前端页面。
|
|
|
|
| 文件 | 说明 |
|
|
|------|------|
|
|
| `OpsDashboard.vue` | 主页面 |
|
|
| `types.ts` | 类型定义 |
|
|
| `components/OpsDashboardHeader.vue` | 头部 |
|
|
| `components/OpsConcurrencyCard.vue` | 并发卡片 |
|
|
| `components/OpsLatencyChart.vue` | 延迟图表 |
|
|
| `components/OpsThroughputTrendChart.vue` | 吞吐量趋势 |
|
|
| `components/OpsErrorTrendChart.vue` | 错误趋势 |
|
|
| `components/OpsErrorDistributionChart.vue` | 错误分布 |
|
|
| `components/OpsErrorLogTable.vue` | 错误日志表 |
|
|
| `components/OpsErrorDetailModal.vue` | 错误详情弹窗 |
|
|
| `components/OpsRequestDetailsModal.vue` | 请求详情弹窗 |
|
|
| `components/OpsAlertEventsCard.vue` | 告警事件 |
|
|
| `components/OpsAlertRulesCard.vue` | 告警规则 |
|
|
| `components/OpsEmailNotificationCard.vue` | 邮件通知配置 |
|
|
| `components/OpsWebhookNotificationCard.vue` | Webhook 通知配置 |
|
|
| `components/OpsSettingsDialog.vue` | 设置对话框 |
|
|
| `components/OpsOpenAITokenStatsCard.vue` | OpenAI Token 统计 |
|
|
| `utils/opsFormatters.ts` | 格式化工具 |
|
|
| `utils/errorDetailResponse.ts` | 错误响应解析 |
|
|
|
|
---
|
|
|
|
### 2.2 Sora 管理页面 (新增)
|
|
|
|
**路径**: `frontend/src/views/admin/SoraAdminView.vue`
|
|
|
|
Sora 视频生成服务的管理后台。
|
|
|
|
**功能**:
|
|
- 概览标签页：系统统计、按状态/模型分布
|
|
- 用户统计标签页：用户配额、使用量、生成数
|
|
- 生成记录标签页：历史记录、状态筛选
|
|
|
|
**测试文件**: `frontend/src/views/admin/__tests__/SoraAdminView.spec.ts`
|
|
|
|
---
|
|
|
|
### 2.3 数据管理配置页面 (新增)
|
|
|
|
**路径**: `frontend/src/views/admin/data-management/`
|
|
|
|
数据管理配置前端页面。
|
|
|
|
| 文件 | 说明 |
|
|
|------|------|
|
|
| `DataManagementView.vue` | 主页面 |
|
|
| `components/PostgresProfilesCard.vue` | PostgreSQL 配置 |
|
|
| `components/RedisProfilesCard.vue` | Redis 配置 |
|
|
| `components/S3ProfilesCard.vue` | S3 配置 |
|
|
| `components/BackupJobsCard.vue` | 备份任务配置 |
|
|
|
|
---
|
|
|
|
### 2.4 管理 API 客户端 (新增)
|
|
|
|
**路径**: `frontend/src/api/admin/`
|
|
|
|
| 文件 | 说明 |
|
|
|------|------|
|
|
| `ops.ts` | 运维监控 API |
|
|
| `sora.ts` | Sora 管理 API |
|
|
| `dataManagement.ts` | 数据管理 API |
|
|
|
|
---
|
|
|
|
## 三、路由配置
|
|
|
|
### 3.1 后端路由 (修改)
|
|
|
|
**路径**: `backend/internal/server/routes/admin.go`
|
|
|
|
新增路由:
|
|
```go
|
|
// Sora 管理
|
|
soraGroup := admin.Group("/sora")
|
|
soraGroup.GET("/stats", soraHandler.GetSystemStats)
|
|
soraGroup.GET("/users", soraHandler.ListUserStats)
|
|
soraGroup.GET("/generations", soraHandler.ListGenerations)
|
|
soraGroup.DELETE("/users/:id/storage", soraHandler.ClearUserStorage)
|
|
|
|
// 运维监控
|
|
opsGroup := admin.Group("/ops")
|
|
// ... 多个运维监控路由
|
|
```
|
|
|
|
### 3.2 前端路由 (修改)
|
|
|
|
**路径**: `frontend/src/router/index.ts`
|
|
|
|
新增路由:
|
|
```typescript
|
|
{ path: '/admin/ops', component: OpsDashboard }
|
|
{ path: '/admin/sora', component: SoraAdminView }
|
|
{ path: '/admin/data-management', component: DataManagementView }
|
|
```
|
|
|
|
---
|
|
|
|
## 四、国际化支持
|
|
|
|
### 4.1 中文翻译 (修改)
|
|
|
|
**路径**: `frontend/src/i18n/locales/zh.ts`
|
|
|
|
新增翻译键:
|
|
- `admin.sora.*` - Sora 管理页面
|
|
- `admin.ops.*` - 运维监控页面
|
|
- `admin.dataManagement.*` - 数据管理页面
|
|
|
|
### 4.2 英文翻译 (修改)
|
|
|
|
**路径**: `frontend/src/i18n/locales/en.ts`
|
|
|
|
对应英文翻译。
|
|
|
|
---
|
|
|
|
## 五、测试覆盖
|
|
|
|
### 5.1 后端测试
|
|
|
|
| 文件 | 说明 |
|
|
|------|------|
|
|
| `prommetrics/metrics_test.go` | Prometheus 指标测试 |
|
|
| `routes/common_test.go` | 健康检查端点测试 |
|
|
| `service/webhook_service_test.go` | Webhook 服务测试 |
|
|
| `handler/admin/sora_handler_test.go` | Sora Handler 测试 |
|
|
|
|
### 5.2 前端测试
|
|
|
|
| 文件 | 说明 |
|
|
|------|------|
|
|
| `SoraAdminView.spec.ts` | Sora 管理页面测试 |
|
|
| `OpsSettingsDialog.spec.ts` | 运维设置对话框测试 |
|
|
| `OpsOpenAITokenStatsCard.spec.ts` | Token 统计卡片测试 |
|
|
|
|
---
|
|
|
|
## 六、合并注意事项
|
|
|
|
### 6.1 冲突风险文件
|
|
|
|
以下文件在合并时需要特别注意，可能需要手动解决冲突:
|
|
|
|
1. **后端**:
|
|
- `backend/internal/server/routes/admin.go` - 路由注册
|
|
- `backend/internal/server/routes/common.go` - 健康检查
|
|
- `backend/internal/service/wire.go` - 依赖注入
|
|
|
|
2. **前端**:
|
|
- `frontend/src/router/index.ts` - 路由配置
|
|
- `frontend/src/i18n/locales/zh.ts` - 中文翻译
|
|
- `frontend/src/i18n/locales/en.ts` - 英文翻译
|
|
|
|
### 6.2 合并流程建议
|
|
|
|
1. **拉取官方最新代码**:
|
|
```bash
|
|
git fetch origin
|
|
git merge origin/main
|
|
```
|
|
|
|
2. **检查冲突文件**:
|
|
- 优先检查上述冲突风险文件
|
|
- 确保自定义路由不被覆盖
|
|
- 确保翻译键不被删除
|
|
|
|
3. **运行测试**:
|
|
```bash
|
|
# 后端
|
|
cd backend && make test
|
|
|
|
# 前端
|
|
cd frontend && npm test
|
|
```
|
|
|
|
4. **验证功能**:
|
|
- 访问 `/admin/ops` 验证运维监控
|
|
- 访问 `/admin/sora` 验证 Sora 管理
|
|
- 访问 `/admin/data-management` 验证数据管理
|
|
- 访问 `/metrics` 验证 Prometheus 指标
|
|
|
|
---
|
|
|
|
## 七、版本历史
|
|
|
|
| 日期 | 版本 | 说明 |
|
|
|------|------|------|
|
|
| 2026-04-16 | v1.0 | 初始文档，记录所有自定义功能 |
|
|
|
|
---
|
|
|
|
## 八、代码审查验证结果
|
|
|
|
> 基于 2026-04-16 全面代码审查报告的验证
|
|
|
|
### 8.1 阻塞级问题验证
|
|
|
|
| 编号 | 问题 | 验证结果 | 说明 |
|
|
|------|------|----------|------|
|
|
| 🔴 #1 | CREATE DATABASE SQL 注入 | ⚠️ 已确认 | 已有前置校验 `validateDBName()`，但可加强防御深度 |
|
|
| 🔴 #2 | ORDER BY 动态 SQL 注入 | ✅ 误报 | 已使用白名单校验，代码安全 |
|
|
|
|
**详细说明**:
|
|
|
|
- **#1 CREATE DATABASE**: 代码已有注释说明依赖前置校验，但建议使用引号包裹加强防御：
|
|
```go
|
|
// 当前代码 (setup.go:204)
|
|
_, err := db.ExecContext(ctx, fmt.Sprintf("CREATE DATABASE %s", cfg.DBName))
|
|
|
|
// 建议改进
|
|
quotedName := fmt.Sprintf(`"%s"`, cfg.DBName)
|
|
_, err := db.ExecContext(ctx, fmt.Sprintf("CREATE DATABASE %s", quotedName))
|
|
```
|
|
|
|
- **#2 ORDER BY 注入**: 经验证，`channelListOrderBy()` 和 `usageLogOrderBy()` 均使用白名单模式：
|
|
```go
|
|
// channel_repo.go:249-269 - 白名单校验
|
|
switch sortBy {
|
|
case "id": column = "c.id"
|
|
case "name": column = "c.name"
|
|
case "status": column = "c.status"
|
|
case "created_at": column = "c.created_at"
|
|
default: column = "c.id" // 安全回退
|
|
}
|
|
```
|
|
|
|
### 8.2 建议级改进验证
|
|
|
|
| 编号 | 问题 | 验证结果 | 优先级 |
|
|
|------|------|----------|--------|
|
|
| 🟡 #3 | config.go 文件过大 (2497行) | ✅ 已确认 (2496行) | 中 |
|
|
| 🟡 #4 | GatewayHandler 职责过重 | ✅ 需关注 | 中 |
|
|
| 🟡 #5 | usage_logs 表分区策略 | ⚠️ 需确认生产配置 | 中 |
|
|
| 🟡 #6 | JWT Secret 自动生成风险 | ⚠️ 需运维关注 | 中 |
|
|
| 🟡 #7 | Admin API Key header 冲突 | ⚠️ 需验证路由顺序 | 低-中 |
|
|
|
|
### 8.3 信息级发现验证
|
|
|
|
| 编号 | 问题 | 验证结果 |
|
|
|------|------|----------|
|
|
| 💭 #8 | 密码复杂度要求不一致 | ✅ 已确认 |
|
|
| 💭 #9 | 测试覆盖不均衡 | ✅ 已确认 |
|
|
| 💭 #10 | 前端 confirm() 调用 | ✅ 已确认 (SoraAdminView.vue:100) |
|
|
| 💭 #11 | Dockerfile 非固定镜像标签 | ✅ 已确认 |
|
|
|
|
### 8.4 待修复项清单
|
|
|
|
**高优先级** (建议立即处理):
|
|
1. [ ] 加强 CREATE DATABASE 的防御深度
|
|
|
|
**中优先级** (建议近期处理):
|
|
2. [ ] 拆分 config.go (2496行)
|
|
3. [ ] 确认 usage_logs 分区在生产环境已启用
|
|
4. [ ] 添加 JWT Secret 轮换告警机制
|
|
|
|
**低优先级** (可选改进):
|
|
5. [ ] 统一密码复杂度要求
|
|
6. [ ] 替换前端 confirm() 为 ConfirmDialog 组件
|
|
7. [ ] 固定 Dockerfile 镜像版本
|
|
|
|
---
|
|
|
|
## 九、参考链接
|
|
|
|
- 官方仓库: https://github.com/Wei-Shaw/sub2api
|
|
- 目标仓库: https://www.tksea.top/pham/tokens-reef
|
|
- Prometheus 文档: https://prometheus.io/docs/
|