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。
# 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:
ONE_CLICK_ENABLE_JFS=1初始化 JuiceFS 文件系统,在控制节点执行如下命令:
sudo /usr/local/services/cubetoolbox/scripts/cube-jfs/init.sh然后挂载控制节点 JuiceFS 文件系统:
sudo /usr/local/services/cubetoolbox/scripts/cube-jfs/mount.sh计算节点初始化
编辑计算节点的配置文件,设置 ONE_CLICK_ENABLE_JFS=1。
ONE_CLICK_ENABLE_JFS=1执行如下命令在计算节点挂载 JuiceFS 文件系统:
sudo /usr/local/services/cubetoolbox/scripts/cube-jfs/mount.sh执行了 mount.sh 脚本后 JuiceFS 挂载将会开机自启。
在控制节点检查
所有节点挂载完成后,在控制节点执行脚本检查 JuiceFS 文件系统挂载状态:
sudo /usr/local/services/cubetoolbox/scripts/cube-jfs/check.sh应当输出类似如下内容:
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 迁移到其他对象存储
修改配置文件使用其他对象存储:
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 等地址。例如:
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 集群的初始化。
cp deploy/kubernetes/chart/runtime-values.example.yaml runtime-values.yaml默认配置不会启用 JuiceFS 跨机存储方案,需要手动修改 runtime-values.yaml 文件:
cubeJuiceFS:
enabled: true启用后 Chart 会额外部署:专供 JuiceFS 使用的独立 Redis、一个只在首次执行格式化的 Job,以及在每个计算节点挂载文件系统的 DaemonSet。
参考 Helm 部署章节中的 Helm 安装 章节,使用对应的多节点/腾讯云TKE/单节点集群的 Helm 安装命令进行安装。
# 多节点集群安装命令
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:
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 部署
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 以避免明文存储密钥:
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:
cubeJuiceFS:
enabled: true
storage:
type: s3
bucket: https://<bucket>-<appid>.cos.<region>.myqcloud.com/cube-jfs
existingSecret: cube-jfs-objectstorage.bucket 是传给 JuiceFS 的完整 --bucket 值,不只是桶名;路径风格的 S3 兼容存储要把桶名写进 URL,例如 http://minio.example.com:9000/cube-jfs。
请注意,目前 Cube 暂不支持从对象存储 A 平滑切换到对象存储 B,请在安装时指定需要使用的对象存储,或者参考 JuiceFS 官方的数据同步文档进行数据迁移。
使用 Redis 之外的元数据引擎
JuiceFS 的元数据存储非常重要,如果在生产环境部署,推荐使用 Redis 集群以降低数据丢失的风险。
只替换 Redis 时,先创建密码 Secret:
kubectl -n cube-system create secret generic cube-jfs-meta \
--from-literal=meta-password='<redis-password>'然后在 runtime-values.yaml 中增加 metadata:
cubeJuiceFS:
enabled: true
metadata:
url: redis://redis.example.com:6379/0
existingSecret: cube-jfs-meta
secretRevision: initial节点变更
新增节点
- 按正常流程安装并注册新的 Cube 计算节点;
- 在新节点的
.one-click.env写入ONE_CLICK_ENABLE_JFS=1; - 在新节点执行
sudo /usr/local/services/cubetoolbox/scripts/cube-jfs/mount.sh; - 回到控制节点执行
sudo /usr/local/services/cubetoolbox/scripts/cube-jfs/check.sh,确认新会话出现。
控制节点只需要在初始化的时候执行一次 /usr/local/services/cubetoolbox/scripts/cube-jfs/init.sh,后续新增节点不需要再次执行。
删除节点
先按节点相关操作隔离节点并清空沙箱。然后在待删除节点执行:
sudo /usr/local/services/cubetoolbox/scripts/cube-jfs/mount.sh unmount再在控制节点删除节点记录:
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_MB | 102400(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 和容器日志:
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 时使用的凭证失效。
容器运行但宿主机看不到挂载
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:
sudo systemctl restart cube-sandbox-cubelet.serviceremote_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 变化时才会变,所以它不会自行重试:
kubectl -n cube-system delete job -l app.kubernetes.io/component=cube-juicefs-formatKubernetes:不要删除 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 重新升级,完成后移除确认键。