ARM64环境Harbor 2.8.2离线安装与镜像推送避坑指南

简介：面向ARM 64位架构的Harbor 2.8.2离线安装包，专为在无外网或受限网络环境中部署容器镜像仓库的运维与开发人员准备。资源共6个文件，包括安装脚本、环境准备工具、公共函数库、配置模板、许可文件及核心镜像离线包，可完整支撑Harbor在ARM服务器上的静默安装与配置，无需从公网拉取额外组件。离线包约639.65MB，体积控制得当，便于内网传输、离线分发和批量部署。已有261人学习下载，适合边缘计算、物联网、信创及私有化部署场景。借助该包，用户可快速搭建企业级镜像仓库，启用权限控制、镜像复制与漏洞扫描能力，并支持LDAP/AD等身份认证集成。对于需要在国产化ARM设备上高效交付Harbor服务的团队，这是一款开箱即用、省时省力的基础资源。

1. 先别急着解压：arm 环境的 Harbor 2.8.2 离线包，落地前要把这三件事想清楚

拿到harbor-offline-installer-v2.8.2-arm64.tar.gz，多数人第一步就是解压、改harbor.yml、跑install.sh。在 x86 服务器上这条路很顺，但换成 arm 环境后，同样的操作往往会在加载镜像、权限校验、架构匹配这些环节上卡住。这份离线包解决的问题，是把 Harbor 2.8.2 的所有依赖容器以 arm64 镜像形式一次性带到内网，绕过在线拉取的不确定因素。它的适用对象很明确：只有 arm64 服务器的私有化环境，以及希望在断网或弱网条件下把镜像仓库立起来的团队。下面从环境自查、离线安装、镜像推送写到备份升级，全程用可以直接复制的命令，并标注那些只有真正在 arm 上装过才会遇到的边界条件。

2. 环境自查与前置准备：arm64 离线包不是解压就能跑的

2.1 先确认机器是 arm64：三条命令看清真实架构

arm 这个词在工程里被用得很乱。有人说的 arm 指 32 位的 armv7，有人说的是服务器级的 aarch64，也就是 armv8 的 64 位指令集。harbor-offline-installer-v2.8.2-arm64.tar.gz里的arm64明确指向后者，所以在动手之前，先要在目标机器上确认架构，否则后面每一步都可能因为镜像平台不匹配而中断。

uname -m lscpu | grep Architecture cat /proc/cpuinfo | grep -E "model name|CPU architecture" | head -5

第一行uname -m是判断架构最直接的方式，输出aarch64才是这个离线包的目标平台；输出armv7l或armhf说明机器是 32 位 arm，需要换对应架构的 Harbor 包，不要硬装。第二行lscpu能看到完整架构信息，第三行用来确认具体 CPU 型号，方便后续排查内核与虚拟化相关的问题。无论是物理服务器、云实例还是虚拟机，只要三条命令的结果指向 aarch64，这个离线包就可以继续往下走。

确认完架构，还要看一眼操作系统内核版本。Harbor 的容器运行时依赖 docker daemon，而 docker daemon 对内核版本有明确要求。常见做法是用uname -r查看内核，如果小于 4.0，建议先升级系统内核，否则容器在初始化 cgroup 时可能报错；这类问题在 arm 的单板设备上比 x86 更容易遇到，因为很多 arm 板子出厂带的是非常老的定制内核。

2.2 依赖组件检查：docker、docker compose 与系统工具

Harbor 2.8.2 的安装脚本依赖两个核心组件：docker 和 docker compose。需要注意，Harbor 2.8 系列使用的是 docker compose v2，也就是集成在 docker CLI 里的docker compose子命令，而不是早年那种独立的docker-compose二进制。如果目标机器上只有旧版独立二进制，安装脚本会在前置检查阶段直接报错，根本走不到部署那一步。

docker version --format '{{.Server.Version}}' docker compose version openssl version tar --version | head -1 free -h df -h /data

上面这段命令把后续安装会用到的工具一次性查完。docker version确认 server 端版本在 20.10 以上，docker compose version确认 v2 插件存在，openssl和tar是解压和证书生成阶段的依赖，最后两行看内存和磁盘。建议内存不低于 4GB，至少预留 20GB 磁盘空间给 Harbor 的数据目录。离线包本身和启动后的镜像、数据库日志都会落在data_volume上，磁盘太满会导致 registry 容器反复重启，这类问题排查起来非常消耗时间。

