diff --git a/docs/guide/self-build-deploy.md b/docs/guide/self-build-deploy.md
index 900ed6b9..536f3108 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,42 @@ 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
+# 1. Install xfsprogs (If `mkfs.xfs` is missing)
+# Ubuntu/Debian
+sudo apt update && sudo apt install xfsprogs -y
+# RHEL/CentOS
+# 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
+sudo dd if=/dev/zero of=/var/lib/cube-sandbox/xfs-loopfile bs=1G count=0 seek=20 status=progress
+
+# 3. Format the loopback file as XFS
+sudo mkfs.xfs /var/lib/cube-sandbox/xfs-loopfile
+
+# 4. Create the mount point and mount
+sudo mkdir -p /data/cubelet
+sudo mount -o loop /var/lib/cube-sandbox/xfs-loopfile /data/cubelet
+
+# 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.
+
+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..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` | 安装脚本依赖 |
 
@@ -123,6 +124,39 @@ CUBE_SANDBOX_NODE_IP=<你的节点IP>
 
 ### 2.3 执行安装
 
+#### （可选）
+Cube Sandbox 要求 /data/cubelet 所在的文件系统必须是 XFS。如果当前并非XFS文件系统，可以考虑使用现有文件系统上创建一个大文件并格式化为 XFS，再通过 loop 方式挂载。这种做法适合测试或虚拟机环境。
+
+```bash
+# 1. 安装 xfsprogs（如果没有 mkfs.xfs）
+# Ubuntu/Debian
+sudo apt update && sudo apt install xfsprogs -y
+# RHEL/CentOS
+# sudo yum update && sudo yum 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
+
+# 3. 格式化为 XFS
+sudo mkfs.xfs /var/lib/cube-sandbox/xfs-loopfile
+
+# 4. 创建挂载点并挂载
+sudo mkdir -p /data/cubelet
+sudo mount -o loop /var/lib/cube-sandbox/xfs-loopfile /data/cubelet
+
+# 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 支持）的文件系统上，并且文件内需要有足够的空闲空间供沙箱使用。你可以自行通过 `seek` 和 `count` 的调整以适配当前的硬件条件。
+
+通过运行以下指令以确保运行在`XFS` 文件系统。
+```bash
+df -T /data/cubelet
+# 类型应为 xfs
+```
+
 #### 控制节点
 
 ```bash