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

## 2026.06.02 发布 v0.3.0

CubeSandbox 0.3.0 引入了 **CubeCoW** Copy-on-Write 快照引擎，为 AI Agent 沙箱带来百毫秒级快照、克隆与回滚能力。本次发布还新增了 **AgentHub** 数字助理控制台（Preview 预览版）、**Web UI** 可视化管理界面，以及 **Go SDK**。82 个提交，22 位贡献者，这是开源以来规模最大的版本。

### 🎯 核心特性

#### CubeCoW：快照、克隆与回滚

* **CubeCoW Copy-on-Write 快照引擎**（#360）：基于 reflink 的卷快照实现全生命周期 CoW 快照管理，提供高效的块级快照操作。可在任意时刻创建轻量、节省空间的检查点。
* **Soft-dirty 增量内存快照**（#389）：基于 soft-dirty 页面追踪实现逐周期增量内存快照，仅捕获首次全量快照后的脏页，大幅降低重复快照周期的时间和存储开销。
* **快照恢复与 vsock 处理**（#388）：快照恢复时正确重置 VSOCK 连接，确保回滚后连接状态干净。
* **快照 I/O 优化**（#400）：从所有快照写路径中移除不必要的 `sync_all()` 调用，在不影响数据完整性的前提下显著降低快照写入延迟。
* **示例套件与开发者指南**（#374）：完整的快照、回滚、克隆工作流示例与分步指南，包含可运行的代码。
* **Host-mount 暂停快照恢复修复**：修复了带有暂停 host-mount 文件系统的沙箱快照恢复问题。

#### AgentHub 数字助理控制台（Preview 预览版）

* **AgentHub API 与 UI**（#420）：基于 CubeSandbox 构建的完整数字助理控制台，包括：
  * AgentHub 持久化层与助手生命周期管理
  * OpenClaw 集成，支持 AI Agent 编排
  * 快照时间线，支持可视化检查点创建与回滚
  * 从任意快照克隆沙箱，创建并行探索环境
  * 模板操作，复用助手配置
  * 模型设置与企业微信通知配置
  * 完整的中英文国际化支持

#### Web UI

* **可视化管理界面**（#299）：浏览器直接访问的 Web 管理界面，支持沙箱、模板、集群节点的可视化管理。内置模板商店，可浏览和部署预构建的沙箱镜像。日常操作无需命令行。

### 🛠️ SDK

#### Python SDK（v0.2.1）

* **模板创建 API**（#365）：支持从 Python 代码程序化创建沙箱模板，实现端到端自动化，无需 shell 命令。
* **envd 进程 API 迁移**（#1676a0fc）：命令执行改为通过 envd 进程 API，提高可靠性与一致性。
* **进程退出边界处理**（#a210dfc2）：修复 envd 进程生命周期管理中的边界情况，防止命令挂起。
* **Stderr 覆盖与文件回退加固**（#9e2c64ab）：改进错误输出捕获，加固文件操作回退路径。
* **envd 默认值与网络策略对齐**（#418）：将 envd 服务默认值和网络策略配置与服务端默认值对齐。

#### Go SDK（全新）

* **Go SDK 首发**（#5de861ac, #3b5caf29）：完整的 Go SDK，提供类型安全的 API 绑定，支持沙箱生命周期管理，让 Go 应用原生创建、管理和销毁沙箱。

### ✨ 功能增强

#### 部署

* **一键部署迁移至 systemd**（#331）：一键安装脚本现在通过 systemd 管理所有服务，提供正确的服务监控、故障自动重启和 `systemctl` 集成。
* **Docker Compose 容器生命周期管理**（#386）：容器生命周期管理迁移至 Docker Compose，简化多容器编排，改善重启行为。
* **安装前预下载检测**（#288）：在线安装脚本在下载前验证网络连通性和磁盘空间，避免安装中途失败。
* **健康检查与诊断脚本**（#305）：新增 `check.sh` 和 `collect-logs.sh`，用于一键部署的健康验证与日志收集。
* **Cgroup v2 CPU 控制器预检**（#367）：安装脚本检测 cgroup v2 CPU 控制器支持情况，缺失时在安装前给出明确指引。
* **网络代理就绪等待**（#304）：安装脚本等待 network-agent 完全就绪后再继续，消除初始化期间的竞态条件。
* **Docker 挂载目录防创建**（#417）：防止 Docker 在 bind-mount 文件路径自动创建目录，确保正确的挂载行为。
* **Guest 镜像优化**（#347）：创建后自动压缩 ext4 镜像并优化 Dockerfile，减小镜像体积和拉取时间。

#### 基础设施

* **集中化数据库迁移**（#385）：CubeMaster 使用 `goose` 管理数据库 schema 迁移，支持版本化、自动化的 schema 升级。
* **节点资源上报**（#382）：Cubelet 向 CubeMaster 上报已分配的节点资源（CPU、内存、磁盘），支持集群级资源感知。
* **基于路径的沙箱路由**（#334）：CubeProxy 支持基于路径的沙箱路由和共享后端解析，提升路由灵活性。
* **调度器指标**（#326, #301）：Cubelet 通过 `/v1/metrics` 暴露调度器 Prometheus 指标，支持沙箱调度与资源利用的实时监控。

