JUICE on Pigsty v5.0

模块：JUICE

Mon, 01 Jan 0001 00:00:00 +0000

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

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

集群配置

Mon, 01 Jan 0001 00:00:00 +0000

概念与实现

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

参数列表

Mon, 01 Jan 0001 00:00:00 +0000

JUICE 模块参数共 2 项：

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

参数概览

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

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

预置剧本

Mon, 01 Jan 0001 00:00:00 +0000

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

示例：

管理预案

Mon, 01 Jan 0001 00:00:00 +0000

常见运维场景如下：

更多问题参见 FAQ。

初始化实例

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

初始化流程：

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

重新配置

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

监控告警

Mon, 01 Jan 0001 00:00:00 +0000

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 会自动写入抓取目标：

常见问题

Mon, 01 Jan 0001 00:00:00 +0000

端口冲突怎么办？

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

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

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

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

JUICE on Pigsty v5.0

模块：JUICE

集群配置

概念与实现

参数列表

参数概览

预置剧本

juice.yml

运行粒度

管理预案

初始化实例

重新配置

监控告警

监控架构

常见问题

端口冲突怎么办？

为什么 data 变更不生效？

`juice.yml`

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