Skip to content

JuiceFS 服务配置 ​

JuiceFS 是一个开源、POSIX 兼容的分布式文件系统。JuiceFS 采用数据与元数据分离的设计,数据存储在对象存储,元数据存储在元数据存储,支持接入使用 Redis、MySQL、TiKV 等元数据存储和 MinIO、S3、COS 等对象存储。

CubeSandbox 借助 JuiceFS 的能力实现跨机存储方案,具体架构见 JuiceFS 跨机存储架构,性能测试数据见 JuiceFS 性能测试。

预览版

JuiceFS 存储方案目前处于 Preview 预览阶段,适合快速上手与早期试用。配置项、部署脚本和运行行为在后续版本中仍可能调整。默认搭配控制节点 Redis/MinIO 仅适用于试用;生产环境请先在测试环境验证,并参考更换存储切换到更可靠的元数据引擎与对象存储。

前置条件 ​

  • 所有节点的内核需要 FUSE 支持
  • 所有节点能够访问同一个 JuiceFS 元数据引擎和对象存储。

one-click 安装部署 ​

默认 one-click 不会启用 JuiceFS 跨机存储方案,需要手动配置启用。

可以在安装 one-click 时编辑 .env 文件配置相关信息,也可以在安装后编辑 cube 全局配置文件 .one-click.env。

bash
# one-click 包的 .env 文件路径
cp env.example .env

# 或者安装完成后编辑配置文件 /usr/local/services/cubetoolbox/.one-click.env
vim /usr/local/services/cubetoolbox/.one-click.env

控制节点初始化 ​

首先在应在控制节点配置信息并初始化 JuiceFS 文件系统,然后再在各计算节点进行配置。

Cube 默认使用控制节点上的 Redis 作为 JuiceFS 元数据引擎,使用控制节点上的 MinIO 作为对象存储。

该方案仅适用于快速上手尝试,后续如需在生产环境部署,请切换到其他元数据引擎或对象存储,见下文更换存储。

设置 ONE_CLICK_ENABLE_JFS=1:

bash
ONE_CLICK_ENABLE_JFS=1

初始化 JuiceFS 文件系统,在控制节点执行如下命令:

bash
sudo /usr/local/services/cubetoolbox/scripts/cube-jfs/init.sh

然后挂载控制节点 JuiceFS 文件系统:

bash
sudo /usr/local/services/cubetoolbox/scripts/cube-jfs/mount.sh

计算节点初始化 ​

编辑计算节点的配置文件,设置 ONE_CLICK_ENABLE_JFS=1。

bash
ONE_CLICK_ENABLE_JFS=1

执行如下命令在计算节点挂载 JuiceFS 文件系统:

bash
sudo /usr/local/services/cubetoolbox/scripts/cube-jfs/mount.sh

执行了 mount.sh 脚本后 JuiceFS 挂载将会开机自启。

在控制节点检查 ​

所有节点挂载完成后,在控制节点执行脚本检查 JuiceFS 文件系统挂载状态:

bash
sudo /usr/local/services/cubetoolbox/scripts/cube-jfs/check.sh

应当输出类似如下内容:

bash
JuiceFS volume
  Name:          cube
  Storage:       s3
  Bucket:        http://<control-node-ip>:9000/cube-jfs
  Active clients: 3
  Used space:    12288 bytes

Active client sessions
  SID  CLIENT HOST   REPORTED ADDRESSES  MOUNT PATH         MOUNT TIME
  ---  ------------  ------------------  -----------------  ------------------------------
  2    a26a3780ac6f  172.17.0.2          /data/cubelet/storage/jfs  2026-10-28T08:46:15.482143729Z
  1    c9af1d5570f4  172.17.0.3          /data/cubelet/storage/jfs  2026-10-28T08:43:29.693002719Z
  3    30e38b8072fe  172.17.0.2          /data/cubelet/storage/jfs  2026-10-28T08:49:31.946778689Z

更换存储 ​

从 MinIO 迁移到其他对象存储 ​

修改配置文件使用其他对象存储:

bash
ONE_CLICK_ENABLE_JFS=1

# 可继续使用现有 Redis;新卷时必须是新的、空的元数据地址。
CUBE_JFS_META_URL="redis://<redis-host>:6379/0"
CUBE_JFS_META_PASSWORD="<redis-password>"

# 例如使用腾讯云 COS
CUBE_JFS_STORAGE="cos"
CUBE_JFS_BUCKET="https://<bucket>-<appid>.cos.<region>.myqcloud.com"
CUBE_JFS_ACCESS_KEY="<COS-SecretId>"
CUBE_JFS_SECRET_KEY="<COS-SecretKey>"

然后参考one-click 安装部署进行控制节点和计算节点初始化。

