[RFC]RAGFS与后端存储之间增加一层分布式缓存框架方案

[tuofang]

Single OpenViking RAGFS Distributed Cache Design

目录

1. 背景与目标
2. 技术选型
3. Openyuanrong-datasystem
4. Mooncake
5. Redis
6. 关键维度对比
7. UB 支持情况
8. 总体架构
9. 接入 Yuanrong 后架构
10. 第一步：建立 Yuanrong Provider 的 crate 和 feature 边界
11. 第二步：准备 Yuanrong Worker 和 C++ SDK
12. 第三步：实现稳定的 C ABI Bridge
13. 第四步：实现 Rust FFI 和安全的 YuanrongClient
14. 第五步：实现公共 CacheProvider 接口
15. 第六步：接入配置和 CacheProviderFactory
16. 第七步：由 CachedFileSystem 使用 Provider
17. 第八步：完成关闭、降级和端到端验证
18. 接入 Mooncake 架构
19. 第一步：固定 Mooncake 版本和部署形态
20. 第二步：增加可选 crate 和 Cargo feature
21. 第三步：构建并链接 Mooncake native 库
22. 第四步：定义 MooncakeConfig 并完成 setup
23. 第五步：封装同步 Rust API 和并发控制
24. 第六步：实现 MooncakeProvider
25. 第七步：注册到 CacheProviderFactory
26. 第八步：接入公共 CachedFileSystem
27. 第九步：分阶段优化并完成验证
28. 接入 Redis 架构
29. 第一步：增加 Redis adapter crate 和 feature
30. 第二步：定义连接与部署配置
31. 第三步：实现 RedisProvider
32. 第四步：注册到 CacheProviderFactory
33. 第五步：处理 Redis 特有约束
34. 第六步：完成验证和上线配置
35. 缓存对象
36. 文件缓存
37. 目录缓存
38. 子树 Generation
39. 缓存对象策略
40. 单写者一致性保证
41. 文件场景
42. 文件读
43. 文件写与更新
44. 文件删除
45. 文件 Rename
46. 目录场景
47. 目录读
48. 目录创建
49. 目录删除
50. 目录 Rename
51. 缓存击穿与请求合并
52. Leader 与 Follower
53. 与文件变更的并发关系
54. 错误、超时与清理
55. 容量与观测
56. 预取方案
57. 预取触发
58. 热点反馈 + hot_keys 缓存
59. OpenViking 定制优化
60. 1. 缓存 raw read_dir
61. 2. tree(agent) 批量摘要读取
62. 3. write_context 批量更新
63. 故障与降级
64. 指标监控
65. 推荐落地顺序
66. 最终保证

背景与目标↑ 目录

本方案面向单 OpenViking 进程场景：

OpenViking 独立进程
  -> RAGFS / MountableFS
  -> CachedFileSystem
  -> CacheProvider
       -> YuanrongProvider / MooncakeProvider / RedisProvider
  -> Backend FileSystem

目标是在 RAGFS 基础上通过统一 Provider 接入 Yuanrong DataSystem、Mooncake 或
Redis，作为小文件和目录缓存层，提升多读少写场景下的读性能，同时保证单写者
场景下的缓存失效一致性。

本方案假设：

1. 只有一个 OpenViking/RAGFS 进程写入该 namespace。
2. 所有文件和目录变更都经过 RAGFS。
3. backend 不会被外部绕过 RAGFS 直接修改。
4. Provider 的 put/delete(key) 成功后，同一 key 的后续读取不会返回旧值。
5. 缓存层只作为加速层，不作为事实来源。
6. 使用 RedisProvider 时默认只从 primary 读取；故障切换、连接重置或写结果不确定
   时进入 bypass 并回源，不依赖异步 replica 提供写后读一致性。

在该前提下，一致性问题从分布式多写者一致性收敛为单写者缓存失效一致性。

单写者缓存失效一致性 =
  backend 变更成功
  -> RAGFS 按文件系统语义更新或删除相关 cache key
  -> 变更返回

技术选型↑ 目录

Openyuanrong-datasystem↑ 目录

总体定位：

利用计算节点的 HBM、DRAM 和 SSD，把共享存储中的数据按照访问需求搬到离计算最近的位置，通过共享内存、热副本和多级缓存降低延迟并削减后端存储负担。

图中 RAGFS 通过 SDK 访问本节点 worker：同节点进程与 worker 之间可通过共享内存读写数据，worker 之间通过 TCP 或 RDMA 传输缓存对象；节点内或节点间的 HBM 数据可通过 HCCS、RoCE 等链路流动；ETCD 或内置 Metastore 负责集群元数据和节点管理。RDMA、RoCE、HCCS 等能力是否可用取决于实际部署版本、编译选项和硬件环境，应以部署版本的能力为准。

控制小对象带来的内存碎片：初始化时申请一大块共享内存，通过空闲块复用和相邻空闲空间合并减少碎片；系统本身不负责自动将多个 key 合并为一个对象。

一致性策略

Yuanrong DataSystem 的 KV 接口支持以下一致性类型，一致性类型通过 SetParam、MSetParam 等写入参数指定：

一致性类型	含义	适用说明
PRAM	Pipeline RAM consistency，默认模式	保证同一进程发出的写操作按程序顺序被其他进程观察，开销较低
CAUSAL	因果一致性	保证存在因果关系的操作按因果顺序被观察，约束强于 PRAM

上述一致性类型解决的是 KV 操作的可见顺序，不直接提供文件系统层面的路径、文件内容和目录成员关系的一致性。RAGFS 仍需以文件 key、目录 key 和 subtree_generation 等机制维护文件系统语义。

本文后续缓存方案采用以下 key 级副本更新前提：

更新缓存的节点请求 master 更新 primary
  -> master 通知其他副本失效
  -> 旧副本全部失效后更新返回
  -> 后续读取按需从 primary 拉取最新值并建立本地副本

该机制保证同一个 key 更新完成后不会继续从旧副本读取旧值；跨 key 的原子关系，例如“文件内容更新并同步更新父目录项”，仍由 RAGFS 的变更顺序和失效规则保证。

可靠性与生命周期

• none：对象只保存在缓存层，worker 故障或对象淘汰后可能丢失，适合可从 backend 重建的缓存数据。
• write_back：先写缓存，再异步持久化，写入延迟较低，但需要接受异步落盘窗口内的故障风险。
• write_through：写入缓存时同步持久化，可靠性较高，但写入路径更长。
• TTL：通过 ttlSecond 或 Expire 设置对象过期时间，适合限制缓存陈旧时间和回收冷对象。
• LRU：本地副本可按 LRU 淘汰；跨节点读取建立的本地副本也受容量与淘汰策略约束。
• Spill：内存压力较大时可将对象下沉到 SSD，读取时再提升到内存层，以容量换取可控的访问延迟。

对于 RAGFS 缓存，缓存数据可以从 backend 重建，因此通常不把 Yuanrong 当作唯一持久化副本；具体写入模式应根据故障恢复目标选择。

KVClient 接口

RAGFS 的 native 接入层通过 KVClient 使用以下主要接口：

接口	作用	接入时的关注点
Init / ShutDown	初始化和关闭客户端	由 YuanrongProvider 随 OpenViking 进程生命周期管理
Create / MCreate	创建共享内存 Buffer	适合减少大对象或批量对象写入时的内存复制
Set	写入单个 key	可配置一致性、TTL 和写入模式
MSet	批量写入多个 key	单次最多 10000 个对象，文档建议一次不超过 64 个
MSetTx	事务式批量写入	1 至 8 个 key 全部成功或全部失败，可用于小规模关联元数据
Get	获取单个或批量对象	支持字符串、Buffer 和 ReadOnlyBuffer；Buffer 形式可减少复制
Read	读取对象的指定范围	适合只读取对象局部内容的场景
Del	删除单个或批量 key	key 不存在时也按成功处理，便于实现幂等失效
Exist	批量判断 key 是否存在	单次最多查询 10000 个 key
Expire	更新对象 TTL	可批量更新，单次最多 10000 个 key
QuerySize	查询对象大小	可在分配读取 Buffer 或执行大小策略前使用
HealthCheck	检查服务健康状态	用于初始化检查、降级判断和监控

Get 的 subTimeoutMs 可在 key 尚不存在或尚未就绪时等待一段时间，设置为 0 表示不等待。key 最长为 255 字节，并受允许字符范围约束，因此 RAGFS 应先对规范化路径编码或哈希，再生成稳定的缓存 key。

参考资料：

• Yuanrong DataSystem KVClient C++ API
• Yuanrong DataSystem ConsistencyType
• 《Mooncake 与 openYuanrong datasystem 深度研究报告》

Mooncake↑ 目录

Mooncake Store 是面向 LLM 推理和远程内存池的分布式 KVCache 存储引擎。Master Service 负责对象分配、元数据、lease、复制任务和集群管理，Mooncake Client 负责实际数据读写，控制流与数据流相互分离。

Mooncake 多节点缓存参考架构。版本、lease 和 invalidation 由 Rust 服务及外部控制面协同维护；Mooncake 原生数据面负责对象放置和直接数据传输。

图中每个应用节点包含进程内 L1 热缓存、Rust 服务和 Mooncake Client。Rust 服务负责缓存协议、版本判断和 L1 管理；Mooncake Client 通过 RPC 与 Master 交互控制信息，通过 Transfer Engine 在本地或远端 Segment 之间直接传输数据。控制面中的版本索引和失效事件是 RAGFS 接入时增加的文件系统语义层，不应视为 Mooncake 原生提供了订阅式 invalidation 总线。

Mooncake 控制小对象内存碎片的方式是预先分配较大的 Segment，通过空闲空间复用、相邻空闲空间合并和 bin 分类降低分配碎片；系统本身不负责自动将多个 key 打包为一个对象。

提供接口

Mooncake 公开的接口面包括 Store 原生客户端 API、C API、Python API 和 Rust bindings。Rust bindings 已进入官方版本，但具体方法签名仍应以实际 checkout 的版本为准。

接口或接口组	作用	接入关注点
new / setup	创建客户端并连接 metadata server、Master 和本地 Segment	setup 需要 hostname、metadata server、Segment 大小、协议、RDMA 设备和 Master 地址等参数
health_check	检查 Store 服务可用性	用于启动检查、探活和降级判断
put / get	写入和读取单个对象	面向 string key -> object 模型，不直接提供文件或目录语义
BatchPut / BatchGet	批量写入和读取对象	适合合并请求，降低大量小对象的调用开销
PutStart / PutEnd / PutRevoke	控制一次写入的创建、提交和撤销生命周期	只有完成提交的对象才能作为完整对象被读取；异常中断对象由超时回收机制处理
ExistKey / GetReplicaListRequest	查询对象和副本位置	成功查询时可取得对象级 lease，保护后续读取
Remove / RemoveAll	删除对象	lease 有效期内删除会受到保护；强制删除需要谨慎使用
register_buffer / unregister_buffer	注册和注销数据缓冲区	RDMA 零拷贝路径通常要求使用已注册内存
put_from	从已注册 Buffer 直接写入对象	减少中间复制，适合大对象或打包后的 blob
HTTP /metrics、/query_key、/health 等	指标、key 查询、Segment 检查和健康检查	属于管理与观测接口，不作为业务数据读写协议

