企业官网建设流程全解析

1. 动手之前，先把 Mooncake 的组件边界摸清楚

Mooncake 这套东西最早是给超长上下文、超大并发的推理场景设计的，核心思路一句话就能说清：把 KV Cache 从单机显存里拽出来，做成一个跨节点可复用的分布式缓存池，同时把 Prefill 和 Decode 拆到不同机器上跑，中间靠一条高吞吐的传输通道把 KV 搬来搬去。听起来简单，真到部署的时候，很多人第一步就卡住了——clone 下来一堆目录，Transfer Engine、Store、P2P Store、各种 integration，到底哪个是要跑起来的服务，哪个只是个库？

我这次把从笔记本单机验证，到两节点 TCP 打通，再到 RDMA 集群上接 vLLM 做 PD 分离的完整过程整理了一遍。这篇内容适合三类人看：一是想先在本机把 Mooncake 跑通、验证一下传输性能的开发者；二是手里有几台机器、想做跨实例 KV 复用的推理服务运维；三是已经上了 PD 分离、但被传输瓶颈或者缓存管理问题折磨过的同学。单机部分你照着敲基本能过，生产环境那部分我给的是核对清单和容量算法，具体参数得结合你自己的硬件再算一遍。

1.1 三个核心组件，各自管什么

**Transfer Engine（传输引擎，简称 TE）**是地基。它干的事情非常纯粹：在节点之间或者同节点不同进程之间搬内存块。底层传输可以走 RDMA（RoCEv2 或者 InfiniBand），也可以退化成 TCP。向上暴露的是一组很原始的原语——我注册一块内存，你告诉我对端的 segment 名字和偏移量，我把数据搬过去。它不关心你搬的是 KV 还是别的什么，所以理论上也能拿来做别的数据搬运。

Mooncake Store建在 TE 之上，由 Master 和 Client 两部分组成。Master 是个独立进程，管元数据：哪个 key 落在哪个 segment、租约还有多久过期、内存水位到了要不要淘汰。Client 一般嵌在推理进程里，负责本地内存注册和 put/get 调用。需要特别纠正一个常见误解：Store 的缓存介质是各节点的 DRAM（也可以配 SSD 做二级），不是显存。显存那部分归推理框架自己管。

Connector是桥接层。vLLM 侧主要有两个，一个偏 PD 分离的数据面转发，一个偏分布式 KV 缓存池，名字在不同版本里改过几次，很容易搞混。SGLang 那边也有对应集成。这一层最容易出问题，因为它是跟着 vLLM 版本走的，上游 API 一动，Connector 就得跟着改。

1.2 单机、小集群、生产环境到底差在哪

很多人一上来就想直接按生产标准搭，结果被 RDMA 的网卡配置、交换机 PFC、GID index 这些细节拖了三四天，连一条传输都没跑通。我的建议是严格分三档走，每一档只解决一个问题，跑通了再进下一档。

单机这档的目标是：确认编译没问题、Python 包能 import、Transfer Engine 能把一块内存从 A 搬到 B 并且校验通过、Master 能起来、Store 能 put 进去再 get 出来。这一档完全不需要任何网络配置，遇到问题也基本是依赖缺失或者版本不匹配，排查成本极低。

小集群这档，目标是把"跨机"这个变量加进来。先用 TCP 打通，确认元数据服务、segment 注册、握手、传输这整条链路是通的。等你确认 TCP 下带宽和延迟符合预期了，再换 RDMA。这个顺序千万别反——如果一上来就上 RDMA，传输失败的时候你根本分不清是网卡配置问题、GID 选错、还是代码里 protocol 参数写错了。

生产环境这档，要解决的问题就变成了：缓存容量怎么规划、Master 挂了怎么办、内存水位怎么设、监控看哪些指标、Connector 和推理框架版本怎么锁。这些跟"能不能跑起来"完全是两类问题，混在一起想会把自己绕进去。

1.3 部署前必须拍板的四个选择

