Skip to main content

命令参考

在终端输入 juicefs 并执行，就能看到所有可用的命令。在每个子命令后面添加 -h/--help 并运行，就能获得该命令的详细帮助信息，例如 juicefs mount -h。

NAME:
   juicefs - A POSIX file system built on object storage.

USAGE:
   juicefs [global options] command [command options]

VERSION:
   5.3.7 (2026-04-22 58af72b)

COMMANDS:
   help, h  Shows a list of commands or help for one command
   ADMIN:
     auth     Authorize a volume
     destroy  Destroy an existing volume
     gc       Garbage collector of objects in data storage
     fsck     Check consistency of a volume
     dump     Dump metadata into a JSON file
     load     Load metadata from a previously dumped JSON file
     version  Show version
     quota    Manage directory quotas
     heal     Heal a replicated volume
     restore  restore files from trash
   INSPECTOR:
     status         Show status of a volume
     stats          Show real time performance statistics of JuiceFS
     profile        Show profiling of operations completed in JuiceFS
     info           Show internal information of a path or inode
     summary        Show data and files distribution of a directory
     debug, doctor  Collect and display system static and runtime information
     lsof           List open files
   SERVICE:
     mount    Mount a volume
     umount   Unmount a volume
     gateway  Start an S3-compatible gateway
     webdav   Start a WebDAV server
   TOOL:
     attr              Manage attributes for files and directories
     bench, benchmark  Run benchmarks on a path
     objbench          Run benchmarks on an object storage
     warmup            Build cache for target directories/files
     clone, snapshot   Clone a file/directory without copying data
     rmr               Remove directories recursively
     sync              Sync between two storages
     import            Import existing files from object storage
     merge             merge files together without copying.
     find              find files with predicates and actions
     grep              parallelized file pattern searcher
     compact           Trigger compaction of chunks

GLOBAL OPTIONS:
   --verbose, --debug, -v  enable debug log (default: false)
   --quiet, -q             show warning and errors only (default: false)
   --trace                 enable trace log (default: false)
   --trace-file value      write runtime trace to a file (use 'go tool trace' to analyze)
   --no-agent              disable pprof (:6060) agent (default: false)
   --pyroscope value       pyroscope address
   --no-color              disable colors (default: false)
   --help, -h              show help
   --version, -V           print version only (default: false)

全局选项​

项说明
-q --quiet仅显示警告及错误日志。
-v --verbose --debug开启调试日志。
--trace开启比 --debug 选项更详细的调试日志。
--no-agent关闭 pprof 代理。
--pyroscope配置 Pyroscope 地址，如 http://localhost:4040。
--no-color关闭日志的颜色。

管理​

juicefs auth​

向 JuiceFS Web 控制台发起认证并获取文件系统的配置。配置文件会保存为 $HOME/.juicefs/$VOL_NAME.conf。该命令的常见使用场景：

  • 大量节点需要挂载时，直接运行 juicefs mount 会遇到交互式录入，不方便自动化。因此用 juicefs auth 命令提前认证、获取配置文件。可以参考「自动化部署」；
  • 如果对象存储的认证信息（Access Key、Secret Key）或者存储桶本身发生变化，也需要重新运行 juicefs auth，更新相关信息。比方说对象存储桶迁移到了其他区域，或者变更了对象存储供应商，客户端都需要更新配置；
  • ​私有部署元数据节点 IP 或者控制台地址发生变更，也需要用 juicefs auth 重新认证、获取新的配置。大部分迁移变更操作都是平滑的，因此只需要更新客户端配置文件即可，并不需要重新挂载（需要根据具体执行计划，咨询 Juicedata 工程师）；
  • 对于 CSI 驱动场景，如果元数据服务、对象存储、私有控制台的服务地址发生了变更，则需要更新「文件系统认证信息」，CSI 驱动会自动运行 juicefs auth，更新客户端的配置文件缓存。

概览​

juicefs auth NAME [options]

juicefs auth myjfs --token xxx --access-key xxx --secret-key xxx

参数​

项说明
NAME文件系统的名字。
--token=TOKEN文件系统的 Token，在网站控制台的文件系统设置中查看。
--bucket=BUCKET在文件系统创建之初，对象存储桶已经在控制台设置好了。但如果有需要，可以使用该参数覆盖桶设置，比如因为网络环境不同，某些客户端需要使用特定的对象存储服务地址。

和控制台的文件系统的桶设置一样，该参数既可以填写桶名，也可以填写完整 endpoint（以 https:// 或 http:// 开头），这两种填写方法的区别如下：

  • 只填写桶名，客户端会自动根据网络情况智能选择内外网 endpoint（如果对象存储支持）。以 OSS 杭州区域 为例，如果传入 --bucket=test，那么挂载前客户端会进行网络测试，自动选择 https://test.oss-cn-hangzhou-internal.aliyuncs.com 或者 https://test.oss-cn-hangzhou.aliyuncs.com。
  • 显式填写完整 endpoint，例如 https://test.oss-cn-hangzhou-internal.aliyuncs.com，那么客户端会尊重该配置，不再智能选择。
对象存储的服务地址通常会解析出多个 IP，JuiceFS 客户端会在每次请求随机挑选可用地址，来达到负载均衡的效果。这个行为对应的代码在社区版和商业版都是复用的，因此可以直接参考社区版源码。
--access-key=ACCESSKEY对象存储的密钥，获取方式参见 文档。如不指定则需要交互式录入。如果云主机已经配置免密访问对象存储，则传入空字符串（或者在交互式录入时直接按回车键跳过）即可。
--secret-key=SECRETKEY对象存储的密钥，获取方式参见 文档。如不指定则需要交互式录入。如果云主机已经配置免密访问对象存储，则传入空字符串（或者在交互式录入时直接按回车键跳过）即可。
--session-token=SESSIONTOKEN对象存储 session token（可选）
--shards=0与社区版的 --shards 作用相同。企业版 JuiceFS 文件系统一般使用可以方便扩容并提升性能的对象存储，不轻易达到单桶的容量或性能上限，因此该参数更多是为了和社区版保持兼容，如果不是单桶服务能力有限的自建对象存储，一般不主动使用多桶拆分，这样会增加管理复杂度。
--storage-class=value目标端的新建文件的存储类型（也叫存储级别，可以阅读相应文档了解更多：S3、OSS），如果目标端存储支持的话。
--bucket2=BUCKET2用于文件系统复制功能的目标对象存储 Bucket 名称或 endpoint 地址，格式和注意事项同 --bucket。
--access-key2=ACCESSKEY2开启文件系统复制功能时，目标对象存储密钥（可选）。文件系统复制请详见「跨区数据复制」。
--secret-key2=SECRETKEY2开启文件系统复制功能时，目标对象存储密钥（可选）。文件系统复制请详见「跨区数据复制」。
--session-token2=SESSIONTOKEN2开启文件系统复制功能时，目标对象存储的 session token（可选）文件系统复制请详见「跨区数据复制」。
--shards2=0如果开启了文件系统复制功能，那么 --shards2 需要对齐 --shards。
--passphrase=PASSPHRASE加密密钥的密码，关于数据加密详见「数据加密」。
--encrypt-keys加密对象存储认证信息，默认为 false。
--subdir=SUBDIR对将要挂载的子目录进行认证，如果需要的话，还可以创建出限制只允许访问子目录的客户端令牌，详见「客户端权限控制」。
--conf-dir=CONFDIR配置文件目录，默认 ~/.juicefs
--no-update客户端会从默认控制台获取最新的配置，将该参数设为 true 以禁用此行为，客户端挂载时将不再访问 JuiceFS 控制台。

juicefs gc​

用来清理对象存储数据泄漏。如果发现对象存储用量远大于文件系统大小，并且也排除了回收站留存、短时间内大量覆盖写等情况，说明可能发生了对象存储泄漏，需要运行该命令来检查泄漏情况，以及清理这些泄漏数据。

