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

模块：JUICE

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

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

JuiceFS 是一款高性能的 POSIX 兼容分布式文件系统，可以使用 PostgreSQL 作为元数据引擎。

Pigsty 中的 JUICE 模块提供了完整的 JuiceFS 部署与管理方案，支持多实例配置、自动化安装、监控集成，以及利用 PostgreSQL 的备份恢复能力实现文件系统的时间点恢复（PITR）。

模块特点

PostgreSQL 元数据引擎：利用 PostgreSQL 存储文件系统元数据，享受高可用与 PITR 能力
灵活的数据存储：支持 PostgreSQL 大对象、MinIO、S3 等多种后端存储
多实例支持：单节点可挂载多个独立的 JuiceFS 文件系统
PITR 能力：利用 PostgreSQL 的备份恢复能力实现文件系统时间点恢复
监控集成：自动集成到 VictoriaMetrics 监控系统

配置示例

以下是一个典型的 JuiceFS 配置示例，使用 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
    port  : 9567

使用场景

JUICE 模块适用于以下场景：

AI 编程沙箱：为 Code-Server、Jupyter Lab 提供持久化存储
共享存储：多节点挂载同一文件系统，实现文件共享
数据湖存储：为数据分析、机器学习任务提供大容量存储
备份归档：利用对象存储后端实现低成本的数据归档

文档导航

集群配置：配置 JuiceFS 实例、存储后端和挂载选项
参数列表：JUICE 模块的参数说明
预置剧本：部署和管理 JuiceFS 的剧本使用指南
管理预案：JuiceFS 管理 SOP，包括扩容、PITR 恢复等
监控告警：JuiceFS 监控指标与 Grafana 仪表盘
常见问题：JuiceFS 模块的常见问题解答

1 - 集群配置

根据需求场景选择合适的存储后端，配置 JuiceFS 文件系统实例

概念

JuiceFS 是一款高性能的 POSIX 文件系统，由元数据引擎和数据存储两部分组成。在 Pigsty 中，我们使用 PostgreSQL 作为元数据引擎，这意味着文件系统的元数据（目录结构、文件属性等）存储在 PostgreSQL 数据库中，可以充分利用 PostgreSQL 的高可用和备份恢复能力。

JUICE 模块的核心特点：

多实例支持：每个节点可以挂载多个 JuiceFS 文件系统实例
PostgreSQL 元数据：利用 PostgreSQL 的可靠性和 PITR 能力
监控集成：每个实例暴露 Prometheus 指标端口
灵活的存储后端：支持 PostgreSQL 大对象、MinIO、S3 等多种数据存储

模块参数

JUICE 模块有 2 个参数：

参数	类型	级别	说明
`juice_cache`	`path`	`C`	JuiceFS 共享缓存目录
`juice_instances`	`dict`	`H`	JuiceFS 实例定义字典，必选参数

juice_cache：所有实例共享的本地缓存目录，默认 /data/juice
juice_instances：必须在节点级别（Host）定义的字典，Key 为文件系统名称，Value 为实例配置对象

实例配置

juice_instances 是一个字典，其中每个键值对定义一个 JuiceFS 文件系统实例：

Key：文件系统名称（实例标识），如 jfs、pgfs、shared
Value：实例配置对象，包含以下字段：

字段	必选	默认值	说明
`path`	是	-	挂载点路径，如 `/fs`、`/pgfs`
`meta`	是	-	元数据引擎 URL，通常为 PostgreSQL 连接串
`data`	否	`''`	`juicefs format` 存储后端选项
`unit`	否	`juicefs-<name>`	systemd 服务名称
`mount`	否	`''`	`juicefs mount` 额外参数
`port`	否	`9567`	Prometheus 指标端口（同节点不同实例必须唯一）
`owner`	否	`root`	挂载点目录属主
`group`	否	`root`	挂载点目录属组
`mode`	否	`0755`	挂载点目录权限
`state`	否	`create`	`create` 创建实例，`absent` 移除实例

配置结构示例：

juice_instances:          # 节点级参数（字典）
  jfs:                    # Key：文件系统名称
    path  : /fs           # Value：实例配置对象
    meta  : postgres://u:p@h:5432/db
    port  : 9567
  shared:                 # 第二个文件系统
    path  : /shared
    meta  : postgres://u:p@h:5432/shared
    port  : 9568          # 端口必须唯一

端口冲突检测

同一节点上的多个 JuiceFS 实例必须使用不同的 port，剧本会在执行前检测端口冲突并报错。