在离线环境下还有一个容易被忽略的点：整个安装过程不会去外网拉任何东西，但前提是 docker 本身已经装好。如果目标机器连 docker 都没有，那就得先用离线 deb/rpm 包把 docker 装好，再回来跑 Harbor 的离线包。我习惯把这一步单独写成一段检查脚本，避免人工漏看：

if [ "$(uname -m)" != "aarch64" ]; then echo "架构不匹配，当前是 $(uname -m)" exit 1 fi if ! docker version >/dev/null 2>&1; then echo "docker 未安装或无法访问 docker daemon" exit 1 fi if ! docker compose version >/dev/null 2>&1; then echo "缺少 docker compose v2 插件" exit 1 fi echo "preflight OK"

这段脚本的逻辑是逐项卡住最关键的三个前置条件，任何一个不满足就立刻退出，而不是等到install.sh跑了一半才暴露问题。参数说明：uname -m判断架构，docker version同时检查 docker 客户端和 daemon 是否可用，docker compose version判断 v2 子命令是否存在。注意脚本里没有检查内存和磁盘，因为这两个值在安装过程中可以用free和df人工确认，写死在脚本里反而会在不同机器上产生误判。

做完这些检查，就可以进入真正的安装环节。前置准备这一段花十分钟，能省掉后面一两个小时的无头绪排查。

3. 离线安装全流程：从解压 tar.gz 到 Harbor 页面可访问

3.1 解压与 harbor.yml 配置：三个必改项

离线包的解压没有特殊之处，tar 命令就能完成。解压后会出现一个 harbor 目录，里面除了install.sh和prepare，还有harbor.yml、harbor.yml.tmpl、common.sh等文件。install.sh是入口脚本，prepare负责生成运行时配置，harbor.yml是唯一需要人工修改的配置文件。

tar -xzf harbor-offline-installer-v2.8.2-arm64.tar.gz cd harbor ls -la

解压完成后，ls -la可以看到上述文件。注意整个解压过程不涉及 root 权限，但后续install.sh需要 root 权限，因为要创建容器和挂载目录。接下来打开harbor.yml，这个文件是 YAML 格式，缩进错误会导致后续prepare阶段报错。需要修改的配置项并不多，但有几个是必须改的，不然装完也用不了。

hostname必须改成实际能访问到这台机器的地址。如果配的是域名，客户端需要在 DNS 里解析到这台机器；如果配的是 IP，页面登录时会有一条 URL 不匹配的警告，但不影响功能。http.port默认 80，很多 arm 服务器上 80 已经被其他服务占用，改成 8080 是常见操作。harbor_admin_password是安装时写死到数据库里的初始密码，安装之后在页面上修改不会同步回这个文件。data_volume建议指到一块独立的数据盘，而不是根目录，否则镜像多了以后根分区被撑满，整个系统都会出问题。

下面是一份最小可用的配置片段：

hostname: 192.168.10.20 http: port: 8080 harbor_admin_password: "Admin@2024" data_volume: /data/harbor

这段配置把服务绑定在192.168.10.20:8080，管理员密码设为Admin@2024，数据落盘在/data/harbor。如果本机有 python3，建议在保存之后先做一次 YAML 语法校验：

python3 -c 'import yaml; yaml.safe_load(open("harbor.yml"))'

这个命令会把harbor.yml读入并解析，如果缩进或引号有问题，会立即抛出异常；没有任何输出就说明格式没问题。很多人在这里直接跳过校验，结果安装时报unexpected end of stream，排查起来才知道是 yaml 语法错误，浪费时间。

3.2 执行 install.sh：选对参数，一步到位

配置写完，接下来是执行安装脚本。最简形式是直接运行sudo ./install.sh，脚本会自动检查依赖、加载离线包内的镜像 tarball、调用 prepare 生成 compose 配置，然后用 docker compose 启动全部容器。

cd harbor sudo ./install.sh # 前置检查通过后，所有镜像由离线包内自动加载

