万字深度解析 CubeSandbox：当 AI Agent 遇见微虚拟机革命——从 KVM 硬件隔离到亚秒级启动的完整技术指南（2026）

当 AI Agent 开始自动执行代码、操作文件系统、调用外部 API，一个根本性问题浮出水面：你敢让 LLM 生成的代码直接在你的机器上跑吗？ CubeSandbox 给出了一个令人兴奋的答案——基于 RustVMM 和 KVM 的微虚拟机，<60ms 冷启动，<5MB 内存开销，硬件级隔离，E2B 无缝兼容。本文从第一性原理出发，深度解析 AI Agent 沙箱的技术本质、CubeSandbox 的架构内幕，以及生产级部署的完整实战。

目录

1. 引言：AI Agent 的代码执行困境
2. 从 Docker 到 microVM：沙箱技术演进史
3. CubeSandbox 架构全景：六大组件协同
4. RustVMM + KVM：亚秒级启动的性能魔法
5. CubeCoW 写时复制：百毫秒级快照与克隆
6. 硬件级隔离：为什么 KVM 比 Docker 更安全
7. E2B 无缝迁移：一行环境变量切换沙箱后端
8. 凭证保险库与 Egress 控制：零信任 Agent 架构
9. 生产级部署：从单节点到 Kubernetes 集群
10. 性能基准测试：与 E2B/Daytona/Firecracker 对比
11. 代码实战：Python + TypeScript SDK 完整示例
12. 深度思考：AI Agent 基础设施的下一个三年

1. 引言：AI Agent 的代码执行困境

1.1 问题的本质

2026 年，AI Agent 已经从"聊天机器人"进化为"自主执行引擎"。它们能够：

• 自动生成并执行代码（Code Interpreter、OpenDevin、Sweep）
• 操作文件系统（读写文件、安装依赖、运行脚本）
• 调用外部 API（支付接口、数据库、第三方服务）
• 访问网络（爬虫、API 调用、数据传输）

这带来了一个之前从未如此紧迫的安全问题：

LLM 生成的代码 → 直接在宿主机执行 = 灾难

真实的攻击面包括：

1.2 现有方案的局限性

在 CubeSandbox 出现之前，业界主要有以下几种方案：

方案 A：Docker 容器

# 最简单粗暴的方式
docker run -i --rm python:3.11 python3 -c "print('Hello from container')"

• ✅ 易于理解，生态成熟
• ❌ 共享宿主机内核，逃逸漏洞屡见不鲜（Dirty COW、runc CVE-2019-5736 等）
• ❌ 冷启动慢（1~5 秒），高密度部署时资源开销大
• ❌ 不适合多租户场景（需要复杂的 namespace/seccomp/AppArmor 配置）

方案 B：gVisor（Google）

Google 为 GKE 开发的用户态内核，用 Go 实现系统调用拦截。

• ✅ 不共享宿主机内核，安全性较好
• ❌ 系统调用兼容性差（不支持 io_uring、bpf 等新特性）
• ❌ 性能开销大（系统调用经过用户态转发，延迟高）
• ❌ 不支持 ptrace、部分 epoll 行为，调试困难

方案 C：Firecracker（AWS Lambda）

AWS 为 Lambda 和 Fargate 开发的 VMM（Virtual Machine Monitor），用 Rust 实现。

• ✅ 硬件虚拟化，安全性极佳
• ✅ 启动快（~125ms），内存开销小（~5MB）
• ❌ 只支持 Linux 内核，无法运行 Windows/macOS
• ❌ API 相对底层，需要自己封装管理逻辑
• ❌ 网络配置复杂（需要配置 TUN/TAP 或 MacVTAP）

方案 D：E2B（开源 SaaS）

专门为 AI Agent 设计的沙箱服务，提供 SDK 和云端沙箱。

• ✅ 开箱即用，SDK 友好（Python/TypeScript）
• ✅ 自动管理生命周期（创建、暂停、销毁）
• ❌ 闭源云服务，数据需要发送到 E2B 的服务器
• ❌ 自定义部署困难，无法在企业内网使用
• ❌ 成本随用量增长（按沙箱时长计费）

1.3 CubeSandbox 的破局之处

CubeSandbox 由腾讯云团队开源，精准地解决了上述所有痛点：

CubeSandbox = Firecracker 级安全 + E2B 级易用性 + 自部署自由度

核心指标：

2. 从 Docker 到 microVM：沙箱技术演进史

要真正理解 CubeSandbox 的价值，我们需要回顾沙箱技术的演进历程。这是一段从"隔离进程"到"隔离操作系统"到"隔离硬件"的进化史。

2.1 第一代：chroot（1979）

最早的隔离机制，只是把进程的根目录"绑架"到某个文件夹：

# 创建一个最小的 chroot 环境
mkdir -p /tmp/mychroot/bin /tmp/mychroot/lib
cp /bin/bash /tmp/mychroot/bin/
ldd /bin/bash | grep -o '/lib/[^ ]*' | xargs -I {} cp --parents {} /tmp/mychroot/

chroot /tmp/mychroot /bin/bash

• ✅ 实现简单，零开销
• ❌ 完全不安全：进程仍然可以看到其他进程、访问 /proc、/sys，root 用户可以直接 escape

2.2 第二代：Linux Namespace + Cgroups（2002~2007）

Docker 的核心技术，通过内核特性实现进程隔离：

// Go 代码示例：使用 syscall 创建新的 UTS namespace
package main

import (
    "os"
    "os/exec"
    "syscall"
)

func main() {
    cmd := exec.Command("/bin/bash")
    cmd.SysProcAttr = &syscall.SysProcAttr{
        Cloneflags: syscall.CLONE_NEWUTS |  // 主机名隔离
                    syscall.CLONE_NEWPID |  // PID 隔离
                    syscall.CLONE_NEWNS |   // 挂载点隔离
                    syscall.CLONE_NEWNET,  // 网络隔离
    }
    cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
    cmd.Run()
}

Namespaces 的七种隔离维度：

致命缺陷：所有容器共享同一个内核。如果内核有漏洞（如 dirtycow、ptrace 漏洞），一个容器可以逃逸到宿主机，影响所有其他容器。

2.3 第三代：用户态内核（gVisor，2018）

Google 的解决方案：用 Go 实现一个"伪内核"，拦截所有系统调用：

应用进程 → Sentry（gVisor 用户态内核）→ 宿主系统调用（仅安全的部分）

• ✅ 应用看不到真实内核，攻击面大幅缩小
• ❌ 系统调用兼容性只有 ~70%，很多应用无法运行
• ❌ 性能损失 30~50%（每次系统调用都要经过用户态转发）

2.4 第四代：microVM（Firecracker，2018）

AWS 的破局之作：用 KVM（Kernel-based Virtual Machine）实现硬件辅助虚拟化，每个"容器"其实是一个完整的虚拟机，但有极小的内存开销和极快的启动速度。

传统虚拟机（QEMU/KVM）：
  QEMU（模拟整个硬件） → KVM → 物理硬件
  启动时间：10~30 秒，内存开销：512MB+

microVM（Firecracker）：
  Firecracker（只模拟最小设备） → KVM → 物理硬件
  启动时间：~125ms，内存开销：~5MB

