彻底理清 Docker 镜像的 Manifest、Digest 与 Image ID

为什么 Docker 的标识符让人头晕？

在使用 Docker 或镜像仓库（Registry）时，我们经常会碰到一堆看起来差不多的 Hash 值：Index Digest、Manifest Digest、Config Digest、Image ID、RepoDigests……

如果你不清楚 Docker 镜像的“俄罗斯套娃”结构，就很容易在调试镜像版本或处理多架构（Multi-arch）镜像时感到混乱。

---

核心架构：镜像的三层“清单”

要理清这些概念，我们需要从 Registry 返回内容的三个层级来看：

1. 第一层：Index（多架构索引）

当你执行 docker pull <image>:<tag> 时，Registry 实际上可能返回的是一份 Index（也叫 Manifest List）。

• 作用：它是一个索引，列出了该镜像支持的所有平台（如 amd64/linux、arm64/linux）。
• Index Digest：对这份索引 JSON 内容计算出的摘要。
• RepoDigests：在执行 docker images --digests 时看到的那个 Digest，通常就是这一层。

2. 第二层：Image Manifest（单平台清单）

当你（或 Docker 客户端）决定了具体架构（如 amd64）后，会根据 Index 里的指示，去拉取对应的 Manifest。

• 作用：这份文件才是“真正”的镜像描述文件，包含了镜像运行所需的两个核心信息：Config（配置） 和 Layers（层）。
• Manifest Digest：这份 Manifest JSON 本身的摘要。

3. 第三层：Config（镜像配置/Image ID）

在 Manifest 中，有一个 config 字段，指向一个 JSON 文件（包含环境变量、入口命令、架构信息等）。

• Image ID：在 Docker 的定义里，Image ID 本质上就是 Config 文件的 Digest。
• 作用：它是镜像内容的唯一身份证明。只要 Config 变了，Image ID 就一定会变。

---

核心概念对比表

为了直观，我们用一套示例 Hash 来串联：

名称	示例 Hash	含义	出现位置
Index Digest	sha256:abcd...	多架构索引的指纹	docker images --digests (RepoDigests)
Manifest Digest	sha256:efgh...	单平台清单的指纹	Index 文档的 manifests[].digest
Config Digest / Image ID	sha256:wxyz...	镜像配置的指纹	Manifest 的 config.digest；docker images 的 IMAGE ID

---

完整链路解析

当我们通过标签拉取镜像时，逻辑链路如下：

1. Tag（标签） 指向 Index（例如 latest 对应 abcd...）。
2. Index 包含多个 Manifest Digest（例如 amd64 对应 efgh...）。
3. Manifest 包含 Config Digest（例如 wxyz...）和多个 Layers。
4. Config Digest Image ID。

关键认知： 你在请求“标签”时，Registry 告诉你的是第一层 Index 的 Digest。 你在请求“单平台 Manifest”时，看到的是第二层 Manifest 的 Digest 和第三层 Config 的 Digest。 它们分属不同的 JSON 文档，所以 Digest 永远不会交叉出现。

---

给开发者的避坑指南

• 为什么本地 Image ID 和远端不一样？ 通常是因为你在 Registry 看到的是 Index Digest（RepoDigest），而本地 docker images 默认显示的是 Image ID（Config Digest）。
• 判断镜像内容是否变化： 最可靠的办法是对比 Image ID。如果 Image ID 没变，说明镜像的元数据和分层内容完全没有变动。
• 多架构推送： 当你推送一个支持多平台的镜像时，你会产生一个全新的 Index Digest，即使底层的各平台 Manifest 和 Config 并没有变化。

---

小结

• Index Digest 是“目录”的摘要。
• Manifest Digest 是“具体版本清单”的摘要。
• Image ID 是“配置与内容定义”的摘要。

理清这三层关系，就能在处理镜像同步、CI/CD 触发以及漏洞扫描时，准确地定位到你关心的那个“唯一标识”。