Mooncake 更适合作为 native dependency 接入，而不是把 Store 当作通用 HTTP 或 gRPC KV 服务。Rust 服务需要链接 Mooncake 原生库，并对同步或阻塞调用做线程隔离。

一致性策略

Mooncake 的公开一致性重点是对象 lease 和完整读取保护，而不是数据库式事务一致性：

1. ExistKey 或 GetReplicaListRequest 成功后，读方获得对象级 lease。
2. lease 有效期内，对象不会被 Remove、RemoveAll 或 eviction 删除。
3. 如果 lease 在读取完成前过期，本次 Get 失败，而不是返回可能损坏或只写入一部分的数据。
4. PutStart 到 PutEnd 之间的对象不会作为已完成对象使用；客户端异常退出后，Master 根据超时配置回收 zombie object。
5. approximate LRU、soft pin 和 hard pin 控制对象淘汰优先级，但不解决跨 key 的文件系统原子关系。

Mooncake 没有公开的 Store 级订阅式失效接口。因此图中的 version / lease / invalidation 需要由 RAGFS 上层实现：文件内容使用版本化 key，当前版本保存在独立元数据中；更新时先写新对象，再切换版本索引，最后通过外部事件通道通知其他节点清理 L1。lease 只保证正在读取的旧对象不会被并发删除，不能代替版本切换和目录失效。

数据面能力

• 控制面与数据面分离：Master 维护 key -> replica / segment / lease，Client 之间直接传输对象数据。
• TCP/RDMA：Transfer Engine 可根据部署环境使用 TCP 或 RDMA，RDMA 路径支持注册内存和零拷贝。
• 多 NIC 与拓扑感知：支持设备发现、路径选择和多链路并行传输。
• 切片与并行 I/O：大对象可以切片后跨路径传输，提高链路利用率和聚合吞吐。
• 失败路径重传：传输任务可以在路径失败后重试或切换路径，降低单链路故障影响。
• 数据局部性：通过 preferred_segment、replica_num、soft pin 和 hard pin 控制副本放置与热点驻留。
• 多层存储：支持 DRAM、SSD offload 和 DFS；内存 miss 时可从 SSD 或 DFS 回退读取。
• 可观测性：Master 提供 Prometheus 风格指标、key 查询、Segment 检查和健康检查接口。

Mooncake 的公开性能数据主要面向较大的 KV block 和高并发传输，不能直接等价为 4 KB 或 16 KB 小文件的 P99。用于小文件缓存时，应优先采用 packed blob 和 side index，减少对象级元数据、lease 和网络调用放大。

Mooncake Client 也可以嵌入业务进程。该模式的代价包括：

• RealClient 会占用业务进程地址空间
• 挂载的全局 Segment 由业务进程持有
• RDMA、Transfer Engine 和 SSD offload 都运行在业务进程内
• Client 故障可能影响整个业务进程
• 业务进程重启时，本地内存副本一起消失

参考资料：

• Mooncake Store 设计文档
• Mooncake HTTP Service API
• Mooncake Store Python API
• 《Mooncake 与 openYuanrong datasystem 深度研究报告》

Redis↑ 目录

Redis 是成熟的内存型网络 KV 数据库，可直接作为 RAGFS 的远程缓存 Provider。
应用通过 RESP 协议和现成 Rust 客户端访问 Redis Server，不需要链接 C++ native
库，也不需要在 OpenViking 进程内初始化 RDMA、共享内存或远程 Segment。

KV 缓存能力

Redis 提供的能力与文件系统缓存对象较容易映射：

能力	Redis 接口	RAGFS 用法
单 key 读写	GET / SET / DEL	存储文件、目录和 generation 的 CacheEnvelope
批量操作	MGET / MSET、Pipeline	合并目录预取、批量失效和热点对象读取
对象过期	EXPIRE、SET EX/PX、TTL	设置文件或目录缓存 TTL
条件更新	SET NX/XX、WATCH	inflight 锁、租约或条件写入
原子逻辑	Lua、Redis Functions、MULTI/EXEC	原子更新少量关联 key 或执行校验后写入
容量管理	maxmemory、LRU/LFU/TTL 等淘汰策略	在达到容量上限时回收可从 backend 重建的对象
事件通知	Keyspace Notifications、Pub/Sub、Streams	可选失效通知和运维事件，不作为唯一正确性来源

Pipeline 只减少多条命令的网络往返，并不自动提供事务原子性。Redis Cluster 中，
MGET、Lua 或事务涉及的多个 key 通常需要落在同一 hash slot；若文件 key、父目录
key 和 generation key 需要原子操作，应使用一致的 hash tag，或者继续采用本文的
“backend 成功后逐 key 失效”方案。

一致性策略

单个 Redis 实例按顺序执行命令，单条命令具有原子性；Lua、Redis Functions 和
MULTI/EXEC 可把一组受支持操作作为不可被其他命令穿插的执行单元。但 Redis
主从复制默认是异步的，因此 primary 返回写成功时，replica 可能尚未收到该写入。

高可用部署下需要明确以下边界：

1. RAGFS 的写、删除和失效操作只发送到 primary，不从可能落后的 replica 读取。
2. WAIT 可以等待指定数量 replica 确认收到此前写入，降低故障切换后的丢写概率，
   但官方文档明确说明它不会使 Redis 成为强一致系统。
3. Redis 7.2 及以上的 WAITAOF 还可以等待本地或 replica 将写入同步到 AOF，
   提高持久性，但超时、故障切换和未覆盖全部成员时仍可能丢失数据。
4. Sentinel 或 Redis Cluster 的自动故障切换是 best effort；极端故障窗口内，
   新 primary 可能缺少刚刚确认的缓存写入。
5. 缓存不是事实数据源，因此允许缓存对象丢失；不能允许错误地把旧缓存作为最新
   backend 状态。发生 failover、超时或连接重置时，Provider 应短暂 bypass，并让
   CachedFileSystem 回源重建。

在本文单 OpenViking 写者场景中，不要求 Redis 提供跨文件系统 key 的强事务。
CachedFileSystem 仍负责先完成 backend 变更，再删除或更新文件 key、父目录 key
和 subtree_generation。Redis 只保证每个缓存原语的执行，不替代文件系统一致性层。

可靠性与高可用

Redis 可以按缓存的重要程度选择不同可靠性配置：

• 无持久化：延迟和写放大最低，进程或节点故障后缓存全部重建，适合纯加速层。
• RDB：周期性生成数据快照，恢复速度较快，但故障时可能丢失最近一个快照周期
  的缓存数据。
• AOF：记录写命令并在重启时重放；appendfsync everysec 通常在性能与恢复窗口
  之间折中，always 更可靠但增加写延迟。
• RDB + AOF：同时保留快照和更完整的写日志，重启时优先使用 AOF 恢复。
• Sentinel：为非分片 primary-replica 部署提供监控、选主和自动故障切换。
• Redis Cluster：提供 hash slot 分片、节点扩展和分片级故障切换，但增加多 key
  操作、迁槽和客户端重定向的复杂度。

缓存容量建议设置 maxmemory，并使用 allkeys-lfu 或 allkeys-lru 淘汰策略。
所有缓存对象仍应携带逻辑过期信息；即使 Redis TTL、淘汰或持久化恢复行为异常，
CachedFileSystem 解码 CacheEnvelope 后也能拒绝过期或 generation 不匹配的数据。

适用性

Redis 的主要优势是部署成熟、客户端生态完整、运维工具丰富，适合快速落地、普通
以太网环境和中小规模小文件缓存。它的限制是每次访问通常经过 socket、RESP 编解码
和数据复制，无法直接获得 Yuanrong 的同节点共享内存路径或 Mooncake 的
RDMA/注册内存数据面；大量小请求必须使用连接池、Pipeline 和 MGET 控制 RTT。

第一阶段可将 RedisProvider 映射为：

get          -> GET
put          -> SET key value PX ttl
delete       -> DEL
get_many     -> MGET 或 Pipeline GET
health_check -> PING

RedisProvider 应复用总体架构中的 CacheProvider 接口，一致性、缓存对象格式、
inflight 合并和 backend 回源逻辑不应在 Redis adapter 中重新实现。

参考资料：

• Redis replication
• Redis persistence
• Redis WAIT
• Redis WAITAOF
• Redis pipelining
• Redis key eviction

关键维度对比↑ 目录

维度	Mooncake	openYuanrong datasystem	Redis
核心定位	分布式 KVCache 存储引擎，偏 LLM 推理与远程内存池	以内存为中心的异构分布式多级缓存，偏近计算缓存与 HBM、DRAM、SSD 协同	通用内存型网络 KV 数据库，缓存生态成熟
控制面	Master 负责分配、元数据、任务、lease 和淘汰；支持 HTTP metadata、ETCD、snapshot 和 restore	ETCD 或内置 Metastore；worker 管理资源与元数据；支持服务发现与同节点亲和	单实例、Sentinel 或 Cluster；Cluster 使用 hash slot 分片
数据面	Client 真正读写；支持 TCP、RDMA、大对象 striping、并行 I/O 和零拷贝	SDK 与本地 worker 共享内存免拷贝；worker 之间支持 TCP、RDMA 或 UB	RESP over TCP/TLS；Pipeline 和批量命令降低 RTT
一致性模型	公开重点是 lease 读保护和“不会读错”，不是数据库式事务一致性	公开提供 PRAM 和 CAUSAL 两种一致性模型，默认 PRAM	单命令原子；主从默认异步复制；WAIT/WAITAOF 提高安全性但不提供强一致
失效与生命周期	approximate LRU、lease、soft pin、hard pin、force remove	TTL、LRU、delete、本地热点副本 LRU、stream publish/subscribe	TTL、DEL、LRU/LFU/TTL 淘汰、可选 keyspace notification
多层存储	DRAM、SSD offload、DFS 和对象快照	HBM、DRAM、SSD 多级缓存，支持 spill 到磁盘	开源版以内存为主，可使用 RDB/AOF 持久化；部分商业形态支持 RAM/Flash 分层
热点数据	replica_num、preferred_segment、soft pin、hard pin，提供显式 locality control	跨节点读取时自动在本地保存副本，适合热点数据回流到本地	LFU/LRU 识别和保留热点，但不提供应用节点本地共享内存副本
可靠性	多副本、lease、SSD/DFS 回退和快照	key 级副本、TTL、spill 和可选持久化模式	RDB、AOF、主从复制、Sentinel、Cluster；故障窗口内仍可能丢写
Rust 集成现状	已有原生 Rust bindings 和示例，仍需按具体版本核对 API	未检索到公开 Rust SDK 文档，建议使用 C++ wrapper 和 Rust FFI	Rust 客户端成熟，纯网络协议接入，无 native SDK 链接依赖
小文件场景适配	更适合远程缓存层，强烈建议对小文件进行打包	更适合节点内热层和异构搬运层，跨节点尾延迟需要自行测试	直接 KV 映射最简单，适合快速落地；需通过 Pipeline/MGET 控制大量小请求 RTT

