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），不包含在本版本交付中。