flowchart TD A[Harbor 磁盘空间不足] --> B{选择清理方式} B -- 官方推荐
UI配置 --> C[配置保留策略] B -- 高度定制化
API操作 --> D[编写清理脚本] subgraph C [方案一：通过 Harbor UI 配置保留策略] C1[创建保留规则] C2[设置保留最近180天镜像] C3[设置定时执行或手动运行] end subgraph D [方案二：通过 Harbor API 编写脚本] D1[认证获取 Token] D2[筛选创建时间早于半年的标签] D3[调用 API 删除旧标签] end C --> E D --> E[执行垃圾回收 GC] subgraph E [关键步骤：垃圾回收 GC] E1[安排维护窗口
GC期间仓库只读] E2[执行垃圾回收命令] E3[真正释放物理磁盘空间] end E --> F[磁盘空间得到释放]

3 方法一：使用Harbor原生保留策略（推荐UI操作）

Harbor自v2.4版本起提供了强大的保留策略(Retention Policy)功能，这是清理旧镜像的最简便方法。

3.1 配置步骤

1. 登录Harbor控制台，进入需要清理的项目
2. 点击"策略"选项卡 -> "添加规则"
3. 配置保留规则：
   • 规则名称：例如"清理半年前镜像"
   • 匹配仓库：可使用**匹配所有仓库，或指定特定仓库
   • 保留策略：选择"保留最近多少天被推送过的"，设置天数为180天（约半年）
   • 标签过滤：可根据需要设置标签匹配模式（如release-*）
   • 删除未打标签的镜像：建议启用，以清理无标签的中间层镜像
4. 设置执行频率（如每周一次）
5. 点击"模拟运行"预览将被清理的镜像
6. 确认无误后"立即执行"

3.2 优势与注意事项

• 优势：官方支持、配置简单、可定时自动运行、提供模拟运行功能降低风险
• 注意事项：
  • 保留策略基于"保留最近推送的镜像"逻辑，而非直接按时间点删除
  • 需要Harbor v2.4+版本支持
  • 执行后仍需运行垃圾回收才能释放物理空间

4 方法二：使用API脚本精确删除

对于需要更复杂清理逻辑或使用旧版Harbor的情况，可通过API脚本实现精确控制。

4.1 Python脚本示例

以下Python脚本示例演示了如何删除指定项目中所有早于半年的镜像标签：

import requests
from datetime import datetime, timedelta

# Harbor配置
HARBOR_URL = 'https://your-harbor.com'
USERNAME = 'admin'
PASSWORD = 'your-password'
PROJECT_NAME = 'your-project'

# 计算半年前时间点
six_months_ago = datetime.now() - timedelta(days=180)

# 获取认证token
def get_token():
    login_url = f'{HARBOR_URL}/c/login'
    resp = requests.post(login_url, json={
        'principal': USERNAME, 
        'password': PASSWORD
    }, verify=False)
    return resp.headers.get('Authorization')

# 获取项目中的所有仓库
def get_repositories(project):
    headers = {'Authorization': get_token()}
    repos_url = f'{HARBOR_URL}/api/v2.0/projects/{project}/repositories'
    resp = requests.get(repos_url, headers=headers, verify=False)
    return [repo['name'] for repo in resp.json()]

# 获取仓库的所有标签及其创建时间
def get_tags(repository):
    headers = {'Authorization': get_token()}
    tags_url = f'{HARBOR_URL}/api/v2.0/{repository}/tags'
    resp = requests.get(tags_url, headers=headers, verify=False)
    return [(tag['name'], datetime.strptime(tag['push_time'], '%Y-%m-%dT%H:%M:%S.%fZ')) 
            for tag in resp.json()]

# 删除早于指定时间的标签
def delete_old_tags():
    for repo in get_repositories(PROJECT_NAME):
        tags = get_tags(repo)
        for tag_name, push_time in tags:
            if push_time 

4.2 Shell脚本方案

Alternatively，也可以使用Shell脚本实现类似功能：

#!/bin/bash
HARBOR_URL="https://your-harbor.com"
USERNAME="admin"
PASSWORD="password"
PROJECT="your-project"

# 获取token
TOKEN=$(curl -s -k -X POST -H "Content-Type: application/json" 
  -d "{"principal": "$USERNAME", "password": "$PASSWORD"}" 
  "$HARBOR_URL/c/login" | grep -o '"token":"[^"]*' | cut -d'"' -f4)

