AgentENV快照完全指南：如何实现沙箱毫秒级恢复与并行分叉

AgentENV快照完全指南：如何实现沙箱毫秒级恢复与并行分叉

【免费下载链接】AgentENVAgentENV (AENV) is a distributed platform for running agent environments at scale.项目地址: https://gitcode.com/gh_mirrors/age/AgentENV

AgentENV（简称 AENV）是一个用于大规模运行 Agent 环境的分布式平台，其核心能力之一就是沙箱快照：把运行中沙箱的内存与文件系统状态在 100 毫秒内增量捕获，之后既能毫秒级恢复出完全相同的环境，也能从一个运行环境并行分叉出多个独立沙箱，支撑大规模并行 Agent 工作流。本指南面向新手，带你从零理解快照的原理、创建、恢复与分叉全流程。

一、快照是什么：给沙箱拍一张"活照片" 📸

AgentENV 中的快照（Snapshot）是沙箱的可复用检查点。与普通备份不同，它冻结的是"活"的运行状态：

• VM 状态与内存：正在运行的进程可以从捕获点继续执行，而不是从头启动
• 根文件系统及其后续所有修改
• 附加磁盘与挂载卷的内容、挂载路径、大小和访问模式
• 运行配置：CPU、内存、磁盘规格，以及环境变量、工作目录、用户、启动命令等上下文

官方概念文档对这一点的描述见 snapshots/index.md。

💡 一个类比：模板（Template）本质上就是快照。模板构建会提交一个快照，模板 ID 只是指向它的一个别名。

关键性能数字

根据项目文档 overview.md 的说明：

操作	耗时
基于快照启动或恢复环境	< 50 毫秒
暂停（pause）环境	< 100 毫秒
增量快照捕获（含磁盘重写入场景）	< 100 毫秒

这背后是 AENV 的两个设计：内存和文件系统变更采用增量捕获，空闲环境可随时释放 CPU 和内存，有新任务到来时再毫秒级"复活"，让闲置环境几乎不花钱。

二、快照保留了什么、没保留什么

创建快照后，你可以用两种方式复用：

方式	说明	适用场景
aenv start <快照>	完整恢复：文件系统、进程、内存、环境变量、资源配置全部继承	需要"原地续跑"的任务
导出为 OCI 镜像冷启动	只保留根文件系统，不保留内存与进程状态	只想要"干净的文件系统起点"

如果只需要捕获的根文件系统，AgentENV 支持在创建快照时自动发布 OCI 镜像（针对 OSS 后端 + OverlayBD 原生镜像场景），详见 snapshots/use.md。

三、从运行中沙箱创建快照：3 行命令搞定

这是全文最关键的一步，命令只有这么长（文档：snapshots/create.md）：

# 基本用法：捕获指定沙箱的当前状态 aenv snapshot create <sandbox-id> # 推荐：附上一个易读的别名 aenv snapshot create <sandbox-id> --name my-checkpoint

两个要点：

1. 源沙箱不会被打断——捕获完成后它继续运行，快照是"旁路"复制的状态
2. 别名可省略——不写--name时，命令会返回生成的快照 ID，之后用它同样有效

创建之后，用下面命令随时启动一个继承全部快照状态的新沙箱：

aenv start my-checkpoint # 或：aenv start <snapshot-id>

这会创建一个拥有全新 sandbox ID的独立沙箱。

快照的日常管理

aenv snapshot list # 列出所有快照 aenv snapshot list --sandbox-id <id> # 只看某沙箱产生的快照 aenv template delete <snapshot-id> # 删除快照（快照与模板共用目录）

CLI 完整说明见 aenv-cli/snapshots.md。

四、并行分叉：一个沙箱变 N 个沙箱 🌱

分叉（Fork）是快照机制最"杀手级"的用法：把一个运行中的沙箱克隆成多个独立子沙箱，用于并行 Agent 工作流。

工作机制（文档：sandboxes/working.md）：

1. 源沙箱短暂暂停，捕获一份状态
2. 源沙箱随即恢复 Running
3. 所有子沙箱共享这同一份捕获状态，但彼此完全独立——每个子沙箱可以成功或失败，互不影响
4. 子沙箱继承源沙箱的文件系统、内存、网络策略、安全模式与 CPU/内存/磁盘配置

