Harbor v2.13.1 ARM64离线安装包制作与部署避坑指南

简介：面向ARM64架构服务器的Harbor v2.13.1离线安装包，专为在鲲鹏、飞腾等国产化平台及树莓派环境中部署Docker镜像仓库的运维、开发人员准备。由于官方安装包长期以x86架构为主要分发对象，该资源精准补齐ARM设备无法直接使用离线包的短板，适用于Kubernetes集群镜像流转、多云场景下Harbor的快速搭建。压缩包共6个文件，包含负责安装与公共配置的2个shell脚本、承载镜像数据的gz核心包、以及配置模板、许可证和prepare预处理文件，整体679.05MB，覆盖从环境检查到服务启动的关键环节。目前已有526人学习下载，使用者可摆脱联网拉取镜像和手工编译的麻烦，借助内置模板修改主机名、存储目录等参数后，即可完成标准部署。资源还附带用于定制HTTP/HTTPS访问、TLS证书和端口参数的tmpl模板及prepare脚本，既适合快速验证，也可作为中高级运维人员制定ARM生产环境镜像管理方案的参考基线。

1. 为什么生产环境都在找Harbor v2.13.1的ARM64离线安装包：它不是简单的架构替换

在ARM64服务器上装Harbor，第一道坎不是配置，而是找对安装包。Harbor v2.13.1是目前最新的2.x维护版本，但官方release里的离线安装包默认按amd64编译，直接拿到鲲鹏、飞腾这类ARM64机器上，docker load能成功，一启动就报exec format error。真正的ARM64版离线安装包不是换个文件名那么简单，它涉及镜像清单、prepare工具和compose编排三处架构一致性。我会把制作、校验、部署和排雷的完整路径讲清楚，适合正在维护国产化基础设施的运维和容器平台工程师。

2. 为什么ARM64离线包不能直接用官方包：镜像清单与prepare工具的架构陷阱

2.1 官方离线包tgz里到底装了什么：install.sh怎么工作

Harbor v2.13.1的官方离线安装包文件名是harbor-offline-installer-v2.13.1.tgz，解压后是一个harbor目录。里面结构向来稳定：

tar -zxf harbor-offline-installer-v2.13.1.tgz cd harbor && ls -la # common.sh install.sh harbor.yml.tmpl prepare images/harbor.v2.13.1.tar.gz

install.sh是总入口，common.sh放着安装时的公共变量和函数，prepare是编译器产物，用来把harbor.yml转换成docker-compose.yml，最后是images目录下的harbor.v2.13.1.tar.gz，这是所有服务镜像的打包文件。install.sh的执行顺序大致是：加载common.sh、检查docker和docker compose、调用prepare生成配置文件、再用docker load导入镜像包，最后docker compose up -d启动全部容器。

这里有个易忽略的环节：install.sh生成的docker-compose.yml不是现成的，而是prepare根据harbor.yml和自定义存储路径动态渲染出来的。prepare本身需要解析yaml、合并默认值、生成nginx配置和若干子配置文件，因此它对目标主机的架构非常敏感。如果你只替换了images/下的镜像tar没动prepare，在ARM64机器上执行./install.sh会直接在prepare那一步报Exec format error，连镜像都不会加载。很多拿到所谓“ARM64安装包”的用户在这里翻车，回头还以为是镜像打包过程中漏了文件。

common.sh里定义了Harbor安装时的各种路径和参数，但它的重点不是架构，而是把prepare和docker compose的调用串联起来。有人以为把common.sh里的uname判断改了就算支持ARM64，这不够。prepare二进制来自Go编译，Go本身是跨架构的，但官方在release流程里只产出了amd64的Linux编译产物，所以必须单独提供arm64版prepare。这也是自制离线包和官方包唯一的本质差异。

2.2 exec format error背后是什么：docker镜像架构和运行时校验