# 获取项目中的仓库列表
REPOS=$(curl -s -k -X GET -H "Authorization: Bearer $TOKEN" 
  "$HARBOR_URL/api/v2.0/projects/$PROJECT/repositories" | jq -r '.[].name')

for REPO in $REPOS; do
  # 获取仓库的标签列表
  TAGS=$(curl -s -k -X GET -H "Authorization: Bearer $TOKEN" 
    "$HARBOR_URL/api/v2.0/$REPO/tags" | jq -r '.[] | [.name, .push_time] | @tsv')
  
  while IFS=$'t' read -r TAG PUSH_TIME; do
    # 转换时间格式并比较
    PTIME=$(date -d "$PUSH_TIME" +%s)
    SIX_MONTHS_AGO=$(date -d "6 months ago" +%s)
    
    if [ $PTIME -lt $SIX_MONTHS_AGO ]; then
      # 删除旧标签
      curl -s -k -X DELETE -H "Authorization: Bearer $TOKEN" 
        "$HARBOR_URL/api/v2.0/$REPO/tags/$TAG"
      echo "Deleted: $REPO:$TAG"
    fi
  done 

4.3 API方法的优缺点

• 优点：灵活性强，可精确控制删除条件，适合批量操作
• 缺点：需要编程知识，存在一定风险，需谨慎测试

5 关键步骤：运行垃圾回收释放物理空间

无论采用哪种方法删除镜像，都必须执行此步骤才能真正释放磁盘空间。

5.1 执行垃圾回收

1. 安排维护窗口：GC期间Harbor将进入只读模式，需提前通知团队
2. 执行GC命令：

   # 进入Harbor安装目录
   cd /path/to/harbor
   
   # 首先进行试运行（不实际删除）
   docker-compose exec -T registry garbage-collect --dry-run /etc/registry/config.yml
   
   # 确认无误后正式执行
   docker-compose exec -T registry garbage-collect /etc/registry/config.yml
   

3. 监控执行结果：GC完成后，查看释放的存储空间大小

5.2 新版Harbor的在线GC

Harbor v2.0+支持在线垃圾回收，可通过UI操作：

1. 以管理员身份登录
2. 进入"系统管理" -> "垃圾清理"
3. 点击"立即清理"或设置定时任务
4. 在"历史记录"中查看执行结果

6 预防措施：建立有效的镜像管理策略

清理只是治标，预防才是根本。以下措施可有效控制镜像增长：

6.1 制定镜像标签规范

• 使用语义化版本控制（如v1.2.3）
• 包含构建日期或Git Commit ID（如20230901-abc1234）
• 区分环境（如dev、staging、prod）
• 避免滥用latest标签

6.2 设置合理的保留策略

根据不同环境设置不同的保留策略：

环境	保留策略	执行频率
开发环境	保留最近10-30个版本或7天	每天
测试环境	保留最近20-50个版本或30天	每周
生产环境	保留所有稳定版本或按需保留	手动

6.3 自动化清理流程

将清理流程纳入CI/CD流水线，定期自动执行：

1. 使用Harbor API查询存储使用情况
2. 在磁盘空间达到阈值时自动触发清理
3. 定期运行垃圾回收任务
4. 设置通知机制，报告清理结果

7 总结

清理Harbor中半年前的镜像是一个系统性的过程，涉及标记删除和物理释放两个关键阶段。您可以根据实际情况选择合适的方法：

1. 首选方案：使用Harbor原生的保留策略功能（方法一），通过图形界面配置保留规则，简单可靠且支持自动化。
2. 备用方案：如需更复杂条件，可通过API脚本（方法二）精确控制删除过程，但需注意测试和验证。
3. 必须步骤：无论采用哪种删除方法，都必须执行垃圾回收(GC) 来真正释放物理磁盘空间。

定期清理不再使用的镜像不仅是存储空间的要求，也是安全最佳实践。通过建立规范的镜像管理策略和自动化清理流程，您可以有效控制Harbor存储增长，确保容器环境的高效稳定运行。

重要提示：在执行任何删除操作前，请务必确认备份重要镜像，并确保没有运行中的容器依赖这些镜像，以免影响业务正常运行。