如何看懂 AgentENV 系统架构全景图从 API 到 Firecracker 微虚拟机的完整数据流【免费下载链接】AgentENVAgentENV (AENV) is a distributed platform for running agent environments at scale.项目地址: https://gitcode.com/gh_mirrors/age/AgentENVAgentENVAENV是一个用于大规模运行 Agent 环境的分布式平台。本文带你从一张全景图出发完整走通一个 HTTP 请求如何穿透 API 层、编排器最终变成一台运行中的 Firecracker 微虚拟机microVM并解释快照、ublk 块设备与分布式控制平面在其中扮演的角色——这是理解 AgentENV 系统架构最快的路径。一、30 秒看懂 AgentENV 系统架构全景AgentENV 的核心目标只有一个让 AI Agent 能跑在隔离、可快照、可秒级恢复的 Firecracker microVM 里并且能在集群中水平扩展。整个系统分两大平面平面组成职责单节点平面Rust 编写API Server Orchestrator Firecracker 存储子系统管理沙箱生命周期、块设备、网络、快照分布式控制平面Go 编写Gateway Scheduler多节点间的路由与节点选择官方架构文档对这一全景有权威定义AgentENV 在隔离的、支持快照的 Firecracker microVM 中运行 AI Agent。其核心是一个存储子系统提供可挂载进虚拟机的分层块设备以及基于 ublk 的内存快照恢复。每个节点还有一个编排器管理沙箱生命周期以及一个分布式控制平面Gateway Scheduler负责多节点路由。完整原文见 architecture.md。二、核心组件地图7 个关键模块与源码位置下面这张表把全景图上的每个方块映射到了源码目录方便你边读边对照代码组件源码位置一句话职责API Serversrc/api/暴露 E2B 兼容的 HTTP API 与反向代理入口Orchestrator 编排器src/orchestrator/沙箱生命周期状态机、持久化与自动清理Firecracker 运行时src/sandbox/firecracker/创建并控制每个沙箱的 microVMoverlaybd 存储storage/overlaybd/基于 LSMT 的分层镜像根文件系统层栈ublk 块设备storage/ublk/用户态块设备服务把镜像暴露为/dev/ublkbN快照管理器src/snapshot/提交、解析、删除持久化快照模板构建器src/template/构建用户模板并发布其提交后的快照 一个值得注意的设计存储 I/O 的重活被隔离在独立守护进程uvm-ublk-daemonstorage/ublk-daemon/里通过 Unix 域套接字 RPC 与节点主进程通信。这样 io_uring 控制与设备生命周期集中在一个进程而节点服务器只负责编排状态互不拖累。三、完整数据流一个创建沙箱请求的旅程我们以POST /sandboxesE2B 兼容接口为例追踪请求在节点内的完整路径。第 1 站API 层Axum HTTP 服务器请求首先到达由 Axum 构建的 HTTP 服务器。在 server.rs 中可以看到路由装配顺序先挂载生成的控制面 API 路由再合并手写的/proxy/*反向代理入口、镜像构建路由与/metrics最后叠加沙箱代理分类中间件和API Key 鉴权中间件。鉴权在这里完成所有控制面请求必须携带部署级X-API-Key。数据面流量进入沙箱内部的请求则由沙箱自身的凭证校验两条路径严格分离。第 2 站编排器生命周期状态机API 层验证请求后交给编排器驱动状态转换。沙箱状态机定义了 8 个状态定义在 types.rsCreating → Running → Pausing → Paused → Resuming → Running ↓ Killing编排器同时负责三件事持久化沙箱元数据写入存储节点重启后 Paused 沙箱依然可恢复自动驱逐超时的沙箱被自动清理释放 CPU 与内存增量指标运行中沙箱数、已分配 CPU/内存等计数器随生命周期事件实时更新第 3 站Firecracker microVM 启动编排器调用 Firecracker 后端sandbox.rs完成三件关键装配分配网络插槽从网络插槽池取一个预热好的 network namespace含 veth TAP避免冷启动时的命名空间创建开销挂载块设备通过 ublk 守护进程创建 overlaybd 块设备作为根文件系统/dev/vda额外数据盘挂为/dev/vdb启动 microVM通过 Firecracker API socket 配置 CPU、内存、boot source 并触发启动第 4 站存储子系统——真正的性能核心 这是 AgentENV 架构中最精妙的部分。虚拟机看到的磁盘其实是一个分层镜像栈/dev/vda ← /dev/ublkbN用户态 ublk 块设备 ↓ overlaybd 层栈 ├── upper可读写层最新写入 ├── layer N … layer 2只读压缩层 └── layer 0基础镜像层读路径ImageFile 从顶层向下查找段索引第一个包含该块映射的层提供服务数据写路径所有写入只追加到顶部可写层底层只读层永远不被修改。块设备怎么来的Linux 内核 ublk 驱动 用户态服务storage/ublk/src/ctrl.rs用户态通过 io_uring 向/dev/ublk-control发送ADD命令内核分配设备 ID创建/dev/ublkcN控制与/dev/ublkbN块设备每个队列一个 worker 线程异步处理内核分发的 I/O虚拟机把它当作普通磁盘读写零额外系统调用开销分层镜像的三大好处按需加载OCI 镜像层可从 registry/OSS 远程拉取本地磁盘只作有界缓存集群镜像总量可超出本地磁盘容量数个数量级⚡写时复制同一模板启动的多个沙箱共享全部只读层只有 upper 层独立快照即分层暂停时上层被封存为新的只读层create_snapshot_and_restack再开一个全新 upper整个过程不拷贝数据四、快照数据流为什么暂停 100ms、恢复 50ms暂停Pause的完整数据流aenv pause id → API: POST /sandboxes/{id}/pause → Orchestrator: Running → Pausing → Firecracker 创建 state-only diff 快照 → 查询脏内存区间用 process_vm_readv 读取选中内存 → 直接生成 overlaybd 内存层叠加在历史快照层之上 → 封存文件系统 upper 层 → SnapshotManager 提交到仓库S3 兼容对象存储 / 分布式文件系统 → Orchestrator: Paused元数据持久化内存与文件系统都走增量 diff只记录自上次快照以来变化的部分因此即使磁盘被大量修改暂停也能在 100ms 内完成。核心提交逻辑见 manager.rs。恢复Resume的完整数据流恢复路径是快照架构的精华所在从快照仓库解析出层栈固定产物会先尝试 P2P向同集群其他节点要命中不了才回源对象存储从分层内存镜像创建一个只读 ublk 块设备作为 Firecracker 的BackendType::File内存后端Firecracker 对块设备做 mmap首次写入时 COW写时复制到匿名内存——底层设备永不被修改同一快照恢复的多个沙箱引用计数共享同一个内存 ublk 设备Linux 页缓存在它们之间复用并发冷启动 I/O 大幅下降 传统 userfaultfd 缺页填充方案被 ublk 方案取代块设备 页缓存天然享受内核缓存无需用户态缺页处理线程。旧实现仍保留在 storage/uffd-core/ 供参考。五、网络数据流每个沙箱一个隔离命名空间每个运行中的沙箱拥有专用 Linux 网络命名空间Firecracker 通过 TAP 设备接入命名空间通过 veth 对连到宿主机。拓扑与报文路径详见 networking.md。关键机制一览地址规划由插槽索引派生宿主机交互 IP、veth/31链路地址、VM 固定链路地址内部地址池在用户放行规则之前被整体拒绝沙箱之间完全隔离透明出口代理需要域名策略时命名空间内 TCP 80/443 被 REDIRECT 到本地代理egress_proxy.rs代理解析 SNI/Host 后查可信 DNS策略失败即关闭fail-closed策略热替换iptables-restore批处理原子替换命名空间规则链存量连接不受影响网络预热池(network slot, Firecracker 进程)对可以预先创建恢复路径直接移交跳过 spawn 与 socket 等待六、分布式控制平面Gateway 与 Scheduler 如何协作多节点部署时客户端只面对一个 Gateway。数据流如下Client ──HTTP── Gateway(:8080) ├─ 新沙箱 → gRPC Schedule() 选节点 ├─ 已有沙箱 → gRPC LookupNode() 查绑定 └─ 创建成功后 → RecordAssignment() 播种沙箱→节点绑定 ↓ 反向代理 HTTP Node A / Node B (:8000)Gatewayservices/gateway/HTTP 反向代理。从路由头x-agentenv-sandbox-id/e2b-sandbox-id或基于 Host 的代理域名{port}-{sandboxID}.{domain}提取数据面路由控制面路由如 pause按 URL 路径中的沙箱 ID 路由。它还聚合GET /sandboxes、GET /nodes等跨节点列表请求Schedulerservices/scheduler/gRPC 服务维护内存中的沙箱→节点绑定表。RPC 包括Schedule、LookupNode、RecordAssignment、Heartbeat等契约见 scheduler.proto。调度策略支持round_robin默认与random绑定生命周期运行时节点心跳携带完整沙箱 ID 清单调度器将其视为事实来源心跳中缺失的绑定会被清除节点下线时UnregisterNode主动清理其名下绑定节点发现支持static配置显式列表与kuberneteswatch EndpointSlice取就绪 DaemonSet Pod IP两种模式⚠️ 一个诚实的设计取舍所有绑定都在内存中Scheduler 重启后绑定丢失但会通过新沙箱创建 各节点下一次心跳清单自动重建。可选加速层——P2P 制品传输src/p2p/快照提交成功后固定 Firecracker 产物与 overlaybd 层会经 P2P 层尽力广播解析时先问 P2P 再问对象存储让制品在集群内自然扩散。调度器只存/返透明的 peer 端点真正的目录查询与字节传输全部走节点直连。七、架构全景速查源码目录对照表目录内容src/api/HTTP API 层E2B 兼容端点 反向代理src/orchestrator/沙箱生命周期状态机与持久化src/sandbox/Firecracker 管理、网络命名空间、ublk 集成src/snapshot/快照仓库后端、运行时解析、P2P 发布src/template/用户模板构建器storage/overlaybd/LSMT 分层镜像核心本地/registry/tar 后端storage/ublk/ storage/ublk-daemon/用户态块设备与守护进程services/gateway/ services/scheduler/分布式控制平面Go 延伸阅读仓库内官方文档架构总览docs/src/internals/architecture.md沙箱网络docs/src/internals/networking.md反向代理设计docs/src/internals/proxy-design.mdP2P 设计docs/src/internals/p2p-design.md控制平面服务docs/src/internals/services.md八、总结AgentENV 架构设计的三个关键洞察存储即架构AgentENV 的性能故事完全由存储子系统书写——overlaybd 分层镜像让镜像仓库变成集群级无限缓存ublk 让块 I/O 停留在用户态却享受内核级效率快照 分层 写时复制文件系统快照是封存上层内存快照是只读块设备 COW两者都不做全量拷贝这才有了暂停 100ms、恢复 50ms 的硬指标平面分离、进程隔离API 编排、块 I/O、分布式路由分属不同进程乃至不同语言栈每个平面只对自己的延迟敏感路径负责互不拖累理解了这个API → Orchestrator → Firecracker → ublk → overlaybd的数据流主链你就掌握了 AgentENV 系统架构的骨架——无论是排查一次慢启动还是评估如何扩展集群都能从这张全景图快速定位到正确的模块。【免费下载链接】AgentENVAgentENV (AENV) is a distributed platform for running agent environments at scale.项目地址: https://gitcode.com/gh_mirrors/age/AgentENV创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考