1. 先把 Mooncake 的部署逻辑讲透，再动手敲命令

我头一回在生产集群里上 Mooncake，是因为推理服务的首 token 延迟在高峰期抖得厉害。单机 vLLM 跑得好好的，一放到几十张卡的集群里，Prefill 节点算完的 KV Cache 没法高效传给 Decode 节点，网络成了新瓶颈。这种场景下，Mooncake 就是为"以 KVCache 为中心"的分离式推理架构准备的——它把 KV Cache 从 GPU 显存里抽出来，做成一个跨节点、分层、可复用的分布式缓存池。简单说，它要解决的是"算力没吃满、显存反复搬、缓存命中率低"这三件事。

这套东西由几块拼图组成：Transfer Engine负责底层数据传输（RDMA、TCP、NVMe-oF、共享内存都能接），Mooncake Store负责缓存对象的分布式管理与路由，Mooncake Master是元数据大脑，负责 Segment 分配和淘汰策略，P2P Store则用来做模型权重和 checkpoint 的点对点分发。本文面向的是已经了解大模型推理、现在要把 Mooncake 落地的工程师——从一台开发机跑通，到几十台节点组成生产集群，我会把每一步的判断依据和踩过的坑都摊开说。

2. 部署前必须搞明白的架构决策

2.1 为什么选"分离式 + 集中缓存"而不是单机堆卡

我一开始也犹豫过：把模型切得更细、多卡张量并行，不是更直接吗？实测下来这条路在长上下文场景会撞墙。张量并行的通信量随 TP 度数上升，跨机 NVLink 缺失时直接打回 PCIe 带宽；而分离式架构把 Prefill 和 Decode 拆到不同节点，用 Mooncake 做 KV Cache 中转，Prefill 可以按算力密度配置（比如 8 卡 A800），Decode 按显存带宽配置，两边的硬件不必一样。这样调度器可以针对"缓存命中"而不是"请求排队"做决策——这就是它所谓 KVCache-centric 的含义。

代价是运维复杂度上来了：你要维护 Master 的高可用、元数据服务、RDMA 网络、Segment 的容量规划。所以我的判断是，单机显存够用、并发不高的小场景别上集群，只有当你做到下面这些条件时才值得上：

• 单请求上下文长度常年超过 8K，KV Cache 复用率有优化空间
• 集群规模超过 16 张卡，且 Prefill / Decode 负载有明确的时间差
• 业务对 TTFT（首 token 延迟）和吞吐都有硬指标

2.2 Transfer Engine 的传输路径选择

这是部署最容易翻车的一环。Transfer Engine 抽象了多条后端路径，我在不同环境里都用过：

提示：单机部署直接用 tcp 或 shm 就行，不要折腾 RDMA，否则一堆 GID、PFC、MTU 的坑能把调试时间吃掉两天。

2.3 单机模式和集群模式的边界在哪

我的经验是，单机模式只用来验证功能与压测接口，一旦要上业务就得转集群。单机模式下 Master、Store、Client 都跑在同一台机器上，用 shm 或 tcp 通信，整个体系本质上还是一个本地缓存池，没有跨节点收益。集群模式才是 Mooncake 真正发挥的地方：多个存储节点各自贡献 DRAM/SSD 作为 Segment，Master 统一管理，客户端只需一个全局地址就能读任意缓存。

具体怎么切分，我画了一个判断表：

• 只做功能验证、跑通 Python 示例 → 单机
• 需要给离线批量推理提速、KV Cache 复用率高 → 单机或小集群
• 在线服务、TTFT 敏感、节点数 >4 → 集群 + RDMA
• 有冷热分层需求（显存→DRAM→SSD） → 集群 + NVMe 池

3. 单机部署：从零到跑通第一个读写测试

3.1 系统环境与硬件底线

先说我踩过的第一个坑：Mooncake 对 glibc 和编译器版本有要求，太老的发行版会缺符号。我推荐组合是Ubuntu 22.04 + GCC 11 + CMake 3.22+。如果要用 RDMA，还要装libibverbs-dev、rdma-core，并确保/dev/infiniband存在。

硬件上单机最低配置参考：

• CPU：16 核以上，编译阶段就能看出来
• 内存：≥64GB，因为 Store 需要预分配大块 DRAM 做 Segment
• 磁盘：≥200GB 空闲空间，SSD 优先
• 网卡：单机验证用普通网卡即可，RDMA 网卡留到集群阶段

注意：Mooncake 的 Store 会预先mmap一大块内存，如果你用容器部署，务必把--shm-size调大，否则启动时会 OOM。

3.2 依赖安装与源码构建

依赖项我按顺序列一下，这样不会因为链接顺序出问题：

