Agent隔离执行环境：自建Firecracker沙箱集群的关键设计

1. 为什么自建 Agent 沙箱集群，而不是直接上开源沙箱套件

做 Agent 服务的隔离执行环境这件事，大多数人第一个想到的是去用现成的开源沙箱平台或者商业 API。我们当初也评估过几条路：直接调第三方执行环境 API、用 Docker 容器做隔离、自己啃 Firecracker 搞一套沙箱集群。最后选了自建，核心原因是控制力要求太高——任务的执行时长要限制、文件要能注入和回收、进程要能编排，任何一个环节依赖外部平台，限制和成本都会非常被动。

先看清楚自建沙箱集群到底解决什么问题。Agent 场景里，代码执行环境的特点是：短生命周期、高并发、每个实例的现场环境都得干净可预期。容器方案的问题是隔离边界不够硬，共享宿主机内核意味着某些暴露面始终在，一个逃逸漏洞或者资源抢占就可能拖垮宿主上的其他任务。gVisor 这类用户态内核是折中，但性能损耗和兼容性问题在真实业务里很糟心。Firecracker 这个项目的好处是它是 KVM 上的极简 microVM，每个沙箱独立内核、独立设备模型，启动延迟能到 200ms 到 400ms，内存附加成本通常只有几十兆，几乎就是为这种场景设计的。

我们当时的架构思路是这样的：宿主机上跑一个控制面服务，负责管理 Firecracker 进程、维护沙箱状态、执行文件分发和进程编排。每一个沙箱是一个独立的 microVM，VM 内部跑一个极小的 supervisor 进程，专门负责接收任务、启动作业进程、回传日志和退出码。这个 supervisor 就是整个集群里最核心的编排执行单元。整个系统的架构图如果用文字表达，就是三层：最底部宿主机上的 Firecracker 进程和 KVM 内核模块，中间是控制面调度器（负责建 VM、销毁 VM、资源配额），最上面是每个 VM 里的静态 supervisor 和按任务启动的临时进程。

这一期内容我打算把做这套集群时最重要的几个设计决策讲透——状态机、文件管理、进程编排，最后再聊聊我们是怎么从 E2B 上那套经过生产验证的方案里校准了一堆踩坑经验。这些内容适合已经在用 Docker 跑 Agent 执行环境、现在想往更硬隔离升级的团队，或者打算自己基于 Firecracker 做 PaaS 类执行环境的开发者。

2. 状态机设计：把沙箱生命周期管明白

2.1 沙箱生命周期有哪几个状态

沙箱不像普通容器可以那你随便创建销毁。一个 microVM 从开始创建到最终终止，中间牵涉内核加载、rootfs 挂载、网络设备 tap 创建、vsock 握手、任务执行与超时回收。如果不用状态机约束，几十个沙箱一跑起来，光是排查"哪个 VM 是正在启动、哪个是正在执行、哪个是僵死"就能把人逼疯。我们最终把状态收敛成五个：PENDING、RUNNING、PAUSED、STOPPING、TERMINATED，另外在后端会把异常退出统一标成 FAILED。

PENDING 是 VM 还没起来时的状态。此时控制面已经调用了 Firecracker 的 Create 接口，但是内核还没有加载成功，VM 也还没有应答心跳。RUNNING 是状态机的核心：VM 内 supervisor 已经通过 vsock 与控制面连接上，Agent 任务可以被分发了。PAUSED 这个状态我们平时用得不多，但它很重要，Firecracker 支持 VM pause/resume，我们会在做快照或者临时需要冻结执行现场时用到它。STOPPING 表示控制面已经开始销毁流程，可能是任务完成后自动回收，也可能是判断 VM 僵死之后的强制清理。TERMINATED 是终态，意味着 Firecracker 进程已经退出，socket 文件清理完毕，VM 占用的内存和 CPU 全部归还宿主机。

状态迁移看起来简单，真正难的地方在并发回收和超时兜底。比如 RUNNING 状态的沙箱如果 supervisor 突然失去心跳，你不能等它自然超时，要立刻标记 FAILED 并进入 STOPPING。再比如 STOPPING 状态如果 Firecracker 进程卡住，控制面需要有兜底的 kill 路径，否则这个沙箱会永远占着资源。状态越多越要警惕过渡状态的可靠性，过渡状态一定要有超时时间。

