Cubesandbox

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/agent/ 全量 Rust 源码 目的: 系统性梳理 cube-agent (沙箱内 Guest Agent) 的架构、处理流程与安全配置 每节都带文件位置证据,可以直接引用。 1. 概述 cube-agent 是每个 MicroVM sandbox 内部的 PID 1 init 进程,派生自 Kata Containers agent。它作为沙箱内所有容器的根进程,管理容器生命周期、I/O 转发、网络配置和设备热插拔。 属性 值 语言 Rust 2021 edition 编译目标 x86_64-unknown-linux-musl (静态链接) 运行时间 tokio (多线程) 通信协议 ttrpc over vsock 协议端口 vsock:1024 (默认) OCI 运行时 rustjail (fork 隔离) 可观测性 Prometheus 指标 + OpenTelemetry vsock 导出 父进程 PID 1 (init) 构建系统 Makefile + cargo (SECCOMP 可配置) 核心职责:...

调研时间: 2026/07/07 调研范围: /home/zs/Develop/TraceCubeSandbox/CubeAPI/ 全量 Rust 源码 目的: 系统性梳理 CubeAPI (CubeSandbox 的 HTTP 网关) 的架构、处理流程与安全配置 配套文档: ../安全边界/T1-cubeapi-ingress.md (边界视角,本文档是"内部视角") 每节都带文件位置证据,可以直接引用。 1. 概述 CubeAPI 是 CubeSandbox 项目的 HTTP API 网关,对外提供 E2B-兼容的 REST API,让客户端能创建/查询/销毁 sandbox。 属性 值 语言 Rust (异步运行时 tokio) Web 框架 axum + tower (HTTP 路由 / 中间件) RPC 框架 ttrpc (与下游 CubeMaster / Cubelet 通信) 依赖 (Cargo.toml) axum = "0.7", tower-http, reqwest, utoipa, tokio, seccompiler 默认监听 0.0.0.0:3000 (可通过 --bind 改) 上游服务 CubeMaster (gRPC over ttrpc) 目标兼容 E2B OpenAPI (templateID, sandboxID, envVars, metadata) 核心职责:...

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/CubeEgress/ 全量 Lua + 配置 目的: 系统性梳理 CubeEgress (出站透明代理) 的架构、处理流程与安全配置 每节都带文件位置证据,可以直接引用。 1. 概述 CubeEgress 是 CubeSandbox 项目的出站透明代理,基于 OpenResty (nginx + LuaJIT) 构建,通过内核 TPROXY 透明地拦截来自 sandbox 的所有出站 TCP 80/443 流量并执行安全策略。 属性 值 语言 Lua (9 模块,~1800 行) + Bash (入口/脚本) 运行时 OpenResty (nginx + LuaJIT, TPROXY 补丁) 基础镜像 openresty-tproxy (自定义 nginx 1.29.2 + TPROXY) 监听地址 192.168.0.1:8080 (HTTP) + 192.168.0.1:8443 (HTTPS MITM) 管理 API 127.0.0.1:9090/admin/v1/ 上游证书验证 proxy_ssl_verify on, 深度 4 核心职责:...

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/Cubelet/ 全量 Go 源码 目的: 系统性梳理 Cubelet (CubeSandbox 的节点代理) 的架构、处理流程与安全配置 配套文档: security-boundaries/T3-cubelet.md (边界视角,本文档是"内部视角") 每节都带文件位置证据,可以直接引用。 1. 概述 Cubelet 是 CubeSandbox 的节点级代理,运行在每个物理计算节点上。它是 containerd 的 fork 扩展版本,增加了 MicroVM sandboxing 支持。 属性 值 语言 Go 1.24.8 + Rust (cubecow 存储引擎通过 CGo 链接) 运行时 containerd 扩展版 (OCI兼容) RPC 协议 ttrpc (与 CubeShim 通信) + gRPC (与 network-agent 通信) HTTP API 节点元数据上报 (与 CubeMaster) CLI 工具 cubecli (管理/调试) 存储后端 cubecow (XFS reflink 写时复制引擎) 网络后端 TAP 设备 + eBPF TC 过滤器 配置 TOML 配置文件 + YAML 动态热重载 核心职责:...

