分布式系统

Mooncake Store 把对象位置和副本状态集中在 Master。这样简化了一致性，但也意味着 Master 的状态不能只存在进程内存中。 本篇基于提交 777cc77，阅读 oplog、snapshot、standby controller 和恢复相关源码。 一、先澄清高可用目标 Mooncake Store 面向高速缓存池。缓存数据本身可以因为节点故障而丢失，系统并不等价于强持久化对象存储。 但控制面仍需要可靠：Master 重启后必须尽可能恢复对象元数据、Segment、配额和副本状态，否则即使真实字节还在，系统也不知道如何访问和回收它们。 因此需要区分两件事。 数据副本是否仍存在。 Master 是否记得这些副本及其状态。 本篇主要讨论第二件事。 二、为什么只做定期快照不够 假设 Master 每十分钟保存一次完整快照。第九分钟发生的大量 Put、Remove 和 Eviction，在崩溃后都会消失。 缩短快照间隔又会频繁扫描和序列化庞大元数据。 常见解决方案是 snapshot 加 oplog： Snapshot 保存某个时刻的完整状态。 OpLog 记录快照之后的增量变化。 恢复时先加载 Snapshot，再重放 OpLog。 Mooncake Store 的 Master 也采用了这一思路。 三、OpLog 记录什么 不是每个函数调用都值得写日志。需要持久化的是会改变可恢复状态的操作，例如对象元数据建立、提交、删除、副本变化和 Segment 相关更新。 当前 master_service.cpp 中可以看到 AppendOpLogWithDurableFinalize、批量预留和 durable finalize 等路径。 这里最关键的顺序是：某些不可逆的内存状态变化，要等对应日志达到持久条件后才能最终确认。 否则进程可能在“内存已经释放，但日志还没记住”时崩溃，恢复后重新得到一个指向已释放空间的副本。 四、Durable Finalize 的设计含义 名字里的 durable finalize 表明操作被拆成了准备与最终完成。 大致过程如下： 准备元数据变化 -> 追加 OpLog -> 等待达到持久条件 -> 执行最终回收或确认 这和 Put 的两阶段思路相似。系统先建立可回滚或可恢复的中间状态，再跨过明确的持久化边界。 ...

写入建立对象，读取和淘汰决定缓存系统能否长期稳定运行。本篇沿 Get、Remove 与后台 Eviction 三条路径，观察 Mooncake Store 如何维护副本可读性和容量平衡。 源码基线仍为 777cc77。 一、Get 首先读取的是元数据 Client 不知道对象当前在哪台机器，也不应缓存一份永远不变的地址。 读取开始时，Client 向 Master 请求副本列表。核心入口之一是 MasterService::GetReplicaList。 Master 查找 key 对应的 ObjectMetadata，然后筛选当前允许读取的副本。返回结果包含 Segment、offset、长度和介质等信息。 随后 Client 才通过 Transfer Engine 把对象复制到本地 Buffer。 二、不是列表里的每个副本都可读 一个对象可能同时存在以下副本： 已完成并可读的内存副本。 正在复制的动态副本。 写入失败、等待清理的副本。 位于本地盘的副本。 所在 Segment 正在卸载的副本。 因此 Get 不能只检查 replicas 是否非空。源码中的 HasReadableReplica 以及各种状态判断，负责把控制面中的暂态副本排除掉。 读取正确性的一个重要来源，就是“只从已提交的副本集合中选择”。 三、副本选择优化什么 拥有多个可读副本后，系统还要选择来源。 理想选择通常考虑： 是否位于本机或同一故障域。 介质是 DRAM、VRAM 还是磁盘。 传输协议和拓扑成本。 副本是否正在被回收。 是否能满足本次 Buffer 类型。 Mooncake 将元数据筛选与实际传输分开，使选择策略可以持续演进。Master 保证候选集合合法，Client 和 Transfer Engine 完成具体数据路径。 四、读取失败不等于对象不存在 控制面返回副本后，数据面仍可能失败。例如节点刚好退出、网络断开，或 Segment 已经不可访问。 ...

Mooncake Store 的 Put 不是一次 RPC。它是一段跨越 Client、Master、分配器和 Transfer Engine 的两阶段流程。 本文继续使用提交 777cc77。阅读重点是 real_client.cpp 与 master_service.cpp 中的写入路径。 一、为什么 Put 必须拆成两段 如果 Master 收到 Put 请求后立刻把对象标记为可读，其他 Client 可能读到尚未传完的数据。 如果等所有数据都发送给 Master，再由 Master 落到目标节点，控制面又会成为数据面瓶颈。 Mooncake Store 的做法是：Master 先预留副本，Client 直接传输，最后由 Master 提交状态。 PutStart -> 返回目标副本 -> 直接传输对象 -> PutEnd 这相当于围绕一次数据面操作建立轻量级提交协议。 二、Client 侧的准备工作 Put 开始前，RealClient 需要确定源 Buffer 的位置和长度。源数据可能来自普通主机内存，也可能来自已经注册的加速器内存。 Client 会把大对象切成适合传输的任务。每个任务包含本地地址、远端 Segment、远端 offset 和长度，然后交给 Transfer Engine。 Store 不重复实现 RDMA、TCP 或 GPU Direct 细节。它只把“对象副本”翻译成 Transfer Engine 能执行的传输描述。 ...

Mooncake Transfer Engine 解决的是“怎样快速搬数据”，Mooncake Store 解决的则是更上层的问题：一个对象叫什么、放在哪些节点、有哪些副本、何时可读、空间不足时淘汰谁，以及 Master 重启后怎样恢复这些事实。 本文使用 Mooncake 仓库提交 777cc77 作为源码基线。这个版本的 Store 已经远超早期原型，包含多租户配额、内存与本地盘分层、动态副本、批量淘汰、快照和热备等能力。 一、先看整体分层 Mooncake Store 可以拆成四层。 第一层是上层调用者。vLLM、SGLang 或其他推理系统通过 Python、C++、Rust、Go 等接口访问对象。 第二层是 Client。RealClient 负责本地缓冲区、Master RPC、数据传输、重试和资源清理。 第三层是 Master。MasterService 保存对象元数据，管理 Segment、分配副本、维护租户配额，并驱动淘汰和复制。 第四层是数据资源。DRAM、VRAM、本地 SSD 或其他后端提供真正保存字节的空间，Transfer Engine 执行跨节点传输。 数据不会先发送到 Master，再由 Master 转发。Master 只告诉 Client 应该访问哪些副本，真正的大块数据直接在 Client 与目标内存之间移动。 二、源码目录怎样阅读 建议先抓住以下文件。 mooncake-store/include/real_client.h：Client 的主要状态和接口。 mooncake-store/src/real_client.cpp：Put、Get、Remove 与初始化流程。 mooncake-store/include/master_service.h：Master 的核心数据结构。 mooncake-store/src/master_service.cpp：元数据状态机和控制逻辑。 mooncake-store/include/replica.h：副本描述与状态。 mooncake-store/include/segment.h：可分配存储资源。 mooncake-store/src/allocation_strategy.cpp：副本放置策略。 mooncake-store/src/allocator.cpp：具体空间分配。 mooncake-store/src/transfer_task.cpp：Store 到 Transfer Engine 的任务封装。 不要一开始就顺序阅读体量巨大的 master_service.cpp。更有效的方法是从 RPC 接口出发，沿 PutStart、PutEnd、GetReplicaList 和 Remove 四条链路向下追踪。 ...