如果想要漏洞扫描能力，可以带--with-trivy参数，这样会额外启动一个 trivy 容器用于扫描镜像漏洞。如果不需要扫描功能，建议先不加这个参数，trivy 会占用额外内存，在内存紧张的内网 arm 服务器上，这往往是压垮系统的最后一根稻草。

安装过程中会看到脚本输出从检查环境到加载镜像、生成配置、启动容器的一系列进度。如果机器性能一般，镜像加载和容器启动会持续几分钟，这是正常的。真正需要警惕的是脚本在中途异常退出，退出码为 1，这类问题的处理我放在第 5 章详细讲。

安装完成后，先看容器状态：

cd harbor sudo docker compose ps curl http://localhost:8080/api/v2.0/ping

docker compose ps应该看到log、registry、core、portal、db、jobservice、redis这些服务全部处于 Running 状态。如果有容器反复重启或者处于 Exited 状态，用sudo docker compose logs <服务名>查看对应日志。curl探测的路径是 Harbor 的 API 健康检查接口，正常会返回一个Pong字符串。这里直接用 HTTP 探测即可，因为默认harbor.yml里没有启用 HTTPS。如果是在远程执行，把 localhost 换成实际 IP 或域名。

到这里，Harbor 已经算是装起来了。浏览器访问http://192.168.10.20:8080，用 admin 和配置的密码登录，就能看到管理界面。但“页面能开”只代表服务活着，真正判断一个私有镜像仓库能不能用，要看它是否支持客户端推送和拉取镜像，这是下一章的内容。

4. 仓库初始化与镜像推送：arm64 离线包装完怎么才算“能用”

4.1 客户端配置：把 docker 的“不信任”改掉

Harbor 装好之后，客户端默认是连不上它的。原因在于 docker 客户端对待 HTTP 和 HTTPS 的策略：默认情况下，dockerd 只信任 HTTPS 的 registry 地址，而我们在harbor.yml里配置的是 HTTP。这时候如果不做任何设置，docker login会直接报错。解决方式有两种，一是给 Harbor 配正规的 HTTPS 证书，二是让 docker 对这个地址放行 HTTP，后者在 arm 开发环境里更常见。

sudo tee /etc/docker/daemon.json <<EOF { "insecure-registries": ["192.168.10.20:8080"] } EOF sudo systemctl restart docker

insecure-registries告诉 dockerd，访问192.168.10.20:8080这个地址时不要强制 TLS 校验。配置完必须重启 docker，否则配置不生效。这里有一个很容易踩的细节：数组里必须写完整的IP:端口，只写 IP 的话，docker 不会把带端口的地址视为不安全的 registry，登录时依然会尝试 HTTPS。

重启之后，先确认配置生效，再登录：

docker info | grep -i "insecure" docker login 192.168.10.20:8080

docker info输出里会列出所有 insecure registry 地址，看到刚配置的哪一行就说明生效了。登录时输入 admin 和之前设置的密码，出现Login Succeeded就说明客户端与 Harbor 之间已经打通。如果报错，大概率是daemon.json语法有误或者 docker 没重启成功，用sudo systemctl status docker看一眼就能定位。

这里需要说明一个选型判断：insecure-registries 适合内网和测试环境，生产环境还是应该走 HTTPS。arm 环境里很多团队为了省事一路 HTTP 用到底，但如果 Harbor 要暴露给多个网段的客户端，建议至少用自签证书并把 CA 分发到各客户端，否则每次新接入一台机器都要手工改 daemon.json。两种方式二选一，不要混用，混用最容易出现“这台机器能登录、那台机器报 x509”的诡异局面。

4.2 推一个 arm64 镜像：完整的 tag-push-pull 闭环

登录成功之后，第一件要做的事情是确认要推送的镜像本身是 arm64 架构。Harbor 只是一个镜像仓库，它不会做跨架构转换，推送上去是什么架构，拉取时就会匹配什么架构。

docker image inspect --format '{{.Architecture}}' busybox

如果输出不是arm64，而是amd64，说明这个镜像在 x86 上拉取过，架构不对。在 arm64 节点上想拿到正确架构的镜像，常见做法是显式指定平台重新拉取：

docker pull --platform linux/arm64 busybox:latest docker image inspect --format '{{.Architecture}}' busybox

