CubeSandbox使用12个常见陷阱：老手总结的血泪经验清单

CubeSandbox使用12个常见陷阱：老手总结的血泪经验清单

【免费下载链接】CubeSandboxInstant, Concurrent, Secure & Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox

CubeSandbox 是面向 AI Agent 的极速、安全、轻量沙箱服务（Sandbox），基于 RustVMM 与 KVM 实现硬件级隔离，单沙箱内存开销不到 5MB，可在 60ms 内交付可完整提供服务的隔离环境。很多新手第一次部署 CubeSandbox 沙箱时都踩过坑：装不上、模板建不出、挂载写不进、日志找不到。本文把官方故障排查文档里最高频的12 个常见陷阱整理成清单，每条都给出原因和解决方向，帮你少走弯路。

💡 排查问题的第一步：先打开 Web 控制台http://<控制节点IP>:12088确认节点状态和模板是否 READY，再按本文清单逐项对照。

部署安装阶段：6 个最常见的坑

陷阱 1：选了错系统——没有 XFS、glibc 太老

这是新手踩坑率最高的一条。CubeSandbox 依赖 XFS 的 reflink 能力做写时复制（CoW）快照，而 Ubuntu/Debian/WSL 默认是 ext4，一键部署的预检会直接拒绝并提示not XFS。

系统	建议
OpenCloudOS 9 / TencentOS 4	🏆 推荐，默认 XFS，开箱即用
Ubuntu 20.04/22.04/24.04	可用，但需手动挂 XFS 到/data/cubelet
Debian / WSL	可用，需同时确认 glibc ≥ 2.31

另外注意：官方二进制基于 Ubuntu 20.04 构建，系统 glibc 必须 ≥ 2.31，否则二进制根本跑不起来。细节见 quickstart.md 的"Supported Systems"部分。

陷阱 2：/data/cubelet 磁盘空间不足

沙箱镜像和可写层都落在/data/cubelet。最低要求50GB，如果要构建多个模板或自定义镜像，建议 200GB 以上。空间不足不仅安装失败，还会导致模板构建卡在UNPACKING/BUILDING_EXT4阶段，甚至报出mkfs.ext4之类的迷惑性错误。装之前先df -h看一眼。

陷阱 3：沙箱 CIDR 与宿主机内网重叠

一键部署的沙箱网络默认是192.168.0.0/18。如果你的办公网/内网也是192.168.x.x，沙箱 IP 就会和物理网络撞车，典型症状是模板创建失败，报context deadline exceeded。

排查时留意ip route输出：更具体的路由（如192.168.1.0/24）会优先于/18走物理网卡，Cubelet 探测沙箱端口时根本到不了真正的沙箱。解决方法是把 Cubelet 网络 CIDR 改成不重叠的网段（如172.31.64.0/18），完整步骤见 local-network-cidr-conflict.md。

陷阱 4：改 CIDR 前没清理残留的 cube-dev 和 TAP 设备

CubeSandbox 会创建大量持久化 TAP 设备（z192.168.x.x）和一个cube-dev虚拟接口。停止服务不会清理它们，重启机器也不够——systemd 会在开机时按旧配置重建。带着残留设备改 CIDR，预检会直接拒绝并给出"确定性重置"提示：先停服务、删cube-dev、清理z*TAP，再重新安装。不要图省事跳过冲突检查。

陷阱 5：bpffs 未挂载

Cubelet 的嵌入式网络运行时（eBPF 虚拟交换机）需要把程序和 map 固定到/sys/fs/bpf。在 WSL2 或精简 Linux 环境里这个文件系统默认不挂载，安装会卡在预检。先确认内核支持（grep -w bpf /proc/filesystems），再执行mount -t bpf bpf /sys/fs/bpf并写入/etc/fstab持久化。详见 deployment.md。

陷阱 6：Ubuntu 上 cgroup v2 的 cpu 控制器没开启

Ubuntu/Debian 云镜像默认不会把 cgroup v2 的cpu控制器委派给子 cgroup，且multipathd的实时线程会导致写入失败（Invalid argument）。后果是Cubelet 的 CPU 配额不生效——你限制了 4 核，实际可以超卖。如果你的宿主机是 Ubuntu/Debian 云镜像，记得检查/sys/fs/cgroup/cgroup.controllers里是否有cpu。

模板与运行时：4 个高频问题

陷阱 7：在嵌套虚拟化环境里直接生产使用

在 AWS EC2 这类嵌套虚拟化环境跑 CubeSandbox，MicroVM 可能因缺少指令集位（XSAVE 系列）直接 panic，且缺页时双份 VM-exit 会让 guest agent 慢到撑爆探活预算。

