Harbor私有镜像仓库部署及使用教程

一、引言

在微服务架构与分布式部署成为主流的今天，Docker镜像的高效管理与安全分发已成为企业DevOps流程中的核心环节。Harbor是一个开源的企业级容器镜像仓库服务，用于安全地存储、分发和管理Docker容器镜像、Helm Chart等符合OCI标准的制品。它最初由VMware于2014年开发，2016年开源，2018年成为CNCF（云原生计算基金会）沙箱项目，并于2020年6月正式成为CNCF毕业项目。它在Docker Registry的基础上，增加了RBAC权限控制、Trivy镜像漏洞扫描、Cosign/Notary镜像签名、跨仓库镜像复制、审计日志等企业级功能。本教程主要面向企业内网环境下的Harbor私有镜像仓库部署和使用需求，涵盖从离线安装到基础应用的完整实践路径。

二、安装部署

2.1 下载离线包

内网环境下需要下载离线安装包完成Harbor安装。对于amd64（x86）架构，直接从Harbor官网下载最新版离线安装包（Assets）；对于ARM64架构，使用如下命令下载V2.10.2版本的AARCH64离线安装包：

# 下载离线镜像包dockerpull alanpeng/harbor_images_aarch64:v2.10.2# 创建一个新的容器实例TEMP_CONTAINER_ID=$(dockercreate alanpeng/harbor_images_aarch64:v2.10.2 /bin/true)# 从容器中拷贝文件dockercp$TEMP_CONTAINER_ID:/harbor-offline-installer-aarch64.tgz ./harbor-offline-installer-aarch64.tgz# 删除容器实例dockerrm$TEMP_CONTAINER_ID

2.2 执行安装

解压离线包并创建配置文件。

tarzxf harbor-offline-installer-aarch64.tgzcdharborcpharbor.yml.tmpl harbor.yml

修改配置文件harbor.yml：

vimharbor.yml

常用配置项如下：

# The IP address or hostname to access admin UI and registry service.# DO NOT use localhost or 127.0.0.1, because Harbor needs to be accessed by external clients.hostname:<hostname># Harbor部署服务器IP# http related confighttp:# port for http, default is 80. If https enabled, this port will redirect to https portport:<port># https related config# 内网环境下通常使用HTTP协议即可，因此可以注释或删除HTTPS相关内容# https:# https port for harbor, default is 443# port: 443# The path of cert and key files for nginx# certificate: /your/certificate/path# private_key: /your/private/key/path# enable strong ssl ciphers (default: false)# strong_ssl_ciphers: false# The initial password of Harbor admin# It only works in first time to install harbor# Remember Change the admin password from UI after launching Harbor.harbor_admin_password:<admin_password># 默认为Harbor12345

配置完成后，执行安装脚本：

sudo./install.sh

安装过程会自动加载离线镜像并启动所有服务。详细安装流程及完整配置说明可参考官方文档。

三、Web管理

3.1 创建项目

打开浏览器，登录http://<hostname>:<port>进入Harbor Web UI，用户名为admin，初始密码为配置文件中设置的<admin_password>（默认为Harbor12345）。

点击"新建项目"，填写项目名称，选择访问级别。

3.2 管理用户

Harbor默认自带一个超级管理员admin，如果有多用户需求，则需要先创建用户。创建用户以后，就可以将用户添加到具体项目中，实现权限控制，默认的超级管理员是所有项目的项目管理员。

点击 “用户管理”，创建新用户。

选择一个项目，在成员界面将用户添加进该项目，并设置角色权限。

角色权限说明如下：

四、镜像推送与拉取

4.1 配置本地Docker客户端

若Harbor使用HTTPS协议，可跳过此步；若使用HTTP协议，由于Docker默认要求仓库使用HTTPS，需要配置Docker信任该Harbor仓库，否则Docker客户端会拒绝连接。

对于Linux系统，创建或修改/etc/docker/daemon.json文件；对于Windows或Mac系统，创建或修改~/.docker/daemon.json文件。修改内容如下：

{"insecure-registries":["<hostname>:<port>"]}

修改配置文件后，需重启Docker客户端才能生效。Linux系统执行如下命令（现有运行中容器不会受影响）：

systemctl reloaddocker

Windows或Mac系统直接重启Docker Desktop。

执行如下命令检查配置是否生效：

dockerinfo|grep-A5"Insecure Registries"

若输出内容中包含<hostname>:<port>则说明配置已生效。

4.2 登录Harbor

dockerlogin<hostname>:<port>-u<username>-p<password>

输出Login Succeeded表示成功。上述命令会将密码保存在 ~/.docker/config.json 中，生产环境建议使用docker login --password-stdin或配置凭证助手。

4.3 推送镜像到Harbor

# 给本地镜像打标签dockertag<image>:<image_tag><hostname>:<port>/<harbor_project>/<image>:<image_tag># 推送镜像dockerpush<hostname>:<port>/<harbor_project>/<image>:<image_tag>

登录Harbor Web UI，进入项目即可查看已推送的镜像。

4.4 从Harbor拉取镜像

dockerpull<hostname>:<port>/<harbor_project>/<image>:<image_tag>

五、镜像复制与同步

Harbor支持跨仓库镜像复制与同步，首先配置好远程仓库地址和对应的匹配规则，然后就可以把本地仓库镜像同步到远程仓库，实现镜像备份和高可用功能。

5.1 添加目标仓库

点击 “仓库管理” → “新建目标”，选择提供商（Harbor/Docker Hub/AWS ECR/阿里云ACR等），填写目标地址和访问凭证。

5.2 创建复制规则

点击"复制管理" → “新建规则”。

各配置项说明如下：

六、总结

Harbor是一个企业级镜像仓库管理服务，在安全性、可管理性和扩展性上为微服务容器化交付提供了坚实底座。本教程面向内网离线部署业务场景，覆盖了从安装包获取、HTTP配置、Web项目与用户管理，到镜像推送拉取及跨仓库同步的日常运维操作链路。Harbor的功能远不止于此，还包括漏洞扫描、代理缓存等高级应用，值得深入学习和探索。

参考文献

[1] https://goharbor.io/docs/2.15.0/install-config
[2] https://github.com/mgl-pub/build-harbor-aarch64
[3] https://cloud.tencent.com/developer/article/2474843
[4] https://blog.csdn.net/sinat_17584329/article/details/159171648
[5] https://ask.csdn.net/questions/9760180