Hypervisor (cube-hypervisor) 架构、处理流程与安全配置

调研时间: 2026/07/08 调研范围: /home/zs/Develop/TraceCubeSandbox/hypervisor/ 全量 Rust 源码 目的: 系统性梳理 cube-hypervisor (KVM VMM) 的架构、处理流程与安全配置

每节都带文件位置证据,可以直接引用。

1. 概述

cube-hypervisor 是 CubeSandbox 的 KVM 虚拟机监视器 (VMM),基于开源 Cloud Hypervisor 定制,负责任何 MicroVM 的创建、启动、暂停、恢复、快照等生命周期管理。

核心职责:

• KVM VM 生命周期 (create/boot/pause/resume/shutdown/delete)
• vCPU/内存/设备分配与管理
• virtio 设备模拟 (block/net/console/rng/balloon/vsock/fs)
• 设备热插拔 (CPU/内存/PCI)
• 快照与恢复 (内存 + 设备状态)
• 实时迁移 (live migration)
• 安全隔离 (seccomp + umask + TDX/SGX)

2. 架构

2.1 顶层目录结构

hypervisor/
├── Cargo.toml                    # Workspace 根, 26 个成员
├── src/
│   ├── main.rs                   # CLI 入口 + seccomp + VMM 启动
│   ├── lib.rs                    # VmmInstance 导出
│   ├── common.rs                 # 日志配置 + core dump 默认值
│   └── vmm_config.rs             # VmmConfig 结构
├── vmm/                          # 核心 VMM crate
│   └── src/
│       ├── lib.rs                # Vmm 主循环 (epoll)
│       ├── vm.rs                 # Vm 结构体 (生命周期)
│       ├── vm_config.rs          # VmConfig + 子配置
│       ├── cpu.rs                # vCPU 管理 + seccomp
│       ├── memory_manager.rs     # 内存管理 (hugepages/NUMA)
│       ├── device_manager.rs     # 设备管理 + virtio 初始化
│       ├── migration.rs          # 实时迁移 + 快照
│       ├── api/mod.rs            # ApiRequest/ApiResponse 定义
│       ├── api/service.rs        # VMM_SERVICE 全局单例
│       ├── api/http/mod.rs       # HTTP REST API 服务器
│       ├── api/http/http_endpoint.rs # HTTP 端点处理器
│       ├── seccomp_filters.rs    # Seccomp BPF 定义
│       ├── config.rs             # CLI 配置解析
│       ├── coredump.rs           # Guest coredump 支持
│       ├── acpi.rs               # ACPI 表生成
│       ├── interrupt.rs          # 中断管理
│       ├── serial_manager.rs     # 串口管理
│       ├── pci_segment.rs        # PCI 段管理
│       ├── pagemap_anon.rs       # 匿名页映射
│       ├── soft_dirty.rs         # 软脏页跟踪
│       ├── clone3.rs             # clone3 系统调用封装
│       └── gdb.rs                # GDB 调试支持
├── hypervisor/                   # Hypervisor 抽象层
│   ├── src/lib.rs                # HypervisorType enum + new() 工厂
│   ├── src/hypervisor.rs         # Hypervisor trait
│   ├── src/vm.rs                 # Vm/VmOps trait
│   ├── src/cpu.rs                # Vcpu trait + VmExit
│   ├── src/device.rs             # Device trait
│   ├── src/arch/                 # 架构相关 (x86_64 + AArch64)
│   └── src/kvm/                  # KVM 实现 (kvm ioctl 封装)
├── virtio-devices/               # virtio 设备模拟 (block/net/console/rng/fs/vsock)
├── devices/                      # 传统设备 (serial/RTC/i8042/SysCtrl)
├── pci/                          # PCI 总线 + 配置空间
├── net_util/                     # 网络工具 (TAP/MACVTAP)
├── block_util/                   # 块设备工具 (QCOW/VHDX/raw)
├── qcow/ / vhdx/                 # 磁盘格式支持
├── vm-migration/                 # 快照/迁移协议
├── vm-virtio/                    # virtio 队列/传输层
├── vhost_user_block/             # vhost-user 块后端
├── vhost_user_net/               # vhost-user 网络后端
├── virtiofsd/                    # virtio-fs 共享文件系统
├── vfio_user/                    # VFIO user 设备
├── tpm/                          # TPM 设备
├── vm-device/                    # 设备总线抽象
├── vm-allocator/                 # 地址空间分配器
├── acpi_tables/                  # ACPI 表生成
└── docs/                         # 30+ Markdown 文档