造成泄漏的常见原因是对象存储长时间服务异常，造成清理回收站数据的删除请求大量、反复失败，此时元数据服务为了减小内存压力，会在失败一定次数以后停止重试，直接删除对应的元数据。待对象存储服务恢复以后，由于元数据已经清理，对应的对象存储块将不会再重试删除，造成泄漏。

概览​

juicefs gc [command options] VOLUME-NAME

# 只检查并打印结果，不进行实际清理
juicefs gc $VOL_NAME

# 删除泄露的对象
juicefs gc $VOL_NAME --delete

参数​

项说明
--delete删除泄漏的对象 (默认：false)
--threads=10, -p 10并发线程数，默认为 10。

juicefs fsck​

检查文件系统一致性，如果文件对应的对象存储数据块缺失，可以用该命令检查出来。

概览​

juicefs fsck [command options] VOLUME-NAME

juicefs fsck $VOL_NAME

参数​

项说明
--threads=10, -p 10并发线程数，默认为 10。
--repair修复对象命名的哈希前缀。JuiceFS 企业版给每个对象路径命名添加 hash 前缀（用 slice ID 对 256 取模，原理和社区版 --hash-prefix 相同），相当于“打散”对象存储键值，避免在对象存储服务层面创造请求热点。

如果文件系统因为某些原因并未启用哈希前缀（比如从社区版导入未启用该特性的文件系统），可以用该参数进行修复。

juicefs dump​

导出元数据。与社区版不同，JuiceFS 企业版并不需要用导出元数据的方式进行备份——Juicedata 工程师已经在元数据服务层面做好了定期备份。因此该命令通常用于问题排查，以及在社区版、企业版之间相互迁移数据。

如何导入导出元数据，详见「导入文件系统」。

概览​

juicefs dump [command options] PATH JSON-PATH

# 导出元数据至 meta-dump.json
juicefs dump /jfs meta-dump.json

# 只导出文件系统的一个子目录的元数据
juicefs dump /jfs/subdir meta-dump.json

参数​

项说明
PATH挂载点路径。
JSON-PATH导出文件路径。如果文件名以 .gz 结尾，将会自动使用 gzip 进行压缩。
--gzip用 gzip 压缩导出结果。

juicefs load​

将元数据导入一个空的文件系统，该命令常用于从社区版迁移数据至企业版，详见「导入文件系统」。

概览​

juicefs load [command options] PATH [FILE]

# 将元数据备份文件 meta-dump.json.gz 导入文件系统
juicefs load /mnt/jfs meta-dump.json.gz

juicefs version​

用来打印当前版本，或者升级版本。在版本更新页可以查看每个版本的更新详情。

概览​

juicefs version [options]

# 用一行命令完成升级、平滑重启
juicefs version -u -r

# JuiceFS 客户端新版发布之时，可能存在某些兼容性问题
# 可以用下方环境变量完成大版本的回滚，比方说从 5.2 降级到 5.1
export JFSCHAN=5.1
juicefs version -u

参数​

项说明
-u --upgrade升级客户端到最新版。
-r --restart如果客户端发生了升级，则执行平滑重新挂载。

juicefs quota​

管理目录配额的子命令，与社区版不同，企业版通过 Web 控制台来创建和管理配额，用户不应直接使用该命令。这个命令的存在是为了与社区版保持一致，让 CSI 驱动能够以相同的接口来管理 PV 配额。

juicefs heal​

「数据复制」场景下修复数据，运行双向数据同步，使两个对象存储数据保持一致。

概览​

juicefs heal VOL-NAME [options]

参数​

项说明
--start=value用于指定对象存储的同步范围。
--upload-limit=0上传数据所用带宽的上限，单位 Mbps，默认为 0（无限制）。
--conf-dir配置文件目录，默认 ~/.juicefs

检视​

juicefs status​

显示文件系统的基本状态，包括活跃的客户端会话列表（FUSE 挂载客户端、Hadoop SDK、S3 网关和 WebDAV）。

概览​

juicefs status [command options] VOLUME-NAME

juicefs status $VOL_NAME

参数​

项说明
--session=0 -s 0传入会话 ID（Session ID，也就是 status 命令输出的 SID），展示指定会话的具体信息。

juicefs stats​

stats 命令通过读取 JuiceFS 客户端的监控指标，打印各个指标的每秒变化情况。该命令可以通过 --schema 和 --verbosity 参数调整输出格式和级别，可以使用 -l 1 --schema=ufmcaro 来打印所有可用信息，效果如下：

$ juicefs stats -l 1 --schema="ufmcaro" /jfs
---------usage--------- ----------fuse--------- ----------meta--------- ----blockcache--- -------------readahead------------ ------------------------------remotecache------------------------------ ------------------------object-----------------------
 cpu   mem   buf  cache| ops   lat   read write| ops   lat   send  recv| read write evict| used winvl wclup wshrk wfree wclos| read  rd_c  lat  write  wr_c  lat   db_c  lat   pr_c  lat   wb_c  lat | get  get_c  lat   put  put_c  lat   del  del_c  lat
 0.0%  124M   32M   44M|   0     0     0     0 |   0     0     0     0 |   0     0     0 |   0     0     0     0     0     0 |   0     0     0     0     0     0     0     0     0     0     0     0 |   0     0     0     0     0     0     0     0     0

各个板块指标介绍：

usage：

  • cpu：进程的 CPU 使用率。
  • mem：进程的物理内存使用量。
  • buf：进程已使用的读写缓冲区大小，如果该数值逼近甚至超过客户端所设置的 --buffer-size，说明读写缓冲区空间不足，需要视情况扩大，或者降低应用读写负载。

fuse：

  • ops/lat：通过 FUSE 接口处理的每秒请求数及其平均时延，单位为毫秒。
  • read/write：通过 FUSE 接口处理的读写带宽。需要注意 FUSE 视角统计的读数据量，未必是客户端真实的读带宽：文件读取后，数据会进入内核页缓存，下次读取时不会再经过 FUSE，导致 FUSE read 比实际值低，甚至完全为 0。

meta：

  • ops/lat：每秒处理的元数据请求数和平均时延，单位为毫秒。注意部分能在缓存中直接处理的元数据请求未列入统计，以更好地体现客户端与元数据引擎交互的耗时。

blockcache：

代表本地数据缓存，如果读请求已经被内核缓存，那么流量将不会体现在 blockcache 相关指标下。因此如果反复读取相同文件，却发现持续产生 blockcache 流量，说明文件始终未能被内核页缓存收录，考虑往该方向排查（比如内存吃紧，不足以缓存更多文件）。

  • read/write：客户端本地数据缓存的每秒读写流量。

readahead：

预读数据浪费相关的指标，如果发生不符合预期的读放大，可以通过该板块相关指标，来判断是否存在浪费，以及浪费的具体原因。

  • used：预读数据中，实际被读到、没有浪费的部分。
  • winvl：w 代表 wasted，invl 代表 invalid，该指标表示有文件被写入更新引起的预读失效的数据量。
  • wclup：clup 代表 cleanup，表示读范围没有交集而被主动抛弃的预读数据。
  • wshrk：shrk 代表 shrink，表示由于读写缓冲区大小不足，被后台线程抛弃的预读数据。
  • wfree：缓冲区内存由于其他原因主动释放所导致的浪费，比方说，预读窗口不仅会随着顺序读而变大，也会随着读速度的变化而缩小，那么由于预读窗口大小调整而被抛弃的预读数据，会计入在该指标。
  • wclos：文件被关闭导致预读数据被释放的部分。

remotecache：

分布式缓存相关指标。

  • read/rd_c/lat：从缓存组读取的数据量、读请求数、延迟。
  • write/wr_c/lat：缓存组的写请求数据量、写请求数、延迟。

object：

