Harbor磁盘空间清理指南：如何安全清理半年前的镜像

1 背景：为何需要定期清理Harbor镜像

在多项目开发环境中，随着持续集成/持续部署（CI/CD）流程的不断运行，Jenkins等工具会频繁地向Harbor镜像仓库推送新构建的镜像。久而久之，仓库中会积累大量历史镜像版本，导致虚拟机磁盘空间迅速耗尽。这些"僵尸镜像"不仅占用宝贵的存储资源，还可能增加安全风险和管理复杂度。

根据实践经验，一个中等规模的开发团队每周可能产生数十甚至上百个新镜像。如果没有有效的清理策略，Harbor存储占用呈指数级增长只是时间问题。更糟糕的是，单纯删除镜像并不立即释放物理空间——这是许多管理员常遇到的误区。

本文将详细介绍两种有效清理半年前镜像的方法：Harbor原生保留策略和API脚本清理方案，并解释最终释放磁盘空间的关键步骤。

2 清理原理：Harbor的两级删除机制

Harbor采用两级删除机制，理解这一点对有效管理存储空间至关重要：

1. 软删除（标记删除）：当我们通过界面或API删除镜像标签时，Harbor只是移除了镜像的元数据引用，并未真正删除底层的物理文件（blobs）。这就是为什么删除镜像后磁盘空间似乎没有变化。
2. 硬删除（物理删除）：需要通过垃圾回收（Garbage Collection, GC） 过程来实现。GC会清理那些不再被任何镜像引用的底层数据块，从而真正释放磁盘空间。

官方推荐
UI配置

高度定制化
API操作

关键步骤：垃圾回收 GC

安排维护窗口
GC期间仓库只读

执行垃圾回收命令

真正释放物理磁盘空间

方案二：通过 Harbor API 编写脚本

认证获取 Token

筛选创建时间早于半年的标签

调用 API 删除旧标签

方案一：通过 Harbor UI 配置保留策略

创建保留规则

设置保留最近180天镜像

设置定时执行或手动运行

Harbor 磁盘空间不足

选择清理方式

磁盘空间得到释放

3 方法一：使用Harbor原生保留策略（推荐UI操作）

Harbor自v2.4版本起提供了强大的保留策略(Retention Policy)功能，这是清理旧镜像的最简便方法。

3.1 配置步骤

1. 登录Harbor控制台，进入需要清理的项目