2.2 模块分层

┌──────────────────────────────────────────────────────────┐
│  入口层                                                    │
│    • main.rs — CLI parsing + seccomp + VMM 线程启动       │
│    • lib.rs — VmmInstance 封装 (mpsc 通道)                │
├──────────────────────────────────────────────────────────┤
│  VMM 层 (核心控制循环)                                      │
│    • vmm/lib.rs — epoll 事件循环                            │
│    • vmm/vm.rs — VM 生命周期管理                           │
│    • vmm/api/ — ApiRequest + HTTP REST API + service       │
├──────────────────────────────────────────────────────────┤
│  资源管理层                                                │
│    • vmm/cpu.rs — vCPU 线程 + seccomp                     │
│    • vmm/memory_manager.rs — 内存分区 + 大页              │
│    • vmm/device_manager.rs — 总线 + 设备                   │
├──────────────────────────────────────────────────────────┤
│  虚拟设备层                                                │
│    • virtio-devices/ — block/net/console/rng/fs/vsock    │
│    • devices/ — 串口/RTC/键盘/SysCtrl                     │
│    • pci/ — PCI 总线 + 配置空间                            │
├──────────────────────────────────────────────────────────┤
│  Hypervisor 抽象层                                         │
│    • hypervisor/ — KVM/MSHV/Vcpu/Vm trait                │
│    • hypervisor/src/kvm/ — KVM ioctl 封装                 │
│    • hypervisor/src/arch/ — x86_64 + AArch64 架构支持     │
└──────────────────────────────────────────────────────────┘

2.3 交互关系

┌──────────────┐   VmmInstance (mpsc)   ┌──────────────────┐
│   CubeShim   │ ─────────────────────▶│  cube-hypervisor  │
│  (Rust)      │   ApiRequest           │  (KVM VMM)       │
│              │ ◀─────────────────────│                   │
│              │   ApiResponse          │                   │
└──────────────┘                        └────────┬─────────┘
                                                 │ KVM ioctl
                                                 ▼
                                          ┌──────────────┐
                                          │   Linux KVM   │
                                          │  (内核模块)    │
                                          └──────────────┘

3. 处理流程

3.1 VM 创建与启动

CubeShim                     cube-hypervisor                     KVM
  │                              │                              │
  │ VmmInstance::new()           │                              │
  │ ────────────────────────────▶│                              │
  │                              │                              │
  │                              │ ① src/lib.rs                  │
  │                              │   - 设置日志/seccomp          │
  │                              │   - 创建 api channel          │
  │                              │   - 启动 VMM 线程             │
  │                              │                              │
  │                              │ ② vmm/lib.rs                  │
  │                              │   - epoll 事件循环启动        │
  │                              │   - HTTP API 线程             │
  │                              │                              │
  │ ApiRequest::VmCreate         │                              │
  │ ────────────────────────────▶│                              │
  │                              │ ③ vmm/vm.rs                   │
  │                              │   - hypervisor.create_vm()   │
  │                              │   - KVM_CREATE_VM            │
  │                              │   - 创建内存区域              │
  │                              │ ──────────────────────────▶ │ KVM_CREATE_VM
  │                              │                              │
  │ ApiRequest::VmBoot           │                              │
  │ ────────────────────────────▶│                              │
  │                              │ ④ vmm/cpu.rs                  │
  │                              │   - KVM_CREATE_VCPU          │
  │                              │   - vCPU 线程启动 + seccomp  │
  │                              │                              │
  │                              │ ⑤ vmm/device_manager.rs      │
  │                              │   - virtio 设备创建           │
  │                              │   - vsock/virtio-net/...     │
  │                              │                              │
  │                              │ ⑥ PVH direct boot             │
  │                              │   - 加载内核 vmlinux          │
  │                              │   - 设置 cmdline             │
  │                              │   - KVM_RUN (vCPU 运行)      │
  │                              │                              │
  │ NotifyEvent::VsockServerReady│                              │
  │ ◀───────────────────────────│                              │
  │                              │                              │

