# luban

**Repository Path**: xfcode-projects/luban

## Basic Information

- **Project Name**: luban
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-13
- **Last Updated**: 2026-11-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 鲁班

## 1. 使命

让线上异常从"人盯告警"变成"系统自动发现、自动生成待办、供 Agent 消费并回填结果"的闭环。通过统一日志采集、规则化待办生成、MCP 协议对外暴露能力，把运维排障从被动响应转为可被 AI 驱动的自动化流程，降低值班成本与故障平均修复时间（MTTR）。

---

## 2. 架构

```
┌──────────────────────────────────────────────────────────────────────┐
│  ① 采集层                                                             │
│  Java App (Logback JSON) → 采集代理 → 存储引擎 → 可视化/告警           │
└────────────────────────────┬─────────────────────────────────────────┘
                             │ 告警 Webhook / 定时轮询
┌────────────────────────────▼─────────────────────────────────────────┐
│  ② 规则层                                                             │
│  规则引擎 → 异常指纹去重 → 生成待办 → 落库 → 通知                      │
└────────────────────────────┬─────────────────────────────────────────┘
                             │ 待办数据
┌────────────────────────────▼─────────────────────────────────────────┐
│  ③ MCP Server 层（对外协议入口）                                       │
│  待办查询 / 待办执行 / 状态回填                                        │
└────────────────────────────┬─────────────────────────────────────────┘
                             │ MCP (SSE / Streamable HTTP)
┌────────────────────────────▼─────────────────────────────────────────┐
│  ④ 消费端：外部 Agent（自愈）  +  Web 前端（人工查看）                  │
└──────────────────────────────────────────────────────────────────────┘
```

**数据流**：日志入库 → 规则命中 → 指纹判重 → 生成待办 → MCP 暴露 → Agent 拉取执行 → 回填状态 → 前端展示待办/已办。

---

## 3. 功能

### 3.1 采集层支持的组件

| 环节 | 主选 | 备选 | 说明 |
|---|---|---|---|
| 应用埋点 | Logback + SLF4J | Log4j2 | 输出 JSON 结构化日志，必带 `traceId / service / level / exception` |
| 采集代理 | Promtail | Fluent Bit、Filebeat | 负责采集与打标签，记录文件偏移，重启不重复采集 |
| 存储引擎 | Loki | Elasticsearch | Loki 只对标签建索引、正文压缩存储，资源占用低；需全文检索时换 ES |
| 可视化/告警 | Grafana | Kibana | 作为告警触发入口，对接规则层 Webhook |

> 容器化部署：K8s 环境挂载 `/var/log/pods`；老 Docker runtime 需额外挂载 `/var/lib/docker/containers`。

### 3.2 规则层

**（1）规则能力**

- 规则引擎：Drools，支持运行时动态加载 DRL，无需重启即可调整规则
- 触发方式：Grafana Alert Webhook（事件驱动，推荐）或定时轮询 Loki
- 规则维度：日志级别、异常类型、关键字、服务名、时间窗口、错误频次阈值
- 规则示例：`level=ERROR && exception contains "SQLTransientConnectionException"` → 生成 P1 待办

**（2）重复判断（去重机制）**

- 指纹算法：`MD5(异常类 + 栈顶3帧 + 服务名)`
- 判重逻辑：同一指纹在去重窗口（默认 5 分钟）内只生成一条待办，重复命中则累加 `hitCount` 并更新 `lastOccurTime`
- 状态约束：指纹处于 `PROCESSING / FIXED` 状态时不再重复生成，避免同一问题刷屏

### 3.3 MCP Server

| Tool | 类型 | 功能 |
|---|---|---|
| `get_pending_todos` | 只读 | 提供待办消息列表（含优先级、服务、时间窗口） |
| `get_todo_detail` | 只读 | 提供单条待办详情与日志上下文 |
| `query_logs` | 只读 | 按 LogQL 查询 Loki，返回裁剪后的日志片段 |
| `exec_todo` | 执行 | 执行待办对应的处置动作（诊断/重启/扩容等），写操作需幂等键 |
| `update_todo_status` | 回填 | **执行完成后修改状态**：`OPEN → PROCESSING → FIXED / CLOSED`，并回填根因、执行记录、耗时 |

> 安全约束：只读工具可自动执行；变更类动作必须带审批开关；禁止 Agent 直接传入原始 LogQL/SQL，服务端做白名单校验。

### 3.4 前端展示

| 页面 | 内容 |
|---|---|
| 待办列表 | 展示 `OPEN / PROCESSING` 状态待办，字段：待办 ID、服务、错误类型、优先级、发生时间、命中次数 |
| 已办列表 | 展示 `FIXED / CLOSED` 状态待办，字段：待办 ID、根因、处置动作、处理人（Agent/人工）、耗时 |
| 详情页 | 点击任意待办进入，展示：日志快照、traceId、异常指纹、关联告警 |
| 执行记录 | 详情页内嵌时间线，展示每次 `exec_todo` / `update_todo_status` 的操作人、动作、结果、时间戳 |

---

需要我补充某一层的代码骨架（如 Drools 动态规则加载、MCP Tool 定义或前端列表页原型）吗？