在敲第一条命令之前，有四个决定如果不提前想好，后面很可能要推倒重来。

第一个是传输协议。如果你的机器之间只有普通以太网、没有 RDMA 网卡，那就老老实实用 TCP。TCP 的吞吐在万兆网下大概能跑到 1 GB/s 出头，做跨节点 KV 复用的收益会比较有限，但用于功能验证完全够。如果有 RoCE 网卡和配套交换机，那 RDMA 是唯一选择，单流跑到几十 GB/s 是很正常的事情，这个差距在长上下文场景下就是能不能用的区别。

第二个是元数据服务用什么。Transfer Engine 需要一个地方存各个 segment 的握手信息，常见做法是 etcd，也有用 Redis 或者其他键值存储的。生产环境建议直接用 etcd 集群，别用单点。这里有个坑：很多人以为元数据服务就是 Store 的 Master，其实这是两个完全不同的东西，一个存的是网络端点信息，一个存的是 KV 的位置和租约，只是它们经常部署在同一台机器上，所以容易被混淆。

第三个是缓存放在哪。默认是 DRAM，容量受限于内存大小。如果要做 SSD 二级缓存，需要在 Client 侧额外配置路径和容量上限。我的经验是，除非你的内存真的非常紧张，否则先把 DRAM 这一层调稳，SSD 二级缓存涉及文件系统缓存管理、读写放大等问题，会显著增加排查复杂度。

第四个是Master 的可用性策略。Master 管元数据，挂了之后 Client 的 put/get 会失败，但已经建立的传输不受影响。生产环境至少要做到 Master 进程能快速重启并从持久化状态恢复，或者干脆上主备。这个后面第 4 章会细说。

2. 单机部署：先把第一条 Transfer 跑通

单机这一档，我的预期是半天之内搞定，如果超过一天，大概率是某个依赖版本不对，而不是你操作有问题。

2.1 软硬件基线与环境依赖

先说我用的环境，供你对齐：Ubuntu 22.04、内核 5.15、gcc 11、cmake 3.22、Python 3.10、单张消费级显卡（单机验证阶段其实用不到显卡，Transfer Engine 走的是内存到内存，只有涉及显存相关的传输才需要）。内存建议至少 32 GB，因为后面要注册一块几百 MB 到几 GB 的缓冲区做测试。

依赖装起来不复杂，但有几个容易漏的。hiredis是给元数据存储做客户端的，libcurl和openssl有些组件会用到，glog和gflags在很多版本里是编译期的硬依赖。另外如果你的机器上有 RDMA 网卡，libibverbs-dev和librdmacm-dev要装上，即使暂时不用 RDMA，编译时也会去找这些头文件。

sudo apt update sudo apt install -y build-essential cmake pkg-config \ libhiredis-dev libcurl4-openssl-dev libssl-dev \ libgflags-dev libgoogle-glog-dev libyaml-cpp-dev \ libibverbs-dev librdmacm-dev libnuma-dev \ python3-dev python3-pip python3-venv git

注意：不要用系统自带的 cmake。Ubuntu 20.04 自带的是 3.16，某些子项目要求 3.18 以上，编译到一半才报错会很浪费时间。用cmake --version确认一下，低了就自己装一个新版。

2.2 编译与 Python 包安装

仓库里通常会带一个依赖安装脚本，长这样：

git clone https://github.com/kvcache-ai/Mooncake.git cd Mooncake # 有些版本会自带依赖脚本，先看一眼有没有 ls dependencies.sh 2>/dev/null && bash dependencies.sh

编译建议分两步走，先只编 Transfer Engine，确认这一步过了再编其他组件。全量编译动辄十几分钟，出错回滚的成本很高。

mkdir -p build && cd build cmake .. -DCMAKE_BUILD_TYPE=Release make -j$(nproc)

