命令参考
这篇文档会详细的介绍 juicefs 客户端所有的命令与参数。
概况
没有任何参数执行 juicefs 时会列出所有命令和功能描述。
juicefs COMMAND [options]
COMMAND could be:
auth authorize a filesystem
mount mount a filesystem
umount umount a filesystem
info show information of file or directory
lsof list recent opened files
import import files from existing object storage
rmr remove all files/directories recursively
snapshot create or remove snapshots
grep parallelized file pattern searcher
profile analyze log (Experimental)
benchmark run benchmark
doctor collect diagnose information
warmup build cache for target directories/files
version show the version
使用方式：juicefs [COMMAND] [options]
所有命令后面加 -h 或者 --help 都可以查看参数列表和帮助信息。
juicefs auth
认证并获取文件系统的配置，配置文件将会保存为 $HOME/.juicefs/$VOL_NAME.conf。当需要通过脚本自动化部署 JuiceFS，或使用自建对象存储进行私有化部署时，该命令十分有用。
语法
juicefs auth NAME [options]
参数
| 项 | 说明 |
|---|---|
NAME | 文件系统的名字。 |
--token=TOKEN | 文件系统的 Token，在网站控制台的文件系统设置中查看。 |
--bucket=BUCKET | 对象存储的 Bucket 名称或 Endpoint 地址（可选）。 |
--access-key=ACCESSKEY | 你使用的对象存储的密钥，获取方式参见 文档。 |
--secret-key=SECRETKEY | 你使用的对象存储的密钥，获取方式参见 文档。 |
--session-token=SESSIONTOKEN | 对象存储 session token（可选） |
--bucket2=BUCKET2 | 用于文件系统复制功能的目标对象存储 Bucket 名称或 Endpoint 地址（可选）。 |
--access-key2=ACCESSKEY2 | 开启文件系统复制功能时，目标对象存储密钥（可选）。文件系统复制请详见「跨区数据复制」。 |
--secret-key2=SECRETKEY2 | 开启文件系统复制功能时，目标对象存储密钥（可选）。文件系统复制请详见「跨区数据复制」。 |
--session-token2=SESSIONTOKEN2 | 用于文件系统复制功能的对象存储 session token（可选） |
--passphrase=PASSPHRASE | 加密密钥的密码，关于数据加密详见「数据加密」。 |
--subdir=SUBDIR | 对将要挂载的子目录进行认证，如果需要的话，还可以创建出限制只允许访问子目录的客户端令牌，详见「客户端权限控制」。 |
--conf-dir=CONFDIR | 配置文件目录，默认 ~/.juicefs |
--no-update | 客户端会从默认控制台获取最新的配置，将该参数设为 true 以禁用此行为，客户端挂载时将不再访问 JuiceFS 控制台。 |
备注
- 当
--token、--accesskey和--secretkey没有以参数方式指定时，会以交互方式输入。 - 如果你的云提供商支持为云主机配置免密访问对象存储（比如 AWS IAM），
--accesskey和--secretkey为空字符串即可。如--accesskey ""，或者交互输入时直接按回车键跳过。
juicefs mount
挂载文件系统。挂载时必须提供文件系统的 Token（在网站控制台的 文件系统设置 中查看），以及访问对象存储 API 的秘钥对（参考文档 如何获取对象存储的 API 密钥）。
如果挂载文件系统之前没有通过 auth 子命令生成配置文件，那么客户端会以命令行交互的方式要求你分别提供文件系统 Token 和访问对象存储 API 的秘钥对。
JuiceFS 支持用 root 以及普通用户挂载，但由于权限不同，挂载时所使用的的缓存目录和日志文件等路径会有所区别，详见下方参数说明。
语法
juicefs mount NAME MOUNTPOINT [options]
参数
| 项 | 说明 |
|---|---|
NAME | 文件系统的名字。 |
MOUNTPOINT | 主机上的挂载路径，比如：/jfs。 |
--update-fstab | 在 Linux 挂载时，更新 /etc/fstab，详见 开机自动挂载. |
-f, --foreground | 前台运行，客户端日志也会直接在前台输出，此选项多用于调试。 |
-b, --background | 后台运行，这也是默认行为。 |
--subdir=SUBDIR | 对将要挂载的子目录进行认证，如果需要的话，还可以创建出限制只允许访问子目录的客户端令牌，详见「客户端权限控制」。 |
--ioretries=IORETRIES | 网络故障的重试次数（默认：30）。 |
--http=ADDRESS | 指定通过 HTTP 提供文件访问的监听地址，比如 localhost:8080。 |
--disallow-list | 禁止在 WebDAV 中列出目录。 |
--log=LOGPATH | 日志存储路径，视挂载用户不同，默认为 /var/log/juicefs.log 或 ~/.juicefs/log/juicefs.log。 |
-v, --verbose | 显示更多日志。 |
--no-update | 客户端会从默认控制台获取最新的配置，将该参数设为 true 以禁用此行为，客户端挂载时将不再访问 JuiceFS 控制台。 |
对象存储相关参数
| 项 | 说明 |
|---|---|
--external | 客户端默认会使用内网地址访问对象存储，该参数可以显式指定使用对象存储的外网地址。 |
--internal | 显式指定对象存储的内网地址（适用于区分内外网域名的对象存储，比如：阿里云 OSS、UCloud UFile 等）。 |
--max-uploads=MAXUPLOADS | 最大并发上传请求数，默认为 20。提高并发度往往需要伴随增大 --buffer-size, 详见「读写缓冲区」。 |
--prefetch=PREFETCH | 随机读对象存储块的一小段，会触发异步下载整个块，这个过程就是 prefetch。该参数用于控制该行为的并发度，默认为 1，设为 0 以禁用该行为。需注意，prefetch 可能在某些情况下带来读放大，详见读放大。 |
--upload-limit=UPLOADLIMIT | 上传数据所用带宽的上限，单位 Mbps，默认为 0（无限制）。除用于主动限速外，大吞吐场景下可能导致机器负载过高，考虑使用该参数控制机器负载。 |
--download-limit=DOWNLOADLIMIT | 下载数据所用带宽的上限，单位 Mbps，默认为 0（无限制）。除用于主动限速外，大吞吐场景下可能导致机器负载过高，考虑使用该参数控制机器负载。 |
--delete-limit=DELETELIMIT | 对象存储 DELETE API 调用上限（QPS），默认为 0（无限制）。某些对象存储存在 API 调用频率限制的时候，可以使用该参数进行控制。 |
--get-timeout=GETTIMEOUT | 下载单个对象的最长时间（秒），默认为 60。低带宽场景下可能需要适当增大，详见读写错误 |
--put-timeout=PUTTIMEOUT | 上传单个对象的最长时间（秒），默认为 60。低带宽场景下可能需要适当增大，详见读写错误 |
--gc | 挂载后检查和清理泄露的对象存储块。JuiceFS 一般不会产生对象存储泄露，但如果发现对象存储文件数量异常，可以使用该命令检查并清理。 |
--dry | 执行 GC 垃圾回收时，只进行检查，不实际删除对象存储文件。 |
--flip | 翻转文件系统复制功能的两个对象存储的复制顺序（也就是把第二个对象存储作为源），文件系统复制请详见「跨区数据复制」。 |
安全相关参数
| 项 | 说明 |
|---|---|
--rsa-key=RSAKEY | 指定 RSA 私钥路径（PEM），如果秘钥是用密语加密过的，在挂载时会被询问，也可以通过 JFS_RSA_PASSPHRASE 环境变量设置。 |
缓存相关参数
详读缓存以了解 JuiceFS 的缓存设计。
| 项 | 说明 |
|---|---|
--cache-dir=CACHEDIR | 本地缓存的存储路径，视用户不同，默认为 /var/jfsCache 或 $HOME/.juicefs/cache。多盘缓存用 : 分割多个目录，目录可包含通配符 *（需要添加引号）。例如：--cache-dir '/data*/jfsCache:/mydata*/jfsCache'。 |
--cache-size=CACHESIZE | 本地缓存容量，单位 MiB，默认 102400（100GiB）。当指定了多个缓存目录时，总容量会平均分配到各个目录。 |
--free-space-ratio=FREESPACE | 缓存目录的最小剩余空间占比，默认 0.2，如果启用了「客户端写缓存」，则该参数还控制着写缓存占用空间。 |
--buffer-size=BUFFERSIZE | 读写缓冲区大小，单位 MiB，默认 300。详读「读写缓冲区」以了解如何对该参数进行调优。 |
--cache-mode=CACHEMODE | 缓存目录的权限模式，默认是 0600。 |
--cache-group=CACHEGROUP | 缓存共享组名称，相同组的客户端之间可以相互共享缓存的数据，默认未启用。 |
--subgroups=SUBGROUPS | 一个缓存组中子组的数量，默认为 0。 |
--group-ip=GROUPIP | 手动设置缓存共享组的 IP 地址，一般来说只有多网卡节点中，需要绑定特定网卡时，才会用到此设置。 |
--no-sharing | 当前客户端不加入分布式缓存集群，默认为加入。 |
--writeback | 写数据时优先写到本地磁盘，然后在后台异步上传到对象存储。默认为 false。 |
--cache-partial-only | 是否只缓存小文件和随机读的部分，默认为 false。 |
--fill-group-cache | 为新写入的 block 构建远端缓存 |
--metacache | 将元数据缓存在运行客户端的主机的内存里，默认启用。使用 --metacacheto=0 关闭缓存。 |
--metacacheto=METACACHETO | 元数据的缓存过期时间（单位为秒），默认为 300。 |
--max-cached-inodes=MAXCACHEDINODES | Inodes 的最大缓存数量，默认为 5000000。 |
--opencache | 是否使用缓存的元数据来打开文件，默认为 false，也就是说每次打开文件时都会访问元数据服务，确认文件是否被更改过。因此在需要频繁打开文件，而修改又较少时（建议针对只读场景开启），可以考虑启用 --opencache，进一步提升读性能。 |
--attrcacheto=ATTRCACHETO | 文件/目录的属性在内核中的缓存时间（秒），默认为 1。 |
--entrycacheto=ENTRYCACHETO | 文件项在内核中的缓存时间（秒），默认为 1。 |
--direntrycacheto=DIRENTRYCACHETO | 目录项在内核中的缓存时间（秒），默认为 1。 |
--readdir-cache | 在内核中建立 readdir 缓存（需要 Kernel 4.20 及以上）。 |
FUSE 相关参数
| 项 | 说明 |
|---|---|
--allow-other | 允许其他用户访问（当用 root 挂载时默认开启，否则需要在 /etc/fuse.conf 中启用 user-allow-other）。 |
--enable-xattr | 开启扩展文件属性 xattr 的支持。默认为 false，如果没有特殊需要建议关闭，会产生额外开销。 |
--enable-acl | 开启 POSIX ACL 的支持。 |
--no-posix-lock | 禁用 POSIX lock 支持。 |
--no-bsd-lock | 禁用 BSD lock 支持。 |
--block-interrupt=BLOCKINTERRUPT | 中断信号的阻塞时间（单位为秒），默认为 1。 |
-o FUSE_OPTS | 添加其他 FUSE 选项。如通过 -o writeback_cache 开启 FUSE 写缓存可以极大提高随机写入和碎片写入的性能（需要使用 Linux Kernel 3.15 及以上）。 |
挂载文件系统的方法可以参考 快速上手指南。
实验性参数
| 项 | 说明 |
|---|---|
--min-balance-diff=MINBALANCEDIFF | 当前 zone 与 inodes 最少的 zone 之间的 inodes 差值超过这个值时则自动均衡元数据 |
--min-dir-inodes=MINDIRINODES | 当前路径的目录数超过这个值时则自动均衡元数据 |
--max-space=MAXSPACE | 总的存储容量上限 GiB（默认不限制） |
--source=SOURCE | 将 JuiceFS 作为一个目录的缓存 |
--refresh-interval=REFRESHINTERVAL | 当将 JuiceFS 作为一个目录的缓存时，元数据更新频率（秒）。默认为 60。 |
--update-source | 将数据变更同步回源缓存目录 |
--fsck | 检查数据完整性 |
废弃的参数
以下是 JuiceFS 客户端已经弃用的参数，仅保留作为参考。
| 项 | 说明 |
|---|---|
--async | 由 --writeback 参数取代 |
--ssl | 使用 HTTPS 访问对象存储（始终启用） |
--dircache | 由 --metacache 参数取代 |
-d | 由 -v 参数取代 |
--cacheDir=CACHEDIR | 由 --cache-dir 参数取代 |
--cacheSize=CACHESIZE | 由 --cache-size 参数取代 |
--allow-root | 允许 root 用户访问（由 --allow-other 参数取代） |
--no-sync | 不要复制对象存储 |
--batch=<batch> | 合并小文件的等待时间（单位为秒） |
--keep-fd | 保持 FUSE 会话存活 |
juicefs umount
卸载 JuiceFS 文件系统。该命令跨平台通用，Linux 下使用 umount 来执行卸载，而 macOS 下则一般用 diskutil unmount。
语法
juicefs umount PATH [options]
参数
| 项 | 说明 |
|---|---|
PATH | 挂载路径 |
-f --force | 强制卸载 |
juicefs info
显示 JuiceFS 文件系统中文件或目录的信息。
语法
juicefs info PATH [-n|--plain]
参数
| 项 | 说明 |
|---|---|
PATH | 要查询的路径。 |
-n --plain | 把文件大小显示为字节数。 |
例子
显示一个目录的信息
# juicefs info /jfs/logs
/jfs/logs:
inodes: 4 # 当前目录包含的 inode 总数
directories: 2 # 其中目录的数量
files: 2 # 其中文件的数量
chunks: 44 # 所有文件包含的 chunk 数量
length: 2.91G # 所有文件的实际大小总和
size: 2.91G # 计费大小，所有文件和目录大小会对齐到 4KB，为最小计费单位
显示一个文件的信息
# juicefs info --plain /jfs/daily-log.tar
/jfs/daily-log.tar:
inode: 2955 # 文件的 inode id
length: 3128903680 # 文件实际大小
size: 3128950784 # 文件计费大小
chunks: 47 # 数据块总数和清单，每块最大 64MB
0: 58597 67108864 0 67108864 # 格式为：在文件中的位置，块ID，块长度，实际使用的起始位置，长度
1: 58598 67108864 0 67108864
...
45: 58661 67108864 0 67108864
46: 58662 41895936 0 41895936
juicefs lsof
列出 JuiceFS 最近（10 分钟内）被打开过的文件。
语法
juicefs lsof PATH
juicefs import
juicefs import 将目标文件的元数据信息写入 JuiceFS 的元数据存储引擎，从而纳入 JuiceFS 的管辖，该操作并不会实际复制任何文件，文件仍原样保存在对象存储里。换言之，对于导入的文件，如果在文件系统中更改文件名、权限等属性，并不会被同步到对象存储中的源文件。同样地，删除这些文件也只会删除其元数据，并不会真正删除对象存储中的源文件。
此外，导入的文件也不支持缓存，无法利用到 JuiceFS 强大的缓存设计。
因此，用 juicefs import 导入的文件，虽然能够正常在 JuiceFS 使用，但却无法获得一个高性能的体验。如果对这部分数据追求最好的性能效果，建议将数据整体拷贝到 JuiceFS，我们推荐用 Juicesync 这款工具，但归功于 JuiceFS 的 POSIX 兼容性，你也可以用任意其他工具。
语法
juicefs import URI DST [-v] [--name=<name>] [--mode=<mode>]
参数
| 项 | 说明 |
|---|---|
URI | 要导入文件的 URI，格式为 <bucket_name>[.<domain>][/<prefix>] |
DST | 导入文件的存放目录。 |
--name=NAME | 文件系统的名字，Linux 下是可选的。 |
--mode=MODE | 导入文件的权限（Unix 格式）。 |
-v, --verbose | 显示详细日志。 |
--conf-dir | 配置文件目录，默认 ~/.juicefs |
--no-update | 客户端会从默认控制台获取最新的配置，将该参数设为 true 以禁用此行为（通常不需要）。 |
备注
- 导入的文件数据是只读的，但文件和目录的其他属性（如名字、权限等）可以修改，且改动不会同步到对象存储中。
- 可以在 JuiceFS 中删除导入的文件，但并不会实际删除对象存储中的对象。
juicefs rmr
快速删除目录里的所有文件和子目录，效果等同于 rm -rf，但该命令直接操纵元数据，不经过 POSIX，所以速度更快。
该命令会尝试以当前用户的身份去递归删除指定目录里面的所有文件和子目录，跳过无权限删除的部分，返回被删除的文件和目录数量以及剩余的文件和目录数。
如果文件系统启用了回收站功能，被删除的文件会进入回收站。回收站的文件依然参与计费，详见「回收站」。
语法
juicefs rmr DIR ... [-h]
juicefs snapshot
创建或删除快照。
对指定数据进行完整备份。JuiceFS 创建快照时不会实际拷贝文件数据，而是仅拷贝元数据，因此对大文件或者目录做快照时速度一样很快。只有在源数据发生修改时，才会真正拷贝数据到快照中（Copy-on-Write）。
但也正因为快照过程会拷贝元数据，用量增加会导致 JuiceFS 计费上涨，因此对文件数目庞大的目录进行快照操作时，需要谨慎。
语法
juicefs snapshot SRC DST [-f|--force] [-c|--copy] # 创建快照
juicefs snapshot -d DST [-f|--force] # 删除快照
参数
| 项 | 说明 |
|---|---|
SRC | 要做快照的目录。 |
DST | 快照存放的目录。 |
-d --delete | 删除快照。 |
-f --force | 强行覆盖或删除文件。 |
-c --copy | 用当前用户的 UID，GID，umask 来创建新快照，默认使用源文件的 UID，GID 和 mode。 |
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 的行。 |
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 benchmark
执行性能测试，内容包括大文件和小文件的 read/write/stat。
语法
juicefs benchmark [options] path-to-test
参数
| 项 | 说明 |
|---|---|
--dest=DEST | 要测试的路径（默认：/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 doctor
全面收集各种用于排查的信息，包括访问日志、客户端日志、CPU 性能统计、Goroutine 堆栈等。遇到一些疑难杂症时，JuiceFS 团队可能会要求你使用该命令打包收集报错信息，来帮助解决你的问题。
我们也鼓励你阅读「问题排查方法」和「问题排查案例」，来尝试自己上手分析和解决一些常见问题。
语法
juicefs doctor MOUNTPOINT
juicefs warmup
为指定路径和文件预热缓存。如果开启了分布式缓存，那么在缓存组内任意成员节点执行该命令，都能获得相同效果。
语法
juicefs warmup [PATH] [options]
参数
| 项 | 说明 |
|---|---|
-f LISTFILE 或 --listfile=LISTFILE | 包含需要预热的路径的文件（一行一个路径） |
-c CONCURRENT 或 --concurrent=CONCURRENT | 下载并发度，默认 50。如果对象存储的下载带宽较小，需要降低并发度，让预热过程更稳定。 |
-b | 后台运行 |
juicefs version
显示客户端版本，在 版本更新页 可以查看每个版本的更新详情。
语法
juicefs version [options]
参数
| 项 | 说明 |
|---|---|
-u --upgrade | 升级客户端到最新版。 |
-r --restart | 如果客户端发生了升级，则执行平滑重新挂载。 |
