Linux部署Harbor及证书配置教程

本文详细解析了在Linux系统上成功部署Harbor镜像仓库的关键要点与常见陷阱，重点强调三大硬性依赖（Docker ≥20.10、Docker Compose ≥2.0.0、OpenSSL可用）缺一不可，明确指出版本不兼容是“安装成功却无法访问”的根本原因；同时深入剖析harbor.yml中hostname、HTTPS配置与data_volume三项必改项，以及自签名证书生成时CN一致性、SAN扩展、路径映射和私钥600权限等极易被忽视的细节，并提供精准的日志排查路径——从harbor-core连接数据库失败，到harbor-db退出码分析，再到harbor-portal端口监听与防火墙验证，层层递进帮你避开90%的启动崩溃问题，堪称Harbor生产级部署避坑指南。

docker 必须 ≥ 20.10，docker compose 必须 ≥ 2.0.0，openssl 必须可用——这三个条件不满足，./install.sh 即使跑完也大概率启动失败，别跳过验证。

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

很多人卡在“安装成功但打不开网页”，实际是依赖没对齐。不是版本略低一点能凑合，而是 Harbor v2.9+ 明确拒绝旧版 docker-compose（v1.x）和低于 20.10 的 docker。

• docker --version 输出必须是 Docker version 20.10.x 或更高；若为 18.09，运行 docker info 可能报 failed to create endpoint
• docker compose version（注意：无连字符）必须输出类似 Docker Compose version v2.27.1；若提示 command not found，说明系统装的是 Python 版 docker-compose（v1），需手动下载二进制并放到 /usr/local/bin/
• which openssl 必须返回路径；CentOS/RHEL 最小化安装常漏掉 openssl 包，yum install -y openssl 补上即可

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

直接运行 ./install.sh 前，harbor.yml 里这三处不改，后续必然 docker login 失败或页面 502。

• hostname：不能写 localhost 或 127.0.0.1，必须填客户端能解析的地址，比如 192.168.88.240 或 harbor.example.com；浏览器访问 URL、docker login 地址、证书 CN 字段三者必须一致
• https 块：生产环境必须启用；测试环境若想用 HTTP，得整段注释掉 https: 及其下所有行，并确保顶部有 https.enabled: false，同时把 http.port 改成非 80 端口（如 8080），否则宿主机 80 被占但 Harbor 不监听
• data_volume：默认 /data，若系统盘小，建议改成独立路径如 /opt/harbor-data，且执行 chown 10000:10000 /opt/harbor-data（Harbor 容器以 UID 10000 运行，权限不对会导致 harbor-db 启动失败）

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

Harbor 启动时会读取 certificate 和 private_key 指定路径下的文件，路径错一个字符、权限不对、或证书 CN 与 hostname 不一致，都会导致 harbor-portal 无法响应或浏览器报 NET::ERR_CERT_COMMON_NAME_INVALID。

• 证书生成命令中 -subj "/CN=xxx" 的 xxx 必须和 harbor.yml 中 hostname 完全相同；若用 IP 访问，还得加 -addext "subjectAltName = IP:192.168.88.240"
• 证书文件路径必须是容器内可读的绝对路径，例如 /usr/local/harbor/tls/cert.crt；如果放在 /root/tls/，Harbor 容器默认无权访问，得用 volume 映射或提前移到 harbor/ 目录下
• 私钥文件权限必须是 600（chmod 600 tls/cert.key），否则 nginx 容器启动时拒绝加载，日志里会出现 SSL_CTX_use_PrivateKey_file failed

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

别一看到 docker ps -a 里有 Exited (1) 就重装，先定位真实错误点。

• 查 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'；若没输出，检查防火墙：firewall-cmd --list-ports（CentOS/RHEL）或 ufw status（Ubuntu），确保对应端口已放行

证书路径、hostname、UID 权限这三点，改错任意一个都可能让 Harbor 启动后立即崩溃，而且错误日志分散在不同容器里，容易误判。动手前务必逐行核对。

终于介绍完啦！小伙伴们，这篇关于《Linux部署Harbor及证书配置教程》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！