K8s节点从私有Docker Registry拉取镜像报文件系统层sha256校验失败

核心原因 #

该报错是指节点拉取到的镜像层哈希值，和私有Registry中存储的对应镜像层标准哈希值不一致，触发了Docker/containerd的完整性校验拦截。

分步排查解决 #

• 步骤1：清理节点本地损坏的镜像缓存
  首先停止节点的容器运行时，清理残留的损坏镜像数据，操作如下：
  如果节点使用Docker作为运行时：

  systemctl stop docker
  rm -rf /var/lib/docker/*
  systemctl start docker
  

  如果节点使用containerd作为运行时：

  systemctl stop containerd
  rm -rf /var/lib/containerd/*
  systemctl start containerd
  

  操作完成后手动执行docker pull/crictl pull命令拉取镜像，验证是否恢复正常。
• 步骤2：排查节点侧异常
  如果清理缓存后仍然报错，优先排查该节点的本地环境问题：
  • 检查磁盘健康状态：执行dmesg | grep -i error排查是否有磁盘坏道、IO写入失败相关报错，磁盘写入异常会导致镜像层写入本地时损坏
  • 排查网络传输问题：确认节点和私有Registry之间是否存在代理、WAF、流量审计设备，这类设备可能会篡改二进制传输内容，或在大文件传输时丢包导致镜像层不完整。可以在Registry上放置一个测试大文件，节点下载后校验哈希值，确认传输链路完整性
  • 核对运行时版本：对比该节点和其他正常拉取镜像节点的Docker/containerd版本，部分旧版本运行时存在镜像层校验的已知bug，升级到和正常节点一致的稳定版本即可修复
• 步骤3：排查Registry侧异常
  如果所有节点拉取该镜像都返回同样的校验报错，说明Registry中存储的该镜像本身已损坏，直接重新构建镜像（构建时不要加--cache-from参数避免复用损坏的缓存层），重新推送到私有Registry即可。

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