与 Alluxio、JuiceFS 等系统相比，三者都不是带 POSIX、FUSE 或目录树语义的完整
文件系统缓存产品。它们只提供不同形态的 KV 缓存和数据面能力；目录树、rename、
版本索引、批量失效、回源和命名空间隔离仍需由 RAGFS 实现。

UB 支持情况↑ 目录

UB 定位及协议边界

灵衢（UnifiedBus，UB）面向超节点互联，将 I/O、内存访问和不同处理单元之间的通信统一到同一互联体系中。对分布式缓存而言，UB 主要优化跨节点或跨处理单元的数据搬移路径，不改变 KV 对象模型、缓存生命周期或上层一致性语义。

Mooncake 中需要区分两个名称相近但用途不同的协议：

协议	主要用途	实现后端
ub	Kunpeng 节点之间的远程 CPU/NUMA 内存访问	URMA/UMDK，对应经典 Transfer Engine 的 UbTransport
ubshmem	Ascend NPU Fabric 和共享内存访问	Ascend UBShmem Runtime，对应独立的 UBShmemTransport

ubshmem 的能力不能用于推断 ub 的能力。本文对 Mooncake 的分析主要指通过 protocol="ub" 启用的 URMA 数据面。

openYuanrong DataSystem

openYuanrong DataSystem 已集成 UB 支持，通过 URMA 在具备 UB 硬件的超节点内加速 worker 之间的数据传输，并对应用保持原有 KVClient 接口。启用 UB 后，Set/Get 等调用方式不变，变化发生在 worker 的底层跨节点传输路径。

主要能力和部署要求如下：

• 编译时使用 build.sh -M on 启用 UB；如不需要 CANN 异构能力，可同时使用 -X off。
• 编译环境与运行环境的 URMA 版本必须一致，否则可能出现 UB 能力异常。
• 运行环境建议使用 openEuler 24.03、UB 2.0，并安装相应 UB/URMA 用户态和内核组件。
• 至少需要两个具备 UB 硬件和软件环境的节点，集群管理依赖稳定可用的 ETCD。
• 进程部署通过 dscli start ... --enable_urma true 启用。
• Kubernetes 部署通过 Helm 配置 global.performance.enableUrma: true，并将宿主机 URMA 工具和 /lib64/urma/ 挂载到 Pod。
• 可以在一个节点写入 key、另一个节点读取该 key，以验证 UB 跨节点数据路径。

生产环境还建议关闭 LPI、启用大页内存并绑定 NUMA 节点，减少 CPU 低功耗状态和远端 NUMA 访问对尾延迟的影响。例如进程部署时可以组合使用：

--enable_urma true
--enable_huge_tlb true
--cpunodebind 0
--localalloc

Yuanrong 的 UB 文档已覆盖源码编译、进程部署、Kubernetes 部署和跨节点验证流程，部署路径相对完整。实际性能仍取决于 UB 拓扑、URMA 版本、NUMA 绑定、大页配置以及目标硬件环境。

Mooncake Store

Mooncake 已为经典 Transfer Engine 实现基于 URMA/UMDK 的 UB 后端，并接入 Store 的 Put、Get、副本写入和副本读取路径。上层没有新增 UB 专用的 Put/Get API，而是在通用初始化接口中指定 protocol="ub" 和设备列表。

Mooncake UB 当前支持：

• UB 设备发现、多设备过滤和拓扑选择。
• 本地内存注册及远端 Segment 导入。
• 基于 URMA RC Jetty 的单边 READ 和 WRITE。
• Store Put/Get、副本写入和副本读取。
• 默认 64 KiB Slice 分片、完成状态查询和失败 Slice 重试。
• 设备 Fatal、端口 Down、EID Change 后的失活处理与恢复。
• Real Client 共进程部署及独立 Client Service 部署。

构建时需要显式启用：

cmake .. -DUSE_UB=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo

目标环境主要是 Kunpeng 950、openEuler 24.03 LTS-SP3、UBCore/URMA 和 UMDK。部署前需要确认存在真实的 liburma.so、URMA 头文件，并能通过 urma_admin -l 发现设备。当前构建逻辑在找不到真实 liburma.so 时可能编入 Mock URMA，因此“编译成功”不等于二进制已经具备真实 UB 硬件访问能力。

Mooncake Store 初始化时建议显式指定真实设备名，例如 urma0 或 urma0,urma1。多设备路径会按 Slice 进行拓扑和失败重选，但不能仅凭配置多个设备就认定单次传输一定能获得所有设备的聚合带宽。

当前限制包括：

• OBMM_ENDPOINT 尚未实现，实际可用的是 URMA Endpoint。
• ub 路径主要支持 CPU/NUMA 内存；Ascend Fabric Memory 应使用 ubshmem。
• TENT Transport 当前没有 UB 后端，UB 应使用经典 Transfer Engine。
• Store 没有提供 UB 原子操作接口，当前数据操作使用单边 READ 和 WRITE。
• UB 初始化或传输失败时没有自动回退到 TCP 的逻辑。
• 真实双节点硬件、Store 完整 E2E、多副本、多设备聚合和长期故障测试覆盖仍有限。

因此 Mooncake UB 已经贯通设备发现、内存注册、元数据交换、连接建立、单边读写和 Store Put/Get，不只是协议占位；但它仍是默认关闭、面向特定硬件的高级传输后端，成熟度和测试覆盖低于 TCP/RDMA。

构建、部署与能力对比

维度	openYuanrong DataSystem	Mooncake Store
UB 接入位置	worker 之间的数据传输路径	经典 Transfer Engine 的 UbTransport
上层接口	原有 KVClient Set/Get 等接口保持不变	原有 Store Put/Get 等接口保持不变
启用方式	build.sh -M on；运行时 --enable_urma true	CMake -DUSE_UB=ON；初始化时 protocol="ub"
主要环境	openEuler 24.03、UB 2.0、匹配版本的 URMA	Kunpeng 950、openEuler 24.03 LTS-SP3、UBCore/URMA、UMDK
集群依赖	至少两个 UB 节点和 ETCD	Master、Metadata Service、UB Client 节点
数据操作	KV 跨节点读取和写入	URMA 单边 READ/WRITE，覆盖 Put/Get 和副本传输
多设备能力	依赖底层 UB/URMA 环境和部署配置	支持设备发现、过滤、拓扑选择和 Slice 级失败重选
部署方式	进程部署和 Kubernetes Helm 部署	Real Client 共进程或独立 Client Service
性能建议	关闭 LPI、启用大页、绑定 NUMA	显式指定设备，校验 NUMA/拓扑并在真实硬件压测
自动回退 TCP	文档未说明自动回退机制	不支持
文档与验证	包含编译、部署、K8s 和跨节点读写验证	实现分析完整，但真实硬件 Store E2E 测试覆盖有限
当前成熟度	已提供较完整的产品化启用和部署流程	功能链路已贯通，但低于 TCP/RDMA，不宜作为通用默认协议

参考资料：

• <yuanrong_ub_support.md>
• <mooncake_store_ub_support.md>

总体架构↑ 目录

RAGFS 将缓存拆分为“文件系统公共缓存层”和“可替换缓存 Provider”两部分。CachedFileSystem 只实现一次文件与目录缓存语义，Yuanrong、Mooncake 和 Redis 仅在执行 get、put、delete 等缓存原语时产生差异。

整体调用关系如下：

OpenViking
  -> RAGFSBindingClient
  -> MountableFS
  -> StatsWrappedFS
  -> CachedFileSystem
       -> Backend FileSystem
       -> Arc<dyn CacheProvider>
            -> YuanrongProvider
            -> MooncakeProvider
            -> RedisProvider

CachedFileSystem 负责：

• 判断文件、目录或控制对象是否允许缓存。
• 生成 file_key、dir_key，编码和校验统一的 CacheEnvelope。
• 处理 cache hit、miss、backend 回源和缓存回填。
• 在写、删除、rename 后执行文件 key、父目录 key 和 subtree_generation 失效。
• 实现 inflight 请求合并、预取、超时、降级和统一指标。

Provider 只提供最小缓存原语：

#[async_trait]
pub trait CacheProvider: Send + Sync {
    fn name(&self) -> &'static str;
    fn capabilities(&self) -> ProviderCapabilities;

    async fn get(&self, key: &str) -> CacheResult<Option<Bytes>>;
    async fn put(
        &self,
        key: &str,
        value: Bytes,
        options: &PutOptions,
    ) -> CacheResult<()>;
    async fn delete(&self, key: &str) -> CacheResult<()>;
    async fn get_many(
        &self,
        keys: &[String],
    ) -> CacheResult<Vec<Option<Bytes>>>;
    async fn health_check(&self) -> CacheResult<()>;
}

Provider 对公共操作的映射：

公共操作	YuanrongProvider	MooncakeProvider	RedisProvider
get	KVClient::Get	MooncakeStore::is_exist + get	GET
put	KVClient::Set	MooncakeStore::put	SET，可附带 PX
delete	KVClient::Del	MooncakeStore::remove	DEL
get_many	批量 Get	batch_get_into，第一阶段可循环 get	MGET 或 Pipeline
health_check	KVClient::HealthCheck	MooncakeStore::health_check	PING

Yuanrong 的 TTL、事务式 MSetTx、partial read，Mooncake 的 ReplicateConfig、buffer registration、batch zero-copy，以及 Redis 的 Pipeline、Lua、WAIT 等高级能力不进入最小公共接口。Provider 通过 ProviderCapabilities 声明能力，公共层只在能力可用时启用对应优化，不支持时回退到基础操作。

配置只负责选择 Provider：

storage:
  agfs:
    cache:
      enabled: true
      provider: mooncake  # mooncake | yuanrong | redis
      failure_mode: bypass
      operation_timeout_ms: 50
      sdk_concurrency: 16

