执行docker compose up时报refusing to create a tag with a digest reference错误

错误详情 #

完整报错信息如下：

> exporting to image:
------
failed to solve: rpc error: code = Unknown desc = refusing to create a tag with a digest reference

触发原因 #

该错误由Docker BuildKit组件的标签校验逻辑触发：Docker规则禁止给已经携带摘要引用（格式为@sha256:xxx）的镜像创建自定义标签，当检测到标签配置中包含摘要后缀时就会抛出该异常，常见触发场景如下：

• docker-compose.yml配置文件的image字段同时填写了标签和镜像摘要，格式类似image: my-service:v1@sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824，build完成后Docker尝试给生成的镜像打这个带摘要的非法标签
• 本地已存在带非法标签的同名镜像，compose执行up操作时读取到该标签格式不符合规则
• 20.10版本之前的Docker存在BuildKit已知bug，使用构建缓存时会误将源镜像的摘要写入到新镜像的标签配置中

修复方案 #

• 检查docker-compose.yml中所有服务的image配置，移除@sha256:及之后的摘要内容，仅保留镜像名和自定义标签即可
• 清理本地无效镜像，执行命令docker image prune -f删除无用镜像后，重新执行docker compose build和docker compose up
• 升级Docker到20.10及以上稳定版本，修复BuildKit的兼容问题
• 临时绕过校验：执行compose命令前先设置环境变量export DOCKER_BUILDKIT=0，关闭BuildKit后即可正常执行操作

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