数据截至 (上游 commit aae05d825bb5)
OCI 镜像到可启动根文件系统
30 秒导读: 你写
docker.io/library/python:3.12,microsandbox 要把它变成一块 microVM 能挂载启动的磁盘。别的运行时会把每层 tar 解包到一个目录再用 overlayfs 叠起来;microsandbox 从不解包——它把每层单独烤成一个 EROFS 只读镜像(按内容哈希缓存),然后用一张"只有元数据、数据块指针指回各层"的 fsmeta 镜像加一个 VMDK 描述文件,零拷贝地把它们拼成一块盘。本章讲清这条流水线的每一步。
本章是 microsandbox 系列的第 3 章。相邻章节:进程与生命周期见 01-lifecycle,主机↔客机通信见 02-protocol-relay,rootfs 挂进 VM 之后客机里的可写层与写时复制见 04-guest-filesystem。本章只到"生成好那块只读盘"为止。
代码全部在 crates/image/lib 下(as-of commit 517d139)。
1. 这是什么(零基础也能懂)
一句话定义
把一个 OCI/Docker 镜像(比如 python:3.12)从远端 registry 拉下来,变成一个 microVM 可以当磁盘挂载、开机就能跑的根文件系统。
它要解决的问题
镜像在 registry 里的样子,和 VM 需要的样子,不是一回事:
| registry 里的镜像 | VM 需要的 rootfs | |
|---|---|---|
| 形态 | 一叠压缩 tar(每层一个 .tar.gz) | 一块能挂载的块设备 / 磁盘镜像 |
| 结构 | 增量层,还带"删除标记" | 合并后的最终文件树 |
| 访问 | 要解压、要按顺序叠 | 内核直接寻址、只读挂载 |
传统做法:把每层 tar 解包到磁盘上一个目录,再用 overlayfs 把这些目录叠成一个视图。microsandbox 面向的是 microVM(轻量虚拟机,不是容器),客机内核要的是一块盘,不是主机上的一个目录;而且它想要内容寻址的全局缓存和零数据拷贝的层复用。于是它选了另一条路(见 §5)。
用起来什么样
对上层(SDK / CLI)来说,这一大坨复杂度浓缩成一次 pull:
// 示意,非源码:真实入口是 Registry::pull()
let cache = GlobalCache::new(&cache_dir)?; // 打开全局缓存
let registry = Registry::new(Platform::host_linux(), cache)?; // linux/本机架构
let result = registry.pull(&"python:3.12".parse()?, &PullOptions::default()).await?;
// result.manifest_digest 就是这块 rootfs 的身份;
// 缓存里此刻已经躺着一个 <manifest>.vmdk,VM 挂它即可启动。
真实签名见 crates/image/lib/registry/client.rs:177 的 Registry::pull。它返回 PullResult(crates/image/lib/pull.rs:55),里面有层的 diff_id 列表、解析好的 ImageConfig(entrypoint/env/cmd 等运行时默认值)和 manifest_digest。
一句话直觉
把镜像想成"一叠透明胶片",每张胶片(层)画了一些文件、也可能划掉下面的文件。 microsandbox 不把胶片摞在灯箱上看(overlayfs),而是给每张胶片单独扫描存档(每层一个 EROFS),再画一张"总索引"说明最终每个像素来自哪张胶片(fsmeta),最后把索引和所有胶片钉成一册(VMDK)。
2. 顶层全景(它大概怎么转)
主线:从镜像引用到 .vmdk
怎么读这张图: 从上到下是一次 pull 的时间顺序;方框是阶段,右侧是落在缓存里的产物。核心是层级并发——中间那段每层各跑一条流水线。
Registry::pull(reference, options) crates/image/lib/registry/client.rs:157
│
▼
① 取镜像级 flock + 早缓存命中检查 ──── 命中就直接返回 ──► (manifests/<hash>.json 齐 → 秒回)
│ 未命中 / policy=Always / force
▼
② 拉 manifest + config,选平台 ────────────────────► 多架构 index → 挑 linux/arm64 那张
│ (fetch_manifest_and_config → parse_and_resolve_manifest)
▼
③ 解析 config 得 diff_ids + 层描述符 ──────────────────► 校验:层数 == diff_id 数
│
▼
④ 每层并发跑流水线(信号量限并发 ≤16):
┌───────────────────────────────────────────┐
│ 下载 .tar.gz ─► 校验压缩层 digest │──► layers/<blob>.tar.gz
│ 解压+摄取 tar ─► 建 FileTree,算 diff_id │──► (顺带校验 diff_id)
│ 写 EROFS 只读镜像 │──► layers/<diff_id>.erofs
└───────────────────────────────────────────┘
│
▼
⑤ 合并所有层的树(处理 whiteout/opaque)→ 写 fsmeta ──► fsmeta/<manifest>.erofs
│
▼
⑥ 拼 VMDK 描述文件([fsmeta][layer0][layer1]…) ──────► vmdk/<manifest>.vmdk ← VM 挂这个
部件一句话职责
| 部件 | 干什么 | 在哪(crates/image/lib/) |
|---|---|---|
Registry | 拉取编排器:锁、缓存、平台、进度、并发 | registry/client.rs:59 |
PullPolicy / PullOptions | 决定"要不要联网、要不要强制重来" | pull.rs:13 / pull.rs:28 |
RegistryAuth | 匿名 or 用户名密码鉴权 | auth.rs:18 |
Platform | 多架构镜像里选哪张 manifest | platform.rs:17 |
Layer | 单层的下载 + 断点续传 + digest 校验 | layer/download.rs:35 |
GlobalCache | 内容寻址的全局缓存 + 目录布局 | cache/store.rs:65 |
Digest | OCI 摘要 sha256:…,内容寻址的键 | digest.rs:13 |
tar ingest | tar 流 → FileTree,处理 whiteout | tar/ingest.rs:190 |
FileTree / merge | 内存文件树 + 层合并 | tree/model.rs:161 / :689 |
write_erofs | 把一棵树写成 EROFS 只读镜像 | erofs/writer.rs:149 |
write_fsmeta | 写"只有元数据、指回层数据"的 EROFS | erofs/fsmeta.rs:97 |
write_vmdk_descriptor | 把多个 EROFS 拼成一块虚拟盘 | stitch/vmdk.rs:20 |
ext4 format_ext4 | 给可写上层格式化空 ext4(→04) | ext4/formatter.rs |
3. 核心原理(逐个机制,由浅入深)
3.1 拉取管线:什么时候才联网
要解决的小问题: 拉镜像很贵(下载 + 解压 + 建镜像)。绝大多数时候本地缓存已经有了,不该重复干活;但有时又要强制刷新。怎么用一个开关表达清楚?
两个正交的旋钮。 microsandbox 把"要不要联网"和"要不要重做本地产物"拆成两个独立字段(pull.rs:28):
// 真实定义 crates/image/lib/pull.rs:28
pub struct PullOptions {
pub pull_policy: PullPolicy, // 何时联系 registry
pub force: bool, // 即使有缓存也重下、重建
}
PullPolicy 三态(pull.rs:13):
| 取值 | 含义 | 典型场景 |
|---|---|---|
IfMissing(默认) | 缓存全在就用缓存,否则拉 | 日常启动 |
Always | 总是拉 manifest 校验新鲜度,但 digest 没变的层仍复用 | 追 :latest |
Never | 绝不联网,本地没有就报 NotCached | 离线 / 气隙环境 |
早缓存命中是"全都在才算数"。 pull_inner 第一件事(拿到镜像级锁之后)就是 resolve_cached_pull_result_async(client.rs:1457):它读持久化的镜像元数据,然后逐项检查——每层 EROFS 在不在、fsmeta 在不在、VMDK 在不在,任何一样缺了都判未命中、走完整拉取。只有全齐才秒回(client.rs:332)。
校验镜像有效不是看"文件存不存在",而是看"字节对不对齐"。 一个被中断的写会留下半个文件。is_valid_erofs_artifact 用一个便宜又靠谱的判据:非空 且 长度是 4096 的整数倍(EROFS 块大小),不满足就当它无效(cache/store.rs:636,EROFS_ALIGNMENT_BYTES = 4096 在 :35)。
3.2 平台选择:一个引用,多张 manifest
要解决的小问题: python:3.12 在 registry 里往往是一张"胖 manifest"(OCI index),下面挂着 amd64、arm64、armv7… 各一张真 manifest。要挑出跟本机匹配的那张。
先认出这是不是 index,再挑。 parse_and_resolve_manifest(client.rs:537)先从 JSON 里嗅 mediaType,若是 index 就进 resolve_platform_manifest(client.rs:560)遍历候选:OS 必须等、架构必须等,variant(如 armv7 的 v7)优先精确匹配、否则退而求其次取架构匹配的第一张(client.rs:596-609)。attestation 那种伪 manifest 直接跳过。
目标平台默认锁死 linux。 microVM 客机永远是 Linux,所以 Platform::host_linux()(platform.rs:57)只探测本机架构(x86_64→amd64、aarch64→arm64),OS 硬编码 linux。
同一套逻辑还塞给了底层 oci-client。 RegistryBuilder::build 在构造 oci_client::Client 时把 platform_resolver 也设成 resolve_platform_digest(builder.rs:99、client.rs:1325),这样连底层库自己解析 index 时也用同一个平台偏好,不会各挑各的。
3.3 层下载:内容寻址 + 断点续传 + 并发安全
要解决的小问题: 层可能几百 MB;下载可能中断;多个进程可能同时拉同一个镜像。既不能重复下,也不能下坏,还不能互相踩。
内容寻址是一切的地基。 每层的键是它的 Digest(sha256:…),文件名由 Digest::to_path_safe() 把 : 换成 _ 得来(digest.rs:46)。同一层无论被多少镜像引用,在缓存里只有一份 layers/<digest>.tar.gz。
下载三态,让"续传"落地。 determine_download_start(layer/download.rs:348)先看已存在的 .part 文件,给出:
.part 不存在 / 空 → Fresh 从头下
.part 大小 == 期望 && 整文件哈希对得上 → Complete 直接改名成品,连网都不用连
.part 大小 < 期望 → Resume(n) 从第 n 字节继续(HTTP Range)
.part 大小 > 期望 / 哈希不对 → 删掉,Fresh
哈希是边下边算,不事后重读。 下载循环里 hasher.update(&chunk) 增量喂 SHA-256(layer/download.rs:238),下完直接比对压缩层 digest,不匹配就删文件报 DigestMismatch(layer/download.rs:271)。续传时会先把已有字节喂进 hasher 再接着下(:226)。
并发用跨进程文件锁(flock)兜底。 下载前先对 <blob>.download.lock 上排他锁(layer/download.rs:88,锁实现在 cache/lock.rs:27,Unix 走 libc::flock)。拿到锁后再查一遍成品在不在——因为等锁期间别的进程可能已经下完了(layer/download.rs:108)。写完永远是先写 .part 再原子 rename(:281),并发读者绝不会看到半个文件。
一个刻意的设计:锁文件从不删。 见
client.rs:325的注释——稳定的 inode 防止 TOCTOU:两个进程如果对同一路径 flock 了不同 inode(因为中间有人删了重建),锁就形同虚设。
3.4 tar 摄取与树模型:把层变成一棵文件树
要解决的小问题: 一层 tar 里不只有普通文件,还有目录、符号链接、硬链接、设备节点,以及 OCI 特有的删除标记(whiteout)。要把这些忠实地变成一棵可合并的内存树,还要防路径穿越攻击。
摄取即建树。 ingest_tar(tar/ingest.rs:190)逐条读 tar entry,按类型建 TreeNode(tree/model.rs:121:普通文件 / 目录 / 符号链接 / 字符&块设备 / FIFO / socket),插进 FileTree。
顺手算出 diff_id 做内容信任校验。 外层 ingest_compressed_tar(tar/ingest.rs:416)按压缩类型(gzip/zstd 由 media type 判定)套一个解码器,再包一层 HashingReader(:483)——它在解压流经过时算 SHA-256。这个哈希就是解压后的 diff_id。回到主流水线,拿它跟 config 里签过名的 diff_id 比对(client.rs:890-899),对不上就是层被篡改,报 DigestMismatch。压缩层 digest 保下载完整性,解压 diff_id 保内容信任,两道关。
whiteout:把 OCI 删除语义翻成 overlayfs 原生表示。 classify_whiteout(tar/ingest.rs:652)识别两种约定,并当场转换:
| tar 里的名字 | OCI 含义 | 转成树里的什么 |
|---|---|---|
.wh.<name> | 本层删除下层的 <name> | 一个 (major=0,minor=0) 的字符设备节点 |
.wh..wh..opq | 本目录对下层"不透明"(藏掉下层全部内容) | 父目录加 trusted.overlay.opaque=y xattr |
这两个常量在 tree/model.rs:25-30。转成 overlayfs 原生表示,是为了后面合并时能统一处理(§3.5),也为了 EROFS 直接就是 overlayfs 能理解的下层。
路径规范化 = 安全边界。 normalize_path(tar/ingest.rs:524)剥掉 ./ 和前导 /,拒绝任何 .. 分量(防路径穿越写出 rootfs),并施加长度 / 深度上限(默认 4096 / 128,tree/model.rs:18-19)。测试 normalize_rejects_dotdot、ingest_accepts_absolute_path_in_tar 覆盖了这些边界。
大文件不进内存,spool 到磁盘。 ≥ 64 KiB(SPOOL_THRESHOLD,tree/model.rs:84)的文件体不塞进 Vec,而是流式写到一个共享 spool 文件,树里只记 (offset, len)(tar/ingest.rs:330、FileData::Spool 见 tree/model.rs:47)。这让摄取几个 GB 的层也不爆内存。
3.5 层合并:算出"最终每个文件来自哪一层"
要解决的小问题: N 层从下往上叠,上层覆盖下层、whiteout 删除下层。要算出合并后的最终文件树,并且——关键——记住每个最终文件的数据来自第几层(后面 fsmeta 要按这个指回层数据块)。
一趟合并,同时产出树和 provenance。 merge_layers_with_provenance(tree/model.rs:689)从底层到顶层依次 merge_directory_with_provenance,维护一张 路径 → 层号 的 provenance 表:
遇到 whiteout 字符设备 → 从合并树删掉该项,并连带删掉它及子孙的 provenance
遇到 opaque 目录 → 清空该目录已有内容,再叠本层内容
遇到普通文件/目录 → 覆盖,并记 provenance[路径] = 当前层号
判定 whiteout 用 is_whiteout_device(:802,认 major=0 minor=0 的字符设备),判定 opaque 用 xattr(:806)。
合并后把 overlayfs 指令"吃掉"。 和 merge_layer(那个会保留 whiteout 供再叠)不同,provenance 版消费掉 whiteout 和 opaque xattr,输出的是干净的最终态(:704 附近调用 strip_opaque_xattrs,定义在 :792)。因为 fsmeta 要的是"最终有哪些文件",不是"怎么叠出来的"。
3.6 EROFS 只读镜像:把树烤成内核能挂的格式
要解决的小问题: 有了内存里的树,怎么变成 microVM 内核能直接只读挂载的东西?
EROFS 是什么。 EROFS(Enhanced Read-Only File System)是 Linux 内核里的只读文件系统,专为"一次生成、多次挂载、不改"的场景设计——正好是容器/VM 的 rootfs。microsandbox 自己实现了一个最小 EROFS 写入器(erofs/writer.rs)和读取器(erofs/reader.rs,只支持自己写出的那个子集)。
每层单独烤一个 EROFS。 主流水线在每层摄取完树后,spawn_blocking 里调 write_erofs(erofs/writer.rs:149)把这一层的树写成 layers/<diff_id>.erofs,并返回一张 ErofsDataMap(:41)——记录每个文件的数据落在镜像里的第几块、多大。这张 map 是后面 fsmeta"指回数据块"的凭证。
write_erofs 分五趟(writer.rs:153-170):规划布局并分配 NID → 写数据块(顺便填 data map)→ 写元数据(inode + 目录项)→ 写超级块 → 补齐到 4096 块 + 512 扇区对齐(为了 virtio-blk)。目录项按名字排序打包进块,内核对每块做二分查找(writer.rs:372 附近的注释)。
写完立刻把树里的文件数据丢掉。 层 EROFS 一落盘,tree.strip_file_data()(tree/model.rs:522)把树里每个文件的数据清空、只留目录结构和元数据——因为接下来的 fsmeta 合并只需要结构,数据已经在层 EROFS 里了。这是控制内存的关键一手。
3.7 fsmeta + VMDK:零拷贝地把层拼成一块盘
这是整章最巧的一步,单独拉到 §4 讲透。一句话预告:合并后的 rootfs 不复制任何文件数据——fsmeta 是一张只装元数据的 EROFS,它的文件 inode 用"块索引"通过 EROFS 设备表指向各层 EROFS 里的数据块;VMDK 描述文件再把 [fsmeta][layer0][layer1]… 摆成一块连续虚拟盘。
4. 深入实现:fsmeta 设备表与 VMDK 拼接
4.1 为什么不直接写一个"合并后的大 EROFS"
技术上完全可以:把合并树连数据一起写成一个巨大的 EROFS。但那样每拉一个新镜像都要把所有共享层的数据再拷一遍——python:3.12 和 python:3.12-slim 共享的 glibc 层会被复制两份。microsandbox 的选择是:层数据只存一份(在各自的 layers/<diff_id>.erofs 里),合并只在"元数据 + 指针"层面发生。
4.2 fsmeta:只有元数据的 EROFS
write_fsmeta(erofs/fsmeta.rs:97)接收合并树、provenance 表、和各层的 ErofsDataMap,产出一张特殊 EROFS:
- 目录、符号链接:照常用扁平布局,数据(目录项)就在 fsmeta 自己里。
- 普通文件:用 chunk-based inode(
EROFS_INODE_CHUNK_BASED,format.rs:45)——inode 本身不含数据,而是跟一串块索引,每个索引写着"到几号设备、第几块去取"。
设备表把"层"编号成"设备"。 fsmeta 头部写一张设备表(write_device_table,fsmeta.rs:212),每层一个槽位,记录该层 EROFS 的总块数和它在最终虚拟盘里的起始块地址(mapped_blkaddr,累加得出)。设备 0 是 fsmeta 自己, 设备 i+1 是第 i 层。
块索引 = (设备号, 起始块)。 write_chunk_indexes(fsmeta.rs:912)对每个 chunk-based 文件,用 provenance 查到它来自第几层,取 device_id = layer_idx + 1,再从那层的 data map 查到文件的起始块,写进索引条目(fsmeta.rs:919-934)。于是内核读这个文件时,顺着 inode → 块索引 → 设备表 → 落到某层 EROFS 的某块,数据一个字节都没搬。
fsmeta.erofs 各层 EROFS(独立缓存,零拷贝)
┌───────────────────────────┐
│ 超级块 + 设备表 │ 设备1 → layers/<diffA>.erofs
│ dev1: blocks=…, addr=… │───┐ 设备2 → layers/<diffB>.erofs
│ dev2: blocks=…, addr=… │ │
├───────────────────────────┤ │ /usr/bin/python 的数据:
│ 目录树 inode(数据在本地) │ │ inode(chunk-based)
│ /usr/bin/python inode: │ └──► 块索引[(dev=1, block=1234), …]
│ 块索引 ─────────────────────────► 实际字节在 设备1 的 1234 块
└───────────────────────────┘
4.3 VMDK:把多个 EROFS 摆成一块盘
设备表里的"起始块地址"要落到一个真实的连续地址空间里。write_vmdk_descriptor(stitch/vmdk.rs:20)干这个:它写一个 VMDK flat 描述文件(纯文本,不含数据),把 [fsmeta][layer0][layer1]… 每个文件当作一个 extent,声明"从盘的第几扇区起、映射到哪个文件"。
VMDK 描述文件(twoGbMaxExtentFlat) 虚拟盘地址空间
RW <n0> FLAT "…/fsmeta.erofs" 0 ┌────── ────┐ 0
RW <n1> FLAT "…/layerA.erofs" n0 │ fsmeta │
RW <n2> FLAT "…/layerB.erofs" n0+n1 ├──────────┤ n0 ← 设备表里 dev1 的 addr
… │ layerA │
├──────────┤ ← dev2 的 addr
│ layerB │
└──────────┘
每个 extent 必须 512 字节对齐(所以 §3.6 里 EROFS 结尾要补到 512 扇区),超过 2 GiB 的文件拆成多行(MAX_EXTENT_SECTORS,stitch/vmdk.rs:9)。VM 挂载这个 .vmdk,内核只认识一块盘;盘头是 fsmeta(块 0 的 EROFS 超级块),内核挂载它、顺着设备表和块索引就能读到后面各层的数据。这就是"按引用组装 rootfs"的全貌。
4.4 相位级幂等:只重建缺的那部分
materialize_layers_and_fsmeta(client.rs:674)不是无脑重来,而是先看哪 些产物已在:层 EROFS、fsmeta、VMDK 各查一遍(client.rs:709-716)。
| 已有状态 | 动作 |
|---|---|
| 层 + fsmeta + VMDK 全在,非 force | 直接返回,啥都不干 |
| 层 + fsmeta 在,只缺 VMDK | 只重拼 VMDK(regenerate_vmdk_only,client.rs:1169) |
| fsmeta 缺 | 强制层重新产出树(否则缓存层会短路成 tree=None),再生成 fsmeta |
| 某些层缺 | 只补那几层 |
fsmeta/VMDK 生成同样用镜像级 flock 保护、拿锁后再查一遍(client.rs:994),防并发重复生成。写产物一律临时文件 + 原子 rename(client.rs:1124、:1147)。
4.5 并发流水线的骨架
层任务不是顺序跑,而是每层 tokio::spawn 一条任务,用一个信号量限制同时活跃数(client.rs:738,上限 MAX_LAYER_PIPELINE_CONCURRENCY = 16,:49;实际取值按 CPU 核数算,layer_pipeline_concurrency,:1526)。任务内部:拿信号量 → 查缓存(命中且非 force 就返回 tree=None)→ 下载 → 拿层级 flock → 再查一遍 → 摄取 tar → 校验 diff_id → 写 EROFS → strip 树。全部完成后 wait_for_layer_tree_pipeline(client.rs:1425)收集结果,保留第一个错误并整体失败。
重复层的坑。 一个 manifest 里可能有相同 digest 的重复层。代码对此有专门处理:重复 diff_id 时只有第一个任务真建 EROFS,其余拿到缓存返回 tree=None,合并阶段再按 diff_id 把树克隆回各位置(
client.rs:1026-1058)。强制重下会和"另一个任务正要读同名 tar"竞争,所以下载故意不 force、只有 materialization 才 force(client.rs:730附近的长注释)。
5. 巧妙之处(可借鉴的技术)
-
"按引用合并"而非"拷贝合并"。 层数据只存一份,合并只发生在元数据 + 指针层。共享层在多个镜像间天然零成本复用。核心在 fsmeta 的 chunk-based inode + 设备表(
erofs/fsmeta.rs:912)加 VMDK 拼接(stitch/vmdk.rs:20)。 -
直接生成目标格式,跳过"解包到目录"这一步。 别的运行时:tar → 解包成目录 → overlayfs 挂载。microsandbox:tar → 内存树 → 直接烤 EROFS。少一次全量落盘、产物即挂载单元、天然内容寻址可缓存(
erofs/writer.rs:149)。 -
两道 digest 关,职责分明。 压缩层 digest 边下边算保下载完整性(
layer/download.rs:238);解压 diff_id 保内容信任(config 里签过名,client.rs:890)。 -
相位级幂等 + 内容寻址,让重复
pull几乎免费。 早缓存命中检查逐项验产物(client.rs:1457),有效性用"4096 对齐"这个便宜判据(cache/store.rs:636)。 -
跨进程 flock + 原子 rename + 从不删锁文件。 多个进程/沙箱可安全并发拉同一镜像;续传靠
.part三态机(layer/download.rs:348);稳定 inode 防 TOCTOU(client.rs:325)。 -
大文件 spool 到磁盘,树只留指针。 摄取多 GB 层不爆内存(
SPOOL_THRESHOLD,tree/model.rs:84);写完 EROFS 立刻strip_file_data(:522)进一步降内存。 -
快照 = 内容寻址的清单。
snapshot::Manifest(snapshot/manifest.rs:175)用规范字节形式(字段声明序、map 键排序、无省略)的 SHA-256 作为身份(:198),跨进程/平台稳定;它用manifest_digest指回不可变的镜像下层、用upper记录可写上层(ext4),从而把"从某镜像+某次改动"钉成一个可复现的构件。
6. 边界与局限
-
本章只到"生成只读盘"。 rootfs 挂进 VM 之后客机里的可写上层、写时复制、主机穿透属于 04-guest-filesystem。ext4 formatter(
ext4/formatter.rs)在本 crate 里,但它格式化的是空的可写上层,不是镜像内容——本章只顺带一提。 -
SDK 层的
Image句柄封装(sdk/rust/lib/image)不在本章;本章讲的是crates/image这个底层 crate。 -
EROFS reader 是"够用就好"。
erofs/reader.rs明确只支持自己写出的子集:扩展 inode、非压缩、排序目录项,不支持共享 xattr / 压缩 / chunk(reader.rs:1-8的注释)。它主要给 Append 补丁等场景读回自己的镜像用(read_file_from_erofs,reader.rs:981),不是通用 EROFS 实现。 -
快照链是半成品。
SnapshotFormat::Qcow2和Manifest::parent字段已在 schema 里占位,但今天只产Raw、parent恒为null(snapshot/manifest.rs:66、:107)——为将来 qcow2 backing chain 预留、不做 schema 迁移。 -
OS 恒为 Linux。 平台解析只为多架构 index 选架构,OS 硬编码 linux(
platform.rs:57);非 Linux 客机不在设计内。
7. 横向对比
同 shelf 的其它沙箱运行时(e2b、aio-sandbox、cua、k8s-agent-sandbox)大多复用现成容器栈(containerd / Docker / Firecracker 自带的镜像路径),把"镜像 → rootfs"外包给底层。microsandbox 的特别之处是自己从 OCI registry 一路手写到 EROFS/VMDK,以换取:内容寻址的全局缓存、零拷贝层复用、以及对 microVM 块设备启动路径的完全掌控。代价是要自己实现 registry 客户端、tar 摄取、EROFS/ext4 写入器——本 crate 的分量,大半来自这份"不外包"。
8. 代码地图(导航索引)
用符号名 grep 比行号抗漂移。全部相对 crates/image/lib/。
| 主题 | 文件 | 符号 |
|---|---|---|
| 对外入口 / 拉取编排 | registry/client.rs | Registry::pull、Registry::pull_inner |
| 拉取策略 / 选项 / 结果 | pull.rs | PullPolicy、PullOptions、PullResult |
| 早缓存命中检查 | registry/client.rs | resolve_cached_pull_result_async |
| 层级并发编排 | registry/client.rs | materialize_layers_and_fsmeta、layer_pipeline_concurrency |
| 只重拼 VMDK | registry/client.rs | regenerate_vmdk_only |
| manifest 解析 | registry/manifest.rs | OciManifest::parse、is_index |
| 平台选择 | registry/client.rs、platform.rs | resolve_platform_manifest、resolve_platform_digest、Platform::host_linux |
| 客户端构造 / TLS / 平台 resolver | registry/builder.rs | RegistryBuilder::build |
| 鉴权 | auth.rs、config.rs | RegistryAuth、RegistryAuth::Basic |
| 镜像 config 解析 | config.rs | ImageConfig::parse |
| 层下载 / 续传 / 校验 | layer/download.rs | Layer::download、determine_download_start、DownloadStart |
| 内容寻址摘要 | digest.rs | Digest、Digest::to_path_safe |
| 全局缓存布局 | cache/store.rs | GlobalCache、layer_erofs_path、is_valid_erofs_artifact |
| 跨进程锁 | cache/lock.rs | open_lock_file、lock_exclusive、flock_unlock |
| tar 摄取 | tar/ingest.rs | ingest_compressed_tar、ingest_tar、HashingReader |
| whiteout / 路径规范化 | tar/ingest.rs | classify_whiteout、normalize_path |
| 文件树模型 | tree/model.rs | FileTree、TreeNode、FileData |
| 层合并 + provenance | tree/model.rs | merge_layers_with_provenance、is_whiteout_device |
| 层 EROFS 写入 | erofs/writer.rs | write_erofs、ErofsDataMap |
| fsmeta 写入 / 设备表 / 块索引 | erofs/fsmeta.rs | write_fsmeta、write_device_table、write_chunk_indexes |
| EROFS 常量 / 格式 | erofs/format.rs | EROFS_INODE_CHUNK_BASED、EROFS_BLKSIZ |
| 最小 EROFS 读取器 | erofs/reader.rs | ErofsReader、read_file_from_erofs |
| VMDK 拼接 | stitch/vmdk.rs | write_vmdk_descriptor |
| 可写上层 ext4(→04) | ext4/formatter.rs | format_ext4、format_ext4_with_tree |
| 快照清单 | snapshot/manifest.rs | Manifest、Manifest::digest、SnapshotFormat |