企业官网建设流程全解析

如果你在 Ubuntu 上装过 Harbor，大概会理解我想吐槽什么：网上教程一抓一大把，可真到了自己的机器上，20.04 能跑通的步骤扔到 22.04 上可能连 Docker 源都加不进去，18.04 上的问题更是五花八门。我最近两个月在测试环境和两个生产环境里，分别用 Ubuntu 18.04、20.04、22.04 各部署了一遍 Harbor，踩了不少坑，也把成功路径确定了下来。这篇教程就围绕这三个版本来写，覆盖离线在线安装包怎么选、harbor.yml 真正要改哪些字段、install.sh 跑完之后怎么验证，以及三版本最容易翻车的地方和排查思路。不管你是第一次装，还是准备换机器重新搭一套，照着这套流程走，能省掉大量试错时间。

1. 为什么在三个 Ubuntu 版本上装 Harbor，竟然会得到三种结果

1.1 差异根源不在 Harbor 本身，而在 Docker 和 Compose

Harbor 这套东西说到底是把一堆容器编排起来跑，它自己不是一个编译安装的应用。打开安装目录你会发现里面是 install.sh、common.sh、harbor.yml.tmpl，再加上一个带版本号的镜像包。install.sh 做的事本质上就是加载镜像、用 prepare 生成 Docker Compose 配置、然后拉起一堆容器。所以真正决定安装成败的，是你机器上 Docker 和 Docker Compose 是否干净、版本是否匹配。

问题恰恰出在这里。Ubuntu 18.04、20.04、22.04 虽然都是 Debian 系，但内核版本从 4.15、5.4 一直到 5.15，默认软件源里的包差异也很大。18.04 的 curl 和 gnupg 版本偏老，如果直接照抄 20.04 添加 Docker 官方源的命令，很可能卡在 gpg 加密钥那一步。22.04 的 systemd 更严格，sudo 权限、文件权限、systemd-resolved 占端口这些细节都会被放大。Harbor 本身反而是最不挑环境的那个。

1.2 硬件资源：先看内存、磁盘、CPU 再动手

Harbor 默认启动的容器至少有 database、redis、registry、core、portal、jobservice 这六个，如果开了 trivy、notary、chartmuseum，内存占用会明显上涨。我的建议是最低 2G 内存起步，4G 最稳妥；要是只有 1G，坚决劝退，否则装完 portal 一直重启，你会以为是 Harbor 坏了，其实只是机器不够用。

磁盘上，/var/lib/docker 和 Harbor 的 data_volume 是两条线。默认 data_volume 是 /data，但如果你把数据盘挂在别处，比如 /home 下面，就必须改配置。镜像仓库一旦跑起来，镜像文件、数据库文件都会往这里堆，50G 是最低舒适线，能用数据盘就用数据盘。CPU 双核以上问题不大，但如果是单核小机器，同时 push 镜像和跑 GC 的时候，卡顿会很明显。

1.3 访问方式定不下来，后面全是白干

Harbor 的 hostname 不是随便填的，它会被写进生成的链接、登录信息、证书 CN 这些地方。你需要在动手前想清楚：是拿 IP 访问，还是拿域名访问？是打算用 HTTP 测试，还是上 HTTPS？

这里经常有人反复折腾。第一次随便填了个临时域名，后来想改成 IP，结果所有 docker login 过的环境都要重新处理证书或 insecure-registry 配置，浏览器里保存的地址也得清。所以在准备阶段就花五分钟把这个定下来，能避免后面两三个小时的返工。

2. 动手前必须养成的三个习惯：版本、磁盘、端口

2.1 一键检查系统版本和内核

不管拿到哪台机器，第一件事是确认系统版本和内核，别信截图，别信别人说“这台机器是 20.04”。只需要两条命令：

lsb_release -a uname -r

我遇到过最迷惑的情况是：机器标签写的是 Ubuntu 22.04，实际内核还是 5.4，因为它是从 20.04 原地升级上来的。这种机器走 22.04 的安装路子可能没问题，但如果你照 22.04 的教程处理 systemd-resolved，反而会把系统原本的服务搞乱。所以先看版本，永远没错。

2.2 磁盘空间和目录规划

然后是看盘：

df -h

重点看根分区和打算放数据的分区。Harbor 的 compose 文件里所有容器数据都会写到 data_volume 指定目录下，如果根分区只剩 20G，而你要把生产镜像都推上去，那基本是拿命在扛。我一般会在安装前就规划好：

