JuiceFS format

有许多命令可帮助您管理文件系统，该页面提供了有关这些命令的详细参考。

在终端输入 juicefs 并执行，你就会看到所有可用的命令。另外，你可以在每个命令后面添加 -h/--help 标记获得该命令的详细帮助信息。

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

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

VERSION:
 1.0.0+2022-08-01.0e7afe2d

COMMANDS:
 ADMIN:
 format Format a volume
 config Change configuration of 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
 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 Show information from multiple dimensions such as the operating environment and system logs
 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

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) and gops (:6070) 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 hack/autocomplete/zsh_autocomplete

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

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

echo "source path/to/zsh_autocomplete" >> ~/.zshrc

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

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

source /etc/bash_completion.d/juicefs

juicefs format

格式化文件系统；这是使用新文件系统的第一步。

juicefs format [command options] META-URL NAME

META-URL：用于元数据存储的数据库 URL，详情查看「JuiceFS 支持的元数据引擎」。
NAME：文件系统名称

--block-size value
块大小；单位为 KiB (默认：4096)

--capacity value
容量配额；单位为 GiB (默认：不限制)

--inodes value
文件数配额 (默认：不限制)

--compress value
压缩算法 (lz4, zstd, none) (默认："none")

--shards value
将数据块根据名字哈希存入 N 个桶中 (默认：0)

--storage value
对象存储类型 (例如 s3、gcs、oss、cos) (默认："file"，请参考文档查看所有支持的对象存储类型)

--bucket value
存储数据的桶路径 (默认："$HOME/.juicefs/local" 或 "/var/jfs")

--access-key value
对象存储的 Access Key (也可通过环境变量 ACCESS_KEY 设置)

--secret-key value
对象存储的 Secret Key (也可通过环境变量 SECRET_KEY 设置)

--session-token value
对象存储的 session token

--encrypt-rsa-key value
RSA 私钥的路径 (PEM)

--trash-days value
文件被自动清理前在回收站内保留的天数 (默认：1)

--force
强制覆盖当前的格式化配置 (默认：false)

--no-update
不要修改已有的格式化配置 (默认：false)

$ juicefs format sqlite3://myjfs.db myjfs

$ juicefs format redis://localhost myjfs --storage s3 --bucket https://mybucket.s3.us-east-2.amazonaws.com

$ 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 --inode 1000000 --capacity 102400

$ juicefs format sqlite3://myjfs.db myjfs --trash-days 0

挂载一个已经格式化的文件系统。

juicefs mount [command options] META-URL MOUNTPOINT

META-URL：用于元数据存储的数据库 URL，详情查看「JuiceFS 支持的元数据引擎」。
MOUNTPOINT：文件系统挂载点，例如：/mnt/jfs、Z:。

--metrics value
监控数据导出地址 (默认："127.0.0.1:9567")

--consul value
consul 注册中心地址 (默认："127.0.0.1:8500")

--no-usage-report
不发送使用量信息 (默认：false)

-d, --background
后台运行 (默认：false)

--no-syslog
禁用系统日志 (默认：false)

--log value
后台运行时日志文件的位置 (默认：$HOME/.juicefs/juicefs.log 或 /var/log/juicefs.log)

-o value
其他 FUSE 选项 (参见此文档来了解更多信息)

--attr-cache value
属性缓存过期时间；单位为秒 (默认：1)

--entry-cache value
文件项缓存过期时间；单位为秒 (默认：1)

--dir-entry-cache value
目录项缓存过期时间；单位为秒 (默认：1)

--enable-xattr
启用扩展属性 (xattr) 功能 (默认：false)

--bucket value
为当前挂载点指定访问访对象存储的 endpoint

--get-timeout value
下载一个对象的超时时间；单位为秒 (默认：60)

--put-timeout value
上传一个对象的超时时间；单位为秒 (默认：60)

--io-retries value
网络异常时的重试次数 (默认：10)

--max-uploads value
上传对象的连接数 (默认：20)

--max-deletes value
删除对象的连接数 (默认：2)

--buffer-size value
读写缓存的总大小；单位为 MiB (默认：300)

--upload-limit value
上传带宽限制，单位为 Mbps (默认：0)

--download-limit value
下载带宽限制，单位为 Mbps (默认：0)

