tokens-reef/PROJECT_DIFF.md

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.5 管理员 API Handler (新增)

路径: backend/internal/handler/admin/

文件	说明
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.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
dataManagement.ts	数据管理 API

---

三、路由配置

3.1 后端路由 (修改)

路径: backend/internal/server/routes/admin.go

新增路由:

// 运维监控
opsGroup := admin.Group("/ops")
// ... 多个运维监控路由

3.2 前端路由 (修改)

路径: frontend/src/router/index.ts

新增路由:

{ path: '/admin/ops', component: OpsDashboard }
{ path: '/admin/data-management', component: DataManagementView }

---

四、国际化支持

4.1 中文翻译 (修改)

路径: frontend/src/i18n/locales/zh.ts

新增翻译键:

• 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 服务测试

5.2 前端测试

文件	说明
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/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() 调用	✅ 已确认
💭 #11	Dockerfile 非固定镜像标签	✅ 已确认

8.4 待修复项清单

高优先级 (建议立即处理):

1. 加强 CREATE DATABASE 的防御深度

中优先级 (建议近期处理): 2. [x] 拆分 config.go (已完成) 3. [ ] 确认 usage_logs 分区在生产环境已启用 4. [x] 添加 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/