Firecracker 做了几个关键减法：

1. 只模拟最少的硬件设备：一个 virtio-net 网卡、一个 virtio-block 磁盘、一个 serial 控制台（没有 USB、没有 GPU、没有 audio）
2. 用 KVM 的 ioctl(KVM_RUN) 直接运行客户机代码：不需要 QEMU 的二进制翻译
3. 用 Rust 实现 VMM：内存安全，无 GC 停顿

2.5 第五代：AI Agent 原生沙箱（CubeSandbox，2026）

CubeSandbox 站在 Firecracker 的肩膀上，但针对 AI Agent 场景做了深度优化：

Firecracker（通用 microVM）= 基础能力
    +
CubeSandbox（AI Agent 专属）= Firecracker + Agent 管理能力 + E2B 兼容层 + 凭证保险库

关键创新：

1. CubeCoW（Copy-on-Write）快照引擎：可以在 100ms 内克隆一个完整的沙箱（包括内存状态）
2. Credential Vault（凭证保险库）：Agent 调用外部 API 时，Key 不进入沙箱，由代理网关注入
3. E2B Compatible API：不需要改代码，改一个环境变量就切换到自部署沙箱
4. WebUI Dashboard：可视化监控所有沙箱状态、资源使用、模板版本

3. CubeSandbox 架构全景：六大组件协同

CubeSandbox 采用微服务架构，各组件职责清晰，可以独立部署和扩展。

3.1 架构总览

                        ┌─────────────────────────────────────┐
                        │          AI Agent / SDK             │
                        │   (Python/TypeScript/REST API)     │
                        └──────────────┬──────────────────────┘
                                       │ HTTPS (E2B Compatible)
                                       ▼
                        ┌─────────────────────────────────────┐
                        │        CubeAPI (REST Gateway)        │  ← 对外统一接口
                        │   认证 / 限流 / 请求路由 / 计费     │
                        └──────────────┬──────────────────────┘
                                       │ gRPC / HTTP
                  ┌────────────────────┼────────────────────────┐
                  ▼                    ▼                        ▼
        ┌──────────────┐   ┌──────────────────┐   ┌──────────────────┐
        │  CubeMaster   │   │   CubeProxy       │   │   CubeEgress     │
        │  (调度中枢)    │   │   (流量代理)       │   │   (出口网关)      │
        │               │   │                   │   │                   │
        │ - 沙箱调度    │   │ - WebSocket 转发  │   │ - 凭证注入        │
        │ - 资源分配    │   │ - 文件上传/下载   │   │ - Egress 过滤    │
        │ - 健康检查    │   │ - 端口映射        │   │ - 审计日志        │
        └──────┬────────┘   └──────────────────┘   └──────────────────┘
               │
               ▼
        ┌──────────────┐
        │   Cubelet     │   ← 每台物理机上的 Agent
        │  (节点 Agent) │
        │               │
        │ - 管理本地沙箱 │
        │ - 调用 KVM     │
        │ - 收集指标     │
        └──────┬────────┘
               │ ioctl(KVM_RUN)
               ▼
        ┌──────────────┐
        │  RustVMM     │   ← 用 Rust 实现的 VMM
        │  (VMM 引擎)  │
        │               │
        │ - 内存管理    │
        │ - vCPU 调度   │
        │ - virtio 设备 │
        └──────┬────────┘
               │ /dev/kvm
               ▼
        ┌──────────────┐
        │   Linux KVM  │   ← 内核模块，硬件辅助虚拟化
        └──────────────┘

3.2 核心组件详解

CubeAPI：统一接入网关

# CubeAPI 的配置示例（简化版）
server:
  listen: 0.0.0.0:8080
  tls:
    cert: /etc/cubesandbox/tls/cert.pem
    key: /etc/cubesandbox/tls/key.pem

auth:
  mode: jwt  # 或 "api_key" / "none"（开发环境）
  jwt_secret: ${JWT_SECRET}

ratelimit:
  enabled: true
  requests_per_minute: 1000

cors:
  allowed_origins:
    - "https://your-agent-frontend.com"

CubeAPI 完全兼容 E2B 的 API 规范，这意味着：

# 原来连接 E2B Cloud 的代码
import os
from e2b import Sandbox

sandbox = Sandbox()  # 默认连接 E2B Cloud

# 切换到 CubeSandbox，只需要改一个环境变量
os.environ["E2B_API_URL"] = "http://your-cubesandbox:8080"
os.environ["E2B_API_KEY"] = "your-cubesandbox-token"

sandbox = Sandbox()  # 现在连接的是自部署的 CubeSandbox

CubeMaster：调度中枢

CubeMaster 是整个系统的"大脑"，负责：

1. 沙箱调度：决定在哪个节点上创建沙箱（考虑资源余量、亲和性、反亲和性）
2. 模板管理：管理操作系统镜像（template），支持版本控制和增量更新
3. 健康检查：定期检查 Cubelet 的心跳，标记离线节点

调度算法伪代码：

def schedule_sandbox(request):
    """为新的沙箱选择合适的节点"""
    candidate_nodes = []
    
    for node in all_nodes:
        if not node.is_healthy():
            continue
        if node.available_memory < request.memory_mb:
            continue
        if node.available_vcpus < request.vcpu_count:
            continue
        # 检查模板是否已缓存到该节点（避免网络传输镜像）
        if node.has_template(request.template_id):
            node.template_cached_bonus = 100  # 优先级加分
        candidate_nodes.append(node)
    
    # 按资源余量排序（Bin Pack 策略）
    candidate_nodes.sort(key=lambda n: n.available_memory, reverse=True)
    
    if not candidate_nodes:
        raise NoAvailableNodeError()
    
    return candidate_nodes[0]

Cubelet：节点 Agent

Cubelet 运行在每一台物理机上，是沙箱的"接生婆"：

// Rust 伪代码：Cubelet 创建沙箱的核心逻辑
pub async fn create_sandbox(&self, req: CreateSandboxRequest) -> Result<Sandbox> {
    // 1. 分配资源（内存 + vCPU）
    let memory_region = self.allocate_memory(req.memory_mb)?;
    let vcpus = self.allocate_vcpus(req.vcpu_count)?;
    
    // 2. 加载模板（Kernel + Root FS）
    let kernel = self.template_cache.get_kernel(req.template_id)?;
    let rootfs = self.template_cache.get_rootfs(req.template_id)?;
    
    // 3. 创建 KVM 虚拟机
    let vm = RustVMM::new()
        .with_memory(memory_region)
        .with_vcpus(vcpus)
        .with_kernel(kernel)
        .with_rootfs(rootfs)
        .with_network(self.create_tap_device()?)
        .build()?;
    
    // 4. 启动（ioctl(KVM_RUN)）
    vm.start()?;
    
    // 5. 等待 Guest OS 启动完成（通过 serial 控制台握手）
    vm.wait_for_boot_complete(Duration::from_secs(5)).await?;
    
    Ok(Sandbox { vm, metadata: req.metadata })
}

RustVMM：内存安全的 VMM 引擎

CubeSandbox 使用 Rust 实现 VMM（Virtual Machine Monitor），替代 Firecracker 的某些组件，主要优势：

