★ FEATURED ARTICLE 如果你在 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 和 ComposeHarbor 这套东西说到底是把一堆容器编排起来跑它自己不是一个编译安装的应用。打开安装目录你会发现里面是 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 日志把根分区塞满。顺便检查一下 inodedf -i大镜像一多inode 耗尽也是有可能的别等 push 的时候报 no space left 才想起来。2.3 端口占用检查Harbor 默认的 http 端口是 80https 端口是 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并把端口改成 8080http: 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 psharbor-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 能开但登录时报 503docker 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_volumeHarbor 的数据基本都在 data_volume 目录下结构大致是 database、redis、registry 等子目录。备份最朴素的办法就是sudo tar -czf harbor-backup-$(date %F).tar.gz /data/harbor恢复时保证容器处于停止状态把解压后的目录放回原位置再执行 install.sh 启动。如果你有专门的备份工具直接用也行。重要的是养成定期备份的习惯别等磁盘坏了才意识到。7.3 开机自启动别只依赖 install.shHarbor 的容器不一定都带 restart: always。假如服务器意外重启Harbor 不一定会自动拉起来。为了让它在机器重启后自动恢复需要两步。第一步确保 Docker 开机自启sudo systemctl enable docker第二步给所有 Harbor 容器设置统一的重启策略docker update --restartalways $(docker ps -q --filter nameharbor)这样只要 Docker 启动Harbor 相关容器就会被自动拉起。实际在 18.04、20.04、22.04 上这套机制都通用。7.4 三个版本我的最终取舍这三台机器折腾下来我的体会是如果新购机器直接选 22.04配合 Docker Compose v2 和离线包最省心20.04 非常稳妥适合已经有存量环境的人18.04 不是不能用但你得接受它基础软件包偏旧的事实在加源、装依赖时多花一点时间。网上很多教程喜欢把安装过程封装成“复制粘贴就能成功”但真正部署软件的经验是环境差异永远存在理解命令背后的作用和排查思路比背命令重要得多。在准备一台机器之前先把版本、磁盘、端口、访问方式这四个基本问题搞清楚Harbor 的安装其实只是往前走一小步而已。
阅读完成 · 觉得有帮助？