关键文件位置:

• VmmInstance 创建: hypervisor/src/lib.rs:86-257 (VmmInstance::new)
• VMM 循环: hypervisor/vmm/src/lib.rs (start_vmm_thread)
• VM 管理: hypervisor/vmm/src/vm.rs (Vm 结构体)
• vCPU 管理: hypervisor/vmm/src/cpu.rs (CpuManager)
• 设备管理: hypervisor/vmm/src/device_manager.rs (DeviceManager)
• Seccomp: hypervisor/vmm/src/seccomp_filters.rs (get_seccomp_filter)

3.2 快照创建

来源: hypervisor/vmm/src/migration.rs

CubeShim                     cube-hypervisor
  │                              │
  │ ApiRequest::VmSnapshot       │
  │ ────────────────────────────▶│
  │                              │
  │                              │ ① 暂停 VM (pause)            │
  │                              │ ② 保存 vCPU 状态              │
  │                              │ ③ 保存内存快照 (逐步复制)     │
  │                              │ ④ 保存设备状态                │
  │                              │    - state.json                │
  │                              │    - config.json               │
  │                              │    - memory 快照文件           │
  │                              │ ⑤ 恢复 VM (resume)            │
  │                              │                              │
  │ SnapshotInfo ◀──────────────│
  │                              │

关键常量:

// vmm/src/migration.rs:17-18
pub const SNAPSHOT_STATE_FILE: &str = "state.json";
pub const SNAPSHOT_CONFIG_FILE: &str = "config.json";

3.3 vCPU 线程安全

来源: hypervisor/vmm/src/cpu.rs

① CpuManager::create_vcpu()
   - KVM_CREATE_VCPU ioctl
   - 分配 vCPU ID + 事件 fd
   - 启动独立线程

② 每 vCPU 线程:
   - apply_seccomp_filter() — 应用最小 syscall 集
   - KVM_RUN 循环
   - VmExit 事件处理:
     • IoIn/IoOut → PIO 处理
     • MmioRead/MmioWrite → MMIO 处理
     • Hypercall → 超调用处理
     • Shutdown → VM 关闭

③ vCPU 热插拔:
   - 新增 vCPU → 创建新线程 + seccomp
   - 删除 vCPU → 停止线程 + 清理

4. 路由与端点

4.1 HTTP REST API (Unix socket)

来源: hypervisor/vmm/src/api/http/http_endpoint.rs + vmm/src/api/http/mod.rs

前缀: /api/v1

4.2 程序化 API (VmmInstance)

来源: hypervisor/src/lib.rs:69-358

// hypervisor/src/lib.rs
pub struct VmmInstance {
    vmm_thread: Option<JoinHandle<Result<(), VmmError>>>,
}

impl VmmInstance {
    pub fn new(config: VmmConfig) -> Result<Self, Error>;
    pub fn send_request(&self, request: ApiRequest) -> Result<ApiResponse, Error>;
    pub fn join(&mut self) -> Result<(), Error>;
    pub fn join_timeout(&mut self, timeout: Option<Duration>) -> Result<(), Error>;
}

4.3 VMM_SERVICE 全局单例

来源: hypervisor/vmm/src/api/service.rs:14-90

// vmm/src/api/service.rs:14-16
lazy_static! {
    pub static ref VMM_SERVICE: Mutex<VmmService> = Mutex::new(VmmService::new());
}