启动时由 CacheProviderFactory 创建一个进程级 Arc<dyn CacheProvider>，所有允许缓存的 mount 共享该实例。第一阶段不支持运行中热切换；修改 provider 后重启 OpenViking 生效，可以避免旧 Provider 上仍在执行的请求、注册内存和 native handle 生命周期互相干扰。

结论：

1. CachedFileSystem 决定“如何缓存文件系统”，Provider 决定“缓存对象存放在哪里”，职责边界清晰。
2. 文件、目录、rename、写后失效和 subtree_generation 等一致性逻辑只在公共层实现，不分别复制到各个 Provider。
3. Yuanrong 和 Mooncake 的同步 native API 应通过 spawn_blocking 或专用线程池隔离；Redis 使用异步连接池并限制连接数和并发命令数。
4. Provider 必须把自身错误统一转换为 miss、timeout、unavailable、invalid data 和 internal error，cache miss 返回 Ok(None)，不能被当作系统故障。
5. native 依赖应通过 Cargo feature 和独立 adapter crate 隔离；配置只能选择当前构建产物已经编译并链接的 Provider。

接入 Yuanrong 后架构↑ 目录

Yuanrong 以 CacheProvider 实现接入，不作为新的文件系统 backend，也不在
CachedFileSystem 中增加 Yuanrong 分支。公共缓存层只依赖
Arc<dyn CacheProvider>，由启动配置决定装配 YuanrongProvider 还是其他
Provider。

接入过程分为八步：

第一步：建立 Yuanrong Provider 的 crate 和 feature 边界
第二步：准备 Yuanrong Worker 和 C++ SDK
第三步：实现稳定的 C ABI Bridge
第四步：实现 Rust FFI 和安全的 YuanrongClient
第五步：实现公共 CacheProvider 接口
第六步：接入配置和 CacheProviderFactory
第七步：由 CachedFileSystem 使用 Provider
第八步：完成降级、关闭和端到端验证

完成后，OpenViking 上层接口以及 LocalFS、S3FS、SQLFS 等 backend 均保持
不变。Yuanrong 的类型、错误码和 native handle 只存在于 Provider 实现内部。

接入 Yuanrong 后的整体架构

第一步：建立 Yuanrong Provider 的 crate 和 feature 边界↑ 目录

先把公共缓存逻辑和 Yuanrong native 依赖分开：

crates/ragfs/
  CachedFileSystem
  CacheProvider trait
  CacheProviderFactory
  CacheEnvelope / CachePolicy / inflight / metrics

crates/ragfs-cache-yuanrong-sys/
  Yuanrong C++ SDK 的 unsafe FFI 和 C ABI bridge

crates/ragfs-cache-yuanrong/
  YuanrongClient
  YuanrongProvider
  YuanrongConfig
  错误映射和并发控制

在 workspace 中增加可选 feature：

[features]
default = []
cache-yuanrong = ["dep:ragfs-cache-yuanrong"]

ragfs 核心不得暴露 DsClient、KVClient、C++ Status 或 native handle。
未编译 cache-yuanrong 时，如果配置了 provider: yuanrong，启动阶段应返回
明确的配置错误；不能运行到第一次 get 时才失败。

这一阶段的验收标准是：关闭 feature 时 RAGFS 可以完全不链接 Yuanrong
动态库，开启 feature 后 Factory 可以看到 yuanrong Provider 构造器。

第二步：准备 Yuanrong Worker 和 C++ SDK↑ 目录

首先部署 Yuanrong DataSystem 集群，并在运行 OpenViking 的节点上启动 Yuanrong worker。RAGFS 只连接本节点 worker，不直接管理 primary、replica 或 ETCD。

ETCD:
  保存 Yuanrong 集群元数据

本节点 Yuanrong worker:
  提供 RAGFS SDK 接入地址
  管理本地 DRAM / SSD 缓存
  miss 时从 primary 或远端 replica 拉取数据

RAGFS:
  只调用 Yuanrong C++ SDK 的 KV 接口

同时准备 Yuanrong C++ SDK 的以下构建输入：

SDK 头文件目录
SDK 动态库或静态库
worker host / port
运行时动态库搜索路径
SDK 与 worker 的兼容版本

先使用独立 C++ 示例连接本节点 worker，验证：

HealthCheck
Set(key, value)
Get(key)
Del(key)
批量 Get（若 SDK 版本支持）

只有该示例稳定通过后再进入 Rust 接入，避免把 worker 部署、动态库链接和 FFI
问题混在一起排查。

第三步：实现稳定的 C ABI Bridge↑ 目录

RAGFS 是 Rust 项目，而 Yuanrong 提供 C++ SDK。不要让 Rust 直接绑定 std::shared_ptr、C++ Status 等复杂类型，应先增加一层稳定的 C ABI。

新增底层 crate：

crates/ragfs-yuanrong-sys/
  build.rs
  src/lib.rs
  native/yuanrong_bridge.h
  native/yuanrong_bridge.cpp

build.rs 负责：

编译 yuanrong_bridge.cpp
添加 Yuanrong SDK include path
链接 Yuanrong SDK library
设置 C++ 标准和必要编译参数

C ABI 至少暴露：

typedef struct YrClientHandle YrClientHandle;

int yr_client_create(
    const char *host,
    uint16_t port,
    YrClientHandle **out);

int yr_client_get(
    YrClientHandle *client,
    const char *key,
    uint8_t **data,
    size_t *size);

int yr_client_set(
    YrClientHandle *client,
    const char *key,
    const uint8_t *data,
    size_t size);

int yr_client_delete(
    YrClientHandle *client,
    const char *key);

int yr_client_mget(/* keys and output array */);
int yr_client_health_check(YrClientHandle *client);

void yr_buffer_free(uint8_t *data);
void yr_client_destroy(YrClientHandle *client);
const char *yr_last_error(YrClientHandle *client);

C++ bridge 内部创建并持有 Yuanrong client：

struct YrClientHandle {
    std::shared_ptr<datasystem::DsClient> client;
    std::mutex error_mutex;
    std::string last_error;
};

接口映射关系：

yr_client_create -> 构造 DsClient 并连接本节点 worker
yr_client_get    -> client->KV()->Get
yr_client_set    -> client->KV()->Set
yr_client_delete -> client->KV()->Del
yr_client_mget   -> SDK 批量读取接口或受控并发 Get
yr_client_health_check -> SDK 健康检查接口
yr_client_destroy -> 释放 DsClient

C ABI 必须明确内存所有权：

Rust 传入的 key/value:
  只在调用期间有效，C++ 不长期持有指针

Get 返回的 buffer:
  由 C++ 分配
  Rust 复制或接管后必须调用 yr_buffer_free

错误信息:
  转换成稳定错误码
  yr_last_error 只用于补充诊断信息

这一阶段完成后，Rust 看到的只是普通 C 函数和 opaque handle，不感知 Yuanrong 的 C++ 类型。

第四步：实现 Rust FFI 和安全的 YuanrongClient↑ 目录

在 ragfs-yuanrong-sys/src/lib.rs 中声明 unsafe FFI：

unsafe extern "C" {
    fn yr_client_create(
        host: *const c_char,
        port: u16,
        out: *mut *mut YrClientHandle,
    ) -> c_int;

    fn yr_client_get(/* ... */) -> c_int;
    fn yr_client_set(/* ... */) -> c_int;
    fn yr_client_delete(/* ... */) -> c_int;
    fn yr_client_destroy(client: *mut YrClientHandle);
}

再新增安全封装 crate：

crates/ragfs-cache-yuanrong/
  src/client.rs
  src/provider.rs
  src/config.rs
  src/error.rs

YuanrongClient 管理 handle、错误转换和并发控制：

pub struct YuanrongClient {
    raw: NonNull<sys::YrClientHandle>,
    concurrency: Semaphore,
}

impl YuanrongClient {
    pub async fn connect(config: &YuanrongConfig) -> Result<Self>;
    pub async fn get(&self, key: &str) -> Result<Option<Bytes>>;
    pub async fn set(&self, key: &str, value: Bytes) -> Result<()>;
    pub async fn delete(&self, key: &str) -> Result<()>;
    pub async fn mget(&self, keys: &[String]) -> Result<Vec<Option<Bytes>>>;
    pub async fn health_check(&self) -> Result<()>;
}

如果 Yuanrong SDK 是同步 API，每次调用通过 spawn_blocking 隔离：

let permit = self.concurrency.acquire().await?;

let result = tokio::task::spawn_blocking(move || {
    unsafe { sys::yr_client_get(/* ... */) }
})
.await?;

drop(permit);

Semaphore 或固定大小 client pool 用于防止大量缓存请求占满 Tokio blocking pool。若 Yuanrong client 不是线程安全的，则每个 handle 同时只允许一个 SDK 调用，或者建立多个 handle 的 client pool。

安全客户端还必须完成统一错误分类：

Yuanrong key not found -> CacheError::Miss，Provider 返回 Ok(None)
连接失败 / worker 不可用 -> CacheError::Unavailable
调用超时 -> CacheError::Timeout
非法参数 -> CacheError::InvalidArgument
SDK 未知错误 -> CacheError::Internal

其中 miss 是正常控制流，不能计入 Provider 故障率。

第五步：实现公共 CacheProvider 接口↑ 目录

YuanrongProvider 组合安全客户端，并实现总体架构中定义的公共接口：

#[async_trait]
impl CacheProvider for YuanrongProvider {
    fn name(&self) -> &'static str { "yuanrong" }

    fn capabilities(&self) -> ProviderCapabilities {
        self.capabilities.clone()
    }

    async fn get(&self, key: &str) -> CacheResult<Option<Bytes>>;
    async fn put(
        &self,
        key: &str,
        value: Bytes,
        options: &PutOptions,
    ) -> CacheResult<()>;
    async fn delete(&self, key: &str) -> CacheResult<()>;
    async fn get_many(
        &self,
        keys: &[String],
    ) -> CacheResult<Vec<Option<Bytes>>>;
    async fn health_check(&self) -> CacheResult<()>;
}

操作映射如下：

CacheProvider 操作	Yuanrong SDK 操作	实现要求
get	KVClient::Get	not found 映射为 Ok(None)
put	KVClient::Set	成功后才返回，不能在 SDK 调用前报告成功
delete	KVClient::Del	key 不存在按幂等成功处理
get_many	批量 Get	SDK 不支持时使用受控并发 Get
health_check	HealthCheck	用于启动探测和熔断恢复

Yuanrong 的 TTL、partial read、事务式批量写等能力通过
ProviderCapabilities 声明。CacheEnvelope、文件和目录 key、逻辑过期时间以及
subtree_generation 均由 CachedFileSystem 处理，不在 Provider 中重复实现。