2.2 状态协调：为什么必须有一个中心状态机

第一版代码里我们把状态直接写在每个 worker 的内存里，结果连着出了几竞态问题。两个 worker 同时拿到同一个沙箱 ID，都以为自己是所有者，开始往里下发任务，导致 VM 里的 supervisor 收到重复请求。这问题不在于 supervisor 不幂等，而在于你没法保证它每次都幂等。后续我们把状态挪到了一个中心化的控制面存储里，每个沙箱的状态更新都带版本号，用乐观锁保证同一条记录不会被并发覆盖。

控制面的核心表结构其实很简单：沙箱 ID、状态、所属 worker 节点、任务 ID、创建时间、最近心跳时间、版本号。每次 worker 在处理沙箱之前都要先抢锁，抢到锁之后才能推进状态机。心跳在每个 RUNNING 沙箱上是独立 goroutine 做的，每 5 秒更新一次最近心跳时间，这样调度器可以精准判断哪些沙箱是失活的。

我们试过把状态机放在 Redis 里用 Lua 脚本保证原子性，但后来发现对于这种低频状态变更，数据库表加版本号就完全够用，还省掉一套基础设施运维成本。状态变更的 QPS 其实不高，一个集群几千个沙箱，也就是每秒几十次更新，连单机 SQLite 都能扛，重点是路径清晰、可审计。

2.3 超时与自动回收

状态机设计里最容易被忽略的是超时配置。初始设计时我们对沙箱的预期是活 5 分钟以内——任务执行结束，立刻销毁。但实际跑起来后，Agent 场景经常出现长耗时的代码执行任务，比如用户让 Agent 跑一个数据处理脚本，一跑就是 20 分钟。我们不能允许沙箱无限存活，但也不能把所有任务一律按 5 分钟上限回收。

后来我们设计了两级超时。一级是任务级超时，每个任务在分发时带一个 timeout 字段，默认 10 分钟，可调。一级是沙箱级空闲超时，如果 RUNNING 状态沙箱超过 2 分钟没有新任务分发进来，并且队列里也没有积压任务，控制面会主动触发 STOPPING。这样既照顾了长短任务，又能防止闲置沙箱占着内存不放。还有一个容易被坑的点：Firecracker 的 stop 动作如果直接 kill 进程，VM 里的文件系统可能没有来得及同步，所以所有 STOPPING 流程我们都尽量先给 supervisor 发一个优雅退出消息，等 3 秒再强制 kill。这条经验是我们在数据丢失事故之后才总结出来的，后面文件管理章节细说。

3. 文件管理：镜像、读写层与文件注入的三层设计

3.1 根文件系统的三层设计

Firecracker 的存储模型和 Docker 不一样。Docker 的镜像层是分层的，你 pull 镜像时本地会有多个 layer 合并成可写层。Firecracker 本质上只给你一个块设备，你给它的就是一个 raw 或 qcow2 格式的磁盘镜像，它启动时直接把这个盘挂成根文件系统。为了让每个沙箱之间互不影响，我们做了三层设计：基础镜像层、临时可写层、任务数据盘层。

基础镜像层是一份只读的 ext4 镜像，里面预装了 supervisor 和 Agent 的 runtime 依赖。这个镜像我们放在宿主机本地目录，每个物理机只需保留一份。临时可写层我们使用 overlayfs 实现，本质上就是在 VM 启动时，根文件系统以只读方式挂载，可写改动落到一块临时分配的内存盘或者临时磁盘上。任务数据盘层是另一块通过块设备挂载进去的盘，专门放任务相关的输入文件和输出文件，任务结束之后这块盘直接清零回收，不污染基础镜像。

之所以搞三层而不是直接给每台 VM 一个独立磁盘镜像副本，原因很现实：磁盘空间和启动时间。每份基础镜像动辄 1-2GB，如果不共享，一台宿主机跑 30 个沙箱要准备 60GB 空闲空间，还不算读写开销。用只读共享加 overlay 可以大幅缩减磁盘占用，还能利用页面缓存的共享特性。

