# 日志中心设计说明

> 更新：2026-07-05
> 范围：Loki/Elasticsearch 数据源、统一日志查询、字段发现、查询历史、保存查询、日志告警、日志 RBAC。// Logan.Li

---

## 定位

日志中心负责把多种日志后端统一成一个查询工作台，重点不是采集日志，而是：

1. 管理日志数据源。
2. 代理查询 Loki / Elasticsearch。
3. 提供统一查询体验和结果展示。
4. 从查询条件生成日志告警。
5. 按用户/角色限制可见数据源、索引、标签范围。

---

## 能力矩阵

| 能力 | 当前状态 | 说明 |
|------|----------|------|
| Loki 查询代理 | 已完成 | 后端代理查询，前端统一展示 |
| ES 查询代理 | 已完成 | 支持索引、字段、结果解析 |
| 日志数据源管理 | 已完成 | 创建、测试、配置 |
| 查询编辑器 | 已完成 | 快速查询、自动补全、查询构建 |
| 时间范围 | 已完成 | TimeRangePicker |
| 字段侧栏 | 已完成 | 字段统计和过滤 |
| 查询历史/保存查询 | 已完成 | 前端交互能力 |
| 日志告警 | 已完成 | 从查询创建告警规则 |
| 日志 RBAC | 已完成 | log scope role |

---

## 主要代码落点

| 层 | 文件 / 目录 | 说明 |
|----|-------------|------|
| 后端控制器 | `backend/controller/log_datasource.go` | 日志数据源 CRUD |
| 后端控制器 | `backend/controller/log_proxy.go` | Loki/ES 查询代理 |
| 后端控制器 | `backend/controller/log_proxy_explore.go` | 探索式查询能力 |
| 后端控制器 | `backend/controller/log_scope_role.go` | 日志范围权限 |
| 后端模型 | `backend/model/log_datasource.go` | 日志数据源 |
| 后端模型 | `backend/model/log_scope_role.go` | 日志 RBAC |
| 前端 API | `frontend/src/api/log/` | 日志中心 API |
| 前端组件 | `frontend/src/components/monitor/log-center/` | 日志中心完整 UI |

---

## 查询链路

```text
LogCenter UI
  ├── select datasource
  ├── build query
  ├── choose time range
  └── GET/POST /api/v1/log/...
        │
        ▼
Backend log proxy
  ├── load datasource
  ├── check log RBAC
  ├── translate request
  ├── query Loki / ES
  ├── normalize response
  └── return unified result
```

统一结果建议包含：

| 字段 | 说明 |
|------|------|
| `timestamp` | 日志时间 |
| `message` | 原始消息 |
| `labels` | Loki label 或 ES 字段标签 |
| `fields` | 结构化字段 |
| `source` | 数据源和索引/stream |
| `raw` | 原始日志对象 |

---

## 数据源模型

| 字段 | 说明 |
|------|------|
| `name` | 数据源名称 |
| `type` | loki / elasticsearch |
| `endpoint` | 服务地址 |
| `auth_type` | none / basic / token |
| `config` | 索引、租户、TLS、超时等 JSON |
| `status` | active / inactive |

敏感字段必须后端加密或脱敏返回，前端不应展示密码/token。

---

## 日志告警

```text
Saved Query / Current Query
  → create log alert rule
  → alert engine query log datasource
  → match count / pattern
  → create alert event
  → notify policy
```

建议规则字段：

| 字段 | 说明 |
|------|------|
| `datasource_id` | 日志数据源 |
| `query` | Loki LogQL 或 ES DSL/QueryString |
| `time_window` | 查询窗口 |
| `condition` | count > N / contains / no data |
| `severity` | warning / critical |
| `labels` | 业务、环境、服务 |

---

## 日志 RBAC

日志权限不只按页面菜单控制，还应按数据范围控制：

| 维度 | 示例 |
|------|------|
| 数据源 | 只能看生产 Loki，不能看审计 ES |
| 索引/stream | 只能看 `app-*` |
| 标签 | `namespace=dev`、`app=order` |
| 查询语法 | 禁止超大范围、禁止敏感索引 |

---

## 验收清单

1. Loki 数据源测试成功并能查询日志。
2. ES 数据源测试成功并能查询索引日志。
3. 查询时间范围切换后 URL/状态同步正确。
4. 字段侧栏能展示字段和值分布。
5. 从查询创建日志告警后能触发事件。
6. 无权限用户无法查询受限数据源或标签。
7. 查询超时、后端不可达时前端错误明确。