第六步：接入配置和 CacheProviderFactory↑ 目录

增加 Provider 配置：

storage:
  agfs:
    cache:
      enabled: true
      provider: yuanrong
      failure_mode: bypass
      operation_timeout_ms: 50
      sdk_concurrency: 16
      yuanrong:
        host: 127.0.0.1
        port: 31501

Factory 只在启动时选择一次：

CacheProviderFactory::create(config)
  -> provider == yuanrong
  -> 校验 cache-yuanrong feature
  -> 解析 YuanrongConfig
  -> YuanrongClient::connect
  -> health_check
  -> Arc<YuanrongProvider>
  -> 返回 Arc<dyn CacheProvider>

进程内所有可缓存 mount 共享同一个：

Arc<dyn CacheProvider>

初始化或健康检查失败时：

strict 模式:
  RAGFS 启动失败

bypass 模式:
  记录错误
  使用 DisabledCacheProvider 或不包装 backend
  OpenViking 继续访问原 backend

第一阶段不支持运行时热切换 Provider。修改配置后重启 OpenViking，避免旧
native handle、阻塞任务和新 Provider 生命周期交叠。

第七步：由 CachedFileSystem 使用 Provider↑ 目录

RAGFSBindingClient 的启动顺序调整为：

创建 Tokio runtime
  -> 读取 cache 配置
  -> CacheProviderFactory::create
  -> 创建 MountableFS(provider, cache_config)
  -> 注册并 mount LocalFS / S3FS / SQLFS

mount 包装流程保持 Provider 无关：

plugin.initialize(config)
  -> Backend FileSystem
  -> CachedFileSystem(backend, Arc<dyn CacheProvider>)
  -> StatsWrappedFS
  -> MountInfo.fs

let backend = plugin.initialize(config.clone()).await?;

let fs: Box<dyn FileSystem> = if cache_config.enabled {
    Box::new(CachedFileSystem::new(
        backend,
        Arc::clone(&self.cache_provider),
        CacheNamespace {
            mount: normalized_path.clone(),
            account: config.account.clone(),
        },
        cache_config.policy.clone(),
    ))
} else {
    backend
};

let wrapped_fs = StatsWrappedFS::new(fs);

对于不适合缓存的插件，可以在 mount 级别关闭：

localfs / s3fs / sqlfs:
  根据配置启用缓存

queuefs:
  默认不包装

serverinfofs:
  默认不包装

完成该步骤后，MountableFS 仍然只调用 dyn FileSystem，不知道内部是否启用了缓存。

公共层保存的字段为：

pub struct CachedFileSystem {
    backend: Box<dyn FileSystem>,
    provider: Arc<dyn CacheProvider>,
    namespace: CacheNamespace,
    policy: CachePolicy,
    locks: PathLockManager,
}

读路径调用公共 Provider 原语：

read(path)
  -> cache_policy(path, Read)
  -> bypass: backend.read
  -> provider.get(file_key)
  -> hit 且 generation 有效: 返回缓存
  -> miss/stale: backend.read
  -> provider.put(file_key, CacheEnvelope)
  -> 返回

read_dir(path)
  -> cache_policy(path, ReadDir)
  -> provider.get(dir_key)
  -> hit 且 generation 有效: 返回 raw entries
  -> miss/stale: backend.read_dir
  -> provider.put(dir_key, CacheEnvelope)
  -> 返回

变更路径也不感知 Yuanrong：

write/remove/rename/mkdir/remove_all
  -> 获取本进程 path/subtree lock
  -> 先执行 backend 变更
  -> backend 成功后调用 provider.put/delete
  -> remove_all/目录 rename 必要时 bump subtree_generation
  -> 返回

Yuanrong 自身负责 key 在 primary 和 replica 之间的数据一致性；RAGFS 公共层负责
文件系统语义上的 key 选择、写后失效、目录失效和回源顺序，两者不能混为一层。

第八步：完成关闭、降级和端到端验证↑ 目录

关闭时按以下顺序释放：

停止 PrefetchExecutor
  -> 等待有限时间内的后台任务
  -> drop CachedFileSystem
  -> drop Arc<YuanrongProvider>
  -> 释放 YuanrongClient handles
  -> 卸载 backend
  -> 关闭 Tokio runtime

至少需要验证以下链路：

1. Yuanrong 可用，首次 read miss 后回填，第二次 read hit
2. Yuanrong 不可用，read 自动回源 backend
3. write 后不会继续读取旧 file_key
4. remove 后 file_key 和 parent dir_key 失效
5. rename 后 old/new path 不返回历史缓存
6. remove_all 后残留子孙 key 因 subtree_generation 失效
7. queuefs、锁文件、控制文件始终 bypass
8. 进程关闭时 Yuanrong handle 和后台任务正常释放
9. 未编译 cache-yuanrong 时配置 yuanrong 能在启动阶段报错
10. 同一个 CachedFileSystem 测试集可通过 mock、Yuanrong 两种 Provider

最终调用链：

OpenViking Python
  -> PyO3 RAGFSBindingClient
  -> MountableFS
  -> StatsWrappedFS
  -> CachedFileSystem
       -> cache hit:
            CacheProvider
            -> YuanrongProvider
            -> YuanrongClient
            -> Rust FFI
            -> C ABI / C++ Bridge
            -> Yuanrong C++ SDK
            -> 本节点 Yuanrong worker

       -> cache miss / 变更:
            Backend FileSystem
            -> LocalFS / S3FS / SQLFS
            -> 回填或失效 Yuanrong cache key

经过以上八步，接入关系可以概括为：

Yuanrong 负责缓存数据存取和 key 级副本一致性；
CachedFileSystem 负责何时读缓存、何时回源、何时失效；
YuanrongProvider 只负责把公共缓存原语映射到 Yuanrong SDK；
原始 FileSystem 插件继续负责访问真实 backend；
OpenViking 和 RAGFSBindingClient 的文件系统 API 保持不变。

接入 Mooncake 架构↑ 目录

Mooncake 与 Yuanrong 使用同一个 CacheProvider 扩展点。区别仅在 Provider 内部：
Mooncake 可以直接使用官方 Rust crate mooncake_store，不需要额外编写
C ABI bridge，但仍需链接 Mooncake Store 和 Transfer Engine 的 native 库。

接入过程分为九步：

第一步：固定 Mooncake 版本和部署形态
第二步：增加可选 crate 和 Cargo feature
第三步：构建并链接 Mooncake native 库
第四步：定义 MooncakeConfig 并完成 setup
第五步：封装同步 Rust API 和并发控制
第六步：实现 MooncakeProvider
第七步：注册到 CacheProviderFactory
第八步：接入公共 CachedFileSystem
第九步：分阶段优化并完成验证

第一步：固定 Mooncake 版本和部署形态↑ 目录

第一阶段固定一个经过验证的 Mooncake Git commit，不直接跟随 main。部署至少
包括：

Mooncake Master
Metadata Service（etcd 或 Redis 等受支持实现）
每个 OpenViking 节点可访问的 Mooncake Store / Transfer Engine
OpenViking 进程内的 MooncakeProvider

先使用 TCP 协议完成端到端验证，再在真实硬件环境切换 RDMA 或 UB。协议切换只
修改 Mooncake 配置，不改变 Provider 接口和 CachedFileSystem。

第二步：增加可选 crate 和 Cargo feature↑ 目录

新增独立 adapter crate：

crates/ragfs-cache-mooncake/
  Cargo.toml
  src/config.rs
  src/client.rs
  src/provider.rs
  src/error.rs

依赖官方 Rust crate，并固定 revision：

[dependencies]
mooncake_store = {
  git = "https://github.com/kvcache-ai/Mooncake.git",
  rev = "<verified-commit>",
  optional = true
}

[features]
cache-mooncake = ["dep:ragfs-cache-mooncake"]

若构建环境不允许 Cargo 拉取 Git 依赖，可将同一 revision 作为 source archive
或 submodule 固定在内部依赖仓库中。无论采用哪种方式，都要记录 Mooncake
commit、C++ native 库版本和 Rust crate 版本的对应关系。

第三步：构建并链接 Mooncake native 库↑ 目录

Mooncake Rust crate 是对 C/C++ Store API 的安全封装，build.rs 仍需找到
native 头文件和库。使用 Mooncake CMake 构建：

cmake -S . -B build \
  -DWITH_STORE=ON \
  -DWITH_STORE_RUST=ON
cmake --build build --target build_mooncake_store_rust -j

在 RAGFS 构建环境中设置并校验：

MOONCAKE_BUILD_DIR
MOONCAKE_STORE_LIB_DIR
MOONCAKE_STORE_INCLUDE_DIR
LIBRARY_PATH
LD_LIBRARY_PATH

除 mooncake_store 和 transfer_engine 外，还要准备其依赖的 glog、gflags、
numa、curl、ibverbs、xxhash、jsoncpp、CacheLib 相关库以及 C++ runtime。

CI 应增加一个 cache-mooncake native 构建任务。链接检查失败时立即停止构建，
不要在运行阶段静默降级。

第四步：定义 MooncakeConfig 并完成 setup↑ 目录

配置需要覆盖 MooncakeStore::setup 的必要参数：

storage:
  agfs:
    cache:
      enabled: true
      provider: mooncake
      failure_mode: bypass
      operation_timeout_ms: 50
      sdk_concurrency: 16
      mooncake:
        local_hostname: 10.0.0.12
        metadata_server: etcd://10.0.0.20:2379
        master_server_addr: 10.0.0.21:50051
        protocol: tcp
        device_name: ""
        global_segment_size: 17179869184
        local_buffer_size: 4294967296
        replica_num: 2

实现强类型配置：

pub struct MooncakeConfig {
    pub local_hostname: String,
    pub metadata_server: String,
    pub master_server_addr: String,
    pub protocol: String,
    pub device_name: String,
    pub global_segment_size: usize,
    pub local_buffer_size: usize,
    pub replica_num: usize,
    pub sdk_concurrency: usize,
}

启动时按顺序执行：

MooncakeStore::new()
  -> store.setup(...)
  -> store.health_check()
  -> 构造 MooncakeClient

hostname、协议、segment 大小或服务地址无效时直接返回 Provider 初始化错误。

第五步：封装同步 Rust API 和并发控制↑ 目录

Mooncake 官方 Rust API 是同步接口。MooncakeStore 可跨线程共享，但不能直接
在 Tokio executor 线程上执行阻塞的远程传输：

pub struct MooncakeClient {
    store: Arc<MooncakeStore>,
    concurrency: Arc<Semaphore>,
}

每次操作先获取 permit，再进入 spawn_blocking：

let permit = self.concurrency.clone().acquire_owned().await?;
let store = Arc::clone(&self.store);
let key = key.to_owned();