请注意,目前 Cube 暂不支持从对象存储 A 平滑切换到对象存储 B,请在 one-click 安装时指定需要使用的对象存储,或者参考 JuiceFS 官方的数据同步文档进行数据迁移。

使用 Redis 之外的元数据引擎 ​

JuiceFS 的元数据存储非常重要,如果在生产环境部署,推荐使用 Redis 集群以降低数据丢失的风险。

CUBE_JFS_META_URL 可以使用 JuiceFS 支持的 MySQL、PostgreSQL、TiKV 等地址。例如:

bash
CUBE_JFS_META_URL="mysql://user:@(10.0.0.20:3306)/juicefs"
CUBE_JFS_META_PASSWORD="password"

新集群直接填写该地址后执行控制节点初始化即可。已有卷迁移时,先停止写入并卸载所有客户端,再用 juicefs dump 从旧元数据引擎导出、用 juicefs load 导入一个空的新元数据引擎,随后更新所有节点的 CUBE_JFS_META_URL 并重新挂载。对象存储密钥默认不会包含在 dump 中,需要在新元数据引擎上重新配置。参考 JuiceFS 官方的元数据备份与迁移文档。

Kubernetes Helm 部署 ​

请先参考本文档中的 k8s 部署的 Helm 安装 章节,安装 Helm 并完成 Kubernetes 集群的初始化。

bash
cp deploy/kubernetes/chart/runtime-values.example.yaml runtime-values.yaml

默认配置不会启用 JuiceFS 跨机存储方案,需要手动修改 runtime-values.yaml 文件:

yaml
cubeJuiceFS:
  enabled: true

启用后 Chart 会额外部署:专供 JuiceFS 使用的独立 Redis、一个只在首次执行格式化的 Job,以及在每个计算节点挂载文件系统的 DaemonSet。

参考 Helm 部署章节中的 Helm 安装 章节,使用对应的多节点/腾讯云TKE/单节点集群的 Helm 安装命令进行安装。

bash
# 多节点集群安装命令
helm upgrade --install cube ./deploy/kubernetes/chart \
  -n cube-system \
  --create-namespace \
  -f runtime-values.yaml \
  --wait \
  --timeout 90m

如果 Cube 已经安装,但之前没启用 JuiceFS;现在升级并首次启用 JuiceFS 跨机存储方案,则启用过程会重建 Cube Node Pod。应先停止或迁移所有计算节点上正在运行的沙箱,再临时配置 lifecycleChangeAck: true:

yaml
cubeJuiceFS:
  enabled: true
  lifecycleChangeAck: true

第一次 helm upgrade 成功后,把 lifecycleChangeAck 改回 false,再执行 一次相同的 helm upgrade。

第二次升级只清除 Helm release 中的一次性确认,不会重启 Cube Node、JuiceFS 或 Redis。之后可以保留 false,也可以从 runtime-values.yaml 删除该行。lifecycleChangeAck 不是 JuiceFS 日常配置。

以后修改 JuiceFS 镜像、存储地址或挂载参数时的维护步骤,见 Kubernetes 升级说明。

验证 Kubernetes 部署 ​

bash
kubectl get job,daemonset,pod -n cube-system

kubectl exec -n cube-system daemonset/cube-juicefs -c juicefs -- \
  findmnt -T /data/cubelet/storage/jfs

kubectl exec -n cube-system daemonset/cube-node -c cubelet -- \
  findmnt -T /data/cubelet/storage/jfs

两次检查都必须显示 fuse.juicefs。之后创建模板时指定 --backend jfs; 已有 XFS 模板不会自动转换为 JFS。

更换存储 ​

Chart 默认创建独立的 JuiceFS Redis,并使用 Chart MinIO 中的 cube-jfs bucket。本节仅用于替换这两个默认后端, 外部 Redis 和外部对象存储可以单独替换,不要求同时配置。

从 MinIO 迁移到其他对象存储 ​

先创建对象存储 Secret 以避免明文存储密钥:

bash
kubectl -n cube-system create secret generic cube-jfs-object \
  --from-literal=access-key='<access-key>' \
  --from-literal=secret-key='<secret-key>'

然后在 runtime-values.yaml 中增加 storage:

yaml
cubeJuiceFS:
  enabled: true
  storage:
    type: s3
    bucket: https://<bucket>-<appid>.cos.<region>.myqcloud.com/cube-jfs
    existingSecret: cube-jfs-object

storage.bucket 是传给 JuiceFS 的完整 --bucket 值,不只是桶名;路径风格的 S3 兼容存储要把桶名写进 URL,例如 http://minio.example.com:9000/cube-jfs。

请注意,目前 Cube 暂不支持从对象存储 A 平滑切换到对象存储 B,请在安装时指定需要使用的对象存储,或者参考 JuiceFS 官方的数据同步文档进行数据迁移。