VMM_SERVICE 是一个全局静态单例,管理 VMM 线程与外部之间的 mpsc 通道。send_request() 发送 ApiRequest 后通过 EventFd 通知 VMM 线程,然后阻塞等待 ApiResponse。

5. 安全机制

5.1 Seccomp BPF 过滤

来源: hypervisor/vmm/src/seccomp_filters.rs

每个线程类型有独立的 seccomp 策略:

// vmm/src/seccomp_filters.rs:21-28
pub enum Thread {
    Api,             // HTTP API 线程
    SignalHandler,   // 信号处理线程
    Vcpu,            // vCPU 线程 (最小 syscall 集)
    Vmm,             // VMM 控制线程
    PtyForeground,   // PTY 前台线程
    All,             // 通用白名单
}

seccomp 模式 (CLI --seccomp):

5.2 安全特性

5.3 Core Dump 配置

来源: hypervisor/src/common.rs:20-27 + hypervisor/src/main.rs:541-565

// common.rs:20-27
pub fn default_coredump_filter() -> String {
    "0x33".to_string()  // 默认过滤 mask
}
pub fn default_coredump_limit() -> u64 {
    2 * 1024 * 1024 * 1024  // 2GB limit
}

实际应用 (main.rs:560-565):

• 写入 /proc/self/coredump_filter (默认 0x33)
• setrlimit(Resource::CORE, 2GB) 限制大小

5.4 内存保护

来源: hypervisor/vmm/src/memory_manager.rs

5.5 umask 加固

来源: hypervisor/src/main.rs:748

let _ = unsafe { libc::umask(0o077) };

所有新创建的文件仅 owner 可读写,组和其他用户无权限。

6. 配置项

6.1 VMM 配置 (VmmConfig)

来源: hypervisor/src/vmm_config.rs:11-41

pub struct VmmConfig {
    pub core_dump: Option<CoreDumpConfig>,
    pub event_monitor: Option<EventMonitorConfig>,
    pub gdb: Option<GdbConfig>,
    pub log_file: String,                    // "/data/log/CubeVmm/vmm.log"
    pub log_json_file: Option<String>,       // "/data/log/CubeVmm/vmm.json"
    pub log_level: LevelFilter,              // "info"
    pub log_stderr: bool,
    pub sandbox_id: String,                  // "cube-hypervisor"
    pub seccomp: SeccompAction,              // KillProcess
    pub event_notifier: Option<EventNotifyConfig>,
    pub http_path: Option<String>,
}

6.2 VM 配置 (VmConfig)

来源: hypervisor/vmm/src/vm_config.rs

6.3 启动示例

# 最小启动 (CLI)
./cube-hypervisor --kernel vmlinux --cmdline "console=ttyS0" \
    --disk path=rootfs.img --cpus 1 --memory size=512M \
    --vsock cid=3

# 程序化 (通过 CubeShim)
let instance = VmmInstance::new(config)?;
instance.send_request(ApiRequest::VmCreate(vm_config))?;
instance.send_request(ApiRequest::VmBoot)?;

7. 关键文件清单

8. API 请求枚举

来源: hypervisor/vmm/src/api/mod.rs

pub enum ApiRequest {
    VmCreate(Box<VmConfig>),
    VmBoot,
    VmDelete,
    VmInfo,
    VmPause,
    VmResume,
    VmShutdown,
    VmReboot,
    VmSnapshot(SnapshotConfig),
    VmRestore(Option<RestoreConfig>),
    VmSendMigration(VmSendMigrationData),
    VmReceiveMigration(VmReceiveMigrationData),
    VmAddDevice(Box<DeviceConfig>),
    VmAddDisk(Box<DiskConfig>),
    VmAddFs(Box<FsConfig>),
    VmAddNet(Box<NetConfig>),
    VmAddPmem(Box<PmemConfig>),
    VmAddVsock(Box<VsockConfig>),
    VmAddUserDevice(Box<UserDeviceConfig>),
    VmAddVdpa(Box<VdpaConfig>),
    VmRemoveDevice(Box<PciBdf>),
    VmResize(VmResizeData),
    VmResizeZone(VmResizeZoneData),
    VmCounters,
    VmPowerButton,
    VmmPing,
    VmmShutdown,
    // ... (guest_debug 特性相关)
}

