Linux部署Harbor私有镜像仓库安装与证书配置教程

时间：2026-06-15 07:47

在部署Harbor私有镜像仓库并启用HTTPS时，许多用户常常遇到“安装脚本执行成功，但网页无法访问”或“docker login失败”等问题。实际上，这些问题的根本原因往往不在Harbor本身，而是由于几个前置依赖和配置细节未能严格对齐。本文将逐一解析这些常见陷阱，帮助您顺利部署。首先需要明确一

在部署Harbor私有镜像仓库并启用HTTPS时，许多用户常常遇到“安装脚本执行成功，但网页无法访问”或“docker login失败”等问题。实际上，这些问题的根本原因往往不在Harbor本身，而是由于几个前置依赖和配置细节未能严格对齐。本文将逐一解析这些常见陷阱，帮助您顺利部署。

linux环境下部署 harbor 私有镜像仓库详细安装与证书配置

首先需要明确一个关键前提：docker 版本必须 ≥ 20.10，docker compose 版本必须 ≥ 2.0.0，且 openssl 必须正常可用。这三项条件缺一不可，否则即使 ./install.sh 脚本执行完毕，Harbor 也很可能无法正常启动。请务必不要跳过验证步骤。

确认三个核心依赖是否就位

许多“安装成功但服务异常”的案例，本质上源于依赖版本不匹配。这并不是“版本稍低也能凑合”的问题，因为 Harbor v2.9 及以上版本已明确拒绝旧版 docker-compose（v1.x）以及低于 20.10 的 Docker 引擎。

具体如何核实？

Docker 版本：运行 docker --version，输出必须是 Docker version 20.10.x 或更高。如果显示的是 18.09 这类旧版本，后续执行 docker info 时很可能会报 failed to create endpoint 等错误。
Docker Compose 版本：请格外注意，此处指的是新版插件形式的 docker compose（中间无连字符）。运行 docker compose version，应输出类似 Docker Compose version v2.27.1。如果提示 command not found，说明系统里安装的仍是 Python 版的 docker-compose（v1），需要手动下载二进制文件并放到 /usr/local/bin/ 目录下。
OpenSSL 可用性：执行 which openssl，需返回有效路径。在 CentOS/RHEL 等系统的最小化安装中，openssl 包常被遗漏，只需运行 yum install -y openssl 即可补装。

离线安装包解压后必须改的三项配置

在正式运行 ./install.sh 之前，harbor.yml 配置文件中有三项配置必须修改，否则后续 docker login 失败或页面 502 错误几乎不可避免。

hostname：这里不能简单设为 localhost 或 127.0.0.1，必须填写客户端（包括浏览器和 Docker 客户端）能够解析的地址。例如服务器的 IP 地址 192.168.88.240，或者已配置的域名 harbor.example.com。关键原则：浏览器访问的 URL、docker login 时使用的地址、以及证书中的 CN 字段，这三者必须完全一致。
https 配置块：生产环境强烈建议启用 HTTPS。如果仅在测试环境使用 HTTP，需将 https: 及其下方所有配置行整段注释掉，并确保配置文件顶部有 https.enabled: false 的明确设置。同时，记得将 http.port 从默认的 80 端口改为其他端口（例如 8080），否则若宿主机 80 端口已被占用，Harbor 的 HTTP 服务将无法监听。
data_volume：默认数据目录为 /data。若系统盘空间紧张，建议调整至独立且空间充足的路径，如 /opt/harbor-data。修改后，务必执行 chown 10000:10000 /opt/harbor-data 命令，因为 Harbor 容器以 UID 10000 的用户运行，目录权限不当会导致 harbor-db 等核心组件无法启动。

自签名证书生成与挂载路径要严格匹配

这是 HTTPS 配置中最易出错的环节。Harbor 启动时会严格按照 harbor.yml 中 certificate 和 private_key 指定的路径读取证书文件。路径中多一个字符、文件权限不正确或证书 CN 与 hostname 不一致，都会直接导致 harbor-portal 服务无法响应，浏览器报 NET::ERR_CERT_COMMON_NAME_INVALID 错误。

具体需要注意以下几点：

证书主题（CN）必须匹配：生成证书时，-subj "/CN=xxx" 中的 xxx 必须和 harbor.yml 里的 hostname 一字不差。如果使用 IP 地址访问，还需要在生成命令中添加 -addext "subjectAltName = IP:192.168.88.240" 这样的扩展字段。
证书路径必须正确且可访问：证书文件路径必须是容器内可读的绝对路径，例如 /usr/local/harbor/tls/cert.crt。如果你把证书放在了 /root/tls/ 这类默认容器无权访问的目录，要么通过 volume 映射进容器，要么提前将证书文件移动到 Harbor 安装目录下。
私钥文件权限必须是 600：执行 chmod 600 tls/cert.key，将私钥文件权限设置为 600。如果权限不对，nginx 容器会在启动时拒绝加载私钥，日志中会出现 SSL_CTX_use_PrivateKey_file failed 的错误。

启动失败时优先查这三个日志位置

当通过 docker ps -a 发现容器状态为 Exited (1) 时，不必急于重装整个 Harbor。按以下顺序排查，通常能快速定位问题。

查看 harbor-core 日志：运行 docker logs harbor-core（注意不要加 -f，因为它已经退出了）。一个高频错误是 failed to connect to database: dial tcp 127.0.0.1:5432，这通常意味着 harbor-db 数据库容器没有成功启动。
检查 harbor-db 状态：运行 docker inspect harbor-db | grep -A 5 "Status"。如果显示 "ExitCode": 1，接着检查两个方向：一是磁盘空间是否充足（df -h /data），二是数据目录的权限是否正确（ls -ld /data/database 的属主必须是 10000）。
确认 harbor-portal 是否在监听端口：运行 ss -tlnp | grep ':80\|:443'，查看 80 或 443 端口是否有进程在监听。如果没有输出，很可能是防火墙挡住了，需要检查并放行相应端口：在 CentOS/RHEL 上使用 firewall-cmd --list-ports，在 Ubuntu 上使用 ufw status。