From 88b13febca63a3179dedd365d0d02c232aa26d8d Mon Sep 17 00:00:00 2001 From: Dafeigy <1070642765@qq.com> Date: Thu, 14 May 2026 16:36:31 +0800 Subject: [PATCH 1/4] docs: add xfs instructions for self-build-deployment Signed-off-by: Dafeigy <1070642765@qq.com> --- docs/guide/self-build-deploy.md | 32 ++++++++++++++++++++++++++++++ docs/zh/guide/self-build-deploy.md | 26 ++++++++++++++++++++++++ 2 files changed, 58 insertions(+) diff --git a/docs/guide/self-build-deploy.md b/docs/guide/self-build-deploy.md index 900ed6b9..340e867f 100644 --- a/docs/guide/self-build-deploy.md +++ b/docs/guide/self-build-deploy.md @@ -27,6 +27,7 @@ After deployment, you will have a fully functional Cube Sandbox instance with: | Linux | OpenCloudOS 9 (recommended) or Ubuntu 22.04+ | | Docker | Must be installed and running | | root access | `install.sh` requires root privileges | +| FileSystem | XFS | | DNS routing | `systemd-resolved` (preferred) or `NetworkManager + dnsmasq` | | `tar`, `rg`, `ss` | Required by install script | @@ -123,6 +124,37 @@ See [Configuration Reference](#configuration-reference) below for a full list of ### 2.3 Install +#### (Optional) Create XFS, and mount it via loop device +Cube Sandbox requires the /data/cubelet directory to reside on an XFS filesystem. + +Create a large file, format it as XFS, and mount it via loop device. +This works well for testing, development, or virtualized environments. +```bash +# Create a 20 GB sparse file (adjust size as needed) +sudo dd if=/dev/zero of=/xfs-loopfile bs=1G count=0 seek=20 status=progress +# Or use fallocate for speed: sudo fallocate -l 20G /xfs-loopfile + +# Format as XFS +sudo mkfs.xfs /xfs-loopfile + +# Mount point +sudo mkdir -p /data/cubelet + +# Mount via loop +sudo mount -o loop /xfs-loopfile /data/cubelet + +# Persistent mount (add to /etc/fstab) +echo '/xfs-loopfile /data/cubelet xfs loop 0 2' | sudo tee -a /etc/fstab +``` +> Note: The loop file must be on a filesystem that supports sparse files (ext4 does), and you’ll need enough free space inside the file for the sandbox. Adjust the count/seek parameter to your required capacity. + +To make sure that you are running under `xfs`, run the following command: +```bash +df -T /data/cubelet +# type should be xfs +``` + + #### Control Node ```bash diff --git a/docs/zh/guide/self-build-deploy.md b/docs/zh/guide/self-build-deploy.md index 96639ce6..1762af64 100644 --- a/docs/zh/guide/self-build-deploy.md +++ b/docs/zh/guide/self-build-deploy.md @@ -123,6 +123,32 @@ CUBE_SANDBOX_NODE_IP=<你的节点IP> ### 2.3 执行安装 +#### （可选） +Cube Sandbox 要求 /data/cubelet 所在的文件系统必须是 XFS。如果当前并非XFS文件系统，可以考虑使用现有文件系统上创建一个大文件并格式化为 XFS，再通过 loop 方式挂载。这种做法适合测试或虚拟机环境。 + +```bash +# 1. 创建一个 20G 的空文件（大小按需调整） +sudo dd if=/dev/zero of=/xfs-loopfile bs=1G count=0 seek=20 status=progress +# 或者用 fallocate 更快：sudo fallocate -l 20G /xfs-loopfile + +# 2. 把这个文件格式化为 XFS +sudo mkfs.xfs /xfs-loopfile + +# 3. 创建挂载点并挂载 +sudo mkdir -p /data/cubelet +sudo mount -o loop /xfs-loopfile /data/cubelet + +# 4. 设置开机自动挂载 +echo '/xfs-loopfile /data/cubelet xfs loop 0 2' | sudo tee -a /etc/fstab +``` +> 注意：文件实际放在 / (ext4) 上，但挂载到 /data/cubelet 后，Cube 看到的就是 XFS 了。可以自行通过 `seed` 和 `count` 的调整以适配当前的硬件条件。 + +通过运行以下指令以确保运行在`XFS` 文件系统。 +```bash +df -T /data/cubelet +# 类型应为 xfs +``` + #### 控制节点 ```bash From 3a4be44b86033750ef0a54c90f073a39d01a969e Mon Sep 17 00:00:00 2001 From: Dafeigy <1070642765@qq.com> Date: Sat, 16 May 2026 11:52:11 +0800 Subject: [PATCH 2/4] docs: add XFS loopback workaround for non-XFS root filesystem Signed-off-by: Dafeigy <1070642765@qq.com> --- docs/guide/self-build-deploy.md | 27 ++++++++++++++++----------- docs/zh/guide/self-build-deploy.md | 27 +++++++++++++++++---------- 2 files changed, 33 insertions(+), 21 deletions(-) diff --git a/docs/guide/self-build-deploy.md b/docs/guide/self-build-deploy.md index 340e867f..93e8ae49 100644 --- a/docs/guide/self-build-deploy.md +++ b/docs/guide/self-build-deploy.md @@ -130,21 +130,26 @@ Cube Sandbox requires the /data/cubelet directory to reside on an XFS filesystem Create a large file, format it as XFS, and mount it via loop device. This works well for testing, development, or virtualized environments. ```bash -# Create a 20 GB sparse file (adjust size as needed) -sudo dd if=/dev/zero of=/xfs-loopfile bs=1G count=0 seek=20 status=progress -# Or use fallocate for speed: sudo fallocate -l 20G /xfs-loopfile +# 1. Install xfsprogs（If `mkfs.xfs` is missing） +# Ubuntu/Debian +sudo apt update && sudo apt install xfsprogs -y +# RHEL/CentOS +# sudo yum update && install xfsprogs -y -# Format as XFS -sudo mkfs.xfs /xfs-loopfile +# 2. Create a standard directory and a sparse loopback file (adjust size as needed, e.g., 20G) +sudo mkdir -p /var/lib/cube-sandbox +sudo dd if=/dev/zero of=/var/lib/cube-sandbox/xfs-loopfile bs=1G count=0 seek=20 status=progress -# Mount point -sudo mkdir -p /data/cubelet +# 3. Format the loopback file as XFS +sudo mkfs.xfs /var/lib/cube-sandbox/xfs-loopfile -# Mount via loop -sudo mount -o loop /xfs-loopfile /data/cubelet +# 4. Create the mount point and mount +sudo mkdir -p /data/cubelet +sudo mount -o loop /var/lib/cube-sandbox/xfs-loopfile /data/cubelet -# Persistent mount (add to /etc/fstab) -echo '/xfs-loopfile /data/cubelet xfs loop 0 2' | sudo tee -a /etc/fstab +# 5. Persist the mount in /etc/fstab +grep -q '/var/lib/cube-sandbox/xfs-loopfile' /etc/fstab || \ + echo '/var/lib/cube-sandbox/xfs-loopfile /data/cubelet xfs loop 0 2' | sudo tee -a /etc/fstab ``` > Note: The loop file must be on a filesystem that supports sparse files (ext4 does), and you’ll need enough free space inside the file for the sandbox. Adjust the count/seek parameter to your required capacity. diff --git a/docs/zh/guide/self-build-deploy.md b/docs/zh/guide/self-build-deploy.md index 1762af64..ebb9e2cc 100644 --- a/docs/zh/guide/self-build-deploy.md +++ b/docs/zh/guide/self-build-deploy.md @@ -127,21 +127,28 @@ CUBE_SANDBOX_NODE_IP=<你的节点IP> Cube Sandbox 要求 /data/cubelet 所在的文件系统必须是 XFS。如果当前并非XFS文件系统，可以考虑使用现有文件系统上创建一个大文件并格式化为 XFS，再通过 loop 方式挂载。这种做法适合测试或虚拟机环境。 ```bash -# 1. 创建一个 20G 的空文件（大小按需调整） -sudo dd if=/dev/zero of=/xfs-loopfile bs=1G count=0 seek=20 status=progress -# 或者用 fallocate 更快：sudo fallocate -l 20G /xfs-loopfile +# 1. 安装 xfsprogs（如果没有 mkfs.xfs） +# Ubuntu/Debian +sudo apt update && sudo apt install xfsprogs -y +# RHEL/CentOS +# sudo yum update && install xfsprogs -y + +# 2. 创建标准路径（/var/lib/cube-sandbox）并生成稀疏文件（示例 20G） +sudo mkdir -p /var/lib/cube-sandbox +sudo dd if=/dev/zero of=/var/lib/cube-sandbox/xfs-loopfile bs=1G count=0 seek=20 status=progress -# 2. 把这个文件格式化为 XFS -sudo mkfs.xfs /xfs-loopfile +# 3. 格式化为 XFS +sudo mkfs.xfs /var/lib/cube-sandbox/xfs-loopfile -# 3. 创建挂载点并挂载 +# 4. 创建挂载点并挂载 sudo mkdir -p /data/cubelet -sudo mount -o loop /xfs-loopfile /data/cubelet +sudo mount -o loop /var/lib/cube-sandbox/xfs-loopfile /data/cubelet -# 4. 设置开机自动挂载 -echo '/xfs-loopfile /data/cubelet xfs loop 0 2' | sudo tee -a /etc/fstab +# 5. 安全写入 /etc/fstab（避免重复条目） +grep -q '/var/lib/cube-sandbox/xfs-loopfile' /etc/fstab || \ + echo '/var/lib/cube-sandbox/xfs-loopfile /data/cubelet xfs loop 0 2' | sudo tee -a /etc/fstab ``` -> 注意：文件实际放在 / (ext4) 上，但挂载到 /data/cubelet 后，Cube 看到的就是 XFS 了。可以自行通过 `seed` 和 `count` 的调整以适配当前的硬件条件。 +> 注意：循环文件必须位于支持稀疏文件（ext4 支持）的文件系统上，并且文件内需要有足够的空闲空间供沙箱使用。你可以自行通过 `seed` 和 `count` 的调整以适配当前的硬件条件。 通过运行以下指令以确保运行在`XFS` 文件系统。 ```bash From 595ddeafb647e8bba4c15d62070fabb1dabb9507 Mon Sep 17 00:00:00 2001 From: Dafeigy <1070642765@qq.com> Date: Sun, 17 May 2026 07:40:29 +0800 Subject: [PATCH 3/4] chore: fix issues based on cubebot review Signed-off-by: Dafeigy <1070642765@qq.com> --- docs/guide/self-build-deploy.md | 2 +- docs/zh/guide/self-build-deploy.md | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/guide/self-build-deploy.md b/docs/guide/self-build-deploy.md index 93e8ae49..8429fed1 100644 --- a/docs/guide/self-build-deploy.md +++ b/docs/guide/self-build-deploy.md @@ -134,7 +134,7 @@ This works well for testing, development, or virtualized environments. # Ubuntu/Debian sudo apt update && sudo apt install xfsprogs -y # RHEL/CentOS -# sudo yum update && install xfsprogs -y +# sudo yum update && sudo yum install xfsprogs -y # 2. Create a standard directory and a sparse loopback file (adjust size as needed, e.g., 20G) sudo mkdir -p /var/lib/cube-sandbox diff --git a/docs/zh/guide/self-build-deploy.md b/docs/zh/guide/self-build-deploy.md index ebb9e2cc..d871e0bb 100644 --- a/docs/zh/guide/self-build-deploy.md +++ b/docs/zh/guide/self-build-deploy.md @@ -27,6 +27,7 @@ | Linux | 推荐 Ubuntu 22.04+ | | Docker | 已安装并正常运行 | | root 权限 | `install.sh` 需要 root 执行 | +| 文件系统 | XFS | | DNS 路由 | `systemd-resolved`（推荐）或 `NetworkManager + dnsmasq` | | `tar`、`rg`、`ss` | 安装脚本依赖 | @@ -131,7 +132,7 @@ Cube Sandbox 要求 /data/cubelet 所在的文件系统必须是 XFS。如果当 # Ubuntu/Debian sudo apt update && sudo apt install xfsprogs -y # RHEL/CentOS -# sudo yum update && install xfsprogs -y +# sudo yum update && sudo yum install xfsprogs -y # 2. 创建标准路径（/var/lib/cube-sandbox）并生成稀疏文件（示例 20G） sudo mkdir -p /var/lib/cube-sandbox @@ -148,7 +149,7 @@ sudo mount -o loop /var/lib/cube-sandbox/xfs-loopfile /data/cubelet grep -q '/var/lib/cube-sandbox/xfs-loopfile' /etc/fstab || \ echo '/var/lib/cube-sandbox/xfs-loopfile /data/cubelet xfs loop 0 2' | sudo tee -a /etc/fstab ``` -> 注意：循环文件必须位于支持稀疏文件（ext4 支持）的文件系统上，并且文件内需要有足够的空闲空间供沙箱使用。你可以自行通过 `seed` 和 `count` 的调整以适配当前的硬件条件。 +> 注意：循环文件必须位于支持稀疏文件（ext4 支持）的文件系统上，并且文件内需要有足够的空闲空间供沙箱使用。你可以自行通过 `seek` 和 `count` 的调整以适配当前的硬件条件。 通过运行以下指令以确保运行在`XFS` 文件系统。 ```bash From d9135f502b777cd7d986162f5e4cd971033ac4e0 Mon Sep 17 00:00:00 2001 From: NUL4i <55502809+Dafeigy@users.noreply.github.com> Date: Mon, 18 May 2026 11:52:24 +0800 Subject: [PATCH 4/4] Fix typo in self-build-deploy guide Signed-off-by: Dafeigy <1070642765@qq.com> --- docs/guide/self-build-deploy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/self-build-deploy.md b/docs/guide/self-build-deploy.md index 8429fed1..536f3108 100644 --- a/docs/guide/self-build-deploy.md +++ b/docs/guide/self-build-deploy.md @@ -130,7 +130,7 @@ Cube Sandbox requires the /data/cubelet directory to reside on an XFS filesystem Create a large file, format it as XFS, and mount it via loop device. This works well for testing, development, or virtualized environments. ```bash -# 1. Install xfsprogs（If `mkfs.xfs` is missing） +# 1. Install xfsprogs (If `mkfs.xfs` is missing) # Ubuntu/Debian sudo apt update && sudo apt install xfsprogs -y # RHEL/CentOS