docker镜像本身是一堆层，每层是文件系统快照，但最上面的config对象记录了这个镜像运行时需要的内核和指令集架构。当你docker pull时，默认拉取当前主机架构对应的变体，除非显式指定--platform。假如你把一份amd64的镜像tar在arm64机器上docker load进去，docker不会拦你，因为load出来的镜像tag可能是一样的。直到你docker compose up，容器运行时去执行第一个进程，CPU发现指令集对不上，内核直接抛exec format error，容器秒退。

docker image inspect --format '{{.Architecture}}' goharbor/harbor-core:v2.13.1 # amd64 或 arm64，取决于你之前pull的是哪个变体

这个Architecture字段是构建镜像时写入的，有时是arm64，有时是aarch64，脚本里判断时要同时接受两种写法。更深一层的问题在于：同一个镜像tag在registry里往往同时存在多个架构的manifest，但docker save导出的只是本地缓存中的那个具体架构。这是很多自制离线包翻车的根源——开发者在一台x86_64机器上docker pull，没有加--platform，拉下来的全是amd64，然后docker save打包，拿到ARM64机器上自然起不来。人眼看镜像tag完全一致，但实际架构完全不同。所以在制作离线包时，拉镜像和导出镜像必须严格控制在同一架构下。

2.3 哪些镜像需要重新按ARM64拉取：goharbor核心、postgres、nginx、redis与trivy

Harbor v2.13.1的服务镜像数量在12到15张左右，具体取决于是否启用trivy和chartmuseum。一个最小集至少包括这些goharbor/前缀的镜像：

• goharbor/harbor-core:v2.13.1
• goharbor/harbor-jobservice:v2.13.1
• goharbor/harbor-registryctl:v2.13.1
• goharbor/harbor-registry:v2.13.1
• goharbor/harbor-portal:v2.13.1
• goharbor/harbor-log:v2.13.1
• goharbor/harbor-db:v2.13.1
• goharbor/nginx-photon:v2.13.1
• goharbor/redis-photon:v2.13.1

以上镜像在Docker Hub和Quay上都有官方arm64构建。harbor-db实际是postgresql的定制版，arm64支持很成熟；nginx-photon是Nginx加基础调试工具，arm64也没问题。真正需要警惕的是基础组件里不带goharbor前缀的那几张：比如redis和postgresql原版镜像，有些历史版本只有amd64，或者多架构发布不全。Harbor v2.13.1官方默认捆绑的是photon-based的定制镜像，通常已经发布arm64，但如果你在制作时手滑用了社区版本的redis镜像，就可能在harbor-log或jobservice启动时碰到exec format error。同样，trivy-adapter镜像本身支持arm64，但它启动后要去联网下漏洞数据库，离线环境要额外处理。

如果要快速判断一个镜像是否支持arm64，用docker manifest inspect看它的platform列表即可：

docker manifest inspect goharbor/harbor-core:v2.13.1 | grep -A6 arm64

如果输出里没有arm64，这张镜像就不能用于ARM64离线包。这个检查在开始制作前就要完成，而不是等打包后才发现缺镜像。

3. 在QEMU模拟环境下制作Harbor v2.13.1 ARM64离线安装包

3.1 用qemu-user-static挂上ARM64执行环境，避免先买一台实机

制作ARM64离线包，最稳妥的办法是直接在一台ARM64机器上在线安装一遍再打包，但很多团队手头没有飞腾、鲲鹏机器。我一般会在x86_64开发机上用qemu用户态模拟，让docker能够拉取正确架构的镜像，同时验证prepare等二进制能不能在模拟环境中跑通。第一步安装和启用：

sudo apt install -y qemu-user-static binfmt-support docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

第一条命令给系统装上qemu对ARM64用户态的支持和binfmt的注册工具。第二条命令通过特权容器把binfmt的解析规则写进内核，系统重启后会失效，需要重新运行。注册完成后可以验证：

docker run --rm --platform linux/arm64 alpine uname -m # aarch64

