全部文档
当前文档
最近更新时间：2026-10-13 23:31:07
客户端本地缓存数据无法共享，当本地缓存容量无法满足缓存需求时，推荐使用分布式缓存。
在大量客户端反复访问同一批文件的场景，可以使用分布式缓存将海量数据缓存到多个客户端共享。如AI训练读取数据集场景，多个客户端需要频繁访问相同的数据，单机缓存无法满足容量和性能需求，可将训练数据集缓存到多个GPU节点的空闲SSD或内存中，有效提升访问性能。
本文介绍如何通过分布式缓存提供多客户端缓存共享能力，以下仅介绍分布式缓存相关的关键参数，完整参数列表参见客户端命令集。
启用分布式缓存后，多个客户端会构成一个分布式缓存组（一个一致性哈希环），每一个缓存组的数据在组内共享。缓存组内的每个成员，需通过--cache-group设置组名，相同组名的成员即构成一个缓存组。缓存组内任何一个成员在读取文件时，会根据目前缓存组拓扑结构计算出当前数据块所在节点，并向该节点发起请求，如果数据尚未存在该节点，该节点从KPFS下载数据并存储在本地缓存盘中。
如上图所示，KPFS客户端4读取文件a（由4个数据块a1-a4组成）时，假设根据一致性哈希算法，得出a1-a4分别位于KPFS客户端1-4所在节点，因此每个成员节点都会访问KPFS，下载所需数据块。下载完毕后，KPFS客户端1-3通过内网通信，将数据块返回给KPFS客户端4，完成文件读取。
注意
建议将分布式缓存组部署在高性能（至少以万兆网络相互连接）、安全的内网环境，确定节点间通信顺畅，以获得更好的性能。
推荐用同构节点（至少缓存盘大小相同）来构建缓存组，缓存组目前的一致性哈希算法并不会考虑到不同节点的可用空间不一致，从而调整各个节点的权重，因此如果缓存组节点的磁盘大小不一致，将会在均匀分配的算法下产生空间浪费。
启用分布式缓存后，除了单客户端自身的本地数据缓存，还有来自缓存组内客户端的多级数据缓存。
读请求会依次请求内核分页缓存、客户端内存缓冲区、本地缓存，分布式缓存组，缓存中没找到对应数据时才会读取KPFS。
分布式缓存组就是由一个个 KPFS 客户端组成的，在分布式缓存组的每个节点上运行如下客户端挂载命令，组建分布式缓存。
$VOL_NAME：替换为文件系统名。
$MOUNTPOINT：替换成实际挂载的路径。
--cache-group：分布式缓存组的名称，相同组名的客户端可以组成一个分布式缓存组。
--cache-size：本地读缓存空间容量，单位MiB，示例设置为7000000MiB（需根据训练数据集的总大小 及 GPU节点空闲Nvme SSD大小 合理配置）。
--cache-dir：本地缓存目录，可将本地盘或内存作为缓存目录，多个缓存目录用：分割，目录暂不支持通配符*的写法，示例为/DATA/disk0:/DATA/disk1（可将GPU节点空闲Nvme SSD作为缓存目录）。
--group-ip（可选）：如果分布式缓存组的节点绑定了多块网卡，那可使用该参数指定节点间通信的网卡，推荐将性能好的网卡分配给缓存组，用于节点间通信，需要手动设置完整IP地址 或 CIDR类型地址。
# $VOL_NAME 替换为文件系统名，$MOUNTPOINT 则替换成实际挂载的路径，--cache-group 是用户自定义的缓存组名称
sudo /usr/local/bin/kpfs mount $VOL_NAME $MOUNTPOINT --save-conf --cache-group=mygroup --cache-size=7000000 --cache-dir=/DATA/disk0,/DATA/disk1挂载完毕后，查看客户端日志，确认缓存组已启用。
# 在KPFS日志中查看「heartbeat group」关键字，确认该客户端已加入缓存组
cat /var/log/kpfs.log |grep "heartbeat group"缓存组搭建完毕，但组内成员节点还没有缓存任何数据，为了提升应用首次访问的速度，执行预热命令，将数据预热到整个缓存组。
# 在任意缓存组成员节点运行预热命令，效果相同。
# 可预热/datadir/train-data目录下所有文件，预热的文件数据会平均分配到缓存组的所有节点
kpfs warmup /datadir/train-data
# 可预热指定文件，预热的文件数据会平均分配到缓存组的所有节点
echo '/datadir/file1
/datadir/file2
/datadir/file3' >/tmp/filelist.txt
kpfs warmup /datadir --listfile=/tmp/filelist.txt预热完成后，检查数据已缓存完成，然后执行训练。命令执行后会输出缓存状态吗：0=完全缓存、1=部分缓存、2=未缓存，并汇总已缓存字节与容量占比。
# 检查/datadir/train-data目录的缓存情况
kpfs check /datadir/train-data
# 检查指定文件的缓存情况
kpfs check /datadir --listfile=/tmp/filelist.txt适合场景：在Kubernetes集群中，客户端Pod不常驻，客户端不断被销毁、重建，可能导致缓存利用率很低。对于此类动态创建伸缩的计算集群，可以将文件系统挂载在固定几个节点，组成一个常驻、稳定的独立缓存集群（本质就是一个分布式缓存组）。示范步骤如下：
独立缓存集群：准备n个客户端，组建一个分布式缓存组，名称为mygroup，参见上文分布式缓存配置步骤。
应用侧客户端：加入独立缓存集群并启用--no-sharing参数，挂载完毕后应用侧客户端会从独立缓存集群获取数据。但不分享自己的缓存数据，避免其频繁变动，影响缓存集群的服务能力。
POSIX客户端使用
# 添加 --no-sharing 参数，虽然加入缓存组，但不向其他成员提供分布式缓存服务
sudo /usr/local/bin/kpfs mount $VOL_NAME $MOUNTPOINT --save-conf --cache-group=mygroup --cache-size=7000000 --cache-dir=/DATA/disk0,/DATA/disk1 --no-sharing
# 挂载完毕以后，如果有需要，也可以直接在 --no-sharing 挂载点上执行预热，同样能将数据预热到整个缓存组
kpfs warmup /datadir/train-data容器环境使用：使用静态PV，则在PV中的mountOptions下增加参数；使用动态PV，在StorageClass中设置同样参数。
mountOptions:
- --save-conf
- --cache-group mygroup
- --no-sharing
- --cache-size 7000000
- --cache-dir /DATA/disk0,/DATA/disk1挂载完毕后，应用侧客户端就会以「只索取，不分享」的方式来使用独立缓存集群的数据了。另外，即便对于这些客户端，多级缓存的设计依然生效。
纯净模式