Skip to main content

命令参考

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

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

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

VERSION:
   1.3.1

COMMANDS:
   ADMIN:
     format   Format a volume
     config   Change configuration of a volume
     quota    Manage directory quotas
     destroy  Destroy an existing volume
     gc       Garbage collector of objects in data storage
     fsck     Check consistency of a volume
     restore  restore files from trash
     dump     Dump metadata into a file
     load     Load metadata from a previously dumped file
     version  Show version
   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
     debug    Collect and display system static and runtime information
     summary  Show tree summary of a directory
   SERVICE:
     mount    Mount a volume
     umount   Unmount a volume
     gateway  Start an S3-compatible gateway
     webdav   Start a WebDAV server
   TOOL:
     bench     Run benchmarks on a path
     objbench  Run benchmarks on an object storage
     warmup    Build cache for target directories/files
     rmr       Remove directories recursively
     sync      Sync between two storages
     clone     clone a file or directory without copying the underlying data
     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)
   --log-id value          append the given log id in log, use "random" to use random uuid
   --no-agent              disable pprof (:6060) agent (default: false)
   --pyroscope value       pyroscope address
   --no-color              disable colors (default: false)
   --help, -h              show help (default: false)
   --version, -V           print version only (default: false)

COPYRIGHT:
   Apache License 2.0

自动补全​

通过加载 hack/autocomplete 目录下的对应脚本可以启用命令的自动补全，例如：

source hack/autocomplete/bash_autocomplete

请注意自动补全功能仅对当前会话有效。如果你希望对所有新会话都启用此功能，请将 source 命令添加到 .bashrc 或 .zshrc 中：

echo "source path/to/bash_autocomplete" >> ~/.bashrc

另外，如果你是在 Linux 系统上使用 bash，也可以直接将脚本拷贝到 /etc/bash_completion.d 目录并将其重命名为 juicefs：

cp hack/autocomplete/bash_autocomplete /etc/bash_completion.d/juicefs
source /etc/bash_completion.d/juicefs

全局选项​

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

管理​

juicefs format​

创建并格式化文件系统，如果 META-URL 中已经存在一个文件系统，不会再次进行格式化。如果文件系统创建后需要调整配置，请使用 juicefs config。

概览​

juicefs format [command options] META-URL NAME

# 创建一个简单的测试卷（数据将存储在本地目录中）
juicefs format sqlite3://myjfs.db myjfs

# 使用 Redis 和 S3 创建卷
juicefs format redis://localhost myjfs --storage=s3 --bucket=https://mybucket.s3.us-east-2.amazonaws.com

# 使用带有密码的 MySQL 创建卷
juicefs format mysql://jfs:mypassword@(127.0.0.1:3306)/juicefs myjfs
# 更安全的方法
META_PASSWORD=mypassword juicefs format mysql://jfs:@(127.0.0.1:3306)/juicefs myjfs

# 创建一个开启配额设置的卷
juicefs format sqlite3://myjfs.db myjfs --inodes=1000000 --capacity=102400

# 创建一个关闭了回收站的卷
juicefs format sqlite3://myjfs.db myjfs --trash-days=0

参数​

项说明
META-URL用于元数据存储的数据库 URL，详情查看「JuiceFS 支持的元数据引擎」。
NAME文件系统名称。
--force强制覆盖当前的格式化配置，默认为 false。
--no-update不要修改已有的格式化配置，默认为 false。

数据存储参数​

项说明
--storage=file对象存储类型，例如 s3、gs、oss、cos。默认为 file，参考文档查看所有支持的对象存储类型。
--bucket=path存储数据的桶路径（默认：$HOME/.juicefs/local 或 /var/jfs）。
--access-key=value对象存储的 Access Key，也可通过环境变量 ACCESS_KEY 设置。查看如何设置对象存储以了解更多。
--secret-key=value对象存储的 Secret Key，也可通过环境变量 SECRET_KEY 设置。查看如何设置对象存储以了解更多。
--session-token=value对象存储的临时访问凭证（Session Token），查看如何设置对象存储以了解更多。
--storage-class=value 新增自 v1.1默认存储类型。

数据格式参数​

项说明
--block-size=4M块大小，单位为 KiB，默认 4M。4M 是一个较好的默认值，不少对象存储（比如 S3）都将 4M 设为内部的块大小，因此将 JuiceFS block size 设为相同大小，往往也能获得更好的性能。
--compress=none压缩算法，支持 lz4、zstd、none（默认），启用压缩将不可避免地对性能产生一定影响。这两种压缩算法中，lz4 提供更好的性能，但压缩比要逊于 zstd，他们的具体性能差别具体需要读者自行搜索了解。
--encrypt-rsa-key=valueRSA 私钥的路径，查看数据加密以了解更多。
--encrypt-algo=aes256gcm-rsa加密算法 (aes256gcm-rsa, chacha20-rsa) (默认："aes256gcm-rsa")
--hash-prefix对于部分对象存储服务，如果对象存储命名路径的键值（key）是连续的，那么坐落在对象存储上的物理数据也将是连续的。在大规模顺序读场景下，这样会带来数据访问热点，让对象存储服务的部分区域访问压力过大。

启用 --hash-prefix 将会给每个对象路径命名添加 hash 前缀（用 slice ID 对 256 取模，详见内部实现），相当于“打散”对象存储键值，避免在对象存储服务层面创造请求热点。显而易见，由于影响着对象存储块的命名规则，该选项必须在创建文件系统之初就指定好、不能动态修改。

目前而言，AWS S3 已经做了优化，不再需要应用侧的随机对象前缀。而对于其他对象对象存储服务（比如 COS 就在文档里推荐随机化前缀），因此，对于这些对象存储，如果文件系统规模庞大，建议启用该选项以提升性能。
--shards=0如果对象存储服务在桶级别设置了限速（或者你使用自建的对象存储服务，单个桶的性能有限），可以将数据块根据名字哈希分散存入 N 个桶中。该值默认为 0，也就是所有数据存入单个桶。当 N 大于 0 时，bucket 需要包含 %d 占位符，例如 --bucket=juicefs-%d。--shards 设置无法动态修改，需要提前规划好用量。

管理参数​

项说明
--capacity=0容量配额，单位为 GiB，默认为 0 代表不限制。如果启用了回收站，那么配额大小也将包含回收站文件。
--inodes=0文件数配额，默认为 0 代表不限制。
--trash-days=1文件被删除后，默认会进入回收站，该选项控制已删除文件在回收站内保留的天数，默认为 1，设为 0 以禁用回收站。
--enable-acl=true 新增自 v1.2启用POSIX ACL，该选项启用后暂不支持关闭。

juicefs config​

修改指定文件系统的配置项。注意更新某些设置以后，客户端未必能立刻生效，需要等待一定时间，具体的等待时间可以通过 --heartbeat 选项控制。

概览​

juicefs config [command options] META-URL

# 显示当前配置
juicefs config redis://localhost

# 改变目录的配额
juicefs config redis://localhost --inodes 10000000 --capacity 1048576

# 更改回收站中文件可被保留的最长天数
juicefs config redis://localhost --trash-days 7

# 限制允许连接的客户端版本
juicefs config redis://localhost --min-client-version 1.0.0 --max-client-version 1.1.0

参数​

项说明
--yes, -y对所有提示自动回答 "yes" 并以非交互方式运行 (默认值：false)
--force跳过合理性检查并强制更新指定配置项 (默认：false)

数据存储参数​

项说明
--storage=file 新增自 v1.1对象存储类型，例如 s3、gs、oss、cos。默认为 file，参考文档查看所有支持的对象存储类型。
--bucket=path存储数据的桶路径（默认：$HOME/.juicefs/local 或 /var/jfs）。
--access-key=value对象存储的 Access Key，也可通过环境变量 ACCESS_KEY 设置。查看如何设置对象存储以了解更多。
--secret-key=value对象存储的 Secret Key，也可通过环境变量 SECRET_KEY 设置。查看如何设置对象存储以了解更多。
--session-token=value对象存储的临时访问凭证（Session Token），查看如何设置对象存储以了解更多。
--storage-class=value 新增自 v1.1默认存储类型。
--tier-id=value 新增自 v1.4分层存储 ID（1-3），与 --tier-sc 配合使用，用于配置指定 tier 的存储类型。ID 0 为保留默认层，不可在此处配置。
--tier-sc=value 新增自 v1.4分层存储对应的对象存储类型（例如 STANDARD_IA、INTELLIGENT_TIERING、GLACIER_IR），需与 --tier-id 同时使用。
--upload-limit=0上传带宽限制，单位为 Mbps (默认：0)
--download-limit=0下载带宽限制，单位为 Mbps (默认：0)
--max-uploads=20上传并发上限（默认：20）
--max-downloads=200 新增自 v1.4下载并发上限（默认：200）

管理参数​

