Skip to main content

参数设置

Hadoop SDK 是使用 JuiceFS 的众多使用方式之一，因此大部分配置与 JuiceFS 客户端对齐，你可以在「命令参考」找到更详细的说明。

核心配置​

配置项默认值描述
fs.jfs.implcom.juicefs.JuiceFileSystem指定要使用的存储实现，默认使用 jfs:// 作为 scheme。如想要使用其它 scheme（例如 cfs://），则修改为 fs.cfs.impl 即可。无论使用的 scheme 是什么，访问的都是 JuiceFS 中的数据。
fs.AbstractFileSystem.jfs.implcom.juicefs.JuiceFS指定要使用的存储实现，默认使用 jfs:// 作为 scheme。如想要使用其它 scheme（例如 cfs://），则修改为 fs.AbstractFileSystem.cfs.impl 即可。无论使用的 scheme 是什么，访问的都是 JuiceFS 中的数据。
juicefs.token访问 JuiceFS 的凭证，在控制台的设置页或者访问控制页可以看到。
juicefs.bucket对象存储 bucket 地址，此配置可以覆盖文件系统的对象存储桶。一般无需配置。
juicefs.accesskey对象存储的访问 ID（Access Key ID）。如果计算节点已经有访问对象存储的权限，则无需提供。
juicefs.secretkey对象存储的私钥 (Secret Access Key)。如果计算节点已经有访问对象存储的权限，则无需提供。
juicefs.console-url私有部署环境中，JuiceFS Web 控制台地址（云服务用户无需填写），格式如 http://x.x.x.x:8080。

跨区数据复制配置​

阅读「跨区数据复制」以了解更多。

配置项默认值描述
juicefs.bucket2当配置了「跨区数据复制」功能时，此配置可以覆盖文件系统的复制桶。
juicefs.accesskey2复制桶的 Access Key。如果计算节点已经有访问对象存储的权限，则无需提供。
juicefs.secretkey2复制桶的 Secret Key。如果计算节点已经有访问对象存储的权限，则无需提供。

缓存配置​

阅读「缓存」以了解 JuiceFS 客户端的缓存设计。

配置项默认值描述
juicefs.cache-dirmemory本地缓存目录，默认使用 memory 也就是进程内存，可以指定多个文件夹，用 : 分隔，也可以使用通配符 *。如果使用本地目录，推荐手动创建并给予 0777 权限，便于多个应用共享缓存数据。该配置含义同 --cache-dir。
juicefs.cache-size100磁盘缓存容量，单位 MiB。默认值较小是由于 Hadoop SDK 默认使用内存作为缓存。该配置含义同 --cache-size。
juicefs.cache-replica1缓存块允许调度的节点数量。Hadoop 应用均支持通过 BlockLocation 信息进行数据亲和性调度，将任务调度到同一批节点上，尽可能复用数据。提高该值将影响 BlockLocation 的计算方式，让同一个 Block 能够调度到更多的节点，以此提升计算任务并发度。Block 大小通过 juicefs.block.size 配置控制。
juicefs.cache-group配置此项则使用分布式缓存，同一个缓存组内的客户端共享缓存，推荐在主要使用 Spark 的环境使用此配置，因为 Spark 在单个任务处理多个小文件时，计算没有数据本地化。
juicefs.no-sharingfalse加入缓存组时，从缓存集群获取缓存数据，但却不共享自身缓存数据。该选项用于需要访问缓存集群数据，但自身却不断变动的节点（比如 Kubernetes Pod）。
juicefs.cache-full-blocktrue是否缓存完整对象存储块，如果仅需要反复读取小文件，或者磁盘性能比不上对象存储时，推荐设置为 false，此时仅缓存小于 JuiceFS 块大小（4MiB）的文件，和大文件的随机读部分。该配置含义相当于 JuiceFS 客户端的 --cache-partial-only 取反。
juicefs.memory-size300读写数据的缓冲区最大空间，单位为 MiB，含义同 --buffer-size。
juicefs.auto-create-cache-dirtrue是否自动创建缓存目录。为 false 时，如果设定的缓存目录不存在，效果相当于禁用缓存。
juicefs.free-space0.2最低剩余磁盘空间比例，当剩余磁盘空间低于这个比例时，它会清空缓存数据以释放空间，默认 20%。该配置含义同 --free-space-ratio。
juicefs.metacachetrue是否启用元数据缓存。
juicefs.discover-nodes-url指定发现集群缓存节点列表的方式，每 10 分钟刷新一次。此节点列表同样也是 juicefs.cache-group 的白名单，只有在此内的节点才能加入分布式缓存，可以用这种方式来防止计算集群外的客户端意外加入缓存组、影响缓存组整体性能（详见缓存组问题排查）。

  • 所有节点：all，相当于禁用节点列表自动发现，此时亲和性调度将不可用
  • YARN：yarn
  • Spark Standalone：http://spark-master:web-ui-port/json/
  • Spark ThriftServer：http://thrift-server:4040/api/v1/applications/
  • Presto：http://coordinator:discovery-uri-port/v1/service/presto/
  • 文件系统：jfs://{VOLUME}/etc/nodes，需手动建立此文件，并将节点的主机名一条一行写入此文件