存储后端

JuiceFS 支持多种数据存储后端，通过 data 字段配置 juicefs format 命令参数：

PostgreSQL 大对象存储

使用 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
    port  : 9567

这种模式的优势是数据和元数据统一管理，可以利用 PostgreSQL 的备份恢复能力实现文件系统的 PITR。

MinIO 对象存储

使用 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
    port  : 9567

S3 兼容存储

使用 AWS S3 或兼容 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
    port  : 9567

典型配置示例

单实例配置

最简单的单实例配置，使用 PostgreSQL 作为元数据和数据存储：

all:
  children:
    infra:
      hosts:
        10.10.10.10:
          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

多实例配置

同一节点挂载多个文件系统，注意端口必须唯一：

all:
  children:
    infra:
      hosts:
        10.10.10.10:
          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  : /data/shared
              meta  : postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/shared_meta
              data  : --storage minio --bucket http://10.10.10.10:9000/shared
              port  : 9568    # 必须与其他实例不同
              owner : postgres
              group : postgres

多节点共享文件系统

多个节点挂载同一个 JuiceFS 文件系统，实现共享存储：

all:
  children:
    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 } } }
        10.10.10.13: { juice_instances: { shared: { path: /shared, meta: "postgres://...", port: 9567 } } }

AI 编程沙箱配置

用于 AI 辅助编程的完整配置示例（对应 conf/vibe.yml）：

all:
  children:
    infra: { hosts: { 10.10.10.10: { infra_seq: 1 }} ,vars: { repo_enabled: false }}
    etcd:  { hosts: { 10.10.10.10: { etcd_seq: 1  }} ,vars: { etcd_cluster: etcd  }}
    pgsql: { hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } } ,vars: { pg_cluster: pgsql }}

  vars:
    # PGSQL 配置
    pg_version: 18
    pg_users:
      - { name: dbuser_meta ,password: DBUser.Meta ,pgbouncer: true ,roles: [dbrole_admin] }
    pg_databases:
      - { name: meta, comment: pigsty meta database }

    # JUICE 配置：使用 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
        port  : 9567

    # VIBE 配置：Code-Server、JupyterLab 和 Claude Code
    code_enabled: true
    code_password: Code.Server
    jupyter_enabled: true
    jupyter_password: Jupyter.Lab
    claude_enabled: true

部署步骤：

./deploy.yml     # 部署基础设施和 PostgreSQL
./juice.yml      # 部署 JuiceFS
./vibe.yml       # 部署 VIBE 模块（Code-Server、JupyterLab、Claude Code）

局限性

JuiceFS 实例的 port 在同一节点上必须唯一，用于暴露 Prometheus 指标
使用 PostgreSQL 作为数据存储时，文件数据存储为大对象，可能不适合超大文件场景
文件系统格式化（juicefs format）是一次性操作，修改存储后端需要重新格式化

2 - 参数列表

JUICE 模块提供了 2 个参数用于 JuiceFS 部署与配置

JUICE 模块的参数列表，共有 2 个参数：

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

参数概览

参数	类型	级别	说明
`juice_cache`	`path`	`C`	JuiceFS 共享缓存目录
`juice_instances`	`dict`	`H`	JuiceFS 实例定义字典，必选参数

参数级别说明：C 表示 Cluster 级别，可在全局或集群中统一配置；H 表示 Host 级别，必须在节点层面定义。

默认参数

JUICE：2 个参数，定义于 roles/juice/defaults/main.yml

#-----------------------------------------------------------------
# JUICE
#-----------------------------------------------------------------
juice_cache: /data/juice              # JuiceFS 共享缓存目录
juice_instances: {}                   # JuiceFS 实例定义字典

`JUICE`

本节包含 juice 角色的参数，这些是 juice.yml 剧本使用的配置参数。

`juice_cache`

参数名称： juice_cache，类型： path，层次：C

JuiceFS 所有实例共享的本地缓存目录，默认为 /data/juice。

JuiceFS 会在此目录下按文件系统 UUID 隔离各实例的缓存数据，用于加速频繁访问的文件读取。

juice_cache: /data/juice

`juice_instances`

参数名称： juice_instances，类型： dict，层次：H

JuiceFS 实例定义字典，必选参数，必须在节点（Host）层面显式配置。

内容为 JSON/YAML 字典格式，Key 为文件系统名称（实例标识），Value 为该实例的配置对象。