使用 Redis 之外的元数据引擎 ​

JuiceFS 的元数据存储非常重要,如果在生产环境部署,推荐使用 Redis 集群以降低数据丢失的风险。

只替换 Redis 时,先创建密码 Secret:

bash
kubectl -n cube-system create secret generic cube-jfs-meta \
  --from-literal=meta-password='<redis-password>'

然后在 runtime-values.yaml 中增加 metadata:

yaml
cubeJuiceFS:
  enabled: true
  metadata:
    url: redis://redis.example.com:6379/0
    existingSecret: cube-jfs-meta
    secretRevision: initial

节点变更 ​

新增节点 ​

  1. 按正常流程安装并注册新的 Cube 计算节点;
  2. 在新节点的 .one-click.env 写入 ONE_CLICK_ENABLE_JFS=1;
  3. 在新节点执行 sudo /usr/local/services/cubetoolbox/scripts/cube-jfs/mount.sh;
  4. 回到控制节点执行 sudo /usr/local/services/cubetoolbox/scripts/cube-jfs/check.sh,确认新会话出现。

控制节点只需要在初始化的时候执行一次 /usr/local/services/cubetoolbox/scripts/cube-jfs/init.sh,后续新增节点不需要再次执行。

删除节点 ​

先按节点相关操作隔离节点并清空沙箱。然后在待删除节点执行:

bash
sudo /usr/local/services/cubetoolbox/scripts/cube-jfs/mount.sh unmount

再在控制节点删除节点记录:

bash
cubeopscli node delete <node-id>

卸载节点不会删除共享 JuiceFS 中的数据。CUBE_JFS_ROOT 下的共享命名空间(objects/、snapshots/、pause-snapshots/)是全集群共享的,其中可能仍有模板、快照或暂停数据被其他节点引用,不要直接删除这些目录。

JFS 相关配置说明 ​

CUBE_JFS_* 系列变量可以在 .env / .one-click.env 中调整,大部分配置项不建议修改,这里说明几个需要关注的配置项。

变量默认值说明
CUBE_JFS_MOUNT_PATH/data/cubelet/storage/jfs挂载点
CUBE_JFS_ROOT.直接在挂载点保存共享命名空间
CUBE_JFS_CACHE_DIR/data/cubelet/jfs-cache本地缓存目录,读缓存与写 staging 都放在其中,建议放在节点的 NVMe/SSD 数据盘上
CUBE_JFS_CACHE_SIZE_MB102400(100 GiB)读缓存大小上限

集群内所有节点必须使用相同的 CUBE_JFS_MOUNT_PATH(以及 CUBE_JFS_ROOT)。 快照 catalog 记录的是挂载点下的绝对路径,挂载点不一致的节点无法解析其他节点创建的包。

缓存目录与容量建议 ​

CUBE_JFS_CACHE_DIR 中同时存放两类数据,目录结构见 JuiceFS 跨机存储架构:

  • 读缓存(raw/):从对象存储拉回的数据块,可随时按 LRU 淘汰,受 CUBE_JFS_CACHE_SIZE_MB 上限约束;
  • 写 staging(rawstaging/):--writeback 下尚未上传到对象存储的脏数据块,上传完成后即删除,不占用 CUBE_JFS_CACHE_SIZE_MB 配额。

CUBE_JFS_CACHE_SIZE_MB 默认 100 GiB,与性能测试所用配置一致。注意它是一个上限而不是预留空间,缓存按需增长:

  • 磁盘可用空间不足 100 GiB 时挂载不会失败,读缓存只会增长到实际可用的大小;

  • JuiceFS 默认 --free-space-ratio 0.1:当缓存所在文件系统剩余空间低于 10% 时,客户端按近似 LRU 的 2-random 算法主动淘汰读缓存块,直到剩余空间回到阈值以上。被淘汰的块下次读取时需重新从对象存储拉取,缓存命中率下降;

    请注意,该参数的 10% 是相对于该目录所在的数据盘总容量计算的,即 /data/cubelet/jfs-cache 缓存目录所在数据盘 /data 总容量为 1000 GiB,那么即使 /data/cubelet/jfs-cache 已使用 100 GiB,剩余空间也高于 10%,该兜底永远不会触发,读缓存的实际限制就是 CUBE_JFS_CACHE_SIZE_MB。

  • 若磁盘被缓存之外的数据(Cubelet 数据、镜像、staging 等)持续占满,淘汰只能暂时腾出空间:客户端会反复淘汰以守住阈值,读缓存被持续压缩,越来越多读请求退化为直读对象存储,性能明显下降;

  • 剩余空间低于阈值的一半(默认 5%)时,staging 写入同样受限:JuiceFS 会提前上传 staging 中的块以释放空间,新写入可能退化为同步写对象存储。必要时可通过 CUBE_JFS_MOUNT_OPTS 调整 --free-space-ratio(例如 0.2)。

  • staging 没有独立配额:若数据盘被写满,--writeback 下的新写入会直接失败,快照、暂停等操作可能报错,因此必须为 staging 和其他数据预留空间。

