全部文档
当前文档
最近更新时间：2026-10-13 23:31:07
KPFS支持多种缓存机制来降低访问时延和提高吞吐量，包括单客户端本地缓存以及多客户端之间的缓存共享（参见通过分布式缓存提供多客户端缓存共享能力）。数据缓存可以有效地提高随机读性能，如果您的应用需要反复读取同一批文件，使用缓存能显著提升性能。
本文介绍如何通过本地缓存提升单客户端读写性能。以下介绍本地缓存相关的关键参数。
KPFS支持客户端内存的多级元数据缓存架构。元数据缓存默认的挂载设置满足「关闭再打开（close-to-open）」一致性，也就是说一个客户端修改并关闭文件之后，其它客户端重新打开这个文件都会看到最新的修改。
注意 内核缓存没有任何主动失效机制（本机挂载点除外），只能等待过期淘汰，默认缓存时间为1秒，不建议调整缓存时间。
内核元数据缓存能显著提高lookup和getattr的性能，缓存项同样存在于客户端内存中。若您文件系统的文件极少变动、完全只读或需要lookup大量文件，可以考虑提高内核元数据缓存时间。客户端在挂载时可以控制如下参数：
文件或目录属性（attribute，包含文件名、大小、权限、修改时间等信息）。
文件项（仅包括direntry。包含文件的inode、名字、类型）。
# 文件/目录属性缓存时间（秒），默认为 5，提升 getattr 性能
--attr-timeout-s=5
# 目录类型文件的缓存时间（秒），默认为 5，提升目录的 lookup 性能
--entry-timeout-s=5注意
若内存中存在元数据缓存，则客户端open文件或目录时默认均会使用内存的元数据缓存。
请务必注意，由于目前客户端内存元数据缓存不支持主动失效，即：文件或目录元数据已缓存在客户端A，客户端B修改并关闭了文件；在客户端A的内存元数据缓存未失效前，会默认使用内存元数据缓存重新打开该文件，会有短暂的元数据不一致情况。
客户端内存元数据缓存用于文件目录结构的加速访问，能显著提高lookup、getattr、access、open的性能。内存元数据缓存默认打开，客户端在挂载时可以控制如下参数：
# 文件的属性在内存中的过期时间（秒），默认为5。
--file-meta-cache-s=5
# 目录的属性在内存中的过期时间（秒），默认为5。
--dir-meta-cache-s=5
# 默认最多会缓存1000个inodes
--inode-cache-lru-count=1000KPFS支持内核页缓存、客户端内存缓冲区、客户端本地缓存的多级数据缓存机制。
读请求会依次请求内核分页缓存、客户端内存缓冲区、本地缓存，缓存中没找到对应数据时从KPFS读取， 并且会异步写入各级缓存以保证下一次访问的性能。
写请求会先写入客户端内存缓冲区，随后写入KPFS，写入KPFS成功后，才算写入成功，内存缓冲区的数据才能释放。
客户端内存缓冲区是分配给KPFS客户端进程的一块内存，通过--read-slice-cache-size和--write-slice-cache-size参数控制大小，默认均为32768MiB，读取和写入产生的数据，都会经过这个缓冲区。读写缓冲区实际可用百分比默认不超过总设置值的30%，且最大不超过机器内存的40%，防止出现机器内存占用过多的情况。
# 读缓冲区大小，单位MiB，默认为32768MiB
--read-slice-cache-size=32768
# 写缓冲区大小，单位MiB，默认为32768MiB
--write-slice-cache-size=32768
# 读写缓冲区百分比限制，默认30
--buffer-limit-percent=30KPFS客户端支持将数据缓存到本地文件系统，缓存目录可以是硬盘或内存，内存无法持久化，一般在测试评估的时候使用。建议缓存目录尽量使用独立的盘，不要用系统盘，也不要和其它应用共用。
注意 本地缓存的一致性和数据可靠性与缓存盘的可靠性直接相关。
如果您的业务场景需要反复读取同一批文件，可以设置客户端本地缓存，将所有读取过的数据缓存到本地缓存，进而提升读性能。以下为本地缓存的关键参数，客户端可以在挂载时调整如下参数：
--cache-dir
本地缓存目录，若您使用本地读缓存，则该参数必须设置。支持传入多个缓存盘目录，使用多块盘进行缓存，以提升总体缓存I/O。当设置了多个缓存目录，客户端会采用hash策略向各个缓存路径中均匀地写入数据，因此建议不同缓存目录的可用空间保持一致，否则可能造成不能充分利用某个缓存目录的情况。读缓存及写缓存会共享缓存目录。
# 可使用多块盘作为缓存目录，用,分割，目录暂不支持通配符*的写法
--cache-dir=/data/cache,/mydata/cache--cache-size
本地读缓存空间容量（单位MiB），默认为0，若您使用本地读缓存，则该参数必须设置。注意：该参数限制的为单缓存目录。例如：--cache-dir 为 /data:/mydata，其中 /data及/mydata的可用空间分别为 4GiB，--cache-size 限制为 3GiB，则分配给读缓存的最大空间为3+3=6GiB，超出后将会触发读缓存淘汰。
# 设置为3072（3GiB）
--cache-size=3072在AI训练场景中，可以通过缓存预热来将数据集提前预热到缓存目录，从而在训练任务开始时直接命中缓存，提高训练效率。客户端可以使用如下命令：
kpfs warmup
将文件提前下载到缓存，提升后续本地访问的速度。可以指定某个挂载点路径 或 通过--listfile选项指定文本文件，在文本文件中指定需要预热的文件名。
# 预热挂载点目录中的所有文件
kpfs warmup /datadir
# 预热挂载点某子目录中的所有文件
kpfs warmup /datadir/train-data
# 预热指定文件
echo '/datadir/file1
/datadir/file2
/datadir/file3' >/tmp/filelist.txt
kpfs warmup /datadir --listfile=/tmp/filelist.txt写缓存仅推荐在特定业务场景下使用，如大量小文件写入（如解压包含大量小文件的压缩文件），以提升写入性能。写入流程变为先写入内存缓冲区，随后写入本地缓存目录，后台异步写入KPFS。客户端可以在挂载时调整如下参数：
--cache-dir
本地缓存目录，若您使用本地写缓存，则该参数必须设置。支持传入多个缓存盘目录，使用多块盘进行缓存，以提升总体缓存I/O。当设置了多个缓存目录，客户端会采用hash策略向各个缓存路径中均匀地写入数据，因此建议不同缓存目录的可用空间保持一致，否则可能造成不能充分利用某个缓存目录的情况。写缓存及读缓存会共享缓存目录。
# 可使用多块盘作为缓存目录，用,分割，目录暂不支持通配符*的写法
--cache-dir=/data/cache,/mydata/cache--ssd-write-cache-gb
本地写缓存空间容量（单位GiB），默认为128GiB。注意：该参数限制的为单缓存目录。例如：--cache-dir 为 /data:/mydata，其中 /data及/mydata的可用空间分别为 128GiB，--ssd-write-cache-gb 限制为 100GiB，则分配给写缓存的最大空间为100+100=200GiB。
# 设置为100GiB
--ssd-write-cache-gb=100--writeback
启用客户端写缓存，默认关闭
# 启用客户端写缓存，设置为1
--writeback=1注意
如果本地盘写性能太差，启用
--writeback会带来更差的写性能。写缓存的数据默认存放在
--cache-dir目录的以“文件系统名+挂载点+关键字Write”组合的子目录下，这个目录存放着待上传的文件数据，误删或损坏意味着数据丢失。启用写缓存后，若您未启用分布式缓存组，在写入KPFS未完成前，数据无法被其他客户端读到。
写缓存和读缓存共享缓存目录空间，因此会相互影响。例如写缓存占用过多的磁盘空间，那么将导致读缓存的大小受到限制，反之亦然。
KPFS控制台包含本地缓存相关监控图表，可以在控制台或API查看相关监控指标，请参见文件系统监控。
纯净模式