CubeSandbox版本升级指南：从0.3到0.6平滑升级避坑清单
【免费下载链接】CubeSandboxInstant, Concurrent, Secure & Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox
CubeSandbox 是面向 AI Agent 的即时、并发、安全且轻量级的沙箱平台（Instant, Concurrent, Secure & Lightweight Sandbox for AI Agents）。本文将从 0.3 一路升到 0.6，带你梳理每个版本的关键变化、官方升级路径，以及新手最容易踩中的那些坑，帮你把生产环境的沙箱集群平滑升级到最新版。
一、升级前先搞清楚：0.3 → 0.6 每个版本改了什么
升级最大的风险不是命令本身，而是"不知道新版本改了什么语义"。下面这张表帮你快速建立全局认知：
| 版本 | 主题 | 与升级强相关的变化 |
|---|---|---|
| v0.3.0 | 快照引擎 | 引入 CubeCoW 写时复制引擎，快照/克隆/回滚成为核心能力，快照数据开始占用额外磁盘 |
| v0.3.1 | 稳定化 | 一键安装器加固：自定义网络 CIDR、glibc 预检、PVM 一致性预检 |
| v0.4.0 | 安全出口 | 新增 CubeEgress 安全代理（凭据注入/域名过滤/审计），最低 glibc 从 2.34 降到 2.31 |
| v0.5.0 | 生命周期自动化 | 新增 AutoPause/AutoResume、ARM64 原生支持、一键升级模式（三路配置合并 + 升级前备份）、静态二进制与内嵌数据库迁移 |
| v0.5.1 | 生产加固 | 独立的 cube-lifecycle-manager 服务、host 挂载路径白名单（默认/data/shared/） |
| v0.6.0 | 运维能力 | 新增CUBE_AUTO_MIGRATION开关控制数据库自动迁移、计算节点隔离、CubeOps 从 CubeAPI 拆分 |
各版本的完整变更明细可查阅仓库内的变更日志：v0.3.0、v0.4.0、v0.5.0、v0.5.1、v0.6.0。
二、两种部署形态，两条升级路径
1️⃣ 一键部署（单机/多机裸金属）：用官方升级模式
⚠️最大前提：install.sh --mode=upgrade是 v0.5.0 才引入的能力。如果你还停留在 0.3 或 0.4，请先按"卸载重装"的思路评估：备份好/data/cubelet下的模板与快照数据、导出数据库中 AgentHub 的状态，再升级安装器。
从 0.5.0 开始，升级流程被官方标准化了（实现见 deploy/one-click/install.sh）：
- 检测已有安装：
--mode=upgrade会先确认这是一次"保配置升级"，找不到旧安装会直接报错退出； - fail-fast 预检：磁盘空间、语义化版本兼容性、网络 CIDR 冲突检查，任何一项不满足都会在动任何文件前终止；
- 升级前自动备份：把配置目录完整备份到升级备份目录，出问题可以回滚；
- 三路 .env 合并：新默认值 + 你的旧自定义值 + 你本次显式传入的值，三方合并，且密钥类配置在 diff 报告中脱敏、在合并文件里原样保留。
2️⃣ Kubernetes（v0.6.0 起，Preview）：helm upgrade
0.6.0 开始支持用 Helm Chart 把控制面与计算节点部署到 TKE / 标准 K8s / k3s。官方升级文档在 docs/guide/kubernetes/upgrade.md，核心红线只有一条：
计算面升级会重建
cube-node大 Pod（netns 变化），中断该节点上所有存量沙箱。
所以 K8s 升级的标准动作是：
- 先只改
runtime-values.yaml里需要升的镜像 tag，不要顺手改大 Pod 的 env / volumeMount（任何模板变更都会触发 Pod 重建）； - 升级计算节点前，先用
cubemastercli node isolate <node-id>隔离节点（至少 60 秒），清掉节点上的沙箱，再执行helm upgrade； - 控制面滚动遵循顺序：CubeOps 先就绪 → CubeMaster → 计算面，且切换期间不要混跑新旧版本 cubelet（新旧 cubelet 上报地址不同，混跑会造成节点状态不一致）。
三、避坑清单：这 8 个坑新手最常踩
🕳️ 坑 1：整份cp env.example .env会把开关全部重置
这是 deploy/one-click/README_zh.md 里明确警告过的坑：升级时如果整份复制示例 env，CUBE_PVM_ENABLE、ONE_CLICK_ENABLE_S3LVOL这类显式开关会被重置为默认值（0）。正确做法是只修改需要的项，或在命令行显式传入，让三路合并保留你原来的自定义值。
🕳️ 坑 2：PVM 主机忘记设置CUBE_PVM_ENABLE=1
PVM 嵌套 KVM 主机如果没显式开启该开关，会装上普通 guest 内核，导致后续模板创建以"莫名其妙的错误"失败。0.3.1 起安装器已加入一致性预检，但升级场景仍建议显式CUBE_PVM_ENABLE=1 ./install.sh传入，避免历史配置丢失。
🕳️ 坑 3：0.5.1 之后，host 挂载路径被白名单限制
0.5.1 起，host 挂载只接受可配置前缀下的路径（默认/data/shared/），..穿越会被中和，/被明确禁止。如果你的沙箱模板绑定了其他绝对路径，升级后创建会失败——请把数据目录迁到/data/shared/下，或调整白名单配置（详见 docs/guide/soft-delete-purge.md 同目录下的持久化存储文档与 examples/host-mount 示例）。
🕳️ 坑 4：流量访问令牌（traffic_access_token）导致旧客户端 403
0.5.0 引入的安全强化：创建沙箱时若设置network.allow_public_traffic=false，每个沙箱会获得独立访问令牌，CubeProxy 对缺失/不匹配令牌的入站请求一律返回 403（0.6.0 进一步与 E2B 对齐）。升级后如果旧版 SDK 或自研脚本开始大面积 403，检查是否带了cube-traffic-access-token请求头。
🕳️ 坑 5：数据库自动迁移与受控升级
0.5.0 起控制面改为内嵌数据库迁移（不再需要手工执行 SQL seed）；0.6.0 又新增CUBE_AUTO_MIGRATION环境变量，可跳过启动时的自动迁移。生产建议：升级 CubeMaster 前确认新版本与旧版本迁移文件兼容，受控场景先关掉自动迁移、人工核对再放开，避免滚动期间多副本互相竞争 schema。
🕳️ 坑 6：模板组件版本绑定失效（"stale replica"）
0.4.0 引入了节点组件版本矩阵与模板兼容性检查：模板绑定了 guest-image / cube-agent / kernel 的版本组合。升级了 guest 镜像或内核后，旧模板副本可能变为"不兼容"，Web UI 会显示 stale 警告。升级后请检查模板兼容状态，必要时重建模板，而不是以为模板"还能用"。
🕳️ 坑 7：网络端口变量改名
0.5.0 废弃了CUBE_PROXY_HOST_PORT，拆分为CUBE_PROXY_HTTP_PORT（默认 80）与CUBE_PROXY_HTTPS_PORT（默认 443）。旧变量在升级合并中会被保留但不再生效，请在新 env 中显式设置两个新变量，避免端口漂移导致数据面不可达。
🕳️ 坑 8：快照与 WAL 数据的保留语义
升级会替换组件二进制，但数据面资产有明确保留规则：/data/cubelet下的模板、快照目录不被覆盖；CubeS3lvol 的wal_bdev.img永不覆盖（仅首次安装创建）。升级前对这块数据做一次冷备，是所有路径中成本最低、收益最高的一步。
四、升级后验证：5 分钟健康检查清单
升级完成不等于升级成功。按这个顺序做一轮验证：
- ✅组件版本：
cubecli version/cubemastercli version，或在 Web UI 的 Versions 页面查看集群组件版本矩阵，确认没有节点停留在旧版本（版本矩阵功能自 0.4.0 提供）； - ✅创建冒烟：用官方示例 examples/code-sandbox-quickstart 创建沙箱并执行一段代码；
- ✅快照闭环：创建一个快照 → 克隆 → 回滚，验证 0.3 引入的 CoW 能力在升级后完好；
- ✅网络策略：确认 CubeEgress 的域名过滤、凭据注入仍按策略生效（0.5.0 起启动窗口为 fail-closed，观察日志中不应出现策略加载失败）；
- ✅生命周期：对开启 AutoPause 的沙箱发一次数据面请求，确认自动恢复链路（CubeProxy → cube-lifecycle-manager → CubeMaster → Cubelet）通畅。
五、升级前夜的备份与回退方案
最后把"后悔药"准备好：
- 数据库：对 MySQL/PostgreSQL 做一次全量 dump（0.6.0 起控制面已支持 PostgreSQL 后端，确认你的备份工具匹配实际引擎）；
- 数据目录：备份
/data/cubelet（模板 + 快照）与安装前缀下的.one-click.env； - 一键部署：0.5.0+ 的升级模式自带配置备份目录，保留它直到新版本运行稳定；
- 回退：保留旧版本的离线发布包与旧 env 基线，必要时执行"从备份恢复 + 旧包重装"。
按这份清单走完，你的 CubeSandbox 集群就能从 0.3 平滑抵达 0.6，把 AutoPause 自动生命周期、ARM64 支持、K8s 部署和节点隔离这些新能力稳稳装进生产环境。
更多参考：docs/changelog/index.md、docs/guide/kubernetes/upgrade.md、docs/guide/node-operations.md
【免费下载链接】CubeSandboxInstant, Concurrent, Secure & Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
