简介面向ARM架构服务器部署Harbor镜像仓库的离线安装包专为内网隔离或无法稳定访问外网的运维场景设计解决手动下载依赖多、版本匹配难的问题。包内包含官方harbor-offline-installer-v2.13.1-arm64.tgz安装程序及配套脚本共6个文件以shell脚本、配置模板、license和镜像压缩包为主install.sh与prepare负责安装引导和环境预检common.sh提供公共函数harbor.yml.tmpl用于自定义端口与存储等参数另含harbor.2.13.1.tar.gz离线镜像包。整体压缩包约513MB已封装完整解压后即可按官方流程部署。目前已有408人学习使用适合具备Linux基础、需要快速搭建企业级Registry的运维或开发人员。资源省去逐一下载组件的繁琐步骤同时保留授权文件帮助用户在ARM平台上稳定运行Harbor 2.13.1。 在ARM服务器上折腾镜像仓库源码包和在线安装脚本都不难找难的是那个让你一眼看到就觉得“就是它”的离线安装包。最近我在部署Harbor 2.13.1机器是arm64架构从官方发布页一层层翻最后锁定的就是harbor-offline-installer-v2.13.1-arm64.tgz这个包。这篇文章就把我在arm环境下用这个离线包从零部署Harbor的完整过程写出来包括拆包、改配置、执行安装、把默认http改成https以及ARM平台上容易踩的坑。适合正在各种ARM服务器、开发板或者QEMU模拟的arm64环境里装Harbor的朋友参考。1. 拿到这个包之前先确认你的机器到底是不是arm641.1 为什么非要找arm64版本的离线包Harbor官方发布页上的安装包是分流派的amd64、arm64还有少数平台专用的。以前很多程序是“随便下载一个包传上去就能跑”在x86时代可以这么干但到了ARM平台就完全不是一回事。Harbor把全套组件装进容器容器镜像本身就是带架构的架构不匹配的镜像就算拉下来也起不来。所以当目标机器是arm64就不要盯着amd64的包看直接找文件名里带arm64的比如harbor-offline-installer-v2.13.1-arm64.tgz。现在会遇到arm64场景的机器比以前多很多各种ARM服务器和开发板、Apple Silicon上跑Linux虚拟机、甚至x86宿主机上用QEMU模拟出来的arm64环境。不能说arm64会取代谁但它出现在机房的概率已经高到你必须掌握这套部署方法。拿错架构包去装Harbor解压阶段看不出问题等docker load进去才发现镜像平台对不上既浪费时间又容易让人怀疑自己哪里配错了。1.2 如何准确判断CPU架构动手之前我先在机器上敲了一组命令确认架构这个环节建议不要跳过uname -m lscpu | grep Architecture dpkg --print-architectureuname -m输出aarch64说明CPU是64位ARM架构。dpkg --print-architecture在Debian/Ubuntu上会输出arm64。如果输出x86_64或amd64那这个ARM离线包就不适合这台机器。命令输出示例判断uname -maarch64是arm64可用uname -mx86_64是amd64不可用dpkg --print-architecturearm64是arm64可用lscpuArchitecture: aarch64是arm64可用这里有个小常识内核里叫aarch64发行版和包管理器里叫arm64Harbor文件名里也写arm64它们指的是同一个东西。网上资料里看到aarch64就当arm64处理别再怀疑自己装错了。1.3 amd64和arm64的镜像真的不通用有人可能想偷懒把amd64的Harbor离线包下载下来到arm64机器上直接docker load能装上吗实测结果基本都是“能load进去但容器起不来”偶尔还会看到exec format error。原因很好理解容器里跑的是基于arm64指令集编译的二进制程序nginx、postgres、redis这些都有架构差异x86和ARM的指令集不通用。打个比方amd64镜像是按x86 CPU的“方言”写的代码到了ARM芯片上CPU根本不认识这些指令。所以正确路径只有一条认准arm64离线包。Harbor从很早的版本就开始提供arm64构建产物2.13.1这个版本的文件名里明确写了arm64说明官方已经帮你编译好整套arm64容器镜像省去了自己从源码构建的麻烦。2. 环境准备这四样不到位离线包再全也白搭2.1 系统版本与基础命令Harbor官方推荐在干净的Linux上安装Ubuntu、Debian、CentOS这类发行版都有人跑过。我这次用的Ubuntu 22.04.5 arm64整体过程很顺。基础工具方面tar、openssl、curl这些大概率系统自带但如果你面对的是非常精简的服务器系统建议先补一下sudo apt update sudo apt install -y tar openssl curl wget vim在内网离线环境里apt源可能本身就不通那就需要提前准备这些基础deb包。好在Harbor离线包依赖的系统软件很少真正的大头是Docker这部分建议在进入安装环节前确认好。2.2 Docker和Compose版本要求Harbor安装脚本依赖docker和docker compose两个缺一不可。版本这块有讲究Docker Engine建议20.10以上实际我更推荐23.0或24.0以上。Compose方面新版本Harbor同时兼容docker composev2插件和docker-composev1独立二进制。如果手头只有老的docker-compose 1.x比如1.24很可能解析不了新版compose文件直接卡在install.sh阶段。安装命令参考sudo apt install -y docker.io docker-compose-plugin sudo systemctl enable --now docker sudo docker --version sudo docker compose version在Debian系发行版上docker.io包提供的Docker版本通常够用。如果你想用官方源装最新docker-ce记得把containerd、docker-ce-cli、docker-buildx-plugin、docker-compose-plugin一起装上别漏了。我这里吃过亏一开始只装了docker-ce漏了docker-compose-pluginHarbor的install.sh直接提示找不到compose命令。2.3 内存、磁盘以及QEMU模拟环境的额外成本Harbor装好后会同时运行一堆容器至少包括nginx、registry、registryctl、core、portal、redis、postgresql、jobservice、exporter有的版本还带漏洞扫描服务。这样一套下来4GB内存只是起步线。如果机器只有2GB内存建议别硬上要么加内存要么先加swapsudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile磁盘方面离线包本身接近1GB解压后镜像包再展开加上后期镜像存储建议给Harbor的数据目录留至少50GB宁可多不能少。还有一种特殊场景在x86宿主机上用QEMU模拟arm64跑Ubuntu做测试安装命令和真机完全一样但镜像加载阶段会很慢因为docker load、容器启动都要经过指令翻译性能损耗明显。QEMU虚拟机的CPU核数和内存尽量给足建议至少4核8GB否则你会误以为安装脚本卡死了。3. 拆包看结构offline-installer和在线安装到底差在哪3.1 解压后有哪些文件把包拷到服务器上进目录后用下面命令拆开tar -zxvf harbor-offline-installer-v2.13.1-arm64.tgz cd harbor ls -lh我看到的文件大概是这样harbor.v2.13.1.tar.gz最大的那个文件几十个容器镜像的打包体离线安装的核心。install.sh安装入口脚本。prepare配置生成工具负责根据harbor.yml生成最终运行配置。common.sh公共函数库install.sh会调用。harbor.yml.tmpl配置文件模板安装前要复制成harbor.yml并修改。docker-compose.yml.tmplcompose文件模板实际运行的compose文件由prepare生成。LICENSE、README.md等。这个结构和在线包最大的区别就是多了harbor.v2.13.1.tar.gz。在线包安装时从镜像仓库实时拉取离线包则把它变成本地加载所以内网、隔离网环境里装Harbor必须用离线包而且是arm64对应的离线包。3.2 install.sh在背后做了什么刚开始接触Harbor的人可能觉得install.sh就是个“一键脚本”跑完就完事。实际上它做了四件事校验环境检查docker、compose命令是否存在版本是否满足要求。拿到harbor.yml里的配置包括hostname、http和https端口、harbor_admin_password、data_volume等。调用prepare生成最终的docker-compose.yml、nginx配置等。加载harbor.v2.13.1.tar.gz里的镜像然后docker compose up -d启动全部服务。理解了这四步后面改配置、重新启动的思路就清晰了改harbor.yml后其实不需要重新加载镜像只需重新执行prepare并compose up -d容器重建后配置就生效了。这个理解能帮你省很多时间。3.3 离线包的正确使用心态想说清楚一点离线包不是“解压出来就能一键运行”的黑盒它省的是网络问题省不掉配置和架构适配的问题。文件名里的arm64只保证容器镜像架构匹配但hostname、端口、TLS证书、密码这些仍然需要你在harbor.yml里写清楚。我见过同事拿离线包解压后直接执行install.sh全程默认配置结果hostname还是模板里的默认域名浏览器访问打不开Docker客户端也登录不了。所以拿到这个tgz先把它当成一个“带镜像的安装工具”而不是全自动安装器。4. 从解压到访问UI完整安装步骤记录4.1 生成并修改harbor.yml解压后第一步是把配置模板复制出来cp harbor.yml.tmpl harbor.yml vim harbor.ymlharbor.yml里需要重点改这几个地方hostname: 192.168.1.100 http: port: 80 harbor_admin_password: Harbor12345 data_volume: /data/harborhostname填本机IP或者规划好的域名不能填127.0.0.1否则其他机器访问不了。http.port默认80如果机器上已经有nginx之类占用80改成8080。harbor_admin_password初始密码生产环境一定要改掉。data_volume所有持久化数据都会落到这个目录建议单独放一块数据盘。如果一开始就打算用https这一步可以顺手把https段配置好。如果想像我一样先把服务跑起来、再用自签名证书慢慢切也可以先只配置http后面按第5节的方法补。4.2 执行install.sh并查看日志配置完直接执行sudo ./install.sh日志开头会做环境检查然后开始加载镜像、创建日志目录这些步骤。镜像加载时间取决于机器性能物理机上通常几分钟内能完成QEMU模拟的arm64环境可能要十几分钟期间CPU会拉高这是正常现象不要中途CtrlC否则镜像加载到一半下次启动又得重新加载。如果一切正常末尾会出现类似这样的一行✔ ----Harbor has been installed and started successfully----看到这行Harbor的安装阶段就算结束了。4.3 验证服务状态和访问后台安装成功不等于所有容器都健康我习惯再用两个命令确认一下sudo docker compose ps curl -k http://127.0.0.1/api/v2.0/pingcompose ps里应该能看到up状态的容器列表curl请求返回一个Pong字符串就说明UI、API、数据库、缓存这一整条链路已经打通。然后浏览器打开http://你填的hostname用admin和刚才设置的harbor_admin_password登录后台新建一个项目就能开始推拉镜像了。推镜像时注意如果hostname填的是IP登录就用docker login 192.168.1.100如果填了域名客户端机器的DNS或hosts里必须能解析到这个域名否则登录会一直提示仓库地址不匹配。5. 装上之后立刻处理的三件事证书、数据目录、自启5.1 把默认http改成https自签名证书方案Harbor默认暴露的是http服务但真实环境里明文传输镜像数据肯定不放心而且docker客户端对非localhost仓库默认要求https。改成https最稳妥的办法是让Harbor的nginx直接提供TLS而不是在外面再套一层反代。流程如下。先生成自签名证书放到固定目录sudo mkdir -p /data/cert cd /data/cert sudo openssl req -newkey rsa:4096 -nodes -sha256 -keyout harbor.key -x509 -days 365 -out harbor.crt \ -subj /CNmyharbor.example.com \ -addext subjectAltName DNS:myharbor.example.com,IP:192.168.1.100然后编辑harbor.ymlhostname: myharbor.example.com http: port: 80 https: port: 443 certificate: /data/cert/harbor.crt private_key: /data/cert/harbor.key接着让配置生效sudo ./prepare sudo docker compose up -dprepare会基于新的harbor.yml重新生成nginx和compose配置up -d会重建配置有变化的容器。注意不要直接改运行中nginx容器里的配置文件Harbor的nginx配置由prepare统一管理手动改完一重建就丢了。Docker客户端访问自签名HTTPS仓库时需要让Docker信任这个证书。最简单的方式是每台客户端机器都建好certs.d目录并放入harbor.crtsudo mkdir -p /etc/docker/certs.d/myharbor.example.com sudo cp harbor.crt /etc/docker/certs.d/myharbor.example.com/ca.crt sudo systemctl restart docker docker login myharbor.example.com如果是临时测试也可以在/etc/docker/daemon.json里加insecure-registries但生产不建议因为那会跳过TLS校验。5.2 数据持久化和备份思路Harbor的数据全部在data_volume默认路径是/data/harbor。里面包含数据库文件、镜像存储、日志等一旦丢失用户、项目、镜像元数据全都没了。有条件的话把data_volume挂到单独的数据盘防止系统盘故障连锅端。定期备份postgresql数据库Harbor的元数据主要存在数据库里镜像本身是文件可以单独同步。数据库备份可以直接在容器内执行pg_dump写个crontab定时脚本。我自己的习惯是把镜像存储和数据库备份分开处理镜像存储用rsync同步到备份盘数据库用pg_dump每天导出一次。这样既保证恢复速度又不至于把所有鸡蛋放在一个篮子里。5.3 重启自动拉起别靠手敲命令Harbor容器在compose配置里基本都带restart: always所以只要dockerd先启动容器就会自动恢复。剩下的问题就是保证Docker服务开机自启sudo systemctl enable docker完成这两步后即使服务器意外重启Harbor也会跟着自动起来不需要人工干预。如果你愿意也可以再写一个systemd unit来调用docker compose up -d但意义不大restart策略已经覆盖了大多数场景反而多加一层服务会把问题复杂化。6. 我踩过的坑ARM环境特有的问题排查过程6.1 docker-compose命令缺失或版本过旧装第一台机器时我漏装了docker-compose-plugin结果install.sh直接停在环境检查阶段报错信息很明确docker-compose命令找不到。解决办法是补装插件。但还有一种情况更隐蔽机器上装了很老的docker-compose 1.xinstall.sh找到了这个命令结果解析compose文件时报version unsupported。这时候需要把老版本卸掉或改调用docker composesudo rm -f /usr/local/bin/docker-compose sudo apt install -y docker-compose-plugin docker compose versionHarbor 2.13.1的compose文件对schema版本有要求老版本的python docker-compose解析不了。所以看到这类错误第一反应不是去改compose文件而是先检查compose工具版本。6.2 QEMU模拟环境性能翻车我有一台x86开发机想验证arm64离线包内容图省事用QEMU起了个arm64 Ubuntu虚拟机内存4GBCPU 4核。安装阶段进展顺利但到docker load那一步明显变慢一个harbor.v2.13.1.tar.gz刷了差不多十几分钟容器全部启动后又感觉UI访问偶发卡顿。这个现象在纯QEMU模拟环境下很正常毕竟整套系统指令集都被翻译执行性能和平常的KVM虚拟机不是一个量级。如果只是验证包能不能装、步骤对不对可以尝试如果是正式环境或需要频繁推拉镜像建议还是用arm64物理机或带硬件虚拟化的云主机别拿模拟环境顶包。6.3 内存不足、端口冲突、hostname遗漏剩下三个问题虽然不只在ARM上出现但在ARM小机器上特别典型。内存不足最容易发生在4GB内存的板子或虚拟机上表现是安装日志显示postgresql容器一直在重启或者容器状态从Up变成Restarting。排查方法很简单dmesg | grep -i oom看到OOM相关日志就说明内存爆了。加swap、关掉不用的扩展组件都能缓解。端口冲突则常见于服务器上已经跑了nginxHarbor默认也要监听80一启动就提示address already in use。这种直接把harbor.yml里的http.port改成8080或其他空闲端口就行不用去停掉已有服务。hostname遗漏问题我在前面说过一次但值得再强调一遍。很多默认模板里的hostname是示例域名如果你不想改、直接照抄装完以后会发现后台虽然能进但Docker客户端执行docker login时又是证书不匹配又是域名解析失败实际体验非常别扭。所以config文件里hostname这一项一定要改成你自己的IP或规划好的域名这是部署Harbor最容易忽略但也最影响后续使用的配置。为了方便排查我把ARM环境Harbor部署的高频问题整理成一张表现象可能原因排查命令解决办法容器反复重启内存不足触发OOMdmesg | grep -i oom加swap或加内存80端口无法绑定已有进程占用ss -tlnp修改http.portdocker login失败、证书不匹配hostname用了默认域名docker login -v修改hostname并让客户端信任证书安装阶段报compose错误compose工具缺失或版本过旧docker compose version安装docker-compose-plugin我在几台arm64机器上重复部署了几次之后最深的体会就是一句话架构先对了后面的路才好走。别看只是一个离线包的选择选错架构后面所有的报错排查都在浪费时间。装完再顺手把证书、备份、自启这三件事处理掉Harbor基本就能长期稳定跑。最后再分享一个小技巧如果机器配置紧张不用急着把扩展组件全开满先把核心的registry、core、database跑起来业务顺了再逐步加功能运维压力会小很多。本文还有配套的精品资源点击获取 ARM64架构下Harbor离线安装部署实战
简介面向ARM架构服务器部署Harbor镜像仓库的离线安装包专为内网隔离或无法稳定访问外网的运维场景设计解决手动下载依赖多、版本匹配难的问题。包内包含官方harbor-offline-installer-v2.13.1-arm64.tgz安装程序及配套脚本共6个文件以shell脚本、配置模板、license和镜像压缩包为主install.sh与prepare负责安装引导和环境预检common.sh提供公共函数harbor.yml.tmpl用于自定义端口与存储等参数另含harbor.2.13.1.tar.gz离线镜像包。整体压缩包约513MB已封装完整解压后即可按官方流程部署。目前已有408人学习使用适合具备Linux基础、需要快速搭建企业级Registry的运维或开发人员。资源省去逐一下载组件的繁琐步骤同时保留授权文件帮助用户在ARM平台上稳定运行Harbor 2.13.1。 在ARM服务器上折腾镜像仓库源码包和在线安装脚本都不难找难的是那个让你一眼看到就觉得“就是它”的离线安装包。最近我在部署Harbor 2.13.1机器是arm64架构从官方发布页一层层翻最后锁定的就是harbor-offline-installer-v2.13.1-arm64.tgz这个包。这篇文章就把我在arm环境下用这个离线包从零部署Harbor的完整过程写出来包括拆包、改配置、执行安装、把默认http改成https以及ARM平台上容易踩的坑。适合正在各种ARM服务器、开发板或者QEMU模拟的arm64环境里装Harbor的朋友参考。1. 拿到这个包之前先确认你的机器到底是不是arm641.1 为什么非要找arm64版本的离线包Harbor官方发布页上的安装包是分流派的amd64、arm64还有少数平台专用的。以前很多程序是“随便下载一个包传上去就能跑”在x86时代可以这么干但到了ARM平台就完全不是一回事。Harbor把全套组件装进容器容器镜像本身就是带架构的架构不匹配的镜像就算拉下来也起不来。所以当目标机器是arm64就不要盯着amd64的包看直接找文件名里带arm64的比如harbor-offline-installer-v2.13.1-arm64.tgz。现在会遇到arm64场景的机器比以前多很多各种ARM服务器和开发板、Apple Silicon上跑Linux虚拟机、甚至x86宿主机上用QEMU模拟出来的arm64环境。不能说arm64会取代谁但它出现在机房的概率已经高到你必须掌握这套部署方法。拿错架构包去装Harbor解压阶段看不出问题等docker load进去才发现镜像平台对不上既浪费时间又容易让人怀疑自己哪里配错了。1.2 如何准确判断CPU架构动手之前我先在机器上敲了一组命令确认架构这个环节建议不要跳过uname -m lscpu | grep Architecture dpkg --print-architectureuname -m输出aarch64说明CPU是64位ARM架构。dpkg --print-architecture在Debian/Ubuntu上会输出arm64。如果输出x86_64或amd64那这个ARM离线包就不适合这台机器。命令输出示例判断uname -maarch64是arm64可用uname -mx86_64是amd64不可用dpkg --print-architecturearm64是arm64可用lscpuArchitecture: aarch64是arm64可用这里有个小常识内核里叫aarch64发行版和包管理器里叫arm64Harbor文件名里也写arm64它们指的是同一个东西。网上资料里看到aarch64就当arm64处理别再怀疑自己装错了。1.3 amd64和arm64的镜像真的不通用有人可能想偷懒把amd64的Harbor离线包下载下来到arm64机器上直接docker load能装上吗实测结果基本都是“能load进去但容器起不来”偶尔还会看到exec format error。原因很好理解容器里跑的是基于arm64指令集编译的二进制程序nginx、postgres、redis这些都有架构差异x86和ARM的指令集不通用。打个比方amd64镜像是按x86 CPU的“方言”写的代码到了ARM芯片上CPU根本不认识这些指令。所以正确路径只有一条认准arm64离线包。Harbor从很早的版本就开始提供arm64构建产物2.13.1这个版本的文件名里明确写了arm64说明官方已经帮你编译好整套arm64容器镜像省去了自己从源码构建的麻烦。2. 环境准备这四样不到位离线包再全也白搭2.1 系统版本与基础命令Harbor官方推荐在干净的Linux上安装Ubuntu、Debian、CentOS这类发行版都有人跑过。我这次用的Ubuntu 22.04.5 arm64整体过程很顺。基础工具方面tar、openssl、curl这些大概率系统自带但如果你面对的是非常精简的服务器系统建议先补一下sudo apt update sudo apt install -y tar openssl curl wget vim在内网离线环境里apt源可能本身就不通那就需要提前准备这些基础deb包。好在Harbor离线包依赖的系统软件很少真正的大头是Docker这部分建议在进入安装环节前确认好。2.2 Docker和Compose版本要求Harbor安装脚本依赖docker和docker compose两个缺一不可。版本这块有讲究Docker Engine建议20.10以上实际我更推荐23.0或24.0以上。Compose方面新版本Harbor同时兼容docker composev2插件和docker-composev1独立二进制。如果手头只有老的docker-compose 1.x比如1.24很可能解析不了新版compose文件直接卡在install.sh阶段。安装命令参考sudo apt install -y docker.io docker-compose-plugin sudo systemctl enable --now docker sudo docker --version sudo docker compose version在Debian系发行版上docker.io包提供的Docker版本通常够用。如果你想用官方源装最新docker-ce记得把containerd、docker-ce-cli、docker-buildx-plugin、docker-compose-plugin一起装上别漏了。我这里吃过亏一开始只装了docker-ce漏了docker-compose-pluginHarbor的install.sh直接提示找不到compose命令。2.3 内存、磁盘以及QEMU模拟环境的额外成本Harbor装好后会同时运行一堆容器至少包括nginx、registry、registryctl、core、portal、redis、postgresql、jobservice、exporter有的版本还带漏洞扫描服务。这样一套下来4GB内存只是起步线。如果机器只有2GB内存建议别硬上要么加内存要么先加swapsudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile磁盘方面离线包本身接近1GB解压后镜像包再展开加上后期镜像存储建议给Harbor的数据目录留至少50GB宁可多不能少。还有一种特殊场景在x86宿主机上用QEMU模拟arm64跑Ubuntu做测试安装命令和真机完全一样但镜像加载阶段会很慢因为docker load、容器启动都要经过指令翻译性能损耗明显。QEMU虚拟机的CPU核数和内存尽量给足建议至少4核8GB否则你会误以为安装脚本卡死了。3. 拆包看结构offline-installer和在线安装到底差在哪3.1 解压后有哪些文件把包拷到服务器上进目录后用下面命令拆开tar -zxvf harbor-offline-installer-v2.13.1-arm64.tgz cd harbor ls -lh我看到的文件大概是这样harbor.v2.13.1.tar.gz最大的那个文件几十个容器镜像的打包体离线安装的核心。install.sh安装入口脚本。prepare配置生成工具负责根据harbor.yml生成最终运行配置。common.sh公共函数库install.sh会调用。harbor.yml.tmpl配置文件模板安装前要复制成harbor.yml并修改。docker-compose.yml.tmplcompose文件模板实际运行的compose文件由prepare生成。LICENSE、README.md等。这个结构和在线包最大的区别就是多了harbor.v2.13.1.tar.gz。在线包安装时从镜像仓库实时拉取离线包则把它变成本地加载所以内网、隔离网环境里装Harbor必须用离线包而且是arm64对应的离线包。3.2 install.sh在背后做了什么刚开始接触Harbor的人可能觉得install.sh就是个“一键脚本”跑完就完事。实际上它做了四件事校验环境检查docker、compose命令是否存在版本是否满足要求。拿到harbor.yml里的配置包括hostname、http和https端口、harbor_admin_password、data_volume等。调用prepare生成最终的docker-compose.yml、nginx配置等。加载harbor.v2.13.1.tar.gz里的镜像然后docker compose up -d启动全部服务。理解了这四步后面改配置、重新启动的思路就清晰了改harbor.yml后其实不需要重新加载镜像只需重新执行prepare并compose up -d容器重建后配置就生效了。这个理解能帮你省很多时间。3.3 离线包的正确使用心态想说清楚一点离线包不是“解压出来就能一键运行”的黑盒它省的是网络问题省不掉配置和架构适配的问题。文件名里的arm64只保证容器镜像架构匹配但hostname、端口、TLS证书、密码这些仍然需要你在harbor.yml里写清楚。我见过同事拿离线包解压后直接执行install.sh全程默认配置结果hostname还是模板里的默认域名浏览器访问打不开Docker客户端也登录不了。所以拿到这个tgz先把它当成一个“带镜像的安装工具”而不是全自动安装器。4. 从解压到访问UI完整安装步骤记录4.1 生成并修改harbor.yml解压后第一步是把配置模板复制出来cp harbor.yml.tmpl harbor.yml vim harbor.ymlharbor.yml里需要重点改这几个地方hostname: 192.168.1.100 http: port: 80 harbor_admin_password: Harbor12345 data_volume: /data/harborhostname填本机IP或者规划好的域名不能填127.0.0.1否则其他机器访问不了。http.port默认80如果机器上已经有nginx之类占用80改成8080。harbor_admin_password初始密码生产环境一定要改掉。data_volume所有持久化数据都会落到这个目录建议单独放一块数据盘。如果一开始就打算用https这一步可以顺手把https段配置好。如果想像我一样先把服务跑起来、再用自签名证书慢慢切也可以先只配置http后面按第5节的方法补。4.2 执行install.sh并查看日志配置完直接执行sudo ./install.sh日志开头会做环境检查然后开始加载镜像、创建日志目录这些步骤。镜像加载时间取决于机器性能物理机上通常几分钟内能完成QEMU模拟的arm64环境可能要十几分钟期间CPU会拉高这是正常现象不要中途CtrlC否则镜像加载到一半下次启动又得重新加载。如果一切正常末尾会出现类似这样的一行✔ ----Harbor has been installed and started successfully----看到这行Harbor的安装阶段就算结束了。4.3 验证服务状态和访问后台安装成功不等于所有容器都健康我习惯再用两个命令确认一下sudo docker compose ps curl -k http://127.0.0.1/api/v2.0/pingcompose ps里应该能看到up状态的容器列表curl请求返回一个Pong字符串就说明UI、API、数据库、缓存这一整条链路已经打通。然后浏览器打开http://你填的hostname用admin和刚才设置的harbor_admin_password登录后台新建一个项目就能开始推拉镜像了。推镜像时注意如果hostname填的是IP登录就用docker login 192.168.1.100如果填了域名客户端机器的DNS或hosts里必须能解析到这个域名否则登录会一直提示仓库地址不匹配。5. 装上之后立刻处理的三件事证书、数据目录、自启5.1 把默认http改成https自签名证书方案Harbor默认暴露的是http服务但真实环境里明文传输镜像数据肯定不放心而且docker客户端对非localhost仓库默认要求https。改成https最稳妥的办法是让Harbor的nginx直接提供TLS而不是在外面再套一层反代。流程如下。先生成自签名证书放到固定目录sudo mkdir -p /data/cert cd /data/cert sudo openssl req -newkey rsa:4096 -nodes -sha256 -keyout harbor.key -x509 -days 365 -out harbor.crt \ -subj /CNmyharbor.example.com \ -addext subjectAltName DNS:myharbor.example.com,IP:192.168.1.100然后编辑harbor.ymlhostname: myharbor.example.com http: port: 80 https: port: 443 certificate: /data/cert/harbor.crt private_key: /data/cert/harbor.key接着让配置生效sudo ./prepare sudo docker compose up -dprepare会基于新的harbor.yml重新生成nginx和compose配置up -d会重建配置有变化的容器。注意不要直接改运行中nginx容器里的配置文件Harbor的nginx配置由prepare统一管理手动改完一重建就丢了。Docker客户端访问自签名HTTPS仓库时需要让Docker信任这个证书。最简单的方式是每台客户端机器都建好certs.d目录并放入harbor.crtsudo mkdir -p /etc/docker/certs.d/myharbor.example.com sudo cp harbor.crt /etc/docker/certs.d/myharbor.example.com/ca.crt sudo systemctl restart docker docker login myharbor.example.com如果是临时测试也可以在/etc/docker/daemon.json里加insecure-registries但生产不建议因为那会跳过TLS校验。5.2 数据持久化和备份思路Harbor的数据全部在data_volume默认路径是/data/harbor。里面包含数据库文件、镜像存储、日志等一旦丢失用户、项目、镜像元数据全都没了。有条件的话把data_volume挂到单独的数据盘防止系统盘故障连锅端。定期备份postgresql数据库Harbor的元数据主要存在数据库里镜像本身是文件可以单独同步。数据库备份可以直接在容器内执行pg_dump写个crontab定时脚本。我自己的习惯是把镜像存储和数据库备份分开处理镜像存储用rsync同步到备份盘数据库用pg_dump每天导出一次。这样既保证恢复速度又不至于把所有鸡蛋放在一个篮子里。5.3 重启自动拉起别靠手敲命令Harbor容器在compose配置里基本都带restart: always所以只要dockerd先启动容器就会自动恢复。剩下的问题就是保证Docker服务开机自启sudo systemctl enable docker完成这两步后即使服务器意外重启Harbor也会跟着自动起来不需要人工干预。如果你愿意也可以再写一个systemd unit来调用docker compose up -d但意义不大restart策略已经覆盖了大多数场景反而多加一层服务会把问题复杂化。6. 我踩过的坑ARM环境特有的问题排查过程6.1 docker-compose命令缺失或版本过旧装第一台机器时我漏装了docker-compose-plugin结果install.sh直接停在环境检查阶段报错信息很明确docker-compose命令找不到。解决办法是补装插件。但还有一种情况更隐蔽机器上装了很老的docker-compose 1.xinstall.sh找到了这个命令结果解析compose文件时报version unsupported。这时候需要把老版本卸掉或改调用docker composesudo rm -f /usr/local/bin/docker-compose sudo apt install -y docker-compose-plugin docker compose versionHarbor 2.13.1的compose文件对schema版本有要求老版本的python docker-compose解析不了。所以看到这类错误第一反应不是去改compose文件而是先检查compose工具版本。6.2 QEMU模拟环境性能翻车我有一台x86开发机想验证arm64离线包内容图省事用QEMU起了个arm64 Ubuntu虚拟机内存4GBCPU 4核。安装阶段进展顺利但到docker load那一步明显变慢一个harbor.v2.13.1.tar.gz刷了差不多十几分钟容器全部启动后又感觉UI访问偶发卡顿。这个现象在纯QEMU模拟环境下很正常毕竟整套系统指令集都被翻译执行性能和平常的KVM虚拟机不是一个量级。如果只是验证包能不能装、步骤对不对可以尝试如果是正式环境或需要频繁推拉镜像建议还是用arm64物理机或带硬件虚拟化的云主机别拿模拟环境顶包。6.3 内存不足、端口冲突、hostname遗漏剩下三个问题虽然不只在ARM上出现但在ARM小机器上特别典型。内存不足最容易发生在4GB内存的板子或虚拟机上表现是安装日志显示postgresql容器一直在重启或者容器状态从Up变成Restarting。排查方法很简单dmesg | grep -i oom看到OOM相关日志就说明内存爆了。加swap、关掉不用的扩展组件都能缓解。端口冲突则常见于服务器上已经跑了nginxHarbor默认也要监听80一启动就提示address already in use。这种直接把harbor.yml里的http.port改成8080或其他空闲端口就行不用去停掉已有服务。hostname遗漏问题我在前面说过一次但值得再强调一遍。很多默认模板里的hostname是示例域名如果你不想改、直接照抄装完以后会发现后台虽然能进但Docker客户端执行docker login时又是证书不匹配又是域名解析失败实际体验非常别扭。所以config文件里hostname这一项一定要改成你自己的IP或规划好的域名这是部署Harbor最容易忽略但也最影响后续使用的配置。为了方便排查我把ARM环境Harbor部署的高频问题整理成一张表现象可能原因排查命令解决办法容器反复重启内存不足触发OOMdmesg | grep -i oom加swap或加内存80端口无法绑定已有进程占用ss -tlnp修改http.portdocker login失败、证书不匹配hostname用了默认域名docker login -v修改hostname并让客户端信任证书安装阶段报compose错误compose工具缺失或版本过旧docker compose version安装docker-compose-plugin我在几台arm64机器上重复部署了几次之后最深的体会就是一句话架构先对了后面的路才好走。别看只是一个离线包的选择选错架构后面所有的报错排查都在浪费时间。装完再顺手把证书、备份、自启这三件事处理掉Harbor基本就能长期稳定跑。最后再分享一个小技巧如果机器配置紧张不用急着把扩展组件全开满先把核心的registry、core、database跑起来业务顺了再逐步加功能运维压力会小很多。本文还有配套的精品资源点击获取