项说明
--capacity value容量配额，单位为 GiB
--inodes value文件数配额
--trash-days value文件被自动清理前在回收站内保留的天数
--enable-acl 新增自 v1.2开启 POSIX ACL（不支持关闭），同时允许连接的最小客户端版本会提升到 v1.2
--encrypt-secret如果密钥之前以原格式存储，则加密密钥 (默认值：false)
--min-client-version value 新增自 v1.1允许连接的最小客户端版本
--max-client-version value 新增自 v1.1允许连接的最大客户端版本
--dir-stats 新增自 v1.1开启目录统计，这是快速汇总和目录配额所必需的 (默认值：false)
--changelog 新增自 v1.4启用元数据 changelog（默认值：false）
--changelog-max-age 新增自 v1.4changelog 条目的最长保留时间，例如 2h 或 30m；0 表示不按时间清理
--changelog-max-lines 新增自 v1.4最多保留的 changelog 条目数量；0 表示不限制

juicefs quota 新增自 v1.1​

管理目录、用户和组配额

概览​

juicefs quota command [command options] META-URL

# 为目录设置配额
juicefs quota set redis://localhost --path /dir1 --capacity 1 --inodes 100

# 为用户设置配额
juicefs quota set redis://localhost --uid 1000 --capacity 2 --inodes 200

# 为组设置配额
juicefs quota set redis://localhost --gid 100 --capacity 5 --inodes 500

# 获取目录配额信息
juicefs quota get redis://localhost --path /dir1

# 获取用户/组配额信息
juicefs quota get redis://localhost --uid 1000
juicefs quota get redis://localhost --gid 100

# 列出所有配额
juicefs quota list redis://localhost

# 删除目录配额
juicefs quota delete redis://localhost --path /dir1

# 检查目录配额的一致性
juicefs quota check redis://localhost --path /dir1

# 检查用户组配额的一致性
juicefs quota check redis://localhost

参数​

项说明
META-URL用于元数据存储的数据库 URL，详情查看「JuiceFS 支持的元数据引擎」。
--path value卷中目录的全路径（用于目录配额）
--uid value用户 ID（用于用户配额）
--gid value组 ID（用于组配额）
--create目录不存在时自动创建（仅对目录配额生效）
--capacity value空间硬限制，单位 GiB (默认：0)
--inodes value硬限制 inode 数 (默认：0)
--repair修复不一致配额 (默认：false)
--strict在严格模式下计算目录的总使用量 (注意：对于大目录可能很慢) (默认：false)

juicefs destroy​

销毁一个已经存在的文件系统，将会清空元数据引擎与对象存储中的相关数据。详见「如何销毁文件系统」。

概览​

juicefs destroy [command options] META-URL UUID

juicefs destroy redis://localhost e94d66a8-2339-4abd-b8d8-6812df737892

参数​

项说明
--yes, -y 新增自 v1.1对所有提示自动回答 "yes" 并以非交互方式运行 (默认值：false)
--force跳过合理性检查并强制销毁文件系统 (默认：false)

juicefs gc​

如果对象存储块因为某种原因，完全脱离了 JuiceFS 的管理，也就是对象存储上依然还存在，但在 JuiceFS 元数据已经不复存在，无法被回收释放，这种现象称作「对象泄漏」。如果你并没有进行任何特殊操作，那么对象泄露通常昭示着 bug，建议提交 GitHub Issue。

与此同时，你可以用该命令清理泄漏对象。顺带一提，该命令还能够清理失效的文件碎片。详见「状态检查 & 维护」。

概览​

juicefs gc [command options] META-URL

# 只检查，没有更改的能力
juicefs gc redis://localhost

# 触发所有 slices 的压缩
juicefs gc redis://localhost --compact

# 删除泄露的对象
juicefs gc redis://localhost --delete

参数​

项说明
--compact对所有文件执行碎片合并。
--delete删除泄漏的对象，以及因不完整的 clone 命令而产生泄漏的元数据。
--threads=10并发线程数，默认为 10。

juicefs fsck​

检查文件系统一致性。

概览​

juicefs fsck [command options] META-URL

juicefs fsck redis://localhost

参数​

项说明
--path value 新增自 v1.1待检查的 JuiceFS 中的绝对路径
--repair 新增自 v1.1发现损坏后尽可能修复 (默认：false)
--recursive, -r 新增自 v1.1递归检查或修复 (默认值：false)
--sync-dir-stat 新增自 v1.1同步所有目录的状态，即使他们没有损坏 (注意：巨大的文件树可能会花费很长时间) (默认：false)
--repair-dir-mode value 新增自 v1.4修复目录时使用的权限模式，八进制格式（默认值："0755"）

juicefs restore 新增自 v1.1​

重新构建回收站文件的树结构，并将它们放回原始目录。如果需要恢复文件存在命名冲突，程序会直接跳过，不会覆盖新创建的文件（注意日志中会有提示）。

概览​

juicefs restore [command options] META HOUR ...

juicefs restore redis://localhost/1 2023-05-10-01

参数​

项说明
--put-back将恢复的文件移动到原始目录，面对命名冲突时会直接跳过，不会覆盖已有文件。
--threads=10线程数，默认 10，如果恢复速度慢，增加并发以提速。

juicefs dump​

导出元数据。阅读「元数据备份」以了解更多。

概览​

juicefs dump [command options] META-URL [FILE]

# 导出元数据至 meta-dump.json
juicefs dump redis://localhost meta-dump.json

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

参数​

项说明
META-URL用于元数据存储的数据库 URL，详情查看「JuiceFS 支持的元数据引擎」。
FILE导出文件路径，如果不指定，则会导出到标准输出。如果文件名以 .gz 结尾，将会自动压缩。
--subdir=path只导出指定子目录的元数据。
--keep-secret-key 新增自 v1.1导出对象存储认证信息，默认为 false。由于是明文导出，使用时注意数据安全。如果导出文件不包含对象存储认证信息，后续的导入完成后，需要用 juicefs config 重新配置对象存储认证信息。
--threads=10 新增自 v1.2并发线程数，默认 10。
--fast 新增自 v1.2使用更多内存来加速导出。
--skip-trash 新增自 v1.2跳过回收站中的文件和目录。

juicefs load​

将元数据导入一个空的文件系统。阅读「元数据恢复与迁移」以了解更多。

概览​

juicefs load [command options] META-URL [FILE]

# 将元数据备份文件 meta-dump.json 导入数据库
juicefs load redis://127.0.0.1:6379/1 meta-dump.json

参数​

项说明
META-URL用于元数据存储的数据库 URL，详情查看「JuiceFS 支持的元数据引擎」。
FILE导入文件路径，如果不指定，则会从标准输入导入。如果文件名以 .gz 结尾，将会自动解压。
--encrypt-rsa-key=path 新增自 v1.0.4加密所使用的 RSA 私钥文件路径。
--encrypt-algo=aes256gcm-rsa 新增自 v1.0.4加密算法，默认为 aes256gcm-rsa。

检视​

juicefs changelog 新增自 v1.4​

跟踪显示文件系统元数据操作的 changelog。用法和保留策略详见「元数据 Changelog」。使用前需要先启用 changelog 功能：

juicefs config redis://localhost --changelog

概览​

juicefs changelog [command options] META-URL

# 从最新的 changelog 开始跟踪
juicefs changelog redis://localhost

# 从指定元数据版本开始跟踪
juicefs changelog redis://localhost --from 100

参数​

项说明
META-URL用于元数据存储的数据库 URL，详情查看「JuiceFS 支持的元数据引擎」。
--from=0从指定元数据版本开始显示 changelog。0 表示从最新版本开始跟踪。

juicefs status​

显示 JuiceFS 的状态。

概览​

juicefs status [command options] META-URL

juicefs status redis://localhost

参数​

项说明
--session=0, -s 0展示指定会话 (SID) 的具体信息 (默认：0)
--more, -m 新增自 v1.1显示更多的统计信息，可能需要很长时间 (默认值：false)

juicefs stats​

展示实时的性能统计信息，阅读「实时性能监控」以了解更多。

概览​

juicefs stats [command options] MOUNTPOINT

juicefs stats /mnt/jfs

# 更多的指标
juicefs stats /mnt/jfs -l 1

参数​

项说明
--schema=ufmco控制输出内容的标题字符串，默认为 ufmco，含义如下：
u：usage
f：FUSE
m：metadata
c：block cache
o：object storage
g：Go
--interval=1更新间隔；单位为秒 (默认：1)
--verbosity=0详细级别；通常 0 或 1 已足够 (默认：0)

juicefs profile​

展示基于文件系统访问日志的实时监控数据，阅读「实时性能监控」以了解更多。

概览​

juicefs profile [command options] MOUNTPOINT/LOGFILE

# 监控实时操作
juicefs profile /mnt/jfs

# 重放访问日志
cat /mnt/jfs/.accesslog > /tmp/jfs.alog
# 一段时间后按 Ctrl-C 停止 "cat" 命令
juicefs profile /tmp/jfs.alog

# 分析访问日志并立即打印总统计数据
juicefs profile /tmp/jfs.alog --interval 0

参数​