代表与对象存储相关指标，在缓存场景下，读请求穿透到对象存储，将会明显降低读性能，可以用该指标来断定数据是否完整缓存。另一方面，通过对比 object.get 和 fuse.read 的数据，也能初步判断读放大的情况。

  • get/put：客户端与对象存储交互的 GetObject/PutObject 每秒流量。

该命令的更多介绍和用法详见「实时性能监控」。

概览​

juicefs stats [options] MOUNTPOINT

参数​

项说明
--schema=ufmcro控制输出内容的标题字符串，默认为“ufmcro”，含义如下：
u: usage
f: FUSE
m: meta
c: blockcache
r: remotecache
o: object
a: readahead
g: go
--interval=1更新间隔，单位为秒，默认为 1。
--verbosity=0 -l 0详细级别，默认为 0，使用 1 来获得更详细输出。特别地，当 --schema 包含读放大相关指标时，使用 -l 1 能够打印更详细的相关指标，指征读放大浪费的具体原因。

juicefs profile​

对「文件系统访问日志」进行简单直观的统计，在命令行展示各项操作的耗时统计数据，帮助你迅速判断应用对文件系统的访问模式，评估访问性能。

该命令的更多介绍和用法详见「实时性能监控」。

概览​

juicefs profile [command options] MOUNTPOINT/LOGFILE

# 对指定挂载点进行文件系统访问耗时统计，假设挂载点并不是默认的 /jfs，而是 /mnt/jfs
juicefs profile /mnt/jfs

# 对提前收集好的离线访问日志进行重放
cat /jfs/.oplog > /tmp/op.log
juicefs profile /tmp/op.log

参数​

项说明
-g GROUP_BY --group-by=GROUP_BY根据指定属性对输出结果进行分组，默认为 cmd，可选值为：uid、pid、cmd。
-s SORT_BY --sort-by=SORT_BY根据指定列对输出结果进行排序，默认为 total_time，可选值为：group、number、avg_time、total_time。
-u FILTER_BY_UID --filter-by-uid=FILTER_BY_UID根据 UID 对输出结果进行过滤，多个关键词使用半角逗号（,）分隔。
-p FILTER_BY_PID --filter-by-pid=FILTER_BY_PID根据 PID 对输出结果进行过滤，多个关键词使用半角逗号（,）分隔。
-w WINDOW_SIZE --window-size=WINDOW_SIZE统计时间窗口大小，浮点数，单位为秒，默认为 60。
-i FLUSH_INTERVAL --flush-interval=FLUSH_INTERVAL输出的刷新间隔，浮点数，单位为秒，默认为 2。

juicefs info​

显示 JuiceFS 文件系统中文件或 inode 的信息。

概览​

juicefs info [command options] PATH/INODE

# 查询文件
juicefs info /mnt/jfs/foo

# 查询目录
juicefs info -r /mnt/jfs/bar/

# 通过 inode 反查文件信息
cd /mnt/jfs
juicefs info -i 100

参数​

项说明
PATH/INODE要查询的路径或 inode。
-i --inode通过 inode 查询文件信息，注意当前目录必须在 JuiceFS 挂载点中。
-r --recursive递归获取目录中所有子目录及文件的信息。
--raw显示内部原始信息。

juicefs summary​

显示目标目录树摘要。

概览​

juicefs summary [command options] PATH

juicefs summary /jfs/foo

# 显示最大深度为 5
juicefs summary --depth 5 /jfs/foo

# 显示前 20 个 entry
juicefs summary --entries 20 /jfs/foo

参数​

项说明
--depth=2 -d 2显示树的深度，0 表示只显示根，默认为 2。
--entries=10 -e 10显示前 N 个 entry，按大小排序，默认为 10。
--csv以 CSV 格式打印摘要。

juicefs doctor​

又名 juicefs debug。全面收集各种用于排查的信息，包括访问日志、客户端日志、CPU 性能统计、Goroutine 堆栈等。遇到一些疑难杂症时，JuiceFS 团队可能会要求你使用该命令打包收集报错信息，来帮助解决你的问题。

我们也鼓励你阅读「问题排查方法」和「问题排查案例」，来尝试自己上手分析和解决一些常见问题。

概览​

juicefs doctor MOUNTPOINT

juicefs lsof​

列出 JuiceFS 最近（10 分钟内）被打开过的文件。

概览​

juicefs lsof PATH

服务​

juicefs mount​

挂载文件系统。挂载时必须提供文件系统的 Token（在网站控制台的 文件系统设置 中查看），以及访问对象存储 API 的秘钥对（参考文档 如何获取对象存储的 API 密钥）。

如果挂载文件系统之前没有通过 auth 子命令生成配置文件，那么客户端会以命令行交互的方式要求你分别提供文件系统 Token 和访问对象存储 API 的秘钥对。

JuiceFS 支持用 root 以及普通用户挂载，但由于权限不同，挂载时所使用的的缓存目录和日志文件等路径会有所区别，详见下方参数说明。

概览​

juicefs mount NAME MOUNTPOINT [options]

参数​

项说明
NAME文件系统的名字。
MOUNTPOINT主机上的挂载路径，比如：/jfs。
--foreground
-f		前台运行，客户端日志也会直接在前台输出，此选项多用于调试。
--background
-b
-d		后台运行，这也是默认行为。
--no-syslog禁用 syslog。
--log=PATH日志存储路径，视挂载用户不同，默认为 /var/log/juicefs.log 或 ~/.juicefs/log/juicefs.log。
--update-fstab在 Linux 挂载时，更新 /etc/fstab，详见 开机自动挂载。
--max-space限制挂载点的总大小。对于按量付费的用户而言，JuiceFS 并没有实际容量上限，因此 df -h 会显示非常大的值。设置该选项来限制挂载点的容量上限，同时将 df -h 的容量上限设为对你的场景更合理的数值。
--prefix-internal为内部文件添加 .jfs 前缀，例如 .jfs.stats， .jfs.config。
--hide-internal隐藏所有内部文件（.accesslog， .stats 等）。
--sort-dir通过 readdir 读取挂载点目录内容，默认会返回乱序列表，如果打算在 JuiceFS 挂载点上部署 nfsd 等通过翻页来读取目录的系统，乱序会引起故障，需要启用该参数，然后读取目录返回的文件列表将按命名排序。注意，该选项并不影响 ls 等 Linux 工具的输出，ls 自身便会对结果进行排序。
--token=TOKEN指定客户端令牌。
--no-update客户端会从默认控制台获取最新的配置，将该参数设为 true 以禁用此行为，客户端挂载时将不再访问 JuiceFS 控制台。
--umask=0022指定文件系统的 umask，用于调整新建目录和文件时的默认权限，默认值是 0022（注意最前面的 0 不能省略，表示这是一个八进制数）。例如设置为 0000，新目录的默认权限就是 777，新文件的默认权限就是 666。
--schedule-priority=nice指定客户端主进程的 nice 值，可设置的范围是 -20~99。
--no-sync当设置 --Bucket2 后，定期每 7 天会对桶数据做一次双向同步，而使用 --no-sync 参数会禁用这一操作。用户在带宽受限的环境中使用此参数可以减少不必要的网络流量。注意即使启用此参数，源集群更改的文件还是会通知到镜像集群来拉取数据块，数据仍可以保持一致性，但不再有源集群从镜像拉取数据的情况。用户可以自行按需进行两桶数据匹配。

FUSE 相关参数​