--prefetch value
并发预读 N 个块 (默认：1)

--writeback
后台异步上传对象 (默认：false)

--cache-dir value
本地缓存目录路径；使用 :（Linux、macOS）或 ;（Windows）隔离多个路径 (默认："$HOME/.juicefs/cache" 或 "/var/jfsCache")

--cache-size value
缓存对象的总大小；单位为 MiB (默认：102400)

--free-space-ratio value
最小剩余空间比例 (默认：0.1)

--cache-partial-only
仅缓存随机小块读 (默认：false)

--read-only
只读模式 (默认：false)

--open-cache value
打开的文件的缓存过期时间（0 代表关闭这个特性）；单位为秒 (默认：0)

--subdir value
将某个子目录挂载为根 (默认："")

--backup-meta value
自动备份元数据到对象存储的间隔时间；单位秒 (0 表示不备份) (默认：3600)

--heartbeat value
发送心跳的间隔 (秒);建议所有客户端使用相同的心跳值 (默认：12)。

--upload-delay value
数据上传到对象存储的延迟时间，支持秒分时精度，对应格式分别为 ("s", "m", "h")，默认为 0 秒

--no-bgjob
禁用后台作业（清理、备份等）（默认：false）

$ juicefs mount redis://localhost /mnt/jfs

$ 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

$ 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

卸载一个文件文件系统。

juicefs umount [command options] MOUNTPOINT

-f, --force
强制卸载一个忙碌的文件系统 (默认：false)

$ juicefs umount /mnt/jfs

启动一个 S3 兼容的网关。

juicefs gateway [command options] META-URL ADDRESS

--bucket value
为当前网关指定访问访对象存储的 endpoint

--get-timeout value
下载一个对象的超时时间；单位为秒 (默认：60)

--put-timeout value
上传一个对象的超时时间；单位为秒 (默认：60)

--io-retries value
网络异常时的重试次数 (默认：10)

--max-uploads value
上传对象的连接数 (默认：20)

--max-deletes value
删除对象的连接数 (默认：2)

--buffer-size value
读写缓存的总大小；单位为 MiB (默认：300)

--upload-limit value
上传带宽限制，单位为 Mbps (默认：0)

--download-limit value
下载带宽限制，单位为 Mbps (默认：0)

--prefetch value
并发预读 N 个块 (默认：1)

--writeback
后台异步上传对象 (默认：false)

--cache-dir value
本地缓存目录路径；使用 :（Linux、macOS）或 ;（Windows）隔离多个路径 (默认："$HOME/.juicefs/cache" 或 /var/jfsCache)

--cache-size value
缓存对象的总大小；单位为 MiB (默认：102400)

--free-space-ratio value
最小剩余空间比例 (默认：0.1)

--cache-partial-only
仅缓存随机小块读 (默认：false)

--read-only
只读模式 (默认：false)

--open-cache value
打开的文件的缓存过期时间（0 代表关闭这个特性）；单位为秒 (默认：0)

--subdir value
将某个子目录挂载为根 (默认："")

--attr-cache value
属性缓存过期时间；单位为秒 (默认：1)

--entry-cache value
文件项缓存过期时间；单位为秒 (默认：0)

--dir-entry-cache value
目录项缓存过期时间；单位为秒 (默认：1)

--access-log value
访问日志的路径

--metrics value
监控数据导出地址 (默认："127.0.0.1:9567")

--no-usage-report
不发送使用量信息 (默认：false)

--no-banner
禁用 MinIO 的启动信息 (默认：false)

--multi-buckets
使用第一级目录作为存储桶 (默认：false)

--keep-etag
保留对象上传时的 ETag (默认：false)

--storage value
对象存储类型 (例如 s3、gcs、oss、cos) (默认："file"，请参考文档查看所有支持的对象存储类型)

--upload-delay value
数据上传到对象存储的延迟时间，支持秒分时精度，对应格式分别为 ("s", "m", "h")，默认为 0 秒

--backup-meta value
自动备份元数据到对象存储的间隔时间；单位秒 (0 表示不备份) (默认：3600)

--heartbeat value
发送心跳的间隔 (秒);建议所有客户端使用相同的心跳值 (默认：12)。

--no-bgjob
禁用后台作业（清理、备份等）（默认值：false）

