wren
307 lines
8.2 KiB
Markdown
307 lines
8.2 KiB
Markdown
# LeAudit YAML 规则在线编辑设计
|
|
|
|
## 1. 背景
|
|
|
|
`LeAudit` 内核当前以本地 YAML/DSL 文件作为规则输入载体执行评查流程。现阶段 **不修改 `leaudit` 核心**，但平台侧需要逐步具备以下能力：
|
|
|
|
- 在线查看 YAML 规则内容
|
|
- 在线编辑 YAML 规则
|
|
- 校验规则语法与 DSL 语义
|
|
- 规则版本化保存
|
|
- 规则发布、回滚、审计
|
|
|
|
因此需要在 `leaudit-platform` 中补充一套“**规则管理真相源**”方案，使平台能够支持规则后台，而运行时仍然兼容 `leaudit` 只读取本地 YAML 的既有行为。
|
|
|
|
---
|
|
|
|
## 2. 结论
|
|
|
|
**可以不改 `leaudit` 核心，同时把 DSL YAML 存储到 OSS，并把路径、版本、哈希等元数据存入数据库。**
|
|
|
|
运行时通过 bridge 层完成一次“远端规则 → 本地临时文件”的转换：
|
|
|
|
```text
|
|
数据库读取规则版本信息
|
|
→ 获取 rules.yaml 的 oss_url
|
|
→ 从 OSS 下载到本地临时文件
|
|
→ 调用 leaudit.dsl.loader.load_rules_file(local_tmp_path)
|
|
→ 交给 leaudit 原生执行链继续处理
|
|
```
|
|
|
|
也就是说：
|
|
|
|
- **规则真相源**：OSS + 数据库
|
|
- **执行载体**：本地临时 YAML 文件
|
|
- **LeAudit 输入接口**：保持不变
|
|
|
|
这是当前约束下最稳妥、最容易演进的方案。
|
|
|
|
---
|
|
|
|
## 3. 为什么不能继续把本地 `rules/` 目录作为正式真相源
|
|
|
|
如果未来要开放 YAML 在线编辑界面，本地目录方案会迅速暴露问题：
|
|
|
|
### 3.1 不利于在线编辑
|
|
|
|
- 前端编辑后的内容最终仍要人工写回服务器目录
|
|
- 多实例部署时，需要同步到多台机器
|
|
- 容器化部署时，本地文件可能不是稳定持久层
|
|
|
|
### 3.2 不利于版本管理
|
|
|
|
- 难以明确记录“这次评查到底使用了哪一版规则”
|
|
- 覆盖同一路径的 `rules.yaml` 后，历史执行很难追溯
|
|
- 回滚通常会退化为“手工替换文件”
|
|
|
|
### 3.3 不利于审计与权限
|
|
|
|
- 谁改的、何时改的、为什么发布，很难形成正式审计链
|
|
- 无法自然承载“编辑 / 审核 / 发布 / 回滚”权限流程
|
|
|
|
### 3.4 不利于多实例一致性
|
|
|
|
- API 节点 A 和 Worker 节点 B 可能读取到不同版本本地文件
|
|
- 扩容后所有节点都要同步规则目录，运维成本高
|
|
|
|
因此，本地 `rules/` 目录更适合保留为：
|
|
|
|
- 种子规则导入源
|
|
- 紧急回退备份
|
|
- 开发环境本地调试资源
|
|
|
|
而不应该继续承担正式规则真相源角色。
|
|
|
|
---
|
|
|
|
## 4. 为什么采用“OSS + DB + 本地临时文件”模式
|
|
|
|
该方案同时兼顾了 **不改核心** 和 **平台化管理** 两个目标。
|
|
|
|
### 4.1 对 `leaudit` 零侵入
|
|
|
|
`leaudit` 仍然读取本地 YAML 文件，无需改造其解析器、执行器或 DSL 加载逻辑。
|
|
|
|
### 4.2 支持在线编辑界面
|
|
|
|
前端提交 YAML 文本后，平台可以执行标准流程：
|
|
|
|
```text
|
|
编辑
|
|
→ 保存草稿
|
|
→ 语法校验
|
|
→ DSL 语义校验
|
|
→ 上传 OSS
|
|
→ 写入规则版本表
|
|
→ 发布 / 回滚
|
|
```
|
|
|
|
这让规则成为“平台可管理资产”，而不是“服务器磁盘文件”。
|
|
|
|
### 4.3 规则版本可追溯
|
|
|
|
每次评查运行都可以记录：
|
|
|
|
- `rule_set_id`
|
|
- `rule_version_id`
|
|
- `rule_source_oss_url`
|
|
- `rule_source_sha256`
|
|
|
|
这样可以准确回答：
|
|
|
|
- 这个结果用的是哪一版规则？
|
|
- 规则文件是否被篡改？
|
|
- 是否可以按历史版本回放？
|
|
|
|
### 4.4 发布与回滚简单
|
|
|
|
- 发布：切换 `leaudit_rule_sets.current_version_id`
|
|
- 回滚：切回旧版本 ID
|
|
|
|
无需登录服务器替换目录文件，也不要求应用重新发版。
|
|
|
|
### 4.5 多实例一致
|
|
|
|
所有 API / Worker 都从同一份 DB + OSS 真相源取规则，不再依赖本地目录是否同步。
|
|
|
|
---
|
|
|
|
## 5. 建议的系统分层
|
|
|
|
### 5.1 真相源
|
|
|
|
- **OSS**：存储 `rules.yaml` 正文文件
|
|
- **数据库**：存储规则集、规则版本、绑定关系、发布状态、哈希、编辑人、发布时间等元数据
|
|
|
|
### 5.2 执行层
|
|
|
|
- bridge 层负责把 OSS 文件下载到本地临时路径
|
|
- 临时路径交给 `leaudit.dsl.loader.load_rules_file()` 使用
|
|
|
|
### 5.3 回退层
|
|
|
|
- 本地 `rules/` 目录保留为 fallback 或 emergency backup
|
|
- 当 OSS 不可用或某些历史规则尚未迁移时可临时使用
|
|
|
|
---
|
|
|
|
## 6. 在线编辑功能设计
|
|
|
|
### 6.1 目标能力
|
|
|
|
平台应逐步具备以下功能：
|
|
|
|
- 查看规则集列表
|
|
- 查看规则版本历史
|
|
- 查看某版本 YAML 内容
|
|
- 在线编辑 YAML
|
|
- 保存草稿版本
|
|
- 校验 YAML 语法
|
|
- 校验 LeAudit DSL 语义
|
|
- 发布指定版本
|
|
- 回滚到历史版本
|
|
- 查看发布日志与校验日志
|
|
|
|
### 6.2 推荐流程
|
|
|
|
#### 编辑保存
|
|
|
|
```text
|
|
前端提交 YAML 文本
|
|
→ 后端做 YAML 语法校验
|
|
→ 后端做 LeAudit DSL 语义校验
|
|
→ 生成新版本号 / version_seq
|
|
→ 上传 rules.yaml 到 OSS
|
|
→ 写 leaudit_rule_versions
|
|
→ 返回版本信息
|
|
```
|
|
|
|
#### 发布生效
|
|
|
|
```text
|
|
选择版本发布
|
|
→ 更新 leaudit_rule_sets.current_version_id
|
|
→ 记录发布日志
|
|
→ 清理规则缓存
|
|
→ 后续新 run 自动使用新版本
|
|
```
|
|
|
|
#### 回滚
|
|
|
|
```text
|
|
选择旧版本
|
|
→ 切换 current_version_id 到旧版本
|
|
→ 写回滚日志
|
|
→ 清理规则缓存
|
|
```
|
|
|
|
---
|
|
|
|
## 7. 运行时加载设计
|
|
|
|
### 7.1 核心原则
|
|
|
|
运行时不直接让 `leaudit` 读取 OSS，也不直接读取数据库文本；而是通过 bridge 统一适配。
|
|
|
|
### 7.2 推荐加载链路
|
|
|
|
```text
|
|
document/type 确定
|
|
→ leaudit_rule_type_bindings 查规则集
|
|
→ leaudit_rule_sets.current_version_id
|
|
→ leaudit_rule_versions.oss_url
|
|
→ 下载 OSS 文件到本地临时目录
|
|
→ 校验 sha256
|
|
→ load_rules_file(local_path)
|
|
→ 执行 leaudit pipeline
|
|
```
|
|
|
|
### 7.2.1 当前项目已落地状态
|
|
|
|
当前 bridge 已按这条路线开始落地，分成两条对称链路：
|
|
|
|
- 文档文件链：
|
|
- `leaudit_document_files.local_path / oss_url`
|
|
- 下载或读取后落本地临时文件
|
|
- 再交给原生 `AuditCtx.file_path`
|
|
- 规则文件链：
|
|
- `leaudit_rule_type_bindings`
|
|
- `leaudit_rule_sets.current_version_id`
|
|
- `leaudit_rule_versions.oss_url`
|
|
- 下载到本地临时 `rules.yaml`
|
|
- `RulesLoader.load(local_path)`
|
|
- `NativeRunner -> AuditService.audit(ctx)`
|
|
|
|
这意味着后续开放 YAML 在线编辑界面时，不需要改 `leaudit` 核心，只要继续维护 “OSS + DB + 本地临时文件” 这条桥接链即可。
|
|
|
|
### 7.3 为什么必须保留“本地临时文件”
|
|
|
|
因为当前约束是：
|
|
|
|
- 不修改 `leaudit` 核心
|
|
- `leaudit` 仍以本地路径作为 DSL 加载输入
|
|
|
|
所以本地临时文件不是“倒退”，而是一个必要的兼容层。
|
|
|
|
---
|
|
|
|
## 8. 与现有文档的一致性
|
|
|
|
该方案与当前 `docs/leaudit` 目录中的设计方向保持一致：
|
|
|
|
- `docs/leaudit/dsl_rule_schema_design.md`
|
|
- 已提出“规则真相源 = OSS 文件 + 数据库索引”
|
|
- 已提出“运行时 DB → OSS → 本地临时 YAML → LeAudit loader”
|
|
- `docs/leaudit/bridge_directory_design.md`
|
|
- 已明确 bridge 负责规则加载与缓存
|
|
- `docs/leaudit/processing_logic.md`
|
|
- 已明确 rules resolve 属于桥接层职责
|
|
|
|
本文件的重点是把“**为了未来开放 YAML 编辑界面，为什么必须这样设计**”单独说明清楚。
|
|
|
|
---
|
|
|
|
## 9. 当前项目建议
|
|
|
|
### 9.1 短期
|
|
|
|
- 保持本地 `rules/` 目录可用，确保现有流程可运行
|
|
- 将其视为 fallback，而非长期正式真相源
|
|
|
|
### 9.2 中期
|
|
|
|
- 增加规则内容查看 / 编辑 / 保存 / 发布接口
|
|
- 补齐 `leaudit_rule_versions` 的 OSS 文件上传和版本切换能力
|
|
- 补统一 OSS 客户端与 presign / upload / version publish 能力
|
|
|
|
### 9.3 长期
|
|
|
|
- 后台提供完整 YAML 在线编辑器
|
|
- 支持草稿、发布、回滚、审计
|
|
- 清理本地硬编码规则映射，统一走规则绑定表
|
|
|
|
---
|
|
|
|
## 10. 最终结论
|
|
|
|
如果未来要开放 YAML 编辑界面，那么当前项目最合适的规则架构不是“继续依赖本地目录”，而是：
|
|
|
|
- **OSS 存规则文件正文**
|
|
- **数据库存路径、版本、哈希、状态、发布信息**
|
|
- **运行时下载到本地临时文件后交给 `leaudit` 执行**
|
|
|
|
这样既能保证：
|
|
|
|
- 不修改 `leaudit`
|
|
- 兼容现有 DSL 加载方式
|
|
|
|
又能保证：
|
|
|
|
- 在线编辑方便
|
|
- 版本管理清晰
|
|
- 发布回滚简单
|
|
- 多实例一致
|
|
- 运行结果可审计可追溯
|
|
|
|
这是当前项目向“规则可运营平台”演进时最合理的方案。
|