简介面向云原生运维工程师、Kubernetes 平台开发者及需要在 ARM64 架构服务器上搭建私有镜像仓库的技术人员这份资源提供了 Harbor v2.12.0 的 ARM64 离线安装包可解决国产化芯片或 ARM 服务器环境下无法直接拉取官方镜像、部署企业级容器镜像仓库的问题。压缩包共包含 6 个文件以 sh 安装脚本、gz 镜像归档、license 许可文件、prepare 预检脚本及 tmpl 配置模板为主整体约 639.21MB覆盖从环境校验、配置生成到服务安装的完整离线部署链路。目前已有 368 人学习下载适合具备一定 Linux 与容器基础的中高级读者参考。借助该包读者可在无外网或弱网环境中完成 Harbor 的落地部署获得镜像仓库的存储、权限、复制等核心能力并基于模板文件快速调整端口、存储与 TLS 参数减少自行编译与适配 ARM64 的排错成本。1. Harbor v2.12.0 ARM64 离线安装包为什么值得你花一个下午搞定如果你手里有一台 ARM64 架构的服务器比如国产化信创环境里常见的鲲鹏、飞腾平台或者云厂商新出的 ARM 实例想在上面跑一套私有镜像仓库大概率会撞上同一个问题官方给的安装包大多是 x86_64 的直接拿过来装容器起不来报错信息还特别含糊。Harbor v2.12.0 的 ARM64 离线安装包解决的正是这个场景——它把镜像仓库、数据库、缓存、扫描器这些组件全部打包成 ARM64 可用的镜像配合离线安装脚本让你在没有外网的环境里也能把整套私有仓库拉起来。这件事的价值不在于“装个软件”而在于你终于能在 ARM 服务器上拥有一套带权限管理、镜像扫描、复制策略的企业级仓库而不是退而求其次用 registry 裸跑。适合谁适合正在做信创迁移、需要在 ARM 环境里落地容器化、又不想被网络和架构问题反复折腾的运维和平台工程师。接下来我按实际落地顺序把选型理由、离线包结构、安装步骤、参数调优和踩坑记录一层层拆开。2. 先搞清楚离线包里到底装了什么组件拆解与 ARM64 适配点2.1 离线包不是“一个安装文件”而是一整套镜像快照很多人第一次拿到 Harbor 离线包以为是个类似.run或.bin的自解压程序双击就完事。实际上它的结构是一个压缩包解压后得到一个harbor目录里面包含harbor.yml.tmpl配置模板、install.sh安装脚本、prepare预处理脚本以及最关键的images目录——这个目录里是一堆.tar格式的容器镜像归档文件。安装时install.sh会先调用docker load或nerdctl load把这些镜像导入本地镜像库然后再用docker compose或docker-compose拉起容器。ARM64 版本和 x86_64 版本在目录结构上完全一致区别只在images目录里每个 tar 包内部的镜像架构标签。如果你不小心把 x86_64 的离线包拿到 ARM64 机器上装docker load这一步可能不会报错但容器启动时会直接抛exec format error因为镜像里的二进制是 x86 指令集ARM 内核无法执行。所以拿到包的第一件事是确认包名或解压后的镜像清单里带有arm64或aarch64标识。2.2 核心组件与 ARM64 适配成熟度Harbor v2.12.0 的组件栈大致可以分成四层入口层是nginx和harbor-portal负责反向代理和 Web 界面核心服务层是harbor-core、harbor-jobservice、harbor-registry分别处理 API、异步任务和镜像存储数据层是postgresql和redis分别存元数据和缓存扩展层是trivy扫描器和可选的notary签名服务。在 ARM64 上这些组件的适配成熟度并不一样。nginx、redis、postgresql这些基础组件早就有官方 ARM64 镜像问题不大。harbor-core和harbor-jobservice是 Go 编译的只要编译时目标架构设对运行起来和 x86 没区别。真正容易翻车的是trivy扫描器——它依赖漏洞数据库而数据库的更新机制在离线环境下需要额外处理。另外如果你启用了notary它的签名服务在 ARM64 上的镜像体积会比 x86 大不少因为部分依赖没有预编译的 ARM64 版本需要从源码构建。提示离线安装前先确认目标机器的容器运行时是 Docker 还是 containerd。Harbor 的install.sh默认走 Docker如果你用的是 containerd需要手动改脚本里的加载命令否则镜像导入了但 Harbor 找不到。2.3 为什么选离线安装而不是在线安装在线安装 Harbor 只需要下载一个harbor-online-installer包然后运行install.sh脚本会从 Docker Hub 拉取镜像。但在 ARM64 场景下在线安装有两个硬伤第一Docker Hub 上部分 Harbor 组件的 ARM64 镜像标签可能不全拉取时容易遇到manifest unknown第二很多 ARM64 服务器部署在内网或信创环境里根本没有外网出口在线安装脚本第一步就卡死。离线安装包把镜像提前打包好你只需要把压缩包传到目标机器解压、改配置、执行脚本全程不需要外网。代价是包体积大——完整离线包通常在 2GB 到 3GB 之间传输时要有心理准备。但换来的是可复现性同样的包在同样的架构上装出来的环境完全一致不会因为拉取时间不同导致镜像版本漂移。3. 从零跑通 ARM64 离线安装命令、配置与验证3.1 环境预检内核、运行时与端口在动手之前先花五分钟做环境预检。ARM64 服务器上最常见的坑不是 Harbor 本身而是底层环境不满足要求。你需要确认三件事内核版本、容器运行时版本、以及关键端口是否被占用。# 确认 CPU 架构输出应为 aarch64 或 arm64 uname -m # 确认内核版本Harbor v2.12.0 建议 4.15 以上 uname -r # 确认 Docker 版本建议 20.10.10 以上 docker version --format {{.Server.Version}} # 确认 docker compose 插件是否可用 docker compose version # 检查 80、443、5432、6379 端口是否被占用 ss -tlnp | grep -E :(80|443|5432|6379)\s这几条命令的输出要逐条看。uname -m如果不是aarch64说明你拿错机器了。docker compose version如果报错说明你只有老版的docker-compose独立二进制需要把install.sh里的docker compose替换成docker-compose。端口检查里5432 和 6379 是 Harbor 内部 PostgreSQL 和 Redis 用的如果宿主机上已经有这两个服务在跑要么改 Harbor 配置里的端口映射要么先把冲突的服务停掉。3.2 解压与配置harbor.yml 里必须改的四个参数离线包解压后进入harbor目录你会看到harbor.yml.tmpl。这是配置模板不能直接改要先复制成harbor.yml。# 解压离线包假设包名为 harbor-offline-installer-v2.12.0-arm64.tgz tar -xzf harbor-offline-installer-v2.12.0-arm64.tgz # 进入解压目录 cd harbor # 从模板生成实际配置文件 cp harbor.yml.tmpl harbor.yml # 查看需要修改的关键字段 grep -nE hostname|^https|^http|harbor_admin_password|data_volume harbor.ymlharbor.yml里有四个参数必须改。第一个是hostname默认是reg.mydomain.com你要改成目标机器的 IP 或域名否则 Web 界面和镜像推送都会出问题。第二个是http和https段如果暂时没有证书先把https整段注释掉只保留http并把http.port设成 80。第三个是harbor_admin_password默认密码是Harbor12345生产环境必须改掉。第四个是data_volume默认是/data如果目标机器的/data分区空间不够要改成其他路径。# harbor.yml 关键片段示例 hostname: 192.168.1.100 # 暂时不启用 https整段注释掉 # https: # port: 443 # certificate: /your/certificate/path # private_key: /your/private/key/path http: port: 80 harbor_admin_password: YourStrongPassword123 data_volume: /data改完配置后不要急着执行install.sh。先运行prepare脚本它会检查配置文件的语法和依赖项。# 预处理检查配置和依赖 ./prepare # 如果 prepare 通过再执行安装 ./install.shprepare脚本会做几件事检查harbor.yml里的必填项是否为空、检查data_volume目录是否存在且可写、检查docker和docker compose是否可用。如果这一步报错根据错误信息逐条修不要跳过直接装。3.3 安装后验证三个必须通过的检查点install.sh执行完成后终端会输出一串容器启动日志。但“脚本没报错”不等于“服务可用”。你需要做三个验证。第一个验证是容器状态。执行docker compose ps确认所有容器的STATUS都是Up或Up (healthy)。如果有容器是Exit或Restarting用docker compose logs 服务名看日志。# 查看所有容器状态 docker compose ps # 如果某个容器异常查看它的日志 docker compose logs harbor-core --tail 50第二个验证是 Web 界面。在浏览器里访问http://hostname用admin和你设置的密码登录。如果能进到项目列表页面说明harbor-core、harbor-portal、nginx这条链路是通的。第三个验证是镜像推送。在另一台能访问 Harbor 的机器上或者就在本机执行docker login和docker push。# 登录 Harbor docker login 192.168.1.100 -u admin -p YourStrongPassword123 # 给本地镜像打标签 docker tag nginx:latest 192.168.1.100/library/nginx:latest # 推送镜像 docker push 192.168.1.100/library/nginx:latest推送成功后回到 Web 界面在library项目下应该能看到nginx镜像。如果推送时报denied或unauthorized检查docker login是否成功以及 Harbor 里是否创建了对应的项目。4. 避坑记录ARM64 离线安装里最容易翻车的五件事4.1 镜像加载成功但容器起不来报 exec format error现象docker load导入镜像时没有报错但docker compose up后容器反复重启日志里出现exec format error。原因你用的离线包是 x86_64 版本镜像里的二进制是 x86 指令集ARM64 内核无法执行。docker load只校验镜像格式不校验指令集所以加载阶段不会拦截。解决确认离线包文件名或解压后的images目录里带有arm64或aarch64标识。如果已经装错了先docker compose down清理容器再删除已加载的错误镜像换正确的包重新执行install.sh。4.2 prepare 脚本报 data_volume 目录不可写现象执行./prepare时提示data_volume /data is not writable。原因/data目录可能不存在或者存在但当前用户没有写权限。Harbor 安装脚本默认以当前用户身份运行不会自动创建目录或提权。解决手动创建目录并赋权。# 创建数据目录 sudo mkdir -p /data # 赋予当前用户写权限假设当前用户是 deploy sudo chown -R deploy:deploy /data # 或者如果不想改属主直接给 777仅测试环境 sudo chmod 777 /data生产环境建议用chown而不是chmod 777避免权限过宽。4.3 端口 80 被占用导致 nginx 容器启动失败现象docker compose ps显示nginx容器状态是Exit日志里报bind: address already in use。原因宿主机上已经有其他服务占用了 80 端口比如系统自带的 Web 服务或另一个反向代理。解决先确认占用进程再决定是停掉它还是改 Harbor 的端口。# 查看 80 端口占用 sudo ss -tlnp | grep :80 # 如果占用进程不重要停掉它 sudo systemctl stop 服务名 # 如果不想停改 harbor.yml 里的 http.port 为 8080 # 然后重新执行 ./prepare ./install.sh改端口后访问 Harbor 的地址也要带上端口号比如http://192.168.1.100:8080。4.4 离线环境下 trivy 扫描器无法更新漏洞库现象Harbor 装好后镜像扫描功能报错提示无法下载漏洞数据库。原因trivy默认会从外网拉取漏洞数据库离线环境下没有外网出口拉取失败。解决在能联网的机器上提前下载 trivy 的离线数据库传到目标机器然后配置 Harbor 使用本地数据库。具体做法是修改harbor.yml里的trivy段指定skip_update: true和本地数据库路径。trivy: ignore_unfixed: false skip_update: true offline_scan: true # 其他配置保持默认然后在 Harbor 的data_volume目录下创建trivy子目录把离线数据库文件放进去。具体数据库文件格式和放置路径参考 trivy 官方文档的离线部署说明。4.5 用 containerd 运行时导致 install.sh 卡在镜像加载现象install.sh执行到镜像加载阶段就卡住终端没有任何输出也不报错。原因install.sh默认调用docker load但目标机器上只有 containerd没有 Docker CLI。脚本找不到docker命令可能静默失败或卡住。解决确认目标机器的容器运行时。如果是 containerd需要手动把install.sh里的docker load替换成nerdctl load或ctr -n k8s.io images import。同时docker compose也要替换成对应的 containerd 编排工具比如nerdctl compose。# 检查是否有 nerdctl which nerdctl # 如果有用 nerdctl 加载镜像 nerdctl load -i images/harbor-core.tar # 然后手动用 nerdctl compose 启动 nerdctl compose -f docker-compose.yml up -d这种改法比较绕如果条件允许建议在 ARM64 机器上装一个 Docker让install.sh按默认路径走省去改脚本的麻烦。5. 进阶技巧把 ARM64 Harbor 做成可复制的离线部署单元装好一套 Harbor 只是开始。如果你管的不止一台 ARM64 服务器或者需要频繁在隔离环境里重建仓库真正省时间的做法是把整个安装过程封装成一个可复制的部署单元。我一般会做三件事。第一件事把harbor.yml里所有环境相关的参数抽成变量写一个render-config.sh脚本。这个脚本接收HOSTNAME、ADMIN_PASSWORD、DATA_VOLUME三个参数用sed或envsubst替换模板里的占位符生成最终的harbor.yml。这样换一台机器只需要改三个变量不用手动编辑 YAML。#!/bin/bash # render-config.sh - 根据环境变量生成 harbor.yml set -e HOSTNAME${1:?请传入 hostname} ADMIN_PASSWORD${2:?请传入 admin 密码} DATA_VOLUME${3:-/data} cp harbor.yml.tmpl harbor.yml sed -i s|^hostname:.*|hostname: ${HOSTNAME}| harbor.yml sed -i s|^harbor_admin_password:.*|harbor_admin_password: ${ADMIN_PASSWORD}| harbor.yml sed -i s|^data_volume:.*|data_volume: ${DATA_VOLUME}| harbor.yml echo harbor.yml 已生成hostname${HOSTNAME}, data_volume${DATA_VOLUME}这个脚本的关键在于sed的匹配模式。harbor.yml.tmpl里hostname字段后面可能有空格所以用^hostname:.*匹配整行替换成新值。data_volume同理。执行前先备份原始模板避免改坏。第二件事把离线包和配置脚本一起打成一个“部署包”。目录结构大概是deploy/下放harbor-offline-installer-v2.12.0-arm64.tgz、render-config.sh、install-harbor.sh。install-harbor.sh负责解压、调用render-config.sh、执行prepare和install.sh。这样交付给同事或放到内部制品库时对方只需要传三个参数就能跑。第三件事装完后立刻做一次“冷启动验证”。具体做法是docker compose down停掉所有容器然后docker compose up -d重新拉起确认所有服务能自动恢复。这一步能暴露数据卷挂载、依赖启动顺序、健康检查配置的问题。我见过不少环境装完当天能用第二天重启服务器后 Harbor 就起不来了原因就是postgresql的数据目录没有正确挂载到宿主机容器重启后数据丢了。注意冷启动验证前先确认data_volume下的database和registry目录有数据。如果docker compose down时加了-v参数数据卷会被删除那就真成“后悔药”都救不回来了。最后说一个我自己的习惯每次装完 Harbor我会在library项目里推一个最小的测试镜像比如hello-world然后打上keepalive标签。这个镜像不删用来做日常连通性检查。哪天推送报错了先docker pull这个keepalive镜像如果能拉下来说明仓库核心链路没问题问题在客户端或网络如果拉不下来再去看 Harbor 容器状态。这个习惯帮我省了很多次从零排查的时间。希望帮到你。本文还有配套的精品资源点击获取