3.2 启动前文件注入与运行时文件分发

文件注入是这个项目里最容易走偏的地方。一开始我想的是把所有任务文件在 VM 创建之前都塞进 rootfs，让 supervisor 启动之后直接读文件系统里的内容。实现上确实最简单——你可以在构建镜像时把文件打进去，或者在 VM 启动前修改磁盘镜像。但缺点非常明显：创建 VM 之前你得知道任务文件是什么，而真实场景里 Agent 的任务依赖往往是动态确定的。

所以我们把文件管理分成了两个通道。启动前只注入两个东西：supervisor 二进制和一份配置文件。配置文件里包含 VM 的 CID、控制面地址、任务请求通道用的 vsock 端口。其他所有任务相关文件，都通过虚拟机内部的 vsock 通道在运行时动态下发。每个任务会先打一个文件清单，比如 "需要一个 Python 脚本 input.py 和一份数据 data.csv"，控制面收到清单后把这些文件通过 vsock 连接传给 supervisor，supervisor 再往临时目录写。任务执行完之后，输出文件通过同样的通道传回控制面，然后临时目录直接层清理。这套方案的优点是有机会跨网络、跨宿主机进行文件分发，后续做跨节点调度时不用考虑"文件在哪个节点上"这个限制。

3.3 持久化与快照

Agent 场景里经常会有"让沙箱记住上次状态"的需求。比如用户在一个会话里多次执行代码，希望前一次的变量或者文件结果能保留。如果每次任务都销毁重建 VM，持久化就成了大问题。我们的做法是：除了 VM 临时盘里的 overlayfs 之外，每台沙箱额外挂载一块持久盘，任务的结果文件写到持久盘的固定目录，延长沙箱生命周期时持久盘可以跟着 VM 继续存在，超时回收之后持久盘才会被释放。

更进阶的方案是 Firecracker 的微虚拟机快照（snapshot）功能。快照可以把 VM 的内存状态和磁盘状态都保存下来，下次启动时直接恢复，跳过完整的引导阶段。我们在实验环境里实测过，从快照恢复比冷启动平均快 60% 到 70%。但快照有个坑必须要提示：它依赖 KVM 的 CPU 特性集，同一台宿主机上做的快照，拿到另一台 CPU 型号完全一样的宿主机上才能恢复，跨代际 CPU 恢复会直接失败。所以我们只在同一批物理机之间做快照调度，跨机器调度时强制走冷启动路径。这个限制很重要，如果你在生产环境里直接把快照当成万能高可用方案，很快会被各种 obscure 的错误搞疯。

4. 进程编排：沙箱内的生命周期与并发控制

4.1 进程编排的本质是解决三个问题

进程编排和容器编排是两码事。容器编排调度的是容器，而 Firecracker 沙箱里，我们调度的是 VM 内部的进程。设计 supervisor 时我们确认了三个必须解决的核心问题：孤儿进程回收、输出流双向传输、任务并发边界。每个问题都有坑。

孤儿进程回收上，很多 Agent 任务会 fork 子进程，比如脚本里调subprocess.Popen。当任务进程退出但子进程没有退出时，这个子进程会变成孤儿进程，它的父进程变成 PID 1。如果我们不做回收，随着任务执行次数增加，VM 里会积累一堆僵尸进程。我们采用的方案是在 supervisor 里专门维护一个子进程注册表，每个任务启动前由 supervisor 统一 fork 一个中间层进程，任务进程作为中间层进程的子进程运行。当任务执行完毕，中间层进程负责回收自己所有的孙进程，否则直接向整个进程组发SIGKILL。实际测试中，这个中间层设计比单纯依赖 PID 1 回收靠谱得多。

输出流双向传输上，我们用一个简单的 JSON-RPC 风格协议封装在 vsock 之上。任务启动后，supervisor 实时读取子进程的 stdout 和 stderr，按行包装成 protocol message 回传控制面。控制面这些日志再转发给上层 Agent 服务，这样用户能看到实时的执行日志，而不用等任务结束。这个看似简单的问题在编码上特别容易翻车，尤其是子进程输出量很大的时候，如果你用阻塞式的 readline，消息队列会堆积，日志延迟越来越离谱。我们的办法是给每个输出流维护独立的消息队列，并设一个可配置的发送窗口，超过窗口就直接丢弃日志但保留退出码。

