Harbor API完全指南：自动化镜像管理的15个实用接口示例-优快云博客

Harbor API完全指南：自动化镜像管理的15个实用接口示例

【免费下载链接】harbor Harbor 是一个开源的容器镜像仓库，用于存储和管理 Docker 镜像和其他容器镜像。 * 容器镜像仓库、存储和管理 Docker 镜像和其他容器镜像 * 有什么特点：支持多种镜像格式、易于使用、安全性和访问控制项目地址: https://gitcode.com/GitHub_Trending/ha/harbor

引言：告别手动操作的容器镜像管理痛点

你是否还在为以下问题困扰？频繁手动上传下载镜像占用大量开发时间、跨团队协作时权限管理混乱、无法实时监控镜像仓库状态导致部署延迟。作为容器镜像仓库的事实标准，Harbor提供了功能完备的API接口（Application Programming Interface，应用程序编程接口），通过自动化手段可将镜像管理效率提升80%。本文将系统讲解Harbor API的核心能力，提供15个覆盖项目管理、镜像操作、安全控制的实战示例，帮助你构建完整的自动化镜像管理流水线。

读完本文你将获得：

掌握Harbor API的认证机制与请求规范
学会15个高频接口的参数配置与响应处理
理解API调用的最佳实践与错误处理策略
获取可直接复用的Shell/Python调用代码
了解API在CI/CD流水线中的集成方案

Harbor API架构概览

API版本与基础信息

Harbor当前稳定API版本为v2.0，采用RESTful设计风格，支持JSON（JavaScript Object Notation，JavaScript对象表示法）数据格式。基础路径为/api/v2.0，所有请求需通过HTTP/HTTPS协议传输。

# API基础信息摘要
swagger: '2.0'
info:
  title: Harbor API
  description: These APIs provide services for manipulating Harbor project.
  version: '2.0'
host: localhost
schemes: [http, https]
basePath: /api/v2.0
produces: [application/json]
consumes: [application/json]

认证机制

Harbor API支持两种认证方式：

Basic认证：通过用户名/密码进行简单认证，适用于脚本自动化
令牌认证：通过JWT（JSON Web Token）实现复杂权限控制，适用于应用集成

所有需要权限的接口必须在HTTP头中包含认证信息：

Authorization: Basic YWRtaW46SGFyYm9yMTIzNDU=

API调用流程

典型的Harbor API调用流程包含以下步骤：

验证Harbor服务健康状态
进行身份认证获取访问权限
执行具体操作（如创建项目、上传镜像）
处理响应结果与错误信息

mermaid

核心API实战示例

1. 服务健康检查

接口信息

路径：GET /health
认证：无需认证
功能：检查Harbor各组件运行状态

请求示例：

curl -X GET "http://localhost/api/v2.0/health"

响应示例：

{
  "status": "healthy",
  "components": [
    {"name": "core", "status": "healthy"},
    {"name": "database", "status": "healthy"},
    {"name": "jobservice", "status": "healthy"},
    {"name": "redis", "status": "healthy", "details": {"version": "6.2.6"}},
    {"name": "registry", "status": "healthy"},
    {"name": "registryctl", "status": "healthy"}
  ]
}

应用场景：部署前检查、监控告警触发、自动化脚本前置验证

2. 创建项目

接口信息

路径：POST /projects
认证：需要管理员权限
功能：创建新的镜像仓库项目

请求示例：

curl -X POST "http://localhost/api/v2.0/projects" \
  -H "Authorization: Basic YWRtaW46SGFyYm9yMTIzNDU=" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "microservices",
    "public": false,
    "metadata": {
      "auto_scan": "true",
      "enable_content_trust": "true"
    }
  }'

请求体参数说明：

参数名	类型	描述	示例值
project_name	string	项目名称（必填）	"microservices"
public	boolean	是否公开访问	false
metadata.auto_scan	string	是否自动扫描镜像	"true"
metadata.enable_content_trust	string	是否启用内容信任	"true"
metadata.prevent_vul	string	阻止有漏洞的镜像	"true"
metadata.severity	string	漏洞严重级别阈值	"high"