1. 内存安全：Rust 的所有权系统消除了 use-after-free、double-free 等内存安全漏洞
2. 零成本抽象：高阶抽象（trait、泛型）在编译期被优化掉，运行时性能和 C 相当
3. async/await 原生支持：用 tokio 处理并发 I/O（网络包处理、磁盘 I/O）

RustVMM 的核心数据结构：

/// 表示一个虚拟机的完整状态
pub struct VirtualMachine {
    /// KVM 文件描述符（/dev/kvm）
    kvm_fd: Arc<KvmFd>,
    
    ///  guest 内存布局
    memory: GuestMemory,
    
    /// vCPU 列表
    vcpus: Vec<Vcpu>,
    
    /// virtio 设备（网络、磁盘、console）
    devices: DeviceManager,
    
    /// 快照状态（用于 CubeCoW）
    snapshot_state: Option<SnapshotState>,
}

impl VirtualMachine {
    /// 冷启动一个虚拟机
    pub fn start(&mut self) -> Result<()> {
        // 1. 设置内存布局（把 guest 物理内存映射到 host 虚拟内存）
        self.setup_memory()?;
        
        // 2. 加载 Kernel（bzImage 格式，x86_64）
        self.load_kernel()?;
        
        // 3. 设置 boot parameters（cmdline）
        self.setup_cmdline()?;
        
        // 4. 启动 vCPU 线程（每个 vCPU 一个线程，运行 KVM_RUN）
        for vcpu in &mut self.vcpus {
            vcpu.run()?;  // 内部调用 ioctl(KVM_RUN)
        }
        
        Ok(())
    }
    
    /// 创建快照（CubeCoW 核心）
    pub fn snapshot(&self) -> Result<Snapshot> {
        let memory_snapshot = self.memory.snapshot_cow()?;  // 写时复制快照
        let vcpu_snapshot = self.vcpus.iter().map(|v| v.snapshot()).collect();
        let device_snapshot = self.devices.snapshot()?;
        
        Ok(Snapshot {
            memory: memory_snapshot,
            vcpus: vcpu_snapshot,
            devices: device_snapshot,
            timestamp: SystemTime::now(),
        })
    }
}

4. RustVMM + KVM：亚秒级启动的性能魔法

4.1 KVM 的工作原理

KVM（Kernel-based Virtual Machine）是 Linux 内核的一个模块，把 Linux 变成一个 Type-1.5 Hypervisor（混合类虚拟机监视器）。

没有 KVM：
  应用 → 系统调用 → Linux 内核 → 物理硬件

有 KVM：
  应用（QEMU/Firecracker/RustVMM）
    → ioctl(/dev/kvm, KVM_RUN)
    → Linux 内核（KVM 模块）
    → 硬件虚拟化指令（Intel VT-x / AMD-V）
    → 直接在物理 CPU 上运行 Guest 代码

关键系统调用：

// 1. 打开 KVM 设备
int kvm_fd = open("/dev/kvm", O_RDWR);

// 2. 创建虚拟机
int vm_fd = ioctl(kvm_fd, KVM_CREATE_VM, 0);

// 3. 设置 Guest 内存（把 Host 虚拟内存映射到 Guest 物理内存）
struct kvm_userspace_memory_region region = {
    .slot = 0,
    .guest_phys_addr = 0,
    .memory_size = 512 * 1024 * 1024,  // 512MB
    .userspace_addr = (unsigned long)host_memory,
};
ioctl(vm_fd, KVM_SET_USER_MEMORY_REGION, &region);

// 4. 创建 vCPU
int vcpu_fd = ioctl(vm_fd, KVM_CREATE_VCPU, 0);

// 5. 运行 vCPU（阻塞，直到 VM Exit）
while (1) {
    ioctl(vcpu_fd, KVM_RUN, 0);
    // 处理 VM Exit（I/O 指令、异常、外部中断等）
    handle_vm_exit(vcpu_fd);
}

4.2 <60ms 启动的秘密

CubeSandbox 的亚秒级启动来自以下几项优化：

优化 1：原地启动（In-place Boot）

传统虚拟机需要先把内核加载到内存、解压、再跳转到入口点。CubeSandbox 使用 vmlinux（未压缩的 ELF 格式内核），直接映射到 Guest 内存，省去解压时间。

传统启动流程（~300ms）：
  bzImage（压缩内核）→ 解压到内存 → 跳转到解压后的入口

CubeSandbox 启动流程（~30ms）：
  vmlinux（ELF）→ 直接映射到 Guest 物理内存 → 设置 RIP 寄存器 → 开始执行

优化 2：最小内核配置

CubeSandbox 提供精简的 Guest Kernel，只编译 AI Agent 沙箱必需的驱动：

# 内核配置对比
# 传统发行版内核：~5000 个功能选项，~200MB 压缩后大小
# CubeSandbox 内核：~500 个功能选项，~15MB 压缩后大小

# 精简掉的功能包括：
# - 不需要 GPU 驱动（沙箱里不需要图形界面）
# - 不需要 USB 支持（不需要热插拔设备）
# - 不需要音频驱动
# - 不需要大部分文件系统（只需要 ext4/overlayfs）
# - 不需要复杂网络协议（只需要 TCP/IP + virtio-net）

优化 3：并行初始化

Guest OS（通常是精简版 Linux）的初始化是并行化的：

# Guest OS 的 init 脚本（简化版）
#!/bin/sh

# 并行启动各个子系统
start_network() &
start_syslog() &
mount_overlay() &
configure_dns() &

# 等待所有子系统就绪
wait
echo "Sandbox ready" > /dev/ttyS0  # 通过 serial 通知 Host 启动完成

优化 4：内存预分配 + Hugepages

CubeSandbox 支持两种内存分配方式：

# 配置示例
memory_config:
  allocation_mode: "hugepages"  # 或 "balloon"（按需分配）
  hugepage_size: 2MB  # 或 1GB
  prealloc: true  # 启动时预分配所有内存

使用 Hugepages 的好处：

1. 减少 TLB Miss：2MB Hugepage 相比 4KB 页面，TLB（Translation Lookaside Buffer）命中率大幅提升
2. 减少 Page Table Walk：层级页表查找次数减少
3. 避免内存碎片：预分配连续物理内存

实测数据（来源：CubeSandbox 官方 benchmark）：

4.3 RustVMM vs Firecracker：性能对比

5. CubeCoW 写时复制：百毫秒级快照与克隆

5.1 为什么需要快照？

在 AI Agent 场景中，快照（Snapshot）和克隆（Clone）有两个核心用途：

用途 1：快速恢复现场

场景：Agent 需要执行多步任务，每步都依赖前一步的环境状态
  步骤 1：安装依赖 → 耗时 30 秒
  步骤 2：编译代码 → 依赖步骤 1 的环境
  步骤 3：运行测试 → 依赖步骤 2 的产物

传统方案：每次都从零开始 → 总时间 = 30s + 20s + 10s = 60s
快照方案：步骤 1 完成后打快照，步骤 2/3 从快照恢复 → 总时间 = 30s（仅第一次） + 0.1s（恢复） + 20s + 10s

用途 2：提供"无限个相同环境"

