log-center/docs/log-collection-extension-plan.md

Log Center 日志收集扩展方案

背景

当前 Log Center 仅通过 POST /api/v1/logs/report 收集运行时错误（应用代码中捕获的异常）。以下两类重要错误场景未被覆盖：

1. CI/CD 构建错误 — Gitea Actions 构建失败（Docker build、npm build、测试失败等）
2. 部署错误 — K3s 集群中 Pod 异常状态（CrashLoopBackOff、OOMKilled、ImagePullBackOff 等）

目标：扩展 Log Center，使其成为覆盖"构建→部署→运行"全链路的错误收集平台。

---

实施方案

第一部分：后端 API 扩展

1.1 模型变更 — app/models.py

• 新增 LogSource 枚举：runtime(默认) / cicd / deployment
• ErrorLog 表新增 source 字段（带索引，默认 runtime）
• file_path 改为 Optional[str] = None（CI/CD 和部署错误无文件路径）
• line_number 改为 Optional[int] = None
• ErrorLogCreate 新增 source: str = "runtime" 字段

向后兼容：现有调用方不传 source 时自动为 runtime，无需任何修改。

1.2 指纹去重逻辑 — app/main.py:27 generate_fingerprint()

按 source 分别计算指纹：

Source	指纹组成	去重逻辑
runtime	project_id | error_type | file_path | line_number	不变
cicd	project_id | cicd | error_type | job_name | step_name	同一 Job 的同一 Step 同类错误去重
deployment	project_id | deployment | error_type | namespace | deployment_name	同一 Deployment 同类异常去重

1.3 API 端点变更 — app/main.py

端点	变更
POST /api/v1/logs/report (L33)	构建 ErrorLog 时写入 source 字段
GET /api/v1/bugs (L220)	新增 source 可选查询参数，加筛选条件
GET /api/v1/tasks/pending (L79)	新增 source 可选查询参数
GET /api/v1/dashboard/stats (L187)	新增 source 过滤 + 返回 source_distribution

1.4 数据库迁移 — app/database.py:27 init_db() 的 migrations 列表追加

ALTER TABLE errorlog ADD COLUMN source VARCHAR(20) DEFAULT 'runtime';
ALTER TABLE errorlog ALTER COLUMN file_path DROP NOT NULL;
ALTER TABLE errorlog ALTER COLUMN line_number DROP NOT NULL;
CREATE INDEX ix_errorlog_source ON errorlog (source);

沿用现有 try/except 幂等模式，零停机。

---

第二部分：CI/CD 构建错误上报

2.1 上报脚本 — 新建 scripts/report-cicd-error.sh

Bash 脚本，CI 环境天然有 curl + jq，无需额外依赖。

• 输入：project_id、step_name、错误消息或日志文件路径
• 自动读取 Gitea Actions 环境变量（GITHUB_WORKFLOW、GITHUB_JOB、GITHUB_SHA 等）
• 根据 step 名称推断 error_type（DockerBuildError / NpmBuildError / TestFailure 等）
• 发送到 /api/v1/logs/report，source: "cicd"
• 超时 10s，失败静默（不影响流水线）

2.2 Gitea Actions 集成示例 — 新建 scripts/gitea-actions-example.yaml

在构建步骤后加 if: failure() 条件步骤：

- name: Report Build Failure
  if: failure()
  run: |
    curl -s -X POST "${LOG_CENTER_URL}/api/v1/logs/report" \
      -H "Content-Type: application/json" \
      -d '{ "project_id": "xxx", "source": "cicd", ... }' \
      --max-time 10 || true

---

第三部分：K8s 部署错误监控（CronJob）

3.1 目录结构

log_center/k8s-monitor/
├── monitor.py          # 监控脚本
├── Dockerfile          # 镜像构建
└── requirements.txt    # kubernetes + requests

3.2 监控脚本 — k8s-monitor/monitor.py

• 使用 kubernetes Python 客户端（支持 in-cluster config）
• 扫描指定命名空间的所有 Pod
• 检测异常状态：CrashLoopBackOff、ImagePullBackOff、OOMKilled、Error、CreateContainerConfigError 等
• 通过 Pod label app 映射到 project_id（如 rtc-backend → rtc_backend）
• 获取容器日志（优先 previous=True 拿崩溃前日志）
• 上报到 /api/v1/logs/report，source: "deployment"，level: "CRITICAL"
• context 携带：namespace、pod_name、container_name、deployment_name、restart_count

