飞腾服务器离线部署Harbor v2.4.0 arm64全流程与避坑指南

简介面向需要在ARM架构服务器上私有化部署容器镜像仓库的运维与DevOps人员这份harbor-v2.4.0离线安装包解决了内网无外网、无法在线拉取镜像的部署难题。包内共6个文件以sh脚本、gz压缩包、yml配置、license许可及prepare准备文件为主涵盖安装脚本、镜像归档与配置模板整体约402.34MB解压后执行install.sh即可一键完成安装前置条件为已装好docker与docker-compose。目前已有1576人学习下载说明该版本在ARM环境下的实用性与关注度较高。借助其中的harbor.v2.4.0.tar.gz镜像包与harbor.yml配置样例读者可快速搭建带权限管理、镜像复制与漏洞扫描能力的私有仓库并参考common.sh与prepare脚本理解离线安装的目录结构与依赖准备逻辑减少在国产化或ARM服务器上反复试错的成本。1. 从一台飞腾服务器说起为什么 harbor-v2.4.0 离线装 arm 架构总翻车上个月帮某实验室的 A 同学处理一台飞腾服务器机器上跑着几个内部镜像仓库的迁移任务要求全程离线、架构是 aarch64。他之前照着 x86 的教程走docker load完镜像、docker-compose up -d一敲harbor-core 起来三秒就退出日志里全是exec format error。这不是玄学是 arm 架构下镜像 tag 没选对加上离线包里混进了 amd64 的组件。harbor-v2.4.0 这个版本在 arm 上离线部署坑集中在三处离线包架构、docker-compose 版本、以及 data volume 的权限。这篇笔记按我实际装过一遍的流程写从环境清单到验证跑通中间穿插几条血泪经验。适合正在内网、信创环境或边缘节点上折腾私有镜像仓库的开发者新手照着能走通熟手可以重点看版本取舍和排错那段。2. 装前把环境列清harbor-v2.4.0 在 arm 上到底要什么2.1 硬件与操作系统基线harbor-v2.4.0 官方对 arm64 的支持从 2.0 之后逐步完善但 2.4.0 这个版本对内核和文件系统仍有隐性要求。我一般会先确认三件事CPU 架构是aarch64而不是armv7l内核版本不低于 4.19根分区剩余空间不少于 40G。操作系统层面麒麟 V10 SP2、统信 UOS 20、Ubuntu 20.04 arm64 都实测能跑CentOS 7 的 arm 版因为内核太老docker 版本会被卡在 19.03后面 compose 文件里的version: 3.8会报兼容警告能跑但不推荐。内存方面harbor 全家桶core、portal、registry、redis、postgresql、trivy 等跑起来常驻大概 2.5G 到 3G官方写最低 4G我建议直接给 8G否则 trivy 扫描大镜像时容易 OOM。磁盘要单独挂一块给/data因为镜像层和数据库都往这里写系统盘被撑爆是新手最常见的翻车点。# 确认架构和内核输出必须是 aarch64 和 4.19 以上 uname -m uname -r # 看根分区和计划挂载的数据盘 df -hT | grep -E ext4|xfs # 确认 cgroup 是 v1 还是 v2harbor 2.4.0 在 cgroup v2 上需要额外参数 stat -fc %T /sys/fs/cgroup/上面三条命令里uname -m的输出如果是armv7l就直接换机器别浪费时间stat -fc %T /sys/fs/cgroup/返回cgroup2fs的话后面 docker 启动参数要加--exec-opt native.cgroupdriversystemd否则 harbor 的 portal 容器会反复重启。2.2 依赖组件版本对照离线安装最怕版本错配。harbor-v2.4.0 的离线包自带 docker 镜像但 docker 引擎和 docker-compose 需要自己提前装好。下面这张表是我在 arm 上验证过的组合直接抄组件推荐版本最低版本说明Docker Engine20.10.1719.03.9arm64 包要从对应源取docker-compose1.29.21.25.02.x 语法有差异2.4.0 不认containerd1.6.61.4.0随 docker 一起装openssl1.1.1k1.1.1生成证书用docker-compose 这里要特别说一句harbor-v2.4.0 的docker-compose.yml里写的是version: 3.8compose 2.x 虽然能解析但docker-compose命令本身在 2.x 变成了docker compose插件形式离线环境里插件装起来麻烦所以我一般锁 1.29.2。装完用docker-compose version确认输出是1.29.2不是的话后面prepare脚本会报unknown flag。# 下载 docker-compose 1.29.2 的 arm64 二进制离线环境提前拷进去 # 假设文件已经放在 /tmp/docker-compose-Linux-aarch64 cp /tmp/docker-compose-Linux-aarch64 /usr/local/bin/docker-compose chmod x /usr/local/bin/docker-compose # 验证版本必须是 1.29.2 docker-compose versionchmod x这步别漏漏了会提示Permission denied但报错信息不会直接告诉你是权限问题新手容易往别处查。docker-compose version输出里如果出现Docker Compose version v2.x说明系统里已经有 2.x 的插件需要把/usr/local/bin/docker-compose的优先级调到 PATH 最前或者直接删掉 2.x 的软链。3. 离线包落地harbor-v2.4.0 arm64 包的获取与解压3.1 离线包结构说明harbor 的离线安装包命名规则是harbor-offline-installer-v2.4.0.tgz但 arm 架构的包在官方发布页里和 x86 混在一起下载时一定要看清文件名里有没有arm64或aarch64字样。我拿到的包解压后目录结构是这样的harbor/ ├── harbor.v2.4.0.tar.gz # 所有组件的 docker 镜像 ├── harbor.yml.tmpl # 配置模板 ├── install.sh # 安装入口 ├── prepare # 环境预检脚本 └── common.sh # 公共函数harbor.v2.4.0.tar.gz这个文件是核心里面打包了 9 个镜像解压后docker load进去。如果这个包是 x86 的docker load不会报错但docker run时会提示exec format error这就是 A 同学遇到的那个现象。判断方法很简单docker load之后执行docker images | grep goharbor看镜像的ARCHITECTURE列是不是arm64。# 解压离线包 tar -zxvf harbor-offline-installer-v2.4.0-arm64.tgz -C /opt/ # 进入目录先别急着 install看一眼镜像包大小 ls -lh /opt/harbor/harbor.v2.4.0.tar.gz # 加载镜像这一步在 arm 上大概需要 2-3 分钟 docker load -i /opt/harbor/harbor.v2.4.0.tar.gz # 确认所有镜像都是 arm64 docker images --format {{.Repository}}:{{.Tag}}\t{{.Size}} | grep goharbordocker load的输出会逐层打印如果中途出现no space left on device说明/var/lib/docker所在分区不够需要先清理或迁移 docker 根目录。加载完成后docker images里应该能看到goharbor/harbor-core:v2.4.0、goharbor/registry-photon:v2.4.0等每个镜像的架构信息可以用docker inspect单独确认。3.2 配置 harbor.yml 的关键参数harbor.yml.tmpl复制成harbor.yml之后需要改的地方不多但每一处都影响能不能跑起来。我一般按下面这个顺序改# 复制模板 cp /opt/harbor/harbor.yml.tmpl /opt/harbor/harbor.yml # 编辑 harbor.yml重点改这几项 hostname: harbor.internal.lab # 改成实际访问的域名或 IP http: port: 80 # 内网用 80冲突就换 8080 https: # 离线内网没有证书就整段注释掉否则 prepare 会报错 # port: 443 # certificate: /your/certificate/path # private_key: /your/private/key/path harbor_admin_password: Harbor12345 # 首次登录密码装完可改 data_volume: /data # 必须提前建好目录并给权限 trivy: ignore_unfixed: false skip_update: true # 离线环境必须 true否则拉漏洞库失败hostname这一项如果填了域名客户端机器必须能解析否则docker login会报no such host。data_volume指向的目录要提前mkdir -p /data并chmod 750属主是 root因为 harbor 容器里以 root 跑。skip_update: true是离线环境的后悔药不设的话 trivy 启动时会尝试连外网更新漏洞库超时后整个 harbor-core 会卡在 starting 状态。提示harbor_admin_password如果留默认值装完后第一件事就是登录改掉内网也一样这是习惯问题。4. 执行安装prepare 与 install.sh 的完整流程4.1 prepare 脚本做了什么./prepare这个脚本会根据harbor.yml生成最终给 docker-compose 用的docker-compose.yml同时检查端口占用、目录权限、镜像是否已加载。在 arm 上跑的时候我遇到过两种报错一种是permission denied指向/data原因是目录属主不对另一种是port 80 already in use通常是系统里已经有 nginx 或 httpd 在跑。cd /opt/harbor # 先跑 prepare观察输出 ./prepare # 如果报端口占用查一下谁占了 80 ss -tlnp | grep :80 # 如果报 /data 权限问题重新给权限 chown -R root:root /data chmod 750 /data./prepare成功的话最后会输出Clean up the input dir和Generated configuration file: ./docker-compose.yml。这时候可以打开生成的docker-compose.yml看一眼确认里面所有镜像的 tag 都是v2.4.0没有混入dev或latest。如果prepare中途失败它不会自动回滚需要手动删掉生成的docker-compose.yml再重跑。4.2 install.sh 启动与首次启动观察./install.sh是最后一步它会调用docker-compose up -d把所有容器拉起来。在 arm 上首次启动大概需要 1 到 2 分钟因为 postgresql 要初始化数据库、registry 要建存储目录。启动过程中不要急着docker ps等脚本自己输出✔ ----Harbor has been installed and started successfully.----再操作。# 执行安装 ./install.sh # 安装完成后看容器状态所有容器应该是 Up 或 healthy docker-compose ps # 实时看 harbor-core 日志确认没有反复重启 docker-compose logs -f harbor-coredocker-compose ps的输出里harbor-db、harbor-redis、harbor-core这三个是关键任何一个状态是Exit或Restarting都说明有问题。harbor-core日志里如果出现failed to connect to database多半是harbor-db还没初始化完等 30 秒再docker-compose restart harbor-core即可。如果日志里出现exec format error回到第 3 章检查镜像架构。注意install.sh执行过程中如果中断不要直接重跑先docker-compose down -v清掉容器和 volume再重新./prepare ./install.sh否则残留的 volume 会导致数据库密码不一致。5. 避坑与排查arm 离线装 harbor 最常见的 5 个坑5.1 坑一镜像架构不匹配容器起不来现象docker-compose up -d之后harbor-core和harbor-portal反复重启docker logs里只有一行exec format error没有更多信息。原因离线包里的harbor.v2.4.0.tar.gz是 x86 版本docker load能成功是因为 docker 不校验架构但内核执行时发现指令集不对直接拒绝。解决重新获取 arm64 的离线包用docker inspect goharbor/harbor-core:v2.4.0 | grep Architecture确认输出是arm64。已经 load 进去的 x86 镜像用docker rmi删掉再重新 load。5.2 坑二data_volume 权限不对registry 写不进去现象harbor 能起来但docker push镜像时报received unexpected HTTP status: 500registry容器日志里写permission denied。原因/data目录属主是普通用户或者权限是 755registry 容器里以10000用户跑写不进去。解决chown -R 10000:10000 /data/registry或者简单点chmod 777 /data内网临时用可以长期还是按官方建议给 10000 用户。5.3 坑三docker-compose 版本过高语法不认现象./prepare报Unsupported config option for services: version或者unknown flag: --compatibility。原因系统里装的是 compose 2.x命令形式变成docker compose而 harbor 2.4.0 的脚本里写死了docker-compose。解决降级到 1.29.2或者建一个软链ln -s /usr/libexec/docker/cli-plugins/docker-compose /usr/local/bin/docker-compose并确保 PATH 优先级。5.4 坑四trivy 离线更新失败拖垮 core现象harbor-core一直处于starting状态日志里反复出现failed to download vulnerability database。原因harbor.yml里trivy.skip_update没设成true容器启动时尝试连外网。解决改harbor.yml里trivy.skip_update: true然后./prepare docker-compose up -d。如果已经卡住先docker-compose stop trivy再改配置。5.5 坑五hostname 用了 localhost客户端登录失败现象服务端docker login能成功但另一台机器docker login harbor.internal.lab报dial tcp: lookup harbor.internal.lab: no such host。原因harbor.yml里hostname填了localhost或127.0.0.1客户端无法解析。解决改成内网 DNS 能解析的域名或者在客户端/etc/hosts里加一条记录。改完hostname后必须重新./prepare docker-compose down docker-compose up -d否则证书和配置不生效。6. 装完怎么验证从 push 到 pull 走一遍才算跑通装完不验证等于没装。我一般会走一个最小闭环在服务端docker login然后docker tag一个本地镜像docker push上去再换一台客户端docker pull下来。这一步能同时验证认证、存储、网络和 registry 的读写。# 服务端登录输入 harbor.yml 里设的密码 docker login harbor.internal.lab # 拿一个本地镜像打 tag注意项目名要先在 harbor 界面里建好 docker tag nginx:alpine harbor.internal.lab/library/nginx:alpine # push 上去 docker push harbor.internal.lab/library/nginx:alpine # 换一台客户端同样先登录再 pull docker login harbor.internal.lab docker pull harbor.internal.lab/library/nginx:alpinedocker login如果报x509: certificate signed by unknown authority说明用的是自签证书且客户端没信任把服务端的ca.crt拷到客户端/etc/docker/certs.d/harbor.internal.lab/下即可。docker push如果报denied: requested access to the resource is denied检查项目名是否存在、当前用户是否有 push 权限。docker pull成功的话docker images里能看到harbor.internal.lab/library/nginx:alpine大小和源镜像一致。再补一个验证点登录 harbor 的 Web 界面用admin和harbor_admin_password进去看Projects里有没有libraryRepositories里有没有刚推的 nginx。Web 能打开、镜像能列出说明 portal 和 core 的数据库连接也正常。如果 Web 打不开但 push 能用多半是harbor-portal容器挂了docker-compose restart portal再试。从那以后我每次装完 harbor不管多急都强制走一遍 push 和 pull不看到客户端拉下来镜像不算完。这套流程在 arm 上跑通一次之后后面迁移或重装就是复制粘贴的事。希望帮到你。本文还有配套的精品资源点击获取