简介面向ARM64架构的Harbor v2.8.2离线安装包专为需要在ARM环境如边缘计算、物联网、国产化服务器中部署企业级容器镜像仓库的运维与开发人员准备。包内包含完整的安装脚本、离线镜像包、配置模板及准备脚本共6个文件压缩包整体约639.65MB可在无外网或网络受限的隔离环境中顺利完成安装无需在线拉取镜像特别适合内网私有化部署场景。资源适用于对Harbor已有一定基础、需要快速在ARM64平台上落地镜像管理服务的团队安装后可启用用户权限控制、镜像复制、漏洞扫描等企业功能满足生产级镜像生命周期管理需求。目前已有254人学习使用包内脚本与模板组织清晰安装流程自动化程度高许可证及镜像文件一应俱全能够显著缩短部署与调试周期帮助用户快速构建稳定高效的容器镜像管理环境降低ARM平台落地的复杂度。 前一阵子在给一台ARM64服务器搭内网镜像仓库环境完全离线拿到的输入物就一个harbor-offline-installer-v2.8.2-arm64.tar.gz。这个包解决了我的核心痛点——不用联网拉镜像也不用在ARM板子上现编译解压后跑脚本就能把Harbor v2.8.2完整拉起来。本来是奔着“三步搞定”去的结果在证书配置、docker client信任、开机自启上折腾了不少时间。这篇文章就把我从拿到这个离线包到最终稳定运行的全过程拆开讲覆盖了架构确认、依赖安装、HTTPS/HTTP配置、install.sh执行细节和常见坑适合正在ARM环境比如鲲鹏、飞腾、树莓派、ARM云主机上部署Harbor的运维和开发同学参考。1. 先搞清楚这个离线包到底解决了什么问题1.1 ARM服务器为什么需要专门的Harbor包很多第一次接触ARM服务器的人容易忽略一个事实Harbor本身是分架构发布的。官方发布页会同时提供amd64、arm64、ppc64le、s390x等不同架构的离线包而不是一个包通吃。因为Harbor由一堆容器组成这些容器镜像里的二进制程序必须和宿主机CPU指令集匹配。你拿到的这个harbor-offline-installer-v2.8.2-arm64.tar.gz从文件名就能读出来三层意思arm64这个包里的镜像全部是linux/arm64/v8 架构适用于aarch64 CPU。v2.8.2Harbor版本是2.8.2。offline-installer所有镜像都提前打包好放在压缩包里安装时不依赖外网。如果你的服务器是x86_64那应该去下载文件名里带amd64的包。反过来ARM机器上如果强行用amd64包容器运行时会直接报exec format error这个我在后面第5节会专门讲。提示uname -m输出aarch64就是arm64输出x86_64就是amd64。这是选包时最基础的一步但也是最常出错的一步。1.2 离线包和在线安装包怎么选Harbor官方提供两种安装方式在线安装包online installer和离线安装包offline installer。两者区别很直接在线安装包压缩包只有几MB只包含安装脚本和配置模板安装时要从Docker Hub拉取Harbor的全部镜像。适合测试环境且机器能访问外网。离线安装包压缩包几百MB到1GB以上里面除了安装脚本还包括所有Harbor组件镜像的tar包如harbor-core、harbor-registry、harbor-portal、harbor-nginx等安装时通过docker load导入镜像。选择离线包的核心场景就是生产内网。很多企业机房的ARM服务器不能访问外网或者安全策略不允许直接从Docker Hub拉镜像。这时候离线包就是唯一选择因为它把“拉镜像”这一步提前到了你下载包的这台机器上。我当时选择离线包还有一个原因在线安装时如果网络不稳定Docker拉镜像跑到一半断了重来很麻烦。离线包在导入镜像时是本地磁盘I/O速度和稳定性都可控。1.3 v2.8.2版本有哪些值得关注的变化Harbor 2.x系列整体架构相对成熟v2.8.x算是比较稳定的一个版本线。我选择v2.8.2而不是更新的版本主要考虑两点稳定性优先2.8.2是2.8系列的一个补丁版本修复了之前一些安全问题相比大版本刚发布时更适合生产。依赖门槛适中它对Docker Engine版本要求没那么苛刻17.06.0以上即可Docker Compose V2插件也能用兼容性较好。另外一个细节Harbor v2.8已经支持通过harbor.yml同时配置HTTP和HTTPS但默认配置模板harbor.yml.tmpl打开后http和https两段都在注释状态不同。安装时install.sh会根据你配置的内容生成最终的Docker Compose文件。这一点在后面配置时会具体说。2. 安装前的准备工作架构确认、依赖安装、包校验2.1 确认机器架构与操作系统拿到包后先别急着解压。第一步是在目标服务器上执行uname -m如果输出是aarch64说明系统是arm64架构这个包没问题。如果输出是x86_64那你下错包了。另外要看系统发行版。Harbor离线包本身是跨发行版的底层用Docker跑所以Ubuntu、Debian、CentOS、openEuler理论上都行。但不同发行版的Docker安装方式不一样。我这里用的Ubuntu 22.04 arm64 server这也是目前ARM服务器上比较常见的组合。再检查内核版本uname -rHarbor对内核没有硬性版本要求但如果内核太老比如3.xDocker本身就跑不起来。建议至少Linux Kernel 4.4以上。2.2 安装Docker与Compose插件Harbor offline installer没有内置Docker它依赖宿主机已经装好Docker。在Ubuntu 22.04 arm64上安装Docker最省事的方案sudo apt update sudo apt install -y docker.io docker-compose-v2Ubuntu软件源里的docker.io版本可能不是最新但对Harbor v2.8.2来说完全够用。装完检查docker --version docker compose version如果docker compose提示找不到命令可能是软件源里包名不同或者你需要手动装Docker Compose V2插件。这里有个坑Harbor的install.sh会优先用docker composeV2插件如果没有再找docker-composeV1独立二进制。老系统上如果只有V1版本执行./install.sh有可能报错。解决办法很简单sudo curl -L https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-linux-aarch64 -o /usr/local/bin/docker-compose sudo chmod x /usr/local/bin/docker-compose不过在不能访问外网的机器上curl下载可能也走不通。更稳妥的做法是用发行版自带的包管理器装好Compose V2再在harbor目录下执行的install.sh一般能识别到。2.3 校验安装包完整性离线包动辄几百MB传输过程中可能损坏所以拿到包之后第一件事就是算哈希不要跳过。sha256sum harbor-offline-installer-v2.8.2-arm64.tar.gz把计算出来的哈希值和官方release页面上的sha256sum.txt对照。一致再解压不一致就重新传输。这一步看起来多余但你真踩到一次“解压到一半报错”或者“load镜像时提示tar包损坏”的坑就知道值了。我第一次在ARM机器上部署时就是因为包从移动硬盘拷贝过来时扇区有问题后面排错花了一个多小时。2.4 磁盘、内存与目录规划Harbor离线包解压后harbor目录下会有一个harbor.v2.8.2.tar.gz这是所有Harbor组件镜像的归档文件通常有几百MB。安装后Harbor的容器数据、数据库、镜像存储会占用更多空间。建议给Harbor预留至少50GB磁盘空间。如果还要存大量镜像根据镜像量规划更大的数据盘。默认情况下Harbor的持久化数据在/data目录harbor.yml里配置的data_volume包括数据库和registry存储。安装前先把数据目录挂到大容量磁盘上。查看资源free -h df -h最低配置2核CPU、4GB内存。如果是生产环境建议4核8GB起步。Harbor由内部多个容器组成其中PostgreSQL和Registry相对吃内存内存太小很容易在某一步容器启动失败。3. 动手安装从解压到Harbor跑起来3.1 解压并生成harbor.yml配置文件把离线包上传到/opt目录然后解压cd /opt tar -zxvf harbor-offline-installer-v2.8.2-arm64.tar.gz cd harbor解压后目录里有一个harbor.yml.tmpl模板文件。复制一份cp harbor.yml.tmpl harbor.yml打开harbor.yml最核心的几项配置hostname: 192.168.1.100 http: port: 8080 harbor_admin_password: Harbor12345 data_volume: /datahostname可以直接写IP也可以写域名。要特别注意这里写什么后续docker login就登录什么。如果写的是域名域名必须能解析到这个机器如果写IP就登录IP。3.2 配置HTTP访问和HTTPS证书关键一步这是很多人会卡住的地方也是Harbor最常见的调整点。默认模板中http和https两段都会被读取install.sh会判断如果你配置了https就启用HTTPS如果你只保留http就启用HTTP。这里根据你的实际场景选择场景A内网环境用HTTP简单省事保留http: port: 8080把https整段注释掉注意YAML缩进整段用#注释。这样做的问题是所有客户端机器上的Docker都要配置insecure-registries否则docker login会报HTTPS错误。场景B有域名和证书直接上HTTPS如果你有正式证书或者测试环境用的自签名证书先把证书和私钥放到指定目录比如mkdir -p /data/cert cp harbor.crt /data/cert/ cp harbor.key /data/cert/然后在harbor.yml中配置https: port: 443 certificate: /data/cert/harbor.crt private_key: /data/cert/harbor.key同时把上面http那段注释掉或者保留一个不同的端口用于同时监听。Harbor支持同时开HTTP和HTTPS但一般不用。我当时为了让开发机上的docker能直接docker login一开始用了HTTP模式后来发现每次都要给新同事配daemon.json太烦了索性生成了自签名证书改成HTTPS然后在各客户端也信任了这个证书。实际用下来HTTPS比HTTP省心。注意自签名证书会导致客户端报x509: certificate signed by unknown authority需要在每台客户端机器的/etc/docker/daemon.json里把Harbor地址加入insecure-registries或者在系统里安装根证书。如果你有企业内部的CA证书那是最好的方案。3.3 运行install.sh等待镜像导入配置好harbor.yml后直接执行sudo ./install.sh脚会做几件事检查Docker和docker compose是否可用加载harbor.v2.8.2.tar.gz里的镜像根据harbor.yml生成docker-compose.yml创建并启动Harbor所有容器。第一次执行会看到类似Loaded image: goharbor/...的大量输出这是在本地导入镜像。镜像加载完成后容器启动大约需要1~2分钟。安装脚本最后会显示✔ ----Harbor has been installed and started successfully----。如果中间报错别慌检查Screen输出。常见卡点在第5节说。Harbor装好后会有这些容器在跑harbor-core harbor-registry harbor-registryctl harbor-portal harbor-nginx harbor-log harbor-jobservice harbor-db harbor-redis核心是harbor-nginx它负责统一入口对外暴露HTTP/HTTPS端口再把请求转发给portal和core。3.4 验证服务状态和Web界面安装完成后用以下命令确认容器都处于Up状态docker ps然后打开浏览器访问https://192.168.1.100 # 如果你配置的是HTTP8080端口则访问 http://192.168.1.100:8080默认管理员账号是admin密码就是你在harbor.yml中设置的harbor_admin_password。登录进去后建议先建一个项目比如叫test-project然后从命令行验证整个拉推链路。这里我先不展开下一节讲客户端配置。4. 部署后必做的三件事配置docker、开机自启、日常运维4.1 让docker客户端信任Harbor地址无论你是HTTP还是HTTPS模式客户端机器上都要让Docker“认”这个仓库地址。HTTP模式在每台客户端机器的/etc/docker/daemon.json中加{ insecure-registries: [192.168.1.100:8080] }然后重启Dockersudo systemctl restart docker这样做的原理是Docker客户端默认用HTTPS访问所有registry地址如果发现仓库返回的是HTTP响应就会拒绝认证。insecure-registries的作用是告诉Docker这个地址可以跳过HTTPS。HTTPS模式且使用正式CA证书不需要额外配置直接docker login https://192.168.1.100HTTPS模式且使用自签名证书还是要把这个地址加入insecure-registries或者让客户端信任你的自签名CA。二选一前者简单后者更安全。登录完成后就可以推送镜像了docker tag nginx:latest 192.168.1.100:8080/test-project/nginx:v1 docker push 192.168.1.100:8080/test-project/nginx:v1 docker pull 192.168.1.100:8080/test-project/nginx:v14.2 设置Harbor服务自启动Harbor本身没有自动注册systemd服务服务器重启后不会自动拉起所有容器。如果你不希望每次重启都手动进目录执行docker compose up -d建议做一个Systemd Unit。在/etc/systemd/system/harbor.service里写[Unit] DescriptionHarbor Container Registry Afterdocker.service Requiresdocker.service [Service] Typeoneshot RemainAfterExityes WorkingDirectory/opt/harbor ExecStart/usr/bin/docker compose up -d ExecStop/usr/bin/docker compose down TimeoutStartSec0 [Install] WantedBymulti-user.target然后sudo systemctl daemon-reload sudo systemctl enable harbor sudo systemctl start harbor注意docker compose的路径Ubuntu 22.04上一般是/usr/bin/docker但有些系统Compose插件安装后docker compose是ok的而systemd里建议写完整路径。如果不确定执行which docker查询。另外docker compose down会停止并移除容器但不会删除/data下的数据所以用于日常维护是安全的。4.3 备份与升级注意点Harbor的数据都在data_volume下包括数据库、证书、registry存储。日常备份最简单粗暴的方式是直接备份整个/data目录。但要注意如果Harbor正在运行直接拷贝文件有可能导致数据不一致。稳妥的做法是先停掉Harbor再备份cd /opt/harbor sudo docker compose down sudo tar -czf /backup/harbor-data-$(date %F).tar.gz /data sudo docker compose up -d升级场景要特别留意从旧版本升级到v2.8.2时官方要求先备份数据库然后运行新版离线包里的./upgrade.sh脚本。升级脚本会尝试更新数据库schema旧版本的数据通常能兼容但不排除部分插件不向下兼容。我自己在v2.5升v2.8的时候数据库迁移大约花了10分钟期间服务不可用建议放在维护窗口做。5. 常见问题与排查技巧实录5.1 在qemu模拟的arm64环境里安装时容器报exec format error有一种情况很典型你手上没有物理ARM机器想先用QEMU模拟ARM64环境测试。如果你是用qemu-system-aarch64跑一个完整的ARM虚拟机然后在虚拟机里装Docker和Harbor这种没问题。真正会踩坑的是在x86_64宿主机上直接安装arm64的容器镜像或者用docker run --platform linux/arm64强行模拟。Docker会尝试用qemu-user翻译ARM指令但Harbor的容器里有一些二进制程序在非原生ARM环境下很容易报standard_init_linux.go:228: exec user process caused: exec format error这不是Harbor的问题而是架构不匹配。生产环境不要试图用各种模拟方式跑ARM包老老实实用真机或同一架构的云主机。5.2 docker login报http: server gave HTTP response to HTTPS client这个报错信息基本是“因”的。完整报错通常在Error response from daemon: Get http://192.168.1.100:8080/v2/: http: server gave HTTP response to HTTPS client原因就是我前面说的Docker客户端默认走HTTPS而你的Harbor配置的是HTTP。解决方法是修改客户端的/etc/docker/daemon.json把Harbor地址加到insecure-registries然后重启Docker。注意重启Docker会使当前运行的容器全部重启建议在维护时间操作。5.3 install.sh提示“docker: command not found”或者compose版本不对Harbor的install.sh对Docker和Compose的检测比较严格。如果执行时提示找不到docker可能是当前用户没有/usr/bin/docker的执行路径或者你用非root用户跑脚本但Docker不在PATH里。解决方法export PATH$PATH:/usr/bin:/usr/local/bin sudo ./install.sh如果提示docker compose version不支持查看harbor目录里的common.sh它会在安装时生成临时脚本。最简单的确认方法是执行docker compose version docker-compose --version两个至少有一个可用。两个都没有先装Compose V2插件。5.4 安装后服务起不来或者nginx报502如果docker ps显示有个别容器反复重启或者访问页面时502通常原因有三类hostname配置异常Harbor内部容器之间通过harbor.yml里的hostname互相通信。如果hostname写的是一个无法解析的域名nginx转发到core时可能失败。最简单的解决办法是先用IP当hostname。磁盘空间不足docker exec harbor-db df -h /看看如果目录满了PostgreSQL会启动失败。harbor-core启动慢首次启动时core要初始化数据库耗时较长。如果nginx容器起来了core还没起来浏览器访问会502。等1~2分钟再刷新。排查时看日志最直接docker logs harbor-core --tail 100 docker logs harbor-nginx --tail 100大部分问题在日志里能找到根因。5.5 离线包里的镜像load失败安装脚本如果报Error processing tar file说明离线包里的镜像归档文件可能损坏。这时候回到第2.3节重新校验整个tar.gz的SHA256确认无误后再解压。如果包是在Windows下解压再传到Linux的建议在Linux下重新解压一次避免文件权限和符号链接丢失。最后再分享一点我的体会用这个harbor-offline-installer-v2.8.2-arm64.tar.gz在ARM环境部署Harbor难点不在安装本身而在于环境差异。同样一个包在Ubuntu上顺利跑起来换到另一个发行版可能就卡在Compose插件上。我的习惯是不管什么机器安装前先把Docker和Compose的版本确认好再动Harbor。另外包虽然写着offline但你在下载阶段最好找一个网络好的机器下载后立刻用SHA256校验。等到内网环境再发现问题浪费的可不只是带宽。最后一个小技巧安装后立刻把harbor.yml备份一份附上一段注释写明hostname、证书路径是什么时候配置的下次升级或者迁移时你会感谢当时的自己。本文还有配套的精品资源点击获取