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这个基础数据库的启动状态——只要这两关通过，剩余服务大概率都能顺利运行。