### 🐛 Bug 修复

* **暂停/恢复状态一致性**（#404）：修复 ttrpc 错误和 shim 事件导致的暂停/恢复状态漂移，确保沙箱生命周期状态一致。
* **Shim 就绪握手**（#398）：修复 shim 就绪握手因 stdout（fd 1）重定向而失效的问题，避免静默初始化失败。
* **网络资源泄漏**（#314）：修复沙箱创建时的网络资源泄漏，防止长时间运行后可用网络接口耗尽。
* **Host-mount 目录清理**（#333）：沙箱销毁后正确清理 host-mount 目录，避免磁盘空间累积。
* **Cloud Hypervisor 磁盘 API**（#337）：修复 Cloud Hypervisor 磁盘 API 端点使用错误，避免磁盘操作失败。
* **模板提交幂等性**（#336）：强制 requestID 唯一性并支持幂等提交复用，消除重试请求导致的重复模板提交。
* **配置解析**（#396）：修复 `NodeStatusUpdateFrequency` 使用 `tomlext.Duration` 以确保 TOML 时长正确解析。
* **输入校验**（#344）：在命令执行调用点增加输入校验，提前捕获无效参数。
* **并发 DNS 处理**（#363）：容忍并发 DNS dummy 接口创建，消除并行沙箱创建期间的竞态故障。
* **PMEM 边界对齐**（#351）：压缩后的 guest 镜像与 pmem 边界对齐，修复特定配置下的启动失败。
* **快速检查就绪**（#349）：等待 quickcheck 容器就绪后再继续，消除误报的健康检查失败。
* **服务绑定安全**（#269）：MySQL/Redis 默认绑定 localhost，CubeProxy 改用 host 网络模式，提升网络安全。
* **服务启动顺序**（#346）：`cube-proxy.service` 排在 `cube-sandbox-dns.service` 之后启动，避免 DNS 解析失败。
* **镜像摘要处理**（#303）：在模板中心中剥离镜像摘要的规范前缀，修复镜像引用不匹配问题。
* **暂停状态报告**（#270）：修复沙箱列表响应中的暂停状态显示，确保沙箱状态准确。
* **版本信息注入**（#327）：通过 ldflags 正确注入 cubelet 和 cubemaster 的构建版本信息。

### 🔒 安全

* **Prometheus 升级**（#328）：升级 prometheus 客户端至 0.14.0，移除有漏洞的 `protobuf` 2.28.0 依赖。
* **reqwest 升级**（#323）：CubeAPI 升级 reqwest 至 0.12，修复 `rustls-webpki` 相关 CVE。
* **libseccomp 升级**（#321）：升级 libseccomp 至 0.3.0，修复 GHSA-2r23-gqr7-wr4h。
* **go-jose 版本提升**（#320）：提升 `go-jose/v4` 至最新安全版本。
* **gRPC 依赖更新**（#316）：更新 CubeMaster 中的 gRPC 依赖。

### 📚 文档

* **更新日志重构**（#412, #416）：更新日志按版本拆分文件并建立索引页，导航更清晰。修复 README 中失效的 changelog 链接。
* **性能基准博客**（#419）：发布详细的性能基准测试文章，附可复现的压测脚本，涵盖启动延迟和资源开销指标。
* **博客系统**（#306, #340）：新增博客系统，支持本地搜索和维护者指南。发布「从 Serverless 到 Agent」、PVM 部署指南等社区文章。
* **品牌标识**（#329）：文档站点新增官方 Logo 和 favicon。
* **故障排查指南**（#313）：新增中英文双语的部署和模板创建故障排查子页面。
* **文档交叉引用修复**（#372）：修复文档交叉引用中缺失的 `.md` 扩展名。
* **示例与教程修复**（#406, #407, #377）：修复 create-from-image 教程中的探针路径，将占位 API key 统一为 `e2b_` 前缀，更正克隆状态文档说明。

### ⚙️ 工程优化

* **内核源码迁移**（#395）：将内核源码从 Gitee 迁移至 CNB，并增强解压逻辑。
* **CI/CD 加固**（#330, #335, #338, #393）：新增文档构建检查工作流，修复 CR 工作流，启用外部 PR 自动审查，添加默认 shell 配置并优化制品获取。
* **废弃 API 移除**（#339）：移除代码库中的废弃 `rand.Seed` 调用。
* **Rust 依赖刷新**（#9f8df42f）：在 hypervisor crate 中将 `crossbeam-channel` 从 0.5.13 升级至 0.5.15。

### 👏 贡献者

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

@fslongjin, @ls, @tinklone, @kami-lu, @chenggui53, @cherrycao, @Hengqi Chen, @NovaHe, @maxlong, @Yi Wang, @liciazhu, @Nemo, @Feng King, @Songqian Li, @Joohwan., @Stary, @xiongxz, @yangjie, @YangYuS8, @wangchenglong-hj, @John Eismeier, @dependabot\[bot]