feat: 支持 Mooncake UbDiag 两层编译与单 RPM 分发

[qinyufei63]

Summary

本 PR 将 Mooncake 的 UbDiag 接入收敛为两个互斥编译层，并保持单一 Mooncake RPM 的交付方式。

• Layer 0（默认，MOONCAKE_ENABLE_UBDIAG=OFF）：通过 FetchContent 拉取固定提交 8df2c2844d402e2e4dcd5ceab2424e8d36c5f99f，仅使用 UbDiag 公共头文件并传播 UBDIAG_DISABLE。Mooncake 不编译、不链接 libubdiag.so，RPM 也不包含 UbDiag 运行时产物。
• Layer 1（MOONCAKE_ENABLE_UBDIAG=ON）：使用 find_package(UbDiag CONFIG) 消费系统 RPM 已安装的共享库、开发配置和 CLI。Mooncake 链接系统 libubdiag.so，并保留 PerfPoint、P99/P999/P9999、PerfLog 与 CSV 能力；出包时将所选 CLI、共享库符号链接链和可选配置一并装入 Mooncake RPM。

Layer 1 不下载或编译真实 UbDiag，也不再校验 tag、Git SHA 或文件 SHA。系统 UbDiag 包的功能与 ABI 正确性由 UbDiag 发布方负责；Mooncake 只检查完成编译和单 RPM 交付所需的最小契约。

Layer contract

Layer 0

• 默认开启，无需预装 UbDiag RPM。
• 支持通过 MOONCAKE_UBDIAG_SOURCE_DIR 指定离线源码目录。
• 统一提供 UbDiag::ubdiag_lib 接口目标，但该目标仅传播头文件和 UBDIAG_DISABLE。
• 生成的 mooncake_ubdiag.env 标记为 mock，运行时路径字段为空。

Layer 1

启用 -DMOONCAKE_ENABLE_UBDIAG=ON 时，配置阶段要求：

1. 系统包导出 UbDiag::ubdiag_lib；
2. 导出目标为已安装的 SHARED_LIBRARY，并可解析到真实 libubdiag.so；
3. 目标传播 UBDIAG_ENABLE_PERCENTILE 与 UBDIAG_ENABLE_PERFLOG；
4. 系统中存在 ubdiag CLI；
5. CLI 与共享库均由已安装 RPM 提供，且二者的 VERSION-RELEASE.ARCH 完全一致。

未满足任一条件时，CMake 直接给出安装或重装 UbDiag RPM 的明确错误，不回退到源码构建。

Implementation

• mooncake-common/FindUbDiag.cmake：实现两层选择、统一目标、Layer 1 最小包契约和四字段构建清单。
• Store、Transfer Engine、Integration：统一链接 UbDiag::ubdiag_lib。
• P2P Store：Layer 0 仅启用空实现；Layer 1 才加入系统 UbDiag 库目录和运行时链接。
• scripts/build_rpm.sh：Layer 0 仅打包 Mooncake；Layer 1 额外复制 /usr/bin/ubdiag、与选中真实库对应的 libubdiag.so* 符号链接链及可选 /etc/ubdiag/ubdiag.conf，并通过 %post/%postun 执行 ldconfig。
• docs/ubdiag_integration_guide.md：保留面向用户的构建、打包、安装和故障处理说明。

Scope

最终差异为 8 个文件、465 行新增和 31 行删除，共 496 行：

• 不修改 README；
• 不包含技术交付文档、逐行解读、验证日志、远端验证脚本、容器资产或离线依赖；
• 不包含 cmake/RemoveRpath.cmake、构建树 RPATH 扫描、ELF 全量扫描、源码身份复核或隔离回装等保护性业务外逻辑；
• 提交历史保留本次两层分发从源码 Mock 到系统 UbDiag 的相关演进，移除旧设计稿和验证环境类提交。

How Has This Been Tested?

Current head (64f45d2848bfaf5cb14a28192132df8d6594d5ec)