🏆 老手经验：普通云 VM 请走 PVM 部署路径（推荐方案，不需要裸金属或嵌套虚拟化），而不是直接上嵌套虚拟化。PVM 不支持 ARM64，ARM 裸金属请走 bare-metal-deploy.md。方案对比见 pvm-deploy.md。

陷阱 8：自定义镜像的 probe 配置对不上

自定义模板创建超时，最常见的两个根因：

1. 镜像没有启动 probe 指定的 HTTP 服务（如基于envd的镜像应是49983/health）——先在本地验证该端口通不通；
2. 宿主机在嵌套虚拟化环境（见上一条）。

构建自定义镜像前先读 bring-your-own-image.md。另外别急着调大超时：先确认节点健康、磁盘空间、网络正常，盲目加大超时只会掩盖真正故障的节点。超时参数说明见 service-management.md。

陷阱 9：host mount 报 Permission denied

沙箱里能看到挂载目录却写不进去，是预期内的 Linux 权限行为，不是 bug。host-mount只做映射，不改属主：目录保持宿主的 owner/group/mode，沙箱内默认以沙箱用户（如uid=1000）运行，宿主目录若属于其他 UID 就写不进去。

正确姿势按场景选：

场景	方案
Agent 只读代码	readOnly: true挂载（最安全默认）
需要写回宿主	宿主目录chown到沙箱 UID/GID
不能改宿主属主	用 POSIX ACL（setfacl -m u:1000:rwx）
管理性操作	user="root"运行，仅用于可信工作负载

完整案例见 host-mount-permissions.md，可运行示例在 examples/host-mount/。

陷阱 10：多节点集群里 hostPath 不在被调度到的节点上

Host mount 是节点本地的：hostPath必须存在于沙箱被调度到的那台 Cubelet 节点上。把本机目录直接当远程沙箱的工作区是行不通的。跨节点共享的四个正解：同步仓库到各节点同路径、放共享存储、把仓库打进模板镜像、或运行时拷入小文件。

运维排障：2 个"找不回来"的坑

陷阱 11：日志找错地方——业务日志不在 journalctl 里

这是最坑的新手问题：journalctl里只有进程启动/退出时的少量 stdout，所有业务日志（请求、调度、审计、VMM 创建）都直接写到/data/log/<模块>/下的文件。几个必须记住的位置：

想看什么	去哪看
Cubelet 业务日志	/data/log/Cubelet/Cubelet-req.log
CubeShim 日志（含 guest 内核启动日志）	/data/log/CubeShim/cube-shim-req.log
沙箱容器日志	在计算节点上执行cubecli logs <sandbox-id>
模板构建日志	cubecli logs --tpl <template-id>

两个老手经验：

• guest 内核日志不用专门找——CubeShim 接管了console=hvc0串口，内核printk全量转发进 CubeShim 日志，grep一下InstanceId即可；
• Cubelet 默认warn级别日志太安静，排查问题时记得开debug（动态配置热加载或:9966/debug/loglevel端点），但debug 只对之后新建的沙箱生效，别指望运行中的沙箱突然话多。

完整速查表见 component-log-locations.md。

陷阱 12：不做加固就把服务暴露到公网

CubeSandbox 自带硬件级隔离，但这不意味着 API、Web 控制台和沙箱端口可以裸奔。生产环境暴露前，务必按 network-hardening.md 做网络加固，参考 restrict-public-access.md 限制公共访问，敏感外呼走安全代理（凭据保险库，密钥不进沙箱）。

附：排查时的三个"别"

1. 别急着调超时——先查节点健康、磁盘、网络，超时掩盖不了坏节点；
2. 别只靠重启解决网络问题——cube-dev和 TAP 残留要手动清理；
3. 别用 debug 日志长期跑——日志量会涨一个数量级，排查完记得调回info/warn。

参考资料

• 快速开始：quickstart.md
• 部署故障排查索引：troubleshooting/index.md
• 部署问题清单：troubleshooting/deployment.md
• 模板问题清单：troubleshooting/templates.md
• 架构总览：architecture/overview.md
• Cubelet 网络默认配置：config.toml
• 沙箱日志指南：sandbox-logs.md

踩完这 12 个坑，你的 CubeSandbox 部署经验值大概能追平老手。有新踩的坑，欢迎按官方 故障排查贡献模板 补充进来。

【免费下载链接】CubeSandboxInstant, Concurrent, Secure & Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox