# 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 列表追加

```sql
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()` 条件步骤：

```yaml
- 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