这是本节的多页打印视图。点击此处打印.

模块：JUICE

使用 JuiceFS 分布式文件系统，以 PostgreSQL 作为元数据引擎，提供可共享的 POSIX 存储。

1: 集群配置
2: 参数列表
3: 预置剧本
4: 管理预案
5: 监控告警
6: 常见问题

JuiceFS 是一款高性能、POSIX 兼容的分布式文件系统，可以将对象存储/数据库挂载为本地文件系统。

JUICE 模块依赖 NODE 的基础设施与软件仓库，通常使用 PGSQL 作为元数据引擎。数据存储可以使用 PostgreSQL，或 MINIO / S3 等对象存储。监控集成依赖 INFRA 的 VictoriaMetrics。

flowchart LR
    subgraph Client["应用/用户"]
        app["POSIX 访问"]
    end

    subgraph JUICE["JUICE"]
        jfs["JuiceFS Mount"]
    end

    subgraph PGSQL["PGSQL"]
        meta["Metadata DB"]
    end

    subgraph Object["对象存储（可选）"]
        s3["S3 / MinIO"]
    end

    subgraph INFRA["INFRA（可选）"]
        vm["VictoriaMetrics"]
    end

    app --> jfs
    jfs --> meta
    jfs -.-> s3
    jfs -->|/metrics| vm

    style JUICE fill:#5B9CD5,stroke:#4178a8,color:#fff
    style PGSQL fill:#3E668F,stroke:#2d4a66,color:#fff
    style Object fill:#FCDB72,stroke:#d4b85e,color:#333
    style INFRA fill:#999,stroke:#666,color:#fff

模块特点

PostgreSQL 元数据：元数据存储于 PostgreSQL，便于管理与备份
多实例：单节点可挂载多个独立文件系统实例
多种数据后端：支持 PostgreSQL、MinIO、S3 等
监控集成每实例暴露 Prometheus / Victoria 指标端口
配置简洁：以 juice_instances 字典描述实例

快速开始

最小配置示例（单实例）：

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

部署：

./juice.yml -l <host>

1 - 集群配置

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

概念与实现

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

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

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

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

说明：

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

模块参数

JUICE 模块仅有两个参数：