--umask value 新文件的 umask 的八进制格式 (默认值:“022”)

--consul value
consul 注册中心地址 (默认："127.0.0.1:8500")

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

启动一个 WebDAV 服务。

juicefs webdav [command options] META-URL ADDRESS

META-URL：用于元数据存储的数据库 URL，详情查看「JuiceFS 支持的元数据引擎」。
ADDRESS：webdav 服务监听的地址与端口，例如：localhost:9007

--bucket value
为当前网关指定访问访对象存储的 endpoint

--get-timeout value
下载一个对象的超时时间；单位为秒 (默认：60)

--put-timeout value
上传一个对象的超时时间；单位为秒 (默认：60)

--io-retries value
网络异常时的重试次数 (默认：10)

--max-uploads value
上传对象的连接数 (默认：20)

--max-deletes value
删除对象的连接数 (默认：2)

--buffer-size value
读写缓存的总大小；单位为 MiB (默认：300)

--upload-limit value
上传带宽限制，单位为 Mbps (默认：0)

--download-limit value
下载带宽限制，单位为 Mbps (默认：0)

--prefetch value
并发预读 N 个块 (默认：1)

--writeback
后台异步上传对象 (默认：false)

--upload-delay
数据上传到对象存储的延迟时间，支持秒分时精度，对应格式分别为 ("s", "m", "h")，默认为 0 秒

--cache-dir value
本地缓存目录路径；使用 :（Linux、macOS）或 ;（Windows）隔离多个路径 (默认："$HOME/.juicefs/cache" 或 /var/jfsCache)

--cache-size value
缓存对象的总大小；单位为 MiB (默认：102400)

--free-space-ratio value
最小剩余空间比例 (默认：0.1)

--cache-partial-only
仅缓存随机小块读 (默认：false)

--read-only
只读模式 (默认：false)

--backup-meta value
在对象存储中自动备份元数据的时间间隔（0 表示禁用备份）（默认值：1h0m0s）

--no-bgjob
禁用后台作业（清理、备份等）（默认值：false）

--open-cache value
打开的文件的缓存过期时间（0 代表关闭这个特性）；单位为秒 (默认：0)

--subdir value
将某个子目录挂载为根 (默认："")

--attr-cache value
属性缓存过期时间；单位为秒 (默认：1)

--entry-cache value
文件项缓存过期时间；单位为秒 (默认：0)

--dir-entry-cache value
目录项缓存过期时间；单位为秒 (默认：1)

--gzip
通过 gzip 压缩提供的文件（默认值：false）

--disallowList
禁止列出目录（默认值：false）

--access-log value
访问日志的路径

--metrics value
监控数据导出地址 (默认："127.0.0.1:9567")

--consul value
consul 注册中心地址 (默认："127.0.0.1:8500")

--no-usage-report
不发送使用量信息 (默认：false)

--storage value
对象存储类型 (例如 s3、gcs、oss、cos) (默认："file"，请参考文档查看所有支持的对象存储类型)

--heartbeat value
发送心跳的间隔 (秒);建议所有客户端使用相同的心跳值 (默认：12)。

$ juicefs webdav redis://localhost localhost:9007

在两个存储系统之间同步数据。

juicefs sync [command options] SRC DST

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

NAME：JuiceFS 支持的数据存储类型（如 s3、oss），请参考文档。
ACCESS_KEY 和 SECRET_KEY：访问数据存储所需的密钥信息，请参考文档。
BUCKET[.ENDPOINT]：数据存储服务的访问地址，不同存储类型格式可能不同，具体请参考文档。
[/PREFIX]：可选，源路径和目标路径的前缀，可用于限定只同步某些路径中的数据。

有关 sync 子命令的详细介绍，请参考文档。

--start KEY, -s KEY
同步的第一个对象名

--end KEY, -e KEY
同步的最后一个对象名

--threads value, -p value
并发线程数 (默认：10)

--http-port PORT
监听的 HTTP 端口 (默认：6070)

--update, -u
当源文件更新时修改已存在的文件 (默认：false)

--force-update, -f
强制修改已存在的文件 (默认：false)

--perms
保留权限设置 (默认：false)

--dirs
同步目录 (默认：false)

--dry
不拷贝文件 (默认：false)