场景：同时运行 100 个 Agent 实例，每个都需要相同的环境（Python 3.11 + numpy + pandas）
传统方案：每个实例都重新安装依赖 → 100 × 30s = 3000s
克隆方案：准备一个"黄金镜像"，然后克隆 100 份 → 30s（准备镜像） + 100 × 0.1s（克隆） = 40s

5.2 CubeCoW 的技术原理

CubeCoW（Copy-on-Write）是 CubeSandbox 的快照引擎，核心思想是：不在快照时复制内存，而是共享内存页，只在写入时复制。

传统快照（Eager Copy）：
  快照时，把 512MB 的 Guest 内存完整复制一份 → 写入 512MB 数据到磁盘
  → 耗时：512MB / 1GBps（SSD） = 512ms

CubeCoW（Lazy Copy）：
  快照时，只记录当前内存页的"只读映射" → 耗时：<1ms
  当 Guest 写入某个内存页时，硬件触发 Page Fault
  → Hypervisor 捕获 Page Fault，把该页复制一份，建立新的映射
  → 只复制"脏页"（实际被修改的页），通常 <5% 的总内存

实现细节（Rust 伪代码）：

impl GuestMemory {
    /// 创建 CoW 快照
    pub fn snapshot_cow(&self) -> Result<CoWSnapshot> {
        let mut snapshot = CoWSnapshot::new();
        
        for (guest_phys_addr, host_virt_addr, size) in self.iter_regions() {
            // 把当前内存页设置为只读（触发 Page Fault 以捕获写入）
            unsafe {
                mprotect(host_virt_addr as *mut _, size, PROT_READ);
            }
            
            // 记录映射关系（不复制数据！）
            snapshot.add_mapping(
                guest_phys_addr,
                host_virt_addr,  // 共享同一份物理内存
                size,
                Protection::ReadOnly,
            );
        }
        
        // 快照元数据写入磁盘（异步，不阻塞 VM 运行）
        tokio::spawn(async move {
            snapshot.save_metadata_to_disk().await?;
            Ok(())
        });
        
        Ok(snapshot)
    }
    
    /// 处理 CoW Page Fault
    pub fn handle_cow_fault(&mut self, fault_addr: usize) -> Result<()> {
        // 找到触发 Page Fault 的内存页
        let page = self.get_page_containing(fault_addr)?;
        
        if page.is_cow_snapshot() {
            // 复制该页（写时复制的核心逻辑）
            let new_page = page.copy()?;
            
            // 更新映射（新的页可写，旧的页仍然共享）
            self.remap(fault_addr, new_page.as_ptr(), PROT_READ | PROT_WRITE);
            
            // 恢复 VM 执行
            return Ok(());
        }
        
        Err(PageFaultError::InvalidAddress)
    }
}

5.3 克隆的完整流程

原始沙箱（Sandbox A）
  ├── 内存：512MB（实际只用了 200MB）
  ├── 磁盘：2GB（overlayfs，只写了 100MB）
  └── vCPU 状态：RIP=0xffffffff81234567, RAX=0x0, ...

快照（Snapshot A）
  ├── 内存映射：指向 Sandbox A 的内存页（只读）
  ├── 磁盘映射：指向 Sandbox A 的 overlay 层（只读）
  └── vCPU 状态：完整保存

克隆（Sandbox B = clone from Snapshot A）
  ├── 内存映射：初始时和 Snapshot A 共享（CoW）
  ├── 磁盘映射：初始时和 Snapshot A 共享（CoW）
  └── vCPU 状态：从 Snapshot A 恢复

Sandbox B 第一次写入内存
  └── 触发 Page Fault → 复制对应的内存页 → 继续运行（其他页仍然共享）

实测数据：

注意：克隆 100 个沙箱的时间几乎和克隆 1 个相同，因为快照的元数据已经准备好了，克隆只是"实例化"一个新的 VMM 对象。

6. 硬件级隔离：为什么 KVM 比 Docker 更安全

6.1 攻击面对比

Docker 容器的攻击面：
  ┌─────────────────────────────────────┐
  │   恶意容器进程                       │
  │   - 利用内核漏洞（如 ptrace, eBPF） │
  │   - 利用 Docker 漏洞（runc CVE）   │
  │   - 读取 /proc、/sys 敏感信息      │
  │   - 通过 /dev 访问硬件设备          │
  └──────────┬──────────────────────────┘
             │ 共享内核
             ▼
  ┌─────────────────────────────────────┐
  │   Host Linux Kernel                 │  ← 一旦被攻破，所有容器沦陷
  └─────────────────────────────────────┘

KVM 虚拟机的攻击面：
  ┌─────────────────────────────────────┐
  │   恶意 Guest 进程                    │
  │   - 利用 Guest 内核漏洞             │
  │   - 尝试逃逸到 Hypervisor           │
  └──────────┬──────────────────────────┘
             │ VM Exit（受控的切换）
             ▼
  ┌─────────────────────────────────────┐
  │   RustVMM（Host 用户态进程）        │  ← 用 Rust 实现，内存安全
  │   - 只处理合法的 VM Exit            │
  │   - 严格校验所有 I/O 请求           │
  └──────────┬──────────────────────────┘
             │ ioctl(KVM_RUN)
             ▼
  ┌─────────────────────────────────────┐
  │   Linux KVM（Host 内核）            │  ← 硬件辅助虚拟化，攻击难度极大
  │   - 利用 VT-x / AMD-V 硬件隔离     │
  └─────────────────────────────────────┘

6.2 真实漏洞案例分析

案例 1：CVE-2019-5736（runc 容器逃逸）

# 攻击原理（简化版）
# 恶意容器可以覆盖宿主机上的 runc 二进制文件

# 在容器内执行：
cat > /tmp/evil_runc << 'EOF'
#!/bin/bash
# 这个脚本会在宿主机上以 root 权限执行！
echo "Hacked!" > /host/etc/cron.daily/hack
EOF

# 通过 /proc/self/exe 技巧，替换宿主机上的 runc
ln /proc/self/exe /host/usr/bin/runc  # 实际利用更复杂

影响：Docker/Kubernetes 全版本，直到 2019 年修复。

KVM 防护：Guest 完全看不到 Host 的文件系统，更无法执行 ln /proc/self/exe。

案例 2：Dirty COW（CVE-2016-5195）

// 利用 Linux 内核的 Copy-on-Write 竞态条件，实现提权
// 普通用户可以利用这个漏洞修改只读文件（如 /etc/passwd）

// 攻击原理：
// 1. 打开一个只读文件
// 2. 用 mmap(MAP_PRIVATE) 映射到内存
// 3. 在另一个线程里不停地调用 madvise(MADV_DONTNEED)
// 4. 竞态条件导致 CoW 失效，写入实际上修改了文件内容

影响：Linux 内核 2.6.22 ~ 4.8.3，几乎所有 Linux 服务器。

KVM 防护：Guest 内核和 Host 内核完全隔离，即使 Guest 内核有 Dirty COW 漏洞，也只能攻击 Guest 自己，无法影响 Host。

6.3 CubeSandbox 的纵深防御

除了硬件虚拟化，CubeSandbox 还实现了多层安全防护：

第一层：硬件隔离（KVM）
  ↓ 如果 KVM 有漏洞（极少见）