编译完成后，build/目录下会生成各个组件的可执行文件和动态库。这时候你应该能看到 Transfer Engine 的测试程序和 Mooncake Master 的二进制文件。如果某个组件没编出来，先别急着往下走，去看 CMake 输出里哪个依赖没找到。

Python 侧的安装方式在不同版本里不一样，有的是在根目录直接pip install .，有的是在子目录里。我踩过的坑是：装完之后import mooncake报找不到模块，或者 import 成功但里面的子模块是空的。这种情况下先确认你装的是哪个 wheel，再确认PYTHONPATH有没有被其他环境变量覆盖。

python3 -m venv .venv && source .venv/bin/activate pip install --upgrade pip pip install -e . # 如果根目录有 pyproject.toml 或 setup.py python -c "import mooncake; print(mooncake.__file__)"

2.3 跑通第一条 Transfer

单机模式下，你可以在同一个进程里初始化两个 Transfer Engine 实例，互相传数据。这是验证 API 最省事的方式，不需要任何网络配置。

下面这段是我实际验证用的代码骨架，接口签名在不同版本之间有差异，你对着自己仓库里examples/目录下的示例改一下就能用。

import time from mooncake.engine import TransferEngine SEGMENT_A = "segment_a" SEGMENT_B = "segment_b" BUF_SIZE = 1024 * 1024 * 256 # 256 MB # 两个实例共用同一个元数据服务，单机阶段可以用本地的一个 meta = "127.0.0.1:2379" a = TransferEngine() a.initialize("127.0.0.1", meta, "12345", "tcp") b = TransferEngine() b.initialize("127.0.0.1", meta, "12346", "tcp") # 注册内存，拿到本地地址 addr_a = a.allocate_managed_buffer(BUF_SIZE) a.register_memory(addr_a) addr_b = b.allocate_managed_buffer(BUF_SIZE) b.register_memory(addr_b) # 先写点数据进去 import ctypes data = b"x" * BUF_SIZE ctypes.memmove(addr_b, data, BUF_SIZE) # A 打开 B 的 segment，然后发起传输 a.open_segment(SEGMENT_B) start = time.time() a.transfer_sync(SEGMENT_B, addr_a, addr_b, BUF_SIZE) cost = time.time() - start print(f"传输 {BUF_SIZE / 1024 / 1024} MB 耗时 {cost * 1000:.2f} ms, " f"带宽 {BUF_SIZE / cost / 1024 / 1024 / 1024:.2f} GB/s")

这里有几个关键点必须理解，不然换成跨机场景会一头雾水。

initialize的第二个参数是元数据服务地址，单机你可以起一个本地的 etcd，也可以看你的版本是否支持内存内的元数据后端。第三个参数是 RPC 端口，同一个进程里两个实例必须用不同端口，跨机则各用各的。第四个参数是协议，tcp或rdma。

allocate_managed_buffer和register_memory是两个概念。前者是在本地申请一块可以被远端访问的内存（通常是 mmap 出来的大页或者 pinned 内存），后者是把这块内存注册到 NIC 或者 MR（Memory Region）表里。顺序不能反，而且没注册的内存传给transfer_sync会直接失败或者静默走到一个性能极差的慢路径。

open_segment做的是握手，它去元数据服务里查这个 segment 对应的网络端点，然后在本地建连接。这个操作有一定开销，生产环境里不要在每次传输前都调一次，应该在启动阶段就把对端 segment 开好并缓存。我见过有人把它写在请求处理的热路径里，单次延迟直接多了几毫秒。

单机跑出来的带宽一般在 10 到 20 GB/s 之间，取决于你的内存带宽和 CPU 单核性能。如果只有 1 GB/s 出头，先检查是不是走了 TCP 回环而不是共享内存路径。

2.4 单机起一个 Master 和 Store Client

传输验证通过之后，就可以上 Store 了。第一步是起 Master。

./build/mooncake-store/src/mooncake_master \ --rpc_port=9003 \ --eviction_high_watermark_ratio=0.9 \ --eviction_ratio=0.1

