Linux安装Harbor企业级镜像仓库与Docker私有化部署详解

搞定Harbor的安装部署，很多时候并不在于你下载的安装包版本有多新，而在于三个最基础的依赖组件是否真正配置到位。如果docker、docker compose或者openssl其中任何一个出了问题，那么./install.sh脚本要么会静默失败，要么就会陷入容器反复重启又退出的死循环中。

检查并安装 Harbor 的三个硬性依赖

很多所谓的“安装失败”，其实问题根源都在依赖环节，而不是后续的配置细节。这一步必须逐一排查，不能跳过：

• Docker版本：运行docker --version，确保版本不低于20.10。如果还停留在旧版（比如18.09），很可能会在后续遇到failed to create endpoint这类网络异常。
• Docker Compose版本：这里有个关键点，需要使用的是docker compose（即Compose V2），而不是旧的docker-compose（V1）。运行docker compose version，版本需≥2.0.0。如果提示命令未找到，通常需要前往GitHub releases页面下载对应的二进制文件，然后放到/usr/local/bin/目录下。
• OpenSSL：运行which openssl，必须有输出路径。在一些最小化安装的CentOS或RHEL系统上，这个包可能默认没有安装，用yum install -y openssl补上即可。

离线安装时 harbor.yml 的三处必改项

解压离线安装包后，里面的harbor.yml配置文件可不能直接拿来就用。有三个地方必须根据你的实际环境进行调整，错一个都可能导致登录失败或者无法访问：

• hostname：这个值必须设置为客户端（也就是未来要执行docker login和docker push的机器）能够解析的地址。可以是域名（如harbor.example.com），也可以是宿主机的真实IP地址（如192.168.10.50）。切记不要写成localhost或127.0.0.1，否则从其他机器登录时会直接报unauthorized: authentication required。
• HTTPS配置：如果只是测试环境，不打算启用HTTPS，那么需要将配置文件中整个https:配置块注释掉。同时，确保顶层的https.enabled设置为false，并为HTTP服务指定一个端口，比如http.port: 8080（避免与系统80端口冲突）。
• 数据卷路径：默认的数据存储路径是/data。对于生产环境，建议将其修改到一个独立的、空间充足的路径，例如/opt/harbor-data。修改后，必须提前执行chown 10000:10000 /opt/harbor-data，因为Harbor内部的容器进程是以UID 10000的用户运行的，没有这个权限，后续服务会因无法写入数据而启动失败。

容器启动后立即退出？先看 harbor-db 日志

执行完./install.sh后，如果发现docker ps -a列表里的harbor-core或者harbor-jobservice等容器状态是Exited (1)，先别急着重新安装整个Harbor。这时候，十有八九是数据库容器harbor-db没有启动，拖垮了所有依赖它的服务。

• 可以运行docker inspect harbor-db | grep -A 5 "Status"来确认，如果输出中包含"ExitCode": 1，那基本就是它的问题。
• 导致harbor-db启动失败最常见的原因有两个：一是磁盘空间不足（尤其是/data/database所在的分区）；二是/data/database目录的权限设置不正确。解决方法是检查磁盘空间，并确保对该目录执行chown -R 10000:10000 /data/database。
• 还有一种情况，所有容器都显示running，但用浏览器就是打不开http://your-host:8080。这时候别忘了检查宿主机的防火墙，运行firewall-cmd --list-ports看看是否放行了你在harbor.yml里配置的那个http.port端口。

客户端 push 镜像报 x509 certificate signed by unknown authority

这是在启用HTTPS后，客户端推送镜像时最常遇到的错误。问题不在Harbor服务器端，而在于客户端的Docker守护进程不信任Harbor所使用的自签名证书。

• 如果你使用的是Harbor自动生成的证书（即没有配置自己的CA证书），那么需要将Harbor服务器上生成的harbor.crt文件（通常位于common/config/registry/目录下）拷贝到客户端机器的一个特定目录。
• 这个目录路径必须严格匹配Harbor的访问地址和端口。例如，如果你的hostname设为harbor.example.com，https.port是443，那么客户端就需要创建目录/etc/docker/certs.d/harbor.example.com/，并将harbor.crt证书文件放入其中。
• 完成拷贝后，记得在客户端重启Docker服务（systemctl restart docker），否则新的证书不会被加载。

总的来说，Harbor安装的复杂性并不在于步骤繁多，而在于它的各个核心组件（数据库、Redis、镜像仓库、核心服务）都以容器方式运行，彼此之间存在严格的启动顺序和权限依赖。实践经验表明，最容易出问题的地方，往往就是data_volume数据目录的属主设置，以及harbor-db这个基础数据库的启动状态——只要这两关过了，剩下的服务大概率都能顺利跑起来。