Harbor部署需严格匹配Docker（≥24.0.7）、Docker Compose（≥2.24.5，非docker-compose v1.x）和OpenSSL；hostname必须可DNS解析，HTTPS配置须完整且证书路径为绝对路径、属主为UID 10000；/data目录权限错误、防火墙未放行端口、客户端未信任CA证书是三大静默失败主因。
Harbor 不是“装个包就完事”的服务，它依赖 Docker、Docker Compose 和 OpenSSL 三者严格匹配，缺一不可；任何一项版本不兼容或权限配置错位，都会导致 harbor-core 退出、harbor-db 启动失败或客户端 docker login 报 unauthorized: authentication required。
确认 docker 和 docker compose 版本是否满足最低要求
Harbor v2.10+ 要求 docker --version ≥ 24.0.7（或至少 20.10），且 docker compose version（注意无连字符）必须 ≥ 2.24.5。很多失败源于误用旧版 docker-compose（v1.x）或系统自带的低版本 docker.io（Ubuntu）。
- 运行
docker --version和docker compose version验证 —— 若后者报command not found，说明没装对，得手动下载二进制 - CentOS/RHEL 用户别用
yum install docker-compose，那装的是 Python 版 v1.x，和 Harbor 不兼容 - Ubuntu 用户慎用
apt install docker.io，它默认是 20.10 以下旧版；建议用官方 repo 安装docker-ce -
openssl必须存在：运行which openssl，若为空，yum install -y openssl或apt install -y openssl
修改 harbor.yml 时 hostname 和 https 是两个致命坑
hostname 写成 localhost 或 127.0.0.1，会导致所有客户端 docker login 失败；而 HTTPS 配置不完整，会直接让 install.sh 启动后全部容器反复退出。
-
hostname必须设为客户端能 DNS 解析的值，比如harbor.example.com或宿主机真实 IP（如192.168.10.100） - 若仅测试，禁用 HTTPS：注释掉整个
https:块，并确保http.port不是 80（避免端口冲突），例如设为8080 - 启用 HTTPS 时，
certificate和private_key路径必须绝对路径，且文件属主需为 UID 10000（Harbor 容器运行用户），否则harbor-nginx启动失败 -
data_volume默认是/data，若系统盘小，务必提前改到大分区（如/opt/harbor-data），并执行chown 10000:10000 /opt/harbor-data
启动失败时优先查 harbor-db 和防火墙
执行 ./install.sh 后，docker ps -a 显示 harbor-core 或 harbor-jobservice 状态为 Exited (1)，90% 是数据库没起来，不是配置写错了。
- 先看
harbor-db容器日志：docker logs harbor-db—— 常见错误是initdb: could not change permissions of directory "/var/lib/postgresql/data": Permission denied，说明/data/database目录权限不对 - 检查
harbor-db容器状态：docker inspect harbor-db | grep -A 5 "Status"，若"ExitCode": 1，大概率是磁盘满或目录属主非 10000 -
harbor-portal能 ping 通但打不开页面？检查宿主机防火墙：firewall-cmd --list-ports（CentOS）或ufw status（Ubuntu），确认http.port或https.port已放行 - 别急着重装：删容器前先备份
/data下的database和redis目录，重装后可复用
客户端 push 镜像前必须信任证书或禁用校验
用自签名证书部署 HTTPS Harbor 后，docker push 会报 x509: certificate signed by unknown authority —— 这不是 Harbor 没跑起来，而是 Docker 客户端根本不认你的 CA。
- 若用自签名证书，必须把
ca.crt（生成时的根证书）拷到客户端/etc/docker/certs.d/<hostname>:443/ca.crt，路径名必须和hostname+ 端口完全一致 - Ubuntu/Debian 客户端还需运行
update-ca-certificates刷新系统证书库 - 开发测试环境可临时绕过：在客户端 Docker 配置中加
"insecure-registries": ["<hostname>:443"]到/etc/docker/daemon.json，然后systemctl restart docker - 注意：HTTP 模式下，
insecure-registries填的是hostname:port（如"192.168.10.100:8080"），不是域名加端口组合
真正卡住人的从来不是“怎么装”，而是 hostname 解析失败、ca.crt 放错路径、/data/database 权限不对这三处 —— 它们不会报错在控制台，只会让容器静默退出。每次改完配置，先 docker-compose down -v 清干净再重试，比反复调 install.sh 更省时间。