• 系统盘与数据盘分离；
• data_volume 指向数据盘，例如 /data/harbor；
• 给 / 目录留至少 20G，避免 Docker 日志把根分区塞满。

顺便检查一下 inode：

df -i

大镜像一多，inode 耗尽也是有可能的，别等 push 的时候报 no space left 才想起来。

2.3 端口占用检查

Harbor 默认的 http 端口是 80，https 端口是 443。但现实中 80 和 443 经常被 Nginx、Apache 或者别的 Web 服务占着，所以安装前用这条命令看一眼：

ss -lntp | grep -E ':(80|443|5000|8080)\s'

如果你要暴露 Docker Registry 的标准端口 5000，也要检查。一般来说，我建议在测试环境把 Harbor 的 HTTP 端口改成 8080，避开 80。但要注意：改端口不是只把 harbor.yml 里的数字改掉，改完还必须重新执行 install.sh 或者 prepare，否则容器里的配置不会更新。

3. 安装包选离线还是在线，以及下载后我习惯先做哪两件事

3.1 离线包与在线包的本质区别

Harbor 官方的发布页会提供两类安装包，离线包通常叫 harbor-offline-installer-vX.Y.Z.tgz，在线包叫 harbor-online-installer-vX.Y.Z.tgz。很多人以为离线包就是体积大一点，其实差异非常关键。

离线包内部带了一个 harbor.vX.Y.Z.tar.gz，这是所有 Harbor 容器镜像的打包文件。install.sh 在安装时不需要去远程仓库拉镜像，直接把镜像 load 进来就完事。在线包则要求安装时至少能访问到镜像仓库，否则装到一半会卡在镜像拉取上。生产环境我基本只用离线包，尤其当你处在隔离内网环境，离线包是唯一靠谱的选择。

3.2 下载后第一件事：校验完整性

这个步骤被很多人跳过，但我不建议。Harbor 安装包动辄几百 MB，万一传到一半损坏，install.sh 执行到 docker load 阶段才报错，浪费时间不说，还容易让你误判成环境问题。

官方的 sha256 校验值通常会随发布说明一起给出。下载后执行：

sha256sum harbor-offline-installer-v2.10.0.tgz

拿这个结果和发布页面里的值对一下。不一致就重新下载，不要硬装。我自己就碰到过一次包没下全，load 镜像阶段死活报错，最后重新下载后一次通过。

3.3 解压后先看目录结构，别急着改配置

解压命令很简单：

tar -xzf harbor-offline-installer-v2.10.0.tgz cd harbor

目录下会看到 install.sh、common.sh、harbor.yml.tmpl 和镜像包。这时候有个习惯很重要：永远不要直接改名 harbor.yml.tmpl 然后改它，最好复制一份为 harbor.yml，再在 harbor.yml 里做修改。原因很简单，将来升级时你还需要模板做对比，而且改坏了可以直接从模板重新复制，不用重新解压。

4. harbor.yml 逐项配置：这里改错一个字，后面等三天

4.1 hostname 怎么填，决定了你的访问体验

打开 harbor.yml 首先看到的是 hostname 字段。官方模板默认是 reg.mydomain.com。如果你是用 IP 访问，这里直接写 IP，比如：

hostname: 192.168.1.100

如果是域名访问，写域名。注意，这个值会被写入各类链接里。如果写错了，界面能打开但样式错乱、登录后跳转地址不对，docker login 也会用错 host。它不是随便填的标识，是会真实影响功能的。

4.2 http 和 https 的取舍

模板默认同时给出了 http 和 https 的配置块，但实际使用中，测试环境我通常只保留 http，并把端口改成 8080：

http: port: 8080

然后把整个 https 配置块注释掉。这时候 Docker 客户端去登录 Harbor，需要让 dockerd 信任这是非安全仓库。在 /etc/docker/daemon.json 里写：

{ "insecure-registries": ["192.168.1.100:8080"] }

然后重启 docker。需要提醒的是：重启 Docker 会把当前运行的所有容器全部重启一遍，如果你是旧版 docker，容器没有配置 restart 策略，可能会出现服务断掉的情况。所以最好在维护窗口做这一步。

生产环境我建议保留 https，证书路径可以指向你已有的证书，也可以是自签名。自签名证书生成之后，所有要登录 Harbor 的机器都需要把 CA 证书加进系统信任列表，否则 curl 和 docker login 都会报证书错误。

4.3 管理密码和数据库密码一定要改

Harbor 的管理员账号默认是 admin，密码模板里写的是 Harbor12345。这个密码几乎是人尽皆知的默认值，部署完如果不改，相当于大门敞开着。

