pham/tokens-reef
2
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
3c956061956438ccd2728be2e8fcedabce66129c
tokens-reef/PROJECT_DIFF.md

12 KiB
Raw Blame History

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

使用方式:

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

新增路由:

// 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

新增路由:

{ 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. 拉取官方最新代码:

    git fetch origin
git merge origin/main

  2. 检查冲突文件:

    • 优先检查上述冲突风险文件
    • 确保自定义路由不被覆盖
    • 确保翻译键不被删除

  3. 运行测试:

    # 后端
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: 代码已有注释说明依赖前置校验，但建议使用引号包裹加强防御：

    // 当前代码 (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() 均使用白名单模式：

    // 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行) ✅ 已确认，已拆分 中
🟡 #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. [x] 拆分 config.go (已完成) 3. [ ] 确认 usage_logs 分区在生产环境已启用 4. [ ] 添加 JWT Secret 轮换告警机制

低优先级 (可选改进): 5. [ ] 统一密码复杂度要求 6. [ ] 替换前端 confirm() 为 ConfirmDialog 组件 7. [ ] 固定 Dockerfile 镜像版本

九、参考链接

Reference in New Issue View Git Blame Copy Permalink