命令参考
在终端输入 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 mount
会遇到交互式录入,不方便自动化。因此用juicefs auth
命令提前认证、获取配置文件。可以参考「自动化部署」; - 如果对象存储的认证信息(Access Key、Secret Key)或者存储桶本身发生变化,也需要重新运行
juicefs auth
,更新相关信息。比方说对象存储桶迁移到了其他区域,或者变更了对象存储供应商,客户端都需要更新配置; - 私有部署元数据节点 IP 或者控制台地址发生变更,也需要用
juicefs auth
重新认证、获取新的配置。大部分迁移变更操作都是平滑的,因此只需要更新客户端配置文件即可,并不需要重新挂载(需要根据具体执行计划,咨询 Juicedata 工程师); - 对于 CSI 驱动场景,如果元数据服务、对象存储、私有控制台的服务地址发生了变更,则需要更新「文件系统认证信息」,CSI 驱动会自动运行
juicefs auth
,更新客户端的配置文件缓存。
概览
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(可选) |
--shards=0 | 与社区版的 --shards 作用相同。企业版 JuiceFS 文件系统一般使用可以方便扩容并提升性能的对象存储,不轻易达到单桶的容量或性能上限,因此该参数更多是为了和社区版保持兼容,如果不是单桶服务能力有限的自建对象存储,一般不主动使用多桶拆分,这样会增加管理复杂度。 |
--storage-class=value | 目标端的新建文件的存储类型(也叫存储级别,可以阅读相应文档了解更多:S3、OSS),如果目标端存储支持的话。 |
--bucket2=BUCKET2 | 用于文件系统复制功能的目标对象存储 Bucket 名称或 endpoint 地址,格式和注意事项同 --bucket 。 |
--access-key2=ACCESSKEY2 | 开启文件系统复制功能时,目标对象存储密钥(可选)。文件系统复制请详见「跨区数据复制」。 |
--secret-key2=SECRETKEY2 | 开启文件系统复制功能时,目标对象存储密钥(可选)。文件系统复制请详见「跨区数据复制」。 |
--session-token2=SESSIONTOKEN2 | 开启文件系统复制功能时,目标对象存储的 session token(可选)文件系统复制请详见「跨区数据复制」。 |
--shards2=0 | 如果开启了文件系统复制功能,那么 --shards2 需要对齐 --shards 。 |
--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