同时要注意 database 块里的 password 字段。这个密码是 Harbor 内部 PostgreSQL 的密码，虽然不直接对外，但如果你把它设成带特殊字符的密码，有些情况下会被错误解析。我的习惯是设置一个只包含大小写字母和数字的强密码，长度 16 位以上。别在配置里写注释，也别用中文标点，这种隐形问题排查起来特别耗时间。

4.4 数据目录和可选组件，第一次安装尽量做减法

data_volume 字段默认是 /data。如果我需要放到数据盘，会改成类似 /data/harbor。改完它，所有组件的数据都会落在这个目录下面。

可选组件我建议第一次安装一律关闭。trivy 是漏洞扫描组件，对内存占用比较大；notary 负责镜像签名，平时用不上；chartmuseum 是 Helm Chart 仓库，需要的时候再开。在 harbor.yml 里把它们对应配置的 enabled 设置为 false，或者注释掉相关段落。装最小可用集合，等系统跑稳了再按需开组件，这是我现在的习惯。

5. install.sh 与 prepare 脚本执行后，如何验证整套服务可用

5.1 install.sh 除了启动容器，还做了什么

很多人以为 install.sh 就是 docker compose up -d，其实不是。它会先准备目录、设置权限，然后调用 prepare 脚本。prepare 的作用是根据 harbor.yml 生成真正的 docker-compose.yaml，同时生成各类服务端的配置。如果你修改了 harbor.yml 之后不重新执行 install.sh，而只是 docker compose restart，你会发现配置根本没生效，因为你重启的还是一套旧配置生成的容器。

所以凡是改动 harbor.yml，都老老实实重新执行：

sudo ./install.sh

别想着走捷径，我在这上面栽过好几次。

5.2 执行安装的具体流程

环境没问题后，安装命令极其简单：

cd harbor sudo ./install.sh

执行过程中会看到 docker load 镜像的进度条，然后是一串容器被创建。如果一切顺利，最后会提示 Harbor 启动成功。全程大概几分钟，取决于机器性能。

如果之前修改过 harbor.yml，我习惯在安装前手动跑一遍：

sudo ./prepare

这样能在真正 load 镜像之前就把配置错误暴露出来。prepare 报错通常很直接，比如 yaml 格式不对、必填项缺失，修起来也快。

5.3 从三个层面验证安装结果

安装结束不代表能用，我会按三个层面验证：

第一层，看容器状态：

docker compose ps

harbor-db、harbor-core、harbor-portal 等都应该处于 Up 状态。如果哪个容器反复重启或退出，别继续往下走，直接查日志。

第二层，浏览器访问。打开 http://IP:8080，能看到登录页，用 admin 和设置的密码登录成功，说明 Web 层面没问题。

第三层，命令行登录。找一台装 Docker 的客户端执行：

docker login 192.168.1.100:8080

输入账号密码能提示 Login Succeeded，才说明 Docker 客户端和 Harbor 之间的链路是通的。这里要注意，这一步最常报错的就是 x509 证书错误或 insecure-registry 没配好，回到第 4.2 节检查。

5.4 首次登录后的必要调整

登录成功后，先创建项目，比如叫 test-project。然后随便拉一个镜像，打个 tag，推上去验证完整链路：

docker pull busybox:latest docker tag busybox:latest 192.168.1.100:8080/test-project/busybox:v1 docker push 192.168.1.100:8080/test-project/busybox:v1

能 push 成功，说明写入和认证都正常。这时候你再去项目页面看，镜像已经躺在里面了。这一步千万别省，很多人装完 Harbor 只看到登录页，就以为配置没问题，结果真到 push 镜像的时候才报错，那时定位起来更麻烦。

6. 三版本实操中容易翻车的地方与定位思路

6.1 18.04 上：curl 和 gnupg 版本太旧，Docker 源加不进去

在 18.04 上最典型的问题出现在添加 Docker 源那一步。20.04 的教程里通常用 curl 下载 gpg 密钥再写入 apt 源，但 18.04 的 curl 默认没有足够新的 CA 证书，gnupg 也可能没装，导致下载密钥时报错或验证失败。

解决方式很简单，先补齐基础包：

sudo apt update sudo apt install -y curl ca-certificates gnupg

然后再执行添加 Docker apt 源的操作。18.04 的 Docker 版本我不推荐装太老的，20.10 以上的稳定版本完全没问题。Harbor 对 Docker 的版本要求并不苛刻，关键是 Dockerd 要能正常跑起来。

