镜像层 digest 校验的是该层解压后按 OCI 规范归一化（uid/gid→0、去 atime/mtime、权限标准化、路径字典序排序）生成的 tar 字节流的 sha256 哈希，非原始上下文或压缩 blob。
镜像层摘要（digest）到底校验什么
镜像层的 digest 校验的是该层 tar 包解压后、**按特定顺序归档为 OCI tar 的字节流**，不是原始构建上下文，也不是压缩后的 blob 内容。它本质是 sha256:xxx 对归一化 tar 流的哈希——这个归一化包括：统一 uid/gid 为 0、去除 atime/mtime、标准化文件权限（如目录必须是 0755）、按路径字典序排序条目。
常见错误现象：docker build 两次用相同 Dockerfile 和上下文，却得到不同 layer digest；或者你手动 tar -c 一层内容再推送到 registry，pull 后发现 digest 不匹配。
- 别用系统默认
tar命令直接打包——它保留 mtime、随机 inode 顺序、非零 uid，会导致 digest 失效 - OCI 规范要求使用
oci-image-tool或umoci等工具生成合规 tar 流；Docker 内部用的是github.com/containers/image/v5/pkg/compression中封装的归一化逻辑 - 如果你在 CI 中做 layer 复用比对，必须确保所有构建节点的
dockerd版本一致——旧版 Docker（
如何从本地镜像提取某层的准确 digest
别依赖 docker image inspect 输出里的 RootFS.Layers 数组——它只给 base64 编码的 digest 前缀（比如 sha256:abc...def），但没告诉你这是否是“内容寻址”意义上的最终 digest。真正可验证的 digest 存在镜像 manifest 中，且需通过 registry API 获取完整值。
实操建议：
- 先用
docker images --digests看镜像 tag 对应的 manifest digest（即sha256:xxx），这不是 layer digest，但它是入口 - 用
curl -H "Accept: application/vnd.docker.distribution.manifest.v2+json" http://<registry>/v2/<repo>/manifests/<digest></digest></repo></registry>拉取 manifest，从中读layers[n].digest - 注意：本地
docker save导出的 tar 包里，layer 文件名是随机前缀（如aaabbbccc/layer.tar），和 digest 无关；它的 digest 只在 manifest 或index.json里记录
push/pull 过程中 digest 验证失败的典型原因
最常见的不是网络丢包，而是 registry 层级的中间件篡改了 blob 内容——比如某些企业级 registry（如 Harbor 早期版本）启用了自动 virus scan，扫描器在 blob 上传途中重写了 tar 包头；或反向代理（如 Nginx）配置了 gzip on，导致客户端收到的响应体被压缩，而 digest 是按原始未压缩字节计算的。
排查要点：
- 检查 registry 日志里是否有
blob upload invalid digest或manifest verification failed错误 - 用
skopeo copy --debug替代docker push，它会打印每层上传前后计算的 digest，能直接定位哪一层不一致 - 如果用自建 registry，确认
storage.delete.enabled=true且未开启任何 content-transforming middleware（如透明加密、标签注入）
自己实现 layer 内容校验时最容易漏掉的归一化规则
你以为把文件 tar -c --format=gnu --owner=0 --group=0 --numeric-owner . | sha256sum 就完事了？漏了至少三点。
- whiteout 文件（如
.wh.file）必须被剔除或转换为 OCI 标准格式（.wh..wh.aufs→.wh.file），否则 tar 流结构不同 - 空目录必须显式写入 tar（typeflag =
5），不能靠父路径隐含；且权限必须是0755，哪怕源目录是0700 - 符号链接目标路径必须以
/开头（绝对路径），否则 Docker 会把它当相对路径处理，归一化后产生差异
这些细节在 github.com/opencontainers/image-spec/blob/main/layer.md 里写得极细，但没人真去逐条手写归一化逻辑——所以生产环境建议直接复用 containers/image 库的 archive.CompressStream，它已内置全部规则。