如果这里输出的不是aarch64，说明binfmt没生效，后续在你启动任何arm64容器时都会遇到“exec format error”。要注意的是，qemu模拟的是用户态指令集，不模拟硬件加速，所以在模拟环境里完整跑Harbor所有容器会慢，但用来做镜像拉取和prepare替换是够用的。

在Ubuntu/Debian上，包名叫qemu-user-static；在CentOS 7上，EPEL源里也有，但版本较旧，有时对ARM64新特性支持不全。更省心的做法是直接从多架构镜像项目里下载独立的qemu-aarch64-static二进制，放到/usr/bin/后手动注册binfmt。我用过的麒麟V10同样适用这个思路，因为系统自带源里的qemu可能不完整。注册binfmt的命令格式是：

echo ':aarch64:M::\x7fELF\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\xa3\x00:\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff\xff:/usr/bin/qemu-aarch64-static:' > /proc/sys/fs/binfmt_misc/register

这段内容看着像黑匣子，但它解决的问题是：让Linux内核能识别ARM64的ELF文件并交给qemu解释执行。x86_64主机上如果不注册，docker pull之后容器内一启动就会Exec format error，和ARM64机器上遇到的现象一模一样。

3.2 按官方镜像清单拉取linux/arm64镜像并重新打包harbor.v2.13.1.tar.gz

准备好arm64执行环境后，第二步是按镜像清单拉取。我先建一个image-list.txt，把2.3节里列出的镜像tag写进去，然后循环拉取：

cat > image-list.txt <<EOF goharbor/harbor-core:v2.13.1 goharbor/harbor-jobservice:v2.13.1 goharbor/harbor-registryctl:v2.13.1 goharbor/harbor-registry:v2.13.1 goharbor/harbor-portal:v2.13.1 goharbor/harbor-log:v2.13.1 goharbor/harbor-db:v2.13.1 goharbor/nginx-photon:v2.13.1 goharbor/redis-photon:v2.13.1 EOF while read -r img; do docker pull --platform linux/arm64 "$img" done < image-list.txt

注意--platform linux/arm64必须要加。因为docker在x86_64主机上默认还是会拉amd64变体，即使本机装了qemu，pull阶段仍然遵循Docker Hub的manifest选择逻辑。只有显式指定platform，docker拉下来的镜像的Architecture字段才是arm64。如果某个镜像只有amd64变体，pull时会报“no matching manifest for linux/arm64”，这就是早期预警，需要换版本或者自行构建。

拉完后，把本机所有goharbor镜像导出成一个tar文件，替换离线包里的harbor.v2.13.1.tar.gz：

docker save $(docker images --format '{{.Repository}}:{{.Tag}}' | grep '^goharbor/' | sort -u) -o harbor.v2.13.1.tar.gz cp harbor.v2.13.1.tar.gz ../harbor/images/harbor.v2.13.1.tar.gz

这里有个坑：docker save如果镜像在本地存在多个架构变体，会把所有架构的层都导出到tar里，导致包体积变大，而且load到目标机上并不会自动过滤，可能又出现架构混用。更好的做法是先把本机不需要的镜像tag清理掉，确保只保留arm64变体。实际操作中我会先执行docker image ls确认每一张镜像的架构，再save。

3.3 用arm64版prepare替换install.sh依赖，并修正common.sh里的架构判断

镜像tar换好后，prepare是下一个必须处理的对象。官方离线包里的prepare在解压目录根下，是amd64的ELF。在qemu环境下可以继续从goharbor/prepare镜像中把arm64版提取出来：

docker pull --platform linux/arm64 goharbor/prepare:v2.13.1 docker create --name prepare-tmp goharbor/prepare:v2.13.1 docker cp prepare-tmp:/harbor/prepare ./prepare docker rm prepare-tmp chmod +x ./prepare

goharbor/prepare镜像的入口是prepare程序，它在镜像里的路径一般是/harbor/prepare。如果你的tag不是v2.13.1，或者镜像内部路径有变化，可以先进入容器找一下：