注意，对于 Kerberos 集群，仅支持「所有节点」和「文件系统」两种模式。
juicefs.hflush-delay0单位：ms，在此时间间隔内，hflush 的数据会合并，以降低写对象存储请求，提高写入速度（比如 HBase WAL）。
juicefs.write-group-cachefalse往 JuiceFS 写入数据时，同时将这些数据写入缓存集群，该配置含义同 --fill-group-cache。
juicefs.cache-priority 新增自 v5.0.140缓存块的优先级，可选值为：0、1、2、3，数字越大优先级越高。缓存淘汰时会优先淘汰优先级更低的数据。
juicefs.entry-cache0.0文件项缓存的过期时间（单位：秒）
juicefs.dir-entry-cache0.0目录项缓存的过期时间（单位：秒）
juicefs.attr-cache0.0文件缓存的过期时间（单位：秒）
juicefs.block.sizedfs.blocksize 或 128MBJuiceFS 逻辑数据块大小，控制着类似 Spark 等应用的计算任务切片大小。
juicefs.cache-group-size4 * juicefs.block.size考虑到读文件时客户端会进行预读和预取，在开启分布式缓存时，对于小于该值的文件，客户端会尽量将该文件切分的数据块调度到一个节点上，以此来最大化利用缓存数据。

对象存储配置​

配置项默认值描述
juicefs.bucket指定存储桶名称
juicefs.prefetch1预取并发数，同 --prefetch
juicefs.max-uploads50单进程写入对象存储最大并发数
juicefs.upload-limit0单进程写入对象存储速度限制（单位：byte/s）
juicefs.max-downloads200单进程读取对象存储最大并发数
juicefs.download-limit0单进程读取对象存储速度限制（单位 byte/s）
juicefs.get-timeout5读取对象存储超时（单位：秒）
juicefs.put-timeout60写入对象存储超时（单位：秒）
juicefs.max-readahead0最大预读数据量（阅读「缓存」相关章节，了解预读设计），单位 MiB，默认为 0，此时预读量为 juicefs.memory-size 的 20%。如果希望尽量减少预读带来的读放大，可以设置为一个较小的值（如 1）。
juicefs.externalfalse是否使用公网域名访问对象存储

安全配置​

配置项默认值描述
juicefs.server-principal开启 Kerberos 支持后，需指定 JuiceFS 元数据服务的 principal，参考「使用 Kerberos」

其他配置​

配置项默认值描述
juicefs.access-log禁用「文件系统访问日志」的文件路径，可以配置为例如 /tmp/juicefs.access.log，需要所有使用 JuiceFS 的 Hadoop 应用都有写权限。该文件超过 300MiB 会进行滚动，保留最近 7 个文件。
juicefs.debugfalse是否启用 Debug 级别的日志。
juicefs.superuserhdfs超级用户，用这个设置告诉 JuiceFS Hadoop SDK，该集群的超级用户叫什么。
juicefs.supergrouphdfs超级用户组，所有组内用户均为超级用户。
juicefs.rsaPrivKeyPath用于数据存储加密的 RSA 密钥路径
juicefs.rsaPassphrase用于数据存储加密的 RSA 密钥密码
juicefs.file.checksumfalse用于 Hadoop DistCp 时是否验证 checksum，设置为 true 会导致数据额外多读一遍
juicefs.grouping指定 group 文件放置位置，用来配置用户组和用户映射信息，例如 jfs://myjfs/etc/group。文件内容格式：<groupname>:<username1>,<username2>
juicefs.conf-dir指定文件系统配置文件的目录，此配置文件可以在挂载机器的 /root/.juicefs 目录找到，名字格式为 {VOLUME}.conf。

配置多个 JuiceFS 文件系统​

当使用多个 JuiceFS 文件系统时，上述所有配置项均可对单个文件系统指定，需要将文件系统名字 VOL_NAME 放在配置项的中间，比如：

core-site.xml
<property>
  <name>juicefs.{VOLUME}.token</name>
  <value></value>
</property>
最后于 更新
Follow us on X
Let's chat on Slack