Ubuntu 22.04 安装 Harbor 指南

在 Ubuntu 22.04 上通过官方离线安装器与在线安装器两种方式部署 Harbor 2.15.4，完成自签 HTTPS、harbor.yml 配置、服务组件编排托管与验证，并给出安装失败排障细节

HarborHarborDevOps制品管理2026/10/10

Ubuntu 22.04 安装 Harbor 指南

目标：在 Ubuntu 22.04 上通过「官方离线安装器（harbor-offline-installer）」与「官方在线安装器（harbor-online-installer）」两种方式部署 Harbor 2.15.4，完成自签 HTTPS 证书、harbor.yml 配置、Harbor 平台服务组件的编排托管与功能验证，并沉淀安装过程中的排障细节。本文已在 Ubuntu 22.04 真实环境实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS
  • 系统架构：x86_64
  • 内核版本：6.2.0-060200-generic
  • 包管理器：apt（apt-get）
  • Harbor 版本：2.15.4（当前最新稳定版）
  • 安装方式：方案 A 官方离线安装器（harbor-offline-installer）、方案 B 官方在线安装器（harbor-online-installer）
  • 服务编排：docker compose（Compose v5.5.1 插件），Harbor 各功能作为平台服务组件由 Compose 统一编排托管
  • 数据目录：/opt/data/harbor（数据库/制品存储/证书等全部落盘于此）
  • 监听端口：HTTPS 443；HTTP 80 自动 301 跳转 HTTPS
  • 管理账号：admin ／ 密码 q1w2e3r4
  • 服务器地址：172.17.0.63（示例内网 IP，请替换为你的实际服务器地址）
  • 组件镜像：goharbor/*:v2.15.4（prepare/core/portal/jobservice/registry/nginx 等）与 goharbor/valkey-photon:v2.15.4

二、前置条件

  • 拥有 root 权限或 sudo 权限

  • 已安装 Docker Engine（>= 20.10.10）与 Compose 插件（docker compose version 可用）

  • 已完善校验 Docker 与 Compose：

    docker --version
docker compose version

    实测输出：

    Docker version 29.8.1, build 4a63305
Docker Compose version v5.5.1

  • 已有足够的磁盘空间：离线安装器约 713 MB，安装后 Harbor 各组件镜像约占 1.5 GB，再加数据目录预留

  • 已规划数据目录（建议放独立数据盘，本部署使用 /opt/data/harbor）

  • 网络可访问 GitHub Releases 下载安装器（在线方案 B 还需能访问 docker.io 拉取组件镜像）

⚠️ 注意：Harbor 的 hostname 禁止使用 localhost 或 127.0.0.1，否则外部客户端无法通过该地址访问控制台与访问注册表接口。

三、版本选型说明

来源版本类型特点
Harbor 官方离线安装器（harbor-offline-installer-v2.15.4.tgz）2.15.4稳定版内嵌全部组件镜像 tar，安装时本地加载，适合内网/弱网；本文方案 A
Harbor 官方在线安装器（harbor-online-installer-v2.15.4.tgz）2.15.4稳定版安装时从 docker.io 在线拉取组件镜像，包体小（仅几 MB），适合可联网环境；本文方案 B
源码编译构建自定义开发版从 GitHub 拉源码 make 构建，适合二次开发，生产不推荐

💡 说明：Harbor 的离线/在线安装器版本号一致，二者本质区别在于「组件镜像」是打包进安装器（离线）还是安装时在线拉取（在线）。当前稳定版为 2.15.4，版本可随时在 GitHub Releases 页（见参考链接）按需选择。

四、方案 A：官方离线安装器部署

4.1 创建数据目录与解压目录

mkdir -p /opt/data/harbor
mkdir -p /opt/harbor-installer

💡 说明：/opt/data/harbor 为 Harbor 数据目录（后续 harbor.yml 的 data_volume 即指向它）；/opt/harbor-installer 用于存放并解压安装器。

4.2 下载官方离线安装器

从 GitHub Releases 下载离线安装器（体积约 713 MB）。国内网络直连 GitHub 较慢时，可改用 GitHub 加速代理（ghfast.top）兜底：

cd /opt/harbor-installer
wget https://github.com/goharbor/harbor/releases/download/v2.15.4/harbor-offline-installer-v2.15.4.tgz

实测输出（使用 curl + 加速源，节选）：

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  713M  100  713M    0     0  10.0M      0  0:01:13  0:01:11 --:--:-- 10.0M

⚠️ 排障（实测）：直连 github.com 下载时速度可能只有 200~300 KB/s，且偶发 0 字节卡住。改用加速源后恢复到 10 MB/s：

curl -L -o harbor-offline-installer-v2.15.4.tgz \
  https://ghfast.top/https://github.com/goharbor/harbor/releases/download/v2.15.4/harbor-offline-installer-v2.15.4.tgz

4.3 校验与解压

cd /opt/harbor-installer
sha256sum harbor-offline-installer-v2.15.4.tgz
tar xzf harbor-offline-installer-v2.15.4.tgz
cd harbor
ls -l

实测输出（解压后的目录内容）：

total 734852
-rw-r--r-- 1 root root     11347 Oct  8 08:53 LICENSE
-rw-r--r-- 1 root root      3646 Oct  8 08:53 common.sh
-rw-r--r-- 1 root root 752436879 Oct  8 08:53 harbor.v2.15.4.tar.gz
-rw-r--r-- 1 root root     15379 Oct  8 08:53 harbor.yml.tmpl
-rwxr-xr-x 1 root root      1975 Oct  8 08:53 install.sh
-rwxr-xr-x 1 root root      2211 Oct  8 08:53 prepare

💡 说明：解压后可见 harbor.v2.15.4.tar.gz（内嵌全部组件镜像）、harbor.yml.tmpl（配置模板）、install.sh（安装脚本）、prepare（配置生成器）与 common.sh（公共函数库）。HTTPS 自签证书、harbor.yml 的修改在 4.4 / 4.5 完成后再执行 install.sh。

4.4 生成自签 HTTPS 证书

Harbor 的 HTTPS 由前置反向代理组件（nginx）终结，需要服务端证书（server.crt/server.key）与用于签发它的证书中心（CA）证书（ca.crt）。以下用 openssl 生成并放置到数据目录 /opt/data/harbor：

第一步：生成 CA 私钥与自签 CA 证书

cd /opt/data/harbor
openssl req -newkey rsa:4096 -nodes -keyout ca.key -x509 -days 365 \
  -subj "/CN=harbor-ca" -out ca.crt

实测输出：

.+..+............+....+.....+.......+.....+...+....+......+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*.+...
-----

第二步：生成服务端私钥与证书签名请求（CSR）

openssl genrsa -out server.key 4096
openssl req -new -key server.key -out server.csr -subj "/CN=172.17.0.63"

第三步：生成扩展文件并签发服务端证书

cat > ext.cnf <<'EOF'
[ v3_req ]
subjectAltName = IP:172.17.0.63
extendedKeyUsage = serverAuth
EOF
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -days 365 -out server.crt -extensions v3_req -extfile ext.cnf

实测输出：

Certificate request self-signature ok
subject=CN = 172.17.0.63

第四步：校验证书的 SAN（必须包含服务器 IP）

openssl x509 -in /opt/data/harbor/server.crt -noout -text | grep -A1 "Subject Alternative Name"

实测输出：

            X509v3 Subject Alternative Name:
                IP Address:172.17.0.63

ls -la /opt/data/harbor/*.crt /opt/data/harbor/*.key

实测输出：

-rw-r--r-- 1 root root 1805 Oct 10 00:38 /opt/data/harbor/ca.crt
-rw------- 1 root root 3272 Oct 10 00:38 /opt/data/harbor/ca.key
-rw-r--r-- 1 root root 1838 Oct 10 00:38 /opt/data/harbor/server.crt
-rw------- 1 root root 3268 Oct 10 00:38 /opt/data/harbor/server.key

⚠️ 排障（实测）：ext.cnf 中 subjectAltName = IP:harbor.local 这种写法会因 harbor.local 不是 IP 而报错，导致 openssl x509 -req 退出码为 1。必须写成真实的 IP 或域名（如 DNS:registry.example.com）。

💡 说明：ca.crt 将来用于客户端信任，推拉镜像的客户端可将其导入 /etc/docker/certs.d/<host>/ca.crt 使 Docker 信任自签证书；本实测环境因把目标地址加入 Docker daemon 的 insecure-registries，也可直接登录。

4.5 配置 harbor.yml

从模板生成配置文件，并修改 hostname、HTTPS 证书路径、管理员密码、数据目录等关键项：

cd /opt/harbor-installer/harbor
cp harbor.yml.tmpl harbor.yml
sed -i \
  -e "s|^hostname: .*|hostname: 172.17.0.63|" \
  -e "s|^  certificate: .*|  certificate: /opt/data/harbor/server.crt|" \
  -e "s|^  private_key: .*|  private_key: /opt/data/harbor/server.key|" \
  -e "s|^harbor_admin_password: .*|harbor_admin_password: q1w2e3r4|" \
  -e "s|^data_volume: .*|data_volume: /opt/data/harbor|" \
  harbor.yml

确认关键行已修改（实测）：

grep -nE "^hostname:|^  port:|^  certificate:|^  private_key:|^harbor_admin_password:|^data_volume:" harbor.yml

5:hostname: 172.17.0.63
10:  port: 80
15:  port: 443
17:  certificate: /opt/data/harbor/server.crt
18:  private_key: /opt/data/harbor/server.key
47:harbor_admin_password: q1w2e3r4
66:data_volume: /opt/data/harbor

💡 说明：harbor_admin_password 仅在首次安装时生效；data_volume 指向 /opt/data/harbor，Harbor 的数据库、制品存储、配置等都会写入其中。完整参数含义见《Harbor 配置参数详解》。

4.6 执行安装脚本

cd /opt/harbor-installer/harbor
export TERM=xterm
./install.sh

实测输出（节选）：

[Step 0]: checking if docker is installed ...

Note: docker version: 29.8.1

[Step 1]: checking docker-compose is installed ...

Note: Docker Compose version v5.5.1

[Step 2]: loading Harbor images ...
Loaded image: goharbor/prepare:v2.15.4
Loaded image: goharbor/harbor-log:v2.15.4
Loaded image: goharbor/trivy-adapter-photon:v2.15.4
Loaded image: goharbor/harbor-exporter:v2.15.4
Loaded image: goharbor/harbor-portal:v2.15.4
Loaded image: goharbor/harbor-core:v2.15.4
Loaded image: goharbor/harbor-registryctl:v2.15.4
Loaded image: goharbor/valkey-photon:v2.15.4
Loaded image: goharbor/nginx-photon:v2.15.4
Loaded image: goharbor/registry-photon:v2.15.4
Loaded image: goharbor/harbor-db:v2.15.4
Loaded image: goharbor/harbor-jobservice:v2.15.4

[Step 3]: preparing environment ...

[Step 4]: preparing harbor configs ...
prepare base dir is set to /opt/harbor-installer/harbor

[Step 5]: starting Harbor ...
Network harbor_harbor Creating
Network harbor_harbor Created
Container harbor-log Creating
Container harbor-portal Starting
Container redis Starting
Container registry Starting
Container registryctl Starting
Container harbor-db Starting
Container harbor-core Starting
Container harbor-jobservice Starting
Container nginx Starting
✔ ----Harbor has been installed and started successfully.----

⚠️ 排障（实测）：若 Docker 存储驱动为 overlay 且所处文件系统不支持 whiteout（常见于受限/嵌套环境），./install.sh 第 2 步 docker load 会同时出现大量形如

Error unpacking image goharbor/prepare:v2.15.4: apply layer error ... 
failed to convert whiteout file "etc/ssl/certs/.wh.228f89db.0": operation not permitted

的报错，至第 4 步 prepare 彻底失败。解决办法：让 Docker 改用 vfs 存储驱动（在 /etc/docker/daemon.json 增加 "storage-driver": "vfs" 后重启 dockerd），再重新执行 ./install.sh。本文最终以 vfs 驱动部署成功。

4.7 验证平台服务组件状态

cd /opt/harbor-installer/harbor
docker compose ps

实测输出：

NAME                SERVICE        STATUS
harbor-core         core           Up 2 minutes (healthy)
harbor-db           postgresql     Up 2 minutes (healthy)
harbor-jobservice   jobservice     Up 2 minutes (healthy)
harbor-log          log            Up 2 minutes (healthy)
harbor-portal       portal         Up 2 minutes (healthy)
nginx               proxy          Up 2 minutes (healthy)
redis               redis          Up 2 minutes (healthy)
registry            registry       Up 2 minutes (healthy)
registryctl         registryctl    Up 2 minutes (healthy)

💡 说明：9 个平台服务组件全部 Up 且 healthy 即为部署成功。nginx（proxy）对外监听 80/443；其余 core/db/jobservice/portal/registry/registryctl/redis/log 为内部组件。

五、方案 B：官方在线安装器部署

适用于可访问 docker.io 的环境。在线安装器包体很小，安装时按需从仓库拉取组件镜像，其余流程与方案 A 一致。

5.1 下载在线安装器

cd /opt/harbor-installer
wget https://github.com/goharbor/harbor/releases/download/v2.15.4/harbor-online-installer-v2.15.4.tgz
tar xzf harbor-online-installer-v2.15.4.tgz
cd harbor
ls -l

实测中的（同版本）结构说明： 在线安装器不含 harbor.v2.15.4.tar.gz 大包，只有 install.sh、prepare、common.sh、harbor.yml.tmpl 等脚本与模板，安装时通过 Docker 在线拉取组件镜像。

5.2 生成自签证书并配置 harbor.yml

与方案 A 的 4.4 / 4.5 完全相同（生成证书到 /opt/data/harbor 并修改 harbor.yml 的 hostname/certificate/harbor_admin_password/data_volume），此处不再重复。

5.3 执行安装脚本

cd /opt/harbor-installer/harbor
export TERM=xterm
./install.sh

预期输出要点： 在线安装器安装流程与方案 A 一致，唯一差别是第 2 步由 docker load 内嵌包变为从仓库 docker pull 各组件镜像（如 goharbor/harbor-core:v2.15.4、goharbor/harbor-jobservice:v2.15.4、goharbor/registry-photon:v2.15.4 等），其余第 3~5 步与 4.6 相同，最终同样输出 ✔ ----Harbor has been installed and started successfully.----。

⚠️ 注意：在线安装器强依赖 docker.io 可达。若环境无法访问 Docker Hub（如内网隔离），应使用方案 A 离线安装器。

六、多方案对比与选择建议

对比维度方案 A（离线安装器）方案 B（在线安装器）
版本2.15.42.15.4
安装包体积约 713 MB（含组件镜像）仅数 MB（不含镜像）
是否需联网仅下载安装器阶段；安装本身无需安装时需访问 docker.io 拉镜像
适用场景内网隔离/弱网/需离线备份可联网、追求最小下载量
镜像来源安装包内嵌 harbor.v2.15.4.tar.gz 本地 docker load在线 docker pull
部署结果相同（9 个平台服务组件）相同

💡 选择建议：离线/内网环境选方案 A（离线安装器）；能访问 docker.io 且希望省下载流量选方案 B。二者部署出的 Harbor 完全一致，运行管理命令也完全相同。

七、配置说明

7.1 数据目录

所有 Harbor 数据（PostgreSQL 数据库、制品存储、日志、配置等）保存在 data_volume: /opt/data/harbor。建议后续配合独立数据盘并定期备份：

ls -la /opt/data/harbor

7.2 HTTPS 与端口

  • 对外入口为 nginx（proxy）组件，监听 443（HTTPS）、80（HTTP，自动 301 到 HTTPS）。
  • 证书路径由 harbor.yml 的 https.certificate / https.private_key 指定为 /opt/data/harbor/server.crt / server.key。
  • 客户端推拉镜像使用 172.17.0.63:443（或默认 https://172.17.0.63）。

7.3 管理账号

  • 管理账号 admin，首次安装密码取 harbor_admin_password: q1w2e3r4。首次登录后建议到控制台 /c/setting 修改密码并启用机密过期策略（见《Harbor 配置参数详解》）。

7.4 重启与服务自启

Harbor 以 docker compose 编排托管，启停通过 compose 完成：

cd /opt/harbor-installer/harbor
docker compose restart        # 重启全部组件
docker compose stop           # 停止全部组件
docker compose up -d          # 重新拉起全部组件（随 Docker 自启策略生效）

💡 说明：Harbor 内各组件在 compose 中均声明了 restart: always，仅需确保 Docker 守护进程开机自启即可实现 Harbor 随服务器开机恢复（systemctl enable docker 或安装 Docker 时已默认开启）。

八、常见问题

8.1 问题 1：hostname 用了 localhost 报错

原因： Harbor 的 hostname 不允许使用 localhost/127.0.0.1，否则外部无法访问。

解决： 改为服务器真实 IP 或域名（如 172.17.0.63），重新 ./install.sh（配置文件修改后 prepare 会自动重生成 compose 配置）。

8.2 问题 2：docker load 报 operation not permitted（whiteout）

原因： overlay 存储驱动在部分文件系统上无法写入 whiteout，常见于嵌套/受限环境。

解决： 修改 /etc/docker/daemon.json 增加 "storage-driver": "vfs"，重启 dockerd 后重新 ./install.sh（见 4.6 排障）。

8.3 问题 3：下载安装器卡在 0 字节 / 速度过慢

原因： 直连 GitHub Releases 网络不佳。

解决： 改用 GitHub 加速源（如 ghfast.top，见 4.2）使用 curl -L 下载。

8.4 问题 4：docker login 自签证书报 certificate signed by unknown authority

原因： 客户端 Docker 不信任 Harbor 的自签证书。

解决： 将 ca.crt 导入客户端 ~/.docker/ 的 /etc/docker/certs.d/172.17.0.63/ca.crt；或把服务地址加入 daemon 的 insecure-registries（仅限受信内网）。

8.5 问题 5：重启后 docker compose ps 各组件反复 Restarting

原因： 多为 /opt/data/harbor 数据目录权限不符或某组件依赖库未就绪。

解决： 查看单个组件日志定位（如 docker logs harbor-core）；确认数据目录属主与 uid 匹配，再 docker compose restart。

九、卸载与清理

cd /opt/harbor-installer/harbor
docker compose down -v         # 停止并移除组件、网络与命名卷
rm -rf /opt/harbor-installer   # 删除安装器
rm -rf /opt/data/harbor        # 删除数据目录（谨慎：含全部制品与数据库）

💡 说明：docker compose down -v 会清掉 Harbor 的命名卷；/opt/data/harbor 为主机 bind 挂载目录，须显式删除。若日后要保留制品供重装复用，跳过删除 /opt/data/harbor。

十、参考链接

本文档由 www.quzuo.net 平台开发