简介：本资源为 Harbor v2.4.0 的 arm 架构离线安装包，面向需要在国产化或 ARM 服务器环境中快速部署私有镜像仓库的运维与开发人员。包内共 6 个文件，以 sh 安装脚本、gz 镜像归档、yml 配置模板及 license 授权文件为主，压缩包整体约 402MB，覆盖从环境准备到服务启动的完整离线依赖。使用前需预先安装 docker 与 docker-compose，随后执行 install.sh 即可一键完成 Harbor 部署，省去在线拉取镜像的繁琐步骤。目前已有 1574 人学习下载，适合希望规避网络限制、快速搭建企业级镜像仓库的读者参考，可帮助理解离线安装流程、配置文件组织方式及组件依赖关系，为后续仓库运维与版本升级提供可复用的实践基础。
1. harbor-v2.4.0离线安装（arm架构）：内网环境下的镜像仓库落地
很多团队的内网环境压根连不了外网，但 CI/CD 流水线又必须有个靠谱的镜像仓库来存 Docker 镜像。harbor-v2.4.0 离线安装（arm架构）这件事，说白了就是在没有互联网的 ARM 服务器上，把 Harbor 这个企业级镜像仓库完整跑起来。ARM 架构的服务器这两年越来越多，鲲鹏、飞腾这些国产 CPU 基本都是 aarch64，但 Harbor 官方给的离线包默认是 x86_64 的，直接拿过来用会翻车。我见过太多人在这一步卡住，要么是镜像架构不对导致容器起不来，要么是 docker-compose 里的镜像拉不到。这篇文章就是把我自己在 ARM 服务器上离线部署 Harbor 2.4.0 的完整路径拆开，从离线包准备、架构适配、配置修改到启动验证，每一步都给出可复现的命令和参数。适合手里有 ARM 服务器、需要在内网搭镜像仓库的运维和 DevOps 同学。
2. 离线包准备与 ARM 架构适配：从哪拿到能用的安装包
2.1 为什么不能直接用官方 x86 离线包
Harbor 官方发布的离线安装包（offline installer）里打包了所有需要的 Docker 镜像，这些镜像的 manifest 是绑定 CPU 架构的。你从 GitHub Releases 页面下载的harbor-offline-installer-v2.4.0.tgz，里面的镜像全是linux/amd64的。放到 ARM 服务器上执行docker load虽然能导入，但docker run的时候会直接报exec format error，因为内核加载不了 x86 的二进制。这个报错很直接，但第一次遇到的人容易懵——明明镜像 load 成功了，怎么一启动就挂。
常见做法是两条路：一是找社区已经构建好的 ARM 版离线包，二是自己在能联网的 ARM 机器上把镜像重新构建或拉取 ARM 版本，再打包成离线包。我一般会走第二条路，因为社区包版本参差不齐，而且 harbor-v2.4.0 这个版本对应的组件版本必须严格匹配，否则数据库迁移会出问题。
2.2 在联网 ARM 机器上拉取并导出镜像
先找一台能上外网的 ARM 服务器（aarch64），装好 Docker 和 docker-compose。然后按照 Harbor 2.4.0 的docker-compose.yml里定义的镜像列表，逐个拉取 ARM 版本。Harbor 2.4.0 用到的核心镜像包括：goharbor/harbor-core:v2.4.0、goharbor/harbor-portal:v2.4.0、goharbor/harbor-jobservice:v2.4.0、goharbor/harbor-registryctl:v2.4.0、goharbor/registry-photon:v2.4.0、goharbor/redis-photon:v2.4.0、goharbor/harbor-db:v2.4.0、goharbor/nginx-photon:v2.4.0、goharbor/harbor-log:v2.4.0、goharbor/harbor-exporter:v2.4.0、goharbor/trivy-adapter-photon:v2.4.0、goharbor/notary-server-photon:v2.4.0、goharbor/notary-signer-photon:v2.4.0。这些镜像在 Docker Hub 上都有多架构 manifest，直接docker pull就会自动拉取 aarch64 版本。
# 在联网的 ARM 服务器上执行 # 定义镜像列表，对应 Harbor 2.4.0 的组件 IMAGES=( "goharbor/harbor-core:v2.4.0" "goharbor/harbor-portal:v2.4.0" "goharbor/harbor-jobservice:v2.4.0" "goharbor/harbor-registryctl:v2.4.0" "goharbor/registry-photon:v2.4.0" "goharbor/redis-photon:v2.4.0" "goharbor/harbor-db:v2.4.0" "goharbor/nginx-photon:v2.4.0" "goharbor/harbor-log:v2.4.0" "goharbor/harbor-exporter:v2.4.0" "goharbor/trivy-adapter-photon:v2.4.0" "goharbor/notary-server-photon:v2.4.0" "goharbor/notary-signer-photon:v2.4.0" ) # 逐个拉取 for img in "${IMAGES[@]}"; do docker pull "$img" done # 导出为 tar 包，方便拷贝到离线环境 docker save -o harbor-arm64-images.tar "${IMAGES[@]}"这段脚本的逻辑很直白：先定义好 Harbor 2.4.0 所有组件的镜像地址，然后循环拉取。docker pull在 ARM 机器上会自动选择linux/arm64的 manifest，不需要手动指定--platform。最后用docker save把所有镜像打包成一个 tar 文件。参数说明：-o指定输出文件名，后面跟镜像列表。导出的 tar 包大小大概在 2GB 左右，取决于具体版本。注意docker save后面跟的是镜像名加 tag，不能只写镜像名。
2.3 离线包目录结构整理
除了镜像 tar 包，还需要 Harbor 的安装脚本和配置文件。从官方离线包harbor-offline-installer-v2.4.0.tgz里解压出来的harbor目录，里面包含install.sh、harbor.yml.tmpl、prepare、common.sh等脚本。这些脚本本身是 shell 和 Python，不依赖架构，可以直接用。但要注意，官方离线包里的harbor/images目录下是 x86 的 tar 包，需要替换成我们自己导出的 ARM 版 tar 包。
# 在联网机器上准备目录结构 mkdir -p /opt/harbor-offline-arm64 cd /opt/harbor-offline-arm64 # 解压官方离线包（只取脚本和配置模板） tar -xzf harbor-offline-installer-v2.4.0.tgz # 此时会得到 harbor/ 目录 # 删除官方自带的 x86 镜像 tar 包 rm -f harbor/harbor.v2.4.0.tar.gz # 把之前导出的 ARM 镜像 tar 包放进去 mv /path/to/harbor-arm64-images.tar harbor/ # 最终目录结构： # harbor/ # ├── harbor.yml.tmpl # ├── install.sh # ├── prepare # ├── common.sh # └── harbor-arm64-images.tar这里的关键操作是替换镜像包。官方离线包里的harbor.v2.4.0.tar.gz是 x86 的，必须删掉，换成 ARM 版。install.sh脚本在执行时会调用docker load加载harbor/目录下的 tar 包，所以文件名可以自定义，只要在install.sh里对应修改就行。我一般不改脚本，直接把文件名改成脚本里写死的那个，省得动逻辑。
3. 配置文件修改与安装脚本执行：让 Harbor 在 ARM 上跑起来
3.1 harbor.yml 的关键参数设置
Harbor 2.4.0 的配置文件模板是harbor.yml.tmpl，需要复制成harbor.yml再修改。这个文件里几个参数必须改对，否则安装过程会报错或者装完了访问不了。
# harbor.yml 关键配置项 hostname: 192.168.209.133 # 改成你的 ARM 服务器 IP 或域名 http: port: 80 # HTTP 端口，如果 80 被占用改成其他端口 # https 配置，离线内网环境一般先用 HTTP，注释掉 HTTPS 部分 # https: # port: 443 # certificate: /your/certificate/path # private_key: /your/private/key/path harbor_admin_password: Harbor12345 # 管理员初始密码，生产环境务必改掉 database: password: root123 # 数据库密码 max_idle_conns: 50 max_open_conns: 100 data_volume: /data # 数据存储目录，确保磁盘空间足够 trivy: ignore_unfixed: false skip_update: true # 离线环境必须设为 true，否则会尝试联网更新漏洞库 offline_scan: true # 离线扫描模式 jobservice: max_job_workers: 10 notification: webhook_job_max_retry: 10 log: level: info local: rotate_count: 50 rotate_size: 200M location: /var/log/harbor重点说几个参数。hostname必须改成实际 IP，否则 Docker 客户端推送镜像时会报dial tcp 192.168.209.133:443: connect: connection refused这类错误，因为 Harbor 生成的证书和访问地址不匹配。data_volume指定数据盘路径，默认是/data，如果服务器上/data分区空间不够，改成大容量分区。trivy.skip_update在离线环境必须设为true，不然 Trivy 适配器启动时会卡在更新漏洞库那一步，导致整个 Harbor 起不来。trivy.offline_scan也建议开启，避免扫描时尝试联网。
3.2 执行 install.sh 的完整流程
配置文件改好后，就可以执行安装脚本了。install.sh做的事情包括：加载镜像、生成配置、启动 docker-compose 集群。整个过程大概需要几分钟，取决于磁盘 IO 速度。
# 进入 harbor 目录 cd /opt/harbor-offline-arm64/harbor # 复制配置文件 cp harbor.yml.tmpl harbor.yml # 然后用 vi 或 sed 修改 harbor.yml 里的参数 # 执行安装 ./install.sh # 安装脚本会输出类似以下内容： # [Step 0]: checking if docker is installed ... # [Step 1]: checking docker-compose is installed ... # [Step 2]: loading Harbor images ... # Loaded image: goharbor/harbor-core:v2.4.0 # ... # [Step 3]: preparing environment ... # [Step 4]: preparing harbor configs ... # [Step 5]: starting Harbor ... # Creating network "harbor_harbor" with the default driver # Creating harbor-log ... done # Creating harbor-db ... done # Creating redis ... done # Creating registry ... done # Creating harbor-core ... done # Creating harbor-portal ... done # Creating nginx ... done # Creating harbor-jobservice ... done # Creating harbor-exporter ... done # Creating trivy-adapter ... done # Creating notary-server ... done # Creating notary-signer ... done # ✔ ----Harbor has been installed and started successfully.----如果看到最后那行Harbor has been installed and started successfully，说明安装成功了。但别急着高兴，ARM 环境下有几个地方容易出问题。比如install.sh在加载镜像时，如果 tar 包里的镜像架构不对，会报no matching manifest for linux/arm64/v8 in the manifest list entries。这时候要检查docker load是否真的加载了 ARM 镜像，可以用docker inspect看镜像的Architecture字段。
3.3 验证 Harbor 服务状态
安装完成后，用docker-compose ps查看容器状态。所有容器都应该是Up状态，特别是harbor-core、harbor-db、nginx这几个核心组件。
# 查看容器状态 cd /opt/harbor-offline-arm64/harbor docker-compose ps # 预期输出： # Name Command State Ports # --------------------------------------------------------------------------------------------- # harbor-core /harbor/entrypoint.sh Up (healthy) 8080/tcp # harbor-db /docker-entrypoint.sh Up (healthy) 5432/tcp # harbor-exporter /harbor/entrypoint.sh Up 8080/tcp # harbor-jobservice /harbor/entrypoint.sh Up 8080/tcp # harbor-log /bin/sh -c /usr/local/bin/ ... Up 127.0.0.1:1514->10514/tcp # harbor-portal nginx -g daemon off; Up (healthy) 8080/tcp # nginx nginx -g daemon off; Up 0.0.0.0:80->8080/tcp # notary-server /bin/sh -c /entrypoint.sh Up 4443/tcp # notary-signer /bin/sh -c /entrypoint.sh Up 7899/tcp # redis docker-entrypoint.sh redis ... Up 6379/tcp # registry /home/harbor/entrypoint.sh Up (healthy) 5000/tcp # trivy-adapter /home/scanner/entrypoint.sh Up 8080/tcp如果某个容器状态是Restarting或者Exit，用docker-compose logs <服务名>看日志。常见问题：harbor-db起不来可能是数据目录权限不对，harbor-core起不来可能是数据库连接失败。ARM 环境下还要注意，某些镜像的 entrypoint 脚本里可能有硬编码的 x86 路径，但 Harbor 2.4.0 的官方 ARM 镜像已经处理好了，一般不会遇到。
4. 避坑与常见问题排查：ARM 离线安装的血泪经验
4.1 镜像架构不匹配导致容器反复重启
现象：docker-compose ps显示harbor-core或harbor-portal状态为Restarting，日志里报exec /harbor/entrypoint.sh: exec format error。
原因：加载的镜像还是 x86 架构的。虽然docker load成功了，但内核无法执行 x86 二进制。这种情况通常是因为在联网机器上docker pull时没有指定正确的平台，或者 Docker 版本太老不支持多架构 manifest 自动选择。
解决：在联网 ARM 机器上执行docker pull时显式指定--platform linux/arm64，然后重新docker save导出。导入离线环境后，用docker inspect <镜像名> | grep Architecture确认输出是arm64。如果还是 amd64，说明拉取源有问题，检查 Docker 的daemon.json里是否配置了experimental或者镜像加速地址。
4.2 Trivy 适配器启动卡住导致 Harbor 无法访问
现象：install.sh执行到最后一步卡住，或者trivy-adapter容器一直处于Restarting状态，Harbor Web 界面打不开。
原因：Trivy 默认会尝试联网更新漏洞数据库，离线环境下这个请求会超时，导致适配器启动失败。Harbor 2.4.0 的harbor.yml里如果没有正确配置trivy.skip_update和trivy.offline_scan，就会踩这个坑。
解决：修改harbor.yml，确保trivy.skip_update: true和trivy.offline_scan: true。如果已经安装过了，先docker-compose down停掉所有容器，改完配置再./install.sh重新安装。注意docker-compose down不会删除数据卷，所以之前推送的镜像还在。
4.3 推送镜像时报 dial tcp 连接拒绝
现象：在 Docker 客户端执行docker push 192.168.209.133/library/nginx:latest时，报Get "https://192.168.209.133/v2/": dial tcp 192.168.209.133:443: connect: connection refused。
原因：Docker 客户端默认走 HTTPS 推送，但 Harbor 配置的是 HTTP（80 端口）。或者harbor.yml里的hostname写的是域名，但客户端用 IP 访问，导致证书不匹配。
解决：在 Docker 客户端的daemon.json里添加insecure-registries配置，把 Harbor 的地址加进去。然后重启 Docker 服务。如果 Harbor 配了 HTTPS 但用的是自签名证书，还需要把 CA 证书放到客户端的/etc/docker/certs.d/192.168.209.133/目录下。
{ "insecure-registries": ["192.168.209.133"] }改完daemon.json后执行systemctl restart docker。注意这个操作会重启所有容器，生产环境要谨慎。另外，insecure-registries只对 HTTP 或者自签名 HTTPS 有效，如果 Harbor 配了正规证书，就不需要这个配置。
4.4 数据目录权限问题导致数据库启动失败
现象：harbor-db容器状态为Exit，日志里报FATAL: data directory "/var/lib/postgresql/data" has wrong ownership。
原因：Harbor 的数据库容器以非 root 用户运行，但data_volume指定的宿主机目录权限是 root 所有，容器内用户没有写权限。
解决：修改data_volume目录的权限，确保 UID 为 999 的用户（PostgreSQL 容器内的用户）有读写权限。执行chown -R 999:999 /data/database。如果用的是 NFS 挂载，还需要检查 NFS 的no_root_squash配置。ARM 服务器上如果用了国产操作系统，SELinux 可能会拦截，需要临时设为 permissive 模式排查。
4.5 离线环境时间不同步导致证书校验失败
现象：Harbor 安装成功，但 Web 界面登录时报token verification failed或者推送镜像时证书校验失败。
原因：ARM 服务器长时间离线运行，系统时间漂移严重，导致 JWT token 或者 TLS 证书的有效期校验不通过。
解决：在内网搭建 NTP 服务器，或者手动同步时间。执行date -s "2025-01-01 12:00:00"临时设置，然后配置chronyd或ntpd指向内网时间源。Harbor 的 token 默认有效期是 30 分钟，时间偏差超过这个值就会出问题。
5. 进阶技巧：离线环境下的镜像同步与版本升级
5.1 用 Harbor 的复制功能做离线镜像同步
Harbor 2.4.0 自带镜像复制（replication）功能，可以在两个 Harbor 实例之间同步镜像。在内网离线环境下，这个功能可以用来做多级镜像仓库的同步。比如总部有一个 Harbor，分部有一个 Harbor，分部通过离线介质把镜像包带过去，导入后通过复制策略同步到本地。配置路径是：系统管理 -> 仓库管理 -> 新建目标，填上对端 Harbor 的地址和认证信息。然后创建复制规则，选择项目或者仓库，设置触发模式为手动或定时。
这个功能在 ARM 环境下同样可用，但要注意两端 Harbor 的版本最好一致，否则 API 兼容性可能有问题。如果版本不一致，复制任务会报unsupported media type或者manifest invalid。我一般会在复制规则里加上过滤条件，只同步特定 tag 的镜像，避免把测试镜像也同步过去。
5.2 从 2.4.0 升级到更高版本的注意事项
Harbor 的版本升级不能跨大版本，必须逐级升。比如从 2.4.0 升到 2.5.0，再升到 2.6.0。ARM 环境下升级的难点在于，新版本的离线包同样需要 ARM 架构的镜像。升级步骤：先备份数据库和配置文件，然后下载新版本的 ARM 离线包，替换harbor.yml里的镜像 tag，执行./install.sh。升级过程中数据库会自动迁移，但如果迁移失败，回滚会很麻烦。
提示：升级前务必备份
/data/database和harbor.yml，这两个是恢复的关键。数据库备份可以用docker exec harbor-db pg_dump -U postgres registry > registry.sql。
5.3 验证 Harbor 是否真正可用的三个命令
装完之后怎么确认 Harbor 真的能用？我一般跑三个命令。第一个是curl -I http://192.168.209.133/api/v2.0/health，返回 200 说明 API 正常。第二个是docker login 192.168.209.133 -u admin -p Harbor12345，登录成功说明认证没问题。第三个是docker tag nginx:latest 192.168.209.133/library/nginx:latest && docker push 192.168.209.133/library/nginx:latest，推送成功说明存储和 registry 都正常。这三个命令覆盖了 Harbor 的核心链路，任何一个失败都能快速定位问题。
# 健康检查 curl -s -o /dev/null -w "%{http_code}" http://192.168.209.133/api/v2.0/health # 预期输出：200 # 登录测试 docker login 192.168.209.133 -u admin -p Harbor12345 # 预期输出：Login Succeeded # 推送测试 docker pull nginx:latest docker tag nginx:latest 192.168.209.133/library/nginx:latest docker push 192.168.209.133/library/nginx:latest # 预期输出：The push refers to repository [192.168.209.133/library/nginx] # ... # latest: digest: sha256:... size: ...这三个命令跑通，基本可以确定 Harbor 在 ARM 离线环境下已经稳定运行了。后面就是把它接入 CI/CD 流水线，配置项目权限和机器人账号。我自己的习惯是，每次部署完新环境，先把这三个命令存成一个verify.sh脚本，下次升级或者迁移的时候直接跑一遍，省得手动敲。希望帮到你。
本文还有配套的精品资源，点击获取
