指定--platform linux/amd64拉取Docker镜像时摘要不匹配问题

现象说明 #

• 不带--platform参数拉取镜像时，docker pull bitnami/sealed-secrets-controller:v0.19.4返回的摘要和docker run --rm regclient/regctl image digest bitnami/sealed-secrets-controller:v0.19.4的结果完全一致
• 在arm64架构的Mac上，为了拉取amd64架构镜像添加--platform linux/amd64参数后，出现了摘要不匹配的情况：
  • 拉取命令返回的摘要：ca8b5651578f4909d15be21e81c4d7bdc76ff39e0e9f34f6a95e3ca4d26b7c0e
  • regctl指定平台查询的摘要：ed88880030cfe6b7325f6ab06d1667325228f7aa2d8b9f4fc6197acab181e165，这个值和docker manifest inspect显示的linux/amd64平台对应摘要一致，但和拉取时的输出不匹配

本质原因 #

这不是--platform参数导致的异常，而是Docker CLI和regctl返回的摘要层级不同：

• docker pull输出的摘要是镜像manifest list（多平台索引镜像）的哈希值——哪怕指定了--platform，Docker仍会先拉取整个manifest list，再从中筛选对应平台的镜像，但CLI输出的还是顶层索引的哈希
• regctl image digest --platform和docker manifest inspect返回的是指定平台镜像的独立manifest哈希，属于索引下的子层级，两者本身就不是同一个对象的哈希，自然不匹配

验证步骤 #

1. 确认本地镜像的manifest类型：

   docker inspect bitnami/sealed-secrets-controller:v0.19.4 | jq '.[0].ManifestType'
   

   若输出为application/vnd.docker.distribution.manifest.list.v2+json，说明本地存储的是多平台索引，而非单一平台的镜像manifest。

2. 手动计算指定平台manifest的哈希：

   docker manifest inspect bitnami/sealed-secrets-controller:v0.19.4 --platform linux/amd64 | jq -c . | sha256sum
   

   结果会和regctl返回的摘要完全一致，证明这才是目标平台镜像的真实manifest哈希。

解决方案 #

如果需要确保拉取的是指定平台的正确镜像，可以：

• 查看镜像的RepoDigests字段，里面同时包含了manifest list的摘要和对应平台镜像的摘要（格式为bitnami/sealed-secrets-controller@sha256:<平台哈希>）：

  docker inspect bitnami/sealed-secrets-controller:v0.19.4 | jq '.[0].RepoDigests'
  

• 直接通过平台哈希拉取镜像，跳过manifest list的匹配步骤：

  docker pull bitnami/sealed-secrets-controller@sha256:ed88880030cfe6b7325f6ab06d1667325228f7aa2d8b9f4fc6197acab181e165
  

内容的提问来源于stack exchange，提问作者Cdhippen