2026.06.04 发布 v0.3.1

CubeSandbox 0.3.1 是 v0.3.0 之后的稳定性与加固版本，专注于一键安装脚本的健壮性增强、网络稳定性修复、AgentHub 功能完善，以及基于真实基准测试数据的文档扩展。14 个提交，7 位贡献者。

✨ 功能增强

一键部署

• 自定义沙箱网络 CIDR（#451）：用户现在可以在安装时通过 CUBE_SANDBOX_NETWORK_CIDR 指定沙箱网络 CIDR，以规避与宿主机现有网络子网的冲突。支持 CIDR 格式校验、宿主机接口/路由重叠检测，并提供绕过标志（CUBE_SANDBOX_NETWORK_CIDR_SKIP_CONFLICT_CHECK）用于高级场景。配置成功后会持久化到 .one-click.env。
• Systemd 255 ExecStart/ExecStop 兼容（#451）：为所有 ExecStart、ExecStartPre、ExecStartPost 和 ExecStop 指令添加 /usr/bin/bash 前缀，避免 OpenCloudOS 9.4+ 上 systemd-executor 导致的 203/EXEC 错误。
• glibc 版本预检（#457）：安装脚本现在会在安装前检查 glibc >= 2.34，在不支持的发行版（如 CentOS 7、Ubuntu 20.04）上提前失败，避免 cubelet/cubecli 二进制文件在运行时崩溃。
• PVM 一致性预检（#456）：当宿主机加载了 kvm_pvm 内核模块时，安装脚本会验证是否设置了 CUBE_PVM_ENABLE=1。如果没有此检查，PVM 宿主机将静默安装错误的 guest 内核（普通 vmlinux 而非 vmlinux-pvm），导致 VM 模板创建在后续阶段以难以排查的错误失败。可通过 ONE_CLICK_SKIP_PVM_CHECK=1 跳过。

AgentHub（Preview 预览版）

• 快照/回滚 API 路由（#426）：为 AgentHub 添加了快照创建和回滚端点，使数字助理控制台能够管理沙箱检查点。
• 预览按钮与沙箱打开逻辑（#426）：WebUI 现在包含预览按钮和沙箱打开功能，并修复了模板商店的默认值问题。
• 预览功能文档（#426）：新增中英文双语的 AgentHub 预览功能使用指南。

🐛 Bug 修复

• 修复 network-agent 重启导致现有沙箱网络中断（#442）：当 network-agent 重启时，restoreTap() 无条件尝试通过 TUNSETIFF 获取 TAP fd，即使该 TAP 仍被运行中的沙箱持有。由于 IFF_ONE_QUEUE，内核以 EBUSY 拒绝第二次打开，TAP 被推入异常池，清理分支将其 BPF 映射条目删除——导致出口流量被静默丢弃。修复方案：当 tap.InUse 为 true 时跳过 getTapFd，并在没有可用 fd 时向调用方返回明确错误。
• 延迟宿主机 DNS 切换至 CoreDNS 就绪后（#452）：首次安装时，在 CoreDNS 监听之前就改写了宿主机 resolv.conf，导致 DNS 死锁。安装脚本现在等待 CoreDNS 绑定端口，保留一个上游回退 DNS 服务器，并在上游解析路径中过滤预留的 nameserver 地址。

开发环境

• 更新默认 OpenCloudOS 镜像至 9.6（#447）：OpenCloudOS 9.4 qcow2 镜像在 mirrors.tencent.com 上已不再可用，下载失败。将 prepare_image.sh 和 run_vm.sh 中的默认镜像 URL 升级至最新的 9.6-20260514.2 GenericCloud 镜像。

📚 文档

• SA9.4XLARGE32 PVM 基准测试报告（中英文）（#459）：在腾讯云 SA9.4XLARGE32（AMD EPYC 9K65、16 vCPU、32 GiB 内存、200 GiB 增强型 SSD、PVM 内核）上的完整基准测试报告，涵盖冷启动延迟、并发扩展（c=1/10/20）、单机密度（约 743 个空闲沙箱，单个约 27-34 MB）、快照创建与并发及脏页大小的关系、从快照创建、回滚、克隆、暂停/恢复等并发性能。中英文两个版本均已包含。
• BMI5 裸金属基准测试数据（#450）：用来自腾讯云 BMI5 裸金属节点的真实实测数据替换性能基准测试文章（中英文）中的所有模拟/占位数据。重构压测脚本为单层 CLI 风格，以支持可组合的多层扫描，并添加 TAP 池扩容说明。
• v0.3.0 发布博客（#441）：新增中英文 v0.3.0 发布博文（快照/克隆/回滚、AgentHub、Web UI、Go SDK），并将精选文章排序重新调整，v0.3.0 权重最高。
• trpc-agent-go 用例（#446）：新增用例文档，介绍 trpc-agent-go 如何基于 Cube Sandbox 作为安全代码执行后端，中英文侧边栏均已添加条目。
• 性能基准文章修复（#440）：修复 vmm.log 路径，在 2.2 节添加模板创建命令，将通用约定从 3.1 节移至 4.0 节，中英文两个版本均已更新。
• 磁盘空间要求更新（#425）：将 /data/cubelet 的最低磁盘空间要求从 300 GB 降低至 50 GB，构建多个模板时建议 200 GB 及以上。
• 移除重复的快速开始链接（#430）：清理 README 中重复的快速开始链接入口，仅保留顶部导航栏。

👏 贡献者

7 位贡献者共同完成了此版本：

@LoGin (jinlong), @ls (ls-ggg), @cherrycao, @chengjoey, @Hengqi Chen, @joeytao, @tinklone (maxlong)