并发边界上，我们严格控制每个 VM 内同时只执行一个任务。理由很简单：如果同时跑两个 Agent 任务，它们之间会抢占 CPU 和文件资源，一旦某个任务崩了，排查起来是谁导致的问题会非常痛苦。当然"一个任务一个 VM"的代价是并发上限被 VM 数量卡死，所以实际我们的调度策略是靠增大 VM 数量而不是在 VM 内部做任务级并发。每台宿主机上的 VM 数理论上限大概是 CPU 核数的 4 到 6 倍，内存够的情况下可以更高，但超卖太狠会导致每个任务体验很差。

4.2 控制面的调度与资源配额

控制面负责决定一台任务应该调度到哪台宿主机上的哪个沙箱。我们给每台宿主机打了两个资源标签：可分配的 CPU 资源额度和内存额度。每个沙箱的规格在 VM 创建时通过 Firecracker 的 machine config API 设置，比如 1 vCPU 加 512 MiB 内存是小规格，2 vCPU 加 2 GiB 是中规格。调度器拿到任务资源需求后，扫描所有宿主机，找到能满足剩余容量且当前空闲沙箱池里有位置的节点，把任务 ID 下发过去，由节点上的本地调度组件决定复用哪个空闲沙箱或者新建一个沙箱。

这里的资源配额需要注意超卖比例。Firecracker 虽然内存开销很小，但 CPU 超卖并不是无限的。我们实测在 1 vCPU 的沙箱上跑 CPU 密集型任务时，如果每台物理机超卖到 8 倍，所有沙箱的整体吞吐反而会下降，因为频繁的 CPU 上下文切换和缓存争抢抵消了并发收益。最终我们把 CPU 超卖比压到 4 倍，内存超卖比压到 2 倍以内，这个比例下面稳定性最好。

4.3 沙箱池与预启动扩容

控制面调度器最大的性能瓶颈不是状态机处理，而是沙箱冷启动。Firecracker 启动一个 VM 虽然比传统虚拟机快很多，但冷启动路径上还是要经过内核加载、rootfs 挂载、vsock 握手，这些步骤加起来在普通 SSD 上一台也要 300-500ms。如果 Agent 任务临时来一个新建一个，高峰期会大量堆积。

我们的解法是维护一个沙箱预启动池。控制面在低峰期或收到扩容信号时，提前创建一批微VM，让它们处于 PENDING 状态等待任务绑定。任务到来时，调度器从池里直接取一个 VM，通过 vsock 下发文件清单和任务描述，把状态切换到 RUNNING。这样从任务提交到沙箱内进程启动的时间可以压到 50ms 以内，几乎无感。预启动池的代价是闲置 VM 占内存，所以池大小和 VM 规格要做联动配置——小规格 VM 池拉 20 个，中规格池拉 5 个，并且空闲超过 3 分钟的池内 VM 要定期销毁释放资源。

预启动池还有一个好处是并发创建 VM 时不会因为 tap 设备不足、磁盘临时空间竞争等问题导致 30 个请求挤在一起互相拖慢。控制面扩容时按批次创建 VM，每批最多 5 个，批次之间间隔 100ms，把并发峰值削平。

5. E2B 生产经验校准：踩过的坑与调整方案

5.1 E2B 给我的启示：沙箱不只是隔离环境

在做这套系统之前，我花了不少时间研究 E2B 的设计思路和表现。E2B 这个项目专攻 AI 代码执行的沙箱。从它的文档和生产用例里，我能明显感受到一个理念：沙箱不是单纯的隔离环境，它同时是一台有文件系统、网络栈和进程管理能力的微型服务器，沙箱的使用者不应关心它是怎么实现的，只需要关心如何给虚拟机下发指令并获取结果。这个理念直接促使我们重构了 supervisor 和 Agent 之间的交互协议，从原来"发一个任务字符串"演变成"发一个 Job 描述对象"。

