CubeSandbox常见报错速查10个高频错误的原因与快速修复【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandboxCubeSandbox 是一个面向 AI Agent 的轻量级安全沙箱服务基于 RustVMM 与 KVM 构建可以在 60ms 内创建硬件隔离的沙箱实例并兼容 E2B SDK。部署和使用过程中新手最常遇到的问题集中在一键安装预检失败、模板创建超时、网络 CIDR 冲突、宿主机挂载权限不足这几类。本文把社区最高频的 10 个报错整理成速查表每个错误都给出报错现象 → 根本原因 → 修复步骤帮你快速定位并解决问题。 官方排查文档入口docs/guide/troubleshooting/index.md报错速查总表#典型报错信息所属阶段速查章节1not XFS预检拒绝安装错误 12context deadline exceeded模板创建模板创建错误 23cube-dev残留、CIDR 冲突拒绝安装/重装错误 34bpffs is not mounted安装错误 45卡在UNPACKING/BUILDING_EXT4模板构建错误 56探针超时49983/health自定义镜像错误 67RPC deadline构建阶段模板构建错误 78Permission deniedhost-mount运行时错误 89401 UnauthorizedAPI 调用错误 910cgroup v2cpu控制器未启用部署错误 101. 预检报错not XFS/data/cubelet 必须是 XFS现象在一键安装预检阶段被拒绝提示/data/cubelet不是 XFS 文件系统。原因CubeSandbox 的可写层存放在/data/cubelet快照克隆依赖 XFS 的 reflinkCoW能力。Ubuntu / Debian / WSL 等发行版默认根分区是 ext4因此会被预检拦截。修复生产环境挂载一块专用的 XFS 数据盘建议 100–300 GiB到/data/cubelet快速体验创建一个 loopback 的.img文件格式化为 XFS 后挂载到/data/cubelet全新装机建议直接使用 OpenCloudOS 9 等 RHEL 系系统默认 XFS。 详见docs/guide/troubleshooting/deployment.md、docs/guide/quickstart.md2. 模板创建超时context deadline exceeded现象cubemastercli创建模板时失败template tpl-xx creation failed: context deadline exceeded原因一键部署默认沙箱网段为192.168.0.0/18。如果你的物理内网也使用192.168.1.x沙箱 IP 可能与真实内网重叠——访问沙箱地址时流量走了物理网卡而不是沙箱网络cube-dev导致端口探测一直失败、最终超时。在 Cubelet 请求日志/data/log/Cubelet/Cubelet-req.log中可看到PortBindingFailed记录。修复停止服务sudo systemctl stop cube-sandbox-*.target修改 Cubelet/config/config.toml 中的cidr为不与内网重叠的网段如172.31.64.0/18删除旧的cube-dev接口和z*TAP 设备再重启服务 完整命令与日志示例docs/guide/troubleshooting/local-network-cidr-conflict.mdCubeSandbox 网络管控点与流量路径设计图3. 更换 CIDR 时被cube-dev残留拒绝现象更换CUBE_SANDBOX_NETWORK_CIDR重装时预检直接拒绝CUBE_SANDBOX_NETWORK_CIDR 192.168.0.0/17 overlaps an existing cube-dev network (192.168.0.0/18)原因停止 CubeSandbox不会清理cube-dev接口和持久化的z*TAP 设备它们会一直残留。而且重启机器也没用——systemd 服务自启动时会按config.toml重建旧网络。修复确定性重置必须手动执行sudo systemctl stop cube-sandbox-*.target sudo ip link delete cube-dev 2/dev/null || true ip tuntap show | awk -F: /^z[0-9]\./{print $1} \ | xargs -r -n1 -I{} sudo ip tuntap del dev {} mode tap之后再以新 CIDR 运行安装脚本。如果保持原 CIDR 不变则会自动复用现有cube-dev无需任何操作。 详见docs/guide/troubleshooting/local-network-cidr-conflict.md4.bpffs is not mounted现象安装器在修改系统之前直接停止提示/sys/fs/bpf未挂载为bpf文件系统。原因Cubelet 的嵌入式网络运行时eBPF 程序与 map需要/sys/fs/bpfbpffs来 pin 资源。WSL2 和精简版 Linux 环境中通常默认不挂载。修复grep -w bpf /proc/filesystems # 先确认内核支持 bpf mkdir -p /sys/fs/bpf mount -t bpf bpf /sys/fs/bpf若需重启后持久化在/etc/fstab中追加bpf /sys/fs/bpf bpf defaults 0 0 详见docs/guide/troubleshooting/deployment.md5. 模板构建卡死磁盘空间不足现象模板构建长时间停在UNPACKING/BUILDING_EXT4阶段或出现mkfs.ext4报错如 Ext2 inode is not a directory、目录块校验和错误。原因构建模板需要解包 OCI 镜像并写入 ext4 镜像会消耗大量临时磁盘空间。当/tmp、/data/cubelet或/usr/local/services/cubetoolbox/所在分区剩余空间不足时就会卡死或写坏文件系统。修复检查并清理上述分区的磁盘空间df -h保证/data/cubelet至少有 50 GB 可用多模板构建建议 200 GB 以上。 详见docs/guide/troubleshooting/templates.md6. 自定义 image 模板一直探针超时现象tpl create-from-image反复超时最终VsockServerReady或探针预算耗尽。原因两个最常见根因自定义镜像没有启动探针期望的 HTTP 服务——envd类镜像通常要求49983/health可访问但你的镜像里并没有这个服务宿主机是嵌套虚拟化环境如 AWS EC2缺少部分指令集位XSAVE 族会令 MicroVM 触发 panic页错误的 VM-exit 翻倍也会拖慢 Guest 内 agent导致超时。修复先在本地验证镜像中配置的--probe/--probe-path服务确实可达需要envd时按官方自带镜像教程docs/guide/tutorials/准备镜像嵌套虚拟化环境请改用 PVM 部署模式。 详见docs/guide/troubleshooting/templates.md7. 模板构建RPC deadline超时现象构建任务在某阶段报 RPC 超时报错。原因不同阶段受不同超时参数约束——DISTRIBUTING阶段受create_image_timeout_insec限制CREATING_TEMPLATE阶段受app_snapshot_timeout_insec限制。盲目调大超时可能掩盖真正的故障节点。修复先检查节点健康状态、剩余磁盘、网络连通性和 Cubelet 日志确认只是正常偏慢后再调整 CubeMaster 的cubelet_conf中对应超时值并重启 CubeMaster。 详见docs/guide/troubleshooting/templates.md、docs/guide/service-management.md8. 宿主机挂载读写失败Permission denied现象沙箱能看到 host-mount 目录但写入报错/bin/bash: line 1: /mnt/rw/1.txt: Permission denied原因metadata[host-mount]只是把宿主机路径映射进沙箱不会复制或改写属主。readOnly: false表示以读写方式挂载但 Linux 权限依然生效——宿主机目录的 UID/GID 与沙箱内执行命令的用户不一致时就会只读可读、写入被拒。修复任选其一源码仓库类场景改为只读挂载最安全的默认选择为沙箱用户创建专用宿主机目录并对齐属主sudo chown 1000:1000 /tmp/rw属主不能动时用 POSIX ACL 授权sudo setfacl -m u:1000:rwx /tmp/rw受信任的管理类操作可userroot执行写入谨慎使用会在宿主机产生 root 属主文件。⚠️ 多节点集群中hostPath必须存在于沙箱实际被调度的那个节点上。 详见docs/guide/troubleshooting/host-mount-permissions.md、examples/host-mount/9. API 调用返回401 Unauthorized现象启用认证后SDK / 直接 HTTP 调用被拒绝。原因CubeAPI 配置了--auth-callback-url后每个请求的凭据头Authorization: Bearer优先于X-API-Key都会被转发给你的回调服务回调返回 200 才放行任何非 200 状态都会变成 401。常见原因客户端根本没带凭据E2B SDK 需要设置E2B_API_KEY环境变量回调服务本身故障或回调里只校验了路径没校验 HTTP 方法同一 path 可能挂 GET/POST/DELETE/PATCH 多个动作。修复SDK 场景export E2B_API_KEYyour-actual-api-key裸 HTTP 场景带上Authorization: Bearer key或X-API-Key: key请求头检查回调服务返回码并确保同时校验X-Request-Path与X-Request-Method。 详见docs/guide/authentication.md10. cgroup v2cpu控制器未启用资源配额不生效现象Ubuntu / Debian 云镜像上 Cubelet 的 CPU 配额不生效日志中写cpu报Invalid argument。原因这类发行版默认不把 cgroup v2 的cpu控制器下放给子 cgroup且multipathd的实时线程会进一步导致写入失败。修复按发行版标准做法为相关 cgroup 委托cpu控制器如/etc/systemd/system/xxx.service.d/中设置Delegatecpu并在父 cgroup 的cgroup.subtree_control中写入cpu具体复现与修复步骤见官方部署排查文档中引用的社区 issue 记录。 详见docs/guide/troubleshooting/deployment.md附录排查报错时日志在哪里看遇到上面没列到的错误第一反应应该是看日志。一键部署下各组件的业务日志直接落在文件里不在 journalctl 中组件日志路径CubeAPI/data/log/CubeAPI/cube-api-YYYY-MM-DD.logCubeMaster/data/log/CubeMaster/cubemaster-req.logCubelet/data/log/Cubelet/Cubelet-req.logCubeShim含 Guest 内核启动日志/data/log/CubeShim/cube-shim-req.logHypervisor (VMM)/data/log/CubeVmm/vmm.log沙箱 / 模板日志用cubecli logs sandbox-id需在计算节点上执行Cubelet 默认日志级别是warn排障时可通过动态配置dynamicconf/conf.yaml加log_level: debug约 10 秒热加载生效排完记得改回Guest 内核启动日志就在 CubeShim 日志里按InstanceId过滤即可。 完整速查表与命令docs/guide/troubleshooting/component-log-locations.md最后建议排障顺序遵循先看现象哪个阶段、哪条日志→ 对照本文速查表 → 查对应 troubleshooting 文档 → 再调超时/参数避免用加大超时来掩盖真实的节点或磁盘故障。【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CubeSandbox常见报错速查：10个高频错误的原因与快速修复
CubeSandbox常见报错速查10个高频错误的原因与快速修复【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandboxCubeSandbox 是一个面向 AI Agent 的轻量级安全沙箱服务基于 RustVMM 与 KVM 构建可以在 60ms 内创建硬件隔离的沙箱实例并兼容 E2B SDK。部署和使用过程中新手最常遇到的问题集中在一键安装预检失败、模板创建超时、网络 CIDR 冲突、宿主机挂载权限不足这几类。本文把社区最高频的 10 个报错整理成速查表每个错误都给出报错现象 → 根本原因 → 修复步骤帮你快速定位并解决问题。 官方排查文档入口docs/guide/troubleshooting/index.md报错速查总表#典型报错信息所属阶段速查章节1not XFS预检拒绝安装错误 12context deadline exceeded模板创建模板创建错误 23cube-dev残留、CIDR 冲突拒绝安装/重装错误 34bpffs is not mounted安装错误 45卡在UNPACKING/BUILDING_EXT4模板构建错误 56探针超时49983/health自定义镜像错误 67RPC deadline构建阶段模板构建错误 78Permission deniedhost-mount运行时错误 89401 UnauthorizedAPI 调用错误 910cgroup v2cpu控制器未启用部署错误 101. 预检报错not XFS/data/cubelet 必须是 XFS现象在一键安装预检阶段被拒绝提示/data/cubelet不是 XFS 文件系统。原因CubeSandbox 的可写层存放在/data/cubelet快照克隆依赖 XFS 的 reflinkCoW能力。Ubuntu / Debian / WSL 等发行版默认根分区是 ext4因此会被预检拦截。修复生产环境挂载一块专用的 XFS 数据盘建议 100–300 GiB到/data/cubelet快速体验创建一个 loopback 的.img文件格式化为 XFS 后挂载到/data/cubelet全新装机建议直接使用 OpenCloudOS 9 等 RHEL 系系统默认 XFS。 详见docs/guide/troubleshooting/deployment.md、docs/guide/quickstart.md2. 模板创建超时context deadline exceeded现象cubemastercli创建模板时失败template tpl-xx creation failed: context deadline exceeded原因一键部署默认沙箱网段为192.168.0.0/18。如果你的物理内网也使用192.168.1.x沙箱 IP 可能与真实内网重叠——访问沙箱地址时流量走了物理网卡而不是沙箱网络cube-dev导致端口探测一直失败、最终超时。在 Cubelet 请求日志/data/log/Cubelet/Cubelet-req.log中可看到PortBindingFailed记录。修复停止服务sudo systemctl stop cube-sandbox-*.target修改 Cubelet/config/config.toml 中的cidr为不与内网重叠的网段如172.31.64.0/18删除旧的cube-dev接口和z*TAP 设备再重启服务 完整命令与日志示例docs/guide/troubleshooting/local-network-cidr-conflict.mdCubeSandbox 网络管控点与流量路径设计图3. 更换 CIDR 时被cube-dev残留拒绝现象更换CUBE_SANDBOX_NETWORK_CIDR重装时预检直接拒绝CUBE_SANDBOX_NETWORK_CIDR 192.168.0.0/17 overlaps an existing cube-dev network (192.168.0.0/18)原因停止 CubeSandbox不会清理cube-dev接口和持久化的z*TAP 设备它们会一直残留。而且重启机器也没用——systemd 服务自启动时会按config.toml重建旧网络。修复确定性重置必须手动执行sudo systemctl stop cube-sandbox-*.target sudo ip link delete cube-dev 2/dev/null || true ip tuntap show | awk -F: /^z[0-9]\./{print $1} \ | xargs -r -n1 -I{} sudo ip tuntap del dev {} mode tap之后再以新 CIDR 运行安装脚本。如果保持原 CIDR 不变则会自动复用现有cube-dev无需任何操作。 详见docs/guide/troubleshooting/local-network-cidr-conflict.md4.bpffs is not mounted现象安装器在修改系统之前直接停止提示/sys/fs/bpf未挂载为bpf文件系统。原因Cubelet 的嵌入式网络运行时eBPF 程序与 map需要/sys/fs/bpfbpffs来 pin 资源。WSL2 和精简版 Linux 环境中通常默认不挂载。修复grep -w bpf /proc/filesystems # 先确认内核支持 bpf mkdir -p /sys/fs/bpf mount -t bpf bpf /sys/fs/bpf若需重启后持久化在/etc/fstab中追加bpf /sys/fs/bpf bpf defaults 0 0 详见docs/guide/troubleshooting/deployment.md5. 模板构建卡死磁盘空间不足现象模板构建长时间停在UNPACKING/BUILDING_EXT4阶段或出现mkfs.ext4报错如 Ext2 inode is not a directory、目录块校验和错误。原因构建模板需要解包 OCI 镜像并写入 ext4 镜像会消耗大量临时磁盘空间。当/tmp、/data/cubelet或/usr/local/services/cubetoolbox/所在分区剩余空间不足时就会卡死或写坏文件系统。修复检查并清理上述分区的磁盘空间df -h保证/data/cubelet至少有 50 GB 可用多模板构建建议 200 GB 以上。 详见docs/guide/troubleshooting/templates.md6. 自定义 image 模板一直探针超时现象tpl create-from-image反复超时最终VsockServerReady或探针预算耗尽。原因两个最常见根因自定义镜像没有启动探针期望的 HTTP 服务——envd类镜像通常要求49983/health可访问但你的镜像里并没有这个服务宿主机是嵌套虚拟化环境如 AWS EC2缺少部分指令集位XSAVE 族会令 MicroVM 触发 panic页错误的 VM-exit 翻倍也会拖慢 Guest 内 agent导致超时。修复先在本地验证镜像中配置的--probe/--probe-path服务确实可达需要envd时按官方自带镜像教程docs/guide/tutorials/准备镜像嵌套虚拟化环境请改用 PVM 部署模式。 详见docs/guide/troubleshooting/templates.md7. 模板构建RPC deadline超时现象构建任务在某阶段报 RPC 超时报错。原因不同阶段受不同超时参数约束——DISTRIBUTING阶段受create_image_timeout_insec限制CREATING_TEMPLATE阶段受app_snapshot_timeout_insec限制。盲目调大超时可能掩盖真正的故障节点。修复先检查节点健康状态、剩余磁盘、网络连通性和 Cubelet 日志确认只是正常偏慢后再调整 CubeMaster 的cubelet_conf中对应超时值并重启 CubeMaster。 详见docs/guide/troubleshooting/templates.md、docs/guide/service-management.md8. 宿主机挂载读写失败Permission denied现象沙箱能看到 host-mount 目录但写入报错/bin/bash: line 1: /mnt/rw/1.txt: Permission denied原因metadata[host-mount]只是把宿主机路径映射进沙箱不会复制或改写属主。readOnly: false表示以读写方式挂载但 Linux 权限依然生效——宿主机目录的 UID/GID 与沙箱内执行命令的用户不一致时就会只读可读、写入被拒。修复任选其一源码仓库类场景改为只读挂载最安全的默认选择为沙箱用户创建专用宿主机目录并对齐属主sudo chown 1000:1000 /tmp/rw属主不能动时用 POSIX ACL 授权sudo setfacl -m u:1000:rwx /tmp/rw受信任的管理类操作可userroot执行写入谨慎使用会在宿主机产生 root 属主文件。⚠️ 多节点集群中hostPath必须存在于沙箱实际被调度的那个节点上。 详见docs/guide/troubleshooting/host-mount-permissions.md、examples/host-mount/9. API 调用返回401 Unauthorized现象启用认证后SDK / 直接 HTTP 调用被拒绝。原因CubeAPI 配置了--auth-callback-url后每个请求的凭据头Authorization: Bearer优先于X-API-Key都会被转发给你的回调服务回调返回 200 才放行任何非 200 状态都会变成 401。常见原因客户端根本没带凭据E2B SDK 需要设置E2B_API_KEY环境变量回调服务本身故障或回调里只校验了路径没校验 HTTP 方法同一 path 可能挂 GET/POST/DELETE/PATCH 多个动作。修复SDK 场景export E2B_API_KEYyour-actual-api-key裸 HTTP 场景带上Authorization: Bearer key或X-API-Key: key请求头检查回调服务返回码并确保同时校验X-Request-Path与X-Request-Method。 详见docs/guide/authentication.md10. cgroup v2cpu控制器未启用资源配额不生效现象Ubuntu / Debian 云镜像上 Cubelet 的 CPU 配额不生效日志中写cpu报Invalid argument。原因这类发行版默认不把 cgroup v2 的cpu控制器下放给子 cgroup且multipathd的实时线程会进一步导致写入失败。修复按发行版标准做法为相关 cgroup 委托cpu控制器如/etc/systemd/system/xxx.service.d/中设置Delegatecpu并在父 cgroup 的cgroup.subtree_control中写入cpu具体复现与修复步骤见官方部署排查文档中引用的社区 issue 记录。 详见docs/guide/troubleshooting/deployment.md附录排查报错时日志在哪里看遇到上面没列到的错误第一反应应该是看日志。一键部署下各组件的业务日志直接落在文件里不在 journalctl 中组件日志路径CubeAPI/data/log/CubeAPI/cube-api-YYYY-MM-DD.logCubeMaster/data/log/CubeMaster/cubemaster-req.logCubelet/data/log/Cubelet/Cubelet-req.logCubeShim含 Guest 内核启动日志/data/log/CubeShim/cube-shim-req.logHypervisor (VMM)/data/log/CubeVmm/vmm.log沙箱 / 模板日志用cubecli logs sandbox-id需在计算节点上执行Cubelet 默认日志级别是warn排障时可通过动态配置dynamicconf/conf.yaml加log_level: debug约 10 秒热加载生效排完记得改回Guest 内核启动日志就在 CubeShim 日志里按InstanceId过滤即可。 完整速查表与命令docs/guide/troubleshooting/component-log-locations.md最后建议排障顺序遵循先看现象哪个阶段、哪条日志→ 对照本文速查表 → 查对应 troubleshooting 文档 → 再调超时/参数避免用加大超时来掩盖真实的节点或磁盘故障。【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考