juice_instances:
  jfs:                                          # 文件系统名称
    path  : /fs                                 # [必选] 挂载点路径
    meta  : postgres://u:p@h:5432/db            # [必选] 元数据引擎 URL
    data  : --storage postgres --bucket ...    # 存储后端选项
    unit  : juicefs-jfs                         # systemd 服务名
    mount : ''                                  # 额外挂载选项
    port  : 9567                                # 指标端口（同节点必须唯一）
    owner : root                                # 挂载点属主
    group : root                                # 挂载点属组
    mode  : '0755'                              # 挂载点权限
    state : create                              # create | absent

每个实例的配置项说明：

字段	必选	默认值	说明
`path`	是	-	挂载点路径，如 `/fs`、`/pgfs`
`meta`	是	-	元数据引擎 URL，通常为 PostgreSQL 连接串
`data`	否	`''`	`juicefs format` 存储后端参数
`unit`	否	`juicefs-<name>`	systemd 服务单元名称
`mount`	否	`''`	`juicefs mount` 额外参数
`port`	否	`9567`	Prometheus 指标端口，同节点多实例必须唯一
`owner`	否	`root`	挂载点目录属主
`group`	否	`root`	挂载点目录属组
`mode`	否	`0755`	挂载点目录权限
`state`	否	`create`	`create` 创建实例，`absent` 移除实例

配置示例：

使用 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
    port  : 9567

使用 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
    port  : 9567

多实例配置（注意端口唯一）：

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
    port  : 9568    # 必须与 pgfs 不同
    owner : postgres
    group : postgres

端口冲突

同一节点上的多个 JuiceFS 实例必须配置不同的 port 值，否则剧本会在验证阶段报错并终止执行。

3 - 预置剧本

如何使用预置的 ansible 剧本来管理 JuiceFS 文件系统，常用管理命令速查。

JUICE 模块提供了一个剧本，用于部署和移除 JuiceFS 文件系统实例：

juice.yml：部署/移除 JuiceFS 实例

`juice.yml`

用于部署 JuiceFS 的 juice.yml 剧本包含以下子任务：

juice_id        : 验证配置，检查端口冲突
juice_install   : 安装 juicefs 软件包
juice_cache     : 创建共享缓存目录
juice_clean     : 清理实例（state=absent）
juice_instance  : 创建实例（state=create）
  - juice_init  : 格式化文件系统
  - juice_dir   : 创建挂载点目录
  - juice_config: 渲染配置文件
  - juice_launch: 启动 systemd 服务
juice_register  : 注册到监控系统

操作级别

juice.yml 支持两种操作级别：

操作级别	限制参数	说明
节点	`-l <ip>`	部署指定节点上的所有 JuiceFS 实例
实例	`-l <ip> -e fsname=<name>`	仅部署指定节点上的单个实例

节点级别操作

部署指定节点上定义的所有 JuiceFS 实例：

./juice.yml -l 10.10.10.10        # 部署该节点上的所有实例
./juice.yml -l 10.10.10.11        # 部署另一个节点

节点级别操作会：

安装 JuiceFS 软件包
创建共享缓存目录
格式化并挂载所有定义的文件系统实例
将所有实例注册到监控系统

实例级别操作

通过 -e fsname=<name> 参数指定单个实例进行操作：

# 仅部署 10.10.10.10 上名为 jfs 的实例
./juice.yml -l 10.10.10.10 -e fsname=jfs

# 仅部署 10.10.10.11 上名为 shared 的实例
./juice.yml -l 10.10.10.11 -e fsname=shared

实例级别操作适用于：

向现有节点添加新的文件系统实例
重新部署单个故障实例
更新单个实例的配置

常用标签

可以通过 -t <tag> 参数选择性执行部分任务：

# 仅安装软件包，不启动服务
./juice.yml -l 10.10.10.10 -t juice_install

# 仅更新配置文件（不启动服务）
./juice.yml -l 10.10.10.10 -t juice_config

# 仅更新监控注册
./juice.yml -l 10.10.10.10 -t juice_register

# 移除实例（需先在配置中设置 state: absent）
./juice.yml -l 10.10.10.10 -t juice_clean

幂等性说明

juice.yml 是幂等的，可以安全地重复执行：

juice_init（格式化）使用 --no-update 参数，仅在文件系统不存在时执行实际格式化
重复执行会覆盖现有配置文件并执行 daemon-reload
配置变更后需要手动重启服务，或通过完整执行剧本来启动服务
适用于配置变更后的批量更新

提示：如果只想更新配置文件而不启动服务，可以使用 -t juice_config 仅渲染配置。

移除实例

要移除 JuiceFS 实例，需要两个步骤：

在配置中将实例的 state 设置为 absent
执行剧本的 juice_clean 任务

# 步骤 1：修改配置
juice_instances:
  jfs:
    path  : /fs
    meta  : postgres://...
    state : absent    # 标记为待移除

# 步骤 2：执行移除
./juice.yml -l 10.10.10.10 -t juice_clean

# 或仅移除指定实例
./juice.yml -l 10.10.10.10 -e fsname=jfs -t juice_clean

移除操作会：

停止对应的 systemd 服务
执行 umount -l 懒卸载文件系统
删除 systemd 服务文件
删除环境配置文件
重载 systemd daemon

注意：移除操作不会删除 PostgreSQL 中的元数据和文件数据，如需彻底清理，请手动删除对应的数据库。

快速参考

部署操作速查

# 部署节点上所有实例
./juice.yml -l <ip>

# 部署单个实例
./juice.yml -l <ip> -e fsname=<name>

# 更新配置文件
./juice.yml -l <ip> -t juice_config

# 仅更新单个实例配置
./juice.yml -l <ip> -e fsname=<name> -t juice_config

移除操作速查

# 移除节点上所有标记为 absent 的实例
./juice.yml -l <ip> -t juice_clean

# 移除单个实例
./juice.yml -l <ip> -e fsname=<name> -t juice_clean

任务标签速查

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

4 - 管理预案

JuiceFS 文件系统管理 SOP，创建、移除、扩容与故障排查

以下是一些常见的 JuiceFS 管理任务 SOP（预案）：

基础运维

初始化 JuiceFS
移除 JuiceFS
重新配置 JuiceFS
使用 JuiceFS 客户端

扩容与维护

添加新实例
多节点共享挂载
PITR 恢复文件系统

故障排查

常见问题诊断
性能调优

更多问题请参考 FAQ：JUICE。

初始化 JuiceFS

您可以使用 juice.yml 剧本来初始化 JuiceFS 实例：

# 初始化节点上所有 JuiceFS 实例
./juice.yml -l 10.10.10.10

# 初始化特定实例
./juice.yml -l 10.10.10.10 -e fsname=jfs

初始化流程：

安装 juicefs 软件包
创建共享缓存目录 /data/juice
执行 juicefs format 格式化文件系统
创建挂载点目录并设置权限
渲染 systemd 服务配置
启动服务并等待端口就绪
注册到 VictoriaMetrics 监控

移除 JuiceFS

移除 JuiceFS 实例需要两个步骤：

# 步骤 1：在配置中将 state 设置为 absent
# juice_instances:
#   jfs:
#     path: /fs
#     meta: postgres://...
#     state: absent

# 步骤 2：执行移除
./juice.yml -l 10.10.10.10 -t juice_clean

# 或移除指定实例
./juice.yml -l 10.10.10.10 -e fsname=jfs -t juice_clean

移除操作会：

停止 systemd 服务
卸载文件系统（lazy umount）
删除服务配置文件
重载 systemd

注意：移除操作不会删除 PostgreSQL 中的数据，如需彻底清理请手动处理数据库。

重新配置 JuiceFS

您可以部分执行剧本来重新配置 JuiceFS 实例：

./juice.yml -l 10.10.10.10 -t juice_config

配置变更会触发服务重启。如果只想渲染配置而不重启，可以手动管理 systemd 服务。

使用 JuiceFS 客户端

JuiceFS 挂载后就是标准的 POSIX 文件系统，可以直接使用：

# 查看挂载状态
df -h /fs

# 查看文件系统信息
juicefs status /fs

# 查看文件系统统计
juicefs info /fs

# 列出活跃会话
juicefs status postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta

常用命令

# 查看缓存使用情况
juicefs warmup /fs/some/path

# 预热缓存
juicefs warmup -p 4 /fs/some/path

# 清理本地缓存
juicefs gc postgres://... --delete

# 导出文件系统元数据（备份）
juicefs dump postgres://... > metadata.json

# 导入元数据（恢复）
juicefs load postgres://... < metadata.json

添加新实例

向节点添加新的 JuiceFS 实例：

# 在配置清单中添加新实例
juice_instances:
  jfs:
    path  : /fs
    meta  : postgres://...
    port  : 9567
  newfs:                        # 新增实例
    path  : /newfs
    meta  : postgres://...
    port  : 9568                # 端口必须唯一