tokio::task::spawn_blocking(move || {
    let _permit = permit;
    store.get(&key)
})
.await?

Provider 层统一施加 operation_timeout_ms。超时只停止等待，native 调用可能仍在
blocking 线程中运行，因此并发上限必须保守设置，避免故障时累积不可取消调用。

第六步：实现 MooncakeProvider↑ 目录

MooncakeProvider 实现与 YuanrongProvider 相同的公共接口：

pub struct MooncakeProvider {
    client: Arc<MooncakeClient>,
    replicate: ReplicateConfig,
}

操作映射和注意点如下：

CacheProvider 操作	Mooncake Rust API	第一阶段实现
get	is_exist、get	先判断存在，再读取并映射为 Option<Bytes>
put	put	传入 ReplicateConfig，成功后返回
delete	remove	key 不存在按幂等成功处理
get_many	get / batch_get_into	先受控并发循环 get
health_check	health_check	启动探测和熔断恢复

get 不应只调用 get_size 判断 miss，因为负值可能同时表示不存在或内部错误。
建议先调用 is_exist，存在后再调用 get；调用间对象被删除时，将第二次返回的
not found 继续映射为 Ok(None)。

Mooncake 当前 Rust 接口没有通用的对象级 TTL。Provider 应在 capabilities 中声明
native_ttl = false，由 CacheEnvelope 保存逻辑过期时间，读取过期对象时按 miss
处理并异步 remove。

put 使用不可变对象语义：同一个 key 的新内容只在公共层完成 backend 变更和旧
key 失效后写入。MooncakeProvider 不实现文件系统版本、目录 generation 或 rename。

第七步：注册到 CacheProviderFactory↑ 目录

在 Factory 中增加 feature-gated 分支：

match config.provider.as_str() {
    "yuanrong" => create_yuanrong_provider(config).await,
    "mooncake" => create_mooncake_provider(config).await,
    other => Err(CacheConfigError::UnknownProvider(other.into())),
}

create_mooncake_provider 负责：

校验 cache-mooncake feature
  -> 解析 MooncakeConfig
  -> MooncakeStore::new + setup
  -> health_check
  -> 创建 Arc<MooncakeProvider>
  -> 返回 Arc<dyn CacheProvider>

公共层不得出现 if provider == "mooncake"。Provider 选择只发生在 Factory，
高级能力通过 ProviderCapabilities 判断。

第八步：接入公共 CachedFileSystem↑ 目录

MooncakeProvider 创建后，挂载流程和 Yuanrong 完全相同：

plugin.initialize(config)
  -> Backend FileSystem
  -> CachedFileSystem(
       backend,
       Arc<dyn CacheProvider> = Arc<MooncakeProvider>
     )
  -> StatsWrappedFS
  -> MountInfo.fs

文件和目录读：

生成公共 file_key / dir_key
  -> provider.get
  -> hit: 解码 CacheEnvelope 并校验 generation
  -> miss: backend 回源
  -> provider.put 回填

写、删除和 rename：

获取本进程路径锁
  -> 先完成 backend 变更
  -> provider.delete 旧 file_key / dir_key
  -> provider.put 可安全立即回填的对象
  -> 必要时 bump subtree_generation

因此从 Yuanrong 切换到 Mooncake 不修改 CachedFileSystem、backend plugin 或
OpenViking API，只修改配置并使用包含对应 feature/native 库的构建产物。

第九步：分阶段优化并完成验证↑ 目录

第一阶段优先保证基础接口、错误映射和失效顺序正确：

TCP 协议
普通 put/get/remove
受控并发 get_many
逻辑 TTL
故障 bypass
完整文件和目录一致性测试

第二阶段再启用 Mooncake 的零拷贝和批量能力：

register_buffer / unregister_buffer
put_from / get_into
batch_put_from / batch_get_into
RDMA 或 UB

注册内存必须封装成 RAII RegisteredBuffer，确保 drop 时调用
unregister_buffer。batch_get_into 要求调用方预先知道对象大小并准备 buffer，
可在 CacheEnvelope 大小元数据稳定后再接入，不能为了批量读取破坏公共 value
格式。

至少验证：

1. Mooncake 可用时首次 miss 回填、第二次 hit
2. 不存在 key 返回 Ok(None)，内部错误不会被误判为 miss
3. Mooncake 不可用时按 failure_mode 回源或失败
4. write/remove/rename 后不返回旧文件和旧目录
5. remove_all 后残留子孙对象被 subtree_generation 拒绝
6. 多个 mount 共享同一个 MooncakeProvider
7. 高并发请求不阻塞 Tokio executor，Semaphore 上限生效
8. 未编译 cache-mooncake 时配置 mooncake 在启动阶段报错
9. shutdown 先停止后台任务，再 drop MooncakeStore
10. TCP 测试通过后，在真实 RDMA/UB 环境验证传输和 NUMA 配置

Mooncake 接入后的职责边界为：

CachedFileSystem:
  文件系统缓存语义、一致性、序列化、请求合并和指标

MooncakeProvider:
  公共缓存原语到 Mooncake Rust API 的映射
  阻塞隔离、并发限制、错误映射和 ReplicateConfig

Mooncake:
  对象存储、跨节点数据传输、副本和底层介质管理

接入 Redis 架构↑ 目录

Redis 使用与 Yuanrong、Mooncake 相同的 CacheProvider 扩展点。公共
CachedFileSystem、CacheEnvelope、文件与目录一致性、mount 包装和故障
bypass 均复用前文，本节只描述 Redis adapter 的实现差异。

接入过程分为六步：

第一步：增加 Redis adapter crate 和 feature
第二步：定义连接与部署配置
第三步：实现 RedisProvider
第四步：注册到 CacheProviderFactory
第五步：处理 Redis 特有约束
第六步：完成验证和上线配置

第一步：增加 Redis adapter crate 和 feature↑ 目录

新增纯 Rust adapter：

crates/ragfs-cache-redis/
  Cargo.toml
  src/config.rs
  src/provider.rs
  src/error.rs

选择支持 Tokio、连接池、Cluster 和 TLS 的成熟 Redis Rust 客户端，并固定版本：

[features]
cache-redis = ["dep:ragfs-cache-redis"]

RedisProvider 不链接 native SDK，也不使用 spawn_blocking。关闭
cache-redis feature 时，配置 provider: redis 应在启动阶段返回明确错误。

第二步：定义连接与部署配置↑ 目录

配置示例：

storage:
  agfs:
    cache:
      enabled: true
      provider: redis
      failure_mode: bypass
      operation_timeout_ms: 20
      redis:
        mode: standalone       # standalone | sentinel | cluster
        endpoints:
          - redis://10.0.0.30:6379
        username: ""
        password_env: RAGFS_REDIS_PASSWORD
        pool_size: 32
        connect_timeout_ms: 1000
        command_timeout_ms: 20
        key_prefix: ragfs-cache
        default_ttl_seconds: 3600
        read_from_replica: false

密码通过环境变量或 secret manager 注入，不直接写入配置文件。第一阶段建议从
standalone 或 Sentinel primary-only 模式开始；只有容量或吞吐确有需要时再启用
Cluster。

启动顺序为：

解析 RedisConfig
  -> 创建异步连接池或 Cluster client
  -> PING
  -> 创建 Arc<RedisProvider>

第三步：实现 RedisProvider↑ 目录

RedisProvider 直接把公共缓存原语映射到 Redis 命令：

CacheProvider 操作	Redis 命令	实现要求
get	GET	nil 映射为 Ok(None)，其他错误分类为 timeout/unavailable/internal
put	SET key value PX ttl	有 TTL 时一次命令完成 value 和过期时间写入
delete	DEL	返回 0 也按幂等成功处理
get_many	MGET 或 Pipeline GET	保持输入顺序并逐项返回 Option<Bytes>
health_check	PING	用于启动探测和熔断恢复

建议结构：

pub struct RedisProvider {
    client: RedisClient,
    key_prefix: String,
    default_ttl: Duration,
    operation_timeout: Duration,
}

put 优先使用单条带 PX 的 SET，避免 SET 成功而 PEXPIRE 失败。Provider
只处理 Redis key 前缀、命令调用、超时和错误映射，不解析文件路径或
CacheEnvelope。

第四步：注册到 CacheProviderFactory↑ 目录

在既有 Factory 中增加一个分支：

match config.provider.as_str() {
    "yuanrong" => create_yuanrong_provider(config).await,
    "mooncake" => create_mooncake_provider(config).await,
    "redis" => create_redis_provider(config).await,
    other => Err(CacheConfigError::UnknownProvider(other.into())),
}

create_redis_provider 校验 feature 和配置，建立连接并完成 PING，然后返回
Arc<dyn CacheProvider>。后续 mount、读 miss 回填和写后失效全部沿用前文公共
流程，不新增 Redis 专用文件系统分支。

第五步：处理 Redis 特有约束↑ 目录

Redis adapter 需要额外处理以下边界：

• 读取 primary：默认 read_from_replica: false，避免异步复制延迟导致写后读到
  旧缓存。若启用 replica read，只能作为允许短暂陈旧的性能模式。
• Cluster hash slot：MGET 要求 key 位于同一 slot。第一阶段可对不同 slot
  使用 Pipeline；需要原子多 key 操作时再为同一命名空间设计 {hash_tag}。
• 批量限制：对 MGET、Pipeline 和批量 DEL 设置 key 数与总字节上限，避免
  单个请求占满连接或产生超大响应。
• 故障切换：连接重置、MOVED/ASK、超时或 Sentinel/Cluster 选主期间触发
  短暂 bypass；恢复探测成功后再重新启用缓存。
• 事件通知：Keyspace Notification、Pub/Sub 或 Streams 只能用于优化，不能
  成为缓存正确性的唯一依据。
• 可靠性增强：缓存默认不要求 WAIT/WAITAOF。若需要降低 failover 丢失失效
  命令的概率，可作为 RedisProvider 可选写策略，但应接受额外写延迟。

第六步：完成验证和上线配置↑ 目录

除公共 Provider 契约测试外，Redis 至少需要验证：

1. GET nil 正确映射为 cache miss
2. SET PX 写入后 TTL 生效，过期后自动回源
3. DEL 对不存在 key 保持幂等
4. MGET/Pipeline 结果顺序与输入 key 一致
5. write/remove/rename 后不返回旧文件或旧目录
6. 连接池耗尽和命令超时不会阻塞 RAGFS
7. Redis 不可用或 failover 时按 failure_mode bypass
8. Cluster 模式正确处理跨 slot 批量读取和 MOVED/ASK
9. 密码、TLS 和 ACL 配置错误在启动时可诊断
10. 未编译 cache-redis 时配置 redis 在启动阶段报错

