Harbor镜像清理策略与实操指南

1. 为什么Harbor需要定期清理镜像

Harbor作为企业级容器镜像仓库，随着业务发展会积累大量历史镜像。这些镜像会占用大量磁盘空间，导致以下典型问题：

• 存储空间告急：当磁盘使用率达到85%以上时，Harbor会出现性能下降甚至服务不可用的情况。我遇到过某生产环境因未及时清理，导致500GB存储耗尽后整个CI/CD流程中断的案例。

• 运维成本增加：存储扩容只是临时解决方案，长期看会带来硬件成本上升。更严重的是，大容量磁盘的备份和恢复时间会呈指数级增长。

• 安全隐患：旧版本镜像可能包含已知漏洞，保留过多历史版本会增加安全风险。去年某金融客户就因未清理包含Log4j漏洞的旧镜像导致安全事件。

镜像的生命周期通常分为三个阶段：

1. 活跃期（0-3个月）：频繁被拉取用于开发和测试
2. 观察期（3-6个月）：偶尔被拉取用于特殊场景
3. 归档期（6个月+）：几乎不再使用

重要提示：清理前必须确保有完整的备份策略。我曾见过因直接删除导致生产回滚失败的惨痛教训。

2. 清理前的准备工作

2.1 空间占用分析

使用Harbor自带的存储分析功能：

bash复制# 登录Harbor主机
df -h /data  # 查看存储挂载点使用情况
du -sh /data/registry/docker/registry/v2  # 查看镜像实际占用空间

更详细的镜像分析建议使用第三方工具：

• Harbor Cleaner：可视化展示各项目/镜像大小
• Trivy：可扫描镜像漏洞辅助决策

2.2 制定清理策略

根据我的经验，推荐以下分层策略：

2.3 权限检查

清理操作需要admin权限。若遇到"admin没有push权限"错误（近期常见问题），需检查：

1. 用户角色是否为系统管理员
2. 项目是否设置了自定义权限策略
3. 是否启用了LDAP/AD集成认证

修复命令示例：

bash复制# 授予admin项目权限
harbor-cli project add-member --project myproject --username admin --role maintainer

3. 安全清理镜像的实操步骤

3.1 基于时间筛选镜像

使用Harbor API筛选6个月前的镜像：

bash复制# 获取所有镜像列表
curl -u "admin:Harbor12345" -X GET "https://harbor.example.com/api/v2.0/projects/myproject/repositories" -H "accept: application/json"

# 筛选创建时间超过180天的镜像
jq '.[] | select(.created < (now - 15552000)|todate)' repositories.json

3.2 验证镜像可删除性

删除前必须确认：

1. 是否有容器正在使用该镜像（特别是生产环境）
2. 是否被其他镜像作为基础层依赖
3. 是否在最近的部署记录中被引用

检查命令示例：

bash复制# 检查镜像被引用情况
harbor-cli artifact list --project myproject --repository myapp --tag 1.0.0 --detail

3.3 执行删除操作

推荐使用Harbor的垃圾回收机制而非直接删除文件：

1. 先在UI中删除不需要的镜像标签
2. 运行垃圾回收释放空间：

bash复制docker-compose exec -T harbor-registry registry garbage-collect /etc/registry/config.yml

特别注意：垃圾回收期间Harbor会不可用，建议在维护窗口操作。某次我在业务高峰执行导致服务中断30分钟。

4. 清理后的验证与监控

4.1 空间释放验证

执行后检查：

bash复制# 查看存储空间变化
df -h /data
# 检查registry目录大小变化
du -sh /data/registry/docker/registry/v2

正常情况应有20%-40%的空间释放。如果变化不明显，可能是：

• 存在大文件未被清理（如日志、缓存）
• 镜像层存在共享依赖未被释放

4.2 建立预防机制

建议配置：

1. 定期清理任务（Crontab示例）：

bash复制0 3 * * 6 /usr/local/bin/harbor-cleaner --older-than 180d --exclude-tags "prod-*"

2. 监控告警规则（Prometheus示例）：

yaml复制- alert: HarborStorageCritical
  expr: harbor_storage_usage_percentage > 80
  for: 1h
  labels:
    severity: critical
  annotations:
    summary: "Harbor storage usage is {{ $value }}%"

5. 高级技巧与避坑指南

5.1 保留特定镜像的实用方法

有时需要保留某些旧镜像用于审计或法律合规，建议：

• 打上特殊标签（如keep-forever）
• 移动到专用保留项目
• 导出为压缩包存档

导出示例：

bash复制docker pull harbor.example.com/myproject/myapp:1.0.0
docker save -o myapp-1.0.0.tar harbor.example.com/myproject/myapp:1.0.0

5.2 常见问题排查

问题1：删除后空间未释放

• 原因：Linux文件系统特性，被删除文件仍被进程占用
• 解决：重启registry容器或主机

问题2：垃圾回收失败

• 典型错误："unsupported status code 409"
• 解决方法：
  1. 停止所有到Harbor的流量
  2. 执行docker-compose stop registry
  3. 手动运行垃圾回收
  4. 重启服务

问题3：误删关键镜像

• 恢复步骤：
  1. 从备份恢复（必须提前测试备份可用性）
  2. 或从其他环境重新推送

5.3 性能优化建议

对于大型Harbor实例（10TB+）：

• 启用分片存储（参考Registry的storage配置）
• 使用S3等对象存储替代本地磁盘
• 考虑部署Harbor的分布式架构

配置示例（registry.yml）：

yaml复制storage:
  filesystem:
    rootdirectory: /storage
    maxthreads: 100
  maintenance:
    uploadpurging:
      enabled: true
      age: 168h
      interval: 24h
      dryrun: false

这套方案在某电商平台实施后，使Harbor存储成本降低了67%，运维工作量减少80%。关键是要建立制度化的清理流程，而不是临时救火。