Harbor镜像仓库清理指南：高效管理历史镜像

摘要

随着容器化技术的普及，Harbor作为企业级镜像仓库被广泛使用。然而，镜像文件随时间积累会占用大量存储空间，影响系统性能。本文详细介绍Harbor镜像仓库清理旧镜像的三种方法：手动删除、配置自动清理策略、结合CI/CD流程优化。通过命令示例和配置步骤，帮助开发者高效管理存储空间，避免因镜像堆积导致的性能问题。

一、Harbor镜像仓库清理的必要性

Harbor镜像仓库在持续使用过程中，会产生大量历史镜像版本。这些旧镜像可能来自：

开发阶段的频繁迭代构建
测试环境的临时镜像
废弃项目的残留镜像
构建失败产生的无效镜像

存储空间占用会带来以下问题：

磁盘空间不足导致新镜像无法推送
备份时间延长影响运维效率
查询性能下降影响开发体验
增加存储成本（特别是云上部署场景）

据统计，未清理的Harbor仓库中，超过60%的存储空间被6个月未访问的镜像占用。因此，建立科学的镜像清理机制至关重要。

二、手动清理旧镜像的方法

1. 通过Web界面删除

登录Harbor管理界面后：

进入”项目”页面选择目标项目
点击”标签”选项卡查看所有镜像版本
勾选需要删除的镜像标签
点击”删除”按钮确认操作

操作提示：

删除前建议确认镜像使用情况
可通过”最后推送时间”排序辅助筛选
重要镜像建议先导出备份

2. 使用Harbor API删除

通过REST API实现自动化删除：

# 获取镜像标签列表
curl -u "用户名:密码" -X GET "https://harbor地址/api/v2.0/projects/项目名/repositories/镜像名/artifacts" -H "accept: application/json"
# 删除特定标签
curl -u "用户名:密码" -X DELETE "https://harbor地址/api/v2.0/projects/项目名/repositories/镜像名/artifacts/标签名" -H "accept: application/json"

安全建议：

使用服务账号而非个人账号
限制API调用权限
记录删除操作日志

3. 使用Harbor CLI工具

安装Harbor官方CLI后执行：

# 登录Harbor
harbor-cli login --username 用户名 --password 密码 https://harbor地址
# 列出镜像
harbor-cli repo list 项目名
# 删除镜像
harbor-cli artifact delete 项目名/镜像名:标签名

优势：

适合脚本化操作
支持批量处理
操作记录可追溯

三、配置自动清理策略

1. 设置保留策略

在Harbor管理界面：

进入”系统管理”→”垃圾回收”
配置”保留策略”：
- 按保留天数（如保留最近30天）
- 按保留版本数（如每个镜像保留5个最新版本）
- 结合标签规则（如删除包含”test”的标签）

配置示例：

{
  "retention": {
    "type": "keepN",
    "params": {
      "n": 5
    }
  },
  "dryRun": false,
  "template": "删除超过{{.N}}个版本的镜像"
}

2. 配置垃圾回收任务

设置定期执行的垃圾回收：

在”系统管理”→”垃圾回收”中创建任务
配置执行时间（建议非业务高峰期）
选择清理范围（全部项目或指定项目）
设置通知方式（邮件/Webhook）

执行日志分析：

2023-11-15 02:00:00 [INFO] 开始垃圾回收
2023-11-15 02:03:22 [INFO] 删除镜像: project1/nginx:old-version (未访问180天)
2023-11-15 02:05:45 [INFO] 释放空间: 12.5GB
2023-11-15 02:06:00 [INFO] 垃圾回收完成

3. 结合存储配额管理

在项目设置中配置存储配额：

设置项目存储上限（如500GB）
配置警告阈值（如达到80%时通知）
启用自动清理当超过配额时

配额策略示例：

storageQuota:
  hardLimit: 500GB
  warningThreshold: 80%
  autoClean: true
  cleanPolicy:
    keepDays: 90
    keepVersions: 3

四、高级清理技巧

1. 基于镜像元数据清理

利用Harbor的标签过滤功能：

# 删除所有包含"test"的镜像
harbor-cli artifact delete --filter "label like '%test%'" 项目名
# 删除未关联任何部署的镜像
harbor-cli artifact delete --filter "unused=true" 项目名

2. 结合CI/CD流程清理

在Jenkins/GitLab CI中添加清理步骤：

pipeline {
  agent any
  stages {
    stage('Build') { /* 构建步骤 */ }
    stage('Clean') {
      steps {
        sh '''
          # 删除30天前的镜像
          curl -u "$HARBOR_CRED" -X DELETE "https://harbor/api/v2.0/projects/$PROJECT/repositories?with_detail=true" | \
          jq -r '.[] | select(.tags[0].push_time < "'$(date -d "30 days ago" +%s)'") | .name' | \
          xargs -I {} curl -u "$HARBOR_CRED" -X DELETE "https://harbor/api/v2.0/projects/$PROJECT/repositories/{}"
        '''
      }
    }
  }
}

3. 跨项目镜像分析

使用Harbor提供的分析工具：

-- 查询各项目存储占用
SELECT project_name, SUM(size)/1024/1024 AS size_mb 
FROM artifacts 
GROUP BY project_name 
ORDER BY size_mb DESC;
-- 查询未访问超过180天的镜像
SELECT repository_name, tag, push_time 
FROM artifacts 
WHERE push_time < NOW() - INTERVAL '180 days';

五、最佳实践建议

分级存储策略：
- 开发环境：保留最近7天镜像
- 测试环境：保留最近30天镜像
- 生产环境：保留最近90天镜像

备份与清理结合：

# 备份后删除
harbor-cli artifact export 项目名/镜像名:标签名 /backup/path
harbor-cli artifact delete 项目名/镜像名:标签名

监控与告警：
- 设置存储使用率监控
- 配置清理任务执行告警
- 建立清理操作审批流程
权限控制：
- 限制普通用户的删除权限
- 记录所有清理操作日志
- 定期审计清理策略

六、常见问题解决

删除后空间未释放：
- 执行Harbor的垃圾回收任务
- 检查是否有未完成的上传操作
- 重启Harbor相关服务
误删镜像恢复：
- 从备份恢复
- 使用Harbor的回收站功能（需提前配置）
- 联系管理员从底层存储恢复
清理任务失败：
- 检查日志定位错误
- 验证API权限
- 确保有足够磁盘空间执行清理

七、未来发展趋势

智能清理算法：
- 基于镜像使用频率预测
- 结合容器运行数据分析
- 机器学习优化保留策略
与K8s集成：
- 自动识别未使用的镜像
- 根据Deployment历史清理
- 结合HPA策略动态调整
多云管理：
- 跨集群镜像管理
- 统一清理策略配置
- 成本优化建议

通过科学合理的镜像清理策略，Harbor镜像仓库可以保持高效运行，为企业容器化部署提供稳定可靠的存储支持。建议结合实际业务需求，制定适合的清理方案，并定期评估优化。