--delete-src, --deleteSrc
同步后删除源存储的对象 (默认：false)

--delete-dst, --deleteDst
删除目标存储下的不相关对象 (默认：false)

--exclude PATTERN
排除匹配 PATTERN 的 Key

--include PATTERN
不排除匹配 PATTERN 的 Key，需要与 --exclude 选项配合使用。

--links, -l
将符号链接复制为符号链接 (默认：false)

--limit value
限制将要处理的对象的数量 (默认：-1)

--manager value
管理者地址

--worker value
工作节点列表 (使用逗号分隔)

--bwlimit value
限制最大带宽；单位为 Mbps (0 表示不限制) (默认：0)

--no-https
不要使用 HTTPS (默认：false)

--check-all
验证源路径和目标路径中所有文件的数据完整性 (默认：false)

--check-new
验证新拷贝文件的数据完整性 (默认：false)

$ juicefs sync oss://mybucket.oss-cn-shanghai.aliyuncs.com s3://mybucket.s3.us-east-2.amazonaws.com

$ juicefs mount -d redis://localhost /mnt/jfs
$ juicefs sync s3://mybucket.s3.us-east-2.amazonaws.com/ /mnt/jfs/

$ juicefs sync --exclude='a?/b*' s3://mybucket.s3.us-east-2.amazonaws.com/ /mnt/jfs/

$ juicefs sync --include='a1/b1' --exclude='a[1-9]/b*' s3://mybucket.s3.us-east-2.amazonaws.com/ /mnt/jfs/

$ juicefs sync --include='a1/b1' --exclude='a*' --include='b2' --exclude='b?' s3://mybucket.s3.us-east-2.amazonaws.com/ /mnt/jfs/

递归删除指定目录下的所有文件。

$ juicefs rmr /mnt/jfs/foo

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

juicefs info [command options] PATH or INODE

--inode, -i
使用 inode 号而不是路径 (当前目录必须在 JuiceFS 挂载点内) (默认：false)

--recursive, -r
递归获取所有子目录的概要信息（注意：当指定一个目录结构很复杂的路径时可能会耗时很长） (默认：false)

--raw
显示内部原始信息 (默认：false)

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


$ cd /mnt/jfs
$ juicefs info -i 100

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

juicefs bench [command options] PATH

有关 bench 子命令的详细介绍，请参考文档。

--block-size value
块大小；单位为 MiB (默认：1)

--big-file-size value
大文件大小；单位为 MiB (默认：1024)

--small-file-size value
小文件大小；单位为 MiB (默认：0.1)

--small-file-count value
小文件数量 (默认：100)

--threads value, -p value
并发线程数 (默认：1)

$ juicefs bench /mnt/jfs -p 4

$ juicefs bench /mnt/jfs --big-file-size 0

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

juicefs objbench [command options] BUCKET

有关 objbench 子命令的详细介绍，请参考文档。

--storage value
对象存储类型 (例如 s3、gcs、oss、cos) (默认："file"，请参考文档查看所有支持的对象存储类型)

--access-key value
对象存储的 Access Key (也可通过环境变量 ACCESS_KEY 设置)

--secret-key value
对象存储的 Secret Key (也可通过环境变量 SECRET_KEY 设置)

--block-size value
每个 IO 块的大小（以 KiB 为单位）（默认值：4096）

--big-object-size value
大文件的大小（以 MiB 为单位）（默认值：1024）

--small-object-size value
每个小文件的大小（以 KiB 为单位）（默认值：128）

--small-objects value
小文件的数量（以 KiB 为单位）（默认值：100）

--skip-functional-tests
跳过功能测试（默认值：false）

--threads value, -p value
上传下载等操作的并发数（默认值：4）

$ ACCESS_KEY=myAccessKey SECRET_KEY=mySecretKey juicefs objbench --storage s3 https://mybucket.s3.us-east-2.amazonaws.com -p 6

收集泄漏的对象。

juicefs gc [command options] META-URL

--delete
删除泄漏的对象 (默认：false)

--compact
整理所有文件的碎片 (默认：false).

--threads value
用于删除泄漏对象的线程数 (默认：10)

$ juicefs gc redis://localhost

$ juicefs gc redis://localhost --compact

$ juicefs gc redis://localhost --delete