docker run --rm --entrypoint sh goharbor/prepare:v2.13.1 -c "which prepare; ls -l /harbor"

把提取出来的./prepare覆盖到离线包目录下。然后打开common.sh，搜索uname -m或uname。有的版本里有针对x86_64的架构判断，例如：

case "$(uname -m)" in x86_64|amd64) ...

如果遇到ARM64机器上被拒绝的情况，把对应分支改成同时接受aarch64和arm64。common.sh里的其他变量一般不用改，因为prepare生成docker-compose时使用的是相对路径和harbor.yml里的配置。这个替换动作做完后，install.sh才能像在x86_64上一样顺畅走完。

3.4 校验产物：docker manifest inspect与tar包内的镜像一一对应

打包完成别急着交付，先在制作机上做一轮完整校验。第一步，对每一张镜像执行manifest验证：

while read -r img; do echo "== $img ==" docker manifest inspect "$img" | jq -r '.manifests[] | .platform.architecture' | sort | uniq done < image-list.txt

检查输出里是否有arm64。如果某张镜像只有amd64，这一项就会缺失。第二步，解压新生成的harbor.v2.13.1.tar.gz，看看manifest.json里记录的RepoTags和归档内的层引用是否齐全：

tar -xOf harbor.v2.13.1.tar.gz manifest.json | jq '.[].RepoTags'

这个输出应该和image-list.txt里的tag一致。第三步，如果条件允许，把整个离线包拷贝到一台临时ARM64机器上，执行./install.sh --with-trivy --with-chartmuseum，然后docker compose ps看所有服务是否正常。这个“真机冒烟测试”比任何静态校验都可靠，我每次交付前都至少做一遍。

4. 把自制ARM64离线包部署到目标机：从harbor.yml到install.sh参数

4.1 解压后配置harbor.yml的hostname、端口和存储路径

拿到做好的离线包，在目标ARM64服务器上先解压：

tar -zxf harbor-offline-installer-v2.13.1-arm64.tgz cd harbor cp harbor.yml.tmpl harbor.yml vi harbor.yml

harbor.yml是安装的唯一入口。最少要改四个位置。hostname填实际访问域名或IP，不能是localhost，否则Harbor的页面登录会403。http部分是监听端口，默认80，如果和系统Nginx或已有Web服务冲突，改成8080。如果不用https，把https段整个注释掉，因为prepare读取到certificate和private_key路径的文件不存在时会直接退出。harbor_admin_password设置初始化管理员密码，必须至少8位且带大小写和数字。database的password是给Postgres用的，建议也改掉，避免弱密码风险。最后是data_volume，这个目录存放registry数据、数据库和证书，必须单独挂载到大分区。

一个常见误区是只改hostname，其他都用模板默认值。这样在纯离线环境里确实能装起来，但后续要配https，再回头看harbor.yml时容易漏改。我习惯把所有涉及安全的口令都明确写上，哪怕保持默认也在文件里留下痕迹，方便交接。整段配置参考：

hostname: registry.internal.example.com http: port: 80 https: port: 443 certificate: /data/harbor/cert/server.crt private_key: /data/harbor/cert/server.key harbor_admin_password: "N8sT@rm64#2025" database: password: "D8b@rm64#2025" max_idle_conns: 50 max_open_conns: 100 data_volume: /data/harbor

注意这里的https端口和证书路径要真实存在，否则install.sh的prepare阶段会报证书文件缺失。如果只是测试，建议先把https段整个注释掉，用http跑通再说。

4.2 install.sh常用参数：--with-trivy、--with-chartmuseum以及证书模式下必开的选项

执行安装：

sudo ./install.sh --with-trivy --with-chartmuseum

install.sh支持的常见参数如下表。注意参数只在首次安装时有效，后续配置变更都要重新执行prepare再compose up。

