简介面向ARM64服务器的Harbor v2.5.5离线安装包适合在无外网、内网隔离或软件供应链受控环境中部署企业级镜像仓库的运维人员、开发工程师与交付集成商使用。整个归档共24个文件压缩后约531.33MB除核心镜像包外还包含环境变量文件、Compose编排文件、Harbor配置文件、Shell安装脚本与配置模板等其中环境变量用于指定部署参数Compose编排负责定义容器服务配置文件可调整认证、存储与端口脚本用于自动化安装与校验证书与口令文件也为启用HTTPS访问提供了基础。已有206人学习下载说明其在ARM64离线部署场景中具备实际参考价值。通过本包可免去外网拉取镜像和手工编写配置的环节部署时只需核对端口、存储路径与证书参数然后执行安装脚本即可启动Harbor同时脚本与配置模板为二次修改提供了起点适合需要快速交付、批量初始化或后续维护私有仓库的团队直接使用。1. harbor-offline-installer-v2.5.5-arm64.tgz先把这条安装命令的来路说清楚在生产环境里Harbor 上线最大的拦路虎往往不是功能而是环境。内网机房拉不到外网服务器偏偏还是 ARM 架构在线安装那套 docker pull 流程直接废掉这就是你第一次看到 harbor-offline-installer-v2.5.5-arm64.tgz 的典型场景。这个离线安装包把 Harbor 服务端用到的所有容器镜像全部打进了一个 tgz 文件解压后跑一条 install.sh 就能把 Harbor 的核心、Registry、数据库、Redis、Nginx 全拉起来不需要任何公网访问。我在国产化迁移、边缘机房的离线部署里反复用它踩过架构不匹配、磁盘爆满、docker-compose 缺失各种坑这篇文章就把选型理由、离线包内部结构、ARM64 适配和完整安装步骤一次讲透新手能照着跑通熟手能避开我花了一周才搞明白的边界问题。2. 离线包结构到 v2.5.5 选型为什么这个 tgz 值得留一份2.1 离线安装包与在线安装的差距tgz 里到底装了什么Harbor 官方提供两种安装方式在线安装包只是个几百 KB 的脚本真正干活时逐个 docker pull 镜像离线安装包则是把全部服务镜像打完包再压缩。打开 harbor-offline-installer-v2.5.5-arm64.tgz 之前先明确这个包在生产中的定位它是照着「目标机器完全无外网、无法访问 Docker Hub」这个前提设计的。解压后你能看到这些文件harbor.yml.tmpl 是配置模板install.sh 是安装入口common.sh 是脚本库还有一个几十 GB 的 harbor.v2.5.5.tar.gz这个 tar 才是核心里面是 docker save 出来的所有镜像。典型镜像包括 goharbor/harbor-core、goharbor/harbor-registry、goharbor/harbor-jobservice、goharbor/harbor-portal、goharbor/harbor-nginx、goharbor/harbor-db、goharbor/redis-photon以及配套的 Trivy 扫描器镜像。我一般这样理解离线安装的本质是把「拉镜像」这一步提前到有网的机器上完成再搬运到目标机。install.sh 的启动逻辑并不复杂先检查 docker 和 docker-compose 是否存在且满足版本要求再执行 docker load 载入 harbor.v2.5.5.tar.gz载入完成后用 harbor.yml 生成 docker-compose.yml最后 docker-compose up -d 拉起全部容器。那个 load 阶段给人印象最深在机械盘 ARM 机器上载入十多个 GB 的镜像半小时都算正常别中途 CtrlC否则 docker 存储目录里全是半截镜像层。2.2 为什么选 v2.5.5在版本线和维护成本之间找坐标版本选择这件事比想象中影响更大。Harbor 的 2.x 版本线和 1.x 的最大区别是配置体系完全换了1.x 用 harbor.cfg2.x 改用 harbor.yml语法和参数命名全变。如果你在国产化 ARM 机器上部署网上能搜到大量旧教程还停留在 1.8、1.9 的 harbor.cfg直接照抄会翻车。v2.5.5 是 2.5 系列里我比较信任的一个稳定点安装包结构成熟arm64 镜像构建完整对容器漏洞扫描的默认支持也切到了 Trivy比早年必须额外拉 Clair 镜像的方式省事。还有一点是升级策略Harbor 的升级工具 migrations 对 2.5 到 2.6、2.7 的路径支持很顺。如果一上来装最新版API 和配置变化可能让你摸不着头脑而停在 2.x 中段版本至少社群踩坑记录是完整的出问题检索时能找到大量可对照的报错。版本坐标选得稳后续升级才有后悔药可吃。2.3 下载后先做三件事大小、MD5、架构核对拿到 tgz 不要急着解压先做三分钟检查能省掉后续半天排错。第一步看文件大小v2.5.5 离线包通常达到 10GB 以上arm64 包和 amd64 包体积接近如果下载下来只有几十 MB基本是断点异常或平台给错了文件。第二步校验 MD5官方发布页面每个安装包旁都给了 sha256 或 md5 校验值用 sha256sum 手动对一遍内网传输工具偶尔会损坏大文件解压到一半报错再排查就晚了。第三步确认架构uname -m 在 ARM64 机器上应输出 aarch64在 x86 机器上输出 x86_64如果机器是 ARM 却拿了 amd64 的包后面 docker load 虽能成功但容器启动必然报 exec format error。# 文件完整性与架构核对一条命令做完 sha256sum harbor-offline-installer-v2.5.5-arm64.tgz tar -tzf harbor-offline-installer-v2.5.5-arm64.tgz /dev/null echo archive ok uname -msha256sum 的输出要和官网发布页比照不一致就重新下载。tar -tzf 的作用是列出包内文件并同时验证压缩包能否完整解压这一步能提前暴露文件损坏。uname -m 确认内核架构aarch64 才是 ARM64别看 /proc/cpuinfo 里一堆 ARMv8 字样就下结论。提示有些国产化系统的 uname -m 输出是 aarch64但 /etc/os-release 显示的是 Kylin V10架构判断以 uname -m 为准。3. ARM64 适配与部署前置从架构陷阱到国产化环境检查3.1 ARM64 最容易被忽略的坑架构不匹配与 registry 镜像关联ARM64 上部署 Harbor 的第一步不是装 Harbor而是确认你要跑在什么指令集上。Harbor 的官方 arm64 离线包对应的是 linux/arm64 平台内部镜像全是 ARMv8 指令集编译的产物。常见做法是在打包镜像时通过 Docker manifest 做多架构关联但离线包里的镜像已经固定成单一架构没有 Docker Hub 的 manifest 机制帮你自动选择所以拿错包就是结构性错误。另一个连带坑是目标机器上已有的镜像仓库缓存。如果这台 ARM 机器之前用 docker pull 拉过 amd64 镜像docker 会在本机保存一个错误架构的镜像层导致后续 docker-compose up 时旧镜像覆盖新镜像或直接报错。我处理过类似问题明明离线包架构正确容器还是起不来最后 docker images 一看harbor-core 镜像的架构栏写着 amd64。解决方法是部署前先 docker system prune -a 清空旧镜像缓存再执行 install.sh。3.2 没有真机时的预演用 QEMU 模拟 ARM64 跑通流程很多团队在拿到飞腾、鲲鹏真机之前想先在本地验证安装流程最现实的手段就是 QEMU 模拟 ARM64。这个方法不适合做性能验证但用来确认步骤、看脚本输出是够用的。我在 x86 笔记本上用 qemu-system-aarch64 起过 Ubuntu ARM64 虚拟机把 tgz 传进去跑了一遍 install.sh原理是用 QEMU 的 TCG 动态二进制翻译把 ARM 指令翻译成 x86 指令执行。# 启动一个 ARM64 的 QEMU 虚拟机示意需提前下载 UEFI 固件和 Ubuntu ARM64 cloud 镜像 qemu-system-aarch64 -M virt -cpu cortex-a72 -smp 4 -m 4096 \ -bios QEMU_EFI.fd \ -drive ifnone,fileubuntu-arm64.qcow2,formatqcow2,idhd0 \ -device virtio-blk-device,drivehd0 \ -netdev user,idnet0 -device virtio-net-device,netdevnet0 \ -nographic参数说明-cpu cortex-a72 选定 ARMv8 内核模型-m 4096 给 4GB 内存Harbor 在 2GB 内存下会跑得很难受模拟环境里给足-nographic 让串口直接输出到当前终端方便观察 install.sh 的日志。跑通过程中你会发现 QEMU 翻译执行很慢docker load 一个 10GB 的镜像可能要一两个小时所以它只适合验证配置语法和安装流程不适合反复做性能测试。3.3 部署前必查清单内存、磁盘、容器运行时三个维度ARM 设备形态差异极大从开发板到鲲鹏服务器都有部署前如果不在环境上较真装完跑不动再排查就晚了。我的习惯是列一张检查清单逐项过每条都有明确阈值。内存方面Harbor 实际跑起来至少需要 2GB 可用内存如果同时启用 Trivy 扫描器建议 4GB 以上。很多人忽略的是 swapARM 小机器内存不够时会用 zram 或 swap 兜底但 Harbor 的 PostgreSQL 在 swap 压力下会很慢表现为页面打开卡顿但容器状态正常。磁盘方面安装包本身占 10GB 以上docker load 后镜像又占一份再加上运行时数据data_volume 指向的目录至少要准备 20GB 空闲。更关键的是 data_volume 必须放在块存储上如果挂载点是 NFS 网络盘数据库的 fsync 会成为灾难Harbor 页面转圈、推送镜像超时基本都是这么来的。容器运行时方面docker 版本建议 19.03 以上docker-compose 必须存在且版本不低于 1.18.0。有些国产化系统预装的是 podmaninstall.sh 检测不到 docker 会直接退出这时候常见做法是补装 docker-ce 或 docker-engine而不是强行适配。3.4 银河麒麟 V10 飞腾架构部署的额外检查项在 Kylin Linux V10 飞腾Phytium这类国产化组合上部署热门搜索里出现频率很高实际坑也很典型。系统默认可能不带 docker-ce需要走麒麟原厂源或离线 rpm 包安装装完 docker 后第一件事是确认 docker info 的 Architecture 字段输出 aarch64。还有 SELinux 和审计策略的问题。银河麒麟默认开启安全模块如果容器启动时 docker 报 permission denied先别怀疑 Harbor 配置用 getenforce 看状态临时 setenforce 0 验证确认后写进 /etc/selinux/config。另外飞腾机器上常见的内核模块是 kunpeng 或 phytium 相关驱动docker 存储驱动推荐 overlay2如果系统默认给的是 devicemapper大概率是历史遗留配置要改成 overlay2 再装 Harbor。# 国产化 ARM 系统上的快速环境确认 docker info | grep -E Architecture|Storage Driver docker-compose --version getenforce free -h df -h /dataArchitecture 必须是 aarch64Storage Driver 建议 overlay2docker-compose --version 输出不能是 command not foundgetenforce 输出如果为 Enforcing 就要提前处理free 和 df 分别确认内存与磁盘空间。这套命令跑完环境才算达到安装前置条件。4. 用 ARM64 离线包跑通安装解压、改配置、一条命令拉起4.1 解压并生成 harbor.yml五个必改参数一次说清进入正式安装后第一步是解压。注意 tar 解压时不要把整个包直接解到根目录先进到 /opt 或 /srv 这类专门放应用的目录。解压完成后目录名通常就叫 harbor里面已经有 install.sh拿 harbor.yml.tmpl 复制一份成 harbor.yml 再改。mkdir -p /opt/harbor-install mv harbor-offline-installer-v2.5.5-arm64.tgz /opt/harbor-install/ cd /opt/harbor-install tar -zxf harbor-offline-installer-v2.5.5-arm64.tgz cd harbor cp harbor.yml.tmpl harbor.ymlharbor.yml.tmpl 里自带的是一份带示例证书的 HTTPS 配置内网环境没有合法证书时我一般先把 HTTPS 整段注释掉走 HTTP 更省事。五个必改参数如下hostname 必须改成目标机器可访问的 IP 或域名不能留默认的 reg.mydomain.com否则登录后 registry 地址全是错的。http.port 默认 80如果端口被 Nginx 占着改成 8080 或其它未占用端口同时要记得防火墙放行。harbor_admin_password 默认是 Harbor12345生产环境必须改长度至少 12 位。data_volume 默认 /data要提前确认该分区剩余空间 20GB 以上建议单独挂一块盘。database.password 是 Harbor 内置 PostgreSQL 的 root 密码留着默认值非常危险顺手改掉。# harbor.yml 核心片段注释掉 https 段后 hostname: 192.168.10.21 http: port: 8080 harbor_admin_password: YourStrongPassw0rd database: password: change_me_db_pwd data_volume: /data/harbor log: level: infohostname 填 IP 是最省事的但如果后续要用域名访问这里就要填 FQDN 并在 /etc/hosts 里绑定。http.port 改掉后UI 地址变成 http://IP:8080同时 docker login 时也要带端口。data_volume 一旦配置完成后续数据就都往这个目录写装完再改目录会非常痛苦要提前规划好盘符。4.2 执行 install.sh镜像 load 阶段最需要的是耐心配置改好后直接执行安装脚本。如果不需要 Trivy 漏洞扫描和 Notary 签名直接 ./install.sh 就行需要的话加上对应参数。我一般会启用 Trivy离线环境下镜像扫描能力很宝贵。# 启动 Harbor 并附带 Trivy 漏洞扫描服务 ./install.sh --with-trivyinstall.sh 的执行分三个阶段。第一阶段检查环境脚本会逐项确认 docker、docker-compose、python 版本任何一项不满足就直接退出并打印具体缺失项。第二阶段是 docker load屏幕会滚动显示 loaded image 的进度这是整个安装中最长的过程日志看起来像卡住其实在做磁盘 IO。我在机械盘 ARM 机器上见过 load 一个 tar 包耗时四十分钟的别在此时重启 docker 服务否则前功尽弃。第三阶段是 prepare 和 up脚本根据 harbor.yml 生成 docker-compose.yml然后 docker-compose up -d 创建并启动容器。load 完成后会用 docker-compose ps 看到所有容器状态刚起来的一分钟内部分容器可能还在 healthcheck 中状态显示 starting 很正常。如果这阶段报错先别怀疑 Harbor 配置回去看 docker 日志和磁盘空间我在下面避坑章节会展开讲。4.3 装完怎么判断真的能用端口、日志、初始登录一句装完了不代表能用我会按顺序做三个验证。先看端口监听curl 一下配置的 http.port能返回 Nginx 默认页面说明入口通。再看核心容器日志docker logs harbor-core 里不能有 FATAL 或数据库连接失败的记录。最后打开浏览器访问 http://IP:端口用 harbor_admin_password 登录登录成功才算基础跑通。curl -I http://192.168.10.21:8080 docker logs harbor-core --tail 100 docker-compose psdocker-compose ps 输出里 STATUS 列要稳定在 Up 而不是 RestartingRESTARTS 列数字不要持续增长。curl -I 的结果里 HTTP 状态码 200 或 302 都正常302 是跳转到登录页的常见表现。如果 curl 直接报 connection refused基本是容器还没完全就绪等一两分钟再试还不行就进入排查阶段。提示首次登录后立刻改掉 admin 密码不行harbor_admin_password 只影响初始管理员密码登录后应该在 UI 里重新设置。5. 避坑实战记录ARM64 离线安装里我遇到的四个典型问题5.1 启动失败且 curl 报 connection refused端口冲突与 hostname 配置现象install.sh 正常执行完docker-compose ps 也显示容器 Up但 curl 本机端口就是不通。原因最常见的是 http.port 与宿主机已有服务冲突Nginx 或其它 Web 服务占用了 80 端口Harbor 的 Nginx 容器端口映射失败而 docker-compose ps 显示的容器状态可能还是 Up因为容器起来了端口绑定却失败。另一个常见原因是 hostname 写成了 reg.mydomain.com 却没有改 /etc/hostsHarbor 内部生成的 URL 指向了一个无法解析的域名。解决先 netstat -tlnp 看端口占用换成空闲端口再把 hostname 改成 IP 或者绑定 hosts最后 docker-compose down 再 up 让配置重新生效。netstat -tlnp | grep :80 docker-compose down docker-compose up -ddocker-compose down 会把已创建的容器删掉但数据卷保留所以重来一次不会丢数据。修改 harbor.yml 后必须完整 down 再 up只 docker-compose restart 有时不会重新生成配置。5.2 容器反复重启且日志出现 exec format error拿错了架构包现象docker load 成功但 harbor-core、harbor-db 等容器全部进入 Restarting 状态docker logs 报 exec format error 或 exec user process caused: exec format error。原因exec format error 是内核拒绝执行可执行文件本质是镜像架构与宿主机不匹配。你下载的是 x86_64 的离线包却在 ARM64 机器上安装了docker load 不检查架构容器一启动就露馅。解决确认包名里的 arm64 字样重新下载匹配架构的 harbor-offline-installer-v2.5.5-arm64.tgz。如果机器之前拉过错误架构镜像先 docker system prune -a 清理干净再重新解压安装。docker inspect harbor-core --format {{.Architecture}} uname -mdocker inspect 输出的 Architecture 如果是 amd64而 uname -m 显示 aarch64就实锤了架构错位。这个现象在国产化平台上特别迷惑人因为系统版本和 CPU 型号看起来都正常只有容器起不来。5.3 install.sh 卡在 Prepare 阶段磁盘空间、目录权限与 swap现象脚本走到 prepare 步骤后长时间无输出或直接报 no space left on device再或者提示无法写入 /data/harbor。原因离线包解压后十多个 GBdocker load 后镜像又占一份/data 分区被写满。另一个隐蔽原因是 data_volume 指向的目录权限不对install.sh 是以 root 执行的docker 容器内部进程可能没有该目录的写权限。解决df -h 确认数据分区有 20GB 以上余量把 data_volume 指向一个独立挂载点而不是根分区目录权限直接 chmod -R 755 并 chown 给 10000 用户Harbor 容器默认以 UID 10000 运行。df -h /data mkdir -p /data/harbor chmod -R 755 /data/harbor chown -R 10000:10000 /data/harborHarbor 的容器内进程刻意用非 root 用户运行宿主机目录如果属主是 root容器写不进去就会出现各种诡异失败。装完后再看 /data/harbor 下的数据库目录是否有数据增长如果为空基本就是权限没给对。5.4 国产化 ARM 系统上 docker-compose 命令不存在现象在银河麒麟 V10 或 CentOS 7 ARM 版本上docker 装好了但 install.sh 报 docker-compose: command not found。原因国产化系统的软件源里通常没有 docker-compose 包pip 源又访问不了离线环境下装不上 docker-compose。解决提前在有网机器上下载对应架构的 docker-compose 二进制传到目标机放到 /usr/local/bin/ 下并加执行权限。ARM64 的 docker-compose 官方发布时对应文件名里带 aarch64 或 linux-aarch64 标记。mv docker-compose-linux-aarch64 /usr/local/bin/docker-compose chmod x /usr/local/bin/docker-compose docker-compose --version注意 docker-compose 和 docker 的版本兼容性docker-compose 1.29.x 在 docker 20.10 上工作良好。如果系统里已经装了 docker compose 插件也可以做一个符号链接指向 docker-compose但 install.sh 的版本判断逻辑要以实际输出为准。5.5 镜像推送 500 错误且 registry 日志报 x509 认证问题现象docker login 成功docker push 时返回 500 Internal Server Errorregistry 容器日志里出现 x509: certificate signed by unknown authority。原因harbor.yml 里保留了默认 HTTPS 配置但证书是自签的docker 客户端不信任该证书导致 registry 请求服务端时 TLS 握手失败。解决纯内网环境最省事的做法是抛弃 HTTPS在 harbor.yml 里注释掉整个 https 段走 http.port 的明文 HTTP然后重新 down 再 up。宿主机 Docker 的 daemon.json 里也要把 Harbor 地址加进 insecure-registries。{ insecure-registries: [192.168.10.21:8080] }daemon.json 修改后必须重启 docker否则向 Harbor 推送时仍会走 HTTPS。这个坑在离线环境特别常见因为离线环境多数组件没有合法证书却保留着模板里的默认 HTTPS 配置。6. 装完不等于能交付用健康检查加一次真实推送做验收安装完成只是第一步交付给业务方之前还要做一次能留下记录的验收。我的做法是三步走先盯着容器健康状态再看 Harbor UI 能登录最后真正推一个镜像进去再拉出来。健康状态不要只看 docker ps要看每个服务是否通过 docker inspect 里的 Health 字段。Harbor 的容器镜像里内置了健康检查脚本STATUS 列显示 healthy 才算稳定如果显示 unhealthy即使端口能访问后续推送也可能出问题。接着做一次真实推送测试在业务机上打一个标签推送到 Harbor 项目里再删除本地镜像后 pull 回来这个流程能验证网络、认证和存储三个关键链路。# 在客户端完成一次 Harbor 镜像推送 拉取回环验证 docker login 192.168.10.21:8080 -u admin -p YourStrongPassw0rd docker tag busybox:latest 192.168.10.21:8080/library/busybox:test docker push 192.168.10.21:8080/library/busybox:test docker rmi 192.168.10.21:8080/library/busybox:test docker pull 192.168.10.21:8080/library/busybox:testdocker login 的密码如果包含特殊字符建议用交互式输入而不是命令行明文。push 能成功说明客户端到 registry 的通路没问题pull 能成功说明存储里的镜像可以被正常读取和分发。做完这个回环测试再让业务方把流水线切过来。我现在的习惯是每次离线部署完成后把 harbor.yml、docker-compose.yml、客户端 daemon.json 三个文件的最终版备份到一个固定目录标好日期和架构。这套流程跑熟了之后Harbor 的 ARM64 离线安装对我来说就不再是陌生操作而是像 tar 解压一样自然。后续升级时这个备份目录就是最可靠的后悔药。希望帮到你。本文还有配套的精品资源点击获取