ARM架构下Harbor离线安装：企业级镜像仓库部署全解析

简介面向国产化ARM架构环境的Harbor v2.10.2离线安装包专门用于在信创或内网隔离环境中快速部署企业级容器镜像仓库Harbor本身提供镜像存储、复制、权限管理等能力是国产化替代项目中常用的基础组件。整套资源共6个文件以shell安装脚本、预处理脚本和Harbor镜像tar.gz包为核心前者负责安装流程与部署前检查后者内置完整镜像数据同时附带许可文件与配置文件模板压缩包整体约650.11MB可覆盖离线安装、初始化配置、服务启动全部环节。目前已有96人学习下载适合没有外网的生产环境或信创项目交付。借助该资源读者可省去自行编译和适配ARM平台的繁琐流程获得一套开箱即用的离线部署方案配置模板和脚本可帮助运维人员根据实际网络、存储、域名等参数快速调整后续升级维护与二次定制都更为方便整体设计以生产可用为目标。1. 拿到安装包的第一件事先看懂它在解决什么问题一堆人拿着harbor-offline-installer-aarch64-v2.10.2.tgz这个文件名第一反应就是“解压、执行 install.sh”。我建议你先别急先把这个文件名的每一段拆开看清楚。文件名本身就是一份技术说明书读懂了它后面至少能少踩 70% 的坑。先看harbor。这是 VMware 开源的企业级镜像仓库核心职责是存镜像、管镜像、分镜像。在 CI/CD 流程里它承担的是“制品仓库”这一环负责承接从构建流水线产出的容器镜像再提供给后续的部署环节拉取。有一点要注意Harbor 本身不负责构建镜像也不负责触发部署它主要做的是镜像的存储和分发控制例如基于项目的权限隔离、镜像签名校验、漏洞扫描等都是它的差异化能力。再看offline-installer。这个就实诚多了意味着安装包里面已经把所有需要的镜像文件都打进去了安装过程不依赖外部网络。对生产环境来说这点太要命了——很多机器在隔离网络里外网根本无法访问如果拿着在线安装脚本去执行会卡在拉镜像那一步死活过不去。接着是aarch64。这是 ARM 64 位架构对应服务器常见的有华为鲲鹏、飞腾、Ampere Altra 这些。很多刚接触 ARM 服务器的人习惯直接去 Docker Hub 拉 x86_64 的镜像结果exec format error报错其实就是架构不对镜像里的二进制指令跟 CPU 指令集不匹配等于让一个说汉语的人去读一份只写英文的说明书系统自然没法执行。最后是v2.10.2。这是 Harbor 的版本号。这里有个小知识点Harbor 版本和部分组件版本之间有依赖关系什么版本对应什么特性和 bug 修复跟自己的实际业务量要匹配。比如 2.10.x 是较新的稳定分支在权限管理、配额统计、审计日志这些方面都做了不少增强而 2.10.2 通常是该分支上的补丁版本属于可以直接投入生产的版本。tgz后缀就不用说了这是打包压缩格式解压命令十有八九是tar -xvzf。到这里你大概能看明白了这份安装包解决的是ARM 架构 离线网络环境下部署一套企业级镜像仓库的问题。适合谁用主要就是那些做信创适配、机房物理隔离或者对网络有强管控要求的团队。你不需要连 Docker Hub不需要配代理一把内网机器就能把整套仓库跑起来。我在实际操作中还有一个额外关注点包名里的aarch64只是系统层架构并不代表里面所有组件镜像都能直接在你的系统上跑。它还要求宿主机内核具备相应的运行条件简单说就是内核架构、动态链接库环境都得匹配。要是底层系统是 32 位的 userland或者内核太老这个包依然跑不起来。所以建议拿到包后先跑一句uname -m确认输出aarch64再往下走。2. 安装前的准备一次性避掉 80% 的坑2.1 操作系统与内核版本确认拿到离线包后第一件事不是解压而是确认主机环境。Harbor 官方对操作系统的要求一般会写明支持的主流 Linux 发行版例如 Ubuntu、CentOS、Rocky Linux 等但是在 ARM 平台上不同发行版对 aarch64 的支持程度略有差异。我见过有人拿一个很老的 CentOS 7.4 去跑装到一半发现内核的某些配置项不满足要求最后只能重装系统相当折腾。安装前务必确认以下几条操作系统架构执行uname -m必须输出aarch64。内核版本建议不低于 4.15。系统里执行uname -r可以查看。Harbor 依赖内核的网络、存储和命名空间能力版本太旧会莫名其妙地报错例如网络丢包、存储挂载异常等。系统时间必须保证时区和时间准确否则后面镜像签名校验、日志时间记录会出偏差有时还会导致证书校验失败。建议安装ntpdate或chrony做时间同步。防火墙和 SELinuxHarbor 默认监听 80 和 443 端口。如果系统开了 firewalld需要放行这两个端口SELinux 如果处于 enforcing 状态很可能导致容器挂载目录访问受限Harbor 容器起不来或读写失败。建议先把 SELinux 设为 permissive或者按照官方文档给相关目录打上正确标签。这些小检查每条基本就一条命令的事加起来耗不了三分钟但能帮你省掉后面几个小时的排查时间。2.2 Docker 和 Docker Compose 的版本匹配Harbor 安装脚本依赖 Docker 和 Docker Compose。这步里面坑很多我重点说。Docker 版本太老有些 API 接口跟安装脚本预期不匹配容易导致容器创建失败版本太新某些默认行为变化也可能影响 Harbor 启动。一般来说Harbor 2.10 要求 Docker Engine 版本相对较新建议用 20.10 以上的稳定版本。ARM 机器上安装 Docker直接用官方二进制包或者发行版自带的软件源都行但切记不要混装多个来源的 Docker否则会有二进制冲突。Docker Compose 更要留意。Harbor 的安装脚本底层依赖docker-compose命令来拉起和编排所有服务容器。如果你用的是新版 Docker 内置的docker compose插件并且系统里没有单独安装docker-compose脚本很可能直接报错找不到命令。我建议在 ARM 机器上单独安装一个 docker-compose 二进制文件放到/usr/local/bin/docker-compose并赋予执行权限。版本建议与 Harbor 官方文档保持一致一般选 v2 系列较新的版本即可。安装完成后执行docker-compose --version验证一下输出正常的版本号再继续。另外交代一句Docker 的存储驱动也需要注意。aarch64 平台某些系统默认文件系统是 overlay2 没问题但也有个别情况使用 btrfs 或直接裸设备这会导致镜像层存储异常。建议数据盘用 ext4 或 xfs并确认 Docker 的>cd /opt/install tar -xvzf harbor-offline-installer-aarch64-v2.10.2.tgz解压后目录下面会有一个harbor文件夹里面关键文件包括harbor.yml.tmpl配置模板安装前要复制为harbor.yml并修改。install.sh一键安装脚本负责加载镜像、生成配置、启动容器。common.sh公共函数库安装脚本会依赖它做环境检查和变量处理。harbor.v2.10.2.tar.gz离线镜像包包含 Harbor 所有组件镜像。LICENSE和README.md说明文件。这里面install.sh是主入口。它做的大致事情是检查环境变量、加载离线镜像包到本地 Docker、基于harbor.yml生成 docker-compose 文件、启动所有 Harbor 组件容器。理解这个流程后你遇到问题才知道去哪个环节排查而不是一头扎进容器日志里。3.2 harbor.yml 的核心配置项复制模板并编辑配置文件cd harbor cp harbor.yml.tmpl harbor.yml vim harbor.yml配置文件里有几个项目需要重点关照。第一个是hostname。这个字段决定了你通过哪个地址访问 Harbor。如果只在本机测试可以用 IP比如192.168.1.10。如果打算配置域名那就写域名。这里有个常见误区如果把hostname写成了localhost或者127.0.0.1外部机器访问时会有各种问题因为 Harbor 内部生成的访问地址、推送地址都基于这个字段。所以建议直接填写该机器的内网 IP 或规划好的域名。第二个是harbor_admin_password。这是 Harbor 管理员初始密码默认是Harbor12345。既然是生产环境务必改掉并且注意密码长度和复杂度要求太简单可能导致后续 Web 页面登录报错或者安全审计过不了。第三个是http.port和https.port相关配置。如果不需要 HTTPS可以把https相关段落注释掉只保留 HTTP。如果你对安全有要求配置证书需要提供证书路径和私钥路径支持 PEM 格式。这块我在测试环境一般先用 HTTP等内网域名和证书定了再切 HTTPS。不过切 HTTPS 时要注意改完配置后要重新执行install.sh或./docker-compose重启组件同时客户端机器的 Docker 需要信任该证书否则docker login时会报证书校验失败。常见的做法是把 CA 证书添加到客户端/etc/docker/certs.d/harbor地址/目录下或者将根证书加入系统信任库然后再重启 Docker 服务。第四个是数据卷目录。data_volume字段默认是/data。如果按之前规划的这里改为/data/harbor。还有一个我每次都会顺手改的地方log配置段。默认日志按天切割保留 7 天我一般会调大保留周期比如 30 天方便回溯问题。但要注意log段仅配置容器内部日志的收集和切割策略不涉及 Docker 本身的日志驱动不要误以为改这里会影响 Docker daemon 的日志行为。3.3 执行 install.sh 的完整过程配置没问题后执行sudo ./install.sh脚本开始运行后会先检查环境例如 Docker 服务是否运行、docker-compose 版本是否契合、端口是否被占用。接着会执行镜像导入。这一步耗时最长通常取决于离线包的大小和磁盘写入速度。如果这块卡住不动先确认磁盘 IO 是否正常比如用iostat观察一下也可能是磁盘空间不足导致写入失败。导入完成后脚本会基于harbor.yml生成docker-compose.yml然后后台启动全部组件。整个启动过程可以用docker ps观察容器状态。正常情况下你会看到这些组件nginx反向代理入口registry镜像存储服务registryctlregistry 管理控制器coreHarbor 核心 APIjobservice异步任务处理postgresql数据库redis缓存与任务队列trivy-adapter漏洞扫描组件如果启用exporter监控指标导出如果启用全部容器显示Up之后浏览器访问你在hostname里配置的地址就能看到 Harbor 的登录页面。用配置里设置的管理员账号密码登录进到界面后第一件事是创建一个新项目然后在客户端机器上登录并推送一个测试镜像验证整个链路是否通畅。3.4 客户端推送镜像的验证命令服务端起来后找一台能访问到 Harbor 的客户端机器验证一下。比如给 Harbor 配了一个项目叫test本地镜像叫myapp:v1需要先给镜像打标签再推过去docker tag myapp:v1 192.168.1.10/test/myapp:v1 docker login 192.168.1.10 docker push 192.168.1.10/test/myapp:v1如果你的 Harbor 只配了 HTTP 没有加 HTTPS 信任客户端 Docker 会默认拒绝以非 HTTPS 方式登录。解决办法是编辑/etc/docker/daemon.json添加insecure-registries: [192.168.1.10]然后重启 Docker。这个问题几乎每个团队都会遇到一次顺手记下来能省不少事。推送成功后在 Harbor Web 界面里刷新能看到test/myapp:v1这个镜像已经出现了。到这里基础安装和验证流程算是跑通了。4. 安装后验证与日常维护4.1 健康检查和日志查看Harbor 装完不是就算完了。日常维护中需要关注几项指标容器状态、磁盘占用、API 响应。快速检查容器状态用一句命令docker ps --format table {{.Names}}\t{{.Status}}看所有容器是否都是Up状态。如果有容器反复重启优先查看对应容器的日志例如docker logs -f harbor-coreharbor-core是核心服务大多数 API 层面的问题都会在这里留下日志。如果是网络层面问题先去查harbor-proxynginx的日志。如果是镜像推送失败优先看harbor-registry的日志。Harbor 自带的 API 也提供了健康检查接口。比如curl -k https://harbor地址/api/v2.0/ping如果返回Pong之类的结果说明整体服务是可用的。这个接口非常轻量适合做定时探活。磁盘空间监控也不能落下。Harbor 的数据目录增长很快我建议做个简单的 cron 脚本定期检查/data/harbor目录的使用率超过阈值就告警。不然等你发现推送镜像失败往往数据盘已经满了。4.2 常见问题排查速查表总结一下我在 ARM 离线部署中遇到的典型问题整理成一张排查表方便你直接对应处理。现象可能原因解决思路安装脚本报command not found: docker-compose未安装 docker-compose 或不在 PATH 中下载对应架构的二进制并放到/usr/local/bin赋予执行权限容器反复重启harbor-core日志报数据库连接失败PostgreSQL 容器还没完全启动或数据目录权限不对先查看harbor-db日志确认数据库初始化完成同时检查数据目录属主是否为 999页面访问不了curl 返回 502nginx 容器或 core 容器未正常启动逐个容器查看状态和日志重点关注监听端口是否被占用客户端docker login报证书错误Harbor 使用自签证书客户端未信任按前面提到的方法配置 insecure-registries 或导入证书推送镜像时提示403 Forbidden没有权限推送到该项目检查用户是否已被加入项目成员并且有推送权限镜像推送到一半突然断开日志提示磁盘空间不足数据盘满了清理冗余镜像、执行 GC或者扩容磁盘ARM 机器启动镜像报exec format error镜像架构与宿主机不一致在 Dockerfile 里重新构建 aarch64 镜像或者直接拉取 arm64 版本还有一个容易被忽略的细节Harbor 的 GC 机制。所谓垃圾回收是指清理那些无引用的镜像层文件。当你在 Web 界面删除镜像后存储层并不会立即释放空间需要手动执行 GC垃圾回收。访问接口路径一般是https://harbor地址/api/v2.0/system/gc或者通过 Web 页面左侧的“垃圾回收”功能触发。GC 会开启一个异步任务跑完后才能真正释放一部分空间。这个机制跟在页面上删没删干净没有关系是 Harbor 的存储设计决定的。我见过有人删了一堆旧镜像一看磁盘没变化以为没删掉其实是没有执行 GC。GC 执行期间会占用较多系统资源建议在业务低峰期操作并且要观察任务执行结果避免中间异常导致部分镜像层无法清理。5. 经验杂谈与扩展建议整套 ARM 离线部署走下来说句实话最耗时间的往往不是安装本身而是环境适配。你下载的离线包虽然是 aarch64 版本但底层操作系统、内核模块、Docker 版本之间仍然存在微妙的兼容关系。如果一次没跑起来不要急着怀疑安装包有问题先回头核对操作系统和基础组件的版本。此外如果你的团队有持续交付平台比如 Jenkins、GitLab CI 这类工具Harbor 装好后可以顺势接入。构建服务器在推送镜像前先调用 Harbor API 获取凭证再把镜像推送到指定项目后续部署流水线从 Harbor 拉取镜像整个链路就能串起来。Harbor 的 API 也支持管理项目、用户、机器人账号以及镜像仓库的配置熟练使用之后不仅能提升效率也可以减少人工登录和密码泄露的风险。我在实际操作中还有一个深刻的体会别忘了定期备份 Harbor 数据库和配置文件。Harbor 的镜像数据可以通过重新同步恢复但数据库里存了项目和用户的元数据如果不小心损坏恢复起来比较麻烦。你可以规划一个周期性的备份策略把/data/harbor/database目录和harbor.yml一起打包归档。没有备份的情况下一旦服务器磁盘故障相当于整个仓库的所有记录一夜归零。这个教训我印象很深所以建议所有使用 Harbor 的团队都把备份当成上线前的必做事项。本文还有配套的精品资源点击获取