参数名字和默认值在不同版本里改过，先用--help看一眼再抄。这几个参数的含义值得解释清楚：

--rpc_port是 Master 监听 Client 请求的端口，Client 通过它上报 segment 信息、查询 key 位置、申请租约。默认一般是 9003，如果跟其他服务冲突了记得改。

--eviction_high_watermark_ratio是内存高水位线。当全局 segment 的占用超过这个比例时，Master 开始考虑淘汰。0.9 意味着还剩 10% 就开始动手，这个值不要设得太激进，比如 0.98，因为淘汰本身也需要时间和内存周转空间。

--eviction_ratio是单次淘汰的比例。设 0.1 就是一次淘汰掉 10% 的存量数据，避免频繁触发淘汰导致 CPU 一直在做 LRU 计算。

提示：单机验证阶段 Master 的内存占用可以放心调大，但生产环境里 Master 自己也要占内存（元数据条目），如果你的缓存 key 数量是百万级，Master 单独占几个 GB 是很正常的，规划的时候别漏了。

Master 起来之后，Client 侧这样用：

from mooncake.store import MooncakeDistributedStore store = MooncakeDistributedStore() store.setup( "127.0.0.1", # 本机标识 "127.0.0.1:2379", # 元数据服务 1024 * 1024 * 1024, # 本节点贡献给全局缓存的容量，1 GB 1024 * 1024 * 128, # 本地缓冲区大小，128 MB "tcp", # 协议 "", # 设备名，RDMA 时填，TCP 留空 ) store.put("test_key", b"hello mooncake") print(store.get("test_key"))

setup的第一个参数是节点标识，同一个集群里必须唯一；第三个参数是本节点愿意贡献多少内存给全局缓存池，这个值直接决定了集群总容量；第四个参数是本地缓冲区，用来做数据的临时中转。这两个值加起来才是这个节点实际占用的内存，规划容量的时候容易只算前者。

到这一步，单机的完整链路就通了：内存注册、传输、Master 元数据、put/get。接下来才是真正有难度的部分。

3. 从单机走向两节点：握手、元数据与协议切换

跨机和单机的本质差别只有一个：多了一个"网络端点信息怎么交换"的问题。单机是同进程内直接拿到地址，跨机则需要一个所有节点都能访问的地方来存这些信息，这就是元数据服务的意义。

3.1 先用 TCP 把跨机握手打通

找两台能互相 ping 通的机器，先用 docker compose 在其中一台上起一个 etcd。为什么用 etcd？因为它足够简单，有现成的容器镜像，而且很多人在其他系统里已经维护着 etcd 集群，能复用就复用。

# docker-compose.yml services: etcd: image: quay.io/coreos/etcd:v3.5.12 container_name: mooncake-etcd command: - /usr/local/bin/etcd - --name=etcd0 - --data-dir=/etcd-data - --listen-client-urls=http://0.0.0.0:2379 - --advertise-client-urls=http://10.0.0.11:2379 ports: - "2379:2379" volumes: - ./etcd-data:/etcd-data restart: unless-stopped

docker compose up -d docker compose logs -f etcd # 确认没有报错再继续

advertise-client-urls必须填这台机器对外可达的 IP，不要填127.0.0.1，否则另一台节点连不上。这个坑非常经典，我第一次部署就在这里卡了半小时，日志里只会显示连接超时，看不出是地址填错了。

然后两台机器上各起一个 Transfer Engine 实例，都用同一个 etcd 地址，分别用不同的本地标识和 RPC 端口。节点 A 调open_segment打开节点 B 的 segment，然后发起传输，跟单机代码几乎一样，只是本地标识从127.0.0.1换成了各自的真实内网 IP。

这里必须理解的一件事是：open_segment的背后是两次查询。第一次是本地 Engine 启动时把自己的端点信息写进 etcd，第二次是open_segment时去 etcd 读对端的端点信息，然后在本地建连接。所以如果 etcd 挂了，已经建立连接的传输不受影响，但新节点加入或者新的open_segment会失败。这个特性决定了生产环境里 etcd 的高可用等级要求比 Master 还高。

3.2 切到 RDMA 之前，先做三件核对

TCP 跑通之后别急着改参数，先做核对。RDMA 出问题的时候，90% 的原因是下面这三件事没确认。

第一，ibv_devices能不能列出你期望的设备。如果什么都不显示，说明驱动没装好或者网卡没识别。第二，ibv_devinfo -d <dev>里state是不是PORT_ACTIVE，如果是PORT_DOWN或者INIT，说明链路层没起来，问题在交换机或者光模块，不在代码。第三，看link_layer是Ethernet还是InfiniBand，这决定你后面填的地址类型完全不同。

ibv_devices ibv_devinfo -d mlx5_0 | grep -E "state|link_layer|active_mtu|max_mtu" show_gids # 查看 RoCE 场景下的 GID 表

切换到 RDMA 只需要改两个地方：initialize里的协议参数改成rdma，setup里的设备名填上网卡设备名比如mlx5_0。但填完不代表就能跑，RoCE 场景下 GID index 选错是非常高频的问题。同一张网卡上通常有 v1、v2 以及 IPv4、IPv6 的多种 GID，选错了要么连不上，要么连上了但性能只有理论值的一小部分。

# 记录下正确的 GID index，配置时对照 show_gids | grep -i v2

注意：RDMA 的性能对 MTU 非常敏感。如果链路协商到的active_mtu是 1024 而不是 4096，带宽可能只有理论值的一半多一点。这个要看交换机端口的 MTU 配置，两端不一致时会自动降到较小的那个。

3.3 Master 独立部署与元数据服务的辨析

两节点跑通之后，下一个动作是把 Master 从推理节点上挪走，放到一台独立机器上。原因有两层：一是 Master 的内存和 CPU 占用会随着缓存 key 数量增长，跟推理服务抢资源不划算；二是推理节点做滚动重启的时候，Master 不应该跟着一起挂。

挪完之后，Client 的setup里指向 Master 的地址要跟着改。这里有个容易搞混的点：Client 的setup参数里既有元数据服务地址（etcd），又有 Master 地址，它们是分开配置的。元数据服务管的是传输层的端点信息，Master 管的是 KV 的位置和租约，两者生命周期独立。实际部署时我一般把它们放同一台机器的不同端口上，物理上省事，逻辑上还是要拎清楚。

Master 挪走之后要做一次完整验证：两个推理节点分别 put 一个 key，然后在对方节点上 get 同一个 key。如果 get 不到，说明 Master 的全局视图没建立起来，重点查 Client 上报 segment 的那一步有没有成功。日志里通常会有 segment 注册的打印，能看到每个节点贡献了多少容量。

到这一步，你已经有了一个两节点的、可用的分布式 KV 缓存。生产环境的差距主要在规模、可靠性和可观测性上。

4. 生产环境：集群规模、PD 分离与容量规划

生产部署跟前面两档最大的区别不是技术难度，而是你没有试错的余地。一个参数设错，可能是几百张卡的集群一起抖动，或者缓存命中率掉到个位数。

4.1 RDMA 集群的部署前核对清单

在往几十个节点上铺之前，我建议先做一次全集群的一致性核对。下面这张表是我实际用的版本，每一行都有对应的命令，跑完一遍基本能排除掉大部分低级问题。

带宽基线这一步特别值得强调。我在一个集群上遇到过单流带宽只有理论值三分之一的情况，最后查到是网卡插在了 PCIe 3.0 x8 的槽位上，而卡本身是 PCIe 4.0 x16 的。这种硬件层面的带宽瓶颈，在应用层看起来就是"Mooncake 性能不行"，实际上跟软件一点关系都没有。用lspci -vv查一下LnkSta字段就能确认。

4.2 接 vLLM 做 PD 分离的配置要点

Mooncake 最常见的生产用法是配合 vLLM 做 Prefill / Decode 分离。基本形态是：一部分实例只做 Prefill，算完把 KV 通过 Mooncake 传出去；另一部分实例只做 Decode，接收 KV 继续生成。这样做的收益是两类负载各自用最适合的并行策略和硬件配置，长上下文场景下吞吐提升非常明显。

启动 Prefill 实例的大致命令：

vllm serve <model_path> \ --host 0.0.0.0 --port 8100 \ --tensor-parallel-size 8 \ --kv-transfer-config '{ "kv_connector": "MooncakeConnector", "kv_role": "kv_producer", "kv_connector_extra_config": { "mooncake_protocol": "rdma", "device_name": "mlx5_0" } }'

Decode 实例把kv_role改成kv_consumer，其他的类似。这里有几个实际会踩的点。

Connector 名字跟 vLLM 版本强绑定。不同时期 vLLM 侧的名字、必需字段、甚至配置的层级结构都改过。不要照抄网上的配置，先去你装的那个 vLLM 版本对应的 Mooncake 示例脚本里抄，那个是唯一可靠的来源。如果你用的是写分布式 KV 缓存池的那个 Connector，配置结构又是另一套，多了一个指向 Master 的地址字段。

kv_producer和kv_consumer的实例数量比例不能拍脑袋定。经验值是 Prefill 实例的总算力要能覆盖住 Decode 实例的输入速率，否则 Decode 会一直等 KV。如果你的请求平均输出长度是输入长度的 5 倍以上，Decode 侧的压力会明显更大，配比要往 Decode 倾斜。这个比例上线后要基于实际的排队指标再调。

传输发生在请求的关键路径上，所以 RDMA 的延迟会直接叠加到首 token 延迟里。这也是为什么不要用 TCP 跑生产——万兆网下单次传输几百 MB 的 KV 可能就要几百毫秒，用户是能明显感知到的。

4.3 缓存容量怎么算，水位怎么设

这是生产环境里最需要算清楚的一件事。容量算小了缓存命中率上不去，算大了内存浪费、还可能影响推理服务本身。我按第一性原理给你走一遍。

先算单个 token 的 KV 大小：

单 token KV 字节数 = 2 × 层数 × KV 头数 × head_dim × 数据类型字节数

乘 2 是因为 K 和 V 各一份。注意 KV 头数在用了 GQA/MQA 的模型里远小于注意力头数，这个容易算错。举几个实际的例子：

有了这个数字，就能反推。假设你的集群有 10 个节点，每个节点愿意贡献 512 GB 内存给缓存池，总容量就是 5 TB。如果平均每个请求的上下文长度是 32k tokens，用的是 70B 级别模型，那么单个请求的 KV 就是 320 KB × 32768 ≈ 10 GB。也就是说整个缓存池大概能存 500 个请求的 KV。

这个数字决定了你的缓存命中率上限。如果并发请求数远超这个值，缓存会一直处于淘汰边缘，命中率会很难看。这时候要么加内存，要么把缓存池设计成只覆盖前缀部分——因为同一条 system prompt 或者固定的长文档前缀是命中率的主要来源，完整的 KV 反而没那么必要。

水位参数我一般这么设：高水位 0.85，淘汰比例 0.15。留 15% 的余量是为了给淘汰过程本身留周转空间，也为了避免在缓存刚满的时候出现频繁的淘汰抖动。如果你的负载有明显的突发特征，高水位可以再降一点到 0.8。

4.4 监控要盯哪些指标

Master 一般会暴露一个 metrics 端点，给 Prometheus 抓。指标名各版本有差异，但有几类是一定要看的。

提示：Prometheus 抓取间隔别设太密。Master 的 metrics 端点在大规模下每次采集都有一定开销，15 秒间隔对大多数场景够了，设成 1 秒可能会让 Master 本身成为瓶颈。

告警阈值上，我最关心的是两个：淘汰次数的增长率和传输失败率。这两个指标一异常，基本意味着服务已经在劣化，只是还没到用户能感知的程度，属于最佳干预窗口。

5. 常见问题与排查技巧实录

这一章是我自己踩过和帮别人排查过的案例汇总，按现象分类，方便你对着查。

5.1 传输类问题速查表

这里展开说两个最有代表性的。

第一个是open_segment超时。这个问题的迷惑性在于，它表现成"网络不通"，但实际上九成以上是配置问题。排查顺序应该是：先确认当前节点能连到元数据服务的端口（用 nc 或 telnet），再确认元数据服务里确实有这个 segment 的记录（用 etcdctl 直接 get 一下前缀），最后才怀疑网络。我遇到过一次是 etcd 里存的地址是一个已经不用的旧 IP，原因是节点重建后advertise-client-urls没更新，旧记录还在。

第二个是并发下的传输失败。RDMA 的 Queue Pair 数量和内存注册的 MR 数量都是有上限的，单连接测试完全看不出来，一上并发就爆。这时候应用层的报错往往很模糊，只说提交失败。我一般的做法是先把单进程的并发数从 1 往上翻倍试，找到失败的临界点，再对着网卡的资源上限去调。另一个常见原因是ulimit -l太小，RDMA 需要锁住物理内存，这个值默认可能只有 64 KB，一定要调大。

ulimit -l unlimited # 或者写进 /etc/security/limits.conf，注意需要重新登录生效

5.2 存储与内存类问题

Client 启动后内存占用远超配置值。这种情况一般是global_segment_size和local_buffer_size都配得比较大，再加上框架本身的内存，加起来超了。规划的时候要把这三块都算进去，还要给操作系统留一部分。另外一个隐蔽原因是大页配置没生效，导致 mmap 走了普通页，实际占用比预期多出一些碎片开销。

get 一直返回空，但 put 明确成功了。先确认是不是在同一台机器上 put 和 get——如果是跨机，很可能是 Master 的全局视图没建立，某个节点贡献的 segment 没有成功注册。看 Master 日志里 segment 注册的数量对不对，如果少了，去查那个节点的 Client 日志。还有一个可能是租约问题：key 写入后如果租约到期没有被续，Master 会把它当作可淘汰对象，这时候 get 会 miss。生产环境里租约时间要根据你的访问模式来设，太短会导致热点数据被误淘汰。

命中率长期偏低。这个要分情况看。如果容量使用率也很低，说明请求本身没有复用性，比如每个请求的 prompt 都不一样，那缓存确实帮不上忙。如果容量使用率很高、接近上限，那就是容量不够，要么加内存，要么就接受命中率。

5.3 上线前我会走一遍的检查清单

最后把我自己的上线前清单放出来，你可以对着过一遍。

那个日志的坑我印象很深。Transfer Engine 的 DEBUG 级别日志在传输频繁的时候一秒钟能写几十 MB，我第一次上生产忘了改，磁盘两个小时就满了，然后整个节点的服务全挂。现在我的做法是在初始化脚本里显式设置日志级别和单个文件的滚动大小，不依赖默认值。

还有内核参数这块，我建议不要手工改，直接做进基础镜像或者说初始化脚本里。手工改的问题是节点重建之后会丢，而且几十个节点你没法保证每台都改对了。大页配置尤其重要，走大页之后内存注册的开销会小很多，传输性能也更稳。

我个人在实际操作中的体会是，Mooncake 这一类系统的部署难度，八成不在它自己身上，而在周边的网络、存储、内核参数上。它本身的 API 设计其实相当克制，真正花时间的是让整个集群的硬件和系统配置达到一个"可预期"的状态。我的建议是，第一次部署的时候把每一步的命令和输出都记下来，形成一份属于你自己环境的部署手册，后面扩节点的时候照着抄，出错概率会低很多。另外别小看单机那一档的验证，我见过太多问题其实在单机阶段就能暴露出来，只是大家急着上集群，跳过了那一步。