harbor镜像清理需软删除+垃圾回收（gc）两步才能释放磁盘空间；推荐使用v2.4+原生保留策略（ui配置），或api定制化清理，最后必须停机执行gc。
Linux 系统部署 Harbor 后，仅靠手动删镜像无法真正释放磁盘空间。自动清理策略必须配合软删除 + 垃圾回收（GC）两步才能生效，否则删了也白删。
启用 Harbor 原生保留策略（推荐 UI 配置）
Harbor v2.4+ 内置的 Retention Policy 是最稳妥、免写脚本的方案，适合大多数生产环境：
- 登录 Harbor Web 控制台，进入目标项目 → 点击“策略”选项卡 → “添加规则”
- 设置规则名称（如“半年镜像清理”），匹配仓库建议用 ** 覆盖全部仓库
- 保留策略选“保留最近多少天被推送过的”，填 180（对应半年）
- 勾选“删除未打标签的镜像”，避免残留 untaged blobs 占用空间
- 执行频率设为每周一次（UTC 时间），例如 0 0 * * 6 表示每周六 UTC 0 点运行（国内为周六上午 8 点）
- 配置完先点“模拟运行”，确认将要清理的镜像范围无误再启用
通过 API 实现定制化批量清理
当需要按标签前缀、创建时间或项目维度精细控制时，API 方式更灵活：
- 先用管理员账号调用 /api/v2.0/projects/{project_id}/repositories 获取仓库列表
- 对每个仓库调用 /api/v2.0/projects/{project_id}/repositories/{repo_name}/artifacts，筛选 push_time （即半年前）的镜像
- 对符合条件的 artifact，逐个调用 DELETE /api/v2.0/projects/{project_id}/repositories/{repo_name}/artifacts/{digest}
- 注意：每次请求需携带 Bearer Token，Token 从 /api/v2.0/users/current/permissions 或登录后 Cookie 提取
- 建议加 sleep 间隔（如 0.5 秒），避免触发 Harbor 的 API 限流
执行垃圾回收释放物理空间
无论用 UI 还是 API 删除，都只是标记删除（soft delete）。必须运行 GC 才能清空底层 blobs：
- 停止 Harbor 服务：docker-compose -f docker-compose.yml stop
- 预览 GC 影响（安全第一）：docker run --rm -it --volumes-from registry goharbor/registry-photon:v2.11.1 garbage-collect --dry-run /etc/registry/config.yml
- 确认无误后执行真实 GC：docker run --rm -it --volumes-from registry goharbor/registry-photon:v2.11.1 garbage-collect /etc/registry/config.yml
- 重启服务：docker-compose -f docker-compose.yml start
- 验证效果：du -sh /data/registry/docker/registry/v2/blobs 对比前后大小
关键注意事项与避坑点
自动清理容易因配置疏漏导致误删或无效，这几个细节必须检查：
- 保留策略默认按 推送时间（push_time） 判断，不是创建时间或拉取时间
- GC 过程中 Harbor 必须处于停机状态，否则可能损坏正在上传的镜像层
- 若使用 HTTPS，客户端访问 API 需提前信任 Harbor 的 CA 证书，否则返回 401 或连接拒绝
- Harbor 数据目录（如 /data）所在分区剩余空间应始终 ≥20%，GC 临时文件可能占用额外空间
- 策略启用后不会立即清理历史数据，只对后续满足条件的镜像生效；已有老镜像需手动触发“立即执行”或先跑一遍 API 清理