# 部署新实例
./juice.yml -l 10.10.10.10 -e fsname=newfs

多节点共享挂载

JuiceFS 支持多节点挂载同一文件系统，实现共享存储：

# 多节点配置相同的元数据 URL
app:
  hosts:
    10.10.10.11: { juice_instances: { shared: { path: /shared, meta: "postgres://..." } } }
    10.10.10.12: { juice_instances: { shared: { path: /shared, meta: "postgres://..." } } }
    10.10.10.13: { juice_instances: { shared: { path: /shared, meta: "postgres://..." } } }

# 部署到所有节点
./juice.yml -l app

注意：首次格式化只需要在一个节点执行，其他节点会自动跳过格式化步骤。

PITR 恢复文件系统

当使用 PostgreSQL 作为元数据和数据存储时，可以利用 PostgreSQL 的 PITR 能力恢复文件系统到任意时间点：

# 1. 停止所有节点的 JuiceFS 服务
systemctl stop juicefs-jfs

# 2. 使用 pgBackRest 恢复 PostgreSQL 到指定时间点
pb restore --stanza=meta --type=time --target="2024-01-15 10:30:00"

# 3. 重新启动 PostgreSQL 主库
systemctl start postgresql

# 4. 重新启动所有节点的 JuiceFS 服务
systemctl start juicefs-jfs

这种方式可以恢复文件系统到备份时间范围内的任意时刻。

常见问题诊断

挂载失败排查

# 检查 systemd 服务状态
systemctl status juicefs-jfs

# 查看服务日志
journalctl -u juicefs-jfs -f

# 检查挂载点
mountpoint /fs

# 手动挂载测试
juicefs mount postgres://... /fs --foreground

连接问题排查

# 测试元数据引擎连接
psql "postgres://dbuser_meta:DBUser.Meta@10.10.10.10:5432/meta" -c "SELECT 1"

# 检查端口监听
ss -tlnp | grep 9567

# 测试指标端口
curl http://localhost:9567/metrics

文件系统问题

# 检查文件系统状态
juicefs status /fs

# 检查文件系统一致性
juicefs fsck postgres://...

# 查看活跃会话
juicefs status postgres://... --session

性能调优

缓存优化

juice_instances:
  jfs:
    path  : /fs
    meta  : postgres://...
    mount : --cache-size 102400 --prefetch 3    # 100GB 缓存，预取 3 个块

并发优化

juice_instances:
  jfs:
    path  : /fs
    meta  : postgres://...
    mount : --max-uploads 50 --max-deletes 10   # 并发上传/删除数

内存优化

juice_instances:
  jfs:
    path  : /fs
    meta  : postgres://...
    mount : --buffer-size 300 --open-cache 3600 # 缓冲区大小，打开文件缓存时间

监控关键指标

通过 Prometheus 指标监控 JuiceFS 性能：

juicefs_object_request_durations_histogram_seconds：对象存储请求延迟
juicefs_blockcache_hits/misses：缓存命中率
juicefs_fuse_*：FUSE 操作统计
juicefs_meta_ops_durations_histogram_seconds：元数据操作延迟

5 - 监控告警

JuiceFS 文件系统的监控指标与 Grafana 仪表盘

JuiceFS 每个实例会在配置的端口（默认 9567）暴露 Prometheus 格式的监控指标。

监控架构

JuiceFS Instance (port: 9567)
    ↓ /metrics
VictoriaMetrics (scrape)
    ↓
Grafana Dashboard

Pigsty 会自动将 JuiceFS 实例注册到 VictoriaMetrics，目标文件位于：

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

关键指标

对象存储指标

指标	类型	说明
`juicefs_object_request_durations_histogram_seconds`	histogram	对象存储请求延迟分布
`juicefs_object_request_data_bytes`	counter	对象存储数据传输量
`juicefs_object_request_errors`	counter	对象存储请求错误数

缓存指标

指标	类型	说明
`juicefs_blockcache_hits`	counter	块缓存命中数
`juicefs_blockcache_misses`	counter	块缓存未命中数
`juicefs_blockcache_writes`	counter	块缓存写入数
`juicefs_blockcache_drops`	counter	块缓存丢弃数
`juicefs_blockcache_evictions`	counter	块缓存淘汰数
`juicefs_blockcache_hit_bytes`	counter	缓存命中字节数
`juicefs_blockcache_miss_bytes`	counter	缓存未命中字节数

元数据指标

