---
url: https://cubesandbox.com/zh/changelog/v0.3.1.md
---

## 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)