用途:介绍 Capsem VM 资产(kernel、initrd、rootfs)如何构建、校验、解析与在启动时验证,用于调试启动失败、manifest 异常与哈希不匹配问题。
主要能力与规则:选中的 manifest 是唯一权威,未列入其中的制品在发布、更新、缓存和启动路径中都不存在,不得从缓存目录、发布附件、文件名或渠道名推断成员关系;可变 manifest 需重新获取,缓存只存不可变制品字节,按 manifest 记录的 digest 直接寻址并在每次使用前重新校验。二进制与资产版本相互独立:二进制为当前发布线 1.3.{unix_timestamp},每次构建都变;资产为 YYYY.MMDD.patch,仅在重建 kernel/rootfs/initrd 时变。manifest 用兼容范围(min_binary、min_assets)同时记录两者,并在运行时双向约束。
关键命令:全量重建用 just _build-assets;日常用 just shell(重打包 initrd、构建、签名、启动);用 just shell "capsem-doctor" 验证启动。macOS 上 Docker 相关配方依赖 Colima,连接异常时按 /dev-setup 的恢复流程处理:检查 colima list、docker version、colima ssh -- docker ps,并尝试 colima stop && colima start。
启动解析:开发模式由 Service 检测 arch 子目录并以 --kernel 等参数传给 capsem-process;安装模式读取 v2 manifest,经 ManifestV2::resolve(binary_version, arch, base_dir) 解析为基于哈希的路径,再分别传 --kernel、--initrd、--rootfs;启动时 VmConfig::builder().build() 用 BLAKE3 与编译期哈希校验。清理由 cleanup_unused_assets(base_dir, manifest) 完成,移除未被任何非弃用版本引用的哈希命名文件及旧 v*/ 目录。
限制与注意事项:哈希期望值有两种写法,asset manifest 为裸十六进制,release-graph digest 与派生 profile pin 带 blake3: 前缀,由 VmConfigBuilder::verify_hash 统一解析并拒绝非 blake3 算法;日志中的 pin 应完整记录、不可截断。启动仅校验正在启动的 profile 的 pin,缺失即硬错误。若 build.rs 无法提取哈希,校验会被跳过。持久恢复有独立权威,不得用当前 profile 覆盖保存的 vm/active_profile.toml;已安装 manifest 撤销、保存 profile 损坏、pin 资产缺失或 rootfs 几何无效会阻止启动。其他平台、许可证与价格信息暂未提供。