集群配置

JUICE 模块配置说明：实例定义、存储后端与挂载参数。

概念与实现

JuiceFS 由 元数据引擎 与 数据存储 两部分组成。 当前版本中，meta 会原样透传给 juicefs 作为元数据引擎 URL，生产场景通常使用 PostgreSQL。 数据存储通过 data 参数传入 juicefs format 选项决定。

JUICE 模块执行逻辑与关键命令：

BASH 
# 格式化（仅首次创建有效）
juicefs format --no-update <data> "<meta>" "<name>"

# 挂载
juicefs mount <mount_opts> --cache-dir <juice_cache> --metrics 0.0.0.0:<port> <meta> <path>

说明：

  • --no-update 确保已存在的文件系统不会被覆盖。
  • data 仅用于 首次格式化，文件系统已存在时不会生效。
  • mount 仅用于挂载阶段，可按需传入缓存与并发参数。

模块参数

JUICE 模块仅有两个参数：

参数类型级别说明
juice_cachepathCJuiceFS 共享缓存目录
juice_instancesdictIJuiceFS 实例字典（可为空）
  • juice_cache：所有实例共享的本地缓存目录，默认 /data/juice
  • juice_instances：在 实例级别 定义的实例字典，Key 为文件系统名称；空字典表示不管理实例

实例配置

juice_instances 的每个条目代表一个 JuiceFS 实例：

字段必选默认值说明
path是-挂载点路径，如 /fs
meta是-元数据引擎 URL（建议 PostgreSQL）
data否''juicefs format 选项（存储后端）
unit否juicefs-<name>systemd 服务名
mount否''juicefs mount 额外参数
port否9567指标端口（同节点需唯一）
owner否root挂载点属主
group否root挂载点属组
mode否0755挂载点权限
state否createcreate / absent

配置示例：

YAML 
juice_instances:
  jfs:
    path: /fs
    meta: postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta
    data: --storage postgres --bucket 10.10.10.10:5432/meta --access-key dbuser_meta --secret-key DBUser.Meta
    port: 9567

存储后端

data 字段直接拼接到 juicefs format，可配置任意支持的后端。 以下为常见示例：

PostgreSQL 数据后端

YAML 
juice_instances:
  jfs:
    path: /fs
    meta: postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta
    data: --storage postgres --bucket 10.10.10.10:5432/meta --access-key dbuser_meta --secret-key DBUser.Meta

JuiceFS 会在 --bucket 指定的数据库中创建 jfs_blob 表存储文件数据。 这里的 PostgreSQL 数据后端与 meta 元数据引擎是两个独立角色；它们可以使用同一个数据库，也可以分别部署。数据库和具有读写权限的用户必须预先存在。

Silo / MinIO 兼容对象存储

YAML 
juice_instances:
  jfs:
    path: /fs
    meta: postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta
    data: --storage minio --bucket https://sss.pigsty:9000/juice --access-key <s3_access_key> --secret-key <s3_secret_key>

S3 兼容存储

YAML 
juice_instances:
  jfs:
    path: /fs
    meta: postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta
    data: --storage s3 --bucket https://s3.amazonaws.com/my-bucket --access-key AKIAXXXXXXXX --secret-key XXXXXXXXXX

典型配置

多实例（同节点）

YAML 
juice_instances:
  pgfs:
    path: /pgfs
    meta: postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta
    data: --storage postgres --bucket 10.10.10.10:5432/meta --access-key dbuser_meta --secret-key DBUser.Meta
    port: 9567
  shared:
    path: /shared
    meta: postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/shared
    data: --storage minio --bucket https://sss.pigsty:9000/shared --access-key <s3_access_key> --secret-key <s3_secret_key>
    port: 9568
    owner: postgres
    group: postgres

多节点共享挂载

多个节点挂载同一个 JuiceFS：

YAML 
app:
  hosts:
    10.10.10.11: { juice_instances: { shared: { path: /shared, meta: "postgres://...", port: 9567 } } }
    10.10.10.12: { juice_instances: { shared: { path: /shared, meta: "postgres://...", port: 9567 } } }

第一次格式化由任一节点执行即可，其余节点会通过 --no-update 自动跳过。

注意事项

  • port 会暴露在 0.0.0.0，请结合防火墙或安全组控制访问。
  • data 变更不会更新已存在的文件系统，如需切换后端请手动处理。
  • meta 与 data 可能包含数据库或对象存储凭据；请限制 pigsty.yml 的读取权限，并使用独立的最小权限账号，生产环境不要沿用示例密码。

最后修改 2026-08-14 · v4.5.0 prerelease (e5d3b4fa)