Docker 拉取镜像报错 unknown blob 完整排查方案

报错含义

error pulling image configuration: download failed after attempts=1: unknown blob

直译：拉取镜像配置失败，重试 1 次后终止，镜像缺失必要层文件（blob 镜像分片不存在 / 找不到）

本质：镜像仓库里该标签对应的镜像分层数据损坏、缺失、被删除，或是网络 / 镜像源 / 本地存储异常导致无法获取分片。

一、最快优先解决（按顺序试）

1. 更换镜像标签（最常见根源）

很多镜像 latest 标签会被官方覆盖更新，旧镜像层直接删除，就会报 unknown blob。

• 不要固定用 :latest，指定具体版本号拉取

bash

运行

# 错误
docker pull nginx
# 正确
docker pull nginx:1.27.0

2. 清理本地损坏镜像缓存

本地残留残缺镜像会一直锁死拉取流程：

bash

运行

# 删除同名残留镜像
docker rmi 镜像名:标签
# 清理所有无用镜像、悬空层
docker image prune -a

3. 切换国内镜像加速器（网络源问题高发）

Docker 配置镜像源

编辑 /etc/docker/daemon.json

json

{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com",
    "https://mirror.baidubce.com"
  ]
}

重启 Docker

bash

运行

systemctl daemon-reload
systemctl restart docker

二、进阶场景排查

场景 1：私有仓库（Harbor / 自建 Registry）报该错

1. 镜像推送中途中断，仓库内镜像不完整，重新 push 镜像
2. 仓库磁盘满了，无法存储 blob 分片，清理仓库存储空间
3. Harbor 垃圾清理任务误删了镜像依赖的 blob，关闭自动 GC 或重新上传镜像

场景 2：K8s containerd 拉取镜像报错

containerd 对应配置镜像加速器路径：/etc/containerd/config.toml

修改 [plugins."io.containerd.grpc.v1.cri".registry.mirrors] 节点添加镜像源，重启 containerd。

场景 3：磁盘 inode / 空间耗尽

bash

运行

# 查看磁盘剩余空间
df -h
# 查看inode占用
df -i

磁盘满会导致镜像写入分片失败，直接报 blob 不存在，扩容磁盘或清理大文件。

三、终极兜底方案

1. 在能正常拉取该镜像的机器 docker save 打包镜像，传输到故障机器 docker load 导入
2. 去镜像官网确认该 Tag 是否已下架归档，换可用版本

极简总结

90% 情况 = latest 标签镜像被官方删层 → 指定固定版本号拉取即可；