containerd 在快照已存在时跳过层内容下载的问题

概述

在容器镜像的分发与运行流程中，确保镜像内容的完整下载是后续所有操作（如运行容器、推送镜像）的基础。此知识页面记录了 containerd 中一个与 client.Pull 函数及其 WithPullUnpack 选项相关的缺陷。该缺陷会导致在特定条件下（快照已存在），镜像的层内容被跳过下载，进而引发镜像内容不完整和一系列后续操作失败。理解此问题的机理、影响范围及规避方法，对于维护使用 containerd 的容器平台可靠性和可观测性至关重要。

核心概念

要理解此问题，需要先明确几个核心概念：

client.Pull 与 WithPullUnpack: containerd 的客户端接口方法，用于拉取容器镜像。WithPullUnpack 是一个可选配置，指示 containerd 在拉取镜像后，立即对镜像进行解包（unpack），将其内容解压到本地快照存储中，以便容器可以直接使用。
快照（Snapshot）: containerd 用于存储镜像层解压后文件系统的抽象。每个镜像层会对应一个快照，这些快照通过父子关系组合成容器的最终文件系统视图。
层（Layer）与非层 Blob: OCI 镜像规范将内容分为“层”（构成文件系统的 tar 包）和“非层”（如配置、清单等元数据 Blob）。WithPullUnpack 的设计允许推迟层的下载，以支持远程快照器等场景。
问题根源: unpack 逻辑在检测到目标快照已存在时，会提前退出（early return），从而跳过后续实际获取层内容（fetch）的步骤。这导致即使拉取了元数据，但构成镜像根文件系统的层内容可能并未真正下载到本地存储。

实践

根据提供的 issue 描述，我们可以通过以下步骤复现和理解该问题：

问题复现步骤

首次拉取并运行容器：拉取一个镜像（如 busybox），然后基于该镜像启动一个容器。此时，镜像的元数据和层内容都已完整下载，且快照已创建。
```
nerdctl pull busybox
nerdctl run -d busybox
```
强制删除镜像：由于容器仍在运行（或已停止但未删除），镜像不能直接删除。使用 -f 参数强制删除镜像。此时，镜像的元数据（清单、配置等）从 containerd 的内容存储中被删除，但与已停止容器关联的快照仍然存在。
```
nerdctl rm -f busybox
```
再次拉取镜像：重新拉取同一个镜像。由于快照已经存在，unpack 过程检测到此状态后提前退出，导致本次拉取只获取了元数据，并未下载实际的层内容。
```
nerdctl pull busybox
```
此时观察输出，会发现层内容的下载量（total: 0.0 B）为零。
操作失败：尝试对这个“元数据已存在但层内容缺失”的镜像执行需要完整内容的操作（如推送到另一个仓库），将会失败，提示找不到对应的 Blob 摘要。
```
nerdctl tag busybox myregistry:5000/test
nerdctl push myregistry:5000/test # 失败：not found
```

影响与规避

此缺陷导致镜像处于一个“部分拉取”的不一致状态。虽然元数据（可寻址的清单和配置）存在，但层内容缺失，使得任何依赖于“已打包内容”（packed content）的操作都无法进行。

直接影响: 无法推送该镜像、无法基于其创建新的容器（如果原始快照被清理或损坏）、可能影响某些镜像分析工具。
规避方法: 一旦遇到此问题，需要清理掉不一致的快照或其引用。例如，删除关联的已停止容器，或者手动删除对应的快照，然后重新执行完整的拉取操作。

SRE 要点

与可靠性、可观测性的关联

可靠性影响: 此问题破坏了“镜像拉取”操作的幂等性预期。即，多次执行相同的 pull + unpack 操作，应得到一个功能完整的本地镜像。在特定条件下，这一预期被打破，导致系统处于错误状态，影响依赖该镜像的工作负载的可靠部署和迁移（如跨节点推送或重建）。
可观测性提示: SRE 团队需要监控以下指标或日志模式来发现此问题：
- 镜像拉取成功率/延迟: 表面上拉取成功（元数据获取完成），但后续操作失败。
- 内容存储完整性校验: 定期检查本地镜像层内容是否与元数据清单匹配。
- 特定错误日志: 关注类似 content digest sha256:...: not found 的错误，它可能指向内容缺失问题。

最佳实践与常见反模式

最佳实践:
1. 原子操作: 在管理镜像生命周期时，确保删除镜像前清理所有关联的容器和资源，避免残留快照导致状态不一致。
2. 状态检查: 在对镜像执行关键操作（如推送、分发）前，可先检查其层内容的完整性（例如通过 ctr content ls 等工具）。
3. 版本升级: 关注 containerd 项目的更新，此类行为缺陷通常会在后续版本中修复。
常见反模式:
1. 强制删除后盲目重拉: 在强制删除被使用的镜像后，直接重新拉取而未清理快照，极易触发此问题，导致获得一个“空壳”镜像。
2. 忽略中间状态: 在复杂的镜像分发流水线中，忽略对拉取后状态的校验，直接进行推送或部署。