项说明
--enable-xattr开启扩展文件属性 xattr 的支持。默认为 false，如果没有特殊需要建议关闭，会产生额外开销。
--enable-acl开启 POSIX Extended ACL 的支持，详见 ACL。
--no-bsd-lock禁用 BSD lock 支持。
--no-posix-lock禁用 POSIX lock 支持。
--block-interrupt=1中断信号的阻塞时间（单位为秒），默认为 1。
--readdir-cache在内核中建立 readdir 缓存（需要 Kernel 4.20 及以上）。
--allow-other允许其他用户访问（当用 root 挂载时默认开启，否则需要在 /etc/fuse.conf 中启用 user-allow-other）。
--max-write 新增自 v5.1.0FUSE 读、写请求的单位，默认为 "128K"。修改该选项需要内核 4.20 或以上版本，并且上限为 1MiB。如果系统不存在其他瓶颈，提高该值可以增加顺序写性能，但是相应地也会影响随机写或小追加写的性能，需要充分测试、谨慎调优。
-o FUSE_OPTS添加其他 FUSE 选项。如通过 -o writeback_cache 开启 FUSE 写缓存可以极大提高随机写入和碎片写入的性能（需要使用 Linux Kernel 3.15 及以上）。可进一步参考 FUSE 挂载选项 的简要说明，以及社区版完整文档。

元数据相关参数​

项说明
--case-insensitive查找文件时忽略大小写（默认：不忽略）
--no-bgjob禁止后台任务（默认：允许）
--subdir=SUBDIR挂载子目录，如果需要的话，还可以创建出限制只允许访问子目录的客户端令牌，详见「客户端权限控制」。

元数据缓存相关参数​

项说明
--metacacheto=300元数据的缓存过期时间（单位为秒），默认为 300。
--metacache将元数据缓存在运行客户端的主机的内存里，默认启用。使用 --metacacheto=0 关闭缓存。
--max-cached-inodes=500000Inodes 的最大缓存数量，默认为 500000。
--open-cache
--opencache		是否使用缓存的元数据来打开文件，默认为 false，也就是说每次打开文件时都会访问元数据服务，确认文件是否被更改过。因此在需要频繁打开文件，而修改又较少时（建议针对只读场景开启），可以考虑启用 --opencache，进一步提升读性能。仅对于同一个挂载点，读缓存会根据文件变更自动失效。
--attr-cache
--attrcacheto=1		文件/目录的属性在内核中的缓存时间（秒），默认为“1.0s”。
--entry-cache
--entrycacheto=1		文件项在内核中的缓存时间（秒），默认为“1.0s”。
--dir-entry-cache
--direntrycacheto=1		目录项在内核中的缓存时间（秒），默认为“1.0s”。

对象存储相关参数​

项说明
--get-timeout=60下载单个对象的最长时间（秒），默认为 60。低带宽场景下可能需要适当增大，详见读写错误
--put-timeout=60上传单个对象的最长时间（秒），默认为 60。低带宽场景下可能需要适当增大，详见读写错误
--ioretries=30
--io-retries=30		网络故障的重试次数（默认：30）。重试之间的等待时间是线性增长，但如果设定为超过 30 次，则变为每次固定 10 秒等待。实际使用时的超时时间则与相关请求的 timeout 设置有关。
--object-clients=1 新增自 v5.1.0对象存储客户端实例数，默认为 1。大部分对象存储系统不需要调整该参数，但某些存储（比如 Ceph）的 SDK 中，对于单个客户端实例施加了带宽上限，因此不论使用多大的并发，都无法打满单机带宽，如果你的环境遭遇这种情况，可以尝试增加对象存储客户端数量来进一步提升吞吐。
--max-uploads=20上传并发度，默认为 20。该参数一并控制 DELETE 请求的并发度，所以如果面对海量待删除数据清理太慢，增加上传并发一样可以起到加速作用。

对于粒度为 4MiB 的写入模式，20 并发已经是很高的默认值，在这样的写入模式下，提高写并发往往需要伴随增大 --buffer-size, 详见「读写缓冲区」。但面对百 K 级别的小随机写，并发量大的时候很容易产生阻塞等待，造成写入速度恶化。如果无法改善应用写模式，对其进行合并，那么需要考虑采用更高的写并发，避免排队等待。
--max-downloads=200最大并发下载请求数，默认为 200，这对于客户端已经是很高的默认值，一般无需调整。另外，该选项控制客户端全局的并发度，客户端对于单个文件的预读并发度设置了 128 个分块的硬上限，防止读取大文件时资源占用不受控。
--max-deletes=-1
--delete-limit=-1		对象存储 DELETE API 调用上限（QPS），默认为 -1（无限制），设置为 0 以禁用删除。
--flush-wait=5s持久化到对象存储的时间间隔，默认 5 秒。在大文件写入慢的情况下，过于频繁地调用持久化会导致碎片化，可以考虑增加时间间隔，来减少文件碎片导致的写放大。
--upload-limit=0上传数据所用带宽的上限，单位 Mbps，默认为 0（无限制）。除用于主动限速外，大吞吐场景下可能导致机器负载过高，考虑使用该参数控制机器负载。
--download-limit=0下载数据所用带宽的上限，单位 Mbps，默认为 0（无限制）。除用于主动限速外，大吞吐场景下可能导致机器负载过高，考虑使用该参数控制机器负载。
--external客户端默认会使用内网地址访问对象存储，该参数可以显式指定使用对象存储的外网地址。
--internal显式指定对象存储的内网地址（适用于区分内外网域名的对象存储，比如：阿里云 OSS、UCloud UFile 等）。
--rsa-key=PATH指定 RSA 私钥路径（PEM），如果秘钥是用密语加密过的，在挂载时会被询问，也可以通过 JFS_RSA_PASSPHRASE 环境变量设置。
--flip翻转文件系统复制功能的两个对象存储的复制顺序（也就是把第二个对象存储作为源），文件系统复制请详见「跨区数据复制」。

本地缓存相关参数​

详读缓存以了解 JuiceFS 的缓存设计。

项说明
--buffer-size=300读写缓冲区大小，单位 MiB，默认 300。详读「读写缓冲区」以了解如何对该参数进行调优。
--prefetch=1随机读对象存储块的一小段，会触发异步下载整个块，这个过程在 JuiceFS 中叫做「预取」（prefetch）。该参数用于控制预取的并发度，默认为 1，设为 0 以禁用该行为。需注意：
  • prefetch 可能在某些情况下带来读放大，详见读放大
  • 在独立缓存集群中，客户端不直接访问对象存储，而是通过缓存集群读取数据，因此该参数不起作用。
--max-readahead设置最大预读窗口，单位为 MiB。如果要修改该设置，注意不应超过「块大小 * 128MiB」，因此以常用的 4M 块大小，预读窗口无法超过 512MiB。如果不设置该参数，实际的预读窗口将会根据读写缓冲区和读并发的情况动态调整。

在 5.1.18 以及之后的版本，预读行为有了更好的改善，能显著降低预期之外的读放大，因此如果面临读放大问题，建议先升级 5.1.18，再根据实际情况判断是否需要调整该参数。
--initial-readahead设置初始预读窗口大小，单位为 MiB。更大的初始窗口能够加速大文件的顺序读性能。如果该选项未设置，默认的初始窗口为 4096 字节。

在 5.1.18 以及之后的版本，预读行为有了更好的改善，能显著降低预期之外的读放大，因此如果面临读放大问题，建议先升级 5.1.18，再根据实际情况判断是否需要调整该参数。
--readahead-ratio设置预读比例，默认值为 1.0，设置为 0~1 之间的浮点数来进一步抑制读放大。可以在大文件的随机读场景降低读放大。

在 5.1.18 以及之后的版本，预读行为有了更好的改善，能显著降低预期之外的读放大，因此如果面临读放大问题，建议先升级 5.1.18，再根据实际情况判断是否需要调整该参数。
--writeback启用客户端写缓存，数据优先写到本地磁盘，然后在后台异步上传。默认为 false。写缓存带来数据安全风险，谨慎使用。
--cache-dir=CACHEDIR本地缓存的存储路径，视用户不同，默认为 /var/jfsCache 或 $HOME/.juicefs/cache。支持传入多个缓存路径，用 : 分割多个目录，目录可包含通配符 *（用引号封闭）。例如 '/data*/jfsCache:/mydata*/jfsCache'。此外，还支持使用内存作为缓存目录，传入 /dev/shm 使用内存设备（大小默认为内存的一半），也可以传入 memory 使用客户端进程内存。