第二层：RustVMM 沙箱
  - RustVMM 是一个普通的 Linux 进程，用 seccomp-bpf 限制系统调用
  - 只允许 ~30 个安全的系统调用（read, write, ioctl(KVM_*), mmap, ...）
  - 禁止 execve, ptrace, mount, ...
  ↓ 如果 RustVMM 有漏洞

第三层：凭证保险库（CubeEgress）
  - API Key 不进入沙箱，由 CubeEgress 代理注入
  - 即使沙箱被攻破，攻击者也无法获取外部 API 的凭证
  ↓ 如果网络隔离被突破

第四层：网络 Egress 控制
  - 沙箱只能访问白名单域名/IP
  - 所有网络流量经过 CubeEgress 审计
  - 支持速率限制、敏感数据过滤

seccomp-bpf 配置示例（Rust 伪代码）：

/// 为 RustVMM 进程设置 seccomp 过滤器
fn apply_seccomp_filter() -> Result<()> {
    let filter = SeccompFilter::new(
        vec![
            // 允许的内存相关系统调用
            SeccompRule::new(Syscall::read, vec![]),
            SeccompRule::new(Syscall::write, vec![]),
            SeccompRule::new(Syscall::mmap, vec![]),
            SeccompRule::new(Syscall::munmap, vec![]),
            SeccompRule::new(Syscall::mprotect, vec![]),
            
            // KVM 相关系统调用
            SeccompRule::new(Syscall::ioctl, vec![
                Arg::new(1).in_set(vec![KVM_RUN, KVM_CREATE_VM, ...])
            ]),
            
            // 禁止所有其他系统调用（默认动作：杀死进程）
        ],
        SeccompAction::KillProcess
    )?;
    
    filter.apply()?;
    Ok(())
}

7. E2B 无缝迁移：一行环境变量切换沙箱后端

7.1 E2B 是什么？

E2B 是一个为 AI Agent 提供代码执行沙箱的商业服务，提供：

• 托管沙箱：无需自己管理基础设施
• SDK：Python 和 TypeScript 绑定，API 简单
• 预装环境：Python、Node.js、Java、Go 等

# E2B 官方 SDK 使用示例
from e2b import Sandbox

sandbox = Sandbox()  # 连接到 E2B Cloud

# 在沙箱里执行代码
result = sandbox.run_code("print('Hello from E2B!')")
print(result.stdout)  # "Hello from E2B!"

# 在沙箱里运行命令
proc = sandbox.process.start("pip install pandas")
proc.wait()

# 上传文件到沙箱
sandbox.files.write("/tmp/data.csv", "name,age\nAlice,30\nBob,25")

# 关闭沙箱
sandbox.close()

7.2 为什么要自部署？

E2B Cloud 虽然好用，但有以下几个痛点：

7.3 CubeSandbox 的 E2B 兼容层

CubeSandbox 实现了和 E2B 完全兼容的 API，所以迁移只需要改一个环境变量：

# 原来连接 E2B Cloud
from e2b import Sandbox

sandbox = Sandbox()  # 使用 E2B_API_KEY 环境变量

# 迁移到 CubeSandbox（只需要加两行）
import os
os.environ["E2B_API_URL"] = "http://your-cubesandbox-host:8080"
os.environ["E2B_API_KEY"] = "your-cubesandbox-api-key"

from e2b import Sandbox
sandbox = Sandbox()  # 现在连接的是自部署的 CubeSandbox！

API 兼容性矩阵：

7.4 迁移实战：从 E2B Cloud 到自部署 CubeSandbox

步骤 1：部署 CubeSandbox

# 使用 Docker Compose 一键部署（适合小规模测试）
git clone https://github.com/TencentCloud/CubeSandbox.git
cd CubeSandbox/deploy

# 修改配置（主要是设置 API Key 和网络配置）
vi docker-compose.yml

# 启动所有服务
docker compose up -d

# 检查状态
docker compose ps

步骤 2：获取 API Key

# CubeSandbox 默认使用 JWT 认证
# 用管理员工具生成 API Key
docker exec -it cubesandbox-cubemaster-1 \
  cubectl api-key create --name "my-agent" --expiry 365d

步骤 3：修改 Agent 代码

# 原来的代码（使用 E2B Cloud）
import os
from e2b import Sandbox

# 假设原来用 E2B Cloud
# E2B_API_KEY 环境变量已经设置好

def run_agent_task(code: str):
    sandbox = Sandbox(timeout=300)  # 5 分钟超时
    result = sandbox.run_code(code)
    sandbox.close()
    return result.stdout

# 修改后的代码（使用 CubeSandbox）
import os
from e2b import Sandbox

# 只需要加这两行！
os.environ["E2B_API_URL"] = "http://your-cubesandbox:8080"
os.environ["E2B_API_KEY"] = "your-generated-api-key"

def run_agent_task(code: str):
    sandbox = Sandbox(timeout=300)
    result = sandbox.run_code(code)
    sandbox.close()
    return result.stdout

8. 凭证保险库与 Egress 控制：零信任 Agent 架构

8.1 问题：Agent 需要调用外部 API，但不能把 Key 放进去

传统方案（不安全）：
  Agent 代码：
    import os
    api_key = os.environ["OPENAI_API_KEY"]  # Key 进入了沙箱！
    response = requests.post(
        "https://api.openai.com/v1/chat/completions",
        headers={"Authorization": f"Bearer {api_key}"}
    )
  
  风险：如果沙箱被攻破，攻击者可以读取环境变量、内存、磁盘，获取 API Key

8.2 CubeSandbox 的凭证保险库

CubeSandbox v0.4 引入了 Credential Vault（凭证保险库），核心思想：Key 不进入沙箱，由代理网关注入。

传统流程：
  Agent 代码 → 直接调用 api.openai.com → 需要 Key

CubeSandbox 流程：
  Agent 代码 → 调用 cubesandbox-egress:8080 → 保险库注入 Key → 转发到 api.openai.com

配置示例：

# credential_vault.yaml
vault:
  - name: "openai-api-key"
    type: "header"  # 注入到 HTTP Header
    value: "sk-xxxxxxxxxxxxxxxx"
    inject_to:
      - host: "api.openai.com"
        header_name: "Authorization"
        header_value: "Bearer {{.value}}"
  
  - name: "github-token"
    type: "header"
    value: "ghp_xxxxxxxxxxxxxxxx"
    inject_to:
      - host: "api.github.com"
        header_name: "Authorization"
        header_value: "token {{.value}}"
  
  - name: "database-password"
    type: "env_var"  # 注入到环境变量（不推荐，仅兼容老代码）
    value: "secret-password"
    inject_to:
      - env_var_name: "DB_PASSWORD"

Agent 代码（不需要修改！）：

# Agent 里的代码完全不需要知道 Key 的存在
import requests

# 原来需要 Key 的请求，现在直接发（CubeEgress 会自动注入 Key）
response = requests.post(
    "https://api.openai.com/v1/chat/completions",
    json={"model": "gpt-4o", "messages": [...]}
)
# CubeEgress 会拦截这个请求，自动加上 Authorization Header

8.3 Egress 控制：网络出口防火墙

除了凭证管理，CubeSandbox 还支持精细化的 Egress 控制：

