容器镜像多架构发布如何校验 manifest list 与运行节点匹配

多架构镜像发布的关键，不是看到一个 tag 能拉下来，而是确认这个 tag 背后的 OCI image index（常被称为 manifest list）确实包含目标节点需要的 os、architecture 和必要的 variant，再核对运行时最终选择的 digest。这样才能区分“索引覆盖了节点”和“应用在节点上完全兼容”这两个不同结论。

先区分单平台 manifest 与多平台 image index

单平台镜像通常只有一个 manifest，里面关联一套配置和层；多平台镜像则先返回一个 image index，再由其中的 manifests 数组指向不同平台的 manifest。OCI 规范要求 index 的 schemaVersion 为 2，平台描述至少应能表达操作系统与 CPU 架构。

因此，发布后不要只检查 tag 是否存在。先记录索引的媒体类型、条目数量和每个条目的平台字段，再确认目标平台各有且只有一个可用条目。

读取 os、architecture 与 variant 的匹配关系

把发布目标和节点信息写成同一张表，避免只看“ARM”或“x86”这种过粗的标签。os 描述操作系统，architecture 描述 CPU 架构；在 ARM、AMD64 等存在变体时，还要关注 variant。例如 linux/arm64 与 linux/arm/v7 不是同一个选择条件。

用 inspect 与运行时信息核对实际拉取的 digest

下面的命令只是发布检查示例，输出字段需要按所用 registry 和客户端版本解释。命令中的中文注释说明了为什么查看这些字段：

# 查看 tag 背后的平台条目，确认索引不是单一架构
docker buildx imagetools inspect registry.example.com/demo/app:1.4

# 查看节点可见的平台信息，避免只依据调度标签判断架构
kubectl get nodes -o custom-columns=NAME:.metadata.name,OS:.status.nodeInfo.operatingSystem,ARCH:.status.nodeInfo.architecture

# 在目标节点读取容器运行时看到的镜像摘要，核对是否落到预期条目
crictl inspecti registry.example.com/demo/app:1.4 | grep -E 'repoDigest|architecture|os'

核对时先从索引中找到目标平台的 digest，再与节点实际拉取记录比较。若 tag 使用了缓存，必须确认比较的是当前部署得到的 digest，而不是本地旧镜像名称。

架构匹配后仍要处理二进制与特性边界

索引选择正确，只能证明客户端找到了相符的平台 manifest。应用仍可能因为本地编译产物、CPU 指令集、动态库、内核能力或配置文件不同而启动失败。尤其是同一 linux/amd64 条目，也不代表所有 CPU 特性都一致。

发布清单建议保留三项证据：构建命令声明的目标平台、索引中对应条目的 digest、目标节点启动后的架构与健康检查结果。对 Go 程序，还应把 GOOS、GOARCH 和是否启用 cgo 作为构建元数据记录下来。

相关问题

manifest list 和 OCI image index 是一回事吗？

在实际工具语境中常被互称。OCI 规范名称是 image index，Docker 文档常用 manifest list；写校验脚本时应以返回的媒体类型和字段结构为准。

为什么 amd64 节点拉到了 arm64 镜像？

优先检查索引中的平台字段、节点真实架构、镜像缓存以及是否经过了不识别平台的代理。不要只看业务 tag，直接比较最终 manifest digest。

平台条目缺少 variant 就一定错误吗？

不一定。variant 是可选字段，但当目标 CPU 需要区分变体时，缺少它会降低选择判断的可靠性，应按运行时和镜像构建工具的约定补齐或明确兼容范围。