Docker 镜像标签为什么不能保证部署可复现

发布记录里写着 app:1.4，下一次部署却出现了不同的依赖版本。排查这类问题时，需要先确认这个名字当时指向什么内容。镜像标签方便人识别版本，但要准确定位发布产物，还需要镜像摘要、目标平台和构建输入。

标签是名字，digest 标识内容

Docker 镜像标签可以被重新指向另一份镜像。latest 会变，1.4 这样的版本标签也可以变，具体取决于发布者及仓库策略。[1] 仅记录标签，无法确认两次拉取解析到的内容是否相同。

使用仓库名加摘要的形式，例如“仓库/镜像@sha256:摘要值”，可以固定拉取的镜像版本。[2] 摘要值应取自实际发布或查询结果。发布记录可以同时保存便于阅读的标签和用于精确定位的摘要，部署配置使用经过核对的摘要引用。

digest 还需要结合目标平台理解

多平台镜像可以包含 linux/amd64、linux/arm64 等不同版本。Docker 拉取时会根据平台选择相应版本；同一个多平台引用，在不同架构机器上可能选中不同的镜像清单。[3]

OCI 镜像索引是更高一层的对象，它指向具体镜像清单，并可通过操作系统、架构及架构变体描述平台要求。[4] 因而，固定索引的 digest，是固定这一组清单的内容，并不意味着每台机器都使用同一套二进制文件。

发布前，可以用 docker buildx imagetools inspect 查询仓库中的镜像，查看顶层摘要、清单列表和平台字段。[5] 发布记录应说明摘要对应索引还是单平台清单，同时保存目标平台和选中的子清单摘要。混合架构部署需要分别验证各个平台的产物，不能只用一种架构的结果覆盖其他架构。

固定镜像与重新构建是两件事

按 digest 部署解决的是“使用哪一份已有产物”。重新执行构建时，还会读取 Dockerfile、基础镜像、构建上下文以及构建步骤访问的依赖来源。即使源码提交没有变化，未固定的基础镜像标签或在线依赖也可能带来不同内容。

Dockerfile 的 FROM 可以固定到基础镜像摘要。[1][2] 但这只固定了基础镜像；后续下载脚本、安装软件包或复制本地文件的步骤，仍需要检查各自输入。构建上下文是构建过程能够访问的文件集合，同一提交之外的本地文件也可能进入其中。[6]

构建记录可以保存源码提交、Dockerfile、上下文范围、依赖锁文件、基础镜像摘要、构建参数、工具链版本和目标平台。对在线下载的依赖，保留版本及内容校验信息。记录输入便于追查差异，是否能重新得到相同摘要，仍需要实际重建后比较。

缓存选项也有各自的用途。--pull 用于检查并拉取更新的基础镜像，--no-cache 用于禁用构建缓存；后者不会自动拉取新的基础镜像。[1] 这两个选项都不负责固定在线依赖，重新执行安装步骤时，仍可能拿到上游变化后的内容。

把摘要纳入发布与回滚记录

一次发布可以按“构建并推送、查询摘要和平台、验证产物、更新部署引用”的顺序进行。验证后继续使用同一摘要，避免再次按可变标签解析。回滚记录保留上一份摘要及对应部署配置，环境变量、挂载文件等运行配置也一起记录，方便还原当时的运行条件。

固定摘要后，上游更新标签不会自动替换已固定的镜像，安全修复也需要通过更新摘要引入。[2] 更新时重新构建、验证并保存新的发布记录，让每次变化都有明确的产物对应关系。

参考资料
[1] Docker：Building best practices
https://docs.docker.com/build/building/best-practices/
[2] Docker：docker image pull
https://docs.docker.com/reference/cli/docker/image/pull/
[3] Docker：Multi-platform builds
https://docs.docker.com/build/building/multi-platform/
[4] OCI：Image Index Specification
https://github.com/opencontainers/image-spec/blob/main/image-index.md
[5] Docker：docker buildx imagetools inspect
https://docs.docker.com/reference/cli/docker/buildx/imagetools/inspect/
[6] Docker：Build context
https://docs.docker.com/build/concepts/context/