项说明
--uid=value, -u value仅跟踪指定 UIDs (用逗号分隔)
--gid=value, -g value仅跟踪指定 GIDs (用逗号分隔)
--pid=value, -p value仅跟踪指定 PIDs (用逗号分隔)
--interval=2显示间隔；在回放模式中将其设置为 0 可以立即得到整体的统计结果；单位为秒 (默认：2)

juicefs info​

显示指定路径或 inode 的内部信息。

概览​

juicefs info [command options] PATH or INODE

# 检查路径
juicefs info /mnt/jfs/foo

# 检查 inode
cd /mnt/jfs
juicefs info -i 100

参数​

项说明
--inode, -i使用 inode 号而不是路径 (当前目录必须在 JuiceFS 挂载点内) (默认：false)
--recursive, -r递归获取所有子目录的概要信息，当指定一个目录结构很复杂的路径时可能会耗时很长） (默认：false)
--strict 新增自 v1.1获取准确的目录概要 (注意：巨大的文件树可能会花费很长的时间) (默认：false)
--raw显示内部原始信息 (默认：false)

juicefs debug 新增自 v1.1​

从运行环境、系统日志等多个维度收集和展示信息，帮助更好地定位错误

概览​

juicefs debug [command options] MOUNTPOINT

# 收集并展示挂载点 /mnt/jfs 的各类信息
juicefs debug /mnt/jfs

# 指定输出目录为 /var/log
juicefs debug --out-dir=/var/log /mnt/jfs

# 收集最后 1000 条日志条目
juicefs debug --out-dir=/var/log --limit=1000 /mnt/jfs

参数​

项说明
--out-dir=./debug/结果输出目录，若目录不存在则自动创建，默认为 ./debug/。
--limit=value收集的日志条目数，从新到旧，若不指定则收集全部条目
--stats-sec=5.stats 文件采样秒数 (默认：5)
--trace-sec=5trace 指标采样秒数 (默认：5)
--profile-sec=30profile 指标采样秒数 (默认：30)

juicefs summary 新增自 v1.1​

显示目标目录树摘要。

概览​

juicefs summary [command options] PATH

juicefs summary /mnt/jfs/foo

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

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

# 显示准确的结果
juicefs summary --strict /mnt/jfs/foo

参数​

项说明
--depth value, -d value显示树的深度 (0 表示只显示根) (默认：2)
--entries value, -e value显示前 N 个 entry (按大小排序)(默认：10)
--strict显示准确的摘要，包括目录和文件 (可能很慢) (默认值：false)
--csv以 CSV 格式打印摘要 (默认：false)

服务​

juicefs mount​

挂载一个已经创建的文件系统。

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

概要​

juicefs mount [command options] META-URL MOUNTPOINT

# 前台挂载
juicefs mount redis://localhost /mnt/jfs

# 使用带密码的 redis 后台挂载
juicefs mount redis://:mypassword@localhost /mnt/jfs -d
# 更安全的方式
META_PASSWORD=mypassword juicefs mount redis://localhost /mnt/jfs -d

# 将一个子目录挂载为根目录
juicefs mount redis://localhost /mnt/jfs --subdir /dir/in/jfs

# 开启写缓存（writeback）模式，可以提升写入性能但同时有数据丢失风险
juicefs mount redis://localhost /mnt/jfs -d --writeback

# 开启只读模式
juicefs mount redis://localhost /mnt/jfs -d --read-only

# 关闭元数据自动备份
juicefs mount redis://localhost /mnt/jfs --backup-meta 0

参数​

项说明
META-URL用于元数据存储的数据库 URL，详情查看「JuiceFS 支持的元数据引擎」。
MOUNTPOINT文件系统挂载点，例如：/mnt/jfs、Z:。
-d, --background后台运行，默认为 false。
--no-syslog禁用系统日志，默认为 false。
--hide-internal 新增自 v1.4在目录列表中隐藏所有内部文件（.accesslog、.stats、.config、.control），这些文件仍可通过完整路径访问（默认值：false）。
--log=path后台运行时日志文件的位置 (默认：$HOME/.juicefs/juicefs.log 或 /var/log/juicefs.log)
--force强制挂载即使挂载点已经被相同的文件系统挂载 (默认值:false)
--update-fstab 新增自 v1.1新增／更新 /etc/fstab 中的条目，如果不存在将会创建一个从 /sbin/mount.juicefs 到 JuiceFS 可执行文件的软链接，默认为 false。
--disable-transparent-hugepage 新增自 v1.3关闭内核的透明大页（THP），内存紧张时，THP 可能导致进程挂起等待，默认为 false。

FUSE 相关参数​

项说明
--enable-xattr启用扩展属性 (xattr) 功能，默认为 false。
--enable-cap 新增自 v1.3启用 security.capability 扩展属性 (xattr) ，默认为 false。
--enable-selinux 新增自 v1.3启用 security.selinux 扩展属性 (xattr) ，默认为 false。
--enable-ioctl 新增自 v1.1启用 ioctl (仅支持 GETFLAGS/SETFLAGS) (默认：false)
--root-squash value 新增自 v1.1将本地 root 用户 (UID=0) 映射到一个指定用户，如 UID:GID
--all-squash value 新增自 v1.3将所有用户映射到一个指定用户，如 UID:GID
--umask value 新增自 v1.3新文件和新目录的 umask 的八进制格式
--prefix-internal 新增自 v1.1挂载 JuiceFS 后，挂载点下默认创建 .stats, .accesslog 等虚拟文件。如果这些内部文件和你的应用发生冲突，可以启用该选项，添加 .jfs 前缀到所有内部文件。
--max-fuse-io=128K 新增自 v1.3fuse 请求最大大小 (默认：128K)
-o value其他 FUSE 选项，详见 FUSE 挂载选项

元数据相关参数​

项说明
--subdir=value挂载指定的子目录，默认挂载整个文件系统。
--backup-meta=3600自动备份元数据到对象存储的间隔时间；单位秒，默认 3600，设为 0 表示不备份。
--backup-skip-trash 新增自 v1.2备份元数据时跳过回收站中的文件和目录。
--heartbeat=12发送心跳的间隔（单位秒），建议所有客户端使用相同的心跳值 (默认：12)
--read-only只读模式，只允许 lookup 和 read 请求。注意，只读模式隐含了 --no-bgjob，因此只读客户端不会运行后台任务。
--no-bgjob禁用后台任务，默认为 false，也就是说客户端会默认运行后台任务。后台任务包含：
  • 清理回收站中过期的文件（在 pkg/meta/base.go 中搜索 cleanupDeletedFiles 和 cleanupTrash）
  • 清理引用计数为 0 的 Slice（在 pkg/meta/base.go 中搜索 cleanupSlices）
  • 清理过期的客户端会话（在 pkg/meta/base.go 中搜索 CleanStaleSessions）
特别地，与企业版不同，社区版碎片合并（Compaction）不受该选项的影响，而是随着文件读写操作，自动判断是否需要合并，然后异步执行（以 Redis 为例，在 pkg/meta/base.go 中搜索 compactChunk）
--atime-mode=noatime 新增自 v1.1控制如何更新 atime（文件最后被访问的时间）。支持以下模式：
  • noatime（默认）：仅在文件创建和主动调用 SetAttr 时设置，平时访问与修改文件不影响 atime 值。考虑到更新 atime 需要运行额外的事务，对性能有影响，因此默认关闭。
  • relatime：仅在 mtime（文件内容修改时间）或 ctime（文件元数据修改时间）比 atime 新，或者 atime 超过 24 小时没有更新时进行更新。
  • strictatime：持续更新 atime
--skip-dir-nlink=20 新增自 v1.1跳过更新目录 nlink 前的重试次数 (仅用于 TKV, 0 代表永不跳过) (默认：20)
--skip-dir-mtime=100ms 新增自 v1.2如果 mtime 差异小于该值（默认值：100ms），则跳过更新目录的属性。
--sort-dir 新增自 v1.3按名称对目录中的条目进行排序
--fast-statfs 新增自 v1.3通过使用本地缓存减少元数据访问提升statfs性能，准确性会降低（默认：false）
--network-interfaces=value 新增自 v1.4用于 IP 发现的网络接口白名单；仅使用指定的接口，逗号分隔（例如 eth0,en0），为空表示使用所有接口。

元数据缓存参数​

元数据缓存的介绍和使用，详见「内核元数据缓存」及「客户端内存元数据缓存」。

项说明
--attr-cache=1属性缓存过期时间；单位为秒，默认为 1。
--entry-cache=1文件项缓存过期时间；单位为秒，默认为 1。
--dir-entry-cache=1目录项缓存过期时间；单位为秒，默认为 1。
--open-cache=0打开的文件的缓存过期时间，单位为秒，默认为 0，代表关闭该特性。
--open-cache-limit=value 新增自 v1.1允许缓存的最大文件个数 (软限制，0 代表不限制) (默认：10000)
--readdir-cache=false 新增自 v1.3, only for mount开启目录项缓存，默认为 false，代表不开启
--negative-entry-cache=0 新增自 v1.3, only for mount失败 lookup 查询 (返回 ENOENT) 缓存过期时间，默认为 0，代表不缓存

