系统架构

CubeSandbox 的架构可以先按“控制面”和“数据面”拆开看。控制面负责接收请求、调度、记录状态；数据面负责真正启动 MicroVM、准备存储、接入网络并执行安全策略。

控制面

组件	主要职责	读源码入口
CubeAPI	E2B 兼容 REST API、鉴权、请求转换	CubeAPI/src/
CubeMaster	调度、生命周期编排、模板中心、集群状态	CubeMaster/pkg/
Redis	沙箱元数据、生命周期事件、CubeProxy 路由信息	docs/zh/dev/redis-key-spec.md
WebUI	浏览器控制台，管理沙箱、模板、节点和版本	web/src/

控制面强调无状态服务加 Redis 协调。CubeAPI 与 CubeMaster 可以横向扩容，状态通过 Redis、数据库和节点上报保持一致。

数据面

组件	主要职责	读源码入口
Cubelet	节点本地生命周期管理、调用 containerd、对接 network-agent	Cubelet/
CubeShim	containerd Shim v2，准备 rootfs/内存/内核并拉起 VM	CubeShim/shim/
CubeHypervisor	KVM MicroVM 管理，启动、暂停、快照、恢复	hypervisor/
CubeCoW	rootfs 与内存文件的 CoW 快照、克隆、删除	cubecow/
CubeVS	eBPF 网络转发、NAT、策略、DNS 学习	Cubelet/network/ 与 network-agent/
CubeEgress	L7 出网代理、凭证注入、审计	CubeEgress/
CubeProxy	访问沙箱服务、自动恢复触发、路由	CubeProxy/

数据面强调“每个计算节点自治”。沙箱在哪个节点运行，相关的 VM、TAP、策略、日志和出网代理就主要在那台节点上完成。

一次创建请求怎么走

读这条链路时，先不用陷入每个 RPC 的细节，抓住四个转换：

1. REST 请求变成内部调度请求：CubeAPI 负责兼容 SDK。
2. 调度请求变成节点动作：CubeMaster 选择目标节点。
3. 节点动作变成 MicroVM：Cubelet、CubeShim、CubeHypervisor 协作。
4. 运行结果变成可访问服务：CubeProxy 和 Redis 路由元数据让外部请求找到沙箱。

存储路径

模板和快照能力的关键是 CubeCoW。简化模型如下：

OCI image
  -> rootfs artifact
  -> template rootfs + memory snapshot
  -> sandbox rootfs clone
  -> snapshot / rollback / clone

CubeSandbox 依赖 XFS reflink 与 FICLONE 实现高效 CoW。创建沙箱、创建快照和克隆分支时，尽量避免复制整份文件系统，而是让未修改的数据共享底层 extent。

网络路径

每个沙箱有自己的 TAP 设备。沙箱流量先进入 CubeVS eBPF 程序，再根据策略决定走普通 NAT、被拒绝，或进入 CubeEgress：

这也是为什么网络文档会同时出现 allow_internet_access、allow_out、deny_out 和 rules：前几个主要影响 CubeVS，rules 还会进入 CubeEgress 执行请求级判断。

安全边界

CubeSandbox 的安全不是单个开关，而是多层叠加：

层	边界
虚拟化	每个沙箱独立 Guest 内核，降低共享内核逃逸风险。
运行时	CubeHypervisor 使用最小化设备模型和 seccomp 加固。
网络	CubeVS 对每个沙箱执行出站策略，默认保护内部网段。
L7 代理	CubeEgress 可做域名过滤、路径过滤、凭证注入和审计。
API	CubeAPI 支持鉴权；生产暴露前必须做网络加固。

推荐阅读顺序

1. 架构概览：官方完整架构页。
2. CubeVS 网络模型：网络数据面深潜。
3. 沙箱生命周期：理解自动暂停、恢复与状态变化。
4. Redis Key 命名规范：读源码和排障时很有用。

下一步

继续阅读 环境与部署，把架构组件映射到实际安装后的端口、服务和目录。