4. 镜像仓库推送/拉取故障：认证失败、网络超时、镜像层损坏、存储配额不足、镜像标签管理混乱

镜像仓库（Registry）是容器化交付的核心。推送与拉取操作一旦失败，整条流水线即告中断。本章聚焦五大高频故障模式：认证失败、网络超时、镜像层损坏、存储配额不足、标签管理混乱，逐一给出根因定位、恢复步骤与预防策略。

4.1 故障全景与诊断路径

以下表格汇总了五种故障的典型表现、根因与快速诊断命令，便于流水线自动捕获异常后快速分类。

故障类型	典型错误日志片段	根因	快速诊断命令
认证失败	denied: requested access to the resource is denied	凭证过期、权限不足、 无效	docker login <registry> --username <user> --password-stdin
网络超时	net/http: TLS handshake timeout / i/o timeout	DNS 解析、防火墙、代理、带宽瓶颈	curl -v https://<registry>/v2/
镜像层损坏	blob unknown to registry / failed to copy: unexpected EOF	上传中断、磁盘故障、并发写入冲突	docker manifest inspect <image>:<tag>
存储配额不足	insufficient storage / no space left on device	Registry 后端存储满、命名空间配额耗尽	df -h（节点级） / Registry API 查询配额
标签管理混乱	manifest for ... not found / 标签覆盖导致版本丢失	标签覆盖、删除策略缺失、CI 并发写标签	docker image ls --digests + 审计日志

4.2 认证失败：凭证生命周期与权限模型

认证失败是流水线中最常见的 Registry 故障，通常由以下原因引起：

• 凭证过期： 或密码有有效期（如 Harbor 的 Robot Account 默认 30 天）。
• 权限不足：Service Account 只具备 pull 权限，但流水线尝试 push。
• 多 Registry 混淆：CI 环境变量中配置了错误的 Registry 地址或凭证。

4.2.1 恢复步骤

1. 验证当前凭证：在流水线节点手动执行 docker login 或使用 Registry API 测试。
2. 检查凭证有效期：对于 Robot Account，通过 Registry 管理界面或 API 查看 expires_at 字段。
3. 刷新凭证：在 CI 系统的 Secret Store 中更新密码/，并触发一次验证流水线。
4. 权限审计：确认 Service Account 被授予了正确的项目/命名空间角色（如 developer 或 maintainer）。

4.3 网络超时：分层诊断与链路优化

网络超时在跨地域推送大镜像（>1GB）时尤为突出。诊断需从客户端到 Registry 端逐层排查。

4.3.1 恢复与优化策略

• 客户端调优：设置 --max-concurrent-uploads=3 降低并发；启用 --max-download-attempts=5 自动重试。
• Registry 端：启用 Pull-Through Cache（如 Harbor Proxy Cache）或 Registry Mirror，减少跨公网传输。
• 流水线重试：采用指数退避重试策略（初始 1s，最大 30s，重试 3 次）。

4.4 镜像层损坏：完整性校验与恢复

镜像层损坏通常表现为推送成功后拉取时 blob unknown 或 manifest invalid。根因包括：上传过程中网络闪断、Registry 后端磁盘故障、并发写入同一标签导致层引用错乱。

4.4.1 检测与恢复流程

1. 验证 Manifest：使用 docker manifest inspect <image>:<tag> 检查层列表是否完整。
2. 检查层 Digest：对比本地 docker image inspect 输出的 RepoDigests 与 Registry 返回的 digest 是否一致。
3. 重新推送：删除损坏标签（docker image rm + Registry API 删除），从构建节点重新构建并推送。
4. 启用完整性校验：在 Registry 配置中开启 validation: disabled: false（Harbor）或使用 content-trust 签名。

4.5 存储配额不足：容量规划与自动清理

存储配额不足分为 Registry 后端存储满（磁盘/对象存储）和 项目/命名空间配额耗尽（如 Harbor 项目配额）。

场景	表现	恢复操作	长期策略
后端存储满	推送失败，Registry 日志报 no space left	扩容存储卷；清理未引用的 Blob（GC）	配置存储配额告警（>80% 触发）
项目配额耗尽	API 返回 quota exceeded	删除过期镜像；临时提高配额	实施镜像保留策略（按时间/版本数）

4.5.1 自动清理策略示例

# Harbor 自动清理策略（通过 API 或 Webhook 触发）
# 保留最近 30 天的镜像，且每个仓库最多保留 10 个标签
{
  "rules": [
    {
      "enabled": true,
      "scope": "repository",
      "action": "retain",
      "params": {
        "num_of_tags": 10,
        "older_than": "30d"
      }
    }
  ]
}

4.6 镜像标签管理混乱：不可变标签与审计

标签管理混乱是“软故障”——流水线不直接报错，但会导致部署拉取到错误版本、回滚困难、镜像泄露。典型场景：

• 标签覆盖：CI 并发推送同一 latest 标签，导致不同构建的层混合。
• 标签丢失：手动删除标签后，底层 Blob 未被 GC 回收，但 Manifest 已不可寻。
• 版本混乱：使用 v1.0、v1.0.1、v1.0.1-fix 等无规范标签。

4.6.1 不可变标签（Immutable Tag）实施

在 Registry 端启用不可变标签，防止已推送的标签被覆盖。以 Harbor 为例：

# Harbor 项目配置 - 不可变标签
# 路径：Projects -> <project> -> Configuration -> Tag Immutability
# 规则：匹配所有标签（**）或指定前缀（release-*）
# 效果：任何试图覆盖已有标签的推送都会被拒绝，返回 405 Method Not Allowed

4.6.2 标签命名规范与审计

标签类型	示例	可变性	用途
语义化版本	v1.2.3	不可变	正式发布版本
Git Commit SHA	sha-a1b2c3d4	不可变	唯一标识每次构建
分支+构建号	main-1234	可变（可覆盖）	开发/测试环境自动部署
Latest	latest	可变	仅用于本地开发，禁止用于生产

4.7 综合故障恢复流程（SVG）

以下流程图展示了从检测到恢复的完整闭环，适用于流水线自动集成。

4.8 流水线集成检查清单

将以下检查项作为流水线“Registry 健康门控”的一部分，在每次推送/拉取前执行：

• 凭证有效性：使用 docker login 或 Registry API 验证，失败则触发凭证刷新流程。
• 网络连通性：对 Registry 端点执行 curl -s -o /dev/null -w "%{http_code}"，超时则切换 Mirror。
• 存储配额：通过 Registry API 查询当前使用量，超过 80% 触发清理任务。
• 标签合规：检查推送标签是否符合 v[0-9]+.[0-9]+.[0-9]+ 或 sha-[a-f0-9]{7,40} 规范。
• 推送后验证：推送完成后立即拉取并校验 Digest，确保层完整。