• Layer 0 使用固定 UbDiag 源码完成针对性配置、编译和链接验证；编译命令包含 UBDIAG_DISABLE，产物不依赖 libubdiag.so。
• Layer 1 系统包探针完成配置与链接；CLI/共享库版本一致时通过，不一致时在 CMake 阶段被拒绝。
• 系统 UbDiag 导入目标提升为全局可见，Store、Transfer Engine 和 Integration 可在兄弟目录稳定复用。
• CLI 仅从所选系统 UbDiag 共享库对应的安装前缀查找；PATH 中其他版本或其他前缀的 CLI 不会被误选。
• 缺少 PerfLog 能力和静态 UbDiag 库的负向配置均被拒绝。
• Layer 0 与 Layer 1 Mooncake RPM 均完成构建和隔离安装验证；Layer 0 无 UbDiag 文件，Layer 1 包含标准系统路径下的 CLI、共享库符号链接链和配置。
• git diff --check、目标文件 codespell、cmake-format --check 通过。
• 从提交对象导出的 Linux 脚本通过 bash -n，避免 Windows 工作树 CRLF 干扰结论。
• 最终历史分支的 8 个产品文件与已验证精简树逐字节一致。

完整 Mooncake 本机构建受当前环境缺少目标分支完整第三方依赖限制，未伪造通过结论。

AArch64 双节点 UB 与 RPM 验证

2026-07-30 已在当前最终提交上重新完成 AArch64 双节点真实 UB、UbDiag 数据导出、Mooncake RPM 出包和隔离回装全流程验证。

• Layer 0：三个 Mooncake ELF 的完整 NEEDED 输出均无 libubdiag.so；运行前后 UbDiag SHM 无变化。
• Layer 0：写入 1000 个 key，成功 1000、失败 0；读取 14383 次查询、失败 0，吞吐 44.78 GB/s，P50 22426.57 us，P99 22877.59 us。
• Layer 1：Master/Client 实际加载系统 /usr/lib64/libubdiag.so.0.6.1，CLI 报告 UbDiag 0.6.1。
• Layer 1：写入 1000 个 key，成功 1000、失败 0；读取 14376 次查询、失败 0，吞吐 44.76 GB/s，P50 22256.76 us，P99 25144.86 us。
• PerfPoint、P99/P999/P9999、PerfLog、summary、detail、raw table、watch、history 均取得有效数据并生成 6 类 CSV。
• Layer 0/Layer 1 Mooncake RPM 均完成隔离回装；Layer 1 安装路径为 /usr/bin/ubdiag、/usr/lib64/libubdiag.so* 和 /etc/ubdiag/ubdiag.conf。
• 最终 L0 RPM SHA256：25df589cd502676fedd5339a8f9e24c45f5a87b5fa465f329b7348e36006f945；最终 L1 RPM SHA256：cb4bd78756ed85d0e431275a3ad0cccfcebbbbb02ea13a31c5c4f83c524c38fa。
• 经项目组确认，MemPoint、MemStat、CacheStat 不属于本次 Mooncake 接入验收范围。

Repository-wide checks

pre-commit run --all-files 已在当前精确提交上执行。全仓检查会命中目标分支既有的 trailing-whitespace、EOF、Ruff、codespell、clang-format 和 cmake-format 问题，并修改大量无关文件；因此本 PR 只保留目标 8 个文件的检查结果，不将基线格式化噪声带入本次变更。

Documentation

• Mooncake UbDiag integration guide

Checklist

• I have performed a self-review of my own code
• I have formatted my code using ./scripts/code_format.sh
• I have run pre-commit run --all-files and all hooks pass
• I have updated the documentation (if applicable)
• I have added validation to prove my changes are effective
• For changes >500 LOC: not applicable to the final 496-line diff; RFC #15 remains available as design background

AI Assistance Disclosure

• No AI tools were used
• AI tools were used for implementation review, documentation, and validation assistance

The human submitter has reviewed the changes and is responsible for understanding and defending them.