Docker ADD命令--checksum参数无法使用SHA512算法的问题咨询

更新说明 #

• 更新1：最初误以为是Docker Bug，提交相关报告后确认并非Bug，根源是官方文档描述错误
• 更新2：问题已明确，详情见下文说明

问题场景 #

在Dockerfile中使用ADD命令下载tar包到容器内，尝试通过--checksum参数指定sha512哈希值做文件校验，命令示例如下：

ADD --checksum=sha512:theverylongsha512hashgoeshereblahblahblah https://url.for/the_tarball/the_tarball-1.33.7.tar.gz the_tarball-1.33.7.tar.gz

按照官方文档描述该用法应有效，但执行docker build时触发以下校验不匹配错误：

> [16/29] ADD --checksum=sha512:3d425c5a102d441da33030949ba5ec22e388ed0529c298a1984d62486d4924806949708b834229206ee5a36ba30f6de6d09989019e5790a8b665539f9489efd5     https://github.com/ArtifexSoftware/ghostpdl-downloads/releases/download/gs10040/ghostscript-10.04.0.tar.gz ghostscript-10.04.0.tar.gz:            
------                                                                                                                                                      
ERROR: failed to solve: digest mismatch sha256:c764dfbb7b13fc71a7a05c634e014f9bb1fb83b899fe39efc0b6c3522a9998b1: sha512:3d425c5a102d441da33030949ba5ec22e388ed0529c298a1984d62486d4924806949708b834229206ee5a36ba30f6de6d09989019e5790a8b665539f9489efd5     

从错误信息可看出，Docker实际计算的是文件的sha256哈希值，却与指定的sha512值对比，导致校验失败。手动将参数替换为文件的sha256哈希值后，校验成功通过。

部分依赖软件包仅提供sha512哈希值，虽可手动计算sha256值，但希望确认是否存在遗漏的配置步骤。

使用环境 #

• Docker版本：Docker version 26.0.0, build 2ae903e
• 操作系统：MacOS 12.7，Docker Desktop从4.29更新至4.35后问题仍未解决

结论 #

经确认，此问题并非Docker Bug，而是官方文档描述有误：ADD命令的--checksum参数仅支持sha256算法，不支持sha512。因此只能使用sha256哈希值进行校验，若仅能获取sha512值，需手动转换为sha256值后再使用。

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