sudo apt update sudo apt install -y build-essential cmake ninja-build \ libgflags-dev libgoogle-glog-dev libgtest-dev \ libjsoncpp-dev libyaml-cpp-dev libcurl4-openssl-dev \ libssl-dev libibverbs-dev librdmacm-dev \ libnuma-dev libaio-dev

拿到源码后，构建我一般分两步：先构建 Transfer Engine，再构建 Store。原因是 Store 依赖 TE 的库，如果一起 build 遇到链接错误不好定位。

git clone https://github.com/kvcache-ai/Mooncake.git cd Mooncake mkdir build && cd build cmake .. -DCMAKE_BUILD_TYPE=Release -DWITH_RDMA=ON -DWITH_STORE=ON make -j$(nproc)

编译时长取决于机器，16 核大约 10-15 分钟。WITH_RDMA=ON在没有 RDMA 网卡时也能编过，只是运行期会 fallback 到 TCP。

3.3 启动 Master 并跑通读写测试

启动顺序很重要：先起元数据服务，再起 Master，最后起客户端。单机验证时元数据服务我用的是 etcd，因为配置简单、文档全：

# 1. 启动 etcd（单节点即可） etcd --listen-client-urls http://0.0.0.0:2379 \ --advertise-client-urls http://0.0.0.0:2379 \ --data-dir /var/lib/etcd-mooncake & # 2. 启动 Mooncake Master ./build/mooncake-store/src/mooncake_master \ --rpc_port=50051 \ --eviction_high_watermark_ratio=0.9 \ --default_kv_lease_ttl=5000

Master 起来了以后，客户端这边 Python 侧接一下就通了：