如果你在离线包制作时没有启用某组件，那install.sh就不要带对应参数。比如image-list.txt里没拉trivy-adapter，执行--with-trivy时Harbor会因找不到镜像而报错。在纯离线环境，--with-trivy还会带来一个额外的坑：trivy启动后需要下载漏洞数据库，因此你需要在离线包中额外准备goharbor/trivy-db，或者调整trivy的离线扫描配置。这部分没有绝对通用做法，我通常是先不加trivy部署，等后面有外网条件再补。同样，--with-chartmuseum只在你想要一个Helm Chart仓库时才需要，不是默认功能。

4.3 部署后健康检查：docker compose ps、curl /api/v2.0/ping

install.sh结束后，先看服务状态：

docker compose ps

所有服务应该处于Up，harbor-db和redis的health列是(healthy)。如果某个服务显示Restarting，马上看日志：

docker logs --tail 50 harbor-core docker logs --tail 50 harbor-db

再调用API做基本验证：

curl -k -u admin:YourPassword https://127.0.0.1/api/v2.0/ping

返回PONG表示core服务正常。最后创建项目，docker login到Harbor，push一个测试镜像，再pull回来形成闭环。注意docker客户端如果报x509证书错误，需要把Harbor的ca.crt添加到/etc/docker/certs.d/<harbor域名>/目录下，或者在daemon.json配置insecure-registries。在国产化操作系统上，这个证书信任动作经常被忽略，导致能登录但推送失败，日志提示“http: server gave HTTP response to HTTPS client”，实际上是因为harbor.yml里配置了https而客户端走http，需要检查harbor.yml中的http和https配置，还要检查容器内的nginx端口映射。

5. 避坑与排查：ARM64离线包部署最容易踩的5个坑

5.1 docker load成功但容器崩溃，日志说exec format error

现象：docker compose up后，harbor-core容器秒退，docker logs显示standard_init_linux.go:228: exec user process caused: exec format error。原因：镜像tar里的架构仍然是amd64，docker load时没有做任何拦截，它只是把层解开，并不检查是否能在本机运行。解决：检查制作流程里是否真的指定了--platform linux/arm64，用docker image inspect逐一核对。如果只有少数服务报错，可以单独拉取arm64变体再替换tar，不需要全部重来。这个坑在所有跨架构离线包里排第一，因为很多人从网上下载一个“ARM64离线包”，其实源头机器是x86_64，docker save导出的镜像仍然是amd64。

5.2 prepare执行时Exec format error，导致install.sh进行到一半就停

现象：执行./install.sh，屏幕显示prepare: Exec format error，但前面的脚本检查都正常。原因：官方离线包内置的prepare是x86_64二进制，ARM64内核无法执行。解决：使用3.3节的方法从goharbor/prepare镜像里提取arm64版本并替换。可以在制作离线包前先把这一步做掉，也可以在目标机上临时用docker run方式单独执行prepare，再接手工docker compose up，后者适合着急上线的场景。如果不想动包里二进制，也可以改install.sh，把./prepare那行替换成docker run --rm -v "$PWD":/harbor goharbor/prepare:v2.13.1 prepare，但这样依赖网络，离线环境不推荐。

5.3 harbor-db起来了，但harbor-core连不上数据库，日志反复报password authentication failed

现象：harbor-core容器日志出现connection refused或password authentication failed，但harbor-db容器状态是healthy。原因：harbor.yml中的database.password与数据库初始化时使用的密码不一致，或者数据库镜像初始化时已经用了旧密码，数据卷是旧的。解决：如果数据卷里的postgresql数据已经存在，初始化脚本不会重复执行，改密码也不会生效。要么删除data_volume下的database子目录重新初始化，要么在harbor.yml中保持原密码。这是Harbor一个老问题，和ARM64无关，但在离线包上更容易踩，因为很多人是从amd64机器复制数据卷过来的。删除数据卷的代价是丢失全部镜像数据，操作前务必备份data_volume。

5.4 Trivy扫描报无法初始化漏洞数据库，不是架构问题

