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

## 2026.07.10 Release v0.5.1

CubeSandbox 0.5.1 是一次面向生产落地的跟进发布，在 0.5.0 的 AutoPause / ARM64 / 集群部署基线上补齐关键能力与稳定性。本版本重点包括：**cube-lifecycle-manager 独立控制面服务**（从 CubeProxy sidecar 拆出，支持 CubeProxy 多副本扩展）、**三值 timeout 语义重构**（服务端默认 + `NEVER_TIMEOUT` / 立即超时 / TTL），以及 **host-mount 路径白名单安全加固**。同时修复 ARM64 64KB 页场景下的快照完整性问题，并显著提升出向策略与 TAP 回收的可靠性。共计 59 个提交，来自 18 位贡献者。

### 🎯 核心特性

#### cube-lifecycle-manager：AutoPause 协调器独立化

将原先内嵌在 CubeProxy 镜像中的 `cube-proxy-sidecar` 拆分为独立控制面服务 **cube-lifecycle-manager（CLM）**，使 CubeProxy 可多副本水平扩展，而不再依赖单实例 sidecar。

* **独立部署**：CLM 作为独立服务接入 `cube-sandbox-control.target`；一键安装与腾讯云 Terraform 部署均已纳入。
* **Redis 服务发现**：CubeProxy 各副本将 admin endpoint 注册到 Redis；CLM 通过注册表发现全部在线副本并协调 auto-pause / auto-resume，无需静态配置副本列表。
* **协议兼容**：Wire protocol、Redis schema、SDK 行为保持不变；现有 AutoPause / AutoResume 语义不受影响。
* **腾讯云 Terraform** (#814)：控制面新增 `cube-lifecycle-manager` Deployment；支持 `TENCENTCLOUD_CUBE_PROXY_REPLICAS` 多副本，以及 CLM 副本数 / discovery refresh / admin token 等配置项。

#### 三值 Timeout 语义 + 服务端默认

统一沙箱 idle timeout 语义，与 E2B 对齐，并将「未设置」与「显式默认值」区分开——默认超时决策从 SDK / CubeAPI 下沉到 CubeMaster。

| 取值 | 含义 |
|------|------|
| 省略（`None` / `nil`） | 由集群 `default_timeout_insec` 决定；未配置或 ≤0 时视为永不超时 |
| `NEVER_TIMEOUT`（`-1`） | 永不因 idle 回收 |
| `0` | 立即超时（首次 idle sweep 即回收） |
| `N > 0` | idle TTL = N 秒 |

* **SDK**：Go / Python 的 `CreateOptions.Timeout` 改为可选指针；Create / Connect / Resume 不再自动填入硬编码默认值。暴露 `NeverTimeout` / `NEVER_TIMEOUT` sentinel。
* **CubeAPI / CubeMaster**：timeout 字段改为 `Option` / `*int`，透传「未设置」；`EndAt` 按三值语义计算（`-1` → 无截止时间）。
* **RPC 截止与 idle TTL 解耦**：新增 `create_timeout_insec`（默认 300s）仅约束创建调度 RPC，不再与沙箱 idle TTL 混用。
* **CLM sweeper**：`TimeoutSeconds < 0` 跳过回收；`== 0` 立即回收；旧数据 `nil` 回退到 `DefaultIdleTimeout`。
* **运行时调整**：Python / Go SDK 新增 `set_timeout()` / `SetTimeout()`，支持将运行中沙箱改为 `NEVER_TIMEOUT` (#743, #850)。Web UI 创建沙箱时可传入 timeout (#798)。

#### Host-Mount 路径白名单安全加固

此前 host-mount 接受任意绝对路径，沙箱可 bind-mount 宿主机任意目录。现改为可配置前缀白名单（默认 `/data/shared/`），并用 `filepath.Clean` 消除 `..` 路径穿越；配置中显式禁止根路径 `/` (#756)。

配套更新持久化存储指南（路径限制、权限、多租户隔离、多节点共享存储），示例路径对齐默认前缀 (#768)。

### ✨ 功能增强

#### SDK

* **Node.js / TypeScript SDK（预览）** (#792)：新增 `@cubesandbox/sdk`，API 面与 Python / Go 对齐；尚在验证中，生产使用请谨慎。
* **Python / Go `set_timeout`** (#743, #850)：对齐 E2B API；CubeAPI / CubeMaster 接受 `-1`（`NEVER_TIMEOUT`），拒绝其他负值。
* **Go SDK allowOut 校验对齐** (#802)：不再将 `AllowPublicTraffic=false` 误判为 deny-all；与 CubeAPI 一致，仅在 `AllowInternetAccess=false` 或 `denyOut` 含 `0.0.0.0/0` 时视为全拒绝。

#### 网络与 Egress

* **CubeEgress 明文 HTTP 凭据注入** (#726)：允许对纯 HTTP 上游注入凭据。安全边界是沙箱代码看不到密钥，而非要求 egress→upstream 必须 TLS。
* **CubeEgress 透明代理 IP 随 CIDR 推导** (#851)：不再硬编码 `192.168.0.1`；从 `CUBE_SANDBOX_NETWORK_CIDR` 取网段首个可用 IP，自定义沙箱网段时 TPROXY / OpenResty 监听地址正确。
* **DNS 学习条目最小 TTL**：对 DNS 学到的 egress allow 条目施加最小 300s TTL，避免短 TTL 导致重连被误拒。
* **已建立会话跳过策略重检**：CubeVS 对已存在的 CubeEgress TCP 会话跳过 egress 策略重检，避免 DNS 记录过期打断活跃连接；策略检查折叠进 `create_nat_session`，按会话缓存结果。
* **默认 deny 基线统一回放**：replace / flush 路径始终回放私网 / link-local 默认 deny 条目，create 与 replace 策略形态一致。

#### 部署与安装器

* **CubeProxy 预发布多架构镜像** (#849)：一键部署改为从 TCR 拉取预构建 multi-arch 镜像，不再本机构建；支持 `MIRROR=cn|int` 与 airgap 本地缓存回退。
* **组件镜像发布流水线** (#795)：新增 `release-docker-images.yml`，向 GHCR / TCR 推送 multi-arch 组件镜像；`bump-image.sh` 统一管理硬编码镜像标签。
* **CubeMaster Dockerfile** (#813, #824)：统一 Docker build args / context，修复 ARG 作用域；CubeAPI Dockerfile 改为单次构建并加安全门禁 (#854)。
* **一键 DNS dnsmasq 回退** (#740)：无 systemd-resolved 且 NetworkManager dnsmasq 插件未拉起子进程时，可选由脚本自管 dnsmasq，避免 `cube.app` 解析失败。
* **Cubelet 配置 patch 锚定** (#776)：sed 替换锚定行首，避免改 `CUBE_SANDBOX_NETWORK_CIDR` 时误改空的 `cube_router_cidr`。

#### Web UI / AgentHub / 其他

* **CubeAPI lifecycle snake\_case** (#772)：接受 `lifecycle.on_timeout` / `lifecycle.auto_resume` 等 Python 风格字段名，避免静默落到 kill / 无 resume。
* **AgentHub OpenClaw bind=lan** (#769)：强制 gateway 绑定 `lan`，确保 cube-proxy 可通过 tap IP 访问，避免 `auto` 落到 loopback。
* **ARM64 运行时加固** (#807)：dirty bitmap 粒度改用宿主机页大小（修复 64KB 页上快照严重不完整、恢复后 200% CPU）；aarch64 vCPU 在无 PMUv3 主机上自动回退无 PMU 初始化。
* **开发环境 QEMU 10.x** (#713)：显式 `-drive if=none` + `-device virtio-blk-pci`，修复 QEMU 10.2.2+ 的空 drive 错误。

### 🐛 Bug 修复

#### 生命周期与沙箱

* **Resume 幂等** (#817)：沙箱已处于 Running 时返回可识别的「已在目标状态」信号（CLM 视为成功），不再与真正不可 resume 的状态混为同一错误。
* **删除不存在沙箱返回 404** (#759)：CubeAPI / CubeMaster 对缺失沙箱的 delete 映射为 NotFound。
* **沙箱列表稳定排序** (#762)：按创建时间降序 + SandboxID 打破平局，避免 WebUI / SDK 刷新时顺序跳动。
* **模板网络规则与资源默认值保留** (#581)：从镜像创建模板时保留 egress 规则；CPU/内存同时超限时保留首个校验错误；请求侧 override 在 first-match-wins 下优先生效。

#### 网络与数据面

* **TAP 回收安全**（network-agent）：清理与池准备完成前不归还 TAP；失败清理路径不把带残留策略的 TAP 放回池；复用前清理策略 / DNS allow 状态，避免跨沙箱泄漏。
* **Go SDK envd 端口** (#821)：envd RPC（commands / files / filesystem / PTY）改走 49983，不再误打到 Jupyter 端口 49999；仅 `RunCode`/`/execute` 仍走 Jupyter。

#### 其他

* **示例 host-mount 路径对齐** (#768)：示例与文档路径改为 `/data/shared/...`，匹配默认白名单。

### 📚 文档

* **ARM64 支持公告博客** (#866)：中英文 InfoQ 风格发布稿，介绍与 Arm 联合推进的多架构能力。
* **Pi Agent 集成指南** (#701)：中英文集成文档 + 可运行示例（pause/resume、网络策略、凭据注入）。
* **生命周期 / 配额文档** (#739)：补充 ARM64 安装说明与 lifecycle 配额相关文档。
* **持久化存储指南** (#756)：host-mount 路径限制、权限、多租户隔离、多节点共享存储。
* **Roadmap** (#731)：README 与文档站增加 roadmap。
* **v0.5.0 发布相关** (#770, #781)：发布博客与特性描述更新；Quickstart 注明 Multi-Arch 镜像可用性 (#806)。
* **开发技能与文档规范** (#788, #789)：Claude Code `run-dev` skill；i18n 同步检查与变更驱动文档审计规则。

### ⚙️ 工程改进

* **版本矩阵允许平台后缀** (#747)：版本检查兼容带平台后缀的版本号。
* **PVM guest 构建触发收紧** (#819)：仅在 version tag 时触发 pvm-guest 构建。
* **镜像标签 bump**：发布候选过程中多次同步 one-click / Terraform 默认镜像至 `v0.5.1-rc*` (#826, #867)。
* **Python SDK 版本 bump 至 0.5.0** (#818)。
* **CubeAPI 死代码清理** (#796) 及其他小范围工程整理。

> 说明：Web Example Center（#615）曾合入后随即回滚（#778），不包含在本版本交付中。