这是本节的多页打印视图。 .

模块：JUICE

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

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

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

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

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

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

    subgraph PGSQL["PGSQL"]
        meta["Metadata DB"]
        blob["Data DB / jfs_blob（可选）"]
    end

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

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

    app --> jfs
    jfs --> meta
    jfs -.->|二选一的数据后端| blob
    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、Silo/MinIO、S3 等；元数据与文件数据是两个独立角色
监控集成 每实例暴露 Prometheus / Victoria 格式指标端口
配置简洁：以 juice_instances 字典描述实例

快速开始

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

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

部署：

BASH

./juice.yml -l <host>

1 - 集群配置

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_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。

配置示例：

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 的读取权限，并使用独立的最小权限账号，生产环境不要沿用示例密码。

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：

YAML

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

`juice_cache`

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

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

YAML

juice_cache: /data/juice

`juice_instances`

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

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

YAML

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 的任务结构如下：

BASH

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>`	只处理指定实例

示例：

BASH

./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 目标文件

配置更新

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

BASH

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

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

BASH

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

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

BASH

systemctl restart juicefs-<name>

移除实例

移除流程：

将实例 state 置为 absent
执行 juice_clean

YAML

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

BASH

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

移除动作包括：停止服务、懒卸载、删除 systemd 单元与环境文件、重载 systemd；随后 juice_register 会重写该节点的目标文件并移除陈旧抓取地址。只执行 juice_clean 不会更新监控 Target。 不会删除 PostgreSQL 元数据、PostgreSQL jfs_blob 数据表或对象存储数据。

监控注册

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

TEXT

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

如需手动重新注册：

BASH

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

4 - 管理预案

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

常见运维场景如下：

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

更多问题参见 FAQ。

初始化实例

BASH

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

初始化流程：

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

重新配置

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

BASH

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

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

BASH

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

说明：

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

移除实例

将实例 state 设为 absent
执行 juice_clean

YAML

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

BASH

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

移除动作：

停止 systemd 服务
umount -l 懒卸载
删除 unit 与环境文件
重载 systemd
重写该节点的 VictoriaMetrics 目标文件，移除 state=absent 的实例

不会删除 PostgreSQL 元数据、PostgreSQL jfs_blob 数据表或对象存储数据。

只执行 -t juice_clean 不会更新监控目标，会暂时留下已移除实例的陈旧抓取地址；因此上面的命令同时执行 juice_register。

添加新实例

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

YAML

juice_instances:
  newfs:
    path: /newfs
    meta: postgres://...
    data: --storage minio --bucket https://sss.pigsty:9000/newfs --access-key <s3_access_key> --secret-key <s3_secret_key>
    port: 9568

部署：

BASH

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

多节点共享挂载

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

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

PITR 恢复

JuiceFS 元数据与数据必须恢复到相互一致的状态。执行任何恢复前，请停止所有写入方并卸载/停止每个客户端上的对应 JuiceFS 服务，明确目标 PostgreSQL 集群和时间点，并先确认可用备份：

BASH

# 核对 Patroni 集群成员；在数据库节点核对目标 stanza 的备份
pig pt list <cluster>
pig pb info -s <stanza>

# 在目标数据库节点以 postgres 用户执行恢复
sudo -iu postgres pg-pitr -s <stanza> -t "2026-08-14 10:30:00+08"

PITR 会覆盖 PostgreSQL 数据目录

确认准确的集群名、近期备份、恢复时间点与回滚方案后，按照 PostgreSQL PITR 教程停止 Patroni/PostgreSQL 并执行恢复。pg-pitr 不负责停止服务、恢复 Patroni/DCS、验证数据或重建副本，不要把上述命令当作完整恢复流程。

当元数据与 --storage postgres 的 jfs_blob 位于同一个被恢复的 PostgreSQL 数据库中时，数据库级 PITR 可以把两者恢复到同一时间点。若两者位于不同数据库或集群，必须设计一致的联合恢复点。

如果文件数据位于 Silo/S3，对 PostgreSQL 做 PITR 只会回滚元数据，不会回滚对象：目标时间点之后的新对象可能残留，而已删除或回收的旧对象可能无法找回。恢复能否得到完整文件系统取决于对象版本、回收站与生命周期策略；验证完成前不要运行垃圾回收。

故障排查

挂载失败

BASH

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

元数据连接问题

BASH

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

指标端口检查

BASH

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

性能调优

通过 mount 传入 juicefs mount 选项：

YAML

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。

监控架构

TEXT

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

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

TEXT

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

当前源码随附 Node JuiceFS 仪表盘（UID：node-juice），用于查看单个节点上各 JuiceFS 挂载实例的容量、缓存、对象存储、元数据事务与客户端资源指标。

目标文件示例

YAML

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

如需手动注册：

BASH

./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

缓存命中率：

PROMQL

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

对象存储 P99 延迟：

PROMQL

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

6 - 常见问题

JUICE 模块常见问题解答。

端口冲突怎么办？

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

YAML

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

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

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

如何添加新实例？

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

BASH

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

如何移除实例？

将实例 state 设为 absent
执行：

BASH

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

移除不会删除 PostgreSQL 元数据或对象存储数据。 juice_register 用于同步刷新目标文件；只运行 juice_clean 会留下陈旧的监控抓取地址。

文件数据存储在哪里？

取决于 data 参数：

--storage postgres：JuiceFS 在 --bucket 指定的 PostgreSQL 数据库中创建 jfs_blob 表存储数据
--storage minio/s3：数据存于 Silo/S3 兼容对象存储的 bucket

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

多节点挂载注意事项？

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

监控目标没有生成？

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

BASH

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

如何修改挂载参数？

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

BASH

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

模块：JUICE

模块特点

快速开始

1 - 集群配置

概念与实现

模块参数

实例配置

存储后端

PostgreSQL 数据后端

Silo / MinIO 兼容对象存储

S3 兼容存储

典型配置

多实例（同节点）

多节点共享挂载

注意事项

2 - 参数列表

参数概览

默认参数

juice_cache

juice_instances

3 - 预置剧本

juice.yml

运行粒度

常用标签

配置更新

移除实例

监控注册

4 - 管理预案

初始化实例

重新配置

移除实例

添加新实例

多节点共享挂载

PITR 恢复

故障排查

挂载失败

元数据连接问题

指标端口检查

性能调优

5 - 监控告警

监控架构

目标文件示例

关键指标

对象存储

缓存

元数据事务

常用 PromQL

6 - 常见问题

端口冲突怎么办？

为什么 data 变更不生效？

如何添加新实例？

如何移除实例？

文件数据存储在哪里？

多节点挂载注意事项？

监控目标没有生成？

如何修改挂载参数？

`juice_cache`

`juice_instances`

`juice.yml`

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