客户端启动的时候会扫描缓存路径下的所有文件，将其纳入内存索引，因此不同的 JuiceFS 客户端如果复用了同一个缓存目录，各自写入的缓存数据是无法互相发现的，无法共享各自的缓存数据。如果缓存大小（--cache-size，--free-space-ratio）设置不一致，会以其中的最小值作为阈值开始发起淘汰，因此可能出现挂载点 A 的数据被 B 淘汰掉的情况。
--cache-size=102400本地缓存容量，单位 MiB，默认 102400（100GiB），也可以传入 -1 来表示将盘大小设为缓存大小（从 5.1 开始支持）。当指定了多个缓存目录时，总容量会平均分配到各个目录。

可以将该选项设为 0 以彻底禁用本地磁盘缓存，不过这样会导致客户端额外尝试分配 100MB 的内存用于缓存。另一方面，如果缓存盘短时间内发生大量失败，客户端进程会弃用缓存盘，回退到这 100MB 的内存缓存空间，从监控上体现为缓存流量骤降到 100MB 或以下。

--free-space-ratio=0.1缓存目录的最小剩余空间占比，默认 0.1（但对于 4.9 版本或更早，默认值为 0.2）。该参数不支持设置为 0，如果希望允许缓存尽可能写满磁盘，可以设置一个接近于 0 的值（比如 0.01）。另外如果启用了「客户端写缓存」，则该参数还控制着写缓存占用空间。
--cache-mode=0600缓存目录的权限模式，默认是 0600。
--cache-partial-only对于读缓存，仅缓存小于一个块大小（默认 4MiB）的数据块，例如小于一个块大小的小文件、大文件末尾不足一个块大小的数据块。默认为 false（即缓存所有读取的数据块）。

注意，该选项同时也会对分布式缓存的缓存构建造成影响。

阅读客户端读缓存了解更多关于该选项的说明。
--cache-large-write 新增自 v5.1.0对于一个完整块大小的写入数据也进行缓存，默认情况下 JuiceFS 并不缓存顺序写产生的大块内容（大多数场景下，他们并不会被再次读取），如果你的场景需要，则用该选项开启。
--verify-cache-checksum=extend缓存数据一致性检查级别，启用 Checksum 校验后，生成缓存数据块时会对数据切分做 Checksum 并记录于文件末尾，供读缓存时进行校验。支持以下级别：
  • none：禁用一致性检查，如果本地数据被篡改，将会读到错误数据；
  • full：读完整数据块时才校验，适合顺序读场景；
  • shrink：对读范围内的切片数据进行校验，校验范围不包含读边界所在的切片（可以理解为开区间），适合随机读场景；
  • extend（默认）：对读范围内的切片数据进行校验，校验范围同时包含读边界所在的切片（可以理解为闭区间），因此将带来一定程度的读放大，适合对正确性有极致要求的随机读场景。
--cache-eviction=2-random 新增自 v5.0.1缓存淘汰算法，支持以下策略：
  • 2-random（默认）：用 2-random 算法来淘汰缓存，也就是随机选取两个数据块，删除 atime（最近访问时间）较小者。对于大部分真实场景，该算法效果类似 LRU；
  • none：禁用缓存淘汰，缓存空间写满即止，无法继续写入，需要手动管理缓存数据。
--cache-expire=0s 新增自 v5.1.0设置缓存淘汰时间，留存长于设定时间的缓存块将会被自动清理。默认为 0 表示禁用该功能。

分布式缓存相关参数​

详读分布式缓存以了解更多。

项说明
--cache-group=CACHEGROUP分布式缓存组的组名称，相同组的客户端之间可以相互共享缓存的数据，默认未启用。
--subgroups=0用子组来对缓存组做进一步拆分，默认为 0。如果设置为大于零的整数，实际上就是为缓存组名添加数字前缀，将缓存组进一步拆分为 N 个子组。

当缓存组客户端数量特别多时，缓存组容易出现热点数据（比如所有客户端都同时访问同一个 4M 数据块），导致缓存组的服务提供方特定节点出现网络拥堵。这时添加 --subgroups=10，就能将缓存组拆分为 10 个子组，每个子组内的客户端都会访问各自组内的数据，减少热点发生的可能性。缺点是随着访问，缓存数据会被重复存储，因此需要提前做好容量规划。
--group-network缓存组的监听网卡，默认的监听 IP 是网络设备列表中找到的第一个内网 IP，如果这样的策略不合适，可以使用该参数手动指定网络设备。
--group-ip=GROUPIP手动设置缓存共享组的 IP 地址，在多网卡节点中，使用该参数来绑定特定网卡。除了指定 IP 地址，还可以直接传入 CIDR 前缀来自动匹配 IP，比如用 172.16.0.0 来匹配 172.16.0.0/16。
--group-port缓存组的监听端口，默认为随机端口。如果指定的端口不可用，则会自动 +1 直到绑定成功。
--group-weight=100如果节点间缓存空间大小不一致，通过该值来调节节点各自的权重。建议取值范围为 10 到 1000。比如 1TB 和 3TB 的节点搭配成为缓存组，则可将 1TB 节点设置权重 100，3TB 节点设为 300。
--group-weight-unit=0如果不希望手动设定 --group-weight，而是希望从 --cache-size 自动推算，那么可以指定该参数。单位为 MiB，以默认的 --cache-size=102400 为例，配合 --group-weight-unit=1024，后者含义是“将 1024MiB 记为 1 权重”，也就是说最终权重为 102400 / 1024 = 100。
--group-backup启用“缓存副本”功能，启用该功能的节点如果自身缓存未命中，则会将请求转发给其他节点。请求最终返回后，两个节点都会尝试将数据缓存到本地。阅读「缓存副本」以了解具体原理和适用场景。
--no-sharing加入缓存组时，从缓存集群获取缓存数据，但却不共享自身缓存数据（只索取、不付出）。该选项用于需要访问缓存集群数据，但自身却不断变动的节点（比如 Kubernetes Pod）。默认为 false。
--fill-group-cache将客户端写入的数据块尽量发送给缓存组（不保证 100% 缓存），而不再写入本地缓存。需要注意：
  • 如果客户端同时启用了 --no-sharing，考虑到大部分场景下顺序读的数据缓存价值不大，此时便只会将小于块大小（默认 4MiB）的写入数据发送给缓存组。如果希望大文件顺序读也一并发送给缓存集群、参与缓存构建，需要配合 --cache-large-write。
  • 从 4.9.22 开始，如果启用了--writeback，那么所有大小的写缓存数据一律会异步发送给缓存组，让组内成员有一定概率读到尚未持久化到对象存储的数据。之所以是「一定概率」，是由于缓存组的写入从设计上并不保证可靠，在负载升高、网卡打满的时候可能会丢弃数据。如果需要更可靠、高性能写缓存，使用「共享块设备」将会更合适的选择。
--cache-group-size=0单位 MiB。考虑到读文件时客户端会进行预读和预取，在开启分布式缓存时，对于小于该值的文件，客户端会尽量将该文件切分的数据块调度到一个节点上，以此来最大化利用缓存数据。
--cache-priority=0 新增自 v5.0.14缓存块的优先级，可选值为：0、1、2、3，数字越大优先级越高。缓存淘汰时会优先淘汰优先级更低的数据。
--remote-timeout=65s 新增自 v5.1.0缓存组请求超时时间，默认为 65 秒。
--group-compress 新增自 v5.1.0压缩分布式缓存请求，默认开启。如果你的数据压缩比不理想，可以关闭压缩以节约 CPU 开销。从 5.2.0 开始默认关闭。

实验性参数​

注意

以下参数属于实验性功能，使用不当存在数据安全隐患，并且使用方法和参数均有可能在未来持续调整，如有使用需要，务必在 Juicedata 工程师的指导下操作。