# egress_policy.yaml
default_action: "deny"  # 默认拒绝所有出站流量

rules:
  - name: "allow-openai-api"
    action: "allow"
    destination:
      host: "api.openai.com"
      port: 443
  
  - name: "allow-github-api"
    action: "allow"
    destination:
      host: "api.github.com"
      port: 443
  
  - name: "allow-pypi"
    action: "allow"
    destination:
      host: "*.pypi.org"
      port: 443
  
  - name: "block-private-ip"
    action: "deny"
    destination:
      cidr: "10.0.0.0/8"  # 禁止访问内网 IP
    log: true  # 记录日志

实际效果：

# 以下请求会被 CubeEgress 拦截：

# 1. 访问内网（被 egress_policy 拒绝）
requests.get("http://10.0.0.100/internal-api")  # → 连接超时（被防火墙丢弃）

# 2. 访问不在白名单的域名（被 egress_policy 拒绝）
requests.get("https://evil-hacker.com/steal-data")  # → 连接超时

# 3. 访问白名单域名（允许，且自动注入 API Key）
requests.get("https://api.openai.com/v1/models")  # → 正常返回

8.4 审计日志

所有经过 CubeEgress 的请求都会被记录：

{
  "timestamp": "2026-07-02T09:30:00Z",
  "sandbox_id": "sb-abc123",
  "agent_id": "agent-001",
  "method": "POST",
  "url": "https://api.openai.com/v1/chat/completions",
  "status_code": 200,
  "request_size": 2048,
  "response_size": 4096,
  "latency_ms": 1200,
  "credential_injected": "openai-api-key",
  "policy_matched": "allow-openai-api"
}

这些日志可以发送到 ELK、Grafana Loki 或云端日志服务，用于：

• 异常检测（某个沙箱突然大量调用外部 API）
• 成本分析（统计每个 Agent 的 API 调用量和费用）
• 合规审计（证明数据没有泄露到未授权第三方）

9. 生产级部署：从单节点到 Kubernetes 集群

9.1 单节点部署（开发/测试环境）

# 硬件要求
# - CPU：支持 VT-x 或 AMD-V 的 x86_64 处理器
# - 内存：至少 8GB（每运行 10 个沙箱约需 1GB）
# - 磁盘：至少 50GB（用于存储模板镜像）

# 检查 KVM 是否可用
ls -la /dev/kvm
# 如果报错 "No such file or directory"，需要：
# 1. 在 BIOS 里开启 Intel VT-x 或 AMD-V
# 2. 安装 KVM：sudo apt install qemu-kvm libvirt-daemon-system

# 克隆仓库
git clone https://github.com/TencentCloud/CubeSandbox.git
cd CubeSandbox/deploy

# 修改配置（主要是设置域名、API Key、存储路径）
vi .env

# 启动所有服务（CubeAPI、CubeMaster、Cubelet、CubeEgress、Redis、PostgreSQL）
docker compose up -d

# 检查服务状态
docker compose logs -f cubemaster

# 创建第一个沙箱（测试）
docker exec -it cubesandbox-cubeapi-1 \
  curl -X POST http://localhost:8080/v2/sandboxes \
    -H "Authorization: Bearer your-api-key" \
    -H "Content-Type: application/json" \
    -d '{"template":"python-3.11","timeout":300}'

9.2 多节点集群部署（生产环境）

架构：
                    ┌──────────────────┐
                    │   Load Balancer  │
                    │   (Nginx/HAProxy) │
                    └────────┬─────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │CubeAPI 1│  │CubeAPI 2 │  │CubeAPI 3 │  ← 无状态，可以水平扩展
        └────┬─────┘  └────┬─────┘  └────┬─────┘
             │              │              │
             └──────────────┼──────────────┘
                            │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │CubeMaster│  │CubeMaster│  │CubeMaster│  ← 有状态，用 Raft 选举 Leader
        │  (Leader)│  │ (Follower)│ │ (Follower)│
        └────┬─────┘  └────┬─────┘  └────┬─────┘
             │              │              │
             └──────────────┼──────────────┘
                            │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │ Cubelet  │  │ Cubelet  │  │ Cubelet  │  ← 每台物理机一个
        │ (Node 1) │  │ (Node 2) │  │ (Node 3) │
        │ 128GB RAM │  │ 128GB RAM │  │ 128GB RAM │
        │ 32 vCPU   │  │ 32 vCPU   │  │ 32 vCPU   │
        └──────────┘  └──────────┘  └──────────┘

关键配置（CubeMaster 高可用）：

# cubemaster-config.yaml
cluster:
  mode: "ha"  # 或 "single"（单机模式）
  raft:
    nodes:
      - "cubemaster-1:9379"
      - "cubemaster-2:9379"
      - "cubemaster-3:9379"
    election_timeout: "5s"
    heartbeat_interval: "1s"

scheduling:
  strategy: "binpack"  # 或 "spread"（分散部署）
  max_sandboxes_per_node: 500
  resource_reserve:
    memory_mb: 2048  # 为每个节点保留 2GB 内存给系统进程
    vcpus: 2  # 保留 2 个 vCPU 给系统进程

Node 3 宕机后的自动故障转移：

时刻 T0：Node 3 上运行着 80 个沙箱
时刻 T1：Node 3 突然断电
时刻 T2（5 秒后）：CubeMaster 检测到 Node 3 心跳丢失
时刻 T3：CubeMaster 把 Node 3 标记为 "unhealthy"
时刻 T4：CubeMaster 触发重新调度，把 80 个沙箱分配到 Node 1 和 Node 2
  - 如果有快照：从快照快速恢复（~100ms 每个）
  - 如果没有快照：重新创建沙箱（~60ms 每个），Agent 需要重新执行代码

9.3 Kubernetes 集成（高级）

CubeSandbox 提供了 Kubernetes Operator，可以把沙箱作为 Kubernetes 资源来管理：

# Sandbox CRD 示例
apiVersion: cubesandbox.io/v1alpha1
kind: Sandbox
metadata:
  name: agent-sandbox-001
spec:
  template: "python-3.11"
  resources:
    memory: "1Gi"
    cpu: "2"
  timeout: 300s
  egressPolicy: "default"  # 引用 EgressPolicy CRD
  credentialVault: "default"  # 引用 CredentialVault CRD
  snapshot:
    enabled: true
    schedule: "*/10"  # 每 10 分钟自动快照

---
# EgressPolicy CRD 示例
apiVersion: cubesandbox.io/v1alpha1
kind: EgressPolicy
metadata:
  name: default
spec:
  defaultAction: "deny"
  rules:
    - host: "api.openai.com"
      action: "allow"
    - host: "*.pypi.org"
      action: "allow"

用 kubectl 管理沙箱：

# 创建沙箱
kubectl apply -f sandbox.yaml

# 查看沙箱状态
kubectl get sandboxes
# NAME                STATUS    AGE
# agent-sandbox-001  Running   2m

# 查看沙箱详情
kubectl describe sandbox agent-sandbox-001

# 删除沙箱
kubectl delete sandbox agent-sandbox-001

10. 性能基准测试：与 E2B/Daytona/Firecracker 对比

10.1 测试环境