参数	类型	级别	说明
`juice_cache`	`path`	`C`	JuiceFS 共享缓存目录
`juice_instances`	`dict`	`I`	JuiceFS 实例字典（可为空）

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`	否	`create`	`create` / `absent`

重要

建议在 首次格式化 时显式设置 data，以明确存储后端。
同一节点多个实例必须配置不同的 port。

配置示例：

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 大对象

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

MinIO 对象存储

juice_instances:
  jfs:
    path: /fs
    meta: postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta
    data: --storage minio --bucket http://10.10.10.10:9000/juice --access-key minioadmin --secret-key minioadmin

S3 兼容存储

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

典型配置

多实例（同节点）

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 http://10.10.10.10:9000/shared
    port: 9568
    owner: postgres
    group: postgres

多节点共享挂载

多个节点挂载同一个 JuiceFS：

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 变更不会更新已存在的文件系统，如需切换后端请手动处理。

2 - 参数列表

JUICE 模块参数说明（共 2 项）。

JUICE 模块参数共 2 项：

juice_cache：共享缓存目录
juice_instances：实例定义字典

参数概览

参数	类型	级别	说明
`juice_cache`	`path`	`C`	JuiceFS 共享缓存目录
`juice_instances`	`dict`	`I`	JuiceFS 实例定义字典（可为空）

级别说明：C 为集群级别，I 为实例级别。

默认参数

参数定义于 roles/juice/defaults/main.yml：

#-----------------------------------------------------------------
# JUICE
#-----------------------------------------------------------------
juice_cache: /data/juice
juice_instances: {}

`juice_cache`

参数名称：juice_cache，类型：path，级别：C

所有 JuiceFS 实例共享的本地缓存目录，默认 /data/juice。 JuiceFS 会在此目录下按文件系统 UUID 进行隔离。

juice_cache: /data/juice

`juice_instances`

参数名称：juice_instances，类型：dict，级别：I

JuiceFS 实例定义字典，通常在实例级别定义。默认值为空字典（表示不部署实例）；Key 为文件系统名称，Value 为实例配置对象。

juice_instances:
  jfs:
    path: /fs
    meta: postgres://u:p@h:5432/db
    data: --storage postgres --bucket ...
    port: 9567

实例字段说明：

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

注意

data 仅用于 juicefs format，文件系统创建后不会再更新。
同一节点多实例必须使用不同的 port。

3 - 预置剧本

JUICE 模块剧本使用说明。

JUICE 模块提供 juice.yml 剧本，用于部署与移除 JuiceFS 实例。

`juice.yml`

juice.yml 的任务结构如下：

juice_id        : 校验配置、检查端口冲突
juice_install   : 安装 juicefs 软件包
juice_cache     : 创建共享缓存目录
juice_clean     : 移除实例（state=absent）
juice_instance  : 创建实例（state=create）
  - juice_init  : 格式化文件系统（--no-update）
  - juice_dir   : 创建挂载点目录
  - juice_config: 渲染环境文件与 systemd 服务单元
  - juice_launch: 启动服务并等待指标端口就绪
juice_register  : 注册到 VictoriaMetrics 目标文件

运行粒度

粒度	限制参数	说明
节点	`-l <host>`	部署该节点所有实例
实例	`-l <host> -e fsname=<name>`	只处理指定实例

示例：

./juice.yml -l 10.10.10.10                 # 部署该节点所有实例
./juice.yml -l 10.10.10.10 -e fsname=jfs   # 仅部署 jfs 实例

常用标签

标签	说明
`juice_id`	校验 `juice_instances` 与端口冲突
`juice_install`	安装 `juicefs` 软件包
`juice_cache`	创建共享缓存目录
`juice_clean`	移除实例（state=absent）
`juice_instance`	创建实例（伞形标签）
`juice_init`	格式化文件系统
`juice_dir`	创建挂载点目录
`juice_config`	渲染配置文件
`juice_launch`	启动服务
`juice_register`	写入 VictoriaMetrics 目标文件

配置更新

仅更新配置文件（不重启服务）：

./juice.yml -l <host> -t juice_config

更新配置并确保服务在线（不强制重启）：

./juice.yml -l <host> -t juice_config,juice_launch

如需让新的挂载参数立即生效，请手动重启对应实例服务：

systemctl restart juicefs-<name>

移除实例

移除流程：

将实例 state 置为 absent
执行 juice_clean

juice_instances:
  jfs:
    path: /fs
    meta: postgres://...
    state: absent

./juice.yml -l <host> -t juice_clean
./juice.yml -l <host> -e fsname=jfs -t juice_clean

移除动作包括：停止服务、懒卸载、删除 systemd 单元与环境文件、重载 systemd。 不会删除 PostgreSQL 元数据或对象存储数据。

监控注册

juice_register 会在 infra 节点 写入目标文件：

/infra/targets/juice/<hostname>.yml

如需手动重新注册：

./juice.yml -l <host> -t juice_register

4 - 管理预案

JUICE 模块运维与故障排查手册。

常见运维场景如下：

初始化实例
重新配置
移除实例
添加新实例
多节点共享挂载
PITR 恢复
故障排查
性能调优

更多问题参见 FAQ。

初始化实例

./juice.yml -l <host>
./juice.yml -l <host> -e fsname=<name>

初始化流程：

安装 juicefs 软件包
创建共享缓存目录（默认 /data/juice）
执行 juicefs format --no-update（仅首次创建有效）
创建挂载点目录并设置权限
渲染 systemd 单元与环境文件
启动服务并等待指标端口就绪
注册到 VictoriaMetrics（若存在 infra 节点）

重新配置

修改配置后，建议执行以下命令（更新配置并确保服务在线）：

./juice.yml -l <host> -t juice_config,juice_launch

仅渲染配置文件而不触碰服务状态：

./juice.yml -l <host> -t juice_config

说明：

juice_config,juice_launch 会确保服务处于 started，但不会强制重启已运行实例
data 仅在首次 format 时生效
变更 mount 参数后，请手动重启对应服务（systemctl restart juicefs-<name>）

移除实例

将实例 state 设为 absent
执行 juice_clean

juice_instances:
  jfs:
    path: /fs
    meta: postgres://...
    state: absent

./juice.yml -l <host> -t juice_clean
./juice.yml -l <host> -e fsname=jfs -t juice_clean

移除动作：

停止 systemd 服务
umount -l 懒卸载
删除 unit 与环境文件
重载 systemd

不会删除 PostgreSQL 元数据与对象存储数据。

添加新实例

在配置中新增实例，确保端口唯一：

juice_instances:
  newfs:
    path: /newfs
    meta: postgres://...
    data: --storage minio --bucket http://minio:9000/newfs
    port: 9568

部署：

./juice.yml -l <host> -e fsname=newfs

多节点共享挂载

多个节点配置相同的 meta 与实例名：

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 自动跳过。

PITR 恢复

当 数据也存储在 PostgreSQL（--storage postgres）时，可通过 PG 的 PITR 恢复文件系统：

# 停止所有节点上的服务
systemctl stop juicefs-jfs

# 使用 pgBackRest 恢复元数据库
pb restore --stanza=meta --type=time --target="2024-01-15 10:30:00"

# 启动 PostgreSQL
systemctl start postgresql

# 启动 JuiceFS 服务
systemctl start juicefs-jfs

如果数据存储在 MinIO/S3，仅元数据可回滚，数据对象不会自动回退。

故障排查

挂载失败

systemctl status juicefs-jfs
journalctl -u juicefs-jfs -f
mountpoint /fs

元数据连接问题

psql "postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta" -c "SELECT 1"

指标端口检查

ss -tlnp | grep 9567
curl http://localhost:9567/metrics

性能调优

通过 mount 传入 juicefs mount 选项：

juice_instances:
  jfs:
    path: /fs
    meta: postgres://...
    mount: --cache-size 102400 --prefetch 3 --max-uploads 50

常用关注指标：

juicefs_blockcache_hits/juicefs_blockcache_miss：缓存命中率
juicefs_object_request_durations_histogram_seconds：对象存储延迟
juicefs_transaction_durations_histogram_seconds：元数据事务延迟

5 - 监控告警

JUICE 模块监控与指标说明。

JuiceFS 实例通过 juicefs mount --metrics 暴露 Prometheus 指标。在 JUICE 模块中，指标监听地址为 0.0.0.0:<port>，默认端口 9567。

监控架构

JuiceFS Mount (metrics: 0.0.0.0:<port>)
    ↓
VictoriaMetrics (scrape)
    ↓
Grafana Dashboard

若已部署 INFRA，juice_register 会自动写入抓取目标：

/infra/targets/juice/<hostname>.yml

目标文件示例

- labels: { ip: 10.10.10.10, ins: "node-jfs", cls: "jfs" }
  targets: [ 10.10.10.10:9567 ]

如需手动注册：

./juice.yml -l <host> -t juice_register

关键指标

对象存储

指标	类型	说明
`juicefs_object_request_durations_histogram_seconds`	histogram	对象存储请求延迟
`juicefs_object_request_errors`	counter	对象存储错误数

缓存

指标	类型	说明
`juicefs_blockcache_hits`	counter	缓存命中次数
`juicefs_blockcache_miss`	counter	缓存未命中次数

元数据事务

指标	类型	说明
`juicefs_transaction_durations_histogram_seconds`	histogram	元数据事务延迟（直方图）
`juicefs_transaction_durations_histogram_seconds_count`	counter	元数据事务请求计数

常用 PromQL

缓存命中率：

rate(juicefs_blockcache_hits[5m]) /
(rate(juicefs_blockcache_hits[5m]) + rate(juicefs_blockcache_miss[5m]))

对象存储 P99 延迟：

histogram_quantile(0.99, rate(juicefs_object_request_durations_histogram_seconds_bucket[5m]))

6 - 常见问题

JUICE 模块常见问题解答。

端口冲突怎么办？

同一节点上的多个实例必须使用不同的 port。示例：

juice_instances:
  fs1:
    path: /fs1
    meta: postgres://...
    port: 9567
  fs2:
    path: /fs2
    meta: postgres://...
    port: 9568

为什么 `data` 变更不生效？

data 仅用于 juicefs format --no-update，文件系统创建后不会再更新。如需切换后端，请手动迁移与重新格式化。

如何添加新实例？

在配置中新增实例定义
执行：

./juice.yml -l <host> -e fsname=<name>

如何移除实例？

将实例 state 设为 absent
执行：

./juice.yml -l <host> -t juice_clean

移除不会删除 PostgreSQL 元数据或对象存储数据。

文件数据存储在哪里？

取决于 data 参数：

--storage postgres：数据存于 PostgreSQL pg_largeobject
--storage minio/s3：数据存于对象存储 bucket

元数据存储在 meta 指定的元数据引擎中（Pigsty 生产场景通常使用 PostgreSQL）。

多节点挂载注意事项？

多节点使用相同的 meta 与实例名
首次格式化仅需执行一次，其余节点会自动跳过
确保 port 在每个节点上不冲突

监控目标没有生成？

juice_register 仅在存在 infra 组时写入 /infra/targets/juice/。可手动执行：

./juice.yml -l <host> -t juice_register

如何修改挂载参数？

在实例中调整 mount 后，先刷新配置，再手动重启服务：

./juice.yml -l <host> -t juice_config,juice_launch
systemctl restart juicefs-<name>

模块：JUICE

模块特点

快速开始

1 - 集群配置

概念与实现

模块参数

实例配置

存储后端

PostgreSQL 大对象

MinIO 对象存储

S3 兼容存储

典型配置

多实例（同节点）

多节点共享挂载

注意事项

2 - 参数列表

参数概览

默认参数

juice_cache

juice_instances

3 - 预置剧本

juice.yml

运行粒度

常用标签

配置更新

移除实例

监控注册

4 - 管理预案

初始化实例

重新配置

移除实例

添加新实例

多节点共享挂载

PITR 恢复

故障排查

挂载失败

元数据连接问题

指标端口检查

性能调优

5 - 监控告警

监控架构

目标文件示例

关键指标

对象存储

缓存

元数据事务

常用 PromQL

6 - 常见问题

端口冲突怎么办？

为什么 data 变更不生效？

如何添加新实例？

如何移除实例？

文件数据存储在哪里？

多节点挂载注意事项？

监控目标没有生成？

如何修改挂载参数？

`juice_cache`

`juice_instances`

`juice.yml`

为什么 `data` 变更不生效？