CubeSandbox版本升级指南从0.3到0.6平滑升级避坑清单【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandboxCubeSandbox 是面向 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.31v0.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 --modeupgrade是 v0.5.0 才引入的能力。如果你还停留在 0.3 或 0.4请先按卸载重装的思路评估备份好/data/cubelet下的模板与快照数据、导出数据库中 AgentHub 的状态再升级安装器。从 0.5.0 开始升级流程被官方标准化了实现见 deploy/one-click/install.sh检测已有安装--modeupgrade会先确认这是一次保配置升级找不到旧安装会直接报错退出fail-fast 预检磁盘空间、语义化版本兼容性、网络 CIDR 冲突检查任何一项不满足都会在动任何文件前终止升级前自动备份把配置目录完整备份到升级备份目录出问题可以回滚三路 .env 合并新默认值 你的旧自定义值 你本次显式传入的值三方合并且密钥类配置在 diff 报告中脱敏、在合并文件里原样保留。2️⃣ Kubernetesv0.6.0 起Previewhelm upgrade0.6.0 开始支持用 Helm Chart 把控制面与计算节点部署到 TKE / 标准 K8s / k3s。官方升级文档在 docs/guide/kubernetes/upgrade.md核心红线只有一条计算面升级会重建cube-node大 Podnetns 变化中断该节点上所有存量沙箱。所以 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 里明确警告过的坑升级时如果整份复制示例 envCUBE_PVM_ENABLE、ONE_CLICK_ENABLE_S3LVOL这类显式开关会被重置为默认值0。正确做法是只修改需要的项或在命令行显式传入让三路合并保留你原来的自定义值。️ 坑 2PVM 主机忘记设置CUBE_PVM_ENABLE1PVM 嵌套 KVM 主机如果没显式开启该开关会装上普通 guest 内核导致后续模板创建以莫名其妙的错误失败。0.3.1 起安装器已加入一致性预检但升级场景仍建议显式CUBE_PVM_ENABLE1 ./install.sh传入避免历史配置丢失。️ 坑 30.5.1 之后host 挂载路径被白名单限制0.5.1 起host 挂载只接受可配置前缀下的路径默认/data/shared/..穿越会被中和/被明确禁止。如果你的沙箱模板绑定了其他绝对路径升级后创建会失败——请把数据目录迁到/data/shared/下或调整白名单配置详见 docs/guide/soft-delete-purge.md 同目录下的持久化存储文档与 examples/host-mount 示例。️ 坑 4流量访问令牌traffic_access_token导致旧客户端 4030.5.0 引入的安全强化创建沙箱时若设置network.allow_public_trafficfalse每个沙箱会获得独立访问令牌CubeProxy 对缺失/不匹配令牌的入站请求一律返回 4030.6.0 进一步与 E2B 对齐。升级后如果旧版 SDK 或自研脚本开始大面积 403检查是否带了cube-traffic-access-token请求头。️ 坑 5数据库自动迁移与受控升级0.5.0 起控制面改为内嵌数据库迁移不再需要手工执行 SQL seed0.6.0 又新增CUBE_AUTO_MIGRATION环境变量可跳过启动时的自动迁移。生产建议升级 CubeMaster 前确认新版本与旧版本迁移文件兼容受控场景先关掉自动迁移、人工核对再放开避免滚动期间多副本互相竞争 schema。️ 坑 6模板组件版本绑定失效stale replica0.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 做一次全量 dump0.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），仅供参考 
长河君 · 2026/9/17 6:19:40 · 阅读 1.2k CubeSandbox版本升级指南：从0.3到0.6平滑升级避坑清单
CubeSandbox版本升级指南从0.3到0.6平滑升级避坑清单【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandboxCubeSandbox 是面向 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.31v0.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 --modeupgrade是 v0.5.0 才引入的能力。如果你还停留在 0.3 或 0.4请先按卸载重装的思路评估备份好/data/cubelet下的模板与快照数据、导出数据库中 AgentHub 的状态再升级安装器。从 0.5.0 开始升级流程被官方标准化了实现见 deploy/one-click/install.sh检测已有安装--modeupgrade会先确认这是一次保配置升级找不到旧安装会直接报错退出fail-fast 预检磁盘空间、语义化版本兼容性、网络 CIDR 冲突检查任何一项不满足都会在动任何文件前终止升级前自动备份把配置目录完整备份到升级备份目录出问题可以回滚三路 .env 合并新默认值 你的旧自定义值 你本次显式传入的值三方合并且密钥类配置在 diff 报告中脱敏、在合并文件里原样保留。2️⃣ Kubernetesv0.6.0 起Previewhelm upgrade0.6.0 开始支持用 Helm Chart 把控制面与计算节点部署到 TKE / 标准 K8s / k3s。官方升级文档在 docs/guide/kubernetes/upgrade.md核心红线只有一条计算面升级会重建cube-node大 Podnetns 变化中断该节点上所有存量沙箱。所以 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 里明确警告过的坑升级时如果整份复制示例 envCUBE_PVM_ENABLE、ONE_CLICK_ENABLE_S3LVOL这类显式开关会被重置为默认值0。正确做法是只修改需要的项或在命令行显式传入让三路合并保留你原来的自定义值。️ 坑 2PVM 主机忘记设置CUBE_PVM_ENABLE1PVM 嵌套 KVM 主机如果没显式开启该开关会装上普通 guest 内核导致后续模板创建以莫名其妙的错误失败。0.3.1 起安装器已加入一致性预检但升级场景仍建议显式CUBE_PVM_ENABLE1 ./install.sh传入避免历史配置丢失。️ 坑 30.5.1 之后host 挂载路径被白名单限制0.5.1 起host 挂载只接受可配置前缀下的路径默认/data/shared/..穿越会被中和/被明确禁止。如果你的沙箱模板绑定了其他绝对路径升级后创建会失败——请把数据目录迁到/data/shared/下或调整白名单配置详见 docs/guide/soft-delete-purge.md 同目录下的持久化存储文档与 examples/host-mount 示例。️ 坑 4流量访问令牌traffic_access_token导致旧客户端 4030.5.0 引入的安全强化创建沙箱时若设置network.allow_public_trafficfalse每个沙箱会获得独立访问令牌CubeProxy 对缺失/不匹配令牌的入站请求一律返回 4030.6.0 进一步与 E2B 对齐。升级后如果旧版 SDK 或自研脚本开始大面积 403检查是否带了cube-traffic-access-token请求头。️ 坑 5数据库自动迁移与受控升级0.5.0 起控制面改为内嵌数据库迁移不再需要手工执行 SQL seed0.6.0 又新增CUBE_AUTO_MIGRATION环境变量可跳过启动时的自动迁移。生产建议升级 CubeMaster 前确认新版本与旧版本迁移文件兼容受控场景先关掉自动迁移、人工核对再放开避免滚动期间多副本互相竞争 schema。️ 坑 6模板组件版本绑定失效stale replica0.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 做一次全量 dump0.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），仅供参考