forkd Snapshot Hub使用教程：pack/pull/push三命令秒级分发预热快照（附sha256校验机制）

【免费下载链接】forkdFork() for AI agent microVMs. Spawn 100 children in ~100ms from a warm parent; BRANCH a live VM in ~150ms. KVM-isolated, snapshot CoW.项目地址: https://gitcode.com/gh_mirrors/fo/forkd

forkd Snapshot Hub 是 forkd 内置的快照分发注册表，让你把"配好环境、预热好的 microVM 快照"打包成.forkd-snapshot.tar.zst文件，一行命令拉到另一台机器上直接 fork——无需中央服务、无需登录、零成本。本文带你用 pack、pull、push 三个命令完成快照的打包、分发与校验，全程几分钟。

它解决什么问题

冷启动一个带 Python + numpy 环境的容器要 2~3 秒；而 forkd 从一个"预热好"的父快照 fork 一个子沙箱只要几十毫秒。Hub 的作用就是把这个预热快照从你的机器秒级搬运到别的机器：

• pull 端：一条命令下载 + 校验 + 解包 + 注册，之后forkd fork --tag <tag> -n 100直接开 100 个子沙箱；
• pack 端：一条命令把本地快照压成 zstd 小包（典型 10~100 MiB），带完整 sha256 清单；
• push 端：把打包好的快照以 HTTP PUT 直传你的对象存储（R2/S3 预签名 URL），实现私有分发。

整体设计只有三块，详见 docs/HUB.md：

1. 仓库根目录的 registry.json ——<owner>/<name>到下载地址 + sha256 的映射表；
2. 存放在 Release 上的.forkd-snapshot.tar.zst快照包；
3. forkd pull—— 拉取 registry、下载、校验、解包一条龙。

第一步：forkd pack 打包本地快照

前提是你已经有一个本地快照（比如用forkd from-image从 Docker 镜像烤出来的）。执行：

sudo HOME=$HOME forkd pack \ --tag mything \ --description "my warmed env" \ --base-image python:3.12-slim \ --out /tmp/pk/mything.forkd-snapshot.tar.zst

pack 会做三件事：

• 读取快照目录（vmstate+memory.bin缺一不可），逐文件计算 sha256，写入包内根部的manifest.toml；
• 用 zstd 压缩成单个.forkd-snapshot.tar.zst；
• 若 rootfs 存放在快照目录之外（from-image烤制的镜像），额外产出一个内容寻址的<sha256>.rootfs.zst侧车文件——两个文件要一起上传，否则包只能在原主机上恢复。

快照如果是 v0.5 的 diff 链（带parent_tag），pack 会自动走 v2 链式格式，把链上所有祖先一起打进去，接收方一次 pull 即可恢复整条链。实现细节可参考 crates/forkd-cli/src/hub.rs。

第二步：forkd pull 一行命令拉取并校验

拉取官方发布的预热快照只需：

pip install forkd forkd pull deeplethe/python-numpy # 下载 + sha256 校验 + 解包 forkd ls --snapshots # 确认本地已注册

pull 的完整流程（源码见 crates/forkd-cli/src/hub.rs 的download/unpack）：

1. 解析<owner>/<name>，从 registry 取下载 URL 和期望的 sha256（也支持@v1版本钉住）；
2. HTTPS 流式下载，带进度条（MiB/s + 百分比）；
3. 对下载文件整体算 sha256，与 registry 记录比对，不匹配直接拒绝解包；
4. 解包时再对包内每个文件逐条比对 manifest 里的 sha256，任何截断、位腐、篡改都会报错；
5. 快照路径自动改写为本机路径，注册到$XDG_DATA_HOME/forkd/snapshots/<tag>/，立即可用。

官方 Hub 已发布一批开箱即用的预热包，清单见 registry.json：

第三步：forkd push 上传到你的私有存储

如果你要内部分发（不想走公开 registry），用 push 直传对象存储：

sudo HOME=$HOME forkd push \ --tag mything \ https://r2.example.com/bucket/mything.forkd-snapshot.tar.zst?X-Amz-...

push 会在临时目录现打包，然后以 HTTP PUT 流式上传（不会把 GiB 级的memory.bin整个读进内存），支持进度显示；遇到 403 通常是预签名 URL 过期。接收方拿到 URL 后直接forkd pull <url>即可——注意裸 URL 拉取不走 registry，因此不做 sha256 比对，请自行保管好 URL 的访问控制。

拿到快照之后：fork 一百个子沙箱

sudo forkd fork --tag python-numpy -n 100

每个子沙箱都是 KVM 隔离 + 写时复制，内存共享父快照，几十毫秒一个。官方仓库里每个预热包都有配套配方，例如 recipes/python-numpy/、recipes/playwright-browser/，照着做就能复刻同款快照。

常见问题速查

• sha256 mismatch：registry 记录过期或下载被截断/篡改，重新 pull；仍失败则检查网络中间设备。
• pack format version N is newer：包由更新的 forkd 打出，升级 forkd 或让发布方用旧版重新 pack。
• 解包后本机无法恢复：老包缺少 rootfs 侧车（#242 之前的包），重新用新版 forkd 烤制 + pack 即可。
• 想换私有 registry：forkd pull <owner>/<name> --hub <url>或设置环境变量FORKD_HUB_URL，客户端无需升级。

安全提示：sha256 保证的是完整性而非来源真实性；pull 下来并运行一个包 = 信任其发布者（KVM 是最后一道隔离）。签名支持（Sigstore/cosign）计划在 v1.0 加入。

三步走总结：pack出带 sha256 清单的小包 → 放公开 Release 或push到私有存储 → 对方一行pull完成下载、双重校验与注册，随后秒级 fork 预热沙箱。

【免费下载链接】forkdFork() for AI agent microVMs. Spawn 100 children in ~100ms from a warm parent; BRANCH a live VM in ~150ms. KVM-isolated, snapshot CoW.项目地址: https://gitcode.com/gh_mirrors/fo/forkd