简介适用于ARM64架构的Harbor v2.8.2离线安装包面向在边缘计算、物联网及内网隔离场景中搭建企业级容器镜像仓库的运维与开发人员。离线包内置完整的安装器与配套脚本可在无外网条件下快速部署Harbor解决ARM环境下镜像存储、权限管理、镜像复制与安全扫描等核心需求同时兼容本地文件系统、S3、Azure Blob等后端存储并支持LDAP/AD集成。整个压缩包约639.65MB共6个文件主要包含sh安装/配置脚本、tar.gz主程序压缩包、license许可文件、prepare准备脚本、yml配置模板内容紧凑且结构清晰。已有254人下载学习适合为ARM服务器或国产化终端配置容器镜像服务的技术人员参考。借助该离线包用户无需额外拉取在线镜像解压后依次执行脚本即可完成从环境检查到服务启动的完整流程显著降低ARM平台的部署门槛与排错成本。 如果你所在的项目组接过ARM架构服务器的实施大概率会有这样一幕一台飞腾或鲲鹏的机器操作系统装好了机房策略也放通了但里面什么软件都没有。业务方要的是一个能用的镜像仓库并且这台机器还处在内网离线环境。于是你手上就会多出这样一个文件harbor-offline-installer-v2.8.2-arm64.tar.gz。这篇文章我打算把ARM环境下离线部署Harbor v2.8.2这件事从头到尾梳理一遍。内容包括离线包结构分析、安装步骤、验证方法以及我在实际部署中踩过的一些ARM环境特有的坑。整个流程适合正在做ARM服务器交付、内网环境搭建、或准备把Harbor落地到国产化机器上的同学参考版本锁定在v2.8.2这也是当前ARM离线部署场景里比较稳的选择。1. 一个绕不开的场景ARM服务器上为什么非要装Harbor1.1 什么项目会遇到这个需求先说需求来源。现在ARM服务器的出现频率越来越高尤其是基于飞腾、鲲鹏这类处理器的机器在很多内网项目中已经成了标配。这类机器上跑容器化业务几乎必然要有一个私有镜像仓库——因为业务镜像不能都堆在某个开发机里需要有一个统一拉取和分发的中心节点。Harbor在这里承担的角色非常明确镜像存储、权限控制、复制同步、漏洞扫描。它虽然不是唯一的选择但在国内的团队协作场景下Web界面、项目隔离、Robot账号这些能力确实好用所以成为私有仓库的首选。问题在于ARM服务器一般都在内网隔离环境外网访问受限甚至完全不通。这种情况下常规的在线安装Harbor根本走不通唯一的办法就是提前在一个能联网的ARM机器上下载好离线包再拷贝到目标服务器上安装。这个流程听起来简单实际操作起来问题不少。1.2 为什么非要用离线包有人可能会问直接拿Harbor官方Docker镜像在目标机器上docker run不行吗如果目标机器能访问外网镜像源确实可以但内网环境压根拉不了镜像这就不用多说了。另一个问题是Harbor不是一个单容器应用它是一整套组件nginx、core、portal、registry、jobservice、postgresql、redis再加上可选的trivy和chartmuseum。手工用docker run把这套组件拼起来配置工作量和出错概率都很大。官方离线包的意义就在于把这一整套组件打包成镜像tar包和安装脚本。你只需要解压、改配置、执行install.sh脚本会自动完成镜像加载、配置生成、容器编排启动。离线包在ARM环境里还解决了一个隐藏问题镜像架构。官方发布的harbor-offline-installer-v2.8.2-arm64.tar.gz里所有组件镜像都是arm64架构的不会出现拉到x86镜像导致跑不起来的情况。注意如果你手上只有x86_64的离线包文件名不带arm64在ARM机器上解压和安装流程虽然能走通但镜像加载完启动容器时会直接报exec format error。所以第一步务必确认包名带不带arm64。2. 先看清手里的包v2.8.2-arm64离线包解析2.1 文件里到底有什么拿到harbor-offline-installer-v2.8.2-arm64.tar.gz之后第一件事不是急着解压而是先看大小、校验完整性。这个包一般在2GB出头里面核心的东西是一个更大的镜像tar包。我建议先执行一次校验再往下走避免拷贝过程中文件损坏md5sum harbor-offline-installer-v2.8.2-arm64.tar.gz解压之后你会看到这样一个目录结构harbor/ ├── harbor.v2.8.2.tar.gz # 核心镜像包所有组件的arm64镜像都在这里 ├── harbor.yml.tmpl # 配置模板安装前必须复制并修改 ├── install.sh # 安装入口脚本 ├── common.sh # 公共函数库install.sh会调用 └── LICENSE理解这个结构很重要。install.sh做的事情本质上就三步先加载镜像包里的所有镜像到本地Docker再根据harbor.yml生成最终的docker-compose.yml最后执行docker compose up -d拉起所有容器。所以整个安装过程是否顺利关键就在harbor.yml写没写对以及机器上的Docker环境是不是够用。2.2 为什么选2.8.2而不是更新的版本Harbor现在版本已经出到2.11甚至更高了但ARM离线部署这个场景里v2.8.2依然是一个很值得选用的版本我自己的判断有几点2.8.x是官方对ARM64支持比较完善的一个稳定版本线离线包里arm64镜像齐全过程中很少遇到组件缺失。2.8.2相比2.8.0和2.8.1修复了一批已知问题尤其是jobservice和registry组件偶发的异常退出问题。新版本功能确实更多但对底层环境的要求也更高。部分ARM服务器上的操作系统自带Docker版本偏旧运行新版Harbor会出现兼容性问题而2.8.2对Docker 19.03以上、docker-compose 2.x的适配都比较好。所以我个人把2.8.2归档为ARM离线部署的高性价比版本够用、稳定、踩坑成本低。如果你的业务需求里没有特别新的功能比如完全没有用到Harbor 2.9之后才加入的能力那么v2.8.2完全够用没必要去追新版本给自己找麻烦。3. 从解压到跑通ARM环境离线安装的完整步骤3.1 前置依赖检查Docker、Compose、磁盘在动手跑install.sh之前建议花几分钟做三项检查能省掉后面大量排查时间。第一Docker版本。Harbor v2.8.2要求Docker Engine 17.06.0以上但实际生产环境我个人建议至少20.10。ARM服务器上有些操作系统自带的是Moby或裁剪版Docker版本可能偏低先确认一下docker version第二Compose插件。v2.8.2的install.sh在检测到Compose时会优先使用docker composev2插件如果没有再找docker-composev1独立二进制。ARM环境的操作系统镜像里经常两个都没有需要提前装好。具体选型问题我在第4节详细说。第三磁盘空间。离线包解压后大约占用3GBharbor.v2.8.2.tar.gz解压成镜像后Docker的存储目录会再多占3到5GB此外data_volume里还要存放镜像数据和数据库文件。所以建议至少预留30GB给Harbor相关目录别卡在20GB这种临界值上。3.2 修改harbor.yml的核心配置项进入harbor目录后先把模板复制成正式配置cp harbor.yml.tmpl harbor.yml vim harbor.yml这里我只列必须改的几项其他保持默认即可hostname: 192.168.10.50 http: port: 80 harbor_admin_password: YourStrongPassword123 data_volume: /data/harbor log: level: info local: rotate_count: 50 rotate_size: 200M location: /var/log/harbor几个容易忽略的细节hostname不要写localhost或127.0.0.1。因为后面其他机器要从局域网访问这个仓库hostname会写进镜像的tag里。写localhost会导致其它机器push/pull时把镜像地址解析到本机。最省事的写法是直接用这台ARM服务器的内网IP。harbor_admin_password默认是Harbor12345生产环境必须改掉至少12位包含大小写和数字。data_volume一定要放到空间足够的分区比如独立的数据盘。如果放在根分区且根分区本身不大后续镜像一多很快会被撑爆。如果暂时不想启用HTTPS先把https整段配置注释掉否则即使你配置了证书install.sh也会去检查证书有效性增加不必要的麻烦。3.3 执行install.sh与组件启动验证配置改完后直接执行sudo ./install.sh脚本会先加载镜像包这个过程在ARM机器上耗时较长一般需要3到8分钟取决于磁盘速度。看到Loaded image: ...不断刷出来是正常的耐心等。加载完成后install.sh会调用prepare生成配置最后启动容器。启动完成后第一件事是看容器状态docker compose ps在这个输出里你应该能看到nginx、harbor-core、harbor-portal、harbor-jobservice、registry、registryctl、harbor-db、redis这组容器全部为Up状态。如果出现某个容器反复重启在ARM环境里大概率就是我下一节要说的那几个坑之一。4. ARM环境下最容易踩的四个坑4.1 docker-compose与docker compose的版本旋涡这是我遇到最多的问题而且坑得毫无防备。很多ARM服务器上预装的Docker是操作系统自带的有docker命令但没有docker compose插件也没有docker-compose独立二进制。直接跑install.sh脚本会在某一步报错提示找不到compose命令。装docker-compose独立二进制时又要注意GitHub Release页面上对ARM架构提供的编译产物是docker-compose-linux-aarch64不是docker-compose-linux-x86_64。如果下错架构执行时会直接报Exec format error。我的建议是优先安装compose v2插件因为v2.8.2的install.sh对它支持最好mkdir -p /usr/local/lib/docker/cli-plugins cp docker-compose-linux-aarch64 /usr/local/lib/docker/cli-plugins/docker-compose chmod x /usr/local/lib/docker/cli-plugins/docker-compose装好后用docker compose version验证能看到版本号就说明没问题。之后install.sh和日常运维都用docker compose不用再纠结docker-compose和docker compose的差异。4.2 镜像架构不匹配exec format errorARM环境部署Harbor最经典的问题就是容器启动时报exec format error。出现这个报错90%的原因是镜像架构不对——你加载了x86_64的镜像到ARM机器上而CPU无法执行x86指令。这个问题有几个容易忽视的入口下载离线包时误拿了不带arm64标志的通用包或有x86_64标志的包。务必确认文件名是arm64。手工从外网拉了一些辅助镜像比如手动替换postgresql或redis镜像时没注意镜像的ARCHITECTURE字段。用docker manifest inspect可以快速查询镜像架构但离线环境里不一定有这个命令最简单的办法是在pull镜像时优先选带-arm64标签的版本。还有一个隐蔽点如果你在一台ARM机器上用Docker Buildx构建了一个多架构镜像然后推到Harbor里拉取时Docker会根据客户端架构自动选对应架构的manifest这个没有问题。问题往往出在直接docker load一个不是当前架构的tar包这种时候Docker不会报错但启动容器时就原形毕露了。4.3 根分区空间被打满Harbor的数据增长很容易被低估。镜像数据、数据库、日志三块加起来增长很快。我见过不止一次部署完Harbor之后没过几周机器根分区直接100%容器开始报磁盘写入错误Harbor页面直接打不开。ARM服务器很多是精简交付数据盘不一定被正确挂载所有东西都堆在根分区上。所以部署前一定要用df -h看清楚/var/lib/docker所在分区的剩余空间要求至少20GB。data_volume指向的分区要求最少30GB最好单独挂载数据盘。/var/log/harbor的日志轮转配置v2.8.2默认单个日志文件200MB、保留50个也就是最多10GB日志量大的环境建议调小一点。如果数据盘没挂载先把分区挂好再部署比事后再迁移要省事得多。迁移Harbor数据目录不是简单的移动文件还要处理容器挂载路径和权限非常麻烦。4.4 自签证书导致docker login失败很多ARM环境里没有正规CA签发的证书大家会选择用自签证书开启HTTPS。但配置完HTTPS后客户端机器执行docker login时会报x509: certificate signed by unknown authority这是Docker不信任自签证书导致的。解决办法是在所有需要访问Harbor的客户端机器上把自签CA证书放到Docker的证书目录mkdir -p /etc/docker/certs.d/192.168.10.50/ cp ca.crt /etc/docker/certs.d/192.168.10.50/ systemctl restart docker注意目录名必须是Harbor的hostname也就是你访问Harbor用的域名或IP。如果你后期改了hostname这个目录名也要跟着改否则会继续报证书不信任。这个细节很容易漏但排查起来又特别耗时。如果只是内网临时使用不想折腾证书也可以在所有客户端Docker daemon.json里配置insecure-registries把Harbor地址加进去。但生产环境不建议长期这样搞镜像在传输过程中是明文状态还是配合HTTPS更稳妥。5. 装完之后别急着走健康检查与首次push/pull验证5.1 组件级健康检查Harbor有一个内置的健康检查接口这个非常方便。安装完成后执行curl http://127.0.0.1/api/v2.0/health正常情况会返回一个JSON{ status: healthy, components: [ {name: core, status: healthy}, {name: jobservice, status: healthy}, {name: registry, status: healthy}, {name: registryctl, status: healthy}, {name: portal, status: healthy}, {name: postgresql, status: healthy}, {name: redis, status: healthy} ] }只要status是healthy整体就问题不大。如果某个组件返回unhealthy就去查对应容器的日志比如数据库挂了就看harbor-db的日志不要一上来就重启所有容器容易掩盖真实问题。5.2 用一条完整链路验证仓库可用性健康检查只能说明Harbor内部组件活着真正验证仓库能不能用还是要走一遍完整的push/pull流程。找一台能访问Harbor的客户端机器执行docker login 192.168.10.50 # 输入admin账号和密码 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如果push和pull都成功说明这套Harbor从认证、存储到分发整个链路都是通的。建议在这个环节注意一下客户端机器的Docker架构最好和Harbor所在机器一致也就是都是ARM。如果你从一台x86机器去push一个x86镜像到ARM版Harbor这本身没问题Harbor就是一个镜像仓库它不区分客户端架构。但如果你的镜像本身是x86的后面只能被x86机器拉取ARM机器拉下来也跑不了这是使用层面的问题不是Harbor的bug。6. HTTP改HTTPS给Harbor补上生产环境的一课6.1 证书准备与harbor.yml配置很多人在部署初期图省事直接以HTTP模式把Harbor跑起来了。等真正要上生产或者安全扫描不过关的时候才想起来要改成HTTPS。这个改造在v2.8.2里是支持的流程也还算清晰。首先准备好证书文件一般包括三个服务器证书harbor.crt、私钥harbor.key、CA证书ca.crt。把证书放到一个Harbor可以读取的目录比如/data/cert/然后修改harbor.yml把之前注释掉的https段放开https: port: 443 certificate: /data/cert/harbor.crt private_key: /data/cert/harbor.key同时把http.port改成别的端口比如8080或者直接注释掉http段。这里有个细节Harbor的nginx容器会同时监听80和443如果你两个都开着访问80端口的请求仍然会被强制跳转到443这个行为是由nginx配置决定的不需要你额外配置。6.2 prepare与重启的注意事项改完配置后不是直接重启容器就够了。Harbor的容器编排文件是install.sh通过prepare生成的你改的是harbor.yml需要让prepare重新生成一次配置docker compose down ./prepare --with-trivy docker compose up -d这里--with-trivy要和你第一次安装时保持一致。如果你第一次安装时启用了trivy这次prepare不带这个参数trivy容器就会被从编排文件里去掉这是很多人改HTTPS时踩过的坑。重启完成后再次执行curl -k https://127.0.0.1/api/v2.0/health确认HTTPS模式正常。记得把客户端的/etc/docker/certs.d/目录同步好这一步我在4.4节已经说过了不再重复。7. 落地后的几条运维建议个人经验Harbor装好只是开始后续维护才是重头戏。根据我自己的使用经验有几件事值得在部署早期就做好准备。第一件事是数据库备份。Harbor的元数据全在postgresql里容器一旦损坏或数据卷丢失重建起来非常痛苦。最简单的方式是定期用docker exec进入harbor-db容器执行pg_dump。备份文件不要放在data_volume同一个分区里换个独立位置存放避免数据盘故障时备份一起没了。第二件事是垃圾回收。Harbor删除镜像后实际占用的存储空间并不会立刻释放要执行垃圾回收Garbage Collection才会真正清理。v2.8.2在Web界面里的清理功能就是触发GC的入口。我建议定期做一次GC避免删除大量镜像后磁盘空间迟迟不释放。第三件事是资源规划。ARM机器如果还要跑其他业务Harbor的内存占用要提前留好。v2.8.2整套组件跑起来内存占用通常在3到4GB左右。如果机器总共只有8GB内存Harbor再加业务应用就比较紧张了swappiness建议调低避免生产环境出现不必要的swap抖动。第四件事是升级策略。Harbor的升级有个硬规则大版本不能跨版本直接跳。比如从2.8.2升到2.9.x必须走官方升级脚本不能直接把数据卷挂到新版容器上。离线环境下升级前一定要先备份数据库和harbor.yml然后按官方文档要求逐版本升级不要为了赶时间跳过中间版本。ARM环境部署Harbor说难不难说简单也不简单。核心就是把离线包架构选对、磁盘空间规划好、Compose环境准备好剩下的就都是常规操作了。如果你也正在处理类似的ARM离线部署项目希望这篇内容能帮你少走一些弯路。本文还有配套的精品资源点击获取