Harbor私有镜像仓库部署实战：安装、配置与排错指南

为什么要部署自己的Harbor镜像仓库

在公司或团队开发中，频繁从Docker Hub拉取镜像不仅慢，还容易触发限流。
Harbor作为一款开源的私有镜像仓库，提供了安全认证、镜像复制、漏洞扫描等功能，让镜像管理更规范。
本文针对零基础用户，一步步演示如何在Linux服务器上部署Harbor，并完成镜像的上传和下载。

部署前的环境要求

在开始之前，你需要准备以下条件：

• 一台Linux服务器（推荐Ubuntu 20.04+或CentOS 7+，2核4GB以上配置，磁盘建议50GB以上）。
• 已安装Docker（版本19.03.0+）和Docker Compose（版本1.29.0+）。
• 域名或IP：如果计划通过域名访问，还需要一个已解析的域名；也可以直接使用服务器IP。
• SSL证书（可选但强烈建议）：生产环境必须使用HTTPS，否则浏览器会报不安全。自签名证书也可以用于测试。

如果还没安装Docker和Docker Compose，可先执行以下命令快速安装（Ubuntu）：
`bash
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
`

下载并解压Harbor安装包

1. 访问Harbor的GitHub Releases页面（https://github.com/goharbor/harbor/releases），选择最新稳定版，复制离线安装包下载链接。例如v2.10.0：

   wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz

1. 解压到指定目录（例如/opt）：

   sudo tar -xzvf harbor-offline-installer-v2.10.0.tgz -C /opt
   cd /opt/harbor

修改配置文件并安装Harbor

1. 复制配置模板：

   cp harbor.yml.tmpl harbor.yml

1. 编辑harbor.yml，主要修改以下部分：

• hostname：改成你的域名或IP，例如hostname: 192.168.1.100。
• https相关：如果使用自签名证书，需先创建证书目录并生成证书；如果只想用HTTP测试，可以直接注释掉https区块（不建议用于生产）。
• harbor_admin_password：设置Harbor管理员初始密码（默认是Harbor12345，建议修改）。

示例（仅HTTP测试，生产请务必启用HTTPS）：

   hostname: 192.168.1.100
   http:
     port: 80
   # https:
   #   port: 443
   #   certificate: /your/cert.pem
   #   private_key: /your/key.pem
   harbor_admin_password: MyStrongPass123

1. 执行安装脚本：

   sudo ./install.sh

安装过程会拉取Harbor组件镜像并启动容器，等待几分钟即可。

1. 安装成功后访问http://你的服务器IP，使用管理员账号admin和设置的密码登录。

避坑指南：安装中常见问题

• 端口冲突：Harbor默认使用80和443端口。如果服务器已有Nginx或Apache占用，需要修改harbor.yml中的http.port或关闭冲突服务。
• 磁盘空间不足：Harbor会存储大量镜像数据，默认数据目录在/data，请确保该分区有足够空间。可通过软链接或修改data_volume配置项迁移。
• Docker Compose版本过低：运行docker-compose --version检查，如果低于1.29，请升级。否则安装脚本会报错。
• 证书错误：如果使用自签名证书并在客户端拉取镜像，需要把CA证书添加到客户端的信任列表中。例如Linux下复制到/etc/docker/certs.d/你的域名/目录。
• 安装后容器未全部启动：执行docker-compose ps查看状态，如果有Exited的容器，查看日志进行排查，例如docker logs <容器名>。

验证私有镜像仓库是否正常

1. 在本地Docker客户端登录Harbor：

   docker login 192.168.1.100

输入用户名admin和密码，登录成功会显示Login Succeeded。

1. 打标签并推送镜像：

   docker pull nginx:latest
   docker tag nginx:latest 192.168.1.100/library/nginx:latest
   docker push 192.168.1.100/library/nginx:latest

推送成功后，在Harbor Web界面切换到library项目，就能看到上传的镜像。

1. 从Harbor拉取镜像：到其他机器上登录Harbor，执行：

   docker pull 192.168.1.100/library/nginx:latest

只要网络互通，就能成功拉取。

常见问题解答（FAQ）

Q：Harbor启动后访问页面报502怎么办？
A：通常是因为Nginx容器未启动，执行docker-compose ps查看状态，然后重启Harbor：docker-compose down && docker-compose up -d。

Q：如何开启Harbor的HTTPS？
A：建议使用Let's Encrypt免费证书，将证书文件放在指定目录，并在harbor.yml的https段配置路径，然后重新执行./install.sh（注意会重建容器）。

Q：可以修改Harbor的数据存储路径吗？
A：可以。在harbor.yml中修改data_volume字段，例如data_volume: /mnt/harbor_data，然后重启。

如果你在部署过程中遇到其他卡点，欢迎在评论区留言。
掌握Harbor私有镜像仓库后，你可以进一步探索镜像复制规则、垃圾清理、RBAC权限等高级功能，让镜像管理更高效。