3.3 K8s 部署 — 新建 k8s/monitor-cronjob.yaml

• CronJob：每 5 分钟执行（*/5 * * * *）
• RBAC：ServiceAccount + ClusterRole（仅 pods 和 pods/log 的 get/list 权限）
• 资源限制：64Mi/50m → 128Mi/100m
• 参考 rtc_backend/k8s/backend-deployment-prod.yaml 的 label 和格式风格

---

第四部分：前端 Dashboard 更新

4.1 类型定义 — web/src/api.ts

• ErrorLog 接口新增 source: string，file_path 和 line_number 改为可选
• getBugs 参数新增 source?: string
• getStats 支持 source 参数
• DashboardStats 新增 source_distribution

4.2 缺陷列表 — web/src/pages/BugList.tsx

• 在项目筛选和状态筛选之间新增来源筛选行（全部来源 / 运行时 / CI/CD / 部署）
• 表格新增「来源」列，显示彩色标签
• 「文件」列处理 null：file_path ? \${file_path}:${line_number}` : '-'`

4.3 缺陷详情 — web/src/pages/BugDetail.tsx

• 元信息新增来源显示
• 文件位置区域条件渲染（仅 runtime 有 file_path 时显示）
• CI/CD 错误显示：工作流名称、Job、Step、CI 日志链接
• 部署错误显示：命名空间、Pod 名称、容器、重启次数
• 非 runtime 错误禁用「触发修复」按钮，显示提示

4.4 仪表盘 — web/src/pages/Dashboard.tsx

• 新增「来源分布」表格（运行时/CI/CD/部署各多少条）

4.5 样式 — web/src/index.css

• 新增 .source-badge 及 .source-runtime / .source-cicd / .source-deployment 颜色
• 新增 .source-tabs 筛选行样式（复用 .project-tab 风格）

---

第五部分：Repair Agent 适配

5.1 仅修改一处 — repair_agent/agent/task_manager.py:33

fetch_pending_bugs() 的请求参数增加 "source": "runtime"，确保修复 Agent 只拉取运行时错误，忽略 CI/CD 和部署错误。

---

文件变更清单

文件	操作	说明
app/models.py	修改	LogSource 枚举、source 字段、可选字段
app/main.py	修改	指纹逻辑、source 过滤、stats 扩展
app/database.py	修改	追加 4 条迁移 SQL
web/src/api.ts	修改	类型 + API 函数
web/src/pages/BugList.tsx	修改	来源筛选 + 来源列
web/src/pages/BugDetail.tsx	修改	来源展示 + 条件渲染
web/src/pages/Dashboard.tsx	修改	来源分布表格
web/src/index.css	修改	来源标签样式
repair_agent/agent/task_manager.py	修改	加 source=runtime 过滤
scripts/report-cicd-error.sh	新建	CI/CD 错误上报脚本
scripts/gitea-actions-example.yaml	新建	Gitea Actions 集成示例
k8s-monitor/monitor.py	新建	K8s Pod 监控脚本
k8s-monitor/Dockerfile	新建	监控镜像
k8s-monitor/requirements.txt	新建	Python 依赖
k8s/monitor-cronjob.yaml	新建	CronJob + RBAC

---

验证方案

1. 后端：启动 API，分别用 curl 发送 runtime/cicd/deployment 三种 source 的错误，验证入库和去重
2. 前端：访问 Dashboard，验证来源筛选和来源标签显示正常
3. CI/CD：在某项目的 Gitea Actions 中故意制造构建失败，确认 Log Center 收到 cicd 错误
4. K8s Monitor：本地用 kubectl 模拟 CrashLoopBackOff Pod，运行 monitor.py，确认上报
5. Repair Agent：运行 python -m repair_agent list，确认只返回 runtime 来源的 Bug

---

实施顺序

1. 后端变更（模型 + API + 迁移）→ 部署
2. 前端更新 → 部署
3. CI/CD 上报脚本 → 提交到仓库，集成到各项目流水线
4. K8s Monitor → 构建镜像，部署 CronJob