from mooncake.store import MooncakeDistributedStore store = MooncakeDistributedStore() store.setup( local_hostname="127.0.0.1", metadata_server="etcd://127.0.0.1:2379", global_segment_size=8 * 1024 * 1024 * 1024, # 8GB local_buffer_size=512 * 1024 * 1024, # 512MB protocol="tcp", device_name="", ) store.put("test_key", b"hello_mooncake") print(store.get("test_key"))

我特意留了一段日志观察：put之后 Master 日志会出现ObjectAllocated记录，get时如果命中的是远端 Segment，TE 层会打印TransferRequest的耗时。这套日志是排查问题的第一现场，建议先用-v=2打开详细日志。

3.4 单机部署的三个典型坑

坑一：内存预分配过大导致启动慢。global_segment_size写 32G 时，启动阶段 mmap 就要好几十秒，而且如果物理内存不够会触发 OOM Killer。我一般按物理内存的 60% 给到 Segment。

坑二：local_buffer_size设太小。这个缓冲区是用于 TE 零拷贝的中转区，太小会退化到多次拷贝，吞吐直接砍半。512MB 起步，重负载场景翻倍。

坑三：etcd 的 lease 泄漏。客户端异常退出后 Segment 对应的租约不一定及时清理，重启客户端前先看etcdctl get --prefix mooncake/里有没有残留。这个坑在集群模式里更明显，后文细讲。

4. 生产环境集群部署：从 3 台到 100 台

4.1 网络规划：RDMA 还是 RoCE，以及带宽怎么算

生产环境的网络方案我建议按集群规模分档：

• 3-8 节点、无无损网络条件：先上 TCP，带宽至少 25Gbps，此时瓶颈不在网络而在 DRAM 带宽
• 8-32 节点：上 RoCEv2，配置 PFC 和 ECN 做无损，25G 起步
• 32 节点以上：直接上 InfiniBand HDR/NDR，否则大规模下 PFC 风暴的概率会攀升

带宽怎么算？假设每条请求平均 KV Cache 是 1GB，Prefill 和 Decode 之间 RTT 要控制在 100ms 内，那么单链路至少需要 8Gbps。再乘上并发数，就得到目标带宽。我给个公式：

所需带宽 = 单请求 KVCache 大小 × 并发传输数 / 可接受延迟

举例：1GB × 8 并发 / 0.1s = 80Gbps。这个数字远超单口 25G，说明要么做多链路聚合，要么减少跨节点传输，多做本地 Segment 命中。这是很多团队上线后才发现的事——不是有了 RDMA 就万事大吉。

4.2 元数据服务与 Master 的高可用

生产环境的 etcd 必须 ≥3 节点，跨机架部署。配置上的关键是--heartbeat-interval和--election-timeout，默认值在延迟较高的跨机架环境下容易误判，我一般设成 250ms / 2500ms。

Master 的高可用是另一回事：Mooncake Master 目前不内置多活选举，常见做法是Active-Standby + 外部探测切换。Standby Master 只监听不服务，通过 etcd 的租约判断 Active 是否存活，探测间隔 2s，失败 3 次触发切换。切换时客户端需要重连，Python 侧可以自己写一个重试循环：

def get_client_with_retry(addr_list, max_retry=5): for i in range(max_retry): try: s = MooncakeDistributedStore() s.setup(local_hostname="0.0.0.0", metadata_server="etcd://etcd1:2379,etcd2:2379,etcd3:2379", protocol="rdma", device_name="mlx5_0", master_server_address=addr_list[i % len(addr_list)]) return s except Exception as e: print(f"retry {i}: {e}") raise RuntimeError("mooncake master unavailable")

注意：Segment 的租约 TTL 要设得比 Master 切换时间长，否则切换期间会出现"缓存被误抢"的混乱。我一般把default_kv_lease_ttl设成 8000ms，Master 切换窗口控制在 3s 内。

4.3 存储节点的分池与容量计算

集群里每个存储节点就是一个 Segment 提供者。生产上我习惯按角色分池：

• 热池：DRAM 为主，8 节点，每节点 128GB 给 Store
• 温池：NVMe SSD 为主，4 节点，每节点 2TB
• 冷池：HDD/远端对象存储，用于归档，可选

容量规划的经验值是：热池总容量 ≥ 单批次并发请求 KV Cache 总量 × 2。这个 2 是留给淘汰策略的冗余，因为淘汰不是瞬时的，水线到了还要时间落盘。

Master 的淘汰参数也很关键：

--eviction_high_watermark_ratio=0.9 # 超过 90% 触发淘汰 --eviction_ratio=0.2 # 每次淘汰 20% --eviction_thread_num=4 # 淘汰线程数

淘汰线程数不要设太大，会抢 Bandwidth；也不要只设 1个，否则水线一到就抖动。

4.4 客户端接入与推理框架集成

Mooncake 和 vLLM 的集成主要在 KV Connector 那一层。生产部署时我建议把客户端部署在和 Store 节点同机房、最好同机架的位置，跨机架时延会显著拉低缓存收益。

集成方式上，如果你用的是 vLLM 的 disaggregated prefill 模式，Mooncake 可以通过 KV Connector 直接接管缓存传输；如果是自研推理框架，就走 Python API 或 C++ 的Client接口。

客户端参数里要注意local_buffer_size和global_segment_size的关系：客户端本身也会把自己的一段内存注册成 Segment（可以理解为"客户端也在贡献缓存"），如果你不打算这么做，就把global_segment_size设成 0，只用local_buffer_size做收发缓冲。

5. 监控、调优与故障排查实录

5.1 必看的监控指标

Mooncake 目前没有默认的 Prometheus Exporter，但 Master 的日志和 metrics 端点能接一部分。我按经验列一下关键指标和对应的告警线：

这些指标我一般通过日志解析推给 Prometheus，Master 侧开-v=1就会输出结构化的 metrics 行，用 Vector 或 Filebeat 抽字段很省事。

5.2 常见故障速查表

我把上线三个月遇到的真事整理成表，基本上照着看能解决八成问题：

5.3 调优心得与注意事项

心得一：先测缓存命中率再谈扩容。我见过一些部署，一开始就堆了 20 台存储节点，结果命中率 40%——原因是请求分布太随机，KV Cache 复用率本来就低。这种时候加机器是浪费，得回到业务侧看 prompt 结构。

心得二：RDMA 的 MTU 一定要对齐。交换机配 4096、主机配 1024 会导致大量分片，实测延迟翻三倍。我部署时会先ibv_devinfo看 active_mtu，再统一交换机和主机。

心得三：etcd 和 Master 别同机。这两个组件的资源画像差异很大，混布时 etcd 的心跳抖动会传染给 Master，出现 RPC 间歇性超时。哪怕只有三台机器，也建议把 etcd 挪到一台独立的小规格机器上。

心得四：大版本升级前先做 Segment 快照。Mooncake 元数据在跨版本时不一定向前兼容，生产升级前先停写、等淘汰结束，用etcdctl snapshot save做一次全量备份。这个动作看似多余，但有一次升级遇到 schema 变更，就是靠快照 30 分钟回滚，业务几乎无感。

心得五：客户端进程重启后记得手动清理旧 Segment。客户端侧注册的 Segment 如果没优雅退出，Master 会留着它直到租约到期。批量重启时，旧 Segment 会短暂占用容量，导致新实例启动时被"假满"卡住。我的做法是脚本先抓一遍etcdctl get --prefix里本地 IP 相关的 key，删掉再重启。

最后分享一个我在生产里常用的小技巧：给每个存储节点打一个zone标签，写进 Master 的 Segment 元数据里，客户端按"就近优先"的策略选 Segment。这一招在跨机架部署时尤其管用，命中同机架缓存的 RTT 能从 300 微秒降到 80 微秒，对长上下文推理的 TTFT 提升是实打实的。如果后续你还要做多级缓存（显存 → DRAM → SSD），可以在 Ext 里加一层 EV 策略，让 SSD 池只承接明确标记为"冷数据"的对象，避免把 SSD 当成 DRAM 用。