Harbor镜像仓库清理旧镜像的全面指南

Harbor作为企业级Docker镜像仓库，在持续集成/持续部署(CI/CD)流程中扮演着关键角色。随着时间推移，未及时清理的旧镜像会显著占用存储空间，影响系统性能并增加运维成本。本文将系统阐述Harbor镜像仓库清理旧镜像的多种方法，帮助管理员高效管理存储资源。

一、理解Harbor镜像存储机制

Harbor采用两层存储结构：

项目层：每个项目拥有独立的镜像存储空间
标签层：同一镜像的不同版本通过标签区分

镜像数据实际存储在/data目录下（默认路径），包含：

registry：存储镜像层数据
database：存储元数据
redis：缓存数据（如配置）

典型存储结构示例：

/data/
├── registry/
│   ├── docker/
│   │   └── registry/
│   │       └── v2/
│   │           ├── repositories/
│   │           └── blobs/
├── database/
└── redis/

二、手动清理方法

1. 通过Web界面删除

操作步骤：

登录Harbor管理界面
进入目标项目
在”标签”选项卡中选择要删除的镜像版本
点击”删除”按钮确认

适用场景：少量镜像的精确删除，适合运维人员日常维护。

2. 使用Harbor API删除

通过REST API实现批量删除：

# 获取镜像列表
curl -u "admin:Harbor12345" -X GET "https://harbor.example.com/api/v2.0/projects/library/repositories"
# 删除特定标签
curl -u "admin:Harbor12345" -X DELETE "https://harbor.example.com/api/v2.0/projects/library/repositories/nginx/artifacts/1.21"

优势：可集成到自动化脚本中，适合定期维护任务。

三、标签策略管理

1. 保留策略配置

在harbor.yml中配置：

# 示例配置
gc:
  enabled: true
  schedule: "0 0 * * *"  # 每天午夜执行
  rules:
    - repository: "**"
      retain:
        min: 3  # 每个镜像最少保留3个版本
        days: 7 # 保留最近7天的镜像

2. 标签命名规范

推荐采用语义化版本控制：

<项目>-<版本>-<构建号>
# 示例
web-app-1.2.3-20230815

最佳实践：

使用CI工具自动生成规范标签
避免使用latest作为生产环境标签
定期审核标签命名规范

四、自动清理工具

1. Harbor内置GC工具

执行垃圾回收命令：

# 停止Harbor服务（根据部署方式选择）
docker-compose down
# 执行GC
docker run -it --name gc --rm \
  -v /data:/var/lib/registry \
  -v /path/to/harbor.yml:/etc/harbor/harbor.yml \
  goharbor/harbor-gc:v2.5.0

执行流程：

扫描未引用的blob
生成删除列表
执行物理删除
更新元数据库

2. 第三方工具集成

推荐工具：

Reg：轻量级Docker镜像清理工具

reg -r https://harbor.example.com --auth admin:Harbor12345 \
  rm --tag-filter '*.old' library/nginx

Prometheus+Grafana：监控存储使用情况并设置告警

五、高级清理策略

1. 基于使用频率的清理

实现方案：

记录镜像下载日志
分析使用频率
自动标记低频镜像

示例日志分析脚本（Python）：

import pandas as pd
from collections import defaultdict
def analyze_usage(log_path):
    usage = defaultdict(int)
    with open(log_path) as f:
        for line in f:
            if "pull" in line:
                repo = line.split()[5]
                usage[repo] += 1
    return dict(sorted(usage.items(), key=lambda x: x[1]))

2. 生命周期策略配置

在harbor.yml中定义：

retention:
  enabled: true
  rules:
    - match:
        - "**/*-dev"
      action: "delete"
      days: 30
    - match:
        - "**/*-test"
      action: "retain"
      min: 5

六、实施建议

测试环境优先：首次执行清理前在测试环境验证

备份机制：清理前执行数据库备份

mysqldump -u root -p harbor > harbor_backup.sql

监控告警：设置存储使用率告警（建议80%阈值）
文档记录：维护清理策略变更记录

七、常见问题解决

删除后空间未释放：
- 检查是否有未完成的GC任务
- 确认文件系统是否支持稀疏文件处理
- 执行fstrim命令（适用于SSD）
权限错误：
- 确保执行用户有/data目录写权限
- 检查SELinux/AppArmor配置
性能影响：
- 避免在业务高峰期执行GC
- 调整GC并发参数（--workers）

八、最佳实践总结

分层清理策略：
- 开发环境：保留最近30天镜像
- 测试环境：保留最近15个版本
- 生产环境：保留最近5个稳定版本

自动化流程：

graph TD
  A[镜像推送] --> B{标签检查}
  B -->|符合策略| C[保留]
  B -->|不符合| D[标记待删]
  D --> E[定期清理]
  E --> F[更新元数据]

容量规划：
- 预留20%缓冲空间
- 定期评估存储扩容需求
- 考虑使用对象存储作为二级存储

通过系统实施上述清理策略，企业可有效管理Harbor镜像仓库的存储空间，降低运维成本，同时确保CI/CD流程的顺畅运行。建议每季度进行一次全面清理策略评审，根据业务发展调整保留策略。

Harbor镜像仓库高效清理策略：释放存储空间指南