--platform参数会强制拉取 manifest 列表中 arm64 版本的镜像。拉取完成后 inspect 输出arm64，就可以继续下一步了。

docker tag busybox:latest 192.168.10.20:8080/library/busybox:latest docker push 192.168.10.20:8080/library/busybox:latest

docker tag的作用是给本地镜像打上目标 registry 的完整地址标签，docker push会按标签里的地址把镜像上传到 Harbor。library是 Harbor 默认创建的一个公共项目，推送进去之后所有客户端都能拉取。在另一台同样配置了 insecure-registries 的 arm 节点上，执行：

docker pull 192.168.10.20:8080/library/busybox:latest

能正常拉下来，整个推拉闭环就算打通了。如果拉取时报no matching manifest for linux/arm64，说明推送上去的镜像不是 arm64 架构，回到上面用--platform linux/arm64重新拉取并 tag 推送。这个错误是 arm 环境里跑镜像仓库最常遇到的坑，本质上是镜像内容与运行平台的匹配问题，跟 Harbor 本身没有关系。

5. 避坑：arm 环境安装 Harbor 最容易翻车的 4 个问题

5.1 现象：install.sh 执行到一半报错，exit code 1

在 arm 服务器上跑sudo ./install.sh，前置检查全部通过，但脚本在启动容器阶段中断，最后只留下一行 exit code 1。这个问题我在 arm 环境里遇到过不止一次，原因通常有两个。

第一个原因是 docker compose 版本不对。Harbor 2.8.2 的 compose 配置文件依赖 docker compose v2 的语法，如果宿主机上的 compose 是旧版独立二进制，解析就会失败。解决方式是确认docker compose version能正常输出 v2 版本号，必要时升级 docker。

第二个原因是之前有过一次失败安装，残留的容器或数据目录占住了位置。解决方式是先清理再重跑：

cd harbor sudo docker compose down sudo docker ps -a | grep harbor | awk '{print $1}' | xargs docker rm -f sudo rm -rf /data/harbor/database sudo ./install.sh

注意最后一步删数据库目录要慎重，只有确认数据不需要保留时才执行。如果数据很重要，应该备份而不是删除。这一段的操作逻辑是：docker compose down只停容器不删数据，rm -rf database才是真正清空数据库，顺序不能反。另外一个容易忽略的问题：部分 arm 板子用的老内核跑 docker 时，容器初始化 cgroup 会失败，从日志里能看到与 namespace 或 cgroup 相关的报错，这种情况下只能升级内核，没有捷径。

5.2 现象：docker login 报 x509：certificate signed by unknown authority

客户端已经配了insecure-registries，登录时仍然报x509: certificate signed by unknown authority。这个现象的原因往往不在 Harbor，而在 daemon.json 的配置没有真正生效。

排查步骤是先重启 docker，再确认配置被正确加载：

sudo systemctl restart docker docker info | grep -i insecure

如果docker info里看不到刚配置的地址，说明 daemon.json 的语法可能有误，或者路径不对。另外要确认 daemon.json 里没有同时配置多个 registry 服务，导致格式变成 JSON 数组嵌套错误。还有一种情况是 Harbor 启用了 HTTPS，而客户端只配了 HTTP 的 insecure。两者必须一致：Harbor 用 HTTP，客户端就配 insecure；Harbor 用 HTTPS 加自签证书，客户端就应该把 CA 放到/etc/docker/certs.d/<hostname>:<port>/ca.crt。我自己的血泪经验是，不要一半机器走 insecure、一半机器走证书，统一一种方式，否则每接入一台新机器都要现场改配置。如果排查时想快速定位问题，可以先看 docker daemon 的日志：

sudo journalctl -u docker --since "5 minutes ago" | grep -i insecure

这条命令能直接看到 dockerd 启动时有没有加载 insecure-registries 配置。如果日志里没有相关记录，说明配置文件没有被读取，优先检查路径和 JSON 语法。

5.3 现象：镜像推送到一半失败，或者 push 成功但 pull 报 manifest 不匹配

推送一个几十 GB 的大镜像，进度条到 90% 左右断掉，重试几次还是断在同一个位置。这个问题在 arm 内网环境里多半不是 Harbor 的锅，而是客户端与 Harbor 之间的网络链路不稳定，尤其是跨网段推送大文件时，TCP 连接很容易被中间设备掐断。