调研时间: 2026/07/07 调研范围: /home/zs/Develop/TraceCubeSandbox/CubeMaster/ 全量 Go 源码 + 配置 + 部署脚本 目的: 系统性梳理 CubeMaster (CubeSandbox 的控制面 + 调度器) 的架构、处理流程与安全配置 配套文档: ../安全边界/T2-operator-trust.md (边界视角,本文档是"内部视角") 每节都带文件位置证据,可以直接引用。 1. 概述 CubeMaster 是 CubeSandbox 项目的 控制面 + 调度中心,接收来自 CubeAPI 的 gRPC 请求,完成: 配置加载与 hotswap 热重载 沙箱规格 (sandboxspec) 处理与持久化 节点调度 (scheduler) 与下游 Cubelet 通信 (ttrpc) host-mount 路径白名单校验 模板中心 (templatecenter) 镜像拉取 元数据缓存 (Redis) 与状态存储 (MySQL) 属性 值 语言 Go (1.21+) RPC 框架 ttrpc (与上游 CubeAPI / 下游 Cubelet 通信) HTTP API http_port: 8089 (conf....

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/CubeNet/ 全量 Go + eBPF C 源码 目的: 系统性梳理 CubeNet (网络虚拟化 eBPF 数据面) 的架构、处理流程与安全配置 配套文档: security-boundaries/T4-cubenet-datapath.md (边界视角,本文档是"内部视角") 每节都带文件位置证据,可以直接引用。 1. 概述 CubeNet 是 CubeSandbox 的网络虚拟化与安全执行层,提供基于 eBPF 的内核态数据面,负责 sandbox 网络连接、NAT、策略执行和连接跟踪。 属性 值 语言 Go (用户态管理) + C (eBPF 内核数据面) eBPF 库 github.com/cilium/ebpf v0.17.3 TC 管理 github.com/florianl/go-tc 网卡管理 github.com/vishvananda/netlink (间接) vmlinux bpftool BTF dump (amd64 + arm64) 用户态包 cubevs (Go library) 内核态 src/*.bpf.c (BPF TC 程序) 诊断工具 cubevsmapdump (CLI) 依赖 (go....

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/CubeProxy/ 全量 Lua + Go 源码 目的: 系统性梳理 CubeProxy (数据面反向代理) 的架构、处理流程与安全配置 1. 概述 CubeProxy 是 CubeSandbox 的面向客户端的数据面反向代理，运行在 OpenResty (nginx + LuaJIT) 之上，负责将传入的 HTTP/HTTPS 请求路由到正确的 sandbox 容器后端。 属性 值 语言 Lua (数据面) + Go (sidecar 自动暂停/恢复) 运行时 OpenResty 1.21.4.1-6-alpine-fat sidecar Go 1.25.7 静态编译 (CGO_ENABLED=0, netgo+osusergo) 监听端口 8080 (TLS) + 8081 (明文) 管理 API 127.0.0.1:8082 (状态/元数据管理) sidecar HTTP 127.0.0.1:8083 (内部恢复端点) 服务发现 Redis (cube:v1:shared:sandbox:proxy:*) sidecar 流 Redis Stream (cube:v1:shared:sandbox:lifecycle:events) 上游服务 CubeMaster (HTTP POST /cube/sandbox/update) 构建方式 Go sidecar 主机静态编译 + COPY 进 Docker 镜像 核心职责:...

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/CubeShim/ 全量 Rust 源码 目的: 系统性梳理 CubeShim (containerd Shim v2) 的架构、处理流程与安全配置 配套文档: security-boundaries/T3-cubesandbox-node.md (边界视角,本文档是"内部视角") 每节都带文件位置证据,可以直接引用。 1. 概述 CubeShim 是 CubeSandbox 的 containerd Shim v2 实现 (io.containerd.cube.v2),作为 containerd 与 KVM MicroVM 之间的桥梁。 属性 值 语言 Rust 2021 edition (rust-toolchain 1.77.2) 框架 containerd-shim-rs (Shim v2 ttrpc) 依赖 (Cargo.toml) tokio, cube-hypervisor, containerd-shim, protobuf, ttrpc 二进制 containerd-shim-cube-rs (shim daemon) + cube-runtime (CLI 工具) 上游 containerd (通过 Shim v2 API) 下游 cube-agent (vsock/ttrpc) + cube-hypervisor (KVM) 核心职责:...

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/hypervisor/ 全量 Rust 源码 目的: 系统性梳理 cube-hypervisor (KVM VMM) 的架构、处理流程与安全配置 每节都带文件位置证据,可以直接引用。 1. 概述 cube-hypervisor 是 CubeSandbox 的 KVM 虚拟机监视器 (VMM),基于开源 Cloud Hypervisor 定制,负责任何 MicroVM 的创建、启动、暂停、恢复、快照等生命周期管理。 属性 值 语言 Rust 2021 edition (MSRV 1.77.0) 版本 28.0.0 基础项目 Cloud Hypervisor (开源 VMM) Hypervisor KVM (x86-64 + AArch64) + 可选 MSHV CLI clap 参数解析 日志 /data/log/CubeVmm/vmm.log 管理 API Unix socket HTTP REST API 程序化 API VmmInstance (mpsc 通道) 工作空间 26 个 crate 核心职责:...

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/network-agent/ 全量 Go 源码 目的: 系统性梳理 network-agent (节点网络编排代理) 的架构、处理流程与安全配置 配套文档: 暂无独立安全边界文档 (进程边界隶属于 Cubelet 节点域) 1. 概述 network-agent 是 CubeSandbox 的节点级网络编排组件,从 Cubelet 中拆分出的独立守护进程,负责管理计算节点上沙箱的 TAP 设备、IP 分配、端口代理和 eBPF 集成。 属性 值 语言 Go 1.24.8 API 协议 HTTP + gRPC + Unix socket (SCM_RIGHTS) 健康检查 127.0.0.1:19090 IPAM CIDR 192.168.0.0/18 (默认) 端口范围 20000-29999 状态存储 JSON 文件持久化 依赖 cubevs (CubeNet eBPF 库), cubelog, CubeEgress 通信 localhost loopback (Unix socket + TCP) 核心职责:...