环境与部署

CubeSandbox 需要能运行 KVM MicroVM 的 Linux 环境。学习阶段最重要的不是背命令，而是先选对部署路径。

部署路径怎么选

场景	推荐方式	适合人群
普通 x86_64 云服务器，没有 `/dev/kvm`	PVM 部署	快速体验、云上测试。
已有支持 KVM 的物理机或裸金属	裸金属 / 物理机部署	性能测试、生产验证。
需要多台计算节点	多机集群部署	平台团队、容量验证。
腾讯云自动化拉起集群	腾讯云 Terraform 部署	云上集群试验。
只想读代码和本地调试	开发环境 QEMU VM	贡献者、源码调试。
需要自定义构建产物	本地构建部署	修改组件、验证 PR。

如果只是学习和写第一个 Agent 示例，优先走快速开始或 PVM；如果你要测真实性能，尽量选择原生 KVM 或裸金属。

必须满足的条件

条件	为什么重要
root 权限	安装服务、加载内核模块、配置网络和 systemd 都需要 root。
Linux + KVM/PVM	MicroVM 需要虚拟化能力。
glibc >= 2.31	预构建二进制基于 Ubuntu 20.04 兼容基线。
`/data/cubelet` 使用 XFS reflink	CubeCoW 依赖 reflink 做高效快照和克隆。
至少 50 GB 可用磁盘	模板、rootfs、快照和可写层都在本地占空间。
可访问镜像和发布包	安装脚本需要下载 Release 包与容器镜像。

快速开始文档会给出更细的发行版说明。学习时记住一个关键点：ext4 上能跑很多东西，但 CubeSandbox 的 CoW 快照能力需要 XFS reflink。

快速安装的主线

PVM 快速体验通常是这四步：

安装 PVM 宿主机内核并重启。
运行一键安装脚本。
创建模板。
用 SDK 创建沙箱并执行代码。

核心命令形态如下，实际部署请以快速开始为准：

bash

curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh \
  | CUBE_PVM_ENABLE=1 MIRROR=cn bash

如果机器已经有原生 KVM，可以参考裸金属部署，不需要 PVM 内核步骤。

安装后应该看到什么

项	默认值 / 现象	用途
CubeAPI	`http://<host>:3000`	SDK 和 REST API 入口。
WebUI	`http://<host>:12088`	浏览器控制台。
CubeProxy	`cube.app` 或自定义域名	访问沙箱内服务。
Redis / MySQL	安装脚本管理	控制面状态与持久化数据。
`/data/cubelet`	本地数据目录	模板、沙箱卷、快照、运行时文件。
systemd targets	`cube-sandbox-*.service`	服务启停与日志查看。

安装完成后，先打开 WebUI 看节点是否 Ready，再创建或安装一个模板。不要急着写复杂 Agent；先确认“节点健康、模板 READY、沙箱能创建”这三个基础状态。

最小健康检查

在主机上可以先做这些检查：

bash

# KVM/PVM 是否可用
ls -la /dev/kvm
lsmod | grep kvm

# 关键 API 是否可达
curl -s http://127.0.0.1:3000/health || true

# WebUI 端口是否监听
ss -lntp | grep 12088 || true

# 数据目录文件系统
findmnt /data/cubelet

如果健康检查不通过，优先看部署排障、本地网段冲突和模板排障。

开发环境与生产环境的差异

开发环境更关注“能否调试代码”，生产环境更关注“可用、安全、可观测”：

关注点	开发 / 学习	生产 / 预生产
部署规模	单机即可	多节点或明确容量规划。
网络暴露	本机或内网访问	必须做鉴权、TLS、网络加固。
模板来源	官方预置或示例镜像	固定版本、可追溯构建、定期重建。
日志	临时查看	接入集中日志和审计保存。
升级	跟随 master 学习	对照 Release、变更日志、回滚方案。

下一步

继续阅读第一个沙箱，把安装后的 API、模板和 SDK 串起来。

环境与部署 ​

部署路径怎么选 ​

必须满足的条件 ​

快速安装的主线 ​

安装后应该看到什么 ​

最小健康检查 ​

开发环境与生产环境的差异 ​

下一步 ​