解决方式有两个方向。一是在网络条件改善后再推，二是不走 docker push，改用镜像归档文件直接传输。后一种在离线环境里反而更稳妥：

docker save 192.168.10.20:8080/proj/app:arm64 | gzip > app-arm64.tgz scp app-arm64.tgz node2:/tmp/ docker load < app-arm64.tgz

docker save把镜像导出为 tar 流，gzip压缩后通过scp拷贝到目标节点，docker load再导入。这个方案绕开了 docker push 对网络的要求，适合大镜像跨网段同步。另一种常见的失败是 push 成功，但到另一台机器 pull 时报no matching manifest for linux/arm64。这种情况的根本原因是推送时用了 amd64 镜像，解决方式是先docker pull --platform linux/arm64拉取正确架构，再重新 tag 和 push，与第 4.2 节的处理方式一致。要注意docker save和docker load是一对操作，不要在中间环节混入其他工具，否则镜像 meta 信息容易丢失。

5.4 现象：页面能打开，但 docker push 总在连接阶段超时

Harbor 页面在浏览器里能正常打开，但在客户端执行docker push时长时间卡住，最后报连接超时。这个现象看起来矛盾，实际原因通常是 HTTP 与 HTTPS 协议不一致。

浏览器访问http://192.168.10.20:8080没问题，但客户端 push 时如果daemon.json里没有配置完整的IP:端口，docker 会默认用 HTTPS 去连 Harbor，而 Harbor 只监听 HTTP，TCP 握手之后协议不匹配，连接就挂在那里直到超时。解决方式是检查并修正 daemon.json：

cat /etc/docker/daemon.json

重点看insecure-registries数组里是否包含完整的192.168.10.20:8080，而不是只有 IP。改完之后重启 docker，再重新 push。如果确认配置没问题，还需要排除磁盘写满的情况，用df -h看 Harbor 的data_volume所在分区，磁盘满时容器的写操作会异常卡顿，表现也是 push 超时。最后还可以用curl -v http://192.168.10.20:8080/v2/从客户端侧探一下 Harbor 的 registry API 是否响应，如果 curl 都卡住，说明是网络链路问题，而不是 docker 配置问题。

6. 备份与后续升级：把 2.8.2 离线包的价值延续到下一次

6.1 备份的关键路径与命令

Harbor 的配置和数据分散在两个地方：一是解压目录里的harbor.yml，二是data_volume指向的整个目录。后者包含数据库、镜像存储、job 日志和密钥，备份时两者一起打包最省事。

tar -czf harbor-backup-$(date +%F).tgz \ -C /opt/harbor harbor.yml \ -C /data/harbor database secretkey # secretkey 丢失后数据库敏感字段无法解密

这条命令把harbor.yml、database目录和secretkey打包到一个带日期的压缩文件里。secretkey是 Harbor 的加密密钥，丢失后虽然镜像还在，但数据库内的敏感字段可能无法解密，必须和数据库一起备份。恢复时，先docker compose down停掉服务，再解压覆盖对应路径，最后重新运行install.sh。注意恢复用的离线包版本要和备份时的版本一致，跨版本恢复必须走升级流程。

6.2 升级前先做一次恢复演练

Harbor 2.8.2 升级到更新版本时，install.sh 会自动检测旧版本数据并做数据库迁移。但迁移是不可逆操作，一旦中间断电或磁盘故障，数据可能直接损坏。所以我自己的习惯是：每次升级前，先把备份恢复到一台临时 arm 机器上，跑起来确认所有容器全绿、能正常登录和拉镜像，再动正式环境。

sudo docker compose ps docker login <临时机器IP>:8080 docker pull <临时机器IP>:8080/library/app:arm64

这三条命令在临时机器上执行通过，备份就视为有效。如果恢复后发现某个容器报数据库连接失败，多半是备份时容器还在写入数据，备份文件不完整；下次备份前先docker compose down，或者用容器内数据库工具做逻辑导出代替目录拷贝。这套流程我在多个 arm 环境私有化部署中反复使用，省下的不止是数据重建的时间，还有半夜被叫起来回滚的折腾。希望帮到你。

本文还有配套的精品资源，点击获取