ARM服务器离线部署Harbor：ARM64离线包安装与推送避坑指南

简介这份资源是面向ARM64架构环境的Harbor容器镜像仓库离线安装包专为在边缘计算、物联网及国产化ARM服务器上部署私有镜像仓库的运维与开发人员准备可解决无外网或网络受限场景下无法在线拉取安装文件的问题。压缩包共6个文件以sh安装脚本、gz镜像归档、license许可文件、prepare预检脚本及tmpl配置模板为主整体约639.65MB解压后即可按手册完成部署与参数调整。目前已有261人学习下载适合需要快速落地企业级镜像管理的中高级用户参考。借助该离线包读者可省去逐一下载依赖的繁琐流程直接获得完整的安装脚本、镜像归档与配置模板便于在隔离环境中完成Harbor 2.8.2的搭建、权限配置与后续镜像分发验证。1. ARM 服务器上装 Harbor为什么离线包才是正解在国产化替代和信创项目里ARM 架构服务器已经不是什么新鲜事鲲鹏、飞腾、麒麟 V10 这些组合我这两年碰得越来越多。但每次要在这种环境里搭一套私有镜像仓库最头疼的往往不是 Harbor 本身而是网络——很多生产环境压根不通外网或者只开放极少数白名单端口docker pull直接卡死。这时候harbor-offline-installer-v2.8.2-arm64.tar.gz这种离线包就成了刚需它把 Harbor 的核心组件镜像、安装脚本、配置文件全部打包好解压即用不需要在目标机器上一条条拉镜像。这篇文章就是围绕这个 ARM64 离线包把从环境准备到推送验证的完整链路拆开讲顺带把几个我踩过的坑摆出来让你少走弯路。2. 拆开离线包里面到底装了什么为什么 ARM64 不能混用 x86 包2.1 离线包与在线安装的本质区别Harbor 官方提供两种安装方式在线安装和离线安装。在线安装的install.sh会在执行时从 Docker Hub 拉取十几个组件镜像包括harbor-core、harbor-portal、harbor-db、redis、nginx等。离线包则把这些镜像提前docker save成 tar 文件放在harbor/images目录下安装时直接docker load导入本地。对于 ARM 环境这个区别更关键——ARM64 的镜像和 x86_64 的镜像不是同一套 manifest你拿 x86 的离线包在鲲鹏上跑docker load能成功但docker run时会报exec format error因为二进制指令集对不上。harbor-offline-installer-v2.8.2-arm64.tar.gz这个包名里v2.8.2是 Harbor 版本arm64是架构标识。解压后你会看到这样的目录结构harbor/ ├── harbor.v2.8.2.tar.gz # 所有组件镜像的打包文件 ├── harbor.yml.tmpl # 配置模板 ├── install.sh # 安装入口脚本 ├── prepare # 环境预检脚本 └── common.sh # 公共函数库其中harbor.v2.8.2.tar.gz是核心里面是十几个docker save出来的镜像层。install.sh会调用prepare检查 Docker、Docker Compose 版本然后加载镜像、渲染配置、启动容器。2.2 为什么必须确认 ARM64 架构匹配我见过有人把 x86 的 Harbor 离线包直接扔到飞腾服务器上install.sh跑完没报错但访问 UI 时 502查docker ps发现harbor-core容器不断重启。docker logs harbor-core里一行standard_init_linux.go:228: exec user process caused: exec format error就是答案——镜像里的二进制是 x86 指令集ARM CPU 执行不了。确认方法很简单在目标机器上执行uname -m输出aarch64或arm64才可以用这个包。如果是x86_64那就得换对应的 x86 离线包。另外注意有些国产化环境虽然 CPU 是 ARM但操作系统可能是 32 位的 ARMv7那arm64包同样跑不起来必须用arm或armv7的包。uname -m输出armv7l就属于这种情况。2.3 解压与预检别跳过 prepare 脚本拿到 tar.gz 后第一步是解压tar -zxvf harbor-offline-installer-v2.8.2-arm64.tar.gz cd harbor解压后不要急着改配置先跑一次预检./prepare这个脚本会检查 Docker 是否安装、Docker Compose 版本是否满足、端口 80/443 是否被占用。如果 Docker 没装它会提示你先装 Docker。在 ARM 环境里Docker 的安装本身也可能是个坑——很多国产 OS 的默认源里没有docker-ce需要手动配置 ARM64 的仓库地址。我一般会先确认docker --version docker compose versionHarbor v2.8.2 要求 Docker 17.06 和 Docker Compose 1.18。如果docker compose命令不存在可能是只装了docker-compose带横杠的旧版需要建个软链或者升级。预检通过后再进入配置环节。3. 配置 harbor.yml从模板到可运行实例的关键参数3.1 复制模板并修改 hostname 与端口harbor.yml.tmpl是配置模板直接复制一份cp harbor.yml.tmpl harbor.yml然后编辑harbor.yml最核心的几个参数hostname: 192.168.209.133 http: port: 80 https: port: 443 harbor_admin_password: Harbor12345 data_volume: /data/harborhostname必须改成目标机器的 IP 或域名不能保留reg.mydomain.com。这个值会写进 Docker 的daemon.json和 Harbor 的配置里如果填错后面docker push会报dial tcp 192.168.209.133:443: connect: connection refused或者证书不匹配。http.port默认 80如果被 nginx 或其他服务占了改成 8080 之类的。harbor_admin_password是 admin 用户的初始密码生产环境务必改掉。data_volume是数据持久化目录默认/data如果磁盘空间紧张改到大盘上。3.2 HTTPS 配置证书怎么放什么时候可以跳过Harbor 默认走 HTTPS但离线环境里很多人图省事直接注释掉 HTTPS 段只留 HTTP。这样做能跑起来但docker push时需要改 Docker 的daemon.json加insecure-registries。我的建议是如果是内网测试HTTP 够用如果是生产最好配自签证书或企业 CA 证书。配 HTTPS 需要三个东西证书文件、私钥、CA 证书可选。在harbor.yml里这样写https: port: 443 certificate: /data/harbor/certs/harbor.crt private_key: /data/harbor/certs/harbor.key证书的 CN 或 SAN 必须包含hostname里填的 IP 或域名。自签证书可以用 openssl 生成openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \ -keyout harbor.key -out harbor.crt \ -subj /CN192.168.209.133生成后放到/data/harbor/certs/下确保install.sh执行时能读到。如果跳过 HTTPS记得在harbor.yml里把https整段注释掉否则prepare会报证书文件不存在。3.3 数据目录与日志配置的取舍data_volume默认是/dataHarbor 会在下面建database、redis、registry、job_logs等子目录。如果服务器有多块盘建议把data_volume指到大容量盘上比如/data1/harbor。日志方面Harbor 的容器日志默认走 Docker 的 json-file 驱动时间长了会占满/var/lib/docker。可以在harbor.yml里加log: level: info local: rotate_count: 50 rotate_size: 200M location: /var/log/harbor这样日志会落到宿主机/var/log/harbor并且按大小轮转。rotate_count是保留文件数rotate_size是单文件大小上限。生产环境建议把level设成warning减少日志量。配置改完后执行安装./install.sh这个脚本会依次做加载镜像、渲染docker-compose.yml、启动容器。如果一切顺利最后会输出----Harbor has been installed and started successfully.----。此时用浏览器访问http://192.168.209.133用 admin 和刚才设的密码登录应该能看到 Harbor 的 Web UI。4. 避坑排查ARM 环境 Harbor 推送失败的五个血泪经验4.1 现象docker push 报 dial tcp 192.168.209.133:443 connection refused原因Docker 客户端默认走 HTTPS 推送但 Harbor 只配了 HTTP或者 HTTPS 证书不被信任。另外如果harbor.yml里hostname填的是域名但 DNS 解析不到也会出现类似错误。解决如果是 HTTP 模式在推送端机器的/etc/docker/daemon.json里加{ insecure-registries: [192.168.209.133] }然后重启 Dockersystemctl restart docker。如果是 HTTPS 模式把自签 CA 证书放到/etc/docker/certs.d/192.168.209.133/ca.crt重启 Docker。注意目录名必须是hostname:port的格式端口是 443 时可以省略。4.2 现象docker load 成功但容器启动后 exec format error原因离线包里的镜像架构和宿主机不匹配。常见于把 x86 包拿到 ARM 机器上或者把 ARM64 包拿到 32 位 ARM 上。解决用docker inspect image | grep Architecture确认镜像架构。如果是amd64而机器是aarch64必须换包。另外有些国产 OS 的 Docker 版本较老对多架构 manifest 支持不好建议用官方推荐的 Docker 版本。4.3 现象Harbor UI 能打开但推送镜像时 413 Request Entity Too Large原因nginx 默认的client_max_body_size是 1M推送大镜像时请求体超限。解决修改harbor/common/config/nginx/nginx.conf在http或server段加client_max_body_size 0;0 表示不限制然后docker compose restart nginx。注意这个文件是install.sh渲染出来的直接改harbor.yml里的nginx相关配置可能不生效需要改模板或渲染后的文件。4.4 现象安装脚本卡在 prepare 阶段提示端口被占用原因80 或 443 端口被宿主机的 nginx、apache 或其他服务占了。解决ss -tlnp | grep :80找到占用进程要么停掉要么改harbor.yml里的http.port为其他端口比如 8080。改完重新跑./install.sh。注意如果之前已经装过一次失败先执行docker compose down清理残留容器。4.5 现象ARM 服务器上 Docker 拉取基础镜像超时原因离线包只包含 Harbor 自身的组件镜像不包含你业务用的基础镜像。如果你在 Harbor 上推送的镜像依赖某个基础镜像而该基础镜像在 ARM 环境里没有缓存构建时仍会去外网拉。解决提前在有网的 x86 或 ARM 机器上docker pull对应架构的基础镜像docker save成 tar拷贝到目标机器docker load。或者在内网搭一个临时 registry 做中转。注意基础镜像本身也要选 ARM64 版本比如arm64v8/ubuntu而不是ubuntu。5. 验证与进阶用 skopeo 做跨架构镜像检查把推送成功率提上去Harbor 装好只是第一步真正在生产里跑起来还得确保推上去的镜像架构正确、标签规范、清理策略到位。我一般会在 Harbor 所在的 ARM 机器上装一个skopeo它能在不拉取完整镜像的情况下检查远程镜像的架构信息。比如验证刚推上去的镜像skopeo inspect docker://192.168.209.133/library/myapp:v1.0输出里会包含Architecture字段如果是arm64就说明推对了。如果显示amd64那这个镜像在 ARM 节点上跑不起来需要重新构建。skopeo在 ARM 环境里安装也不复杂麒麟 V10 可以用yum install skopeoUbuntu ARM 用apt install skopeo。另一个实用技巧是给 Harbor 配镜像清理策略。Harbor v2.8.2 支持在 UI 里设置 tag 保留规则比如只保留最近 10 个 tag自动清理旧的。但注意清理策略默认是每天凌晨跑一次如果磁盘紧张可以手动触发docker exec harbor-core /harbor/harbor_core cleanup这个命令会读取数据库里的清理策略并执行。执行前最好确认一下harbor.yml里的data_volume剩余空间避免清理过程中把正在使用的层删掉。我一般会先跑一次df -h /data看看余量再决定是否手动触发。还有一个容易被忽略的点Harbor 的数据库是 PostgreSQL跑在容器里。如果 ARM 服务器的内存小于 4Gharbor-db容器可能因为 OOM 被 kill。建议至少给 Harbor 留 4G 内存docker stats可以实时看各容器资源占用。如果内存实在紧张可以把harbor.yml里的database.max_idle_conns和max_open_conns调小减少连接数。从那以后我每次在 ARM 环境装 Harbor都会先跑一遍uname -m确认架构再检查docker compose version然后才解压离线包。装完后第一件事不是推业务镜像而是用skopeo inspect验证一个测试镜像的架构确认无误再批量推送。这套流程帮我省了不少返工时间希望帮到你。本文还有配套的精品资源点击获取