指标	类型	说明
`juicefs_meta_ops_durations_histogram_seconds`	histogram	元数据操作延迟分布
`juicefs_transaction_durations_histogram_seconds`	histogram	事务延迟分布
`juicefs_transaction_restart`	counter	事务重试次数

FUSE 操作指标

指标	类型	说明
`juicefs_fuse_ops_durations_histogram_seconds`	histogram	FUSE 操作延迟分布
`juicefs_fuse_read_size_bytes`	histogram	读操作大小分布
`juicefs_fuse_written_size_bytes`	histogram	写操作大小分布

文件系统指标

指标	类型	说明
`juicefs_used_space`	gauge	已使用空间（字节）
`juicefs_used_inodes`	gauge	已使用 inode

常用 PromQL

缓存命中率

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

对象存储 P99 延迟

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

元数据操作 P99 延迟

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

读写吞吐量

# 读吞吐
rate(juicefs_blockcache_hit_bytes[5m]) + rate(juicefs_blockcache_miss_bytes[5m])

# 写吞吐
rate(juicefs_fuse_written_size_bytes_sum[5m])

指标采集配置

JuiceFS 实例注册到 VictoriaMetrics 的目标文件格式：

# /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 <ip> -t juice_register

6 - 常见问题

JuiceFS 模块的常见问题解答

端口冲突怎么办？

同一节点上的多个 JuiceFS 实例必须配置不同的 port 值。如果遇到端口冲突错误：

juice_instances have port conflicts: [9567, 9567]

请在配置中为每个实例分配唯一的端口：

juice_instances:
  fs1:
    path: /fs1
    meta: postgres://...
    port: 9567
  fs2:
    path: /fs2
    meta: postgres://...
    port: 9568    # 必须不同

如何添加新实例？

在配置中添加新的实例定义
执行剧本指定新实例名称

./juice.yml -l 10.10.10.10 -e fsname=newfs

如何移除实例？

在配置中将实例的 state 设置为 absent
执行 juice_clean 任务

./juice.yml -l 10.10.10.10 -e fsname=jfs -t juice_clean

文件系统数据存储在哪里？

取决于 data 参数配置：

PostgreSQL 大对象：数据存储在 PostgreSQL 数据库的 pg_largeobject 表中
MinIO/S3：数据存储在对象存储的指定 bucket 中

元数据始终存储在 meta 参数指定的 PostgreSQL 数据库中。

支持哪些存储后端？

JuiceFS 支持多种存储后端，在 Pigsty 中常用的有：

postgres：PostgreSQL 大对象存储
minio：MinIO 对象存储
s3：AWS S3 或兼容 S3 协议的存储

详细列表请参考 JuiceFS 官方文档。

可以在多个节点挂载同一个文件系统吗？

可以。只需要在多个节点配置相同的 meta URL，JuiceFS 会自动处理并发访问。

首次格式化只需在一个节点执行，其他节点会自动跳过格式化步骤。

如何利用 PITR 恢复文件系统？

当使用 PostgreSQL 作为元数据和数据存储时：

停止所有 JuiceFS 服务
使用 pgBackRest 恢复 PostgreSQL 到目标时间点
重启 PostgreSQL 和 JuiceFS 服务

详细步骤请参考管理预案：PITR 恢复文件系统。

缓存目录可以自定义吗？

可以，通过 juice_cache 参数设置：

juice_cache: /data/juice    # 默认值
# 或
juice_cache: /ssd/juice     # 使用 SSD 存储缓存

挂载选项怎么配置？

通过实例的 mount 字段传递额外的 juicefs mount 参数：

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

常用选项：

选项	说明
`--cache-size`	本地缓存大小（MB）
`--prefetch`	预取块数
`--buffer-size`	读写缓冲区大小（MB）
`--max-uploads`	最大并发上传数
`--open-cache`	打开文件缓存时间（秒）

为什么格式化时使用 –no-update？

剧本在执行 juicefs format 时使用 --no-update 参数，确保已存在的文件系统不会被意外修改。这使得剧本可以安全地在多个节点重复执行，而不影响已有的文件系统配置。

服务无法启动怎么办？

检查以下几点：

PostgreSQL 连接：确保元数据库可访问

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

服务状态：查看 systemd 日志

systemctl status juicefs-jfs
journalctl -u juicefs-jfs -f

挂载点：确保挂载点目录存在且未被占用
```
ls -la /fs
mountpoint /fs
```
端口：确保端口未被占用
```
ss -tlnp | grep 9567
```