wren
8.2 KiB
LeAudit YAML 规则在线编辑设计
1. 背景
LeAudit 内核当前以本地 YAML/DSL 文件作为规则输入载体执行评查流程。现阶段 不修改 leaudit 核心，但平台侧需要逐步具备以下能力：
- 在线查看 YAML 规则内容
- 在线编辑 YAML 规则
- 校验规则语法与 DSL 语义
- 规则版本化保存
- 规则发布、回滚、审计
因此需要在 leaudit-platform 中补充一套“规则管理真相源”方案，使平台能够支持规则后台，而运行时仍然兼容 leaudit 只读取本地 YAML 的既有行为。
2. 结论
可以不改 leaudit 核心，同时把 DSL YAML 存储到 OSS，并把路径、版本、哈希等元数据存入数据库。
运行时通过 bridge 层完成一次“远端规则 → 本地临时文件”的转换：
数据库读取规则版本信息
→ 获取 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 文本后，平台可以执行标准流程：
编辑
→ 保存草稿
→ 语法校验
→ DSL 语义校验
→ 上传 OSS
→ 写入规则版本表
→ 发布 / 回滚
这让规则成为“平台可管理资产”，而不是“服务器磁盘文件”。
4.3 规则版本可追溯
每次评查运行都可以记录：
rule_set_idrule_version_idrule_source_oss_urlrule_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 推荐流程
编辑保存
前端提交 YAML 文本
→ 后端做 YAML 语法校验
→ 后端做 LeAudit DSL 语义校验
→ 生成新版本号 / version_seq
→ 上传 rules.yaml 到 OSS
→ 写 leaudit_rule_versions
→ 返回版本信息
发布生效
选择版本发布
→ 更新 leaudit_rule_sets.current_version_id
→ 记录发布日志
→ 清理规则缓存
→ 后续新 run 自动使用新版本
回滚
选择旧版本
→ 切换 current_version_id 到旧版本
→ 写回滚日志
→ 清理规则缓存
7. 运行时加载设计
7.1 核心原则
运行时不直接让 leaudit 读取 OSS，也不直接读取数据库文本；而是通过 bridge 统一适配。
7.2 推荐加载链路
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_bindingsleaudit_rule_sets.current_version_idleaudit_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 加载方式
又能保证：
- 在线编辑方便
- 版本管理清晰
- 发布回滚简单
- 多实例一致
- 运行结果可审计可追溯
这是当前项目向“规则可运营平台”演进时最合理的方案。