数据存储参数​

项说明
--storage=file对象存储类型 (例如 s3、gs、oss、cos) (默认："file"，参考文档查看所有支持的对象存储类型)
--bucket=value为当前挂载点指定访问对象存储的 Endpoint。
--storage-class value 新增自 v1.1当前客户端写入数据的存储类型
--get-timeout=60下载一个对象的超时时间；单位为秒 (默认：60)
--put-timeout=60上传一个对象的超时时间；单位为秒 (默认：60)
--io-retries=10网络异常时的重试次数，元数据请求的重试次数也由这个选项控制。如果超过重试次数将会返回 EIO Input/output error 错误。（默认：10）
--max-uploads=20上传并发度，默认为 20。对于粒度为 4M 的写入模式，20 并发已经是很高的默认值，在这样的写入模式下，提高写并发往往需要伴随增大 --buffer-size, 详见「读写缓冲区」。但面对百 K 级别的小随机写，并发量大的时候很容易产生阻塞等待，造成写入速度恶化。如果无法改善应用写模式，对其进行合并，那么需要考虑采用更高的写并发，避免排队等待。
--max-stage-write=0 新增自 v1.2异步写入数据块到缓存盘的最大并发数，如果达到最大并发数则会直接上传对象存储（此选项仅在启用「客户端写缓存」时有效）（默认值：0，即没有并发限制）
--max-deletes=10删除对象的连接数 (默认：10)
--upload-limit=0上传带宽限制，单位为 Mbps (默认：0)
--download-limit=0下载带宽限制，单位为 Mbps (默认：0)
--check-storage新增自 v1.3在挂载前测试存储以提前暴露访问问题

数据缓存相关参数​

项说明
--buffer-size=300读写缓冲区的总大小；单位为 MiB (默认：300)。阅读「读写缓冲区」了解更多。
--prefetch=1并发预读 N 个块 (默认：1)。阅读「客户端读缓存」了解更多。
--writeback后台异步上传对象，默认为 false。阅读「客户端写缓存」了解更多。
--writeback-threshold-size=0 新增自 v1.4启用 --writeback 后，仅小于此大小的数据块会暂存到本地缓存，较大的数据块将直接上传。默认为 0，表示所有数据块都暂存。
--upload-delay=0启用 --writeback 后，可以使用该选项控制数据延迟上传到对象存储，默认为 0 秒，相当于写入后立刻上传。该选项也支持 s（秒）、m（分）、h（时）这些单位。如果在等待的时间内数据被应用删除，则无需再上传到对象存储。如果数据只是临时落盘，可以考虑用该选项节约资源。阅读「客户端写缓存」了解更多。
--upload-hours 新增自 v1.2启用 --writeback 后，只在一天中指定的时间段上传数据块。参数的格式为 <起始小时>,<结束小时>（含「起始小时」，但是不含「结束小时」，「起始小时」必须小于或者大于「结束小时」），其中 <小时> 的取值范围为 0 到 23。例如 0,6 表示只在每天 0:00 至 5:59 之间上传数据块、23,3 表示只在每天 23:00 至第二天 2:59 之间上传数据块。
--cache-dir=value本地缓存目录路径；使用 :（Linux、macOS）或 ;（Windows）隔离多个路径 (默认：$HOME/.juicefs/cache 或 /var/jfsCache)。阅读「客户端读缓存」了解更多。
--cache-mode value 新增自 v1.1缓存块的文件权限 (默认："0600")
--cache-size=102400缓存对象的总大小；单位为 MiB (默认：102400)。阅读「客户端读缓存」了解更多。
--cache-items=0 新增自 v1.3最大缓存项目数 (默认会根据free-space-ratio计算最大值)
--free-space-ratio=0.1最小剩余空间比例，默认为 0.1。如果启用了「客户端写缓存」，则该参数还控制着写缓存占用空间。阅读「客户端读缓存」了解更多。
--cache-partial-only仅缓存随机小块读，默认为 false。阅读「客户端读缓存」了解更多。
--cache-large-write 新增自 v1.3在上传后缓存完整数据块
--verify-cache-checksum=extend 新增自 v1.1缓存数据一致性检查级别，启用 Checksum 校验后，生成缓存文件时会对数据切分做 Checksum 并记录于文件末尾，供读缓存时进行校验。支持以下级别：
  • none：禁用一致性检查，如果本地数据被篡改，将会读到错误数据；
  • full（1.3 以前的默认值）：读完整数据块时才校验，适合顺序读场景；
  • shrink：对读范围内的切片数据进行校验，校验范围不包含读边界所在的切片（可以理解为开区间），适合随机读场景；
  • extend（1.3+ 的默认值）：对读范围内的切片数据进行校验，校验范围同时包含读边界所在的切片（可以理解为闭区间），因此将带来一定程度的读放大，适合对正确性有极致要求的随机读场景。
--cache-eviction=2-random 新增自 v1.1缓存逐出策略（none、2-random 或 lru 新增自 v1.4）（默认值：2-random）
--cache-scan-interval=1h 新增自 v1.1扫描缓存目录重建内存索引的间隔（以秒为单位）（默认值：1h）
--cache-expire=0 新增自 v1.2超过设置的时间未被访问的缓存块将会被自动清除（即使 --cache-eviction 的值为 none，这些缓存块也会被删除），单位为秒，值为 0 表示永不过期（默认值：0）
--max-readahead 新增自 v1.3最大预读缓冲区大小，单位为 MiB

监控相关参数​

项说明
--metrics=127.0.0.1:9567监控数据导出地址，默认为 127.0.0.1:9567。
--custom-labels监控指标自定义标签，格式为 key1:value1;key2:value2 (默认："")
--consul=127.0.0.1:8500Consul 注册中心地址，默认为 127.0.0.1:8500。
--no-usage-report不发送使用量信息 (默认：false)

Windows 相关参数​

项说明
--o=可以用于指定 FUSE 的额外挂载参数，具体支持情况由 WinFsp 决定。
--log=c:/juicefs.log 新增自 v1.3JuiceFS 日志保存路径（仅对后台运行生效）。
-d 新增自 v1.3是否后台运行。在 Windows 系统下，指定了后台运行后，JuiceFS 将以系统服务运行。（注：运行此参数时，需要有管理员权限，并且同一时间只能挂载一个文件系统）
--fuse-trace-log=c:/fuse.log 新增自 v1.3用于指定 WinFsp FUSE 层的回调日志。（默认：""）
--as-root这是一个兼容选项，开启此设置后，将会把所有文件 uid,gid 以及写入的身份都映射为 root(uid=0) 用户。
--show-dot-files 新增自 v1.3 显示.开头的文件。默认情况下，这些文件会被设置为隐藏文件。
--winfsp-threads=16 新增自 v1.3设置 WinFsp 用于处理内核事件的线程数量，默认为 min(CPU 核数 * 2, 16)。
--report-case 新增自 v1.3配置 JuiceFS 在处理文件名时，是否尽可能上报精确的大小写信息。例如在使用 aaa.txt 打开一个实际为 AAA.txt 的文件名时，JuiceFS 是否向 Windows 内核汇报实际的文件名。（打开此选项可能会对性能有影响）

juicefs umount​

卸载 JuiceFS 文件系统。

概要​

juicefs umount [command options] MOUNTPOINT

juicefs umount /mnt/jfs

参数​

项说明
-f, --force强制卸载一个忙碌的文件系统 (默认：false)
--flush 新增自 v1.1等待所有暂存块被刷新 (默认值：false)

juicefs gateway​

启动一个 S3 兼容的网关，详见「配置 JuiceFS S3 网关」。

概览​

juicefs gateway [command options] META-URL ADDRESS

export MINIO_ROOT_USER=admin
export MINIO_ROOT_PASSWORD=12345678
juicefs gateway redis://localhost localhost:9000

参数​

项说明
META-URL用于元数据存储的数据库 URL，详情查看「JuiceFS 支持的元数据引擎」。
ADDRESSS3 网关地址和监听的端口，例如：localhost:9000
--log value 新增自 v1.2网关日志路径
--access-log=path访问日志的路径
--background, -d 新增自 v1.2后台运行（默认：false）
--no-banner禁用 MinIO 的启动信息（默认：false）
--multi-buckets使用第一级目录作为存储桶（默认：false）
--keep-etag保留对象上传时的 ETag（默认：false）
--umask=022新文件和新目录的 umask 的八进制格式（默认值：022）
--head-dir标准的 S3 协议是没有「目录」这一概念的，因此默认情况下，为了符合 S3 协议，该选项是关闭的，此时对目录进行 HEAD 请求，会返回 404，除非该是显式 PUT 创建的（用类似 aws s3api put-object --key /path/dirname/ 的方式）。