E2B 的另一个生产经验是预构建镜像。它的公开文档里明确推荐把所有热门语言运行时全预装在 rootfs 里，这样任务执行时不需要pip install或者npm install。我们早期也做过"任务要求装包就在沙箱里现装"的事情，生产环境一压测就露馅了：10 个并发任务同时 pip install 大包，磁盘 IO 瞬间打满，所有任务一起变慢，有的直接超时。后来我们把镜像构建流程改成了在 CI 里预装好各种运行时，任务描述里声明依赖名称和版本，supervisor 从本地目录里加载预装的包，不再临时安装。

5.2 镜像版本管理与一致性

E2B 还让我意识到，镜像版本管理不能靠"宿主机上躺着最新的一份镜像"这种懒办法。否则你无法保证集群里不同节点上的镜像完全一致，任务调度到 A 节点和 B 节点跑出来的环境可能不一样。我们后来把镜像当成一个二进制产物来管，构建之后上传到一个内部对象存储，宿主机启动时从对象存储拉取指定版本镜像，校验 sha256 再加载。这样每次部署新镜像能全量生效，不会有节点滞后问题。

这步改造看起来简单，实际解决了我们大量 "复现不了"类的线上问题。以前 Agent 开发环境经常出现"我本地能跑，沙箱里就不行"的状况，其中相当一部分就是镜像不一致造成的。现在镜像版本固定，Task 描述里能指定用哪个镜像 ID，问题的排查范围缩小了一大截。

5.3 网络模型与安全组

E2B 的沙箱默认是允许访问公网的，因为 AI 代码执行经常需要拉取数据集或调用 API。我们也需要在沙箱里提供出网能力，但又不希望沙箱之间互相访问形成内网风险。最后参考它的思路，我们给每个沙箱配了一个隐藏的网段，VM 内的默认出口走 NAT 到宿主机，宿主机上再用 iptables 规则限制跨 VM 通信。

这样做的结果就是每个沙箱的"网络身份"彻底隔离，你不能从一个沙箱里扫描到同宿主机上的其他沙箱端口。这一步在隔离度上比 Docker 用 bridge 模型要高很多，也让我对 Firecracker 的安全性更有信心。

这里给一个配置摘要：每个 microVM 挂一个 tap 设备，宿主机上单独建一个 bridge 网段，比如192.168.100.0/24，每个沙箱分配独立 IP，默认路由指向宿主机侧，宿主机上用 masquerade 做 NAT 出网，再配一条 forward drop 规则阻断沙箱互访。这套做法下来，集群内网络隔离基本干净。

5.4 从 E2B 校准出的冷启动标准

E2B 公开的冷启动数据大概是几百毫秒量级，但我们的实测表明，这个数据高度依赖 microVM 的规格和内核配置。以 1 vCPU + 512MiB 内存、本地 SSD 环境为例，我的观测数据是：创建 VM 到 socket 文件就绪 25ms，内核启动到用户态 supervisor 起来 180-400ms，vsock 握手加任务下发 15-30ms，整个任务流程从控制面收到请求到沙箱内进程 fork 完成大约 350-500ms。如果带 2GB 内存或者大镜像，时间会上浮 200ms 左右。

这个标准让我们敢对上层业务承诺比较激进的任务启动 SLA。我们甚至在控制面做了分位数统计，如果 P95 超过 1 秒就触发告警，方便第一时间发现宿主机负载异常或者镜像拉取瓶颈。对 Agent 场景来说，用户等待代码执行结果，冷启动时长直接决定了"反馈快不快"的体感，这步校准非常重要。

6. 常见问题与排查实录

6.1 内核与 KVM 相关的坑

Firecracker 对宿主机的 Linux 内核有版本要求，KVM 模块必须加载。很多次因为新机器初始化时忘了加载/dev/kvm，Firecracker 直接报权限类错误。排查方法很简单，一条命令ls -l /dev/kvm确认设备节点存在，没有就modprobe kvm_intel或modprobe kvm_amd。如果宿主机是嵌套虚拟化环境，比如你自己在一台虚拟机里跑 Firecracker，必须确认嵌套虚拟化已开启，否则 KVM 初始化会失败。