项说明
--min-inodes-diff=1048576当前分区与 inodes 最少的分区之间的 inodes 差值超过这个值时，自动均衡元数据。默认值为 1048576。
--min-dir-inodes=1048576当前路径的目录数超过这个值时则自动均衡元数据。默认值为 1048576。
--max-space=0挂载点展示的总的存储容量上限 GiB。默认为 0，代表展示真实的文件系统总用量。

Windows 相关参数​

注意

Windows 版本目前处于 Beta 阶段，如下的参数可能会在未来稍有变动。

项说明
-o用于支持 WinFsp FUSE 的挂载选项。
--log用于指定在后台运行时的日志文件路径。
--as-root是否以 Root 的身份对文件进行挂载。启用此选项后，所有的文件操作均会以 UID=0,GID=0 进行。
--ignoreGid是否忽略文件属性中的 GID。
-f是否前台挂载。默认值为 false，注意，当以后台挂载时，JuiceFS 会以系统服务的方式挂载，而这一行为需要管理员权限运行。
--show-dot-files是否显示隐藏文件。默认值为 false。
--winfsp-threadsWinFsp 处理内核消息的线程数，默认值是 max(CPU*2, 16)。
--report-case设置后，JuiceFS 会尽可能地向 Windows 系统反馈大小写敏感的真实路径。（开启后可能会有性能影响）
--enable-kernel-cache开启后，JuiceFS 指示 WinFsp 启用 Windows 内核中的 Cache Manager 以提高部分场景下的读取效率。但开启此选项后，一些诸如 profile, stats 等命令会无法运行。默认值为 false。
--alias文件系统的别名。如果期望将一个文件系统在同一机器上同时挂载到不同盘符，请使用此选项。默认值为空。

juicefs umount​

卸载 JuiceFS 文件系统。该命令跨平台通用，Linux 下使用 umount 来执行卸载，而 macOS 下则一般用 diskutil unmount。此外，客户端还提供一个相似命令 juicefs unmount，这个命令仅在 Kubernetes FlexVolume 下使用，其他场景无需关注。

如果卸载文件系统遇到问题，阅读文档进行排查。

概览​

juicefs umount PATH [options]

参数​

项说明
PATH挂载路径
-f --force强制卸载

juicefs gateway​

启动一个 S3 网关，详见「S3 网关」。

概览​

juicefs gateway [command options] VOLUME-NAME ADDRESS

export MINIO_ROOT_USER=admin
export MINIO_ROOT_PASSWORD=12345678
juicefs gateway testVolume localhost:9000

参数​

除下方列出的参数，该命令还与 juicefs mount 共享参数，因此需要结合 mount 一起参考。

FlagDescription
--console-url=URLWeb 控制台 URL，仅在私有部署环境需要使用。
--mountpoint=s3gateway指定宿主机挂载点，用于解析 JuiceFS 内的绝对路径，默认 s3gateway。详见 S3 网关和符号链接。
--access-log=PATH「文件系统访问日志」的文件路径，默认为文件系统根路径的 .accesslog。
--no-banner不打印 MinIO 启动信息。
--multi-buckets将一级目录作为 Bucket 使用，默认为 false。
--keep-etag保留上传对象的 ETag。
--umask="0022"新文件的 umask，默认 0022。

juicefs webdav​

启动一个 WebDAV 文件共享服务器。

使用环境变量 WEBDAV_USER 和 WEBDAV_PASSWORD 设置访问 WebDAV 共享的用户名和密码。

概览​

juicefs webdav [command options] NAME ADDRESS

# 设置用户名和密码
export WEBDAV_USER=root
export WEBDAV_PASSWORD=1234

# 启动一个 WebDAV 服务器，监听 9007 端口
juicefs webdav myjfs localhost:9007

参数​

除下方列出的参数，该命令还与 juicefs mount 共享参数，因此需要结合 mount 一起参考。

项说明
--cert-file指定 TLS 证书文件
--key-file指定 TLS 密钥文件
--gzip用 gzip 压缩文件。
--disallow-list禁止在 WebDAV 中列出目录。

工具​

juicefs benchmark​

简单的性能测试，内容包括大文件和小文件的 read/write/stat。

概览​

juicefs benchmark [options] path-to-test

参数​

项说明
--dest=/jfs/benchmark用于保存测试数据的临时目录，默认 /jfs/benchmark。
--block-size=BLOCK_SIZE块大小 MiB（默认：1MiB）
--bigfile-file-size=BIGFILE_FILE_SIZE大文件大小，单位 MiB（默认：1024MiB）
--smallfile-file-size=SMALLFILE_FILE_SIZE小文件大小，单位 MiB（默认：0.1MiB）
--smallfile-count=SMALLFILE_COUNT小文件数量（默认：100）

juicefs objbench​

测试对象存储接口的正确性与基本性能。

概览​

juicefs objbench [command options] BUCKET

参数​

项说明
--storage=file对象存储类型 (例如 s3、gcs、oss、cos) (默认：file)
--access-key=value对象存储的 Access Key，也可通过环境变量 ACCESS_KEY 设置。
--secret-key=value对象存储的 Secret Key，也可通过环境变量 SECRET_KEY 设置。
--session-token=value对象存储的会话 token
--block-size=4096每个 I/O 块的大小（以 KiB 为单位）（默认值：4096）
--big-object-size=1024大文件的大小（以 MiB 为单位）（默认值：1024）
--small-object-size=128每个小文件的大小（以 KiB 为单位）（默认值：128）
--small-objects=100小文件的数量（默认值：100）
--skip-functional-tests跳过功能测试（默认值：false）
--threads=4, -p 4上传下载等操作的并发数（默认值：4）
--object-clients=1 新增自 v5.1.0详见「JuiceFS mount 对象存储相关参数」

juicefs warmup​

将文件提前下载到缓存，提升后续本地访问的速度。可以指定某个挂载点路径，递归对这个路径下的所有文件进行缓存预热；也可以通过 --file 选项指定文本文件，在文本文件中指定需要预热的文件名。

如果需要预热的文件分布在许多不同的目录，推荐将这些文件名保存到文本文件中并用 --file 选项传给预热命令，这样做能利用 warmup 的并发功能，速度会显著优于多次调用 juicefs warmup，在每次调用里传入单个文件。

预热命令不会重复下载本地已经存在的文件（会直接跳过），因此显示的下载速度可能会高于实际下载流量。如果开启了分布式缓存，那么在缓存组内任意节点执行该命令，都能获得相同效果。

概览​

juicefs warmup [PATH] [options]

# 预热目录中的所有文件
juicefs warmup /jfs/datadir

# 只预热指定文件
echo '/jfs/f1
/jfs/f2
/jfs/f3' > /tmp/filelist.txt
juicefs warmup -f /tmp/filelist.txt

参数​

项说明
--file=FILE
-f FILE
--listfile=FILE		将需要预热的文件名保存成文本文件，一行一个路径。当需要预热多个指定文件时，建议使用这种方法，效率高于拆分成多个 warmup 命令。
--threads=50
-p 50
-c 50
--concurrent=50		下载并发度，默认 50。增大并发以加速预热，但如果对象存储的下载带宽较小，则需降低并发度，避免下载超时。对于分布式缓存场景，如果预热速度不够快，建议从 20 * [缓存组成员数] 来开始增加，逐渐调优来寻求最合适的并发度。
--cache-priority=0 新增自 v5.0.14缓存块的优先级，可选值为：0、1、2、3，数字越大优先级越高。缓存淘汰时会优先淘汰优先级更低的数据。
--io-retries=1下载单个数据块的最大失败重试次数，默认为 1。在网络环境不佳的情况下可以降低并发、增加重试次数来更好地容错。
--max-failure=0根据预热失败的数据块数量来决定命令返回值，默认允许的失败数量为 0，意味着如果有任何数据块下载失败，命令会返回失败状态（返回值为 1）。面对预热失败，需要查看客户端日志进行问题排查。
--background
-b		后台运行。
--evict主动删除给定路径的缓存内容。
--check检查给定路径是否已被缓存。