在 --head-dir 未开启的情况下，S3 Gateway 会使用目录的 atime 作为目录是否显式创建的判断标准：如果 atime 为 0，则视为显式创建，可以进行 HEAD 请求；如果 atime 大于 0，则视为隐式创建，对其发起 HEAD 请求会返回 404。

在某些场景下，如果希望能够对 所有目录发起 HEAD 请求，可以启用 --head-dir 参数，让文件系统内的所有目录，都可以当做普通的 S3 对象来查询。如果要使用该功能，建议升级到 5.3.8 或者更新版本，来避免一些已知问题。
--hide-dir-object通过 S3 Gateway 在文件系统（尚不存在的）深层目录显式创建文件，目录层级因此被动创建出来，这种目录属于隐式创建目录。

--hide-dir-object 这个参数的作用是隐藏通过 PUT 请求隐式创建的目录。该选项默认关闭，在此情形下，系统会通过 atime 决定目录是否展示：如果 atime 为 0，则目录会出现在 LIST 请求中；如果 atime 大于 0，则不会显示。

如果开启该选项，则彻底隐藏隐式创建的目录，只有用类似 aws s3api put-object --key /path/dirname/ 的方式显式创建目录（atime 为 0），才能够被 LIST 请求展示出来。
--object-tag 新增自 v1.2启用对象标签 API
--domain value 新增自 v1.2虚拟主机样式请求的域
--refresh-iam-interval=5m 新增自 v1.2重新加载网关 IAM 配置的间隔时间（默认值：5 分钟）

元数据相关参数​

项说明
--subdir=value挂载指定的子目录，默认挂载整个文件系统。
--backup-meta=3600自动备份元数据到对象存储的间隔时间；单位秒，默认 3600，设为 0 表示不备份。
--backup-skip-trash 新增自 v1.2备份元数据时跳过回收站中的文件和目录。
--heartbeat=12发送心跳的间隔（单位秒），建议所有客户端使用相同的心跳值 (默认：12)
--read-only只读模式，只允许 lookup 和 read 请求。注意，只读模式隐含了 --no-bgjob，因此只读客户端不会运行后台任务。
--no-bgjob禁用后台任务，默认为 false，也就是说客户端会默认运行后台任务。后台任务包含：
  • 清理回收站中过期的文件（在 pkg/meta/base.go 中搜索 cleanupDeletedFiles 和 cleanupTrash）
  • 清理引用计数为 0 的 Slice（在 pkg/meta/base.go 中搜索 cleanupSlices）
  • 清理过期的客户端会话（在 pkg/meta/base.go 中搜索 CleanStaleSessions）
特别地，与企业版不同，社区版碎片合并（Compaction）不受该选项的影响，而是随着文件读写操作，自动判断是否需要合并，然后异步执行（以 Redis 为例，在 pkg/meta/base.go 中搜索 compactChunk）
--atime-mode=noatime 新增自 v1.1控制如何更新 atime（文件最后被访问的时间）。支持以下模式：
  • noatime（默认）：仅在文件创建和主动调用 SetAttr 时设置，平时访问与修改文件不影响 atime 值。考虑到更新 atime 需要运行额外的事务，对性能有影响，因此默认关闭。
  • relatime：仅在 mtime（文件内容修改时间）或 ctime（文件元数据修改时间）比 atime 新，或者 atime 超过 24 小时没有更新时进行更新。
  • strictatime：持续更新 atime
--skip-dir-nlink=20 新增自 v1.1跳过更新目录 nlink 前的重试次数 (仅用于 TKV, 0 代表永不跳过) (默认：20)
--skip-dir-mtime=100ms 新增自 v1.2如果 mtime 差异小于该值（默认值：100ms），则跳过更新目录的属性。
--sort-dir 新增自 v1.3按名称对目录中的条目进行排序
--fast-statfs 新增自 v1.3通过使用本地缓存减少元数据访问提升statfs性能，准确性会降低（默认：false）
--network-interfaces=value 新增自 v1.4用于 IP 发现的网络接口白名单；仅使用指定的接口，逗号分隔（例如 eth0,en0），为空表示使用所有接口。

元数据缓存参数​

元数据缓存的介绍和使用，详见「内核元数据缓存」及「客户端内存元数据缓存」。

项说明
--attr-cache=1属性缓存过期时间；单位为秒，默认为 1。
--entry-cache=1文件项缓存过期时间；单位为秒，默认为 1。
--dir-entry-cache=1目录项缓存过期时间；单位为秒，默认为 1。
--open-cache=0打开的文件的缓存过期时间，单位为秒，默认为 0，代表关闭该特性。
--open-cache-limit=value 新增自 v1.1允许缓存的最大文件个数 (软限制，0 代表不限制) (默认：10000)
--readdir-cache=false 新增自 v1.3, only for mount开启目录项缓存，默认为 false，代表不开启
--negative-entry-cache=0 新增自 v1.3, only for mount失败 lookup 查询 (返回 ENOENT) 缓存过期时间，默认为 0，代表不缓存

数据存储参数​

项说明
--storage=file对象存储类型 (例如 s3、gs、oss、cos) (默认："file"，参考文档查看所有支持的对象存储类型)
--bucket=value为当前挂载点指定访问对象存储的 Endpoint。
--storage-class value 新增自 v1.1当前客户端写入数据的存储类型
--get-timeout=60下载一个对象的超时时间；单位为秒 (默认：60)
--put-timeout=60上传一个对象的超时时间；单位为秒 (默认：60)
--io-retries=10网络异常时的重试次数，元数据请求的重试次数也由这个选项控制。如果超过重试次数将会返回 EIO Input/output error 错误。（默认：10）
--max-uploads=20上传并发度，默认为 20。对于粒度为 4M 的写入模式，20 并发已经是很高的默认值，在这样的写入模式下，提高写并发往往需要伴随增大 --buffer-size, 详见「读写缓冲区」。但面对百 K 级别的小随机写，并发量大的时候很容易产生阻塞等待，造成写入速度恶化。如果无法改善应用写模式，对其进行合并，那么需要考虑采用更高的写并发，避免排队等待。
--max-stage-write=0 新增自 v1.2异步写入数据块到缓存盘的最大并发数，如果达到最大并发数则会直接上传对象存储（此选项仅在启用「客户端写缓存」时有效）（默认值：0，即没有并发限制）
--max-deletes=10删除对象的连接数 (默认：10)
--upload-limit=0上传带宽限制，单位为 Mbps (默认：0)
--download-limit=0下载带宽限制，单位为 Mbps (默认：0)
--check-storage新增自 v1.3在挂载前测试存储以提前暴露访问问题

数据缓存相关参数​

项说明
--buffer-size=300读写缓冲区的总大小；单位为 MiB (默认：300)。阅读「读写缓冲区」了解更多。
--prefetch=1并发预读 N 个块 (默认：1)。阅读「客户端读缓存」了解更多。
--writeback后台异步上传对象，默认为 false。阅读「客户端写缓存」了解更多。
--writeback-threshold-size=0 新增自 v1.4启用 --writeback 后，仅小于此大小的数据块会暂存到本地缓存，较大的数据块将直接上传。默认为 0，表示所有数据块都暂存。
--upload-delay=0启用 --writeback 后，可以使用该选项控制数据延迟上传到对象存储，默认为 0 秒，相当于写入后立刻上传。该选项也支持 s（秒）、m（分）、h（时）这些单位。如果在等待的时间内数据被应用删除，则无需再上传到对象存储。如果数据只是临时落盘，可以考虑用该选项节约资源。阅读「客户端写缓存」了解更多。
--upload-hours 新增自 v1.2启用 --writeback 后，只在一天中指定的时间段上传数据块。参数的格式为 <起始小时>,<结束小时>（含「起始小时」，但是不含「结束小时」，「起始小时」必须小于或者大于「结束小时」），其中 <小时> 的取值范围为 0 到 23。例如 0,6 表示只在每天 0:00 至 5:59 之间上传数据块、23,3 表示只在每天 23:00 至第二天 2:59 之间上传数据块。
--cache-dir=value本地缓存目录路径；使用 :（Linux、macOS）或 ;（Windows）隔离多个路径 (默认：$HOME/.juicefs/cache 或 /var/jfsCache)。阅读「客户端读缓存」了解更多。
--cache-mode value 新增自 v1.1缓存块的文件权限 (默认："0600")
--cache-size=102400缓存对象的总大小；单位为 MiB (默认：102400)。阅读「客户端读缓存」了解更多。
--cache-items=0 新增自 v1.3最大缓存项目数 (默认会根据free-space-ratio计算最大值)
--free-space-ratio=0.1最小剩余空间比例，默认为 0.1。如果启用了「客户端写缓存」，则该参数还控制着写缓存占用空间。阅读「客户端读缓存」了解更多。
--cache-partial-only仅缓存随机小块读，默认为 false。阅读「客户端读缓存」了解更多。
--cache-large-write 新增自 v1.3在上传后缓存完整数据块
--verify-cache-checksum=extend 新增自 v1.1缓存数据一致性检查级别，启用 Checksum 校验后，生成缓存文件时会对数据切分做 Checksum 并记录于文件末尾，供读缓存时进行校验。支持以下级别：
  • none：禁用一致性检查，如果本地数据被篡改，将会读到错误数据；
  • full（1.3 以前的默认值）：读完整数据块时才校验，适合顺序读场景；
  • shrink：对读范围内的切片数据进行校验，校验范围不包含读边界所在的切片（可以理解为开区间），适合随机读场景；
  • extend（1.3+ 的默认值）：对读范围内的切片数据进行校验，校验范围同时包含读边界所在的切片（可以理解为闭区间），因此将带来一定程度的读放大，适合对正确性有极致要求的随机读场景。