硬件：
  - CPU：Intel Xeon Gold 6338（32 核心，64 线程）
  - 内存：256GB DDR4-3200
  - 磁盘：Intel Optane P5800X（3.2TB，读 6.8GB/s，写 4.2GB/s）
  - 网络：Mellanox ConnectX-6（100Gbps）

软件：
  - Host OS：Ubuntu 24.04 LTS，内核 6.8
  - Guest OS：CubeSandbox Kernel 6.6（精简版）
  - 对比对象：E2B Cloud（2026 年 6 月版本）、Daytona（v0.2.1）、Firecracker（v1.7.0）

10.2 启动时间对比

说明：冷启动 = 从零创建虚拟机；热启动 = 从快照恢复。CubeSandbox 的热启动极快，因为 CubeCoW 快照保留了内存状态，恢复时只需要设置 KVM 寄存器和设备状态。

10.3 内存开销对比

说明：CubeSandbox 和 Firecracker 的内存开销接近，都比 Docker 小一个数量级。这是因为 Docker 需要运行完整的 Linux 系统（systemd、udev、网络管理等），而 microVM 只需要一个极简的 init 进程。

10.4 网络性能对比

用 iperf3 测试沙箱内的网络吞吐量：

# 在沙箱内运行
iperf3 -c 10.0.0.1 -t 30 -P 4  # 4 个并行连接，测试 30 秒

说明：CubeSandbox 的网络性能略低于 Docker，因为数据包需要经过 virtio-net（半虚拟化网络驱动）。但 12Gbps 的单连接吞吐量已经远超大多数 AI Agent 的需求（调用外部 API 通常只需要 ~100Mbps）。

10.5 密度测试：单节点能跑多少个沙箱？

测试目标：在 128GB 内存、32 vCPU 的服务器上，最多能同时运行多少个沙箱（每个沙箱配置：1 vCPU，256MB 内存）？

关键发现：CubeSandbox 的高密度主要来自两方面：（1）极低的内存开销（<5MB）；（2）快速的并行启动（用 Rust 的 tokio 并行创建 420 个虚拟机，充分利用多核 CPU）。

11. 代码实战：Python + TypeScript SDK 完整示例

11.1 Python SDK 完整示例

"""
完整示例：用 CubeSandbox 构建一个"自主编程 Agent"
功能：
  1. 接收用户需求
  2. 在沙箱里生成代码
  3. 在沙箱里运行单元测试
  4. 如果测试失败，自动修复代码（最多重试 3 次）
  5. 返回最终代码和测试覆盖率
"""

import os
import time
from typing import List, Tuple

# 切换到 CubeSandbox（只需要改这两个环境变量）
os.environ["E2B_API_URL"] = "http://your-cubesandbox:8080"
os.environ["E2B_API_KEY"] = "your-api-key"

from e2b import Sandbox


class AutonomousCodingAgent:
    def __init__(self, sandbox_timeout: int = 600):
        self.sandbox_timeout = sandbox_timeout
    
    def solve(self, user_requirement: str) -> Tuple[str, float]:
        """
        自主解决编程任务
        
        Args:
            user_requirement: 用户需求描述
            
        Returns:
            (final_code, test_coverage)
        """
        # 创建沙箱
        print(f"🚀 创建沙箱...")
        sandbox = Sandbox(
            template="python-3.11",
            timeout=self.sandbox_timeout,
            metadata={"task": "autonomous_coding", "requirement": user_requirement[:100]}
        )
        
        try:
            # 步骤 1：让 LLM 生成代码（这里用 OpenAI API 作为示例）
            print(f"🤖 让 LLM 生成代码...")
            code = self._generate_code(sandbox, user_requirement)
            
            # 步骤 2：写入沙箱，运行测试
            print(f"🧪 运行测试...")
            for attempt in range(3):
                # 把代码写入沙箱
                sandbox.files.write("/workspace/solution.py", code)
                sandbox.files.write("/workspace/test_solution.py", self._generate_test(user_requirement))
                
                # 运行测试
                result = sandbox.run_code("""
import subprocess
result = subprocess.run(
    ["python", "-m", "pytest", "test_solution.py", "--tb=short"],
    capture_output=True,
    text=True
)
print("STDOUT:", result.stdout)
print("STDERR:", result.stderr)
print("RETURNCODE:", result.returncode)
""")
                
                if result.returncode == 0:
                    print(f"✅ 测试通过！")
                    break
                else:
                    print(f"❌ 测试失败（第 {attempt+1} 次尝试），让 LLM 修复代码...")
                    code = self._fix_code(sandbox, code, result.stderr)
            
            # 步骤 3：计算测试覆盖率
            coverage_result = sandbox.run_code("""
import subprocess
result = subprocess.run(
    ["python", "-m", "pytest", "test_solution.py", "--cov=solution", "--cov-report=term-missing"],
    capture_output=True,
    text=True
)
print(result.stdout)
""")
            
            coverage = self._parse_coverage(coverage_result.stdout)
            return code, coverage
            
        finally:
            # 一定要关闭沙箱！
            sandbox.close()
            print(f"🧹 沙箱已销毁")
    
    def _generate_code(self, sandbox: Sandbox, requirement: str) -> str:
        """调用 LLM 生成代码（伪代码，实际需要调用 OpenAI/Claude API）"""
        # 这里简化为直接返回示例代码
        return """
def solve(nums, target):
    \"\"\"找出两个数，使它们的和等于 target\"\"\"
    seen = {}
    for i, num in enumerate(nums):
        complement = target - num
        if complement in seen:
            return [seen[complement], i]
        seen[num] = i
    return []
"""
    
    def _generate_test(self, requirement: str) -> str:
        """生成单元测试"""
        return """
import pytest
from solution import solve

def test_basic():
    assert solve([2, 7, 11, 15], 9) == [0, 1]

def test_no_solution():
    assert solve([2, 7, 11, 15], 100) == []

def test_duplicate_numbers():
    assert solve([3, 3], 6) == [0, 1]
"""
    
    def _fix_code(self, sandbox: Sandbox, code: str, error_message: str) -> str:
        """根据错误信息，让 LLM 修复代码"""
        # 伪代码：调用 LLM，传入错误信息和原代码，让它能修复
        return code  # 简化
    
    def _parse_coverage(self, output: str) -> float:
        """解析 pytest-cov 的输出，提取覆盖率"""
        # 伪代码
        return 95.0


# 使用示例
if __name__ == "__main__":
    agent = AutonomousCodingAgent()
    code, coverage = agent.solve("实现一个 Two Sum 算法")
    print(f"最终代码：\n{code}")
    print(f"测试覆盖率：{coverage}%")

11.2 TypeScript SDK 完整示例

/**
 * 完整示例：用 CubeSandbox 构建一个"前端组件预览服务"
 * 
 * 功能：
 * 1. 接收 React 组件代码
 * 2. 在沙箱里安装依赖（React、Vite）
 * 3. 启动 Vite 开发服务器
 * 4. 返回预览 URL（通过 CubeProxy 端口映射）
 */

import { Sandbox } from 'e2b';
import express from 'express';
import * as path from 'path';
import * as fs from 'fs/promises';

