[RFC]: Mooncake UbDiag 两层分发与单 RPM 可复现交付 #15

Changes proposed

背景

Mooncake 的核心数据路径已经使用 UbDiag PerfPoint 埋点。现有使用方式若要求用户另行安装与 Mooncake 编译时 libubdiag.so 完全匹配的 CLI，会引入版本漂移、ABI 不一致和交付拆分问题；同时，默认构建不应强制引入 UbDiag 运行时依赖。

本 RFC 对应 PR #13，目标是在不改变 Mooncake 默认运行依赖的前提下，建立可复现的两层集成和单 RPM 交付链路。

目标

• 默认 Layer 0 使用 UBDIAG_DISABLE：保留 PerfPoint 调用语法，编译为空实现，不链接或打包 UbDiag CLI/动态库。
• 可选 Layer 1 使用 FetchContent：从固定仓库拉取并校验完整 40 位提交 8df2c2844d402e2e4dcd5ceab2424e8d36c5f99f，在同一 CMake 图中构建 libubdiag.so 与 ubdiag CLI。
• Layer 1 只生成一个 Mooncake RPM；包内同时包含 Mooncake、UbDiag CLI、同源动态库、配置和 provenance 文件。
• 打包阶段拒绝系统路径、PATH 或 LD_LIBRARY_PATH 中其他 UbDiag 版本的干扰。
• 最终 RPM 清除构建目录 RPATH/RUNPATH，并记录最终打包字节的 SHA256。

方案

源码身份

CMake 同时记录可读 ref 和不可变完整 SHA。无论在线 FetchContent 还是离线工作树，均要求：

1. HEAD 等于期望 SHA；
2. 工作树无已跟踪或未跟踪改动；
3. 预先存在的 UbDiag::ubdiag_lib 目标必须由当前 Mooncake 构建树创建；
4. UbDiag 二进制目录携带源码提交标记，来源变化时仅重建该依赖目录。

两层编译

打包信任链

CMake 生成结构化 manifest，RPM 脚本只解析允许字段，并仅从当前 BUILD_DIR/_deps/ubdiag-build 取产物。打包时再次核验源码 SHA、工作树、构建标记、CLI 对动态库的 NEEDED、应用消费者、暂存文件一致性和最终 RPATH。Layer 0 反向拒绝任何 UbDiag 文件或链接依赖。

用户接口

MOONCAKE_ENABLE_UBDIAG 是唯一模式开关；MOONCAKE_UBDIAG_SOURCE_DIR 支持离线洁净 Git 工作树。详细命令与运行方式见 docs/ubdiag_integration_guide.md，架构与实现见 docs/mooncake_ubdiag_two_layer_technical_delivery.md。

兼容性与影响

• 默认模式继续保持零 UbDiag 运行时依赖。
• Layer 1 增加 UbDiag 编译时间、RPM 体积和共享内存运行需求。
• 构建机必须可获得精确 UbDiag Git 对象；离线目录必须保留 Git 元数据。
• 出包机与运行机可以不同，来源证明约束的是打包进 RPM 的产物。
• 不引入系统 UbDiag fallback，避免不受控版本被装入 RPM。

验证

已完成：

• Layer 0/Layer 1 配置、编译和同一构建根切换；
• 错误 SHA、脏源码、伪造 CMake target、篡改构建标记、系统假 UbDiag 干扰等负向门禁；
• AArch64 双节点真实 UB write/read benchmark；
• UbDiag summary/detail/P99/PerfLog/raw table/watch/history 与 6 类 CSV 导出；
• Layer 0/Layer 1 单 RPM 内容、精确提交、CLI/库 SHA256、消费者链接和 RPATH/RUNPATH 校验。

非目标

• 不提供或消费客户系统 UbDiag 包；
• 不在运行时切换 Layer 0/Layer 1；模式在编译和出包阶段确定；
• 不在本 RFC 中修改 Mooncake 业务埋点语义。

Before submitting a new issue...

• Make sure you already searched for relevant issues and read the documentation