GitHub_Trending/ha/harbor-helm镜像仓库API文档：开发集成指南
项目地址: https://gitcode.com/GitHub_Trending/ha/harbor-helm Harbor是一个开源可信云原生镜像仓库（Registry），支持镜像存储、签名和扫描功能。通过GitHub_Trending/ha/harbor-helm项目提供的Helm Chart，可快速部署Harbor服务并通过API与开发流程集成。本文档将详细介绍Harbor API的核心功能、认证方式及开发集成示例，帮助开发者高效对接镜像仓库服务。
核心API端点与服务配置
Harbor的API服务由Core组件提供，默认通过8080端口（HTTP）或8443端口（HTTPS）暴露。从配置文件可知，API相关核心参数如下：
- 基础URL：由
EXT_ENDPOINT参数定义，通常配置为Ingress域名（如https://harbor.example.com） - 认证服务：Token服务地址通过
TOKEN_SERVICE_URL指定，默认指向Core组件内部端点 - 仓库控制器：Registry Controller URL通过
REGISTRY_CONTROLLER_URL配置，用于管理镜像存储
核心服务配置示例：
# 来自templates/core/core-cm.yaml的API相关配置
EXT_ENDPOINT: "https://harbor.example.com"
CORE_URL: "http://harbor-core:8080"
TOKEN_SERVICE_URL: "http://harbor-core:8080/service/token"
REGISTRY_CONTROLLER_URL: "http://harbor-registryctl:8080"
API认证机制
Harbor API采用基于令牌（Token）的认证方式，开发集成需先通过凭证获取访问令牌。认证流程如下：
-
获取令牌：向
/service/token端点发送凭证请求curl "https://harbor.example.com/service/token?service=harbor-registry&scope=repository:library/hello-world:pull,push" \ -u "admin:Harbor12345" -
使用令牌：在API请求头中携带令牌
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \ "https://harbor.example.com/api/v2.0/projects"
安全说明：生产环境必须启用HTTPS（通过
internalTLS.enabled配置），避免凭证明文传输。相关TLS配置可参考安全配置文件。
镜像仓库操作API
项目管理
Harbor通过项目（Project） 组织镜像资源，支持创建私有/公共项目及权限控制：
# 创建私有项目
curl -X POST "https://harbor.example.com/api/v2.0/projects" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"project_name":"my-project","public":false}'
镜像上传与拉取
镜像操作需遵循Docker Registry V2 API规范，结合Harbor认证机制实现：
-
上传镜像：
# 标记本地镜像 docker tag my-app:v1 harbor.example.com/my-project/my-app:v1 # 登录并推送（底层调用Harbor API） docker login harbor.example.com -u admin -p Harbor12345 docker push harbor.example.com/my-project/my-app:v1 -
API查询镜像标签：
curl "https://harbor.example.com/api/v2.0/projects/my-project/repositories/my-app/artifacts" \ -H "Authorization: Bearer {token}"
扫描与安全检查
Harbor集成Trivy漏洞扫描器，可通过API触发镜像安全检查：
# 触发镜像扫描
curl -X POST "https://harbor.example.com/api/v2.0/projects/my-project/repositories/my-app/artifacts/v1/scan" \
-H "Authorization: Bearer {token}"
扫描结果可通过/artifacts/{reference}/additions/vulnerabilities端点获取，支持集成到CI/CD pipeline实现自动拦截风险镜像。
高可用部署与API稳定性
为确保API服务稳定，Harbor支持多副本部署架构。如高可用文档所述，关键配置包括：
- 核心组件副本数设置（
core.replicas: 2） - 共享存储配置（
persistence.imageChartStorage.type: s3） - 外部Redis集群用于缓存与会话共享
部署命令示例：
helm install harbor . \
--set core.replicas=2 \
--set registry.replicas=2 \
--set persistence.imageChartStorage.type=s3 \
--set externalURL=https://harbor.example.com
开发集成最佳实践
CI/CD流水线集成
在Jenkins或GitHub Actions中集成Harbor API，实现自动镜像推送：
// Jenkins Pipeline示例
stage('Push to Harbor') {
steps {
script {
dockerImage = docker.image('my-app:v1')
dockerImage.push()
// 调用API创建标签
sh '''
curl -X POST "https://harbor.example.com/api/v2.0/projects/my-project/repositories/my-app/artifacts/v1/tags" \
-H "Authorization: Bearer $HARBOR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"latest"}'
'''
}
}
}
错误处理与重试机制
API调用需处理常见错误场景：
- 401 Unauthorized：令牌过期，需重新获取
- 409 Conflict：项目已存在，可忽略或更新现有配置
- 503 Service Unavailable：服务暂时不可用，建议实现指数退避重试
附录：API文档与资源
- 官方API文档：完整接口定义可通过部署后的Harbor门户访问（
https://harbor.example.com/api/v2.0） - 配置文件参考：
- ** Helm Chart参数**：values.yaml包含所有可配置API相关参数
通过上述指南，开发者可快速实现与Harbor镜像仓库的API集成，构建安全可控的容器镜像管理流程。如需进一步定制，可参考项目贡献指南提交改进建议。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