--cache-eviction=2-random 新增自 v1.1缓存逐出策略（none、2-random 或 lru 新增自 v1.4）（默认值：2-random）
--cache-scan-interval=1h 新增自 v1.1扫描缓存目录重建内存索引的间隔（以秒为单位）（默认值：1h）
--cache-expire=0 新增自 v1.2超过设置的时间未被访问的缓存块将会被自动清除（即使 --cache-eviction 的值为 none，这些缓存块也会被删除），单位为秒，值为 0 表示永不过期（默认值：0）
--max-readahead 新增自 v1.3最大预读缓冲区大小，单位为 MiB

监控相关参数​

项说明
--metrics=127.0.0.1:9567监控数据导出地址，默认为 127.0.0.1:9567。
--custom-labels监控指标自定义标签，格式为 key1:value1;key2:value2 (默认："")
--consul=127.0.0.1:8500Consul 注册中心地址，默认为 127.0.0.1:8500。
--no-usage-report不发送使用量信息 (默认：false)

Windows 相关参数​

项说明
--o=可以用于指定 FUSE 的额外挂载参数，具体支持情况由 WinFsp 决定。
--log=c:/juicefs.log 新增自 v1.3JuiceFS 日志保存路径（仅对后台运行生效）。
-d 新增自 v1.3是否后台运行。在 Windows 系统下，指定了后台运行后，JuiceFS 将以系统服务运行。（注：运行此参数时，需要有管理员权限，并且同一时间只能挂载一个文件系统）
--fuse-trace-log=c:/fuse.log 新增自 v1.3用于指定 WinFsp FUSE 层的回调日志。（默认：""）
--as-root这是一个兼容选项，开启此设置后，将会把所有文件 uid,gid 以及写入的身份都映射为 root(uid=0) 用户。
--show-dot-files 新增自 v1.3 显示.开头的文件。默认情况下，这些文件会被设置为隐藏文件。
--winfsp-threads=16 新增自 v1.3设置 WinFsp 用于处理内核事件的线程数量，默认为 min(CPU 核数 * 2, 16)。
--report-case 新增自 v1.3配置 JuiceFS 在处理文件名时，是否尽可能上报精确的大小写信息。例如在使用 aaa.txt 打开一个实际为 AAA.txt 的文件名时，JuiceFS 是否向 Windows 内核汇报实际的文件名。（打开此选项可能会对性能有影响）

juicefs webdav​

启动一个 WebDAV 服务，阅读「配置 WebDAV 服务」以了解更多。

概览​

juicefs webdav [command options] META-URL ADDRESS

juicefs webdav redis://localhost localhost:9007

参数​

项说明
META-URL用于元数据存储的数据库 URL，详情查看「JuiceFS 支持的元数据引擎」。
ADDRESSWebDAV 服务监听的地址与端口，例如：localhost:9007
--cert-file 新增自 v1.1HTTPS 证书文件
--key-file 新增自 v1.1HTTPS 密钥文件
--gzip通过 gzip 压缩提供的文件（默认值：false）
--disallowList禁止列出目录（默认值：false）
--enable-proppatch 新增自 v1.3启用 proppatch 方法支持
--log value 新增自 v1.2WebDAV 日志路径
--access-log=path访问日志的路径
--background, -d 新增自 v1.2后台运行（默认：false）
--threads=50, -p 50新增自 v1.3用于删除作业的最大线程数（最大 255 个）

元数据相关参数​

项说明
--subdir=value挂载指定的子目录，默认挂载整个文件系统。
--backup-meta=3600自动备份元数据到对象存储的间隔时间；单位秒，默认 3600，设为 0 表示不备份。
--backup-skip-trash 新增自 v1.2备份元数据时跳过回收站中的文件和目录。
--heartbeat=12发送心跳的间隔（单位秒），建议所有客户端使用相同的心跳值 (默认：12)
--read-only只读模式，只允许 lookup 和 read 请求。注意，只读模式隐含了 --no-bgjob，因此只读客户端不会运行后台任务。
--no-bgjob禁用后台任务，默认为 false，也就是说客户端会默认运行后台任务。后台任务包含：
  • 清理回收站中过期的文件（在 pkg/meta/base.go 中搜索 cleanupDeletedFiles 和 cleanupTrash）
  • 清理引用计数为 0 的 Slice（在 pkg/meta/base.go 中搜索 cleanupSlices）
  • 清理过期的客户端会话（在 pkg/meta/base.go 中搜索 CleanStaleSessions）
特别地，与企业版不同，社区版碎片合并（Compaction）不受该选项的影响，而是随着文件读写操作，自动判断是否需要合并，然后异步执行（以 Redis 为例，在 pkg/meta/base.go 中搜索 compactChunk）
--atime-mode=noatime 新增自 v1.1控制如何更新 atime（文件最后被访问的时间）。支持以下模式：
  • noatime（默认）：仅在文件创建和主动调用 SetAttr 时设置，平时访问与修改文件不影响 atime 值。考虑到更新 atime 需要运行额外的事务，对性能有影响，因此默认关闭。
  • relatime：仅在 mtime（文件内容修改时间）或 ctime（文件元数据修改时间）比 atime 新，或者 atime 超过 24 小时没有更新时进行更新。
  • strictatime：持续更新 atime
--skip-dir-nlink=20 新增自 v1.1跳过更新目录 nlink 前的重试次数 (仅用于 TKV, 0 代表永不跳过) (默认：20)
--skip-dir-mtime=100ms 新增自 v1.2如果 mtime 差异小于该值（默认值：100ms），则跳过更新目录的属性。
--sort-dir 新增自 v1.3按名称对目录中的条目进行排序
--fast-statfs 新增自 v1.3通过使用本地缓存减少元数据访问提升statfs性能，准确性会降低（默认：false）
--network-interfaces=value 新增自 v1.4用于 IP 发现的网络接口白名单；仅使用指定的接口，逗号分隔（例如 eth0,en0），为空表示使用所有接口。

元数据缓存参数​

元数据缓存的介绍和使用，详见「内核元数据缓存」及「客户端内存元数据缓存」。

项说明
--attr-cache=1属性缓存过期时间；单位为秒，默认为 1。
--entry-cache=1文件项缓存过期时间；单位为秒，默认为 1。
--dir-entry-cache=1目录项缓存过期时间；单位为秒，默认为 1。
--open-cache=0打开的文件的缓存过期时间，单位为秒，默认为 0，代表关闭该特性。
--open-cache-limit=value 新增自 v1.1允许缓存的最大文件个数 (软限制，0 代表不限制) (默认：10000)
--readdir-cache=false 新增自 v1.3, only for mount开启目录项缓存，默认为 false，代表不开启
--negative-entry-cache=0 新增自 v1.3, only for mount失败 lookup 查询 (返回 ENOENT) 缓存过期时间，默认为 0，代表不缓存

数据存储参数​

项说明
--storage=file对象存储类型 (例如 s3、gs、oss、cos) (默认："file"，参考文档查看所有支持的对象存储类型)
--bucket=value为当前挂载点指定访问对象存储的 Endpoint。
--storage-class value 新增自 v1.1当前客户端写入数据的存储类型
--get-timeout=60下载一个对象的超时时间；单位为秒 (默认：60)
--put-timeout=60上传一个对象的超时时间；单位为秒 (默认：60)
--io-retries=10网络异常时的重试次数，元数据请求的重试次数也由这个选项控制。如果超过重试次数将会返回 EIO Input/output error 错误。（默认：10）
--max-uploads=20上传并发度，默认为 20。对于粒度为 4M 的写入模式，20 并发已经是很高的默认值，在这样的写入模式下，提高写并发往往需要伴随增大 --buffer-size, 详见「读写缓冲区」。但面对百 K 级别的小随机写，并发量大的时候很容易产生阻塞等待，造成写入速度恶化。如果无法改善应用写模式，对其进行合并，那么需要考虑采用更高的写并发，避免排队等待。
--max-stage-write=0 新增自 v1.2异步写入数据块到缓存盘的最大并发数，如果达到最大并发数则会直接上传对象存储（此选项仅在启用「客户端写缓存」时有效）（默认值：0，即没有并发限制）
--max-deletes=10删除对象的连接数 (默认：10)
--upload-limit=0上传带宽限制，单位为 Mbps (默认：0)
--download-limit=0下载带宽限制，单位为 Mbps (默认：0)
--check-storage新增自 v1.3在挂载前测试存储以提前暴露访问问题