上线初期建议使用 primary-only、短命令超时、有限连接池、allkeys-lfu 或
allkeys-lru，并监控 hit rate、命令 P99、连接池等待、超时、eviction、
keyspace miss 和 bypass 次数。

Redis 接入后的职责边界为：

CachedFileSystem:
  文件系统缓存语义、一致性、回源、失效和请求合并

RedisProvider:
  GET / SET / DEL / MGET / PING
  连接池、超时、错误映射、Cluster 重定向和可选可靠性策略

Redis:
  KV 存储、TTL、内存淘汰、复制、持久化和故障切换

缓存对象↑ 目录

文件缓存↑ 目录

文件 key：

file:{namespace}:{account}:{hash(path)}

文件 value 将内容和元数据打包为一个整体对象：

{
  "kind": "file",
  "path": "/local/account/resources/demo/.overview.md",
  "data": "<bytes>",
  "meta": {
    "size": 123,
    "mode": 420,
    "mtime_ns": 10000,
    "digest": "sha256:...",
    "subtree_deps": [
      {"path": "viking://resources/demo", "generation": "g42"}
    ]
  },
  "prefetch": {
    "immediate": [],
    "low_priority": []
  }
}

单写者场景不需要额外维护 ver_key。文件内容一致性由 file_key 的 set/delete 和必要的 subtree_generation 校验保证。

目录缓存↑ 目录

目录 key：

dir:{namespace}:{account}:{hash(path)}

目录 value 缓存 backend 原始 read_dir entries，而不是权限过滤后的最终结果：

{
  "kind": "dir",
  "path": "/local/account/resources/demo",
  "entries": [
    {"name": ".abstract.md", "is_dir": false, "size": 123, "mtime_ns": 10000},
    {"name": "docs", "is_dir": true, "size": 0, "mtime_ns": 10001}
  ],
  "meta": {
    "subtree_deps": [
      {"path": "viking://resources/demo", "generation": "g42"}
    ]
  },
  "prefetch": {
    "immediate": [
      "file:{namespace}:{account}:{hash('/local/account/resources/demo/docs/.abstract.md')}"
    ],
    "low_priority": [
      "file:{namespace}:{account}:{hash('/local/account/resources/demo/docs/.overview.md')}",
      "dir:{namespace}:{account}:{hash('/local/account/resources/demo/docs')}"
    ]
  }
}

缓存 raw entries 的好处是同一份目录缓存可以服务：

• ls(original)
• ls(agent)
• tree
• glob
• grep 的文件收集阶段
• rm/mv 前的 URI 收集

权限过滤仍在 OpenViking / VikingFS 层执行。

子树 Generation↑ 目录

子树 generation key：

subtree:{namespace}:{account}:{hash(scope)}

subtree_generation 用于处理 remove_all 和目录 rename。即使只有单 OpenViking 进程，RAGFS 也不一定知道 Yuanrong 中残留了哪些子孙缓存 key，所以仍然需要它。

remove_all /a 后：
  file_key(/a/b.txt) 可能仍残留在 Yuanrong
  但它 value 记录的 generation 快照已经过期
  后续 read /a/b.txt 会校验失败并回源

建议按 OpenViking 语义边界设置：

viking://resources/<resource>
viking://user/<space>/...
viking://agent/<space>/...
viking://session/<session_id>/...
viking://temp/...

这样读缓存时只需要校验少量 generation key。

缓存对象策略↑ 目录

RAGFS 需要在读写路径前执行 cache_policy(path, op, caller_context)。Yuanrong 适合缓存稳定值，不适合缓存动作、权限判断、锁状态和瞬时控制面。

Cacheable:
  普通小文件
  .abstract.md
  .overview.md
  backend raw read_dir entries
  resource/session/memory 语义边界下的摘要类文件

BypassAlways:
  锁文件，例如 .path.ovlock、*.lock、*.lck
  控制文件，例如 enqueue/dequeue/peek/ack
  heartbeat、lease、cursor、offset、pid
  读写有副作用的 queuefs 或控制面 namespace

BypassIfPermissionDependent:
  结果依赖 caller、role、ACL、临时授权或 agent context 的路径

ShortNegativeOnly:
  可能稍后生成的摘要文件 NotFound

NoPrefetch:
  权限敏感目录
  高动态目录
  控制面目录

权限不确定的对象不能缓存权限过滤后的最终结果。如果 backend raw entries 本身也依赖调用者权限，该路径应该 bypass。

锁文件和控制文件必须强制 bypass。锁文件表达当前瞬时状态，控制文件通常带有操作语义或读副作用，不能用普通文件缓存语义处理。

NotFound 负缓存需要谨慎。.abstract.md、.overview.md 等文件可能稍后生成，默认不缓存 NotFound；确需保护 backend 时，只允许极短 TTL，例如 100ms 到 1s。

单写者一致性保证↑ 目录

单 OpenViking 进程下，不需要复杂分布式一致性协议，也不需要多节点写锁。RAGFS 只需要维护三类失效：

file_key:
  文件内容缓存

dir_key:
  目录 entries 缓存

subtree_generation:
  remove_all / 目录 rename 时让残留子孙缓存失效

推荐变更顺序：

1. 获取本进程内 path/subtree 操作锁
2. 执行 backend 变更
3. 更新或删除 Yuanrong cache key
4. 必要时 bump subtree_generation
5. 变更返回

如果 cache 维护失败，可以选择两种模式：

严格模式:
  cache set/delete/bump 失败则变更返回错误

实用模式:
  backend 已成功则返回成功
  affected path/scope 进入短期 cache bypass
  后台重试 set/delete/bump

如果要保证进程重启后也不读旧缓存，关键变更建议使用严格模式，尤其是 delete、rename、remove_all。

文件场景↑ 目录

文件读↑ 目录

read_file(path)
  1. 判断 cache_policy
     bypass -> backend.read

  2. get file_key(path)

  3. hit:
       校验 value.meta.subtree_deps
       generation 一致 -> 返回 data
       generation 不一致 -> delete file_key，回源 backend

  4. miss:
       backend.read + stat
       构造 file value，记录当前 subtree_generation 快照
       set file_key
       返回 data

保证：

如果文件没有被 subtree 删除或目录 rename 影响，
命中 file_key 可以直接返回。

如果 remove_all / 目录 rename 后残留旧 file_key，
generation 校验会让它失效。

文件写与更新↑ 目录

文件创建和覆盖写统一视为 write_file(path, data)：

write_file(path, data)
  1. 获取 path 写锁
  2. backend.write(path, data)
  3. 如果文件可缓存:
       set file_key(path, new_value)
     否则:
       delete file_key(path)
  4. delete dir_key(parent(path))
  5. 返回成功

保证：

write 返回后：
  file_key 要么是新内容，要么不存在
  parent dir_key 不会继续展示旧目录快照

如果更新的是 .abstract.md 或 .overview.md，直接更新对应 file_key 即可。tree(agent) / ls(agent) 通过 dir_key + mget(child .abstract.md) 读取摘要，不再维护组合缓存。

文件删除↑ 目录

remove_file(path)
  1. 获取 path 写锁
  2. backend.remove(path)
  3. delete file_key(path)
  4. delete dir_key(parent(path))
  5. 返回成功

保证：

remove 返回后：
  read_file(path) 不会从 Yuanrong 读到旧文件
  read_dir(parent) 不会继续展示该文件

文件 Rename↑ 目录

文件 rename 既包括同目录改名，也包括跨目录移动：

rename_file(old_path, new_path)
  1. 获取 old_path + new_path 写锁
  2. backend.rename(old_path, new_path)
  3. delete file_key(old_path)
  4. delete file_key(new_path)
  5. delete dir_key(parent(old_path))
  6. delete dir_key(parent(new_path))
  7. 返回成功

删除 new_path 的原因是目标路径历史上可能存在旧缓存。rename 返回后，下一次读 new_path 应回源 backend 并重建缓存。

目录场景↑ 目录

目录读↑ 目录

read_dir(path)
  1. 判断 cache_policy
     bypass -> backend.read_dir

  2. get dir_key(path)

  3. hit:
       校验 value.meta.subtree_deps
       generation 一致 -> 返回 raw entries
       generation 不一致 -> delete dir_key，回源 backend

  4. miss:
       backend.read_dir(path)
       构造 dir value，记录当前 subtree_generation 快照
       set dir_key(path)
       返回 raw entries

保证：

dir_key 只表示目录子项集合快照。
任何影响子项集合的变更都必须删除对应 dir_key。
权限过滤后的最终结果不缓存。

目录创建↑ 目录

mkdir(path)
  1. 获取 path + parent(path) 写锁
  2. backend.mkdir(path)
  3. 初始化 subtree_generation(path)
  4. delete dir_key(parent(path))
  5. delete dir_key(path)
  6. 返回成功

保证：

mkdir 返回后：
  parent 目录缓存不会继续显示旧 entries
  path 自身不会复用历史空目录缓存

目录删除↑ 目录

空目录删除：

remove_dir(path)
  1. 获取 path + parent(path) 写锁
  2. backend.remove_dir(path)
  3. delete dir_key(path)
  4. delete dir_key(parent(path))
  5. 可选 bump subtree_generation(path)
  6. 返回成功

递归删除：

remove_all(path)
  1. 获取 subtree 写锁
  2. backend.remove_all(path)
  3. bump subtree_generation(path)
  4. delete dir_key(path)
  5. delete dir_key(parent(path))
  6. 返回成功

保证：

remove_all 返回后：
  self/parent 目录缓存被删除
  子树内部残留 file_key/dir_key 因 generation 过期失效

目录 Rename↑ 目录

目录 rename 是整棵子树路径切换：

rename_dir(old_path, new_path)
  1. 获取 subtree move lock
  2. backend.rename(old_path, new_path)
  3. bump subtree_generation(old_path)
  4. bump subtree_generation(new_path)
  5. delete dir_key(old_path)
  6. delete dir_key(new_path)
  7. delete dir_key(parent(old_path))
  8. delete dir_key(parent(new_path))
  9. 返回成功

保证：

old_path:
  残留子孙缓存因 generation 过期而失效

new_path:
  历史目标路径缓存因 generation 过期而失效

old/new parent:
  父目录 entries 被删除，后续回源重建

缓存击穿与请求合并↑ 目录

当大量并发请求同时读取同一个尚未缓存的文件或目录时，如果每个请求都独立回源，会形成缓存击穿：

100 个请求同时读取同一个 file_key
  -> 100 次 cache miss
  -> 100 次 backend.read
  -> 100 次 cache.set

单 OpenViking 进程可以在 CachedFileSystem 内维护进程级 inflight 表，将相同 cache key 的并发 miss 合并为一次 backend 请求：

