简介面向ARM64架构下的Kubernetes与Docker环境Harbor v2.13.1离线安装包专为运维人员准备核心价值是在无外网或内网隔离的ARM服务器上快速部署私有镜像仓库。压缩包为tgz格式共6个文件包含install.sh与common.sh两个Shell脚本分别负责安装执行和公共函数加载harbor.v2.13.1.tar.gz是完整的主镜像包提供Harbor全部组件prepare与harbor.yml.tmpl用于环境预检及核心配置模板LICENSE文件则明确使用许可。整体约679MB结构清晰适合作为生产环境部署的基线资产。目前已有528人学习下载特别适合在信创ARM平台、边缘计算节点或离线机房中搭建镜像管理系统的工程师。拿到手后可直接解压依据模板修改端口、存储路径、证书等参数再执行安装脚本即可完成部署资源同时持续跟进新版离线包便于后续升级维护。1. 先讲清楚Harbor 最新 v2.13.1 的 ARM64 离线安装包解决的是什么问题一台只有 ARM64 CPU 的服务器网络和公网隔离却要搭一个生产可用的镜像仓库这时候最常见的答案就是 Harbor 最新 v2.13.1 的 ARM64 离线安装包。它不是在线装完后“导出的备份”而是官方为 aarch64 架构单独打的离线发行包harbor-offline-installer-v2.13.1-arm64.tgz。包内置了 Harbor 全部组件镜像的 tar 捆从解压到浏览器打开 UI全程不需要外网。这个方案适合三类人在做国产化适配的交付工程师、给边缘机房离线交付的平台组以及接手 ARM64 服务器却不想折腾源码编译的运维。注意一个关键事实它和 x86 的包是两个文件拿错包在 ARM64 机器上启动时会直接报 exec format error这一步走错后面全是黑匣子后面会专门讲。2. 安装之前ARM64 离线包和 x86 包差在哪环境怎么准备2.1 架构差异与离线包的命名规则标题里的“ARM64 版离线安装包”在 Harbor 官方 Release 里对应的是带 arm64 后缀的 tgz。v2.13.1 这个版本同时发布几种安装介质x86_64 机器上用 harbor-offline-installer-v2.13.1.tgzaarch64 对应 harbor-offline-installer-v2.13.1-arm64.tgz另外还有面向 Helm Chart 和 FIPS 加固的包。离线包内部结构一致但 harbor.v2.13.1.tar.gz 里的镜像架构不同x86 包导出的是 amd64 镜像层ARM64 包导出的是 arm64/v8 镜像层。有人会问“Harbor 镜像不是 multi-arch 吗我在 ARM64 上 load x86 包能不能跑”manifest 列表确实是多架构的但 docker save 导出的是具体某个镜像 manifest 下的层不是把整个列表塞进去。你把 amd64 的 tar 在 aarch64 上 load 出来docker images 能看到docker run 才暴露问题harbor-core、harbor-registry 这类容器一启动就抛 “exec format error”反复 CrashLoopBackOff。还有一类更隐蔽的情况在 x86_64 开发机上用 qemu 模拟 ARM64 来“体验”这个离线包。qemu user-mode 确实能让 amd64 容器跑起来但 Harbor 这种带数据库、JobService 多服务的编排在 qemu 下经常遇到线程库和信号处理不兼容的问题安装脚本里部分探测命令也会因为模拟器行为差异给出错误结果。可以做冒烟测试但不建议作为交付依据。我一般拿到机器第一件事就是 uname -m 和 docker info 看 Architecture再决定用哪个包。这个动作 10 秒钟能省掉后面一整天的排障。2.2 离线包里装的是什么组件清单与数据流解压离线包后目录里最关键的是这几个文件mkdir -p /opt/harbor-install cd /opt/harbor-install tar -xzf harbor-offline-installer-v2.13.1-arm64.tgz cd harbor ls -lh # 主要文件 # harbor.yml # 唯一需要手改的配置入口 # install.sh # 离线安装总入口 # prepare # 生成 docker-compose.yml 的预处理工具 # common.sh # 安装脚本公共函数含镜像列表 # harbor.v2.13.1.tar.gz # 所有组件镜像的 docker save 产物 # LICENSE # 软件许可这里我不建议手动docker load -i harbor.v2.13.1.tar.gzinstall.sh 会自动做但你要知道这个 tar 很大。ARM64 版整包通常以 GB 计加上解压后的镜像层、数据卷磁盘预留至少要比 tar 大一倍。Harbor v2.13.1 的组件镜像包括harbor-coreAPI 和调度核心、harbor-registry镜像存储基于 Docker Distribution、harbor-db内嵌 PostgreSQL、harbor-portal前端页面和反向代理、harbor-jobserviceGC、复制、漏洞扫描等后台任务、harbor-log统一日志收集、harbor-registryctl保护 registry 配置的辅助容器再加上可选的 trivy-adapter漏洞扫描、notary-server / notary-signer镜像签名。这些服务安装后由 docker compose 编排端口和数据卷都从 harbor.yml 映射出来。理解这个组件清单对排错很重要。比如 push 失败时你至少要知道流量先到 harbor-portal监听 80/443再反代到 harbor-core最后由 core 把镜像层转发给 harbor-registry。任何一层的容器没起来报错都像“连接被拒”。我见过有人把 harbor-portal 容器误删后整整一天在改客户端 daemon.json方向完全错了。2.3 环境预检磁盘、内存、Docker 与端口离线包虽然免外网但目标机器本身要满足最低运行条件。我习惯按生产标准而不是官方最低要求来预检避免装完发现是纸面部署# 确认 CPU 架构必须是 aarch64 uname -m # 期望输出: aarch64 # 确认磁盘镜像数据目录所在分区预留 100GB 以上按实际业务量调整 df -h /opt /data # 确认内存含 Trivy 建议 8GB 以上不含至少 4GB free -h # 确认 Docker版本不低于 20.10且是标准的 containerd 运行时 docker version --format {{.Server.Version}}几个容易翻车的点注意一下。第一如果是 Ubuntu 系Harbor 容器默认用 host 网络和自定义 bridge升级内核或重启 Docker 后 iptables 策略可能变化安装前把 docker.service 设为开机启用并确认没有防火墙规则挡 80/443。第二Harbor 的 data_volume 不要放在系统盘根分区镜像仓库的存量增长比想象快。第三如果这台机器之前装过旧 Harbor先确认 compose 项目名和网络名是否冲突避免安装脚本“以为你升级”而实际是并存部署。我之前在一个残留环境上直接跑 install.sh结果新旧两套容器同时监听 80 端口谁也起不来。Docker 与 compose 的版本配合也很关键。Harbor v2.13.1 的 install.sh 同时兼容 docker-compose v1docker-compose 命令和 v2docker compose 子命令。但如果你机器上同时有这两个命令脚本默认用 compose v2而你后续手动维护时用 v1 操作两个命令看到的是不同的项目元数据升级时就容易“找不到项目”。统一用一种语法别混用。3. 用离线包安装 Harbor v2.13.1解压、改配置、跑脚本3.1 解压与修改 harbor.yml6 个必动参数进入解压目录后先备份默认配置再改这是后悔药cd /opt/harbor-install/harbor cp harbor.yml harbor.yml.bak vim harbor.ymlHarbor v2.13.1 的配置项很多但离线部署真正需要动的是下面这 6 个。改错了不至于立刻报错但后续 push/pull 一定会反噬所以一次改对。参数默认值离线环境建议hostnamereg.mydomain.com填客户端能访问到的 IP 或域名比如 192.168.209.133http.port80保持 80除非和系统服务冲突客户端端口要与此一致harbor_admin_passwordHarbor12345至少 12 位包含大小写和数字首登后建议轮换data_volume/data改成挂载大分区的绝对路径例如 /data/harbordatabase.passwordroot123改成独立强密码别和 admin 密码相同trivy.skip_updatefalse离线环境改成 true否则 Trivy 启动会尝试连公网更新漏洞库说明一下关键逻辑。hostname 是最容易踩坑的如果填 localhost 或者 127.0.0.1外部机器 push 时 Docker 客户端把仓库地址解析到它自己的回环地址直接连接被拒。建议填局域网 IP 或规划好的域名并让所有客户端能解析到这个地址。http.port 改动时客户端 insecure-registries 里的端口也要跟着变两处不一致是高频翻车点。data_volume 决定镜像 blob 落在哪后续迁移备份都依赖这个路径升级时路径不能变否则旧数据就像消失了一样。3.2 prepare 与 install.sh核心命令到底干了什么配置改完后官方离线安装入口是 install.sh但很多新人不理解 prepare 的作用。install.sh 内部会调用 prepare不过我建议手动跑一次 prepare 来暴露问题减少把错误攒到启动阶段# 预处理基于 harbor.yml 生成 docker-compose.yml 和配置文件 ./prepare # 如果上面输出正常再执行安装按需开启 Trivy 和 Notary sudo ./install.sh --with-trivy --with-notaryinstall.sh 的执行顺序大致是读取 common.sh 里的镜像列表 → 用 docker load 导入 harbor.v2.13.1.tar.gz → 检查 compose 是否存在 → 调用 prepare 生成 docker-compose.yml 与各组件配置 → 最后 docker compose up -d 拉起所有服务。几个容易忽略的点install.sh 需要 root 或 sudo 权限因为要创建数据卷目录、写日志相关配置你不用事先生成 docker-compose.ymlprepare 会按 harbor.yml 生成手动去改 docker-compose.yml 反而会在 prepare 时被覆盖。--with-trivy 和 --with-notary 是按需组件。离线环境里 Trivy 的漏洞库如果不打算更新必须保证 harbor.yml 里 skip_update: true否则 trivy-adapter 容器反复重启。notary 只在需要镜像签名时开默认可以不开省一点内存。另外注意一个细节prepare 脚本会检测 docker-compose 是否可用如果系统里只有 docker 没有 compose 插件安装会在这一步骤中断。Debian/Ubuntu 系通常要单独装 docker-compose-plugin 或 docker-compose-v2 包。3.3 首次验证容器列表、健康检查与 UI安装过程正常等一两分钟后用 compose 看状态cd /opt/harbor-install/harbor docker compose ps # 期望看到 harbor-core、harbor-db、harbor-registry、harbor-portal 都是 running # 用 docker ps 过滤确认没有 CrashLoopBackOff docker ps -a --format {{.Names}}\t{{.Status}} | grep -E harbor|trivy|notary我没有加 --with-chartmuseum 这类旧组件开关。Harbor 从 2.8 左右的版本开始默认不装 chartmuseum新版本里 Chart 仓库能力已经调整所以在 v2.13.1 上不要硬找这个开关除非你明确需要旧版兼容。UI 验证直接浏览器访问 http:// 账号 admin 加 harbor.yml 里设置的密码。命令行验证更靠谱curl -u admin:你的密码 http://192.168.209.133/api/v2.0/projects # 返回 JSON 数组即说明核心 API 正常如果这里通但页面打不开先看 harbor-portal 容器日志往往是前端静态文件权限或者代理配置问题和核心服务无关。到这里一个 ARM64 的 Harbor 已经能用了但上线前把下一章的四个坑过一遍能少走不少弯路。4. ARM64 离线环境避坑4 个高频问题的现象、原因和解决4.1 坑 1qemu 模拟 ARM64 导致容器反复重启现象在 x86 开发机上用 qemu 模拟 ARM64 跑安装脚本install.sh 执行完docker compose ps 显示 harbor-db 一会儿 Up 一会儿 Restarting日志里出现数据库初始化失败。偶尔还会看到容器以类似 “bad linux arm64 image magic!” 的格式错误退出其实是宿主内核在尝试以自身架构解析镜像二进制。原因qemu user-mode 的“模拟”只覆盖用户态系统调用Harbor 中 harbor-db 依赖的 PostgreSQL 对并发和信号处理比较敏感而镜像格式检查发生在内核 exec 路径qemu 配合 binfmt_misc 时某些轻量环境没有注册 aarch64 解释器于是内核拿 x86 的逻辑去读 ARM64 的 ELF直接报错。这不是 Harbor 的问题是运行环境没真正具备执行 ARM64 二进制的能力。解决不要在 x86 机器上交付 ARM64 部署。真的要测试用支持硬件虚拟化的 ARM64 云主机或者带 aarch64 的工控机。如果已经在模拟环境踩进去了先把 binfmt_misc 注册好比如 Debian 系上执行update-binfmts --enable qemu-aarch64能救回来一部分场景但也只是“能 run”不代表生产可用。结论明确ARM64 离线包必须跑在真 ARM64 主机上否则你后续排查的所有问题都可能被模拟器噪声干扰。4.2 坑 2docker push 报 dial tcp 192.168.x.x 连接被拒现象在客户端机器上执行 docker push报错形如get https://192.168.209.133/v2/: dial tcp 192.168.209.133: connect: connection refused注意报错 URL 里 IP 后面的端口或协议不对。原因往往不是 Harbor 挂了而是三选一harbor-portal 没监听该地址harbor.yml 里 hostname 配的是 localhost客户端和 Harbor 不在同一网段但配置里用了无法路由的 IP。这类错误几乎每天都有同行遇到单看报错确实像服务没起。解决先在 Harbor 服务器本机用 curl 验证curl -v http://192.168.209.133/v2/ # 本机通、客户端不通查防火墙和安全组端口 # 本机也不通回到 harbor.yml 检查 hostname 和 http.port确认 harbor.yml 中 hostname 是实际可路由的 IP重新./prepare sudo ./install.sh让改动生效。然后客户端 push 之前把仓库地址显式写成 IP:端口同时确认 docker 配置的 insecure-registries 覆盖了该地址HTTP/HTTPS 协议才不会打架。4.3 坑 3HTTP registry 被 Docker 客户端拒绝insecure-registries现象Harbor 走 HTTP未配置证书客户端 docker login 提示Error response from daemon: Get http://192.168.209.133/v2/: http: server gave HTTP response to HTTPS client原因Docker 客户端默认只信任 HTTPS registryHTTP 需要在 daemon.json 里显式声明为 insecure registry。这是自建 Harbor 最常踩的一道门槛和服务端无关。很多新手看到报错里的 http 字样以为是 Harbor 配置问题其实问题在客户端 Docker 守护进程。解决在每台要 push/pull 的客户端机器上改 /etc/docker/daemon.json{ insecure-registries: [192.168.209.133, 192.168.209.133:80] }改完先sudo systemctl reload docker再 docker login。如果还报错就重启 dockersudo systemctl restart docker。注意 reload 对 daemon 配置不一定完全生效重启更稳但会造成节点上正在运行的容器短暂中断生产环境挑窗口操作。这里有一个经验insecure-registries 的列表是“地址端口”的精确组合只写 IP 不写端口而你 push 时又写了端口系统会认为这是另一台机器重新走 HTTPS 验证照样失败。所有节点上的地址、端口、协议要保持一致。4.4 坑 4从旧版跨版本升级数据库迁移失败现象旧版本 Harbor比如 2.9直接用 v2.13.1 的 install.sh 覆盖启动后 harbor-core 或 harbor-db 报迁移失败日志里出现找不到表或列。原因Harbor 数据库迁移是逐个版本累积的跨两个以上大版本时install.sh 不一定帮你补中间步骤prepare 生成的数据库初始化脚本只针对当前版本。解决不要在 ARM64 离线环境里强行“跳级”。升级前备份整个 data_volume尤其是 /database 子目录然后按官方路径逐版本升级。比如 2.9 → 2.10 → 2.11 → 2.12 → 2.13.1每个版本下载对应离线包、改好 harbor.yml 的路径保持不变、跑 prepare 和 install.sh。如果你拿的是 ARM64 包确认每个中间版本都有 arm64 产物没有的话说明该版本不支持 ARM64不要硬用 x86 包加 qemu 凑合。这条没有捷径数据库迁移不是玄学是建表语句的依赖链。5. 把离线部署变成可持续操作升级路径与三层验证到这里Harbor v2.13.1 的 ARM64 离线安装已经不是一次性动作。我建议把“装完”当起点把升级和验证固化成脚本因为它直接决定这个离线包投入值不值。升级路径方面常见做法是备份 data_volume → 停旧服务 → 解压新版本 ARM64 离线包 → 沿用旧的 data_volume 路径和数据库密码 → 执行 prepare → 执行 install.sh组件开关保持和升级前一致。升级后健康检查要单独做尤其是数据库迁移。我给一个三层验证脚本的最小示例#!/bin/bash # 验证脚本check_harbor.sh HOST192.168.209.133 ADMINadmin PASS你的密码 # 第一层容器都起来且没有 CrashLoopBackOff docker ps -a --format {{.Names}}\t{{.Status}} | grep harbor | grep -v Up # 第二层核心 API 返回 200 curl -s -o /dev/null -w %{http_code} -u $ADMIN:$PASS \ http://$HOST/api/v2.0/health # 第三层实际推拉一个测试镜像离线环境用 busybox arm64 镜像 docker push $HOST/library/test:arm64 docker pull $HOST/library/test:arm64第三层最接近真实用户体验最容易暴露配置不一致问题比单纯看 docker compose ps 更可靠。我习惯在一次升级后完整跑一遍三层前面两层挂掉立即停止后续操作因为数据库迁移失败后再推镜像故障现场会被污染。还有一个验证升级后配置的技巧升级前把旧的 docker-compose.yml 复制一份升级后 diff 一下看数据卷映射和网络是否有非预期变化这是容器化部署里少有的便宜可靠的后悔药。凡是容器、存储、网络卷标有漂移优先怀疑 compose 项目名和 network 名冲突而不要先怀疑 Harbor 程序本身。硬件层面保留一条快速回滚动作备份 data_volume 后压缩到独立文件系统万一升级失败解压回去再把旧版本离线包 install 一遍。在 ARM64 机器上做这件事比在 x86 上更慢因为 Postgres 数据文件的 io 压力会直接拖慢恢复。所以我的习惯是能一次升级到位就不反复切版本否则等待时间都会让你怀疑人生。是否值得投入这个方向我的判断是离线、ARM64、私有化交付这三个词叠加时Harbor 的官方 ARM64 离线包几乎是目前把方案落地成本压到最低的路径。它比在线安装少一个外网依赖比自编译省掉一整个工具链比跨架构模拟稳定得多。只要把 hostname、端口、insecure-registries 和版本升级路径这四个点管住这个方案就是能长期运转的。把第一次排障学到的经验写进脚本比记住“重启大法”更有用希望帮到你。本文还有配套的精品资源点击获取