9. 安全注意事项

9.1 已知风险

9.2 Seccomp 可配置风险

来源: hypervisor/src/main.rs:631-643

let seccomp_action = if let Some(seccomp_value) = cmd_arguments.get_one::<String>("seccomp") {
    match seccomp_value as &str {
        "true" => SeccompAction::Trap,
        "false" => SeccompAction::Allow,     // ⚠️ 可完全禁用 seccomp
        "log" => SeccompAction::Log,
        "process" => SeccompAction::KillProcess,
        // ...
    }
};

虽然默认值是 KillProcess,但 --seccomp false 可完全禁用 seccomp 过滤。生产部署不应传递此参数。

9.3 API 安全

• HTTP API 通过 Unix socket 暴露 (默认 --api-socket path)
• 无内置认证机制 — 安全依赖 socket 文件权限
• CubeShim 通过 VmmInstance (mpsc 通道) 调用,绕过 HTTP 层

9.4 信息泄露面

• seccomp log 模式可能通过日志泄露 syscall 模式
• 快照文件包含完整 guest 内存状态,需文件权限保护
• GDB 调试功能 (feature = “guest_debug”) 可能暴露 guest 寄存器状态

10. 与 SVG 边界模型的关系

11. 特殊特性

11.1 日志系统

来源: hypervisor/src/common.rs:36-257

cube-hypervisor 使用自定义 Logger 实现,支持:

• 异步日志 (defer_logger_thread): 初始化阶段缓冲日志,vCPU 启动后切换异步线程
• 日志轮转: 通过 LOG_CTRL_REOPEN 目标触发文件重开
• 格式: {sandbox_id} --- {ms} --- {level} --- <{thread}> {file}:{line} -- {msg}

11.2 Hypervisor 抽象层

来源: hypervisor/hypervisor/src/lib.rs:71-85

pub fn new() -> std::result::Result<Arc<dyn Hypervisor>, HypervisorError> {
    #[cfg(feature = "kvm")]
    if kvm::KvmHypervisor::is_available()? {
        return kvm::KvmHypervisor::new();
    }
    #[cfg(feature = "mshv")]
    if mshv::MshvHypervisor::is_available()? {
        return mshv::MshvHypervisor::new();
    }
    Err(HypervisorError::HypervisorCreate(anyhow!("no supported hypervisor")))
}

支持多种 Hypervisor 后端:

• KVM (Linux 默认, feature = “kvm”)
• MSHV (Microsoft Hypervisor, feature = “mshv”, x86_64 only)
• KVM-PVM (KVM para-virtualized mode)

11.3 TDX / SGX 支持

• TDX (Intel Trust Domain Extensions): 通过 #[cfg(feature = "tdx")] 条件编译,在 PlatformConfig 中配置 tdx: bool,使用 KVM_MEMORY_ENCRYPT_OP ioctl
• SGX EPC (Intel Software Guard Extensions Enclave Page Cache): 通过 SgxEpcConfig 结构配置 EPC 区域大小

12. 总结

1. Cloud Hypervisor 分支: 继承 Cloud Hypervisor 生态 (Rust, KVM 原生, virtio 设备栈)
2. KVM 原生性能: 直接 KVM ioctl,无额外抽象层
3. 每线程 seccomp: 6 种线程各有独立 syscall 白名单
4. 快照/迁移: 内存 + 设备状态完整序列化 (state.json + config.json)
5. TDX/SGX: 支持机密计算场景
6. 双 API: HTTP REST (Unix socket) + 程序化 VmmInstance (mpsc)
7. Hypervisor 抽象: 支持 KVM/MSHV 多后端切换
8. umask 加固: 所有文件默认仅 owner 访问
9. core dump 控制: filter + limit 防止敏感信息泄露