pub struct CachedFileSystem {
    backend: Box<dyn FileSystem>,
    provider: Arc<dyn CacheProvider>,
    inflight: InflightMap,
    mutation_seq: MutationSequence,
}

type InflightMap = ConcurrentMap<CacheKey, SharedFuture<BackendLoadResult>>;

inflight 的 key 使用规范化后的 file_key 或 dir_key。第一阶段只合并可缓存的小文件全量读取和 read_dir，不合并不同 offset/size 的 range read。

Leader 与 Follower↑ 目录

首个发现 cache miss 且成功创建 inflight[key] 的请求成为 leader，负责回源和回填。后续读取相同 key 的请求成为 follower，等待 leader 的共享结果：

read_file(path)
  1. get file_key
  2. cache hit:
       返回缓存
  3. cache miss:
       原子查找或创建 inflight[file_key]

       创建成功 -> leader:
         记录 mutation_seq(path)
         backend.read(path)
         校验 subtree_generation
         校验 mutation_seq(path) 未变化
         校验通过 -> set file_key
         发布共享结果
         删除 inflight[file_key]

       已经存在 -> follower:
         等待 inflight[file_key] 的共享结果
         直接复用 leader 返回的数据或错误

目录读取使用相同机制：

read_dir(path)
  -> miss 时查找或创建 inflight[dir_key]
  -> leader 只执行一次 backend.read_dir
  -> follower 共享同一份 raw entries
  -> leader 校验 generation 和 mutation_seq 后回填 dir_key

inflight 只合并正在进行的请求，不保存长期结果。请求完成后仍由 Yuanrong 承担正常缓存命中。

与文件变更的并发关系↑ 目录

请求合并不能让较早开始的读请求在写、删除或 rename 完成后重新写入旧缓存。为此，RAGFS 在进程内为路径维护单调递增的 mutation_seq：

leader 开始回源:
  start_seq = mutation_seq(path)

write/delete/rename:
  backend 变更成功
  -> increment mutation_seq(affected paths)
  -> 标记或移除 affected inflight entries
  -> 更新或删除缓存

leader 回填前:
  current_seq = mutation_seq(path)
  current_seq == start_seq:
    允许回填
  current_seq != start_seq:
    放弃回填

mutation_seq 必须在 backend 变更成功后立即递增，早于 Yuanrong set/delete，从而关闭“Backend 已变化但旧 leader 仍可回填”的竞态窗口。变更操作还需要让 affected key 的旧 inflight 条目失效；变更后到达的新读请求不能加入旧 leader，而应重新检查缓存并创建新一轮 inflight。

inflight 条目需要携带创建时的 start_seq。follower 加入前和接受共享结果前都要比较当前 mutation_seq：

current_seq == inflight.start_seq:
  可以加入或接受共享结果

current_seq != inflight.start_seq:
  不加入或不接受旧结果
  重新执行 cache get / inflight 竞争

已经在变更前开始等待的请求与变更操作存在时间重叠，可以共享该轮读取结果；变更返回后新开始的请求必须看到新缓存或重新回源，不能复用旧 inflight 结果。

对于目录操作，mutation_seq 需要覆盖目录自身及受影响的父目录；remove_all 和目录 rename 仍通过 subtree_generation 处理残留子孙缓存。mutation_seq 用于阻止进程内正在执行的旧读取回填，subtree_generation 用于使 Yuanrong 中已经存在的旧子孙缓存失效，两者职责不同。

错误、超时与清理↑ 目录

leader 的成功和失败结果都需要通知所有 follower，并确保 inflight 条目最终被删除：

leader 成功:
  发布 data/entries
  删除 inflight key

leader backend 失败:
  向 follower 发布同一个 backend error
  删除 inflight key

leader cache.set 失败:
  返回已读取的 backend 数据
  记录 cache_set_failed
  删除 inflight key

leader panic / task cancel:
  通过 RAII guard 删除 inflight key
  follower 收到取消或内部错误

leader 必须设置 backend 请求超时，避免一个挂死请求长期占用 inflight。follower 可以设置等待超时，但等待超时后不应立即对同一个 key 再发起独立回源，否则会重新形成击穿；应返回超时错误，或者等待原 leader 的全局截止时间结束后再参与下一轮 leader 竞争。

单个 follower 被取消不能取消 leader，因为 leader 可能仍被其他 follower 等待。只有 leader 自身达到全局超时、Backend 返回或系统关闭时，才结束该 inflight 请求。

容量与观测↑ 目录

inflight 表需要限制最大 key 数，防止大量不同 key 的 miss 占用过多内存：

inflight key 数未达上限:
  正常创建 leader

inflight key 数达到上限:
  不记录新的 inflight
  请求按受控并发直接回源，或进入全局等待队列

建议记录：

inflight_leader_total
inflight_follower_total
inflight_active
inflight_wait_latency
inflight_backend_saved
inflight_timeout
inflight_fill_aborted_by_mutation

请求合并只减少同一进程内对 Backend 的重复访问，不替代 Yuanrong 的分布式 key 一致性，也不改变现有文件和目录失效规则。

预取方案↑ 目录

预取不修改 Yuanrong worker 内部。它由 RAGFS 进程内 PrefetchExecutor 调度，通过 Yuanrong SDK 向backend发起 mget。

RAGFS 主读路径
  -> 返回当前请求结果
  -> 非阻塞提交 prefetch hint

PrefetchExecutor / sidecar
  -> 通过 Yuanrong SDK mget(target_keys)
  -> 不等待主请求
  -> 命中则让本节点 Yuanrong worker 获得近端缓存
  -> miss 则按策略回源

预取触发↑ 目录

不要使用“每次读取都预取”，建议采用一次性窗口触发，推荐规则：

1. 缓存 miss 时触发
   miss 表明当前访问集合可能尚未进入缓存，预取价值最高。
2. 顺序访问确认后触发
   观察到同一目录连续读取两个文件，再预取后续文件。
3. 目录首次读取时触发
   read_dir miss 后预取少量高价值子文件，例如 .abstract.md。
4. 设置冷却时间
   同一目录或 trigger key 在 1~10s 内最多触发一次。
5. 限制预算
   每次最多预取 4~16 个对象，并限制全局并发和字节数。
6. 只预取缓存不存在的对象
   使用一次批量 mget，避免逐 key 查询。

read_dir(path) 命中 dir_key
  -> 立即返回 entries
  -> submit_prefetch(value.prefetch.immediate)

read(file) 命中 .overview.md
  -> 立即返回 data
  -> submit_prefetch(关联小文件 / child .abstract.md)

on_scope_enter(scope)
  -> 读取 hot_keys:{scope}
  -> submit_prefetch(hot_keys.topN)

submit_prefetch 必须是 best-effort：

队列未满:
  接收任务

队列已满:
  丢弃低优先级任务
  记录 prefetch_dropped

热点反馈 + hot_keys 缓存↑ 目录

hot_keys 只缓存热点 key 列表，不缓存真实数据，也不参与一致性判断。单进程场景做hot_keys收益不大，暂时不做。

OpenViking 定制优化↑ 目录

1. 缓存 raw read_dir↑ 目录

目录缓存只缓存 backend 原始 entries，不缓存权限过滤后的输出。这样同一份缓存可以被多条 OpenViking 路径复用。

实际收益

1. 提高命中率：同一目录只保存一份缓存。
2. 减少缓存容量：避免按用户、角色和输出格式复制 entries。
3. 简化失效：目录变更只需删除一个 dir_key(path)。
4. 避免权限数据过期：权限过滤每次实时执行。
5. 减少组合缓存：摘要继续走独立 file_key，不塞进目录缓存。

2. tree(agent) 批量摘要读取↑ 目录

tree(agent) 和 ls(agent) 使用目录缓存与摘要文件缓存组合完成：

get dir_key(path)
mget child .abstract.md file_keys

这样目录 entries 与摘要文件分别走 dir_key 和 file_key，一致性更简单，也避免维护额外的组合缓存失效规则。

3. write_context 批量更新↑ 目录

OpenViking 的 write_context 通常一起写：

content file
.abstract.md
.overview.md

在 backend 写成功后，使用 Yuanrong mset_tx 批量更新这些小文件缓存，并删除相关目录缓存：

mset_tx(content, abstract, overview)
delete dir_key(parent)

故障与降级↑ 目录

缓存层不能破坏文件系统正确性。

Yuanrong get 失败:
  -> 回源 backend

Yuanrong set 失败:
  -> 尝试 delete 对应 key
  -> 失败则 path 进入短期 cache bypass
  -> 严格模式可返回错误

Yuanrong delete 失败:
  -> path/dir/scope 进入短期 cache bypass
  -> 严格模式可返回错误

Yuanrong prefetch 失败:
  -> 忽略，只记 metrics

指标监控↑ 目录

需要记录：

cache_hit
cache_miss
cache_bypass
cache_stale_generation
cache_set_failed
cache_delete_failed
subtree_generation_bump_failed
prefetch_triggered
prefetch_hit
prefetch_waste
prefetch_dropped
inflight_leader_total
inflight_follower_total
inflight_active
inflight_wait_latency
inflight_backend_saved
inflight_timeout
inflight_fill_aborted_by_mutation

推荐落地顺序↑ 目录

1. CachedFileSystem + CacheProvider trait。
2. 先落地一种 Provider：Yuanrong native bridge 或 Mooncake Rust API。
3. cache_policy：排除锁文件、控制文件、权限敏感路径。
4. 文件缓存：优先 .abstract.md / .overview.md。
5. raw read_dir 缓存。
6. subtree_generation 覆盖 remove_all 和目录 rename。
7. 基于 inflight 的缓存击穿保护和请求合并。
8. write_context 批量更新。
9. RAGFS 进程内 PrefetchExecutor。
10. hot_keys 热点反馈和非侵入式预取。

最终保证↑ 目录

在单 OpenViking 进程和 Yuanrong key 级一致性前提下，本方案保证：

文件:
  write/update 返回后，file_key 要么是新内容，要么不存在。
  delete/rename 返回后，不会从 Yuanrong 读到旧 file_key。

目录:
  mkdir/delete/rename 返回后，相关 parent dir_key 被删除。
  read_dir 不会继续读到旧目录 entries。

子树:
  remove_all/目录 rename 返回后，残留子孙 key 会因 subtree_generation 不匹配而失效。

预取:
  只提前填充缓存，不改变一致性语义。
  即使预取到旧数据，后续真实读仍需通过 subtree_generation 校验。

一句话总结：

单进程不需要复杂分布式一致性协议；
但仍需要 RAGFS 按文件系统语义维护 file_key、dir_key 失效；
并保留 subtree_generation 处理 remove_all 和目录 rename 的残留子孙缓存。