命令参考

命令参考

这篇文档会详细的介绍 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
  warmup    build cache for target directories/files
  version   show the version

使用方式：juicefs [COMMAND] [options]

所有命令后面加 -h 或者 --help 都可以查看参数列表和帮助信息。

注意：如果没有把 juicefs 放入到 PATH 环境变量中的某个目录，则需要使用完整路径来运行 juicefs。如果 juicefs 是在当前目录下，则用 ./juicefs。以下文档假定 juicefs 在 PATH 环境变量中的某个目录（比如 /usr/local/bin），可以直接用 juicefs 运行。

下面详细说明所有命令的用法。

juicefs auth

功能

在本地生成文件系统的认证信息配置文件，存储在当前用户的 $HOME/.juicefs 目录中，配置文件名称格式为 [NAME].conf。

当需要通过脚本部署 JuiceFS，或使用自建对象存储进行私有化部署时，该命令十分有用。

语法

juicefs auth <name> [options]

参数

项	说明
`<name>`	文件系统的名字。
`—token=<token>`	文件系统的 Token，在网站控制台的文件系统设置中查看。
`—accesskey=<access_key>`	你使用的对象存储的密钥，获取方式参见文档。
`—secretkey=<secret_key>`	你使用的对象存储的密钥，获取方式参见文档。
`—bucket=<bucket>`	对象存储的 Bucket 名称或 Endpoint 地址（可选）。
`—bucket2=<bucket2>`	用于文件系统复制功能的目标对象存储 Bucket 名称或 Endpoint 地址（可选）。
`—accesskey2=<access_key_2>`	用于文件系统复制功能的目标对象存储存储密钥（可选）。
`—secretkey2=<secret_key_2>`	用于文件系统复制功能的目标对象存储密钥（可选）。

备注

如果以 sudo 方式运行 juicefs，认证信息保存在 /root/.juicefs/[NAME].conf 中。
当 --token、--accesskey 和 --secretkey 没有以参数方式指定时，会以交互方式输入。
如果你的云提供商支持 IAM，--accesskey 和 --secretkey 为空字符串即可。如 --accesskey ""，或者交互输入时直接按回车键跳过。
JuiceFS 的文件系统复制功能在网站的 控制中心 中设置，在文件系统的设置面板，勾选 启动复制，然后选择目标平台和区域。挂载文件系统时，使用 --accesskey2 和 --secretkey2 设置目标对象存储 API 的访问密钥。

juicefs mount

功能

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

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

语法

juicefs mount <name> <mountpoint> [-f] [-b] [-v]
                [--log=<log_path>] [--http=ADDR]
                [--external | --internal] [--max-uploads=<max_uploads>]
                [--cache-dir=<cache_dir>] [--cache-size=<cache_size>]
                [--writeback] [--metacache]
                [--allow-other] [--enable-xattr]
                ...

参数

项	说明
`<name>`	文件系统的名字。
`<mountpoint>`	主机上的挂载路径，比如：`/jfs`。
`-f`	前台运行。
`-b`	在 Docker 中后台运行。
`—subdir=<subdir>`	挂载子目录。
`—ioretries=<number>`	网络故障的重试次数（默认：30）。
`—http=ADDR`	指定通过 HTTP 提供文件访问的监听地址，比如 `localhost:8080`。
`—disallow-list`	禁止在 WebDAV 中列出目录。
`—log=<log_path>`	指定日志存储路径，默认为 `/var/log/juicefs.log`。
`-v`	显示更多日志。
`—no-update`	仅使用本地配置

对象存储相关参数

项	说明
`—external`	客户端默认会使用内网地址访问对象存储，该参数可以显式指定使用对象存储的外网地址。
`—internal`	显式指定对象存储的内网地址（适用于区分内外网域名的对象存储，比如：阿里云 OSS、UCloud UFile 等）。
`—max-uploads<max_uploads>`	最大并发上传请求数，默认为 20。
`—prefetch=<number>`	并发预读 block 数，默认为 3。
`—upload-limit=<upload_limit>`	上传数据所用带宽的上限（Mbps），默认无限制。
`—delete-limit=<delete_limit>`	对象存储 DELETE API 调用上限（QPS），默认无限制。
`—get-timeout=<get_timeout>`	下载单个对象的最长时间（秒），默认为 60。
`—put-timeout=<put_timeout>`	上传单个对象的最长时间（秒），默认为 60。
`—gc`	挂载后立即清理未使用的分块。
`—dry`	执行 GC 垃圾回收时，不删除分块。
`—flip`	翻转文件系统复制功能的两个对象存储的复制顺序（也就是把第二个对象存储作为源）

安全相关参数

项	说明
`—rsa-key=RSAKEY`	指定 RSA 私钥路径（PEM），如果秘钥是用密语加密过的，在挂载时会被询问，也可以通过 `JFS_RSA_PASSPHRASE` 环境变量设置。

缓存相关参数

