ContextQMD
Back to Juicefs

Common Options

docs/zh_cn/reference/_common_options.mdx

1.4.0-dev11.7 KB
Original Source

元数据相关参数 {#mount-metadata-options}

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

元数据缓存参数 {#mount-metadata-cache-options}

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

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

数据存储参数 {#mount-data-storage-options}

项说明
--storage=file对象存储类型 (例如 s3、gs、oss、cos) (默认："file"，参考文档查看所有支持的对象存储类型)
--bucket=value为当前挂载点指定访问对象存储的 Endpoint。
--storage-class value <VersionAdd>1.1</VersionAdd>当前客户端写入数据的存储类型
--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 <VersionAdd>1.2</VersionAdd>异步写入数据块到缓存盘的最大并发数，如果达到最大并发数则会直接上传对象存储（此选项仅在启用「客户端写缓存」时有效）（默认值：0，即没有并发限制）
--max-deletes=10删除对象的连接数 (默认：10)
--upload-limit=0上传带宽限制，单位为 Mbps (默认：0)
--download-limit=0下载带宽限制，单位为 Mbps (默认：0)
--check-storage<VersionAdd>1.3</VersionAdd>在挂载前测试存储以提前暴露访问问题

数据缓存相关参数 {#mount-data-cache-options}

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

监控相关参数 {#mount-metrics-options}

项说明
--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 相关参数 {#mount-windows-options}

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