// 切换到 CubeSandbox
process.env.E2B_API_URL = 'http://your-cubesandbox:8080';
process.env.E2B_API_KEY = 'your-api-key';

interface PreviewServiceOptions {
  sandboxTimeout?: number;
  vitePort?: number;
}

class ReactComponentPreviewService {
  private options: Required<PreviewServiceOptions>;

  constructor(options: PreviewServiceOptions = {}) {
    this.options = {
      sandboxTimeout: options.sandboxTimeout ?? 1800,  // 30 分钟
      vitePort: options.vitePort ?? 5173,
    };
  }

  /**
   * 预览一个 React 组件
   */
  async preview(componentCode: string, componentName: string): Promise<string> {
    console.log(`🚀 创建沙箱...`);
    
    const sandbox = await Sandbox.create({
      template: 'node-20',
      timeout: this.options.sandboxTimeout,
      metadata: {
        service: 'react-preview',
        component: componentName,
      },
    });

    try {
      // 步骤 1：初始化 Vite + React 项目
      console.log(`📦 初始化项目...`);
      await this._initViteProject(sandbox);

      // 步骤 2：写入组件代码
      console.log(`✍️ 写入组件代码...`);
      await sandbox.files.write(
        `/workspace/src/components/${componentName}.tsx`,
        componentCode
      );

      // 步骤 3：修改 App.tsx，引入组件
      const appCode = `
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { ${componentName} } from './components/${componentName}';

function App() {
  return (
    <div className="app">
      <h1>${componentName} Preview</h1>
      <${componentName} />
    </div>
  );
}

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>
);
`;
      await sandbox.files.write('/workspace/src/main.tsx', appCode);

      // 步骤 4：启动 Vite 开发服务器（后台运行）
      console.log(`🌐 启动 Vite 开发服务器...`);
      const viteProcess = await sandbox.process.start({
        cmd: 'npm run dev',
        env: { VITE_PORT: String(this.options.vitePort) },
        background: true,  // 后台运行
      });

      // 等待 Vite 启动完成（检查日志）
      await this._waitForViteReady(sandbox, viteProcess);

      // 步骤 5：获取预览 URL
      const previewUrl = await this._getPreviewUrl(sandbox);
      console.log(`✅ 预览 URL：${previewUrl}`);

      return previewUrl;
    } catch (error) {
      // 出错时销毁沙箱
      await sandbox.close();
      throw error;
    }
    // 注意：不在这里关闭沙箱，让预览服务继续运行
    // 可以设置一个定时器，30 分钟后自动销毁
  }

  /**
   * 初始化 Vite + React 项目
   */
  private async _initViteProject(sandbox: Sandbox): Promise<void> {
    await sandbox.runCode(`
import subprocess
import os

# 创建 Vite 项目（自动确认）
os.chdir('/workspace')
result = subprocess.run(
    ['npm', 'create', 'vite@latest', '.', '--', '--template', 'react-ts'],
    input=b'y\\n',
    capture_output=True
)
print(result.stdout.decode())

# 安装依赖
subprocess.run(['npm', 'install'], capture_output=True)
print('Project initialized!')
`);
  }

  /**
   * 等待 Vite 启动完成
   */
  private async _waitForViteReady(sandbox: Sandbox, process: any): Promise<void> {
    const startTime = Date.now();
    const timeout = 30000;  // 30 秒超时

    while (Date.now() - startTime < timeout) {
      const logs = await process.getLogs();
      if (logs.includes('Dev server running')) {
        console.log(`✅ Vite 已启动`);
        return;
      }
      await new Promise(resolve => setTimeout(resolve, 1000));
    }

    throw new Error('Vite 启动超时');
  }

  /**
   * 获取预览 URL（通过 CubeProxy 的端口映射）
   */
  private async _getPreviewUrl(sandbox: Sandbox): Promise<string> {
    // CubeSandbox 会为沙箱分配一个唯一的子域名
    // 格式：https://{sandbox_id}.sandbox.your-domain.com:{vite_port}
    const sandboxId = sandbox.id;
    const baseUrl = process.env.CUBESANDBOX_PUBLIC_URL ?? 'https://sandbox.example.com';
    return `${baseUrl}/${sandboxId}/_proxy/${this.options.vitePort}`;
  }
}

// 使用示例
async function main() {
  const service = new ReactComponentPreviewService();

  const componentCode = `
import { useState } from 'react';

export function Counter() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(c => c + 1)}>Increment</button>
    </div>
  );
}
`;

  const previewUrl = await service.preview(componentCode, 'Counter');
  console.log(`🔗 打开预览：${previewUrl}`);
}

main().catch(console.error);

12. 深度思考：AI Agent 基础设施的下一个三年

12.1 我们正在经历的范式转移

第一代 AI Agent（2022~2024）：
  LLM → 生成文本 → 结束
  "我是一个聊天机器人"

第二代 AI Agent（2024~2025）：
  LLM → 生成代码 → 解释器执行（Python REPL）→ 返回结果
  "我可以帮你运行代码"

第三代 AI Agent（2025~2026，当前）：
  LLM → 生成代码 → 沙箱执行（CubeSandbox/E2B）→ 返回结果 + 环境状态
  "我可以在隔离环境里运行任意代码，并且记住状态"

第四代 AI Agent（2026~2028，即将到来）：
  LLM → 生成代码 → 多个并行沙箱执行 → 沙箱间通信 → 分布式任务协作
  "我们可以组成团队，每个 Agent 有自己的沙箱，协同完成复杂任务"

12.2 沙箱技术的未来方向

方向 1：GPU 虚拟化

当前的 CubeSandbox 只支持 CPU 沙箱，但很多 AI Agent 任务需要 GPU（模型推理、图像处理、视频编码）。

技术挑战：
  - GPU 的虚拟化比 CPU 复杂得多（显存管理、CUDA 上下文）
  - 需要硬件支持（NVIDIA vGPU、AMD SR-IOV）
  - 成本极高（A100/H100 非常昂贵）

可能的解决方案：
  - 用 rCUDA / GVirtuS 实现 GPU 半虚拟化
  - 用 NVIDIA MIG（Multi-Instance GPU）把一张 A100 分成 7 个独立实例
  - 用 cube-scheduler 智能调度 GPU 任务（类似 kube-scheduler 对 GPU 的支持）

方向 2：跨沙箱通信

当多个 Agent 协作时，它们需要互相通信：

# 未来的 API 可能长这样
sandbox_a = Sandbox()
sandbox_b = Sandbox()

# 在 sandbox_a 里运行一个服务
sandbox_a.run_code("""import FastAPI...\napp = FastAPI()..\n""")

# 让 sandbox_b 调用 sandbox_a 的服务（通过内部网络）
sandbox_b.run_code(f"""
import requests
response = requests.get("http://{sandbox_a.internal_ip}:8000/api")
print(response.json())
""")

方向 3：WASM 作为沙箱内的安全执行单元

WebAssembly（WASM）可以提供比进程级隔离更强的沙箱（在沙箱里面再套一层沙箱）：

应用场景：
  - 用户上传插件（如 Figma 插件、VS Code 扩展），需要在 Agent 沙箱里运行
  - 用 WASM 隔离每个插件，防止恶意插件攻击 Agent 的主逻辑

技术栈：
  Cub