还有内核配置里要打开CONFIG_VSOCKETS、CONFIG_VIRTIO_VSOCKETS，否则 VM 里启动 supervisor 时会发现 vsock 设备根本不存在。这类问题往往在烧镜像时最坑，因为编译内核时没有加 vsock 支持，后面所有 VM 都无法通信。检查办法是看内核目录里有没有vhost_vsock.ko，没有就回炉重编内核，没有捷径。

6.2 vsock 连接异常

我们的控制面与 supervisor 之间用 vsock 通信，最典型的故障是 VM 启动后控制面 connect 失败。常见原因是 supervisor 监听端口和 Firecracker 配置的 guest_cid 对不上。Firecracker API 设置 CID 时要注意，guest_cid不能小于 3，而且宿主机上每个 VM 的 CID 必须全局唯一。如果你创建的 VM 越来越多，CID 不做好分配管理，很容易撞。

还有 socket 文件的问题。我们曾经把 Firecracker 的 Unix socket 放在/tmp下，结果某个清理定时器把所有*.sock一次性删了，导致所有 VM 失联。千万不要把 Firecracker 的 socket 文件放在包含大量临时文件的公共目录里，规划一个独立的运行时目录，比如/run/fc-sandbox，并严格管理文件权限。

6.3 资源泄漏与孤儿沙箱清理

Firecracker 进程如果异常退出，它的 tap 设备和 rootfs 临时盘并不会自动清理干净。我们做了一套宿主机的周期清扫项：每 5 分钟巡检一次，把不在状态机里登记的 Firecracker 进程及其关联的 tap 设备全部清理。另外，VM 的 overlayfs 临时盘文件如果稍微处理不当，会在/var/lib里累积很多没有回收到的大文件，跑几天磁盘就报警。

所以这里给一条实操经验:沙箱销毁流程必须有一个明确的"清理清单"。至少包含：Firecracker 进程退出、Unix socket 文件删除、关联 vhost 进程清理、tap 设备解绑、overlay 临时盘释放、持久盘目录回收。每一步的顺序都有讲究，如果先删了 socket 再杀进程，可能导致控制面无法正常通过 Firecracker API 等待 VM 退出。

下面这张表是我实际运维中总结的高频问题速查：

6.4 控制面与节点之间的消息丢失

最后聊一个工程质量问题。控制面与每个宿主机上的 Agent 之间如果通过消息队列通信，一旦宿主机重启或者队列积压，任务分发就会丢。我们早期采用 Redis Stream 做任务分发，宿主机关机重启后 Stream 数据虽然还在，但消费者状态可能错乱，导致任务发了没执行，Agent 端也没有 ack。后来我们在 Ack 机制上多加了幂等控制和重投策略：每个任务有唯一 ID，控制面收到 ack 前如果超时会重新入队，但会限制重试次数。加上进度日志和任务 ID 全链路透传，这类问题排查起来快很多。

如果你的沙箱集群规模不太大，其实不用一上来就上复杂消息队列。控制面打开一个数据库表当任务队列，单机也能支撑比较高的吞吐。消息中间件的引入要等你确实遇到吞吐瓶颈再做，过早引入只会增加排查复杂度和运维负担。

我个人现在回头看得出的一个体会是：沙箱集群里真正容易出问题的不是 Firecracker 本身，而是你围绕它自己写的这层控制面。状态机、文件管理、进程编排，每个环节看着分立，实际上互相牵连。尤其是文件下发和任务进程编排的边界——什么地方由控制面管，什么地方由 supervisor 管，一定要在文档里写清楚，否则代码改着改着边界就模糊了。

最后再分享一个小技巧：所有沙箱的关键事件（创建、绑定任务、心跳超时、销毁）一定要打结构化日志，带上沙箱 ID 和任务 ID，放在集中式日志系统里。很多线上问题靠肉眼看日志根本拼不出完整链路，但只要事件日志干净，再配合状态机记录的审计轨迹，大部分疑难杂症都能在一杯茶的时间内定位。这套做法我们上线之后持续在用，效果远比堆测试用例和事后告警来得实在。