juicefs snapshot（juicefs clone）​

对指定数据进行快照，创建快照时不会实际拷贝对象存储数据，而是仅拷贝元数据，因此不论对多大的文件或目录进行快照，都非常快。因此对于 JuiceFS，这个命令是 cp 更好的替代，甚至对于 Linux 客户端来说，如果所使用的内核支持 copy_file_range，那么调用 cp 时，实际发生的也是同样的元数据拷贝，调用将会格外迅速。

clone

快照结果是纯粹的元数据拷贝，实际引用的对象存储块和源文件相同，因此在各方面都和源文件一样，可以正常读写。有任何一方文件数据被实际修改时，对应的数据块变更会以写入时复制（Copy-on-Write）的方式，写入到新的数据块，而其他未经修改的文件区域，由于对象存储数据块仍然相同，所以引用关系依然保持不变。

使用这个命令需要注意：

  • 虽然不会拷贝对象存储内容，但是快照产生的元数据，也同样占用存储空间、参与 JuiceFS 计费，因此对庞大的目录进行快照操作时请格外谨慎；
  • 拷贝大目录需要耗费一些时间，在这个过程中如果文件被删除或者移动，命令会提示文件不存在（no such file），是正常现象；
  • JuiceFS 文件系统之间是隔离的，无法跨文件系统创建快照。

概览​

juicefs snapshot SRC DST [-f|--force] [-p|--preserve]  # 创建快照
juicefs snapshot -d DST [-f|--force]  # 删除快照

参数​

项说明
SRC要做快照的目录。
DST快照存放的目录。
-d --delete删除快照。该命令只能用于删除快照，如果用该命令删除普通文件，则会提示没有权限。被删除的数据不会进入回收站（即使开启了回收站），而是直接删除。如果希望进入回收站请使用 juicefs rmr 或 rm -r 命令。
-f --force强行覆盖或删除文件。
-p --preserve如果传入该参数，生成快照会使用源文件的 UID，GID 和文件属性（Windows 客户端会强行使用该行为）。如果不使用该参数，则默认会用当前用户的 UID，GID，umask 来创建新快照。

juicefs rmr​

快速删除目录里的所有文件和子目录，效果等同于 rm -rf，但该命令直接操纵元数据，不经过 POSIX，所以速度更快。如果文件系统启用了回收站功能，被删除的文件会进入回收站。回收站的文件依然参与计费，详见「回收站」。

权限要求

rmr 子命令会受到两部分权限的影响：

  • 如果要使用 --skip-trash 来跳过回收站，那么挂载点所使用的令牌（TOKEN）必须具备管理权限，所有令牌默认都具备管理权限，除非手动取消该配置；
  • 运行 rmr 时，会以当前用户的身份去递归删除指定目录里面的所有文件和子目录，跳过无权限删除的部分，返回被删除的文件和目录数量以及剩余的文件和目录数。

概览​

juicefs rmr DIR ... [-h]

参数​

项说明
DIR需要删除的文件。
--skip-trash跳过回收站、直接删除。需要紧急释放对象存储空间才启用该选项，由于跳过了回收站，一旦被删除则无法恢复，请小心操作。除此外，该功能需要挂载点所使用的令牌（TOKEN）具备管理权限（所有令牌默认都具备管理权限，除非手动取消该配置）。

juicefs sync​

在两个存储之间同步数据，阅读「数据同步」以了解更多。

概览​

juicefs sync [command options] SRC DST

# 从 OSS 同步到 S3
juicefs sync oss://mybucket.oss-cn-shanghai.aliyuncs.com s3://mybucket.s3.us-east-2.amazonaws.com

# 从 S3 直接同步到 JuiceFS
juicefs sync s3://mybucket.s3.us-east-2.amazonaws.com/ jfs://VOL_NAME/

# 源端：a1/b1,a2/b2,aaa/b1   目标端：empty   同步结果：aaa/b1
juicefs sync --exclude='a?/b*' s3://mybucket.s3.us-east-2.amazonaws.com/ jfs://VOL_NAME/

# 源端：a1/b1,a2/b2,aaa/b1   目标端：empty   同步结果：a1/b1,aaa/b1
juicefs sync --include='a1/b1' --exclude='a[1-9]/b*' s3://mybucket.s3.us-east-2.amazonaws.com/ jfs://VOL_NAME/

# 源端：a1/b1,a2/b2,aaa/b1,b1,b2  目标端：empty   同步结果：a1/b1,b2
juicefs sync --include='a1/b1' --exclude='a*' --include='b2' --exclude='b?' s3://mybucket.s3.us-east-2.amazonaws.com/ jfs://VOL_NAME/

