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

**使用方式**:
```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.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`

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

### 3.2 前端路由 (修改)

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

新增路由:
```typescript
{ 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. **拉取官方最新代码**:
   ```bash
   git fetch origin
   git merge origin/main
   ```

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

3. **运行测试**:
   ```bash
   # 后端
   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**: 代码已有注释说明依赖前置校验，但建议使用引号包裹加强防御：
  ```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行) | ✅ 已确认，已拆分 | 中 |
| 🟡 #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/