Harbor v2.9.0离线安装（arm架构）：内网镜像仓库部署实战

简介面向需要在国产化或 ARM 服务器上私有化部署镜像仓库的运维与 DevOps 人员这份资源提供 harbor-v2.9.0 的 arm64 架构离线安装包解决内网环境无法拉取镜像、x86 包无法在 ARM 平台运行的问题。压缩包共 6 个文件约 722.35MB以 gz 离线镜像包为主体配合 sh 安装脚本、prepare 预处理脚本、tmpl 配置模板及 license 授权文件覆盖从环境准备到服务启动的完整链路执行 install.sh 即可一键完成部署前置条件为已安装 docker 与 docker-compose。目前已有 962 人学习下载适合具备一定容器基础、希望快速搭建 ARM 版 Harbor 的读者参考。借助该离线包可省去逐层拉取镜像与手动配置的繁琐过程直接获得可运行的私有仓库环境并对照配置模板调整端口、存储与访问参数降低内网部署门槛。1. harbor-v2.9.0离线安装arm架构内网环境下的镜像仓库落地很多做信创项目的工程师都遇到过这种场景客户机房完全断网服务器是鲲鹏或飞腾的 arm64 机器操作系统是银河麒麟或统信 UOS但 CI/CD 流水线又必须有一个私有镜像仓库来存业务镜像。这时候 harbor-v2.9.0 离线安装arm架构就成了绕不开的一环。Harbor 是 VMware 开源的企业级容器镜像仓库v2.9.0 这个版本在 arm64 上的组件兼容性已经比较成熟但官方发布的离线包默认是 x86_64 架构arm 机器上直接跑会报 exec format error。所以核心工作不是「装 Harbor」而是「在 arm 架构上把 Harbor 的离线安装包重新组装出来」。这篇文章面向的是需要在离线 arm 服务器上部署私有仓库的运维和平台工程师从离线包结构拆解讲到组件替换、配置调参和排错每一步都能照着复现。2. 拆解 harbor 离线安装包arm 架构下哪些组件必须换2.1 离线包目录结构与组件清单Harbor 的离线安装包offline installer本质上是一个 tar.gz解压后包含 harbor 目录和 harbor.v2.9.0.tar.gz 镜像包。harbor 目录里是 docker-compose.yml、prepare 脚本、common.sh 等编排文件而 harbor.v2.9.0.tar.gz 里是十几个容器镜像的 tar 层。安装逻辑很简单先 docker load 导入所有镜像再用 docker compose 拉起容器。问题在于官方离线包里的镜像全是 linux/amd64 的。在 arm64 机器上 docker load 能成功但 docker run 时会直接报exec /harbor/harbor_core: exec format error。所以 arm 架构离线安装的核心思路是保留官方离线包的编排文件和配置模板把里面的镜像全部替换成 arm64 版本。需要替换的镜像清单如下组件镜像名作用arm64 来源核心服务goharbor/harbor-coreAPI 与业务逻辑自行构建或第三方 arm 镜像门户goharbor/harbor-portalWeb UI同上数据库goharbor/harbor-dbPostgreSQL官方 postgres arm64 可替代缓存goharbor/redis-photonRedis官方 redis arm64 可替代注册表goharbor/registry-photon镜像存储官方 registry arm64 可替代任务服务goharbor/harbor-jobservice异步任务自行构建日志goharbor/harbor-log日志收集自行构建代理goharbor/nginx-photon反向代理官方 nginx arm64 可替代扫描器goharbor/trivy-adapter-photon漏洞扫描自行构建这张表是整篇文章的骨架。你会发现Harbor 自研的组件core、jobservice、portal、log、trivy-adapter没有官方 arm64 镜像必须自己编译或者找社区构建好的。而依赖的中间件PostgreSQL、Redis、Registry、Nginx都有官方 arm64 版本可以直接替换。2.2 为什么不能直接用 docker buildx 一把梭有经验的工程师第一反应是用 docker buildx 在 x86 机器上交叉编译 arm64 镜像不就行了理论上可行但 Harbor 的构建体系有几个坑。第一Harbor 的 Makefile 依赖 Photon OS 作为基础镜像而 Photon OS 的 arm64 版本并不完整部分包缺失。第二Harbor 的编译过程需要下载大量 Go 模块和 npm 包离线环境下根本拉不下来。第三即使编译成功镜像里的二进制还需要和 arm64 的 glibc 版本匹配银河麒麟的 glibc 版本和 Photon OS 不一定一致。所以更稳妥的做法是在一台能联网的 arm64 机器上比如鲲鹏开发板或者云上的 arm 实例用 Harbor 源码编译出 arm64 镜像然后 docker save 导出再拷贝到离线环境。如果连这台机器都没有那就只能找社区已经构建好的 arm64 镜像包但要注意版本必须和 v2.9.0 对齐否则数据库 migration 会出问题。我一般会准备一台 arm64 的 Ubuntu 20.04 作为构建机因为 Harbor 官方在 Ubuntu 上的编译依赖最容易满足。构建命令大致如下# 在 arm64 构建机上执行 git clone https://github.com/goharbor/harbor.git cd harbor git checkout v2.9.0 # 安装编译依赖 sudo apt-get install -y docker.io docker-compose make gcc # 编译并构建所有镜像 make build -e BUILD_ARCHarm64 # 导出镜像为 tar 包 make save -e BUILD_ARCHarm64这段命令的逻辑是先切到 v2.9.0 标签确保源码版本和离线包一致然后通过 make build 触发 Dockerfile 构建BUILD_ARCHarm64 会让编译参数指向 arm64最后 make save 把所有镜像导出成一个 tar 文件。参数 BUILD_ARCH 是关键不指定的话默认是 amd64编出来的镜像在 arm 上跑不了。构建完成后你会得到一个 harbor.v2.9.0.tar.gz里面的镜像就是 arm64 的了。把这个文件和官方离线包里的 harbor 目录编排文件组合在一起就得到了一个 arm64 离线安装包。3. 在银河麒麟 arm 服务器上执行离线安装3.1 系统前置检查与 docker 环境准备银河麒麟 V10 SP2 是信创环境里最常见的 arm64 操作系统内核版本一般是 4.19 或 5.10。在开始之前先确认几件事# 确认 CPU 架构 uname -m # 期望输出aarch64 # 确认内核版本 uname -r # 期望输出4.19.x 或 5.10.x # 确认 docker 是否已安装 docker version # 如果没有需要先离线安装 docker如果 docker 还没装需要准备 docker 的 arm64 离线 rpm 包。银河麒麟基于 CentOS 8 的包管理体系可以用yum install --downloadonly在联网机器上下载 docker-ce 及其依赖然后拷贝到离线机器上rpm -ivh安装。注意 docker 版本不要低于 20.10否则 docker compose v2 的语法可能不兼容。安装完 docker 后启动并设置开机自启sudo systemctl enable docker sudo systemctl start docker sudo systemctl status docker这一步看起来简单但血泪经验是银河麒麟默认的 SELinux 策略可能会阻止 docker 挂载卷。如果后面 Harbor 容器启动时报 permission denied先检查getenforce的输出如果是 Enforcing临时设为 Permissive 试试。3.2 导入 arm64 镜像并修改编排文件把 arm64 的 harbor.v2.9.0.tar.gz 和 harbor 目录放到同一级然后执行导入# 解压离线包 tar -xzf harbor-offline-installer-v2.9.0-arm64.tgz cd harbor # 导入所有镜像 docker load -i harbor.v2.9.0.tar.gz # 确认镜像架构 docker inspect goharbor/harbor-core:v2.9.0 --format {{.Architecture}} # 期望输出arm64导入完成后需要修改 harbor.yml 配置文件。从 harbor.yml.tmpl 复制一份cp harbor.yml.tmpl harbor.yml vim harbor.yml关键配置项如下# 修改为服务器的实际 IP 或域名 hostname: 192.168.1.100 # 如果不用 HTTPS注释掉 https 段 # https: # port: 443 # certificate: /your/certificate/path # private_key: /your/private/key/path # 数据存储路径确保磁盘空间足够 data_volume: /data/harbor # 数据库密码生产环境务必修改 database: password: root123 max_idle_conns: 100 max_open_conns: 900hostname 这一项必须填客户端能访问到的地址填 127.0.0.1 的话其他机器 push 镜像会失败。data_volume 建议单独挂一块盘因为镜像层很占空间放在系统盘容易把根分区撑满。3.3 执行安装脚本与验证服务状态配置改好后运行安装脚本sudo ./install.sh --with-trivy--with-trivy表示同时启用漏洞扫描组件。如果不需要扫描功能可以不加这个参数少启动一个容器省点资源。安装脚本会做几件事检查 docker 和 docker compose 版本、加载镜像、生成 docker-compose.yml、启动容器。整个过程大概 2 到 5 分钟取决于磁盘 IO 速度。安装完成后验证容器状态docker compose ps期望看到 9 个容器都是 Up 状态。如果有容器反复重启用docker logs 容器名看日志。最常见的问题是 harbor-db 启动失败原因是数据目录权限不对解决方法sudo chown -R 999:999 /data/harbor/database999 是 PostgreSQL 容器内 postgres 用户的 UID。这个坑在 x86 上不太常见但 arm 环境下因为文件系统权限映射差异出现的概率更高。最后验证 Web 界面和 push 功能# 浏览器访问 http://192.168.1.100 # 默认账号 admin密码 Harbor12345 # 命令行登录并 push 测试镜像 docker login 192.168.1.100 docker tag nginx:latest 192.168.1.100/library/nginx:test docker push 192.168.1.100/library/nginx:testpush 成功说明整个链路通了。如果 push 时报received unexpected HTTP status: 500多半是 harbor-core 和 registry 之间的通信问题检查这两个容器的日志。4. arm 架构离线安装 harbor 的避坑与排查4.1 镜像架构不匹配导致容器起不来现象docker compose up后容器状态一直是 Restarting日志里报exec format error。原因离线包里混入了 amd64 镜像或者 docker load 时没有覆盖旧镜像。解决用docker inspect 镜像名 --format {{.Architecture}}逐个检查发现 amd64 的重新导入 arm64 版本。导入前先docker rmi删掉旧镜像否则 docker load 会跳过已存在的标签。4.2 数据库初始化失败导致 harbor-core 崩溃现象harbor-db 容器 Up但 harbor-core 日志报dial tcp 127.0.0.1:5432: connect: connection refused。原因PostgreSQL 的数据目录权限不对或者初始化脚本没有执行完就超时了。解决先确认/data/harbor/database目录属主是 999:999然后删除该目录下的所有内容重启 harbor-db 容器让它重新初始化。注意这个操作会清空所有数据仅适用于首次安装。4.3 银河麒麟 SELinux 阻止卷挂载现象容器启动时报Permission denied但目录权限看起来没问题。原因SELinux 策略不允许 docker 访问宿主机目录。解决临时setenforce 0验证是否是 SELinux 问题。如果是可以在 docker-compose.yml 里给卷挂载加上:z或:Z标签或者永久调整 SELinux 策略。生产环境不建议直接关闭 SELinux加标签更安全。4.4 docker compose 版本不兼容现象./install.sh报docker compose command not found或unsupported option。原因银河麒麟自带的 docker-compose 可能是 v1 版本而 Harbor v2.9.0 要求 v2。解决离线安装 docker compose v2 的二进制文件放到/usr/local/bin/docker-compose并确保可执行。验证命令是docker compose version注意中间是空格不是横杠。4.5 磁盘空间不足导致镜像 push 失败现象push 镜像时进度条卡住然后报no space left on device。原因/data/harbor所在分区满了或者 docker 的>docker exec harbor-db pg_dump -U postgres registry /backup/registry_$(date %Y%m%d).sql这个备份文件在升级失败时就是后悔药回滚时导入即可。多节点分发的话如果内网有多个 Harbor 实例可以用 rsync 同步镜像存储目录但要注意 registry 的存储驱动必须一致。更稳妥的方式是每个节点独立部署然后用 Harbor 的复制策略做镜像同步。复制策略在 Web 界面的「仓库管理」里配置支持推模式和拉模式跨机房场景建议用拉模式避免网络抖动导致同步中断。最后说一个我踩过的坑arm64 镜像的 manifest 格式和 amd64 略有差异如果 Harbor 前面挂了 CDN 或者反向代理有些代理会缓存 manifest 导致拉取失败。解决方法是给 manifest 的 URL 加上Cache-Control: no-cache头或者在代理层禁用对/v2/路径的缓存。这个坑排查起来很费时间因为现象是「有时候能拉有时候不能拉」看起来像玄学实际上是缓存命中率的问题。希望帮到你。本文还有配套的精品资源点击获取