项	说明
`—cache-dir=<cache_dir>`	本地缓存的存储路径，默认是 `/var/jfsCache` 或 `$HOME/.juicefs/cache`。多盘缓存用 `:` 分割多个目录，目录可包含通配符（需要添加引号）。例如：`—cache-dir ‘/data``/jfsCache:/mydata*/jfsCache’`。
`—cache-size=<cache_size>`	本地缓存容量，默认是 1GiB。当指定了多个缓存目录时，总容量会平均分配到各个目录。
`—free-space-ratio=<free_space_ratio>`	缓存目录的最小剩余空间，默认是 0.2。
`—buffer-size=<buffer_size>`	用来缓存读写数据的总内存大小，默认 300MiB。
`—cache-mode=<cache_mode>`	缓存目录的权限模式，默认是 0600。
`—cache-group=<cache_group>`	缓存共享组名称，相同组的客户端之间可以相互共享缓存的数据，默认未启用。
`—no-sharing`	当前客户端不加入分布式缓存集群，默认为加入。
`—writeback`	写数据时优先写到本地磁盘，然后在后台异步上传到对象存储。默认为 false。
`—cache-partial-only`	是否只缓存小文件和随机读的部分，默认为 false。
`—metacache`	将元数据缓存在运行客户端的主机的内存里，默认启用。使用 `—metacacheto=0` 关闭缓存。
`—metacacheto=<metacacheto>`	元数据的缓存过期时间（单位为秒），默认为 300（5 分钟）。
`—max-cached-inodes=MAXCACHEDINODES`	Inodes 的最大缓存数量，默认为 5000000。
`—opencache`	是否使用缓存的元数据来打开文件，默认不使用。
`—attrcacheto=<attrcacheto>`	文件/目录的属性在内核中的缓存时间，默认 1 秒。
`—entrycacheto=<entrycacheto>`	文件项在内核中的缓存时间，默认 1 秒。
`—direntrycacheto=<direntrycacheto>`	目录项在内核中的缓存时间，默认 1 秒。

FUSE 相关参数

项	说明
`—allow-other`	允许其他用户访问（当用 `root` 挂载时默认开启，否则需要在 `/etc/fuse.conf` 中启用 `user-allow-other`）。
`—enable-xattr`	开启扩展文件属性 xattr 的支持。
`—enable-acl`	开启 POSIX ACL 的支持。
`—no-posix-lock`	禁用 POSIX lock 支持。
`—no-bsd-lock`	禁用 BSD lock 支持。
`-o FUSE_OPTS`	添加其他 FUSE 选项
`-o writeback_cache`	在 3.15+ 的 Linux 内核中启用写入缓存，极大提高随机写入和碎片写入的性能。

挂载文件系统的方法可以参考快速上手指南。

实验性参数

项	说明
`—min-balance-diff=MINBALANCEDIFF`	当前 zone 与 inodes 最少的 zone 之间的 inodes 差值超过这个值时则自动均衡元数据
`—min-dir-inodes=MINDIRINODES`	当前路径的目录数超过这个值时则自动均衡元数据
`—max-space=MAXSPACE`	总的存储容量上限 GiB（默认不限制）
`—source-dir=SOURCEDIR`	将 JuiceFS 作为一个目录的缓存
`—refresh-interval=REFRESHINTERVAL`	当将 JuiceFS 作为一个目录的缓存时，元数据更新频率（秒）。默认为 60。

废弃的参数

注意：以下是 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>`	合并小文件的等待时间（单位为秒）

juicefs umount

功能

卸载 JuiceFS 文件系统。

语法

juicefs umount <mountpoint> [options]

参数

项	说明
`-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 <uri> <dst> [-v] [--name=<name>] [--mode=<mode>]

参数

项	说明
`<uri>`	要导入文件的 URI，格式为 `<bucket_name>[.<domain>][/<prefix>]`
`<dst>`	导入文件的存放目录。
`—name=<name>`	文件系统的名字，Linux 下是可选的。
`—mode=<mode>`	导入文件的权限（Unix 格式）。
`-v`	显示详细日志。
`—no-update`	只使用本地的配置

备注

导入的文件数据是只读的，但文件和目录的其他属性（如名字、权限等）可以修改，且改动不会同步到对象存储中。
可以在 JuiceFS 中删除导入的文件，但并不会实际删除对象存储中的对象。

juicefs rmr

功能

快速删除目录里的所有文件和子目录，类似于 rm -rf，但速度非常快。

语法

juicefs rmr <dir> [-h]

该命令会尝试以当前用户的身份去递归删除指定目录里面的所有文件和子目录，跳过无权限删除的部分，返回被删除的文件和目录数量以及剩余的文件和目录数。

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

juicefs snapshot

功能

创建或删除快照。

快照是在某个时间点（拷贝开始的时间点）对指定数据的完整映像，这是数据备份时经常用到的技术。JuiceFS 的快照在建立时不会实际拷贝文件数据，而是创建一套完整的引用，在源数据发生修改时才拷贝数据（Copy-on-Write 技术）到快照中。

语法

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

功能

收集和分析文件系统的 oplog（operation log）。

语法

juicefs profile [options]

参数

项	说明
`-x PATH` `—path=PATH`	日志文件目录（默认为 `/jfs`）。
`-f FILE` `—file=FILE`	日志文件名（默认为 `.ophistory`）。日志文件区别请参考挂载目录下的 .oplog 虚拟文件。
`-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`	收集 oplog 的时间窗口大小，参数为浮点数，单位为秒（默认值为 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 warmup

功能

为指定路径和文件预热缓存

语法

juicefs warmup [PATH] [options]

参数

项	说明
`-f LISTFILE` 或 `—listfile=LISTFILE`	包含需要预热的路径的文件（一行一个路径）
`-c CONCURRENT` 或 `—concurrent=CONCURRENT`	并发 worker 数量，默认 50。
`-b`	后台运行

juicefs version

功能

显示客户端版本，在版本更新页可以查看每个版本的更新详情。

语法

juicefs version [options]

参数

项	说明
`-u` `—upgrade`	升级客户端到最新版。