命令参考
在终端输入 juicefs 并执行，就能看到所有可用的命令。在每个子命令后面添加 -h/--help 并运行，就能获得该命令的详细帮助信息，例如 juicefs mount -h。
NAME:
juicefs - A POSIX file system built on object storage.
USAGE:
juicefs [global options] command [command options] [arguments...]
VERSION:
5.1.1 (2024-09-20 1faf43b)
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
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:
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.
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)
--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，或使用自建对象存储进行私有化部署时，该命令十分有用。
概览
juicefs auth NAME [options]
juicefs auth myjfs --token xxx --access-key xxx --secret-key xxx
参数
| 项 | 说明 |
|---|---|
NAME | 文件系统的名字。 |
--token=TOKEN | 文件系统的 Token，在网站控制台的文件系统设置中查看。 |
--bucket=BUCKET | 在文件系统创建之初，对象存储桶已经在控制台设置好了。但如果有需要，可以使用该参数覆盖桶设置，比如因为网络环境不同，某些客户端需要使用特定的对象存储服务地址。 和控制台的文件系统的桶设置一样，该参数既可以填写桶名，也可以填写完整 endpoint（以 https:// 或 http:// 开头），这两种填写方法的区别如下：
|
--access-key=ACCESSKEY | 对象存储的密钥，获取方式参见 文档。如不指定则需要交互式录入。如果云主机已经配置免密访问对象存储，则传入空字符串（或者在交互式录入时直接按回车键跳过）即可。 |
--secret-key=SECRETKEY | 对象存储的密钥，获取方式参见 文档。如不指定则需要交互式录入。如果云主机已经配置免密访问对象存储，则传入空字符串（或者在交互式录入时直接按回车键跳过）即可。 |
--session-token=SESSIONTOKEN | 对象存储 session token（可选） |
--storage-class=value | 目标端的新建文件的存储类型（也叫存储级别，可以阅读相应文档了解更多：S3、OSS），如果目标端存储支持的话。 |
--bucket2=BUCKET2 | 用于文件系统复制功能的目标对象存储 Bucket 名称或 endpoint 地址，格式和注意事项同 --bucket。 |
--access-key2=ACCESSKEY2 | 开启文件系统复制功能时，目标对象存储密钥（可选）。文件系统复制请详见「跨区数据复制」。 |
--secret-key2=SECRETKEY2 | 开启文件系统复制功能时，目标对象存储密钥（可选）。文件系统复制请详见「跨区数据复制」。 |
--session-token2=SESSIONTOKEN2 | 用于文件系统复制功能的对象存储 session token（可选） |
--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
参数
| 项 | 说明 |
|---|---|
-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 客户端的监控指标，打印各个指标的每秒变化情况。
该命令的更多介绍和用法详见「实时性能监控」。
概览
juicefs stats [options] MOUNTPOINT
参数
| 项 | 说明 |
|---|---|
--schema=ufmco | 控制输出内容的标题字符串，默认为“ufmco”，含义如下： u: usage f: FUSE m: meta c: blockcache o: object g: go |
--interval=1 | 更新间隔，单位为秒，默认为 1。 |
--verbosity=0 | 详细级别，默认为 0，使用更大值以获得更详细输出。 |
juicefs profile
对「文件系统访问日志」进行简单直观的统计，在命令行展示各项操作的耗时统计数据，帮 助你迅速判断应用对文件系统的访问模式，评估访问性能。
该命令的更多介绍和用法详见「实时性能监控」。
概览
juicefs profile [options]
参数
| 项 | 说明 |
|---|---|
-x PATH --path=PATH | 日志文件目录，默认 /jfs。 |
-f FILE --file=FILE | 日志文件名，默认 .ophistory。参考「访问日志」了解不同的访问日志文件。 |
-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 控制台。 |
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.0 | FUSE 写请求的单位，默认为 "128K"。修改该选项需要内核 4.20 或 以上版本，并且上限为 1MiB。如果系统不存在其他瓶颈，提高该值可以增加顺序写性能，但是相应地也会影响随机写或小追加写的性能，需要充分测试、谨慎调优。 |
-o FUSE_OPTS | 添加其他 FUSE 选项。如通过 -o writeback_cache 开启 FUSE 写缓存可以极大提高随机写入和碎片写入的性能（需要使用 Linux Kernel 3.15 及以上）。 |
元数据相关参数
| 项 | 说明 |
|---|---|
--subdir=SUBDIR | 挂载子目录，如果需要的话，还可以创建出限制只允许访问子目录的客户端令牌，详见「客户端权限控制」。 |
元数据缓存相关参数
| 项 | 说明 |
|---|---|
--metacacheto=300 | 元数据的缓存过期时间（单位为秒），默认为 300。 |
--metacache | 将元数据缓存在运行客户端的主机的内存里，默认启用。使用 --metacacheto=0 关闭缓存。 |
--max-cached-inodes=5000000 | Inodes 的最大缓存数量，默认为 5000000。 |
--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。对于粒度为 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 以禁用该行为。需注意： |
--initial-readahead | 设置初始预读窗口大小，单位为 MiB。更大的初始窗口能够加速大文件的顺序读性能。如果该选项未设置，默认的初始窗口为 4096 字节。 |
--writeback | 启用客户端写缓存，数据优先写到本地磁盘，然后在后台异步上传。默认为 false。写缓存带来数据安全风险，谨慎使用。 |
--cache-dir=CACHEDIR | 本地缓存的存储路径，视用户不同，默认为 /var/jfsCache 或 $HOME/.juicefs/cache。多盘缓存用 : 分割多个目录，目录可包含通配符 *（用引号封闭）。例如 '/data*/jfsCache:/mydata*/jfsCache'。此外，还支持使用内存作为缓存目录，传入 /dev/shm 使用内存设备（大小默认为内存的一半），也可以传入 memory 使用客户端进程内存。 |
--cache-size=102400 | 本地缓存容量，单位 MiB，默认 102400（100GiB）。当指定了多个缓存目录时，总容量会平均分配到各个目录。 可以将该选项设为 0 以彻底禁用本地磁盘缓存，不过这样会导致客户端额外尝试分配 100MB 的内存用于缓 存，详见资源占用问题排查。 从 5.1 起，支持传入 -1 来表示将盘大小设为缓存大小。 |
--free-space-ratio=0.1 | 缓存目录的最小剩余空间占比，默认 0.1（但对于 4.9 版本或更早，默认值为 0.1）。该参数不支持设置为 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 并记录于文件末尾，供读缓存时进行校验。支持以下级别：
|
--cache-eviction=2-random 新增自 v5.0.1 | 缓存淘汰算法，支持以下策略：
|
--cache-expire=0s 新增自 v5.1.0 | 设置缓存淘汰时间，留存长于设定时间的缓存块将会被自动清理。默认为 0 表示禁用该功能。 |
分布式缓存相关参数
详读分布式缓存以了解更多。
| 项 | 说明 |
|---|---|
--cache-group=CACHEGROUP | 分布式缓存组的组名称，相同组的客户端之间可以相互共享缓存的数据，默认未启用。 |
--subgroups=0 | 一个缓存组中子组的数量，默认为 0。用子组来对缓存组做进一步拆分，实际上就是为缓存组名添加数字前缀。 |
--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）的写入数据发送给缓存组。特别地，从 4.9.22 开始，如果启用了客户端写缓存，那么所有大小的写缓存数据一律会异步发送给缓存组，让组内成员有一定概率读到尚未持久化到对象存储的数据。 |
--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 开销。 |
实验性参数
注意
以下参数属于实验性功能，使用不当存在数据安全隐患，并且使用方法和参数均有可能在未来持续调整，如有使用需要，务必在 Juicedata 工程师的指导下操作。
| 项 | 说明 |
|---|---|
--min-inodes-diff=1048576 | 当前分区与 inodes 最少的分区之间的 inodes 差值超过这个值时，自动均衡元数据。默认值为 1048576。 |
--min-dir-inodes=1048576 | 当前路径的目录数超过这个值时则自动均衡元数据。默认值为 1048576。 |
--max-space=0 | 挂载点展示的总的存储容量上限 GiB。默认为 0，代表展示真实的文件系统总用量。 |
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 一起参考。
| Flag | Description |
|---|---|
--console-url=URL | Web 控制台 URL，仅在私有部署环境需要使用。 |
--mountpoint=s3gateway | 指定宿主机挂载点，用于解析 JuiceFS 内的绝对路径，默认 s3gateway。详见 S3 网关和符号链接。 |
--access-log=PATH | 「文件系统访问日志」的文件路径，默认为文件系统根路径的 .accesslog。 |
--no-banner | 不打印 MinIO 启动信息。 |
--multi-buckets | 将一级目录作为 Bucket 使用，默认为 false。 |
--keep-etag | 保留上传对象的 ETag。 |
--umask="022" | 新文件的 umask，默认 022。 |
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） |
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 时，实际发生的也是同样的元数据拷贝，调用将会格外迅速。
快照结果是纯粹的元数据拷贝，实际引用的对象存储块和源文件相同，因此在各方面都和源文件一样，可以正常读写。有任何一方文件数据被实际修改时，对应的数据块变更会以写入时复制（Copy-on-Write）的方式，写入到新的数据块，而其他未经修改的文件区域，由于对象存储数据块仍然相同，所以引用关系依然保持不变。
需要注意的是，虽然不会拷贝对象存储内容，但是快照产生的元数据，也同样占用存储空间、参与 JuiceFS 计费，因此对庞大的目录进行快照操作时请格外谨慎。
概览
juicefs snapshot SRC DST [-f|--force] [-c|--copy] # 创建快照
juicefs snapshot -d DST [-f|--force] # 删除快照
参数
| 项 | 说明 |
|---|---|
SRC | 要做快照的目录。 |
DST | 快照存放的目录。 |
-d --delete | 删除快照。该命令只能用于删除快照，如果用该命令删除普通文件，则会提示没有权限。被删除的数据不会进入回收站（即使开启了回收站），而是直接删除。如果希望进入回收站请使用 juicefs rmr 或 rm -r 命令。 |
-f --force | 强行覆盖或删除文件。 |
-c --copy | 用当前用户的 UID，GID，umask 来创建新快照，默认使用源文件的 UID，GID 和 mode。 |
juicefs rmr
快速删除目录里的所有文件和子目录，效果等同于 rm -rf，但该命令直接操纵元数据，不经过 POSIX，所以速度更快。
该命令会尝试以当前用户的身份去递归删除指定目录里面的所有文件和子目录，跳过无权限删除的部分，返回被删除的文件和目录数量以及剩余的文件和目录数。
如果文件系统启用了回收站功能，被删除的文件会进入回收站。回收站的文件依然参与计费，详见「回收站」。
概览
juicefs rmr DIR ... [-h]
参数
| 项 | 说明 |
|---|---|
DIR | 需要删除的文件。 |
--skip-trash | 跳过回收站、直接删除。需要紧急释放对象存储空间才启用该选项，由于跳过了回收站，一定要仔细确认、小心操作。 |
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：访问数据存储所需的认证信息，如果密钥中含特殊字符，用单引号对SRC，DST进行整体封闭，避免 shell 对其进行特殊解读。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。 |
行为相关参数
| 项 | 说明 |
|---|---|
--dirs | 同步目录（包括空目录）。 |
--perms | 保留权限设置，默认为 false。 |
--inplace | 原地修改文件，而不是进行删除覆盖。如果目标存储是启用了回收站功能的 JuiceFS 文件系统，同步修改过的文件会默认覆盖删除源文件，将其置于回收站。使用 --inplace 来启用原地修改，避免源文件进入回收站。目前仅支持 jfs:// 协议头的目标存储。 |
--links, -l | 将符号链接复制为符号链接，默认为 false，此时会查找并同步符号链接所指向的文件。 |
--delete-src, --deleteSrc | 如果目标存储已经存在，删除源存储的对象。与 rsync 不同，为保数据安全，首次执行时不会删除源存储文件，只有拷贝成功后再次运行时，扫描确认目标存储已经存在相关文件，才会删除源存储文件。 |
--delete-dst, --deleteDst | 删除目标存储下的不相关对象。 |
--check-all | 校验源路径和目标路径中所有文件的数据完整性，默认为 false。校验方式是基于字节流对比，因此也将带来相应的开销。 |
--check-new | 校验新拷贝文件的数据完整性，默认为 false。校验方式是基于字节流对比，因此也将带来相应的开销。 |
--dry | 仅打印执行计划，不实际拷贝文件。 |
--http-port=6070 | pprof 监听的 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。 |
--consul | Consul 注册地址，默认 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 自身的对象存储数据（也就是 chunks 目录）导入文件系统，这部分数据导入文件系统是没有意义的
juicefs import /prefix /jfs/imported
# 假设 Bucket 与文件系统的存储桶处于同一个区域
# 此时可以省略完整 Endpoint，只填写桶名即可
juicefs import another-bucket/prefix /jfs/imported
# 如果桶在其他区域，则需要使用完整 Endpoint
juicefs import other-bucket.s3.cn-northwest-1.amazonaws.com.cn /jfs
# 将特定前缀文件导入 JuiceFS 的特定目录
juicefs import other-bucket/prefix /jfs/oss-imported
参数
| 项 | 说明 |
|---|---|
URI | 要导入文件的对象存储 URI，格式为 BUCKET[.ENDPOINT][/PREFIX]。必须和目标文件系统使用相同的对象存储，并且要求使用相同的认证信息（Access Key、Secret Key）可以访问，无法单独指定 Key。 |
DST | 导入文件的存放目录，该目录必须是 JuiceFS 挂载点，并且文件系统本身所使用的对象存储，和 URI 所指定的必须是相同的对象存储。 |
--mode=0440 | 导入文件的权限（Unix 格式）。 |
--threads=50 | Worker 数量，如果 list 产生的元数据太多、无法及时写入，则需增大该选项、加速写入。 |
--list-threads=10 | 对象存储 list 并发度，如果 list 太慢，可以尝试增加该并发度。 |
--list-depth=2 | 对象存储 list 目录深度。对象存储本身并没有“目录”概念，因此这里指的是以 / 划分的前缀层级。调优思路类似 juicefs sync。 |
--update | 重新导入对象存储一侧更新的部分（通过 atime 比对）。 |
--force-update | 重新 导入所有对象存储所有的变动内容，部分存储系统可能会出现 atime 未能随着对象修改而自动更新的情况，此时可以用该参数进行再次覆盖导入。 |
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 的行。 |
