Harbor镜像仓库老镜像清理指南：安全删除与优化策略

一、Harbor镜像仓库老镜像管理的重要性

Harbor作为企业级Docker镜像仓库，在CI/CD流程中承担着存储、分发镜像的核心职责。随着项目迭代，仓库中会积累大量老旧镜像，这些镜像不仅占用宝贵存储资源，还可能带来安全隐患（如未修复漏洞的旧版本镜像）。有效管理老镜像，既能降低存储成本，又能提升仓库安全性与操作效率。

1.1 老镜像的负面影响

• 存储压力：每个镜像层（Layer）占用独立存储空间，未清理的旧版本会持续消耗资源。
• 安全风险：未及时删除的旧镜像可能包含已知漏洞，若被恶意利用将威胁系统安全。
• 管理混乱：大量无用镜像导致仓库内容冗余，增加运维人员查找目标镜像的难度。

1.2 清理目标与原则

• 目标：删除无用的旧版本镜像，保留最新稳定版及关键历史版本。
• 原则：
  • 避免误删生产环境依赖的镜像。
  • 遵循企业镜像保留策略（如保留最近N个版本）。
  • 记录删除操作，便于审计与回溯。

二、Harbor老镜像删除方法

2.1 手动删除镜像

2.1.1 通过Harbor Web界面删除

1. 登录Harbor：使用管理员账户访问Harbor管理界面。
2. 定位项目与镜像：
   • 进入目标项目（Project）。
   • 在“仓库”（Repositories）标签页下找到需清理的镜像仓库。
3. 删除标签：
   • 点击镜像仓库进入详情页。
   • 在“标签”（Tags）列表中，选择需删除的标签，点击右侧“删除”按钮。
   • 确认删除操作（需管理员权限）。

示例：删除项目myapp中镜像nginx:1.19的旧版本标签v1.0。

2.1.2 通过Harbor API删除

Harbor提供RESTful API，可通过编程方式删除镜像。

步骤：

1. 获取API令牌：登录Harbor获取管理员令牌（Token）。
2. 调用删除API：

   curl -X DELETE "https://<harbor-url>/api/v2.0/projects/<project-name>/repositories/<repository-name>/artifacts/<tag>" \
   -H "accept: application/json" \
   -H "Authorization: Bearer <token>"

   参数说明：

   • <harbor-url>：Harbor服务器地址。
   • <project-name>：项目名称（如myapp）。
   • <repository-name>：镜像仓库路径（如library/nginx）。
   • <tag>：需删除的标签（如v1.0）。

示例：删除myapp项目中library/nginx镜像的v1.0标签。

2.2 自动化删除策略

2.2.1 使用Harbor内置的保留策略

Harbor 2.0+版本支持为项目配置镜像保留策略，自动清理符合条件的旧镜像。

配置步骤：

1. 进入项目设置：在Harbor Web界面选择目标项目，点击“配置”（Configuration）。
2. 设置保留策略：
   • 在“保留策略”（Retention Policy）标签页下，启用策略。
   • 选择策略类型（如“按标签数量保留”或“按时间保留”）。
   • 设置保留规则（如保留最近5个标签，或删除30天前的镜像）。
3. 应用策略：保存设置后，Harbor会按规则自动清理镜像。

示例：配置项目myapp保留最近3个标签，其余自动删除。

2.2.2 结合Cron Job与脚本实现定时清理

对于未使用Harbor保留策略的环境，可通过Cron Job定期执行清理脚本。

脚本示例（基于Harbor API）：

#!/bin/bash
HARBOR_URL="https://<harbor-url>"
PROJECT="myapp"
REPO="library/nginx"
TOKEN="<admin-token>"
# 获取所有标签
TAGS=$(curl -s -H "Authorization: Bearer $TOKEN" \
"${HARBOR_URL}/api/v2.0/projects/${PROJECT}/repositories/${REPO}/artifacts" | \
jq -r '.[].tags[].name')
# 保留最近3个标签，删除其余
COUNT=0
for TAG in $TAGS; do
  ((COUNT++))
  if [ $COUNT -gt 3 ]; then
    echo "Deleting tag: ${TAG}"
    curl -X DELETE "${HARBOR_URL}/api/v2.0/projects/${PROJECT}/repositories/${REPO}/artifacts/${TAG}" \
    -H "Authorization: Bearer $TOKEN"
  fi
done

说明：

• 脚本使用jq解析API返回的JSON数据。
• 通过计数器保留前3个标签，删除后续标签。
• 需安装jq工具（apt-get install jq或yum install jq）。

2.2.3 使用第三方工具（如crond+skopeo）

skopeo是Red Hat开发的容器镜像工具，可配合Cron Job实现跨仓库镜像管理。

示例：定期删除本地Harbor中超过90天的镜像。

#!/bin/bash
HARBOR_URL="<harbor-url>"
PROJECT="myapp"
REPO="library/nginx"
# 查找超过90天的镜像（需结合Harbor API或本地日志）
# 假设通过日志分析获取旧镜像列表
OLD_IMAGES=$(cat /var/log/harbor_old_images.log)
for IMAGE in $OLD_IMAGES; do
  skopeo delete --tls-verify=false docker://${HARBOR_URL}/${PROJECT}/${REPO}:${IMAGE}
done

注意：skopeo需配置Harbor的TLS证书或禁用验证（生产环境建议配置证书）。

三、删除镜像的最佳实践

3.1 备份重要镜像

在执行大规模删除前，建议备份关键镜像至冷存储（如对象存储S3）。

备份方法：

• 使用docker pull下载镜像至本地，再上传至备份存储。
• 通过Harbor的“系统管理”→“垃圾回收”功能生成镜像列表，手动备份。

3.2 记录删除操作

所有删除操作应记录至日志系统，便于审计与问题排查。

日志内容建议：

• 删除时间、操作人、项目名称、镜像仓库、删除标签。
• 删除原因（如“清理超过6个月的旧版本”）。

3.3 测试环境优先验证

在生产环境执行删除前，先在测试环境验证脚本与策略的正确性，避免误删。

3.4 结合监控告警

通过Prometheus+Grafana监控Harbor存储使用率，当存储达到阈值（如80%）时触发告警，提醒运维人员清理。

四、常见问题与解决方案

4.1 删除后存储未释放

原因：Harbor使用“软删除”机制，镜像标记为删除但未立即释放空间。

解决方案：

• 执行Harbor的“垃圾回收”（Garbage Collection）功能：

  # 进入Harbor安装目录
  cd /path/to/harbor
  # 停止Harbor服务
  docker-compose down
  # 执行垃圾回收
  ./install.sh --gc
  # 重启Harbor
  docker-compose up -d

• 定期执行垃圾回收（建议每周一次）。

4.2 权限不足导致删除失败

原因：操作账户未分配project admin或system admin权限。

解决方案：

• 在Harbor Web界面“系统管理”→“用户管理”中，为账户分配足够权限。
• 通过API删除时，确保令牌具有管理员权限。

4.3 删除后镜像仍被引用

原因：Kubernetes或其他容器编排工具仍在使用旧镜像。

解决方案：

• 更新Deployment/StatefulSet的镜像版本为最新版。
• 使用kubectl rollout restart重启Pod。

五、总结

Harbor镜像仓库的老旧镜像管理是DevOps流程中的关键环节。通过手动删除、自动化策略及最佳实践的结合，可有效释放存储空间、降低安全风险，并提升仓库运维效率。建议企业根据自身需求选择合适的清理方式，并定期审计与优化策略，确保Harbor长期稳定运行。