最近更新时间：2025-03-03 10:12:14
KPFS支持多种缓存机制来降低访问时延和提高吞吐量，包括单客户端本地缓存以及多客户端之间的缓存共享（参见通过分布式缓存提供多客户端缓存共享能力）。数据缓存可以有效地提高随机读性能，如果您的应用需要反复读取同一批文件，使用缓存能显著提升性能。
本文介绍如何通过本地缓存提升单客户端读写性能。以下仅介绍本地缓存相关的关键参数，完整参数列表参见客户端命令参考 。
KPFS支持内核和客户端内存的多级元数据缓存架构。元数据缓存默认的挂载设置满足「关闭再打开（close-to-open）」一致性，也就是说一个客户端修改并关闭文件之后，其它客户端重新打开这个文件都会看到最新的修改。
注意 内核缓存没有任何主动失效机制（本机挂载点除外），只能等待过期淘汰，默认缓存时间为1秒，不建议调整缓存时间。
内核元数据缓存能显著提高lookup和getattr的性能，缓存项同样存在于客户端内存中。若您文件系统的文件极少变动、完全只读或需要lookup大量文件，可以考虑提高内核元数据缓存时间。客户端在挂载时可以控制如下参数：
文件属性（attribute，包含文件名、大小、权限、修改时间等信息）。
文件项（包括entry和direntry。包含文件的inode、名字、类型）。
# 文件属性缓存时间（秒），默认为 1，提升 getattr 性能
--attrcacheto=1
# 文件的缓存时间（秒），默认为 1，提升文件 lookup 性能
--entrycacheto=1
# 目录类型文件的缓存时间（秒），默认为 1，提升目录的 lookup 性能
--direntrycacheto=1注意 内存元数据缓存支持主动失效（从KPFS获取文件变更信息，异步地清理客户端内存中的元数据），默认缓存时间为5分钟。
客户端内存元数据缓存用于文件目录结构的加速访问，能显著提高lookup、getattr、access、open的性能。为保证「关闭再打开（close-to-open）」一致性，open特指打开目录，客户端open文件时默认直接访问KPFS，不会使用缓存。客户端在挂载时可以控制如下参数：
# 在客户端中缓存元数据，默认开启。可使用 --metacacheto=0 关闭缓存
--metacache
# 内存元数据的缓存时间，单位为秒，默认 5 分钟
--metacacheto=300
# 默认最多会缓存 500000 个 inodes
--max-cached-inodes=500000对于文件写入不频繁场景，可以启用--opencache（缓存时间同样受--metacacheto）控制，启用后open文件时会直接使用客户端内存中的文件属性缓存。如果您的场景中，被修改的文件需立刻被其它客户端访问，那么不建议开启--opencache。客户端在挂载时可以控制如下参数：
# 是否使用缓存的元数据来open文件，默认为false，可使用--opencache=true 开启
--opencache=falseKPFS支持内核页缓存、客户端内存缓冲区、客户端本地缓存的多级数据缓存机制
读请求会依次请求内核分页缓存、客户端内存缓冲区、本地缓存，缓存中没找到对应数据时从KPFS读取， 并且会异步写入各级缓存以保证下一次访问的性能。
写请求会先写入客户端内存缓冲区，随后写入KPFS，写入KPFS成功后，才算写入成功，内存缓冲区的数据才能释放。
客户端内存缓冲区是分配给KPFS客户端进程的一块内存，通过--buffer-size参数控制大小，默认为300MiB，读取和写入产生的数据，都会经过这个缓冲区。如果您的业务场景为大文件顺序读写（如AI模型训练读写checkpoint） 或需要进行高并发读写，可以提高--buffer-size、-max-uploads、--max-downloads大小，进而提升性能。客户端可以在挂载时调整如下参数：
# 内存缓冲区大小，单位MiB，默认300。
# 该参数对性能的影响最大，您可根据客户端实际可分配的内存资源情况动态调整，客户端整体占用内存可大致按缓冲区的4倍估算（比如，调整为4096，那客户端占用内存大致为4096 × 4 / 1024 = 8GiB）。
# 在大文件顺序读写场景下，至少将缓冲区大小调整为1024。
--buffer-size=4096
# 最大上传并发度，默认为20。
# 在大文件顺序写场景下，并不需要特意调节该参数；如果您的场景需要高并发写或者创建小文件，可提高该参数（KPFS容量Ⅰ型及容量Ⅱ型建议至多调整为64，标准型建议至多调整为256）。
--max-uploads=64
# 最大下载并发度，默认为200。默认值已经很高，一般不需要调整该值。
--max-downloads=200KPFS客户端支持将数据缓存到本地文件系统，缓存目录可以是硬盘或内存，内存无法持久化，一般在测试评估的时候使用。建议缓存目录尽量使用独立的盘，不要用系统盘，也不要和其它应用共用。
注意 本地缓存的一致性和数据可靠性与缓存盘的可靠性直接相关。
如果您的业务场景需要反复读取同一批文件，可以设置客户端本地缓存，将所有读取过的数据缓存到本地缓存，进而提升读性能。以下为本地缓存的关键参数，客户端可以在挂载时调整如下参数：
--cache-dir
缓存目录，默认为/var/jfsCache 或 $HOME/.juicefs/cache。支持传入多个缓存盘目录，使用多块盘进行缓存，以提升总体缓存I/O。支持传入/dev/shm，使用内存作为缓存。支持传入memory字符串直接使用进程内存作为缓存。当设置了多个缓存目录，客户端会采用hash策略向各个缓存路径中均匀地写入数据，因此建议不同缓存目录的可用空间保持一致，否则可能造成不能充分利用某个缓存目录的情况。
# 可使用多块盘作缓存目录，用:分割，目录可包含通配符 *
--cache-dir=/data*/cache:/mydata*/cache
# 可使用内存作缓存目录
--cache-dir=/dev/shm
# 可使用客户端进程内存作为缓存
--cache-dir=memory--cache-size 与 --free-space-ratio
缓存空间总容量（单位MiB，默认102400）与缓存目录的最少剩余空间占比（默认0.1）。这2个参数任意一个达到阈值，均会触发缓存淘汰，淘汰时会随机选取两个数据块，淘汰访问时间更早者。
例如：-cache-dir 为 /data1，其中 /data 的可用空间为 4GiB，--cache-size 为 4GiB，--free-space-ratio 为 0.05，则分配给缓存目录的最大空间为4GiB×（1 - （free-space-ratio）） ，即4GiB × （1-0.05）=3.8GiB，超出后将会触发缓存淘汰。
# 缓存空间总容量，设置为4096（4GiB）
--cache-size=4096
# 缓存目录最少剩余空间占比，设置为0.05
--free-space-ratio=0.05--cache-partial-only
读取数据的时候，仅缓存小于4MiB的数据块，相当于缓存不足 4MiB 的小文件，以及大文件末尾不足4MiB的数据块。该参数默认为false，也就是所有读取的数据块都会被缓存。如果您的缓存盘吞吐不高或大文件仅顺序读一次，可将该参数设置为true。
--cache-partial-only=true注意
KPFS客户端内置坏盘检测机制，如果一段时间内发生大量读盘失败（或超时），客户端将会摘除并弃用缓存盘。因此，如果本地盘性能太差，不建议用作缓存盘。
读缓存的数据默认存放在
/var/jfsCache/<vol-name>/raw/，只能删除末尾的raw目录，而不能整体删除/var/jfsCache/<vol-name>目录。
在AI训练场景中，可以通过缓存预热来将数据集提前预热到缓存目录，从而在训练任务开始时直接命中缓存，提高训练效率。客户端可以使用如下命令：
juicefs warmup
将文件提前下载到缓存，提升后续本地访问的速度。可以指定某个挂载点路径 或 通过--file选项指定文本文件，在文本文件中指定需要预热的文件名。
# 预热挂载点目录中的所有文件
juicefs warmup /datadir
# 预热挂载点某子目录中的所有文件
juicefs warmup /datadir/train-data
# 预热指定文件
echo '/datadir/file1
/datadir/file2
/datadir/file3' >/tmp/filelist.txt
juicefs warmup -file=/tmp/filelist.txt写缓存仅推荐在特定业务场景下使用，如大量小文件写入（如解压包含大量小文件的压缩文件），启用客户端写缓存后，会默认把小于4MiB的数据写入到本地缓存，进而提升写入性能。写入流程变为先写入内存缓冲区，随后写入本地缓存目录，后台异步写入KPFS。客户端可以在挂载时调整如下参数：
--writeback
启用客户端写缓存，默认为false。
# 启用客户端写缓存，设置为true
--writeback = true注意
如果本地盘写性能太差，启用
--writeback会带来更差的写性能。写缓存的数据默认存放在
/var/jfsCache/<vol-name>/rawstaging/，这个目录存放着待上传的文件数据，误删或损坏意味着数据丢失。启用写缓存后，在写入KPFS未完成前，数据无法被其他客户端读到。
写缓存和读缓存共享缓存目录空间，因此会相互影响。例如写缓存占用过多的磁盘空间，那么将导致读缓存的大小受到限制，反之亦然。
写缓存大小同样由
--free-space-ratio控制。如果开启写缓存，则客户端最多使用缓存目录（1 - （free-space-ratio / 2）） * 100的空间。
KPFS控制台包含本地缓存相关监控图表，可以在控制台查看相关监控指标，请参见文件系统监控；也可以通过API获取相关监控指标数据，请参见查询文件系统监控信息。
纯净模式