分叉通过 API 一次最多创建100 个子沙箱：

curl -X POST \ -H 'X-API-Key: test-key' \ -H 'Content-Type: application/json' \ -d '{"count": 3, "timeout": 600}' \ http://127.0.0.1:8000/sandboxes/<sandbox-id>/fork

请求中的count指要创建的数量（默认 1），timeout是子沙箱的存活时间（默认继承源沙箱 TTL）。响应数组会逐一给出每个子沙箱的sandboxID或失败原因。

挂载卷如何跟随分叉与快照？

如果你担心数据卷会被分叉"搅乱"，官方文档 sandbox-forks-and-snapshots.md 给出了明确答案，全程无需手动操作：

• 分叉时：每个exclusive（独占）卷自动做一次独立的写时复制（COW）分叉，子沙箱改自己的副本，互不干扰；ro（只读）卷则继续共享同一个只读卷
• 快照时：所有挂载卷自动纳入快照，记录层、大小、挂载路径和访问模式；从快照启动时会按捕获内容创建新卷并挂到相同路径

五、快照数据存在哪里：三层存储模型

理解持久化机制，才能放心把生产任务交给快照。AENV 的快照数据经过三层（文档：persistence-artifact-inventory.md）：

1. 构建暂存区：捕获进行中的临时工作空间，不是最终记录
2. 已提交快照仓库：真正的持久事实源，保存目录、别名、snapshot.json、VM 状态等，暴露给 API
3. 节点本地运行缓存：启动前物化出可运行的image.json等派生文件，可随时从已提交状态重建

已提交的快照可持久化到S3 兼容对象存储或共享分布式文件系统，即使节点故障数据也不会丢。

用 P2P 加速节点间分发 🚀

多节点集群中，新提交的快照可以在节点间"互相借"，而不用都回源到对象存储。只需在配置文件中开启（文档：snapshots/p2p.md）：

[p2p] enabled = true [snapshot] p2p_enabled = true

注意：P2P 只是可选的分发加速路径，快照仓库始终是持久事实源。

六、实战场景：暂停-恢复让闲置环境近乎免费

除了快照，AENV 还提供与之配套的pause/resume能力，二者常组合使用：

aenv pause <sandbox-id> # 保存状态并停止 microVM，释放 CPU 与内存 aenv resume <sandbox-id> # 从保存点恢复，进程从原处继续

暂停时程序不运行、服务不处理请求，但状态完整留在存储里，之后aenv connect连接暂停的沙箱还会自动恢复它。典型用法：

1. 构建好开发环境 →snapshot create存成检查点
2. 任务跑完pause释放资源
3. 新任务来了：从快照秒级start出新沙箱，或resume老沙箱
4. 需要并行实验时，直接对运行中的沙箱fork出 N 份

七、快速避坑清单 ✅

问题	答案
快照会中断源沙箱吗？	不会，捕获后源沙箱继续运行
删除源沙箱会影响快照吗？	不会，已创建快照独立存在；卷快照同理，删除源卷不影响已提交数据
从快照启动的沙箱和源沙箱是同 ID 吗？	不是，会分配全新的 sandbox ID
分叉最多能分多少个？	单次请求最多 100 个子沙箱
只想拿文件系统不要内存状态怎么办？	将快照 rootfs 导出为 OCI 镜像后aenv start --cold <image>冷启动

总结

AgentENV 的快照体系可以用三句话概括：100 毫秒内增量捕获、50 毫秒内恢复、一次分叉最多 100 份并行沙箱。它把"环境准备"这一通常最耗时的环节变成了近乎零成本的操作——无论是并行强化学习训练、批量实验还是弹性伸缩，快照与分叉都是你在大规模 Agent 平台上最重要的两个杠杆。

建议阅读顺序：快照概念总览 → 创建快照 → 沙箱分叉 → P2P 加速。

【免费下载链接】AgentENVAgentENV (AENV) is a distributed platform for running agent environments at scale.项目地址: https://gitcode.com/gh_mirrors/age/AgentENV