如何利用Docker镜像仓库API实现过期镜像版本的自动化清除？

本文共计752个文字，预计阅读时间需要4分钟。

直接调用Docker Registry API清理镜像，不能仅通过发送DELETE请求就完事——它不会自动识别过期的镜像。必须先明确哪些镜像应被删除，再按规范流程执行删除与回收。核心是查得准、删得稳、收得净。

先确认仓库支持删除功能

Registry 默认禁用删除接口，需显式开启：

• 检查配置文件中是否设置 delete.enabled: true（如 config.yml）
• Docker Compose 部署时，在 registry 服务 environment 下添加：
  REGISTRY_STORAGE_DELETE_ENABLED=true
• 重启 registry 容器后，用 curl -I http://your-registry/v2/ 确认返回状态为 200；再试 curl -X DELETE http://your-registry/v2/myapp/manifests/sha256:xxx，若返回 405 则说明未启用

按标签规则批量定位待删镜像

Registry API 不提供按时间或数量过滤的原生接口，需外部工具辅助查询和筛选：

• 获取某仓库所有标签：
  curl "http://your-registry/v2/myapp/tags/list" | jq -r '.tags[]'
• 对每个 tag，请求 manifest 获取 digest 和时间信息：
  curl -H "Accept: application/vnd.docker.distribution.manifest.v2+json" "http://your-registry/v2/myapp/manifests/$tag"
• 结合策略判断是否过期：例如保留 v[0-9]+\.[0-9]+\.[0-9]+ 标签中最近 3 个，其余 dev-、pr- 标签一律 72 小时无拉取即标记

安全执行删除 + 触发垃圾回收

删除分两步，缺一不可：

• 第一步：调 DELETE API 删除 manifest
  使用 digest（不是 tag）发送请求：
  curl -X DELETE "http://your-registry/v2/myapp/manifests/sha256:abc123..."
  注意：必须带 Accept 头，且 registry 要在只读关闭状态下操作更稳妥
• 第二步：停 registry 后执行 GC
  运行：
  docker exec registry /bin/registry garbage-collect /etc/docker/registry/config.yml --dry-run=false
  GC 只清理已标记为“可删”但 blob 仍残留的层，不扫描磁盘，也不替代 DELETE

推荐用 Harbor 或 reg 工具简化流程

自写脚本易出错，优先复用成熟能力：

• Harbor 用户：直接在 UI 配置 Retention Policy，支持按标签正则、推送时间、拉取时间、是否被项目引用等组合条件，策略自动归档或删除，带预览和审计日志
• 轻量 Registry：用 reg 工具（如 reg delete your-registry/myapp:old-tag --insecure），它会自动解析 digest 并调用 DELETE，比裸 curl 更可靠
• 所有自动化任务必须加“预览模式”：先输出将删的镜像名、digest、大小、最后拉取时间，人工确认后再执行真实删除