6.2 22.04 上：systemd-resolved 占用 53 端口，容器起不来

22.04 默认启用了 systemd-resolved，它监听 127.0.0.53:53 作为 DNS 解析服务。如果你在 docker-compose 里映射了宿主机 53 端口，或者某些容器内部配置需要监听 53，会出现 Address already in use 的错误。

定位方法：

ss -lntp | grep ':53 '

如果看到 systemd-resolve 占着 127.0.0.53:53，直接改 Harbor 相关容器的端口映射，别去停系统服务。停 systemd-resolved 属于动系统底层的操作，会影响整个系统的 DNS 解析，不推荐。

6.3 数据库容器反复重启：先看日志再动手

这是 Harbor 部署里最常遇到的一种问题，表现是 portal 能开，但登录时报 503，docker compose ps 里 harbor-db 一直 Restarting。

标准排查链路是：

docker compose logs database

日志里常见的原因有几类：

• 数据库密码写错，导致初始化失败；
• 数据目录权限不对，PostgreSQL 无法写入；
• 之前的数据目录残留，和当前版本不匹配。

解决时不要盲目删数据目录。先确认密码，再确认权限，最后才考虑备份并清空数据库目录重来。如果数据不重要，最省事的办法是：

sudo docker compose down -v sudo rm -rf /data/harbor/database sudo ./install.sh

这条命令会毁掉已有数据，生产环境千万别第一时间就照做。

6.4 所有版本都容易忽略的：Docker 客户端登录失败

Harbor 安装没问题，浏览器访问也正常，但 docker login 就是失败。绝大多数情况不是 Harbor 的问题，而是客户端 dockerd 不认你的仓库地址。除非你做了正规 HTTPS 证书，否则必须配置 insecure-registries。我见过有人在客户端机器上折腾半天，最后发现 daemon.json 改完没有重启 dockerd。改完配置一定要重启：

sudo systemctl restart docker

而且要注意，这个操作会影响该机器上所有正在运行的容器，最好提前评估影响面。

7. 部署完成不等于结束：升级、备份与自启动要提前想清楚

7.1 升级固定流程：备份、停服、跑新包

Harbor 升级不能直接把新版离线包在旧目录上执行 install.sh。我的一般流程是：

• 先停掉当前 Harbor 服务；
• 备份整个 data_volume 目录；
• 下载新版离线包，解压；
• 如果官方提供升级脚本，按脚本执行；
• 没有脚本就手动执行新版的 install.sh，让 prepare 重新生成配置。

整个过程中最容易忽略的是备份这一步。备份最好做增量前的完整快照，至少把 database 和 redis 目录完整拷走。Harbor 的配置、镜像元数据都在数据库里，丢了它，光备份镜像文件是没用的。

7.2 备份与恢复，核心是 data_volume

Harbor 的数据基本都在 data_volume 目录下，结构大致是 database、redis、registry 等子目录。备份最朴素的办法就是：

sudo tar -czf harbor-backup-$(date +%F).tar.gz /data/harbor

恢复时保证容器处于停止状态，把解压后的目录放回原位置，再执行 install.sh 启动。如果你有专门的备份工具，直接用也行。重要的是养成定期备份的习惯，别等磁盘坏了才意识到。

7.3 开机自启动，别只依赖 install.sh

Harbor 的容器不一定都带 restart: always。假如服务器意外重启，Harbor 不一定会自动拉起来。为了让它在机器重启后自动恢复，需要两步。

第一步确保 Docker 开机自启：

sudo systemctl enable docker

第二步给所有 Harbor 容器设置统一的重启策略：

docker update --restart=always $(docker ps -q --filter "name=harbor")

这样只要 Docker 启动，Harbor 相关容器就会被自动拉起。实际在 18.04、20.04、22.04 上这套机制都通用。

7.4 三个版本我的最终取舍

这三台机器折腾下来，我的体会是：如果新购机器，直接选 22.04，配合 Docker Compose v2 和离线包最省心；20.04 非常稳妥，适合已经有存量环境的人；18.04 不是不能用，但你得接受它基础软件包偏旧的事实，在加源、装依赖时多花一点时间。

网上很多教程喜欢把安装过程封装成“复制粘贴就能成功”，但真正部署软件的经验是：环境差异永远存在，理解命令背后的作用和排查思路，比背命令重要得多。在准备一台机器之前，先把版本、磁盘、端口、访问方式这四个基本问题搞清楚，Harbor 的安装其实只是往前走一小步而已。