数据缓存相关参数​

项说明
--buffer-size=300读写缓冲区的总大小；单位为 MiB (默认：300)。阅读「读写缓冲区」了解更多。
--prefetch=1并发预读 N 个块 (默认：1)。阅读「客户端读缓存」了解更多。
--writeback后台异步上传对象，默认为 false。阅读「客户端写缓存」了解更多。
--writeback-threshold-size=0 新增自 v1.4启用 --writeback 后，仅小于此大小的数据块会暂存到本地缓存，较大的数据块将直接上传。默认为 0，表示所有数据块都暂存。
--upload-delay=0启用 --writeback 后，可以使用该选项控制数据延迟上传到对象存储，默认为 0 秒，相当于写入后立刻上传。该选项也支持 s（秒）、m（分）、h（时）这些单位。如果在等待的时间内数据被应用删除，则无需再上传到对象存储。如果数据只是临时落盘，可以考虑用该选项节约资源。阅读「客户端写缓存」了解更多。
--upload-hours 新增自 v1.2启用 --writeback 后，只在一天中指定的时间段上传数据块。参数的格式为 <起始小时>,<结束小时>（含「起始小时」，但是不含「结束小时」，「起始小时」必须小于或者大于「结束小时」），其中 <小时> 的取值范围为 0 到 23。例如 0,6 表示只在每天 0:00 至 5:59 之间上传数据块、23,3 表示只在每天 23:00 至第二天 2:59 之间上传数据块。
--cache-dir=value本地缓存目录路径；使用 :（Linux、macOS）或 ;（Windows）隔离多个路径 (默认：$HOME/.juicefs/cache 或 /var/jfsCache)。阅读「客户端读缓存」了解更多。
--cache-mode value 新增自 v1.1缓存块的文件权限 (默认："0600")
--cache-size=102400缓存对象的总大小；单位为 MiB (默认：102400)。阅读「客户端读缓存」了解更多。
--cache-items=0 新增自 v1.3最大缓存项目数 (默认会根据free-space-ratio计算最大值)
--free-space-ratio=0.1最小剩余空间比例，默认为 0.1。如果启用了「客户端写缓存」，则该参数还控制着写缓存占用空间。阅读「客户端读缓存」了解更多。
--cache-partial-only仅缓存随机小块读，默认为 false。阅读「客户端读缓存」了解更多。
--cache-large-write 新增自 v1.3在上传后缓存完整数据块
--verify-cache-checksum=extend 新增自 v1.1缓存数据一致性检查级别，启用 Checksum 校验后，生成缓存文件时会对数据切分做 Checksum 并记录于文件末尾，供读缓存时进行校验。支持以下级别：
  • none：禁用一致性检查，如果本地数据被篡改，将会读到错误数据；
  • full（1.3 以前的默认值）：读完整数据块时才校验，适合顺序读场景；
  • shrink：对读范围内的切片数据进行校验，校验范围不包含读边界所在的切片（可以理解为开区间），适合随机读场景；
  • extend（1.3+ 的默认值）：对读范围内的切片数据进行校验，校验范围同时包含读边界所在的切片（可以理解为闭区间），因此将带来一定程度的读放大，适合对正确性有极致要求的随机读场景。
--cache-eviction=2-random 新增自 v1.1缓存逐出策略（none、2-random 或 lru 新增自 v1.4）（默认值：2-random）
--cache-scan-interval=1h 新增自 v1.1扫描缓存目录重建内存索引的间隔（以秒为单位）（默认值：1h）
--cache-expire=0 新增自 v1.2超过设置的时间未被访问的缓存块将会被自动清除（即使 --cache-eviction 的值为 none，这些缓存块也会被删除），单位为秒，值为 0 表示永不过期（默认值：0）
--max-readahead 新增自 v1.3最大预读缓冲区大小，单位为 MiB

监控相关参数​

项说明
--metrics=127.0.0.1:9567监控数据导出地址，默认为 127.0.0.1:9567。
--custom-labels监控指标自定义标签，格式为 key1:value1;key2:value2 (默认："")
--consul=127.0.0.1:8500Consul 注册中心地址，默认为 127.0.0.1:8500。
--no-usage-report不发送使用量信息 (默认：false)

Windows 相关参数​

项说明
--o=可以用于指定 FUSE 的额外挂载参数，具体支持情况由 WinFsp 决定。
--log=c:/juicefs.log 新增自 v1.3JuiceFS 日志保存路径（仅对后台运行生效）。
-d 新增自 v1.3是否后台运行。在 Windows 系统下，指定了后台运行后，JuiceFS 将以系统服务运行。（注：运行此参数时，需要有管理员权限，并且同一时间只能挂载一个文件系统）
--fuse-trace-log=c:/fuse.log 新增自 v1.3用于指定 WinFsp FUSE 层的回调日志。（默认：""）
--as-root这是一个兼容选项，开启此设置后，将会把所有文件 uid,gid 以及写入的身份都映射为 root(uid=0) 用户。
--show-dot-files 新增自 v1.3 显示.开头的文件。默认情况下，这些文件会被设置为隐藏文件。
--winfsp-threads=16 新增自 v1.3设置 WinFsp 用于处理内核事件的线程数量，默认为 min(CPU 核数 * 2, 16)。
--report-case 新增自 v1.3配置 JuiceFS 在处理文件名时，是否尽可能上报精确的大小写信息。例如在使用 aaa.txt 打开一个实际为 AAA.txt 的文件名时，JuiceFS 是否向 Windows 内核汇报实际的文件名。（打开此选项可能会对性能有影响）

工具​

juicefs bench​

对指定的路径做基准测试，包括对大文件和小文件的读/写/获取属性操作。详细介绍参考文档。

概览​

juicefs bench [command options] PATH

# 使用 4 个线程运行基准测试
juicefs bench /mnt/jfs -p 4

# 只运行小文件的基准测试
juicefs bench /mnt/jfs --big-file-size 0

参数​

项说明
--block-size=1块大小；单位为 MiB (默认：1)
--big-file-size=1024大文件大小；单位为 MiB (默认：1024)
--small-file-size=128小文件大小；单位为 KiB (默认：128)
--small-file-count=100小文件数量 (默认：100)
--threads=1, -p 1并发线程数 (默认：1)

juicefs objbench​

测试对象存储接口的正确性与基本性能，详细介绍参考文档。

概览​

juicefs objbench [command options] BUCKET

# 测试 S3 对象存储的基准性能
ACCESS_KEY=myAccessKey SECRET_KEY=mySecretKey juicefs objbench --storage=s3 https://mybucket.s3.us-east-2.amazonaws.com -p 6

参数​

项说明
--storage=file对象存储类型 (例如 s3、gs、oss、cos) (默认：file，参考文档查看所有支持的对象存储类型)
--access-key=value对象存储的 Access Key，也可通过环境变量 ACCESS_KEY 设置。查看如何设置对象存储以了解更多。
--secret-key=value对象存储的 Secret Key，也可通过环境变量 SECRET_KEY 设置。查看如何设置对象存储以了解更多。
--session-token value 新增自 v1.0对象存储的会话令牌
--shards新增自 v1.3如果对象存储服务在桶级别设置了限速（或者你使用自建的对象存储服务，单个桶的性能有限），可以将数据块根据名字哈希分散存入 N 个桶中。该值默认为 0，也就是所有数据存入单个桶。当 N 大于 0 时，bucket 需要包含 %d 占位符，例如 --bucket=juicefs-%d。--shards 设置无法动态修改，需要提前规划好用量。
--block-size=4096每个 IO 块的大小（以 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 [command options] [PATH ...]

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

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

参数​

项说明
--file=value, -f value指定一个包含一组路径的文件（每一行为一个文件路径）。
--threads=50, -p 50并发的工作线程数，默认 50。如果带宽不足导致下载失败，需要减少并发度，控制下载速度。
--background, -b后台运行（默认：false）
--evict 新增自 v1.2逐出已缓存的块
--check 新增自 v1.2检查数据块是否已缓存

juicefs rmr​

快速删除目录里的所有文件和子目录，效果等同于 rm -rf，但该命令直接操纵元数据，不经过内核，所以速度更快。

如果文件系统启用了回收站功能，被删除的文件会进入回收站。详见「回收站」。

参数​

项说明
--skip-trash新增自 v1.3跳过垃圾并直接删除文件（需要 root 权限）
--threads=50, -p 50新增自 v1.3用于删除作业的最大线程数（最大 255 个）

概览​

juicefs rmr PATH ...

juicefs rmr /mnt/jfs/foo

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://META-URL/

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

# 源端：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://META-URL/

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

源路径（SRC）和目标路径（DST）的格式均为：