检查文件系统一致性。

juicefs fsck [command options] META-URL

$ juicefs fsck redis://localhost

分析访问日志。

juicefs profile [command options] MOUNTPOINT/LOGFILE

--uid value, -u value
仅跟踪指定 UIDs (用逗号分隔)

--gid value, -g value
仅跟踪指定 GIDs (用逗号分隔)

--pid value, -p value
仅跟踪指定 PIDs (用逗号分隔)

--interval value
显示间隔；在回放模式中将其设置为 0 可以立即得到整体的统计结果；单位为秒 (默认：2)

$ juicefs profile /mnt/jfs

$ cat /mnt/jfs/.accesslog > /tmp/jfs.alog

$ juicefs profile /tmp/jfs.alog

$ juicefs profile /tmp/jfs.alog --interval 0

展示实时的性能统计信息。

juicefs stats [command options] MOUNTPOINT

--schema value

控制输出内容的标题字符串 (u: usage, f: fuse, m: meta, c: blockcache, o: object, g: go) (默认："ufmco")

--interval value

更新间隔；单位为秒 (默认：1)

--verbosity value

详细级别；通常 0 或 1 已足够 (默认：0)

$ juicefs stats /mnt/jfs

$ juicefs stats /mnt/jfs -l 1

显示 JuiceFS 的状态。

juicefs status [command options] META-URL

--session value, -s value
展示指定会话 (sid) 的具体信息 (默认：0)

$ juicefs status redis://localhost

主动为指定目录/文件建立缓存。

juicefs warmup [command options] [PATH ...]

--file value, -f value
指定一个包含一组路径的文件

--threads value, -p value
并发的工作线程数 (默认：50)

--background, -b
后台运行 (默认：false)

$ juicefs warmup /mnt/jfs/datadir


$ cat /tmp/filelist
/mnt/jfs/datadir/f1
/mnt/jfs/datadir/f2
/mnt/jfs/datadir/f3
$ juicefs warmup -f /tmp/filelist

将元数据导出到一个 JSON 文件中。

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

如果没有指定导出文件路径，会导出到标准输出。

--subdir value
只导出一个子目录。

$ juicefs dump redis://localhost meta-dump

$ juicefs dump redis://localhost sub-meta-dump --subdir /dir/in/jfs

从之前导出的 JSON 文件中加载元数据。

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

如果没有指定导入文件路径，会从标准输入导入。

$ juicefs load redis://localhost/1 meta-dump

修改指定文件系统的配置项。

juicefs config [command options] META-URL

--capacity value
容量配额；单位为 GiB

--inodes value
文件数配额

--bucket value
存储数据的桶路径

--access-key value
对象存储的 Access key

--secret-key value
对象存储的 Secret key

--session-token value
对象存储的 session token

--trash-days value
文件被自动清理前在回收站内保留的天数

--force
跳过合理性检查并强制更新指定配置项 (默认：false)

--encrypt-secret
如果密钥之前以原格式存储，则加密密钥 (默认值：false)

--min-client-version value
允许连接的最小客户端版本

--max-client-version value
允许连接的最大客户端版本

$ juicefs config redis://localhost

$ juicefs config redis://localhost --inode 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

销毁一个已经存在的文件系统

juicefs destroy [command options] META-URL UUID

--force
跳过合理性检查并强制销毁文件系统 (默认：false)

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

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

juicefs debug [command options] MOUNTPOINT

--out-dir value
结果输出目录，若目录不存在则自动创建 (默认：./debug/)

--stats-sec value
.stats文件采样秒数 (默认：5)

--collect-log
启用日志收集 (默认：false)

--limit value
收集的日志条目数，从新到旧，若不指定则收集全部条目

--collect-pprof
启用pprof指标收集 (默认：false)

--trace-sec value
trace指标采样秒数 (默认：5)

--profile-sec value
profile指标采样秒数 (默认：30)

$ juicefs debug /mnt/jfs

$ juicefs debug --out-dir=/var/log /mnt/jfs

$ juicefs debug --out-dir=/var/log --collect-log --limit=1000 /mnt/jfs

$ juicefs debug --out-dir=/var/log --collect-log --limit=1000 --collect-pprof /mnt/jfs

JuiceFS format

juicefs format​

juicefs format