简介面向需要在国产化或 ARM 服务器上私有化部署容器镜像仓库的运维与开发人员这份资源提供 harbor-v2.9.0 的 arm64 架构离线安装包解决内网环境无法拉取镜像、x86 包无法在 ARM 平台运行的问题。压缩包共 6 个文件约 722.35MB包含离线镜像归档、安装脚本、配置模板与许可证等其中 sh 脚本负责一键执行安装gz 归档承载核心镜像数据tmpl 模板用于生成 harbor 配置整体结构清晰、开箱即用。使用前需自行准备 docker 与 docker-compose 环境执行 install.sh 即可完成部署。目前已有 962 人学习下载适合希望快速搭建 ARM 版 Harbor 私有仓库、减少手工配置与排错成本的读者参考使用。1. Harbor v2.9.0 离线安装arm架构内网环境下的镜像仓库落地在信创服务器上装 Harbor最让人头疼的不是配置而是机器根本连不上外网。尤其是 arm 架构的 openEuler 或麒麟系统官方文档默认你在线拉镜像但实际交付现场往往只有一块 U 盘和一条内网链路。Harbor v2.9.0 的离线安装包正是为这种场景准备的——它把核心镜像、Docker Compose 模板、安装脚本全部打包让你在无外网环境下也能把私有镜像仓库跑起来。这篇文章面向需要在 arm64 服务器上落地 Harbor 的运维和平台工程师从离线包结构拆到 docker-compose 参数调优再到 arm 架构特有的坑全部按可复现的步骤写清楚。如果你手里正好有一台 arm 服务器和一块移动硬盘跟着走就能装完。2. 离线包拆解与 arm 架构适配性检查2.1 离线包里到底有什么Harbor 官方发布的离线安装包命名格式通常是harbor-offline-installer-v2.9.0.tgz解压后核心目录结构如下harbor/ ├── harbor.v2.9.0.tar.gz # 所有组件镜像的离线包 ├── harbor.yml.tmpl # 配置文件模板 ├── install.sh # 安装脚本 ├── prepare # 环境预检脚本 └── common.sh # 公共函数库其中harbor.v2.9.0.tar.gz是重头戏里面包含了 registry、portal、core、jobservice、db、redis、nginx 等组件的镜像。在线安装时这些镜像从 Docker Hub 拉取离线安装时通过docker load一次性导入。注意arm 架构的离线包和 x86 的包不能混用——镜像的 manifest 架构不匹配docker load虽然能成功但docker run时会直接报exec format error。2.2 确认服务器架构与系统版本在动手之前先确认目标机器的 CPU 架构和操作系统。这一步看起来简单但 arm 服务器上不同发行版的 Docker 安装方式差异很大。# 确认 CPU 架构输出应为 aarch64 或 arm64 uname -m # 确认操作系统发行版和版本号 cat /etc/os-release # 确认内核版本Harbor v2.9.0 要求内核不低于 4.15 uname -r # 确认 Docker 是否已安装及版本 docker version --format {{.Server.Version}} # 确认 Docker Compose 版本v2.9.0 要求不低于 1.18.0 docker compose versionuname -m输出aarch64说明是 64 位 arm 架构这是 Harbor 离线包支持的目标平台。如果输出armv7l那是 32 位 armHarbor 官方不提供对应离线包需要自行编译所有组件镜像工作量极大不建议走这条路。/etc/os-release里的ID和VERSION_ID决定了后续 Docker 的安装方式——openEuler 和麒麟系统通常自带 docker 或 containerd 包但版本可能偏旧。2.3 Docker 与 Docker Compose 的离线就位Harbor v2.9.0 依赖 Docker Engine 和 Docker Compose。如果目标机器上还没有 Docker需要提前准备 arm64 版本的离线安装包。常见做法是从有网的 arm 机器上用yumdownloader或apt-get download把依赖包全部下载下来再拷贝到目标机器安装。# 在有网的 arm 机器上下载 Docker 及其依赖以 openEuler 为例 mkdir -p /tmp/docker-offline cd /tmp/docker-offline yumdownloader --resolve --destdir/tmp/docker-offline docker-ce docker-ce-cli containerd.io docker-compose-plugin # 打包拷贝到目标机器后执行本地安装 rpm -ivh *.rpm --nodeps --force # 启动 Docker 并设置开机自启 systemctl enable docker systemctl start docker # 验证 Docker 和 Compose 可用 docker info | grep -E Architecture|Server Version docker compose versionyumdownloader --resolve会把所有依赖包一并下载避免目标机器上缺依赖。--nodeps --force在离线安装时常用但要注意如果系统里已有旧版本 Docker先卸载干净再装否则容易出现 containerd 版本冲突。docker compose version输出Docker Compose version v2.x.x才算就绪如果只有docker-compose带横杠命令那是 v1 版本Harbor v2.9.0 虽然兼容但建议升级到 v2。3. Harbor v2.9.0 离线安装全流程3.1 解压离线包与导入镜像把离线包上传到目标服务器建议放在/opt或/data目录下避免放在/tmp因为重启后可能被清理。# 创建安装目录并解压 mkdir -p /opt/harbor-install cd /opt/harbor-install tar -xzf harbor-offline-installer-v2.9.0.tgz # 进入解压后的目录 cd harbor # 导入所有组件镜像这一步耗时较长arm 架构下约 3-5 分钟 docker load -i harbor.v2.9.0.tar.gz # 确认镜像已导入 docker images | grep goharbordocker load的输出会逐层显示Loaded image: goharbor/registry-photon:v2.9.0等信息。如果中途报no space left on device说明/var/lib/docker所在分区空间不足Harbor 全部镜像解压后大约占用 3-4 GB加上运行时的数据卷建议预留至少 20 GB。docker images | grep goharbor应该能看到十几个组件镜像缺任何一个都会导致后续docker compose up失败。3.2 harbor.yml 关键参数配置Harbor 的配置文件模板是harbor.yml.tmpl需要复制一份并重命名为harbor.yml再修改。cp harbor.yml.tmpl harbor.yml vim harbor.yml以下是最需要关注的几个参数按配置块逐一说明# 主机名可以是 IP 或域名内网环境建议直接用 IP hostname: 192.168.1.100 # HTTP 配置内网测试可以只开 HTTP http: port: 80 # HTTPS 配置生产环境必须配内网没有证书可以用自签名 https: port: 443 certificate: /opt/harbor-install/certs/harbor.crt private_key: /opt/harbor-install/certs/harbor.key # 管理员初始密码首次登录后立即修改 harbor_admin_password: Harbor12345 # 数据库密码离线安装用内置 PostgreSQL 即可 database: password: root123 max_idle_conns: 100 max_open_conns: 900 # 数据存储路径建议挂载到大容量分区 data_volume: /data/harbor # 日志配置 log: level: info local: rotate_count: 50 rotate_size: 200M location: /data/harbor/logshostname一旦设定后续所有 docker push/pull 都依赖这个地址改起来很麻烦建议一开始就用最终要用的 IP 或域名。data_volume默认是/data如果服务器上/data分区不大改成其他大容量路径。harbor_admin_password是初始密码Harbor 不会强制你首次登录修改但生产环境一定要改。https块如果暂时不用可以整段注释掉但注释后 Harbor 只监听 HTTPdocker 客户端需要配置insecure-registries才能 push。3.3 执行安装与验证配置改完后运行prepare脚本生成 docker-compose 文件再执行install.sh。# 预检环境会检查 Docker 版本、端口占用、配置文件语法 ./prepare # 执行安装会自动 docker compose up -d 并初始化数据库 ./install.sh # 查看容器状态所有容器应为 Up 或 healthy docker compose ps # 查看 Harbor 核心服务日志 docker compose logs -f core./prepare会读取harbor.yml并生成docker-compose.yml如果配置文件有语法错误会直接报出来。./install.sh执行完毕后用docker compose ps检查正常情况应该看到 9 个左右的容器在运行。core容器负责 API 和认证如果它反复重启多半是数据库连接失败或密钥文件权限问题用docker compose logs core看具体报错。验证安装是否成功最直接的方式是从另一台机器或本机用 curl 访问# 检查 Harbor API 是否响应 curl -k https://192.168.1.100/api/v2.0/systeminfo # 用 docker 登录并推送一个测试镜像 docker login 192.168.1.100 -u admin -p Harbor12345 docker pull hello-world docker tag hello-world 192.168.1.100/library/hello-world:test docker push 192.168.1.100/library/hello-world:testcurl返回 JSON 格式的系统信息说明 API 正常。docker push成功则说明 registry 存储和认证链路都通了。如果 push 时报x509: certificate signed by unknown authority说明用的是自签名证书且客户端没有信任需要在客户端的 Docker 配置里加上insecure-registries或把 CA 证书拷过去。4. arm 架构下 Harbor 的避坑与排查4.1 镜像架构不匹配导致容器起不来现象docker compose up -d后部分容器状态一直是Restartingdocker compose logs看到exec /usr/bin/xxx: exec format error。原因离线包里的镜像不是 arm64 架构可能是 x86 的包被误传到 arm 服务器上或者离线包本身下载错了版本。解决用docker inspect检查镜像架构确认Architecture字段为arm64。如果确实是 x86 镜像需要重新获取 arm64 版本的离线包。Harbor 官方从 v2.5.0 开始提供多架构离线包下载时注意选择arm64标识的版本。# 检查已导入镜像的架构 docker inspect goharbor/harbor-core:v2.9.0 --format {{.Architecture}}4.2 端口冲突导致 nginx 容器无法启动现象docker compose ps显示nginx容器状态为Exit日志报bind: address already in use。原因宿主机上 80 或 443 端口被其他服务占用常见的是系统自带的 httpd 或 nginx。解决先确认端口占用情况再决定是停掉占用服务还是改 Harbor 的监听端口。# 查看 80 和 443 端口占用 ss -tlnp | grep -E :80|:443 # 如果占用服务不需要停掉它 systemctl stop httpd systemctl disable httpd # 如果需要保留占用服务修改 harbor.yml 中的 http.port 为其他端口 # 改完后重新执行 ./prepare docker compose up -d4.3 数据卷权限问题导致 core 容器反复重启现象core容器启动后立即退出日志显示permission denied或cannot open /etc/harbor/...。原因data_volume指定的目录权限不对Harbor 容器内以非 root 用户运行需要目录可写。解决确保data_volume目录存在且权限为 755 或 777同时检查 SELinux 是否开启。# 创建数据目录并放宽权限 mkdir -p /data/harbor chmod 755 /data/harbor # 如果系统开启了 SELinux临时设为 permissive 测试 setenforce 0 # 永久关闭 SELinux 需修改 /etc/selinux/config # 将 SELINUXenforcing 改为 SELINUXdisabled重启生效4.4 离线环境下 docker load 报空间不足现象docker load -i harbor.v2.9.0.tar.gz执行到一半报no space left on device。原因/var/lib/docker所在分区剩余空间不足Harbor 镜像解压后占用空间比压缩包大得多。解决清理 Docker 无用数据或把 Docker 数据目录迁移到大分区。# 查看 Docker 磁盘占用 docker system df # 清理未使用的镜像和容器 docker system prune -a # 如果空间仍然不够迁移 Docker 数据目录 systemctl stop docker mkdir -p /data/docker mv /var/lib/docker/* /data/docker/ # 修改 /etc/docker/daemon.json加入 data-root: /data/docker systemctl start docker4.5 自签名证书导致 docker push 失败现象docker push报x509: certificate signed by unknown authority或server gave HTTP response to HTTPS client。原因Harbor 配了 HTTPS 但用的是自签名证书客户端不信任或者 Harbor 只配了 HTTP 但客户端默认走 HTTPS。解决把 Harbor 的 CA 证书拷贝到客户端的信任目录或者在客户端 Docker 配置里加insecure-registries。# 在客户端机器上创建证书目录 mkdir -p /etc/docker/certs.d/192.168.1.100 # 把 Harbor 服务器的 harbor.crt 拷贝过来 scp root192.168.1.100:/opt/harbor-install/certs/harbor.crt /etc/docker/certs.d/192.168.1.100/ca.crt # 重启 Docker systemctl restart docker如果 Harbor 只配了 HTTP在客户端的/etc/docker/daemon.json中加入{ insecure-registries: [192.168.1.100] }然后systemctl restart docker即可。5. 离线环境下的版本升级与数据迁移技巧Harbor 离线安装完成后后续版本升级同样需要在离线环境下操作。v2.9.0 升级到更高版本时不能直接覆盖安装需要先备份数据库和配置文件再导入新版本镜像最后执行迁移脚本。我一般会先把harbor.yml和/data/harbor整个目录打包备份然后停掉旧版本容器导入新版本离线包用新版本的prepare生成新的 docker-compose 文件再启动。数据库迁移是自动的但跨大版本升级时建议先在测试环境跑一遍。# 备份配置和数据 tar -czf harbor-backup-$(date %Y%m%d).tar.gz /opt/harbor-install/harbor/harbor.yml /data/harbor # 停止旧版本 cd /opt/harbor-install/harbor docker compose down # 解压新版本离线包到新目录 mkdir -p /opt/harbor-install/harbor-new tar -xzf harbor-offline-installer-v2.10.0.tgz -C /opt/harbor-install/harbor-new # 拷贝旧配置到新目录 cp /opt/harbor-install/harbor/harbor.yml /opt/harbor-install/harbor-new/harbor/harbor.yml # 导入新镜像并启动 cd /opt/harbor-install/harbor-new/harbor docker load -i harbor.v2.10.0.tar.gz ./prepare ./install.sh数据迁移的关键是data_volume指向同一个目录这样新版本的容器会直接读取旧数据。数据库迁移脚本在core容器启动时自动执行如果迁移失败core日志会打印具体的 SQL 错误根据错误回滚到旧版本再排查。另一个实用技巧是定期导出 Harbor 的配置和项目列表方便在迁移或重建时快速恢复。Harbor API 支持导出项目元数据用 curl 就能拉取# 获取所有项目列表 curl -k -u admin:Harbor12345 https://192.168.1.100/api/v2.0/projects?page_size100 # 获取指定项目的仓库列表 curl -k -u admin:Harbor12345 https://192.168.1.100/api/v2.0/projects/library/repositories?page_size100这些 JSON 数据可以存档重建 Harbor 后通过 API 批量创建项目和配置机器人账号。我自己的习惯是每次升级前都把项目列表和机器人账号导出成 JSON 存一份虽然大多数时候用不上但有一次数据库迁移卡住靠这份导出文件手动恢复了二十多个项目的权限配置省了大半天时间。arm 架构下 Harbor 的离线安装和升级整体流程和 x86 差异不大核心就是盯紧镜像架构、数据目录权限和端口占用这三件事。希望帮到你。本文还有配套的精品资源点击获取