实战HarborAPI：批量镜像删除全攻略

2025年11月15日 互联网

实战HarborAPI：批量镜像删除全攻略

引言：镜像管理的挑战与Harbor API的价值

在容器化部署日益普及的今天，Harbor作为企业级镜像仓库，承担着存储、分发和管理Docker镜像的核心任务。然而，随着项目迭代加速，镜像仓库中往往会积累大量过期、冗余或测试用的镜像，这些“数字垃圾”不仅占用存储空间，还可能干扰镜像检索效率。手动逐个删除镜像效率低下且易出错，而Harbor提供的RESTful API则为批量自动化管理提供了可能。本文将围绕“实战使用Harbor API批量删除镜像”展开，从基础认证到高级脚本编写，为开发者提供一套可落地的解决方案。

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

1.1 API认证机制

Harbor API采用基于令牌（Token）的认证方式，用户需通过用户名和密码获取访问令牌，后续请求均需携带该令牌。示例代码如下（Python）：

  1. import requests
  3. def get_harbor_token(url, username, password):
  4.     auth_url = f"{url}/api/v2.0/users/login"
  5.     response = requests.post(
  6.         auth_url,
  7.         json={"username": username, "password": password},
  8.         verify=False  # 生产环境需配置SSL证书
  9.     )
  10.     if response.status_code == 200:
  11.         return response.json()["token"]
  12.     else:
  13.         raise Exception("认证失败，请检查用户名密码或网络连接")

关键点：

  • 确保Harbor版本≥2.0（API v2.0），旧版本需调整端点路径。
  • 生产环境必须启用HTTPS，避免明文传输密码。
  • 令牌有效期通常为30分钟，需在脚本中实现自动刷新逻辑。

1.2 权限控制

Harbor通过角色（RBAC）控制API访问权限，删除镜像需具备project admin或system admin权限。若遇到403错误，需检查：

  • 当前用户是否属于目标项目的管理员。
  • 项目是否设置为“私有”（Public项目可能限制删除操作）。

二、批量删除的核心步骤

2.1 查询镜像列表

Harbor API的/api/v2.0/projects/{project_id}/repositories端点可获取项目下所有镜像仓库，进一步通过/api/v2.0/projects/{project_id}/repositories/{repository_name}/artifacts获取具体镜像标签。示例：

  1. def list_artifacts(url, token, project_id, repository_name):
  2.     headers = {"Authorization": f"Bearer {token}"}
  3.     artifacts_url = f"{url}/api/v2.0/projects/{project_id}/repositories/{repository_name}/artifacts"
  4.     response = requests.get(artifacts_url, headers=headers, verify=False)
  5.     return response.json()

优化建议：

  • 使用q参数过滤（如q=name~test*筛选测试镜像）。
  • 分页查询（page=1&page_size=100）避免一次性加载过多数据。

2.2 过滤待删除镜像

根据业务规则（如创建时间、标签名）筛选目标镜像。例如，删除所有snapshot前缀的标签：

  1. def filter_artifacts(artifacts, prefix="snapshot"):
  2.     return [artifact for artifact in artifacts 
  3.             if any(tag["name"].startswith(prefix) for tag in artifact["tags"])]

2.3 执行批量删除

Harbor API的删除端点为/api/v2.0/projects/{project_id}/repositories/{repository_name}/artifacts/{digest}，需传递镜像的digest值（而非标签名）。示例：

  1. def delete_artifact(url, token, project_id, repository_name, digest):
  2.     headers = {"Authorization": f"Bearer {token}"}
  3.     delete_url = f"{url}/api/v2.0/projects/{project_id}/repositories/{repository_name}/artifacts/{digest}"
  4.     response = requests.delete(delete_url, headers=headers, verify=False)
  5.     return response.status_code == 200

注意事项：

  • 删除操作不可逆，建议先备份重要镜像。
  • 若镜像被其他标签引用，需先删除所有关联标签。

三、自动化脚本实战

3.1 完整脚本示例

以下Python脚本整合了认证、查询、过滤和删除功能：

  1. import requests
  2. import argparse
  4. def main():
  5.     parser = argparse.ArgumentParser(description="Harbor批量删除镜像工具")
  6.     parser.add_argument("--url", required=True, help="Harbor地址，如https://harbor.example.com")
  7.     parser.add_argument("--user", required=True, help="Harbor用户名")
  8.     parser.add_argument("--password", required=True, help="Harbor密码")
  9.     parser.add_argument("--project", required=True, help="项目ID或名称")
  10.     parser.add_argument("--prefix", default="snapshot", help="待删除标签的前缀")
  11.     args = parser.parse_args()
  13.     # 获取令牌
  14.     token = get_harbor_token(args.url, args.user, args.password)
  16.     # 查询项目ID（若输入为名称）
  17.     project_id = get_project_id(args.url, token, args.project)
  19.     # 列出所有仓库
  20.     repositories = list_repositories(args.url, token, project_id)
  22.     # 遍历仓库并删除符合条件的镜像
  23.     for repo in repositories:
  24.         artifacts = list_artifacts(args.url, token, project_id, repo["name"])
  25.         targets = filter_artifacts(artifacts, args.prefix)
  26.         for artifact in targets:
  27.             for tag in artifact["tags"]:
  28.                 if delete_artifact(args.url, token, project_id, repo["name"], tag["digest"]):
  29.                     print(f"已删除: {repo['name']}:{tag['name']}")
  31. if __name__ == "__main__":
  32.     main()

3.2 脚本优化方向

  1. 并发处理：使用concurrent.futures实现多线程删除，提升效率。
  2. 日志记录：将操作结果写入文件，便于审计。
  3. 交互式确认：删除前显示待操作列表，避免误删。

四、常见问题与解决方案

4.1 404错误：镜像不存在

  • 原因：digest值错误或镜像已被删除。
  • 解决：在删除前重新查询镜像状态。

4.2 409错误：镜像被引用

  • 原因：镜像存在多个标签。
  • 解决：先删除所有关联标签，或使用/api/v2.0/projects/{project_id}/artifacts/{digest}端点强制删除（需管理员权限）。

4.3 性能瓶颈

  • 场景：需删除数万条镜像记录。
  • 优化：
    • 分批处理（如每次100条）。
    • 使用Harbor的垃圾回收机制（/api/v2.0/system/gc）清理无引用镜像。

五、最佳实践建议

  1. 权限最小化：为脚本创建专用服务账号，仅授予必要权限。
  2. 备份策略：删除前通过docker pull备份重要镜像至本地或对象存储。
  3. 监控告警：结合Prometheus监控Harbor存储使用率，触发自动化清理。
  4. 标签规范：制定镜像命名规范（如<app>-<version>-<env>），减少冗余。

结语：从手动到自动化的跨越

通过Harbor API实现批量镜像删除，不仅解决了手动操作的效率问题，更将镜像管理纳入自动化运维体系。开发者可根据实际需求扩展脚本功能，例如集成至CI/CD流水线，实现“构建即清理”的闭环管理。随着容器技术的深入应用，掌握Harbor API等基础设施的自动化操作，将成为DevOps工程师的核心竞争力之一。

最新文章