简介面向需要在 ARM 架构服务器上私有化部署容器镜像仓库的运维与开发人员这份 Harbor v2.4.0 离线安装包解决的是内网或受限网络环境下无法在线拉取镜像、依赖安装繁琐的问题。包内共 6 个文件以 sh 安装脚本、gz 镜像归档、yml 配置文件及 license 等为主分别承担一键安装、镜像导入与参数配置等用途压缩包整体约 402MB解压后按说明执行脚本即可完成部署前置条件为已装好 docker 与 docker-compose。内容围绕离线场景组织安装脚本与配置文件配合便于读者快速搭建可用的镜像仓库并在此基础上调整端口、存储路径等参数减少逐项排查依赖的时间。目前已有 1578 人学习下载适合具备一定 Linux 与容器基础、希望在内网环境落地 Harbor 的中级用户参考使用。1. 一次在 ARM 服务器上装 Harbor 2.4.0 的翻车记录上周帮一个做私有镜像仓库的团队在 ARM 服务器上装 Harbor 2.4.0本以为半小时能收工结果卡了整整一个下午。问题不在 Harbor 本身而在于我一开始按 x86 的习惯去准备离线包镜像架构对不上docker load全部报no matching manifest。Harbor 2.4.0 这个版本在 ARM 上装的人不算多但一旦装好私有镜像仓库、镜像扫描、项目隔离这些能力都能落地适合内网环境、信创服务器、边缘节点这类不能随便连外网的场景。这篇笔记按「装什么版本 → 怎么准备离线包 → 怎么配 → 坏了怎么救 → 怎么验证」走一遍新手能照着跑通熟手能看到 ARM 架构下几个容易忽略的参数取舍。2. 装前把环境列清ARM 架构下 Harbor 2.4.0 的版本与依赖2.1 硬件与操作系统的最低要求Harbor 2.4.0 官方给的最低配置是 2 核 CPU、4 GB 内存、40 GB 磁盘但这是「能跑起来」的底线不是「能稳定用」的配置。我一般会按 4 核、8 GB 内存、100 GB 磁盘来准备因为 Harbor 自带 PostgreSQL、Redis、Registry、Trivy 扫描器、Jobservice 这一堆容器内存不够时最先出问题的是 Trivy 扫描任务表现为扫描一直排队或者直接失败日志里看不到明显报错属于典型的玄学问题。操作系统方面ARM 服务器上常见的是麒麟、统信、Ubuntu 20.04/22.04 的 ARM 版、CentOS 的 ARM 衍生版。内核建议 4.19 以上低于这个版本时 Docker 的 cgroup v2 支持不完整容器启动会偶发失败。文件系统用 ext4 或 xfs 都行但不要用 overlay 作为宿主机根文件系统Docker 的存储驱动会和它打架。2.2 版本对照表Harbor、Docker、docker-compose 的搭配组件推荐版本说明Harborv2.4.0本文目标版本ARM 离线包需自行构建或找对应架构的 releaseDocker Engine20.10.x2.4.0 的 compose 文件用的是 compose v3 语法20.10 足够docker-compose1.29.x 或 2.x1.29 是 Python 版最后一版2.x 是 Go 版两者命令兼容PostgreSQL内置 13Harbor 自带不用单独装Redis内置 6Harbor 自带不用单独装这里有个容易踩的点Harbor 2.4.0 的docker-compose.yml里写的镜像 tag 是v2.4.0但这些镜像默认只有 amd64 架构。ARM 上要么用官方后来补的 multi-arch 镜像要么自己用源码构建。我这次用的是团队提前构建好的 ARM 镜像包tag 保持一致只是 manifest 是 arm64。2.3 离线包到底包含什么离线安装包不是单个文件而是一组东西Harbor 的安装包harbor-offline-installer-v2.4.0.tgz、所有依赖镜像的 tar 包、以及可选的 Trivy 漏洞库离线包。ARM 架构下镜像 tar 包必须是用docker save从 arm64 环境导出的不能拿 amd64 的包凑数。判断方法很简单docker load之后执行docker inspect image --format {{.Architecture}}输出必须是arm64。提示离线包里的镜像数量在 10 个左右包括 nginx、harbor-core、harbor-db、harbor-jobservice、harbor-portal、harbor-registry、registryctl、redis、trivy-adapter、harbor-exporter。少一个都会在docker-compose up时报 image not found。3. 离线安装实操从解包到 Harbor 起来的完整命令链3.1 解包与目录规划先把离线包传到服务器上我习惯放在/opt/software下安装目录用/opt/harbor数据目录单独挂一块盘到/data这样以后升级或者迁移时数据不会跟着安装目录一起被覆盖。# 创建目录结构 mkdir -p /opt/software /opt/harbor /data/harbor # 解压安装包 cd /opt/software tar -xzf harbor-offline-installer-v2.4.0.tgz -C /opt/ # 确认解压结果 ls -l /opt/harbor/解压后/opt/harbor下会有harbor.yml.tmpl、install.sh、prepare、common.sh这几个文件。harbor.yml.tmpl是配置模板不能直接改要先复制成harbor.yml。这一步很多人图省事直接改 tmpl结果install.sh读的是harbor.yml配置根本没生效装完发现端口还是默认的 80。3.2 导入 ARM 镜像并确认架构镜像导入是 ARM 离线安装里最容易翻车的一步。把所有 tar 包放到一个目录循环 load然后逐个检查架构。# 进入镜像包目录 cd /opt/software/images # 循环导入所有 tar 包 for img in *.tar; do echo loading $img docker load -i $img done # 检查所有镜像的架构非 arm64 的要单独处理 docker images --format {{.Repository}}:{{.Tag}} | while read img; do arch$(docker inspect $img --format {{.Architecture}}) echo $img - $arch donedocker load本身不校验架构所以 amd64 的镜像也能 load 成功但docker-compose up时会报exec format error。上面这段检查就是提前把这个坑挖出来。如果发现某个镜像是 amd64要么换包要么用docker buildx重新构建不要试图用--platform强行跑Harbor 的 core 组件是 Go 编译的二进制架构不对直接起不来。3.3 配置 harbor.ymlARM 环境下必须改的五个参数复制模板后重点改这几项。ARM 服务器通常不对外暴露 80/443或者 80 被别的服务占了所以端口要改数据目录要指到独立盘hostname不能写localhost否则客户端 push 镜像时解析不到。# /opt/harbor/harbor.yml hostname: harbor.internal.example # 改成实际可解析的域名或 IP http: port: 8080 # 避开被占用的 80 https: port: 8443 certificate: /data/harbor/cert/server.crt private_key: /data/harbor/cert/server.key harbor_admin_password: ChangeMe_2024 data_volume: /data/harbor # 数据落独立盘 trivy: ignore_unfixed: false skip_update: true # 离线环境必须 true否则扫描器启动时联网失败skip_update: true是离线环境的关键Trivy 默认启动时会去拉漏洞库内网拉不到就一直重试表现为trivy-adapter容器反复重启。data_volume改了之后install.sh会把 registry 的存储、数据库数据、日志都放到这个目录下所以这个目录的权限要给足我一般chown -R 10000:10000 /data/harbor因为 Harbor 容器内用的 uid 是 10000。3.4 执行安装与首次启动检查配置改完先跑prepare生成 compose 文件再跑install.sh。prepare会根据harbor.yml渲染出docker-compose.yml这一步如果报错多半是 yml 缩进或者证书路径不对。cd /opt/harbor # 生成配置文件--with-trivy 表示启用扫描器 ./prepare --with-trivy # 执行安装--with-trivy 同样要带上 ./install.sh --with-trivy安装脚本会做几件事检查 Docker 和 compose 是否可用、加载镜像、启动容器、等待健康检查。最后输出Harbor has been installed and started successfully才算完。如果卡在Waiting for Harbor to come up先别急着重装用docker-compose ps看哪个容器是unhealthy或restarting再看那个容器的日志八成是端口冲突或者数据目录权限问题。4. 配置调优与常见故障排查4.1 端口、证书与外部访问的取舍ARM 服务器上 80 端口经常被系统自带的 web 服务占用所以改http.port是最省事的做法。但改端口之后客户端docker login要带上端口号比如docker login harbor.internal.example:8080这一点要在团队里说清楚否则会有人反馈「登录不上」其实是没带端口。证书方面内网环境可以用自签证书但要把 CA 分发到所有需要 push 的机器上放到/etc/docker/certs.d/harbor.internal.example:8080/ca.crt然后重启 Docker。不这么做的话docker push会报x509: certificate signed by unknown authority很多人第一反应是去改 Harbor 配置其实是客户端没信任 CA。4.2 数据目录权限与磁盘规划前面提到data_volume要 chown 到 10000这里补充一个细节如果/data是单独挂载的盘挂载后要先chown再跑install.sh因为安装脚本不会帮你改挂载点的属主。我遇到过装完之后 registry 容器一直重启日志里是permission denied写/storage查了半天发现是/data/harbor属主是 root。磁盘规划上registry 的 blob 增长最快建议/data至少留 200 GB并且配一个定时清理策略。Harbor 2.4.0 自带垃圾回收在「系统管理 → 垃圾清理」里可以配 cron我一般设成每周日凌晨跑一次保留最近 30 天的 untagged 镜像。4.3 五个高频踩坑记录现象一docker-compose up报no matching manifest for linux/arm64。原因镜像包是 amd64 的load 进去但架构不匹配。 解决换 arm64 镜像包或者用docker buildx build --platform linux/arm64从源码重新构建构建完docker save导出再 load。现象二harbor-core容器启动后立刻退出日志只有一行panic: runtime error。原因harbor.yml里hostname写成了localhost或者带了下划线Harbor 的配置校验不认。 解决改成合法域名或纯 IP不要带下划线改完重新./prepare再docker-compose up -d。现象三Trivy 扫描任务一直处于Pendingtrivy-adapter容器反复重启。原因离线环境没设skip_update: true扫描器启动时联网拉库超时。 解决在harbor.yml的trivy段加skip_update: true然后./prepare --with-trivy docker-compose up -d。漏洞库需要手动导入的话用trivy image --download-db-only在能联网的机器上拉好再拷到/data/harbor/trivy-adapter/下。现象四docker push报received unexpected HTTP status: 500。原因registry 的存储目录权限不对或者磁盘满了。 解决df -h /data看磁盘docker logs registry看具体错误权限问题就chown -R 10000:10000 /data/harbor磁盘满就清旧镜像或者扩容。现象五升级或重装后原来的镜像和项目全没了。原因重装时data_volume指到了新目录或者docker-compose down -v把 volume 删了。 解决重装前先备份/data/harbordocker-compose down不要带-vharbor.yml里的data_volume保持和原来一致。5. 装完怎么验证三条命令确认 Harbor 真的可用装完看到successfully不代表真的能用我一般会走三步验证缺一步都不算完。第一步看容器状态和健康检查。docker-compose ps里所有容器的State应该是UpHealth是healthy。如果有unhealthy先看那个容器的日志不要直接重启重启解决不了配置问题。cd /opt/harbor docker-compose ps # 期望输出所有服务 State 为 UpHealth 为 healthy没有 healthcheck 的显示 Up 即可第二步用 API 探活。Harbor 2.4.0 的/api/v2.0/health会返回各组件的健康状态比看容器状态更准因为它会实际检查数据库和 registry 的连通性。curl -s http://harbor.internal.example:8080/api/v2.0/health | python3 -m json.tool # 期望status 为 healthycomponents 里 database、registry、redis 都是 healthy第三步走一遍完整的 push/pull。这一步最能暴露问题因为涉及认证、存储、网络三块。# 登录 docker login harbor.internal.example:8080 -u admin -p ChangeMe_2024 # 打 tag 并 push 一个测试镜像 docker tag alpine:3.18 harbor.internal.example:8080/library/alpine:test docker push harbor.internal.example:8080/library/alpine:test # 删掉本地镜像再 pull确认存储真的写进去了 docker rmi harbor.internal.example:8080/library/alpine:test docker pull harbor.internal.example:8080/library/alpine:testpush 成功但 pull 失败多半是 registry 的存储路径问题push 直接 401是认证或者项目权限没配push 报 413是 nginx 的client_max_body_size太小Harbor 2.4.0 默认是 0不限制但如果前面还有一层反向代理要检查那一层的配置。从那以后我每次装完 Harbor不管多急都强制走一遍这三步验证尤其是 push/pull 那一步因为容器状态 healthy 但 registry 写不进去的情况我见过不止一次。希望帮到你。本文还有配套的精品资源点击获取