建议将缓存目录放在独立的快速数据盘上,CUBE_JFS_CACHE_SIZE_MB 不超过该盘可用空间的 70%–80%;数据盘较小(如 100–200 GiB)时按比例调小该值。读缓存的淘汰通常先由 CUBE_JFS_CACHE_SIZE_MB 触发;--free-space-ratio 更多是在缓存盘被其他数据(尤其是 staging 积压)持续填满时兜底,缓存盘越宽裕该兜底触发越晚,建议同时监控缓存盘整体使用率。

镜像分发 ​

目标节点默认从 Cube 自己的镜像仓库拉取 JuiceFS 客户端镜像 cube-sandbox-int.tencentcloudcr.com/cube-sandbox/juicefs:ce-v1.4.1。在 .env 里设置 MIRROR=cn 可改用 -cn 镜像,与其它组件镜像的规则一致。

如果是离线环境,可以提前 docker load 下载镜像,并通过修改配置文件中的 CUBE_JFS_IMAGE 指向本地镜像名。Kubernetes 部署中改为在 values 里设置 images.juicefs.repository / tag。

非必要无需升级 JuiceFS 镜像,应让所有节点使用同一个固定版本。

排障 ​

服务无法启动 ​

先查看 systemd 和容器日志:

bash
journalctl -u cube-sandbox-jfs.service -n 200 --no-pager
docker logs cube-sandbox-jfs
docker logs cube-sandbox-jfs-redis

常见原因包括:

  • CUBE_JFS_META_URL 或 CUBE_JFS_META_PASSWORD 未正确写入 .one-click.env,或者各节点使用的值不一致;
  • 节点没有 /dev/fuse,或 Docker 服务未启动;
  • 无法拉取 CUBE_JFS_IMAGE;
  • Redis、MinIO/S3 地址不可达,或 format 时使用的凭证失效。

容器运行但宿主机看不到挂载 ​

bash
findmnt -T /data/cubelet/storage/jfs
docker inspect cube-sandbox-jfs --format '{{.State.Status}}'

挂载脚本会为挂载点建立 self bind,并设置 rshared 传播。不要绕过 systemd 单元直接运行一个没有 bind-propagation=rshared 的容器,否则 FUSE 挂载可能只在容器命名空间内可见。

Cubelet 报 jfs storage is not configured ​

确认 [cow.jfs] enable = true,并检查 mount_path、root 和 cache_dir 是否与 .one-click.env 一致。修改后重启 Cubelet:

bash
sudo systemctl restart cube-sandbox-cubelet.service

remote_status 长时间停在 inprogress ​

使用 --writeback 时,文件关闭后仍可能有 block 留在本地 staging 区。Cubelet 会等相关 block 上传完成后才登记为 ready。检查 JuiceFS 容器日志、对象存储连通性、缓存盘空间和上传带宽;不要直接删除 cache 目录中的 staging 数据。

只能在源节点恢复 ​

依次确认:资源的 backend 是 jfs、remote_status 已为 ready、所有节点使用相同的元数据地址与 root,并且目标节点的 CPU/kernel 满足跨机恢复条件。host-mount 仍会把沙箱固定在源节点。

Kubernetes:首次安装时格式化 Job 失败 ​

元数据或对象存储凭证配置错误时,格式化 Job 会重试耗尽后失败,挂载 Pod 一直停在 Init:CrashLoopBackOff。修正凭证后,删除失败的 Job 再执行相同的 helm upgrade——Job 名称只在 spec 变化时才会变,所以它不会自行重试:

bash
kubectl -n cube-system delete job -l app.kubernetes.io/component=cube-juicefs-format

Kubernetes:不要删除 Chart 创建的 JuiceFS 元数据 Secret ​

元数据 Secret 保存的是 Chart 管理的 JuiceFS Redis 密码,Helm 升级时会通过 lookup 保留现有密码。删除该 Secret 后 Chart 会生成新的随机密码,而运行中的 Redis 仍在使用旧密码,之后新建的 JuiceFS Pod 全部认证失败。误删后,把 cubeJuiceFS.metadata.password 设为 Redis 实际使用的密码(可从 Redis Pod 内的 /etc/redis/redis-auth.conf 读取),临时设置 cubeJuiceFS.lifecycleChangeAck: true 重新升级,完成后移除确认键。