实战Harbor API：批量删除镜像的高效指南

引言

在容器化部署日益普及的今天，Harbor作为企业级私有镜像仓库，其管理效率直接影响开发运维流程。当镜像仓库积累大量过期或无用镜像时，手动逐个删除不仅耗时，还容易遗漏。本文将深入探讨如何通过Harbor API实现批量删除镜像，结合实战案例与代码示例，帮助开发者高效完成镜像清理任务。

一、Harbor API基础：认证与权限

1.1 API认证机制

Harbor API采用基于Token的认证方式，用户需先获取有效的Token才能执行后续操作。Token的获取通常通过以下两种方式：

基本认证：使用用户名和密码进行Base64编码后，在请求头中添加Authorization: Basic <encoded_credentials>。
Bearer Token：通过登录接口获取Token，后续请求在请求头中添加Authorization: Bearer <token>。

示例代码（Python）：

import requests
from base64 import b64encode
def get_harbor_token(url, username, password):
    auth = b64encode(f"{username}:{password}".encode()).decode()
    headers = {"Authorization": f"Basic {auth}"}
    response = requests.get(f"{url}/api/v2.0/systeminfo", headers=headers)
    # 实际Token获取需调用登录接口，此处仅为示例
    if response.status_code == 200:
        # 假设登录接口返回Token
        token = "mock_token_from_login"  # 实际需替换为真实Token
        return token
    else:
        raise Exception("Failed to authenticate")

1.2 权限要求

执行批量删除操作的用户需具备足够的权限，通常为Project Admin或System Admin角色。权限不足会导致403 Forbidden错误。

二、批量删除镜像的核心步骤

2.1 查询镜像列表

首先需获取目标项目的镜像列表，筛选出需要删除的镜像。Harbor API提供了/api/v2.0/projects/{project_id}/repositories接口用于查询仓库列表，再通过/api/v2.0/projects/{project_id}/repositories/{repository_name}/artifacts获取镜像详情。

示例代码：

def list_repositories(url, token, project_id):
    headers = {"Authorization": f"Bearer {token}"}
    response = requests.get(f"{url}/api/v2.0/projects/{project_id}/repositories", headers=headers)
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception("Failed to list repositories")
def list_artifacts(url, token, project_id, repository_name):
    headers = {"Authorization": f"Bearer {token}"}
    response = requests.get(
        f"{url}/api/v2.0/projects/{project_id}/repositories/{repository_name}/artifacts",
        headers=headers
    )
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception("Failed to list artifacts")

2.2 筛选待删除镜像

根据业务需求筛选镜像，例如按标签名、创建时间或镜像大小。以下示例筛选所有带有dev标签的镜像：

def filter_artifacts(artifacts, tag_filter="dev"):
    filtered = []
    for artifact in artifacts:
        for tag in artifact.get("tags", []):
            if tag_filter in tag["name"]:
                filtered.append({
                    "repository": artifact["repository"],
                    "digest": artifact["digest"],
                    "tag": tag["name"]
                })
    return filtered

2.3 批量删除镜像

Harbor API提供了DELETE /api/v2.0/projects/{project_id}/repositories/{repository_name}/artifacts/{digest}接口用于删除镜像。需注意：

删除操作不可逆，需谨慎执行。
批量删除时建议添加错误处理，避免因单个镜像删除失败导致整个流程中断。

示例代码：

def delete_artifacts(url, token, project_id, artifacts_to_delete):
    headers = {"Authorization": f"Bearer {token}"}
    success_count = 0
    for artifact in artifacts_to_delete:
        repo_name = artifact["repository"]
        digest = artifact["digest"]
        response = requests.delete(
            f"{url}/api/v2.0/projects/{project_id}/repositories/{repo_name}/artifacts/{digest}",
            headers=headers
        )
        if response.status_code == 200:
            success_count += 1
            print(f"Deleted: {repo_name}@{digest}")
        else:
            print(f"Failed to delete {repo_name}@{digest}: {response.text}")
    print(f"Successfully deleted {success_count}/{len(artifacts_to_delete)} artifacts")

三、完整脚本实现

结合上述步骤，以下是一个完整的批量删除脚本：

import requests
from base64 import b64encode
def main():
    HARBOR_URL = "https://your-harbor-server.com"
    USERNAME = "admin"
    PASSWORD = "your_password"
    PROJECT_ID = 1  # 替换为实际项目ID
    TAG_FILTER = "dev"  # 筛选条件
    # 1. 获取Token
    token = get_harbor_token(HARBOR_URL, USERNAME, PASSWORD)
    # 2. 查询仓库列表
    repositories = list_repositories(HARBOR_URL, token, PROJECT_ID)
    # 3. 查询并筛选镜像
    all_artifacts = []
    for repo in repositories:
        repo_name = repo["name"]
        artifacts = list_artifacts(HARBOR_URL, token, PROJECT_ID, repo_name)
        all_artifacts.extend(artifacts)
    filtered_artifacts = filter_artifacts(all_artifacts, TAG_FILTER)
    # 4. 批量删除
    delete_artifacts(HARBOR_URL, token, PROJECT_ID, filtered_artifacts)
if __name__ == "__main__":
    main()

四、安全与最佳实践

4.1 权限控制

限制执行批量删除操作的账号权限，避免误删生产环境镜像。
定期轮换API Token，降低泄露风险。

4.2 日志与审计

记录所有删除操作的日志，包括操作人、时间、镜像信息等。
Harbor自带审计日志功能，可通过/api/v2.0/auditlogs接口查询。

4.3 备份策略

删除前建议备份重要镜像，可通过Harbor的系统备份功能或手动导出。

4.4 性能优化

批量删除时，可并行发起请求以提高效率（需注意Harbor的API并发限制）。
避免在高峰期执行大规模删除操作，减少对仓库性能的影响。

五、常见问题与解决方案

5.1 404 Not Found错误

检查项目ID、仓库名和Digest是否正确。
确认镜像是否存在，可通过Harbor Web界面验证。

5.2 403 Forbidden错误

检查用户权限，确保具备Project Admin或更高权限。
确认Token是否过期，需重新获取。

5.3 500 Internal Server Error

可能是Harbor服务端问题，检查Harbor日志（通常位于/var/log/harbor/）。
减少批量删除的并发量，避免服务端过载。

六、总结

通过Harbor API实现批量删除镜像，可显著提升镜像管理效率，尤其适用于大规模容器化部署场景。本文从API认证、镜像查询、筛选到批量删除，提供了完整的实战指南，并附有Python代码示例。开发者可根据实际需求调整筛选条件和错误处理逻辑，确保操作的安全与高效。

关键点回顾：

使用Bearer Token进行API认证。
通过/api/v2.0/projects/{project_id}/repositories和/artifacts接口查询镜像。
筛选镜像时可根据标签、时间等条件定制逻辑。
删除操作需谨慎，建议先备份并记录日志。

掌握Harbor API的批量操作技巧，将帮助团队更好地管理容器镜像，释放存储空间，提升DevOps流程的自动化水平。