响应状态码：

201: 创建成功
400: 请求参数错误
401: 未授权访问
409: 项目已存在

Python实现示例：

import requests
from requests.auth import HTTPBasicAuth

def create_harbor_project(project_name, public=False, auto_scan=True):
    url = "http://localhost/api/v2.0/projects"
    headers = {"Content-Type": "application/json"}
    data = {
        "project_name": project_name,
        "public": public,
        "metadata": {
            "auto_scan": str(auto_scan).lower(),
            "enable_content_trust": "true"
        }
    }
    
    response = requests.post(
        url,
        json=data,
        headers=headers,
        auth=HTTPBasicAuth("admin", "Harbor12345")
    )
    
    if response.status_code == 201:
        print(f"Project {project_name} created successfully")
        return True
    elif response.status_code == 409:
        print(f"Project {project_name} already exists")
        return False
    else:
        print(f"Failed to create project: {response.text}")
        return False

# 使用示例
create_harbor_project("backend-services", public=False)

3. 项目成员管理

接口信息

路径：POST /projects/{project_name_or_id}/members
认证：项目管理员权限
功能：添加用户/用户组到项目并分配角色

请求示例：

curl -X POST "http://localhost/api/v2.0/projects/microservices/members" \
  -H "Authorization: Basic YWRtaW46SGFyYm9yMTIzNDU=" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": 3,
    "member_user": {
      "username": "developer1"
    }
  }'

角色ID说明：

1: 项目管理员（ProjectAdmin）
2: 开发人员（Developer）
3: 访客（Guest）

应用场景：新团队加入时自动分配项目访问权限，配合LDAP用户导入实现批量授权

4. 镜像标签查询

接口信息

路径：GET /projects/{project_name}/repositories/{repository_name}/artifacts
认证：项目成员权限
功能：列出仓库中的镜像及标签信息

请求示例：

curl -X GET "http://localhost/api/v2.0/projects/microservices/repositories/nginx/artifacts?q=tags=*" \
  -H "Authorization: Basic YWRtaW46SGFyYm9yMTIzNDU="

响应过滤参数：

q=tags=*: 只返回有标签的镜像
q=tags=nil: 只返回无标签的镜像
q=tags=~v1: 模糊匹配标签包含"v1"的镜像
q=tags=v1.2.3: 精确匹配标签"v1.2.3"的镜像

响应示例（精简）：

[
  {
    "digest": "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6d0",
    "tags": [
      {"name": "v1.21.0", "immutable": false},
      {"name": "latest", "immutable": true}
    ],
    "size": 53500635,
    "created": "2023-01-15T08:30:45.721Z",
    "scan_overview": {
      "scan_status": "scanned",
      "severity": "low",
      "total": 3
    }
  }
]

5. 镜像复制管理

接口信息

路径：POST /replications
认证：管理员权限
功能：创建镜像同步规则，实现跨仓库备份

请求示例：

curl -X POST "http://localhost/api/v2.0/replications" \
  -H "Authorization: Basic YWRtaW46SGFyYm9yMTIzNDU=" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sync-to-backup",
    "source_registry": {
      "id": 1
    },
    "destination_registry": {
      "id": 2
    },
    "trigger": {
      "type": "manual"
    },
    "destination_namespace": "backup",
    "filters": [
      {
        "type": "repository",
        "value": "microservices/**"
      }
    ]
  }'

复制触发类型：

manual: 手动触发
event_based: 基于事件触发（如推送新镜像）
scheduled: 定时触发（CRON表达式）

6-15. 高频实用接口速查表

