简介面向需要在ARM架构服务器上离线部署镜像仓库的运维与开发人员该离线安装包提供Harbor v2.9.0的完整安装组件解决内网或隔离环境中无法直接拉取软件包、依赖配置繁琐的问题。包内共6个文件以可执行shell安装脚本和离线容器镜像包为核心同时包含license许可文件、prepare预检脚本及harbor.yml.tmpl配置模板整体约722.35MB覆盖从环境预检、配置生成到镜像加载的完整链路。执行install.sh即可一键安装但需预先安装Docker与Docker Compose环境准备脚本可校验依赖并生成所需配置配置模板支持按需调整端口、存储路径等参数离线镜像包则省去逐一下载组件镜像的步骤。配套部署说明文档能帮助不熟悉Harbor的读者快速理清架构。目前已有959人学习下载适合具备基础容器知识、希望在ARM平台快速落地镜像仓库的读者可显著减少手动部署中的版本兼容与排错成本。 先交代一个背景:我这次部署的机器是ARM架构的服务器,操作系统是麒麟v10,环境处于完全的离线内网。Harbor v2.9.0的离线安装包官方其实提供了,但在ARM机器上跑,和x86最大的区别在于两点:基础组件的架构匹配,以及Harbor内置镜像的架构对应关系。官网文档默认你用的是amd64,所以你跟着官方步骤走,卡在中间某个环节是非常正常的事。这篇文章就是我这次完整操作的复盘,把每一步的逻辑、配置和踩过的坑都尽量说清楚。如果你当前也在做类似的事——在ARM架构服务器上部署Harbor v2.9.0,而且网络受限只能离线安装——这篇文章能帮你节省大量试错时间。内容包括前期选型思路、离线安装包准备、Docker和Docker Compose的离线安装、harbor.yml的编写要点、安装流程拆解,以及在ARM环境下的常见坑和排查方法。1. 安装背景与方案选型1.1 为什么选Harbor v2.9.0,为什么是ARM环境Harbor是目前企业内网用得最多的开源镜像仓库,功能上覆盖了镜像存储、权限控制、复制同步和漏洞扫描,基本能满足私有仓库的全部需求。选择v2.9.0而不是更新的版本,主要考虑的是稳定性。2.9.0这个版本在我实际使用中与Docker 20.10和Docker Compose v2.x的兼容性都很稳定,OCI镜像规范的支持也完整。在ARM架构机器上,镜像仓库本身就是基础设施,选一个经过验证的版本比追求新功能更重要。ARM架构在服务器端的占比这两年上升得非常快,尤其是国产化替代背景下,很多项目都跑在基于ARM的处理器上。但一个现实问题是,大量基础软件的官方安装脚本和文档都以x86_64为主,导致同样的软件在ARM上部署时,总会冒出版本不匹配、架构不兼容之类的异常。Harbor官方虽然发布了适配ARM的安装包,但实际安装链路里还有Docker、Docker Compose、基础依赖这一整套东西要配合,这才是离线部署的真正难点。1.2 离线安装与在线安装怎么选在线安装很简单:装好Docker之后,直接把harbor的docker-compose项目拉下来,再执行install脚本,镜像会从远程仓库自动拉取。但内网环境没有外网连接,所有安装包、镜像包都必须提前准备好再传进去。离线安装的流程本质上也没有多复杂,就是把在线安装过程中“自动完成”的事情拆成手动步骤:提前获取Harbor离线安装包(内含所有Harbor组件镜像的tar包)提前准备好Docker、Docker Compose的安装包把安装包传到内网服务器后,先装基础环境,再执行Harbor安装脚本这里我建议你在搞离线安装之前先确认一个前提:内网是否真的完全隔离。如果还有一台能访问外网的跳板机,可以通过代理方式拉镜像,步骤会简化很多。但如果目标环境是绝对隔离的,那下面这套全离线方案就直接套用。另外一个选型细节是,如果你们的ARM服务器数量多,建议在一台机器上验证好整套离线包,然后把“安装包安装脚本”整体归档,通过内网文件服务器分发。这样后续批量部署时,每台机器只需要重复执行安装流程,省去反复排查依赖的时间。2. 离线安装包准备与架构匹配2.1 需要提前准备的软件清单在开始之前,列一个完整的准备清单,避免到了内网发现缺包。以下是我这次实际用到的软件和版本:软件版本要求用途harbor-offline-installer-v2.9.0.tgzv2.9.0Harbor主程序离线安装包,内含全部Harbor镜像docker-ce20.10及以上容器运行引擎docker-compose-pluginv2.3.0及以上Docker Compose V2插件,Harbor启动依赖python33.6及以上Harbor的prepare阶段会用到tar、openssl等基础工具系统自带即可解压与证书生成关键的下载细节:Harbor离线安装包的命名里不会区分架构,它就一个包名——harbor-offline-installer-v2.9.0.tgz。但这个包内包含了对应平台的Harbor镜像,ARM和x86的包其实内容不同,下载时需要根据自己服务器的CPU架构在release页面选择对应平台的包。我当时就是在下载时没注意,下成了x86版,结果docker load阶段直接报错,镜像平台不匹配。Docker和Docker Compose插件这边也要注意架构区分,下载时选择aarch64或arm64的包。Docker官方仓库提供不同发行版的软件包,如果服务器是Ubuntu就用deb包,如果服务器是CentOS或麒麟这类基于RPM的系统,就准备rpm包。我这里用的是麒麟v10,准备的rpm包,后面安装时直接用rpm -ivh *.rpm一把装完。2.2 架构匹配的隐含坑ARM架构这里有一个容易忽略的层级问题。机器本身是aarch64内核,但上面跑的系统和应用都必须是arm64版本。理论上讲,arm64的Docker可以直接运行。但因为Harbor离线包里的容器镜像,如nginx、postgresql、redis等,都是单独打包的,如果镜像本身是amd64架构,即使docker load能加载,容器运行时也会报fork/exec format error。所以在准备阶段,务必确认三点:服务器CPU架构是aarch64,使用命令uname -m确认下载的Harbor离线包是arm64版本,可以在有网机器上先解压检查一下包内镜像的架构标签Docker和docker-compose-plugin都安装了对应的arm64版本我踩过最冤的一个坑就是包下载正确,但docker-compose-plugin下错了架构。安装时没有任何报错,但执行docker compose version没反应,一查发现是rpm包与系统架构不匹配。很多时候问题不在Harbor本身,而在基础组件,所以准备阶段多花几分钟检查架构,后面能少折腾半天。3. 基础环境配置与校验3.1 ARM服务器上安装Docker离线环境里安装Docker,我一般习惯先把所有rpm包下载到一个目录下,然后在内网机器上执行本地安装。由于依赖较多,rpm安装时可能会出现缺少依赖包的情况,所以前期把依赖关系解决好是关键。最稳妥的方式是:在一台可以联网的同架构机器上,用yum命令把docker相关的rpm全部下载下来,再拷贝到内网。如果你手头已经有内网yum源,也可以直接配置本地repo然后yum install docker-ce,这个方式最省事。没有内网源就只能用rpm离线安装。安装完成后可以做一个快速验证。不要急着启动Harbor,先把docker服务启动并检查Docker版本,同时确认Docker能正常运行容器。我一般会拿一个最简单的arm64镜像测试一下容器能不能起来,确保引擎没问题,再去装Harbor。3.2 Docker Compose插件与版本匹配Harbor v2.9.0的install.sh脚本在执行的时候会检查docker compose的版本,要求不低于v2.3.0。所以安装完Docker之后,第一件事是确认docker compose命令存在且可用。新版Docker把Compose做成了插件方式,安装docker-compose-plugin这个包后,Docker的compose子命令就是可用的。注意命令形式是docker compose,中间有个空格,不是以前独立的docker-compose。还有一个容易忽略的细节:如果你之前装过旧的docker-compose二进制文件,它可能会和新的compose插件命令冲突,导致Harbor的install.sh脚本校验时读取到旧版本,然后报版本过低。我这次就遇到过这个情况,系统里原本残留了一个docker-compose 1.25版本,去掉之后才正常。3.3 磁盘、端口与系统依赖检查Harbor安装完成后,镜像数据、数据库、Redis日志都放在data_volume指定的目录下,默认是/data。离线包本身大约1GB左右,但镜像加载之后占用的磁盘空间会迅速增长,尤其是后面往仓库里推送镜像,空间占用只会越来越大。建议给data_volume所在分区预留充足的磁盘空间,至少40GB以上。端口方面,Harbor默认使用80端口提供HTTP服务。如果80端口被其他服务占用,可以改到其他端口,比如8080。修改端口之后,客户端机器上的Docker配置也要同步修改。配置文件harbor.yml里还有一个hostname字段,这个字段非常重要,后面单独说。系统依赖这部分容易忽略的是python3。Harbor安装脚本在prepare阶段会调用python3来解析和生成配置,如果系统里没有python3,安装会在prepare步骤报错。现在主流Linux发行版一般默认自带python3,但精简系统可能要额外装一下。检查python3 --version确认一下即可。4. Harbor配置与离线安装执行4.1 编写harbor.yml先把离线安装包解压,执行:tar -zxvf harbor-offline-installer-v2.9.0.tgz cd harbor解压后目录里有一个harbor.yml.tmpl模板文件。安装脚本要求当前目录存在harbor.yml,如果不存在,它会自动把模板复制为harbor.yml。实际操作中我建议手动复制模板,然后一处处改清楚,再执行安装脚本。手动改配置可以避免用默认配置导致的一些基础问题。以下是我这次实际使用的harbor.yml核心配置:hostname: 192.168.10.50 http: port: 80 https: port: 443 certificate: /data/cert/harbor.crt private_key: /data/cert/harbor.key harbor_admin_password: Harbor12345 database: password: root123 max_idle_conns: 50 data_volume: /data log: local: rotate_count: 10 rotate_size: 100M location: /var/log/harborhostname字段唯一推荐写法:如果内网有可靠DNS解析,可以写域名;如果没有,直接写IP。写错hostname的最常见后果是客户端push镜像时报错hostname不匹配。实际使用中,如果客户端都是通过IP访问,直接填IP是最省心的方案。http和https这里我分开说明一下。默认模板里https是注释掉的,意味着只以HTTP协议启动。如果启用HTTPS,一定要提前生成证书并且确认证书文件路径能被Harbor进程读取。我们这次生产环境要求走HTTPS,证书提前放到/data/cert目录,并且注意文件权限,否则Nginx配置阶段会因为证书读取失败而报错。如果你的环境对加密没有强要求,先用HTTP模式跑通流程也是可以的,后期再加证书。还有一个容易忽略的配置项是database.password。这个密码用于Harbor内置PostgreSQL数据库,如果服务器上装了其他的PostgreSQL实例,注意端口冲突问题。Harbor默认使用5432端口作为内置数据库端口,如果你的服务器5432端口已被占用,需要在这里改掉。4.2 执行install.sh配置文件准备好后,直接执行:sudo ./install.shinstall.sh整个流程大概分三块:预检查、导入镜像、启动服务。预检查主要是确认docker、docker compose的版本和基本环境;导入镜像阶段会读取当前目录下的Harbor镜像压缩包,通过docker load把所有Harbor组件镜像导入;最后调用docker compose up -d把服务整体拉起。ARM架构的机器上,镜像导入的过程可能会比x86上慢一些,这是正常的。我这次大概等了3分钟左右,主要是几个大镜像解压耗时。如果发现某个镜像load报错,优先怀疑镜像包架构不匹配,而不是怀疑安装脚本。启动完成后,install.sh会输出一段提示,告诉你可以通过哪个地址访问Harbor。此时可以再用docker compose ps确认所有服务的状态,我这边看到的状态是全部healthy或者up。如果某个服务没有起来,不要急着重新执行install.sh,先去查日志,定位具体原因,常见的是端口冲突、权限不对、磁盘空间不足。4.3 安装后的验证与使用服务起来了不算完,按照我的习惯,一定会在客户端机器上完整走一遍登录、推送、拉取的流程,确保仓库真正可用。在客户端机器上,如果Harbor配置的是HTTP协议,需要在Docker配置文件/etc/docker/daemon.json里把Harbor地址加入insecure-registries:{ insecure-registries: [192.168.10.50] }然后重启Docker。这个操作非常关键,否则客户端登录或者push镜像时会报证书相关的错误。验证过程如下:docker login 192.168.10.50 docker tag nginx:latest 192.168.10.50/library/nginx:latest docker push 192.168.10.50/library/nginx:latest docker pull 192.168.10.50/library/nginx:latest如果你准备的是ARM镜像,推送上去之后,其他ARM机器上可以正常拉取使用。这里也顺便提一句,Harbor支持批量复制镜像或者在界面上直接创建项目。内网环境如果有多台机器需要访问仓库,建议先在Harbor里建好项目和用户权限,不要都用一个admin账号裸奔。权限这块即使内网环境也值得花点时间做好,后续维护省很多事。5. 常见问题与排查技巧实录5.1 高频问题速查表这次部署下来,我把在ARM离线场景里会高频遇到的问题整理成了一个速查表,后面再部署可以直接对照排查:现象可能原因解决方案docker load镜像时报错离线包架构不匹配检查并替换为arm64版本的Harbor离线包/proc/sys/kernel/... 相关报错Docker与内核版本兼容问题升级内核或升级Docker到适配版本容器启动后自动退出data_volume目录权限不对检查/data目录拥有者是否可写Nginx容器无法读取证书证书文件权限过大或路径错误确保证书放在可读路径且权限不超过600prepare阶段报python相关错误系统缺少python3安装python3并确认可用客户端登录时提示证书不受信任daemon.json未配置insecure-registries添加Harbor地址到insecure-registries并重启Dockerinstall.sh检查compose版本失败系统存在旧版docker-compose卸载或移除旧docker-compose二进制Push大镜像时卡住磁盘空间不足或网络栈问题检查data_volume磁盘余量,检查网络吞吐表格里列的是最直白的现象对应解法,但有几个问题实际排查起来比表格里复杂,我再单独展开说。5.2 几个值得展开的坑第一个是Harbor服务起来之后访问不了Web界面。这个问题的排查方向至少有四层:第一层确认服务本身是不是起来了,用docker compose ps查看;第二层确认宿主机防火墙有没有放行80端口,很多内网机器默认防火墙策略很严,80或者8080端口没有放行的话,外部访问一定失败;第三层确认浏览器访问的地址和harbor.yml里的hostname策略是否一致,如果你配置的是域名但本机没有做DNS解析,浏览器访问域名会解析失败;第四层是访问的是不是HTTP协议,如果配置了https但浏览器用http访问,会被Nginx直接拒绝,反之亦然。遇到访问问题,按层级一步步查,不要上来就怀疑Harbor安装有问题。第二个是关于日志。Harbor自身的日志默认写在/var/log/harbor目录下,里面每个组件对应一个子目录。排查问题的时候我最常看的是core和nginx这两个目录的日志。比如登录失败、推送超时、复制失败这类问题,在core日志里基本都能看到具体原因。如果你改过log.location配置,日志位置会跟着变。第三个是关于ARM环境的性能表现。ARM服务器上跑Harbor,日常使用完全没问题,但并发推送多个大镜像时,PostgreSQL容器和Redis容器的CPU占用会明显升高。所以如果内网使用人数多,界面上尽量给不同团队分配独立项目,避免所有镜像都堆在一个项目里,同时可以通过Harbor的垃圾回收功能定期清理无用的镜像和blob。磁盘膨胀问题在内网环境里特别普遍,养成定期清理的习惯能省不少事。第四个要单独说的是daemon.json的配置顺序。如果你在daemon.json里既配置了内网Harbor地址,又配置了其他仓库的地址,注意不要有重复和冲突。改完daemon.json一定记得重启Docker,否则配置不会生效。另外,如果你用的是containerd运行时,比如Kubernetes节点上的情况,登录凭据的配置方式会和Docker不一样,需要单独处理。最后再分享一个我个人的建议:Harbor部署完成后,第一时间备份harbor.yml、证书文件,以及/data下的关键配置目录。等以后要升级版本或者迁移机器的时候,这套备份会发挥很大作用。离线部署本来就比在线环境麻烦,前期把这些细节做扎实,后面维护起来就顺滑得多。本文还有配套的精品资源点击获取