现象：镜像能push，但点击漏洞扫描后任务失败，日志提示failed to download the vulnerability database。原因：trivy-adapter启动后会去GitHub或官方镜像源下载trivy-db，离线环境没有外网，或者防火墙只允许走代理。解决：在在线环境提前docker pull aquasec/trivy-db，再手动导入到Harbor所在节点的docker镜像缓存，并修改harbor.yml中trivy相关的offline_scan为true。也可以更彻底地把trivy-db镜像传给用户，在离线包中额外附带。要注意trivy-db也有arm64变体，别又拉成amd64。这个坑跟ARM64没有强关联，但很多人在前几步折腾完架构问题后，会异想天开地怀疑是ARM64导致的，实际上trivy镜像本身是有arm64的。

5.5 install.sh提示docker compose版本不满足，但docker-compose命令能执行

现象：脚本检查到docker compose不存在或版本低于2.0，但docker-compose（带横线）能正常工作。原因：Harbor install.sh判断的是docker compose v2插件，不是旧版python实现的docker-compose。现在的发行版默认装的是docker-compose v1，或者只有v2插件但没链接到PATH。解决：安装插件版，sudo apt install docker-compose-plugin，或从docker官方二进制包拷贝到/usr/local/lib/docker/cli-plugins/docker-compose并加执行权限。ARM64的国产化系统有些源里没有这个包，需要从docker官方下载arm64编译好的二进制，注意别下成amd64的。验证命令是docker compose version，而不是docker-compose version。这个坑和架构无关，但如果你用官方离线包在ARM64上栽在这一步，会特别泄气，因为前面明明是架构问题，到这里又变成了工具链问题。

6. 进阶：用docker manifest自动校验镜像架构，并固化自制离线包的脚本

上面几条坑如果能挨着趟过去，离线包基本能用了。我再分享一个自己常用的校验脚本，它在每次打包前后跑一遍，目的只有一个：确保images/目录下的tar里每个镜像的架构都是arm64。

#!/usr/bin/env bash set -euo pipefail image_list=$(docker images --format '{{.Repository}}:{{.Tag}}' | grep '^goharbor/' | sort) for img in $image_list; do arch=$(docker image inspect --format '{{.Architecture}}' "$img") if [ "$arch" != "arm64" ]; then echo "[FAIL] $img is $arch, not arm64" exit 1 fi done echo "all matched arm64"

这段脚本的逻辑很直白：docker image inspect输出的Architecture就是镜像配置里的原始架构，arm64或者aarch64都可能出现，视构建工具而定。如果脚本发现任何一个镜像不是arm64，就立刻退出。实际使用中我会把它放在一个build-offline.sh里，让它紧接着docker pull和docker save之后执行。注意这里的镜像范围限定在goharbor/下，如果你在离线包里额外加了redis等非goharbor镜像，要把正则再扩大。

如果想要更强的校验，可以进一步比对docker-compose.yml里用到的镜像tag是否都出现在tar中。做法是：

compose_refs=$(grep -E 'image:' docker-compose.yml | awk '{print $2}' | sort -u) tar_refs=$(tar -xOf harbor.v2.13.1.tar.gz manifest.json | jq -r '.[].RepoTags[]' | sort -u) comm -23 <(echo "$compose_refs") <(echo "$tar_refs")

如果输出有内容，说明compose里引用了tar里没有的镜像tag，启动时必然报image not found。这个步骤在手工制作时容易漏掉，因为在拉镜像时少拉一个很简单，而docker compose up只会在用到时才发现。

我自己的习惯是：离线包在进生产前，一定在隔离环境里完整跑一遍install.sh加push/pull验证，再封装成交付物。虽然多花十分钟，但它能把这些架构陷阱、依赖缺失的后悔药提前吃完。记住一条：ARM64离线包的难点不在“包”，而在包里的镜像、prepare和compose配置三者是不是同一架构。希望这套制作和排查路径能帮你在国产化服务器上把Harbor顺利跑起来，少踩几个坑。

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