接口功能	HTTP方法	路径	关键参数	适用场景
获取项目列表	GET	/projects	page, page_size, public	项目管理报告
获取仓库统计	GET	/statistics	-	存储容量监控
删除镜像标签	DELETE	/projects/{p}/repositories/{r}/artifacts/{d}/tags/{t}	digest, tag	清理过期标签
创建Robot账号	POST	/robots	name, permissions	CI/CD流水线授权
获取镜像扫描结果	GET	/projects/{p}/repositories/{r}/artifacts/{d}/additions/vulnerabilities	-	漏洞自动化检查
更新项目元数据	PUT	/projects/{p}/metadatas/{k}	key, value	批量配置自动扫描
检查项目是否存在	HEAD	/projects	project_name	避免创建重复项目
获取项目成员	GET	/projects/{p}/members	page, page_size	权限管理
搜索镜像	GET	/search	q	跨项目镜像检索
创建保留规则	POST	/retentions	name, scope, rule	自动清理策略

API自动化最佳实践

认证令牌管理

对于频繁的API调用，建议使用JWT令牌替代Basic认证：

import requests

def get_harbor_token(base_url, username, password):
    """获取Harbor访问令牌"""
    auth_url = f"{base_url}/c/login"
    response = requests.post(
        auth_url,
        data={"principal": username, "password": password}
    )
    return response.cookies.get("sid")

# 使用令牌进行后续请求
token = get_harbor_token("http://localhost", "admin", "Harbor12345")
headers = {"Cookie": f"sid={token}"}
response = requests.get("http://localhost/api/v2.0/projects", headers=headers)

错误处理策略

Harbor API常见错误码及处理建议：

状态码	含义	处理策略
400	请求参数错误	检查请求体JSON格式与字段合法性
401	未授权	重新获取认证令牌或检查凭据
403	权限不足	确认用户具有操作所需角色
404	资源不存在	验证项目/仓库名称拼写
409	资源冲突	检查项目/镜像是否已存在
429	请求频率限制	实现指数退避重试机制
500	服务器内部错误	查看Harbor核心日志定位问题

批量操作实现

利用API分页机制处理大量数据：

#!/bin/bash
# 批量获取所有项目并导出为CSV

HARBOR_URL="http://localhost/api/v2.0"
AUTH="admin:Harbor12345"
PAGE=1
PAGE_SIZE=100
OUTPUT="projects.csv"

# 写入CSV表头
echo "project_id,name,public,creation_time,repo_count" > $OUTPUT

while true; do
  echo "Fetching page $PAGE..."
  RESPONSE=$(curl -s -u "$AUTH" "$HARBOR_URL/projects?page=$PAGE&page_size=$PAGE_SIZE")
  
  # 检查是否还有数据
  if [ $(echo $RESPONSE | jq length) -eq 0 ]; then
    break
  fi
  
  # 解析JSON并追加到CSV
  echo $RESPONSE | jq -r '.[] | [.project_id, .name, .public, .creation_time, .repo_count] | @csv' >> $OUTPUT
  
  PAGE=$((PAGE + 1))
done

echo "Projects exported to $OUTPUT"

企业级应用案例

CI/CD流水线集成

使用Harbor API实现镜像推送后的自动扫描与质量门禁：

mermaid

多仓库同步方案

通过API实现主从Harbor实例的双向同步，保障灾备能力：

mermaid

总结与进阶方向

本文详细介绍了Harbor API的核心能力，通过15个实用接口示例展示了从基础查询到高级自动化的完整流程。掌握这些接口可以帮助团队：

消除手动操作，降低人为错误
实现精细化权限管理与安全控制
构建端到端的DevSecOps流水线
满足合规管理与安全合规要求

进阶学习方向：

Harbor Swagger文档深入学习（访问/api/v2.0/swagger.json获取完整规范）
API速率限制与缓存策略优化
基于Webhook的实时事件处理
多租户环境下的API访问控制

通过API将Harbor深度集成到企业IT生态系统，是实现容器化转型的关键一步。建议从自动化镜像扫描、清理过期标签等高频场景入手，逐步构建完整的镜像生命周期管理体系。

相关资源

Harbor官方文档：https://goharbor.io/docs
API客户端生成工具：Swagger Codegen
监控模板：Prometheus + Grafana Harbor Dashboard

下期预告：《Harbor漏洞扫描API深度实战：从检测到修复的闭环自动化》

欢迎点赞收藏，关注获取更多容器技术自动化实践指南！

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考