对于需要在内网环境中管理Docker镜像的团队而言，直接使用Docker Hub或公共镜像仓库往往存在网络不稳定、上传下载速度慢以及安全合规方面的隐患。Harbor作为一个企业级的开源镜像仓库，提供了完整的镜像存储、分发、权限控制和安全扫描能力，是目前私有镜像仓库部署的主流选择。它由VMware开源，基于Docker Distribution构建，并扩展了用户管理、项目管理、镜像复制、Web界面等实用功能。下面将详细介绍如何在一台Linux服务器上完成Harbor的部署与基础使用。
在正式安装之前，需要确认服务器满足最低硬件要求。官方建议至少2核CPU、4GB内存、40GB可用磁盘空间，如果计划存储大量镜像或启用漏洞扫描，内存和磁盘应适当增加。操作系统推荐使用Ubuntu 20.04/22.04或CentOS 7/8，并预先安装好Docker Engine和Docker Compose。可以通过下面的命令检查当前环境版本：
docker --version docker compose version
如果尚未安装Docker，请先根据官方文档完成安装。Harbor支持在线安装和离线安装两种方式：在线安装会从Docker Hub拉取所需镜像，适合网络较好的环境；离线安装包则包含了所有依赖的Docker镜像，适合内网隔离环境。安装包可以从Harbor的GitHub releases页面下载，解压后目录中会包含一个名为harbor.yml的配置文件模板，这是后续配置的核心文件。
部署前的环境准备
Harbor的组件由多个Docker容器协同工作，包括核心服务（core）、数据库（postgresql）、Redis、镜像存储后端（registry）、Web门户（portal）、任务调度（jobservice）以及日志收集（log）。在安装前需要规划好数据持久化目录，默认所有数据保存在安装目录下的data文件夹中，生产环境建议将其挂载到独立分区或网络存储，以防止容器重建时数据丢失。
防火墙需要放行Harbor使用的端口。默认情况下，HTTP端口为80，HTTPS端口为443，镜像仓库推送拉取使用的端口为5000。如果计划启用镜像复制或远程管理，还需要开放相应的管理端口。可以使用以下命令检查端口占用情况：
sudo netstat -tulpn | grep -E '80|443|5000'
此外，由于Harbor默认使用HTTP协议进行镜像传输，Docker守护进程会拒绝与不安全的仓库通信。因此，在生产环境中强烈建议为Harbor配置HTTPS证书，或者对于内网测试环境，可以在Docker客户端配置insecure-registries参数来跳过证书验证。但从安全角度考虑，正式使用应优先选择HTTPS方案。
安装与配置Harbor
下载并解压安装包后，首先进入解压目录，复制配置文件模板：cp harbor.yml.tmpl harbor.yml。然后使用文本编辑器打开harbor.yml，修改以下关键配置项：hostname填写服务器的IP地址或域名（不要使用localhost或127.0.0.1），http.port和https.port按需设置，harbor_admin_password设置管理员初始密码，data_volume指定数据存储路径。如果只使用HTTP，需要将https相关段落注释掉，并确保external_url正确指向访问地址。
# harbor.yml 关键配置示例 hostname: reg.ipipp.com http: port: 80 # https: # port: 443 # certificate: /your/certificate/path # private_key: /your/private/key/path harbor_admin_password: Harbor12345 data_volume: /data
完成配置后，运行安装脚本：sudo ./install.sh。该脚本会加载所需的Docker镜像，创建并启动所有Harbor容器，并初始化数据库结构。首次安装需要几分钟时间，可以通过docker compose ps查看容器状态，确保所有服务都处于Up状态。如果安装过程中出现错误，可以检查安装目录下的installation.log文件获取详细信息。
对于需要启用HTTPS的场景，可以在配置文件中指定证书和私钥路径，然后重新运行安装脚本。如果使用自签名证书，还需要将CA证书复制到各Docker客户端的/etc/docker/certs.d/<hostname>/目录下，并重启Docker服务。对于从Let's Encrypt等机构申请的正式证书，操作步骤相同，但无需在客户端额外配置。
使用Harbor管理镜像
安装完成后，在浏览器中访问http://<主机IP或域名>，使用管理员账号（默认用户名admin）和设置的密码登录Web管理界面。首次登录后，可以在“项目”菜单中创建新的项目，项目分为公开和私有两种类型。公开项目允许任何人拉取镜像，私有项目则需要登录并具备相应权限才能访问。管理员还可以在“用户管理”中创建其他用户，并通过“成员”功能将用户添加到项目中，分配开发者、访客或维护者等角色。
在Docker客户端上，首先需要使用docker login命令登录Harbor仓库：
docker login reg.ipipp.com # 输入用户名和密码
登录成功后，就可以推送本地镜像到Harbor。例如，将一个本地镜像myapp:latest打上仓库标签并推送：
docker tag myapp:latest reg.ipipp.com/projectname/myapp:latest docker push reg.ipipp.com/projectname/myapp:latest
拉取镜像时，同样使用完整的仓库地址：docker pull reg.ipipp.com/projectname/myapp:latest。Harbor支持Docker Registry HTTP API V2，因此可以使用任何兼容的客户端工具（如containerd、Podman）进行交互。
除了基本的推送拉取，Harbor还提供了镜像复制规则，可以将特定项目下的镜像自动同步到其他Harbor实例或远程仓库。这一功能在多机房部署或混合云场景中非常实用。管理员可以在“复制管理”中创建策略，设置触发条件（如定时、事件驱动）和目标远程仓库，实现镜像的异地冗余。
常见问题与性能优化
部署和使用Harbor过程中，有时会遇到502 Bad Gateway错误，通常是因为某些容器（如core或portal）未能正常启动。可以通过docker compose ps查看容器状态，并用docker logs <容器名>检查具体日志。另一个常见问题是镜像推送失败提示证书错误，此时需要确认Docker客户端是否正确信任了Harbor的CA证书，或者是否在daemon.json中配置了insecure-registries。
存储空间不足也是需要关注的问题。Harbor的镜像存储默认使用本地文件系统，当磁盘使用率过高时，需要及时清理无用的镜像标签或增加存储容量。可以在Web界面的“清理”功能中执行垃圾回收，释放无引用的层数据。对于大规模生产环境，建议将data_volume指向高性能的存储设备，或配置外部对象存储（如S3兼容存储）来存储镜像层，以提升读写性能和扩展性。
数据库性能也会影响Harbor的整体响应速度。默认的PostgreSQL容器配置较为保守，在高并发场景下可以调整postgresql容器的内存限制，并在postgresql.conf中增加共享缓冲区大小。此外，将Redis和数据库容器部署在独立的高性能节点上，或者使用外部托管服务，都能有效降低单机负载。对于需要高可用的团队，可以考虑多实例部署配合负载均衡器，并共享同一套外部数据库和存储，但这部分超出了单机部署的范畴，需要更详细的架构设计。
Harbor镜像仓库Docker镜像管理私有镜像仓库部署修改时间：2026-09-27 20:29:12