私有镜像仓库过期历史镜像清理与管理方法

清理私有镜像仓库中的过期历史镜像时，首先要区分本地 Docker 缓存与远程仓库存储：Harbor 在通过 Web 界面删除镜像后，还必须手动执行垃圾回收；通用 registry 则需要先开启 delete 功能，再通过 API 或 reg CLI 删除；在 CI/CD 流水线中，建议提前加入预防性策略，例如自动仅保留最近 5 个 tag。

如果想清理私有仓库中已经过期的历史镜像，首先要明确一个关键点：一类是“本地 Docker 引擎中的镜像缓存”，另一类才是“远程私有仓库（如 Harbor、Docker Registry、自建 registry）里真正占用存储空间的镜像数据”。很多人在实际操作时容易混淆这两者，但本地执行 docker rmi 删除的只是当前机器上的镜像文件，并不会影响私有仓库中的历史镜像。要真正释放仓库空间、清理无用镜像，必须依靠仓库本身提供的删除与回收机制。下面结合常见使用场景，系统说明几种常用且有效的清理方法：

确认哪些镜像属于“过期镜像”

判断镜像是否应该清理，不能只看 tag 名称，还要结合使用状态和生命周期综合分析：

• 时间维度：例如最后一次推送或更新时间已超过 30 天，并且长期没有拉取记录
• 标签策略：通常非 latest、非 prod- 前缀，且包含 dev/test/beta 等标识的标签，更适合作为清理对象
• 使用痕迹：可查看 Harbor 的「镜像拉取日志」或 registry 的访问日志，确认这些镜像是否长期未被业务调用

Harbor 仓库：优先通过 Web 界面删除并执行垃圾回收

这种方式更适合中小规模环境，以及需要人工确认和审核的镜像清理场景：

• 登录 Harbor → 进入目标项目 → 打开「镜像」页面，勾选需要删除的镜像（支持批量选择和按标签筛选）
• 点击删除并确认后，镜像通常只是完成“逻辑删除”，对应的 manifest 和 blob 依然会继续占用磁盘空间
• 因此必须手动触发「垃圾回收」（GC）：顶部菜单 →「系统管理」→「垃圾回收」→「立即执行」
• 虽然 GC 默认每 24 小时会自动运行一次，但清理存在延迟；如果刚批量删除完历史镜像，建议立即手动执行一次

通用 registry（v2 API）：使用 curl 或 reg CLI 批量自动清理

这一方案适用于没有 Web 管理界面的自建 registry，或者需要通过脚本自动批量删除镜像的场景：

• 首先确认 registry 配置已开启删除能力：delete: enabled: true
• 获取 token：curl -u "user:pass" -X POST https://reg.example.com/service/token?service=harbor-registry
• 查询 digest：curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.docker.distribution.manifest.v2+json" https://reg.example.com/v2/myapp/manifests/v1.2
• 删除 manifest：curl -X DELETE -H "Authorization: Bearer $TOKEN" https://reg.example.com/v2/myapp/manifests/sha256:abc...
• 实际使用中更推荐借助 reg 工具简化操作流程：reg delete reg.example.com/myapp:v1.2 --insecure（添加 --insecure 可跳过证书校验）

在 CI/CD 流水线中做预防性镜像清理

与其在仓库空间吃紧后再处理，不如在镜像构建和发布阶段就提前控制冗余：

• 在推送前增加保留策略：例如只保留最近 5 个 tag，较旧的标签自动删除（可通过 Harbor API 先查询 tags 列表再执行清理）
• 如果使用 Git 分支名作为 tag，建议制定明确规则，例如 feature-xxx 类型镜像在推送 7 天后自动清理
• 在 Jenkins、GitLab CI 等流水线中集成镜像清理脚本，构建成功后自动执行“保留 prod 标签、删除其他标签”的策略
• 结合镜像安全扫描结果使用：对于 Harbor 检测出高危 CVE 的旧版本镜像，可直接标记为待清理对象