Docker镜像推送遇Unknown blob error的排查求助

问题场景 #

我有一套构建流程，会构建多个镜像并推送到内部Jfrog实例的发布仓库，但其中一个镜像的推送突然持续失败。报错信息如下：

make pushImage
docker push some-repo/path/to/image:tag
The push refers to a repository [some-repo]
[image id 1]: Preparing
[image id 2]: Preparing
[image id 3]: Preparing
[image id 4]: Preparing
[image id 2]: Waiting
[image id 3]: Waiting
[image id 4]: Waiting
unknown blob
make: *** [pushImage] Error 1 

已知该错误一般是目标仓库缺失某个镜像层，但存在两个疑问：

1. 如何确定具体缺失的镜像层？
2. 如何及在哪里补充缺失的镜像层？

已尝试以下无效方法：

• 开启Docker守护进程调试模式，未获取到有效日志
• 禁用缓存重新构建镜像
• 使用docker inspect查看镜像层sha摘要，试图匹配镜像ID定位缺失层，但二者不匹配（已了解原因）
• 将镜像从沙箱仓库手动复制到发布仓库补充缺失层
• 删除容器注册表中带问题标签的镜像后重新推送

一、定位缺失的镜像层 #

方法1：导出镜像解析层列表后逐个校验 #

1. 导出镜像到本地文件：

   docker save some-repo/path/to/image:tag -o image.tar
   

2. 解压并查看镜像包含的所有层：

   tar -xf image.tar
   cat manifest.json | jq '.[] | .Layers'
   

   输出结果会列出所有层的文件名（格式为sha256:<哈希值>/layer.tar），提取其中的哈希值。
3. 用Jfrog API逐个检查层是否存在于目标仓库：

   curl -u <用户名>:<密码> https://<你的Jfrog地址>/artifactory/api/storage/<目标仓库名>/v2/path/to/image/blobs/sha256:<层哈希值>
   

   返回状态码为404的就是缺失的层。

方法2：用Skopeo工具获取精准错误 #

Skopeo工具推送镜像时会输出更详细的层推送日志，直接定位缺失的blob：

skopeo copy docker-daemon:some-repo/path/to/image:tag docker://<你的Jfrog地址>/path/to/image:tag --dest-creds <用户名>:<密码>

执行后会明确提示哪个哈希值的层推送失败。

二、补充缺失的镜像层 #

方法1：用Skopeo重新推送镜像 #

Skopeo会自动检测目标仓库缺失的层并单独推送，无需手动处理单个层，直接执行上述Skopeo的复制命令即可。

方法2：从内部其他仓库同步缺失层 #

如果沙箱仓库或其他内部仓库存在该缺失层，通过Jfrog控制台操作：

1. 登录Jfrog控制台，进入目标发布仓库的「复制」设置页面
2. 添加复制规则，指定源仓库（如沙箱仓库），并设置路径过滤为blobs/sha256:<缺失层哈希值>
3. 触发手动复制任务，等待复制完成后重新推送镜像

方法3：彻底重新构建镜像 #

确保构建环境无残留缓存，重新构建后推送：

docker build --no-cache -t some-repo/path/to/image:tag <构建上下文路径>
docker push some-repo/path/to/image:tag

构建过程中避免中断，确保所有层都完整生成。

方法4：检查Jfrog仓库配置与权限 #

• 确认推送账号对目标发布仓库拥有写入、创建资源的完整权限
• 检查Jfrog是否近期执行过垃圾回收，如果是，可能误删了未被引用的层，可尝试从垃圾回收恢复（若开启了恢复功能），或重新推送对应层

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