[NAME://][ACCESS_KEY:SECRET_KEY[:SESSIONTOKEN]@]BUCKET[.ENDPOINT][/PREFIX]

其中：

  • NAME：JuiceFS 支持的数据存储类型，比如 s3、oss，完整列表见文档。
  • ACCESS_KEY 和 SECRET_KEY：访问数据存储所需的密钥信息，特殊字符需要进行 URL 转义并替换，比如 / 需要被替换为 %2F。另外，如果不清楚如何获取对象存储的 AKSK，参考这里。
  • TOKEN 用来访问对象存储的 token，部分对象存储支持使用临时的 token 以获得有限时间的权限。
  • BUCKET[.ENDPOINT]：数据存储服务的访问地址，不同存储类型格式可能不同（MinIO 目前仅支持路径风格），详见文档。
  • [/PREFIX]：可选，源路径和目标路径的前缀，可用于限定只同步某些路径中的数据。
项说明
--files-from 新增自 v1.3仅同步给定文件中记录的对象，其每行内容都是待同步对象的相对路径，如果对象是目录建议以 / 结尾
--start=KEY, -s KEY, --end=KEY, -e KEY提供 KEY 范围，来指定对象存储的 List 范围。
--end KEY, -e KEY同步的最后一个 KEY
--exclude=PATTERN排除匹配 PATTERN 的 Key。参考「模式匹配」文档了解如何使用。
--include=PATTERN不排除匹配 PATTERN 的 Key，需要与 --exclude 选项配合使用。参考「模式匹配」文档了解如何使用。
--match-full-path 新增自 v1.2使用「完整路径过滤模式」，默认为 false。参考「完整路径过滤模式」文档了解如何使用。
--max-size=SIZE 新增自 v1.2跳过大小大于 SIZE 的文件，单位字节
--min-size=SIZE 新增自 v1.2跳过大小小于 SIZE 的文件，单位字节
--max-age=DURATION 新增自 v1.2跳过最后修改时间超过 DURATION 的文件，单位秒。例如 --max-age=3600 表示仅同步在 1 小时内被修改过的文件。
--min-age=DURATION 新增自 v1.2跳过最后修改时间不超过 DURATION 的文件，单位秒。例如 --min-age=3600 表示仅同步最后修改时间距离当前时间已经超过 1 小时的文件。
--start-time=DURATION 新增自 v1.3跳过开始时间之前修改的文件。例如 2006-01-02 15:04:05
--end-time=DURATION 新增自 v1.3跳过结束时间之后修改的文件。例如 2006-01-02 15:04:05
--limit=-1限制将要处理的对象的数量，默认为 -1 表示不限制
--update, -u当源文件更新时（mtime 更新），覆盖已存在的文件，默认为 false。
--force-update, -f强制覆盖已存在的文件，默认为 false。
--existing, --ignore-non-existing 新增自 v1.1不创建任何新文件，默认为 false。
--ignore-existing 新增自 v1.1不更新任何已经存在的文件，默认为 false。
项说明
--dirs同步目录（包括空目录）。
--perms保留权限设置，默认为 false。
--links, -l将符号链接复制为符号链接，默认为 false，此时会查找并同步符号链接所指向的文件。
--inplace 新增自 v1.2当源路径的文件被修改时，直接修改目标路径中的同名文件，而不是先在目标路径中写一个临时文件，再将这个临时文件原子重命名到真实的文件名。这个选项只有当 --update 选项开启，以及目标路径的存储系统支持原地修改文件（如 JuiceFS、HDFS、NFS）时才有意义，也就是说如果目标路径的存储系统是对象存储开启这个选项是无效的。（默认值：false）
--delete-src, --deleteSrc如果目标存储已经存在，删除源存储的对象。与 rsync 不同，为保数据安全，首次执行时不会删除源存储文件，只有拷贝成功后再次运行时，扫描确认目标存储已经存在相关文件，才会删除源存储文件。
--delete-dst, --deleteDst删除目标存储下的不相关对象。
--check-all校验源路径和目标路径中所有文件的数据完整性，默认为 false。校验方式是基于字节流对比，因此也将带来相应的开销。
--check-new校验新拷贝文件的数据完整性，默认为 false。校验方式是基于字节流对比，因此也将带来相应的开销。
--check-change 新增自 v1.3校验同步前后的数据是否有变更，默认为 false。校验方式基于文件大小和 mtime，比较轻量。
--max-failure 新增自 v1.3最大允许失败的文件数（-1 表示无限）
--dry仅打印执行计划，不实际拷贝文件。
--enable-checkpoint启用 checkpoint，用于断点续传。
--checkpoint-interval=10s保存 checkpoint 的时间间隔。
--checkpoint-force-reset从头开始同步，并覆盖已有 checkpoint。
项说明
--threads=10, -p 10并发线程数，默认为 10。
--list-threads=1 新增自 v1.1并发 list 线程数，默认为 1。阅读并发 list以了解如何使用。
--list-depth=1 新增自 v1.1并发 list 目录深度，默认为 1。阅读并发 list以了解如何使用。
--no-https不要使用 HTTPS，默认为 false。
--storage-class value 新增自 v1.1目标端的新建文件的存储类型。
--bwlimit=0限制最大带宽，单位 Mbps，默认为 0 表示不限制。
--traffic-control-url value 新增自 v1.4全局流量控制服务的 URL，用于在多个 sync 实例间协调带宽。服务需提供 HTTP POST 接口，请求体 {"bytes": <请求字节数>}，响应体 {"granted": <允许字节数>, "expired": <过期时间（毫秒）>}。

--traffic-control-url 使用方法与接口定义：

# 为多个 sync 实例接入同一个全局流量控制服务
juicefs sync SRC DST --traffic-control-url http://127.0.0.1:8080/traffic-control

  • 接口定义：POST /traffic-control（以实际 URL 路径为准），Content-Type: application/json。

  • 请求定义：

    {"bytes": 1048576}
    • bytes：本次申请的带宽额度（字节数）。正数表示申请额度，负数表示返还未使用额度。

  • 返回值定义：

    {"granted": 524288, "expired": 1000}
    • granted：本次授予的可用字节数。
    • expired：本次授予额度的过期时间（毫秒）。
项说明
--manager-addr=ADDR分布式同步模式中，Manager 节点的监听地址，格式：<IP>:[port]，如果不写端口，则监听随机端口。如果没有该参数，则监听本机随机的 IPv4 地址与随机端口。
--worker=ADDR,ADDR分布式同步模式中，工作节点列表，使用逗号分隔。
项说明
--metrics value 新增自 v1.2导出监控指标的地址（默认值："127.0.0.1:9567"）
--consul value 新增自 v1.2用于注册的 Consul 地址（默认值："127.0.0.1:8500"）

juicefs clone 新增自 v1.1​

快速在同一挂载点下克隆目录或者文件，只拷贝元数据但不拷贝数据块，因此拷贝速度非常快。更多介绍详见「克隆文件或目录」。

概览​

juicefs clone [command options] SRC DST

# 克隆文件
juicefs clone /mnt/jfs/file1 /mnt/jfs/file2

# 克隆目录
juicefs clone /mnt/jfs/dir1 /mnt/jfs/dir2

# 克隆时保留文件的 UID、GID 和 mode
juicefs clone -p /mnt/jfs/file1 /mnt/jfs/file2

参数​

项说明
--preserve, -p克隆时默认使用当前用户的 UID 和 GID，而 mode 则使用当前用户的 umask 重新计算获得。如果启用该选项，则保留文件的 UID、GID 和 mode。

juicefs compact 新增自 v1.2​

对给定的目录执行碎片整理，合并或清理不连续的 slice，从而提升读性能。详细介绍参考「状态检查和维护」。

概览​

juicefs compact [command options] PATH

# 对给定目录执行碎片整理
juicefs compact /mnt/jfs

参数​

项说明
--threads, -p并发执行任务的线程数（默认：10）

juicefs tier 新增自 v1.4​

管理分层存储（Storage Tier）。详细介绍参考「分层存储」。

概览​

juicefs tier [subcommand] [command options] META-URL [PATH]

# 查看所有 tier 配置
juicefs tier list redis://localhost

# 为单个文件设置 tier
juicefs tier set redis://localhost --id 1 /path/to/file

# 递归为目录设置 tier
juicefs tier set redis://localhost --id 2 /path/to/dir -r

# 恢复归档对象
juicefs tier restore redis://localhost /path/to/dir -r

子命令​

子命令说明
list META-URL列出当前文件系统所有 tier 配置（id 与存储类型）。
set META-URL PATH为指定文件或目录设置 tier。
restore META-URL PATH向对象存储发起归档恢复请求（适用于 GLACIER / DEEP_ARCHIVE 等归档类型）。

参数​

项说明
--id valuetier ID（0-3）。0 为默认层（保留值），1-3 为可配置层。tier set 时必填。
--recursive, -r递归处理目标目录下的所有文件和子目录（默认：false）。
--force, -f强制将对象重写到 tier 当前映射的存储类型，即使 tier id 未改变（默认：false）。适用于 --tier-sc 变更后需要迁移已有对象的场景。
在 X 上关注我们
在 Discord 上交流
加入微信用户群