ARM内网离线部署Harbor镜像仓库：从arm64离线包到避坑实战

简介面向ARM64架构环境这份Harbor离线安装包专门用于在无外网或网络受限的机房、边缘节点部署容器镜像仓库。Harbor 2.8.2版本支持镜像推送拉取、权限管理、复制和扫描等企业级功能适合运维人员、Kubernetes集群管理者在国产化或ARM设备上快速搭建服务。压缩包共6个文件包括install.sh与prepare等安装准备脚本、harbor.v2.8.2-arm64.tar.gz镜像主包、LICENSE许可文件以及harbor.yml.tmpl配置模板整体大小约639.65MB解压后即可参照模板完成基本配置。离线化的设计规避了安装期间对外部软件源和镜像仓库的依赖尤其适合保密要求高、外网接入受限的环境。已有260人浏览学习对于需要低功耗、高能效比部署Harbor的ARM平台使用者而言这份包含完整安装脚本与配置模板的离线包能显著降低环境准备和排错成本帮助快速获得可用服务。1. 上不了外网的 arm 环境为什么绕不开这个 arm64 离线包一个上不了外网的 arm 环境里自建 Harbor 镜像仓库最先卡住的不是 Harbor 配置而是镜像本身怎么进去。harbor-offline-installer-v2.8.2-arm64.tar.gz 这包离线包把 goharbor 全家桶的 arm64 镜像、安装脚本和配置模板打进一个 tar.gz内网机器解压、改一个 harbor.yml、跑 install.sh三步就能得到一个能 push/pull 的 registry。我按在麒麟 V10、openEuler aarch64 上的落地经验写这篇覆盖离线包结构、安装参数、验收闭环以及 arm 内网部署时躲不开的五条坑。适合要给信创 arm 服务器搭镜像仓库、做 harbor 版本升级或手工维护内网 registry 的运维。2. 拆开 arm64 离线包的内部结构离线装和在线装差在哪2.1 为什么 arm 内网必须用 offline-installerHarbor 的在线安装脚本 install.sh 本质是一个拉取器安装时它要从 Docker Hub 或 Quay 上把 goharbor/harbor-core、goharbor/harbor-registry 这一串运行镜像拉到本地再用 compose 把容器编排起来。这个流程在能联网的 x86 机器上很顺但放到 arm 内网就两头都对不上。一是根本没有外网任何 docker pull 都失败二是官方镜像默认标签大多数是 linux/amd64 的就算有网络拉下来的镜像在 aarch64 机器上跑起来也会直接报 exec format error而不是优雅地提示你架构不对。离线包把这件事换了个做法包里的镜像在发布端就已经用 docker save 导出成归档install.sh 检测到本机环境后先执行 docker load 把这些 arm64 镜像导入本地再走 prepare 生成 compose 文件、起服务。也就是说离线包解决的问题是把「下载镜像」这个动作从安装时挪到了打包时内网机器只要能读 tar.gz 就行。安装时整个过程不碰外网连 Docker Hub 的连通性检查都没有。命名上也能看出门道官方对同一版本一般给出 amd64 和 arm64 两套产物文件名里写 arm64 的就是给 aarch64 用的对应鲲鹏 920、飞腾 FT-2000/64 这类信创机器。你在目标机上先执行 uname -m确认输出是 aarch64 再动手。这个流程跟 docker离线安装arm架构mysql 是一个套路先 load 镜像归档再在本地把容器跑起来区别只是 Harbor 的编排更重依赖 compose 和服务间网络容错空间更小。2.2 解压后里面是什么哪些文件要改、哪些别动拿到包先不急着跑先看清楚里面有什么。查看和解包我都用 tar 的常规参数tar -tzvf harbor-offline-installer-v2.8.2-arm64.tar.gz | head -20 mkdir -p /opt/harbor-pkg tar -zxf harbor-offline-installer-v2.8.2-arm64.tar.gz -C /opt/harbor-pkg cd /opt/harbor-pkg/harbor ls -lh第一条命令是 dry-run 查看包内清单不解压就能看到文件层级我习惯先跑它确认包没损坏、顶层目录是 harbor/ 而不是散落一堆文件。后两条才是正式解压。解压出来的目录里需要关注的是这几个文件install.sh 是安装入口prepare 负责根据 harbor.yml 生成 docker-compose.ymlharbor.yml.tmpl 是配置模板harbor.v2.8.2.tar.gz 就是那一大坨镜像归档。有个容易忽略的细节harbor.yml.tmpl 是模板别直接在它上面改正确做法是复制一份成 harbor.yml 再编辑。prepare 每次执行都会重新读模板生成配置你要是改了模板又覆盖了 harbor.yml之前手工改的参数会丢。install.sh 和 prepare 都是 shell 脚本内网环境想确认它到底干了什么直接 grep 一下加载镜像那一段比自己瞎猜可靠。2.3 落地前十分钟的环境预检三条命令挡掉一半故障arm 环境最不友好的地方是「环境不统一」同样叫 aarch64实际可能是麒麟 V10 SP2、openEuler 22.03 LTS、Ubuntu 22.04 ARM 或者 UOSdocker 的来源五花八门有的来自系统源有的是运维手工拷进去的二进制。我习惯在解包后先跑一组预检把结果记进安装记录后面排错有依据uname -m # 期望 aarch64 docker version --format {{.Server.Version}} # 期望 20.10 或更高 docker compose version || docker-compose --version df -h /data df -i /datauname -m 期望输出 aarch64输出 armv7l 说明机器是 32 位用户态输出 x86_64 说明包选错了。docker 版本方面Harbor 2.8.x 对引擎版本有硬性要求官方文档给的底线是 17.06但我实际遇到在麒麟上跑 openEuler 源里的 20.10.x 最稳太老的 18.09 配合 compose v2 会有兼容性问题。第三条命令最容易翻车很多 arm 系统自带的 docker 只有引擎没有 compose 组件这条会直接报 command not found先补上再继续。最后一行 df 同时看 space 和 inode 两项。/data 是 Harbor 默认数据目录强烈建议单独挂数据盘并留出至少 50GB 给 registry 存储和数据库。inode 用尽在大分区上不常见但如果你把数据目录放在一个只有几 GB 的小分区推几个大镜像后镜像层目录把小盘 inode 吃完报错会是 no space left on devicedf -h 却显示还有空间这种玄学问题在排查时能浪费一上午所以预检时把 df -i 也扫一眼。3. 离线落地全流程改配置、跑 install.sh、推一个 arm 镜像3.1 harbor.yml 必改的四项hostname、端口、数据目录、Trivy配置入口是把模板复制成正式配置cp harbor.yml.tmpl harbor.yml vi harbor.yml我一般只动四个地方其余保持模板默认。下面是我在 intranet 场景里常用的最小配置段hostname: 192.168.10.21 http: port: 8080 # https: # port: 443 data_volume: /opt/harbor-store trivy: ignore_unfixed: false skip_update: true offline_scan: true insecure: truehostname 不要写 localhost客户端 docker 会拿它拼仓库地址写成内网 IP 或 FQDN 都行。http.port 我改成 8080是为了避开 80 端口上可能存在的其他服务如果确定 80 空闲保持默认也行。https 配置段注释掉之后prepare 会生成纯 http 的 nginx 配置内网环境够用。提示如果保留 https 段nginx 会同时监听 443 并自动生成自签证书客户端要么配 insecure-skip-verify要么把证书导入 docker 证书目录比 http 多一层配置内网没必要。data_volume 是 registry 存储、数据库文件和密钥的总目录务必指向独立数据盘。trivy 段的 skip_update 和 offline_scan 两个参数是离线环境的救命配置后面第 4 章专门讲它。这几个参数再列成一张表方便对照配置项内网建议值说明hostname内网 IP 或 FQDN客户端拼仓库地址用别用 localhosthttp.port8080避开 80减少端口冲突data_volume/opt/harbor-store指向独立挂载的数据盘trivy.skip_updatetrue离线必须否则扫描器反复拉漏洞库3.2 执行 install.sh两个开关与一条日志命令配置改完后安装只有一条命令sudo env HARBOR_ADMIN_PASSWORDHarbor2024Admin ./install.sh --with-trivy --with-chartmuseumenv 变量是给 Harbor 指定初始 admin 密码避免用默认的 Harbor12345 裸奔装完还能在 UI 里再改。--with-trivy 开启漏洞扫描组件--with-chartmuseum 装 Helm Chart 仓库没有 Helm 需求就别加组件越少arm 上出问题的面越小。install.sh 是幂等的重复执行不会把已有配置搞坏跑失败了大可以修完配置直接再跑一次不用卸了重来。脚本执行过程中会自动完成 docker load、prepare 和 compose up 三步中间会打印每步的状态。装完马上看容器状态和日志不要急着关终端sudo docker ps --format table {{.Names}}\t{{.Status}} tail -f /var/log/harbor/core.logdocker ps 里应该能看到 harbor-portal、harbor-core、harbor-registry、harbor-jobservice、harbor-db、harbor-redis、harbor-nginx、harbor-log 这八个容器加上装了 trivy 后出现的 harbor-trivy。日志统一收在宿主机 /var/log/harbor 目录下core.log 是核心入口日志起不来先看它比在 UI 上瞎猜快得多。3.3 验收闭环API 探活、配置 insecure registry、推拉镜像安装成功不等于可用我验收固定走三步。先探 API登录和系统信息都能通说明核心服务在线curl -u admin:Harbor2024Admin http://192.168.10.21:8080/api/v2.0/systeminfo能返回一串 JSON 就说明 HTTP 链路通了。第二步是给本机 docker 配置 insecure registry否则 docker login 到 http 仓库会被拒绝sudo tee /etc/docker/daemon.json EOF { insecure-registries: [192.168.10.21:8080] } EOF sudo systemctl restart dockerrestart docker 会把 compose 管理的 Harbor 容器一并重启正常情况下会自动拉起如果没起来cd 到 harbor 目录手动docker compose up -d补一下。所以更稳妥的顺序是先配 daemon.json 再跑 install.sh避免启动后多一次重启。第三步是登录、打 tag、推镜像冒烟一下完整链路docker login 192.168.10.21:8080 -u admin docker tag goharbor/harbore-core:v2.8.2 192.168.10.21:8080/library/test-arm:1.0 docker push 192.168.10.21:8080/library/test-arm:1.0镜像名字可以随意用本机 docker images 里现成的任意镜像不需要联网拉新的。push 成功后其他 arm 节点从这台仓库拉镜像下载就能走内网速度比外网快也不依赖外网。这里 tag 里的 library 是 Harbor 内置的公开项目如果你想建独立项目先到 UI 上创建再用项目名替换。4. 麒麟 aarch64 上装 Harbor 避坑指南五个现场常见的坑arm 环境装 Harbor 最容易出问题的点不在 Harbor 本身而在它脚下的 docker、系统、网络这三层。以下五条是我和周围同事踩过的按现象、原因、解决三个层面拆现场排查可以直接对着找。4.1 现象docker load 成功容器全部报 exec format error原因拿成了 amd64 的离线包或者从 x86 机器上 docker save 出镜像再 load 到 arm 机器。docker load 不校验架构归档能进本地镜像库但容器一启动内核发现可执行文件架构不匹配直接抛 exec format error。解决先uname -m确认目标机器是 aarch64再用docker image inspect goharbor/harbor-core:v2.8.2 --format {{.Architecture}}看已加载镜像的架构。确认包不对就回去重新下载文件名里带 arm64 的离线包别图省事从 x86 仓库搬运镜像。4.2 现象install.sh 卡在依赖检查提示 docker-compose 找不到原因openEuler、麒麟的系统源里自带的 docker 往往只有引擎不带 compose 组件还有的机器装了 compose v2 插件但 install.sh 找的是 docker-compose 命令两边名字对不上就退出。解决常见做法是把 docker-compose v1 的 arm64 静态二进制放到 /usr/local/bin再把 compose v2 插件放到 /root/.docker/cli-plugins/docker-compose两个都备着。docker compose version和docker-compose --version都看一眼确认能输出版本号再跑 install.sh。这一步在 arm 机器上比 x86 常见得多因为很多人只在 x86 上用系统包管理器装过 docker-compose。4.3 现象安装脚本跑完harbor-nginx 一直重启端口不通原因80 或 443 已经被宿主其他服务占用nginx 容器绑定端口失败反复重启或者麒麟自带的防火墙、SELinux 拦了容器端口映射curl 表现为连接拒绝。解决ss -tlnp | grep 8080看端口占用把 harbor.yml 里的 http.port 改成 8080、8081 之类避开。防火墙用firewall-cmd --add-port8080/tcp放行SELinux 可以先setenforce 0做临时验证长期方案是改 /etc/selinux/config 或按日志放行对应服务。改完配置重跑 install.shcompose 会重建容器。4.4 现象开了 --with-trivy扫描任务永远停在 Scanningjobservice 日志刷漏洞库下载失败原因Trivy 扫描器第一次运行要联网下载官方漏洞数据库内网环境拿不到任务就一直挂起界面上所有镜像的扫描状态都是 Scanning。解决在 harbor.yml 的 trivy 段加skip_update: true和offline_scan: true然后重跑 install.sh 重新生成 compose 配置这样 trivy 容器启动时不会去抢式下载。如果你确实需要实时漏洞数据常见做法是在有网的机器上把 trivy 的漏洞库目录cache 目录打包导出再挂载进 harbor-trivy 容器具体路径按你选的 trivy 版本定我一般先用 skip_update 保证服务可用。4.5 现象Harbor 能起来推几个大镜像后写磁盘报 no space left on device原因data_volume 默认 /data没单独挂盘镜像层、数据库、日志全压在根分区上推几个几百 MB 的镜像就把分区撑满也有小分区 inode 被镜像层小文件吃光的情况df -h 看着有空间但就是写不进去。解决安装前df -h和df -i一起看data_volume 务必指向独立数据盘比如 /opt/harbor-store。装完再迁移数据目录很麻烦涉及 compose 文件、容器挂载和权限宁可开工前多花十分钟规划盘位。日志目录 /var/log/harbor 也要留意长时间运行能攒出好几个 GB。5. 装好只是开始备份、升级和日常校验的三个固定动作离线包能装起来只是第一步真正决定这台上线机器能活多久的是后续动作。我现在任何一台 arm 内网 Harbor 部署都会固定做三件事。第一件事是留档案。离线包下载完立刻算 sha256连同解压目录、harbor.yml 一起归档sha256sum harbor-offline-installer-v2.8.2-arm64.tar.gz install-artifacts.sha256 cp harbor.yml /opt/harbor-pkg/harbor/harbor.yml.orig这个习惯救过我一次半年后要复现环境原包早就不知道丢哪了靠归档的 sha256 确认了和备份包一致才敢拿它去恢复。第二件事是备份。任何写库操作升级、改配置、迁移之前先停服务再打包数据目录这是保证 PostgreSQL 数据文件一致性的最稳妥做法cd /opt/harbor-pkg/harbor sudo docker compose down sudo tar -czf /backup/harbor-data-$(date %F).tar.gz -C /opt/harbor-store . sudo docker compose up -d如果要更细粒度地备份单个数据库常见做法是对 harbor-db 容器做 pg_dump。但注意这只备份了逻辑数据registry 里的镜像层文件还得靠 data_volume 目录备份两个是互补关系别只做一半。第三件事是升级走固定路径。harbor 版本升级时不要直接删目录换新包新离线包解压到同一路径、保持 data_volume 不变然后执行sudo ./install.sh --upgrade脚本会先跑数据库迁移再重建容器。版本跨度大时先查官方支持的升级路径比如 2.8.x 升 2.9 通常没问题跳大版本要谨慎。升级完用第 3.3 节的 systeminfo 和 push/pull 冒烟一遍再放行。我吃过最大的亏是把时间省在备份上结果一次跨版本升级把项目元数据搞丢镜像还在仓库结构全乱。现在我的固定习惯就是下载完留 sha256写库前先 down 服务打包数据卷升级前后各冒烟一次。希望帮到你。本文还有配套的精品资源点击获取