源路径（SRC）和目标路径（DST）的格式均为 [NAME://][ACCESS_KEY:SECRET_KEY[:SESSIONTOKEN]@]BUCKET[.ENDPOINT][/PREFIX]，其中：

  • NAME：JuiceFS 支持的数据存储类型，比如 s3、oss，同样也支持 jfs，这样便能绕过 FUSE 挂载点，直接将文件拷贝到 JuiceFS，在大规模场景下可以降低资源开销以及提升数据同步性能。
  • ACCESS_KEY、SECRET_KEY：访问数据存储所需的认证信息，特殊字符需要进行 URL 转义并替换，比如 / 需要被替换为 %2F。
  • SESSIONTOKEN 可选地提供对象存储的 Session Token。
  • BUCKET[.ENDPOINT]：数据存储服务的访问地址，注意 MinIO 目前仅支持路径风格（minio://[ACCESS_KEY:SECRET_KEY[:TOKEN]@]ENDPOINT/BUCKET[/PREFIX]）。
  • [/PREFIX]：可选，源路径和目标路径的前缀，可用于限定只同步某些路径中的数据。
提示

除下方列出的参数，该命令还与 juicefs mount 共享参数，因此需要结合 mount 一起参考。

需要注意的是，这些共享参数，有许多是仅针对 jfs 协议头生效的，比方说 sync 命令虽然也支持 --writeback，但这个参数的生效对象是「JuiceFS 客户端」，可想而知，这个参数仅在目的地是 jfs 协议头时生效。同样以 --writeback 为例，就算目的地是一个 JuiceFS 的宿主机挂载点，也并不会因为 sync 命令启用了 --writeback，而自动变成一个启用了客户端写缓存的挂载点，必须要在 sync 命令内写入 jfs 协议头目的地，写缓存设置方可生效。其他的 mount 共享参数，也遵循该原则。

项说明
--start=KEY, -s KEY, --end=KEY, -e KEY提供 KEY 范围，来指定对象存储的 List 范围。
--exclude=PATTERN排除匹配 PATTERN 的 Key。
--include=PATTERN不排除匹配 PATTERN 的 Key，需要与 --exclude 选项配合使用。
--limit=-1限制将要处理的对象的数量，默认为 -1 表示不限制
--update, -u当源文件更新时（mtime 更新），覆盖已存在的文件，默认为 false。
--force-update, -f强制覆盖已存在的文件，默认为 false。
--existing, --ignore-non-existing不创建任何新文件，默认为 false。
--ignore-existing不更新任何已经存在的文件，默认为 false。
--files-from新增自 v5.1.10读取文本文件来获取需要同步的文件列表，文本文件中每一行的项目将会和命令行参数中提供的源、目的地路径进行字符串拼接，形成最终的完整路径。

举例说明，把 /jfs1/data.tar 同步到 /jfs2/data.tar，那么文件列表内容就是 /data.tar，将其保存为 files.txt，对应的命令则为 juicefs sync --files-from=files.txt /jfs1 /jfs2。
项说明
--dirs同步目录（包括空目录）。对象存储中没有目录概念，因此 juicefs sync 并不会拷贝空目录，因此如果源和目的地均为文件系统，一般都应该启用 --dirs 来拷贝空目录。
--perms保留文件所有权和权限，默认为 false。注意该参数默认只影响文件（不包含目录），如果需要保留目录的所有权和权限，需要配合 --dirs 一起使用。
--inplace原地修改文件，而不是进行删除覆盖。如果目标存储是启用了回收站功能的 JuiceFS 文件系统，同步修改过的文件会默认覆盖删除源文件，将其置于回收站。使用 --inplace 来启用原地修改，避免源文件进入回收站。目前仅支持 jfs:// 协议头的目标存储。
--links, -l将符号链接复制为符号链接，默认为 false，此时会查找并同步符号链接所指向的文件。
--delete-src, --deleteSrc如果目标存储已经存在，删除源存储的对象。与 rsync 不同，为保数据安全，首次执行时不会删除源存储文件，只有拷贝成功后再次运行时，扫描确认目标存储已经存在相关文件，才会删除源存储文件。
--delete-dst, --deleteDst删除目标中多余的对象（即目标中有但源存储中没有的文件）。如果你希望目标和源完全一致，目标中多出来的文件会被删除则可使用这个参数。
--check-all校验源路径和目标路径中所有文件的数据完整性，默认为 false。校验方式是基于字节流对比，因此也将带来相应的开销。
--check-new校验新拷贝文件的数据完整性，默认为 false。校验方式是基于字节流对比，因此也将带来相应的开销。
--check-change新增自 v5.2.0校验同步前后的数据是否有变更，默认为 false。校验方式基于文件大小和 mtime，比较轻量。
--max-failure新增自 v5.2.0最大允许失败的文件数（-1 表示无限）
--dry仅打印执行计划，不实际拷贝文件。
--http-port=6070pprof 监听的 HTTP 端口，默认 6070。
项说明
--threads=10, -p 10并发线程数，默认为 10。增大并发数会增加资源占用，尤其是大文件场景下，因为更多的大文件会被读入进程内存。
--list-threads=1并发 list 线程数，默认为 1。阅读并发 list以了解如何使用。
--list-depth=1并发 list 目录深度，默认为 1。阅读并发 list以了解如何使用。
--no-https不要使用 HTTPS，默认为 false。
--storage-class=value目标端的新建文件的存储类型（也叫存储级别，可以阅读相应文档了解更多：S3、OSS），如果目标端存储支持的话。
--bwlimit=0限制最大带宽，单位 Mbps，默认为 0 表示不限制。
项说明
--manager=ADDR分布式同步模式中，Manager 的节点地址，此为内部参数，在 Worker 节点上运行的同步进程中会包含该设置。
--worker=ADDR,ADDR分布式同步模式中，工作节点列表，使用逗号分隔。

监控相关参数​

项说明
--metrics监控指标收集地址，默认 127.0.0.1:9567。
--consulConsul 注册地址，默认 127.0.0.1:8500。

juicefs import​

juicefs import 会扫描给定的对象存储地址，然后将目标文件的元数据信息写入 JuiceFS 元数据引擎，让这些文件在 JuiceFS 中也能访问，该操作并不会实际复制任何文件，文件仍原样保存在对象存储里。阅读「导入对象存储已有文件」了解更多。

概览​

提示

从外部桶导入的文件，不支持缓存。因此如果希望导入的文件能享受到缓存功能，文件系统和导入源必须使用同一个对象存储桶，并且导入命令必须使用以下格式：

# URI 中不包含 bucket 参数，则支持缓存
juicefs import / /jfs/imported
juicefs import /prefix /jfs
# 如果 URI 包含了 bucket，便不支持缓存
# 在下方例子中，即使 BUCKET 正是文件系统所使用的桶，也不支持缓存
juicefs import BUCKET/prefix /jfs
juicefs import URI DST [-v] [--name=<name>] [--mode=<mode>]

# 假设挂载点为 /jfs，并且 Bucket 与文件系统相同，可以省略桶名
# 下方命令会将整个对象存储桶的内容导入 JuiceFS
juicefs import / /jfs/imported

# 如果你打算通过 JuiceFS 文件系统写入文件，注意不能直接将整个 Bucket 执行导入，必须指定目录名称
# 否则会将 JuiceFS 自身的对象存储数据（也就是 chunks 目录）导入文件系统，这部分数据导入文件系统是没有意义的
# 如果打算导入目录，必须添加末尾的斜杠 /
juicefs import /bucket-directory/ /jfs/imported

# 如果不添加末尾斜杠，则代表用前缀进行扫描，这种方式对于某些对象存储系统并不支持
# 因此仍然建议在目标末尾添加斜杠 / 来导入对象存储的目录
juicefs import /prefix /jfs/imported

# 假设 Bucket 与文件系统的存储桶处于同一个区域
# 此时可以省略完整 Endpoint，只填写桶名即可，这种方式导入不支持缓存，不推荐使用
juicefs import another-bucket/directory/ /jfs/imported

# 如果桶在其他区域，则需要使用完整 Endpoint，这种方式导入不支持缓存，不推荐使用
juicefs import other-bucket.s3.cn-northwest-1.amazonaws.com.cn /jfs

参数​

项说明
URI要导入文件的对象存储 URI，格式为 BUCKET[.ENDPOINT][/PREFIX]。必须和目标文件系统使用相同的对象存储，并且要求使用相同的认证信息（Access Key、Secret Key）可以访问，无法单独指定 Key。
DST导入文件的存放目录，该目录必须是 JuiceFS 挂载点，并且文件系统本身所使用的对象存储，和 URI 所指定的必须是相同的对象存储。
--mode=0440导入文件的默认权限，默认值是 0440（注意最前面的 0 不能省略，表示这是一个八进制数）。这个参数不能调整新目录的默认权限，如果需要调整，请先使用 umask 命令修改，例如如果希望新目录的默认权限是 777，那么就需要这样执行命令 umask 000 && juicefs import ...。
--threads=50Worker 数量，如果 list 产生的元数据太多、无法及时写入，则需增大该选项、加速写入。
--list-threads=10对象存储 list 并发度，如果 list 太慢，可以尝试增加该并发度。
--list-depth=2对象存储 list 目录深度。对象存储本身并没有“目录”概念，因此这里指的是以 / 划分的前缀层级。调优思路类似 juicefs sync。
--update重新导入对象存储一侧更新的部分（通过 mtime 比对）。
--files-from新增自 v5.2.0读取文本文件来获取需要导入的文件列表，文本文件中可以是个具体文件，也可以是一个前缀。
--force-update重新导入所有对象存储所有的变动内容，部分存储系统可能会出现 mtime 未能随着对象修改而自动更新的情况，此时可以用该参数进行再次覆盖导入。

juicefs find​

从 JuiceFS v5.3.7 开始，JuiceFS 提供 juicefs find 子命令，作为 Linux find 在 JuiceFS 文件系统中的高性能替代，在这里阅读文档。

juicefs grep​

Linux grep 的并行版本，使用方法一样，搜索性能更高。

概览​

juicefs grep [PATTERN] PATH ... [options]

参数​

项说明
[PATTERN]要搜索的内容，支持正则表达式。
PATH搜索路径。
-j JOBS --jobs=JOBS并行任务数量（默认为 CPU 核数）。
-e PATTERNS --regexp PATTERNS多用于连接多个 PATTERNS 或者 PATTERN 以 "-" 开头。
-E extended-regexp指定 PATTERN 是扩展正则表达式。
-H每行开始都打印文件名。
-n --line-number输出搜索结果所在的行号。
-i --ignore-case忽略英文字母大小写，默认是区分大小写的。
-v --invert-match搜索不包含 PATTERN 的行。
最后于 更新
在 X 上关注我们
在 Discord 上交流
加入微信用户群