简介面向麒麟V10与ARM64架构的Harbor v2.4.0镜像仓库离线部署资源包专为信创环境中的运维工程师、DevOps及容器平台建设者准备可解决内网环境下无法在线拉取镜像依赖、缺少ARM64适配安装包、Docker与Kubernetes集成难等实际问题适用于国产化替代与私有化交付场景。资源共8个文件以shell部署脚本安装执行、证书生成、Harbor离线安装主包gz、docker-compose编排模板yml为核心另含license授权、prepare环境校验、tmpl模板等配套内容覆盖安装前检查、编排配置、安全证书与自定义参数等环节整体约407MB。目前已有315人学习下载。借助该资源读者可快速获得适配aarch64架构的完整离线安装组件、自动化安装脚本、配置模板及校验工具避免自行编译适配的繁琐过程有效降低Harbor在国产化平台上的部署门槛同时目录结构清晰便于对照相关博文逐项理解安装逻辑为后续对接K8s、管理镜像生命周期打下坚实基础。1. 麒麟V10 ARM64 部署 Harbor v2.4.0先打破「照搬 x86 教程」的幻想在一台麒麟V10 ARM64 服务器上部署 Harbor v2.4.0 镜像仓库难度并不在 Harbor 本身而在「架构」和「生态」两层错位。Harbor 的官方离线包长期以来以 x86_64 为主ARM64 往往要在安装前先把镜像一件件拉下来、核对架构后再重新导出而麒麟V10 的默认软件源里docker、docker-compose 的版本又常常停留在让你一启动就翻车的水平。所以这篇笔记的核心任务就是用一条可复现的路径把 ARM64 架构下的镜像准备、harbor.yml 配置、启动验证和常见故障一次性讲透——适合准备在国产化环境或 ARM 服务器上搭私有仓库的运维和开发同学。2. 部署前的地基麒麟V10 ARM64 与 Harbor v2.4.0 的选型匹配2.1 麒麟V10 ARM64 上先确认的四个基础事实动手之前先把机器情况摸清楚。很多翻车不是 Harbor 的锅而是基础环境不自洽。uname -a cat /etc/os-release docker version --format {{.Server.Os}}/{{.Server.Arch}} docker-compose version这四条命令分别确认内核版本、麒麟V10 的发行版本、docker 服务端架构、docker-compose 版本。这里有个重点docker version 输出的是 Server 的架构不是 Client。如果你只在客户端装了个 amd64 的二进制Server 的 Arch 依旧是 aarch64。这种「看着对、跑起来不对」的情况非常玄学实际上是不小心装错了包。麒麟V10 的 /etc/os-release 通常会写类似 V10 (Tercel) 的代号这决定后续用哪个 yum 源。docker 的存在方式有两种一种是通过麒麟自带的仓库装的 docker-engine另一种是手动装的 docker-ce两种共存时会各自拉出 daemon端口冲突很正常。装之前先看看systemctl status docker确认当前只有一个 docker 服务在跑并记录下它的启动参数再往后走。2.2 为什么选 v2.4.0组件依赖与 ARM64 兼容性Harbor v2.4.0 是比较适合 ARM64 的候选版本因为它的组件结构相对克制。整个 Harbor 由 nginx、core、jobservice、registry、registryctl、portal、postgresql、redis、trivy-adapter 等容器组成v2.4.0 的镜像基于 photon OS多架构构建已经趋于稳定不像早期版本那样几乎只有 amd64 可用。容器组件职责ARM64 注意点nginx入口反向代理分发 API 与镜像流量默认端口 80被占用时改 harbor.ymlharbor-core认证、项目管理、API 核心逻辑无特殊jobservice复制、GC、扫描任务调度无特殊registry镜像存储核心是 Docker Distribution存储驱动建议保持 filesystemregistryctlregistry 配置控制面无特殊portalWeb 前端无特殊postgresql元数据库存项目/用户/标签数据默认落在 data_volume/databaseredis缓存与任务队列v2.4.0 以容器方式部署trivy-adapter漏洞扫描ARM64 下首次同步漏洞库容易超时建议后置上表的实用价值在于排障定位容器反复重启时先判断它是哪个组件再决定看哪份日志。比如登录不了大概率是 core 或 db 的问题页面打不开先看 nginx推送镜像超时重点查 registry 和磁盘。2.3 离线包与在线脚本先想清楚走哪条路Harbor 的安装方式主要有两条路一是harbor-offline-installer-v2.4.0.tgz离线包解压后自带镜像 tar二是install.sh在线脚本它在没有找到本地 tar 时会尝试从镜像站拉取。在内网环境里离线包是首选因为它不依赖外网连通性。但 ARM64 下有一个必须认清的边界官方离线包里的镜像 tar 是什么架构取决于你从哪台机器拉取的镜像。如果你把 x86 服务器上导出的 Harbor 镜像 tar 拿到 ARM64 机器上 loadload 过程会顺利通过因为 tar 解析不校验架构可一旦 docker run 起来立刻报exec format error。所以我通常的建议是不要盲目下载网上现成的离线包而是在 ARM64 机器上自组离线包。这个操作不难而且能把每张镜像的架构确定性握在自己手里。3. 拿到 ARM64 镜像离线包的自助重组与架构校验3.1 官方离线包的边界什么情况能直接用如果你的生产环境真的拿到了一个「声称是 ARM64」的官方离线包怎么快速判断它能不能用两步解压后先看harbor.v2.4.0.tar.gz里的镜像架构再决定是否加载。但实际踩过坑之后我的习惯是放弃判断直接自组一份。原因很简单官方离线包针对不同架构的发布节奏不一致与其花时间验证包的可信度不如自己拉一次镜像。自组离线包的前提是有一台 ARM64 架构的机器并且这台机器能访问镜像站。如果你的所有 ARM64 机器都在内网那就需要先在一台临时开通了外网访问权限的 ARM64 机器上完成拉取和导出再用移动介质把 tar 传进内网。整个过程跟普通离线包的使用体验一致后面没有任何区别。3.2 在 ARM64 机器上组装离线包拉取、导出、合并以下命令在 ARM64 机器上执行把 Harbor 默认组件镜像一次性拉下来并合并导出一个 tar 文件。mkdir -p /opt/harbor-images cd /opt/harbor-images REGISTRY_NSgoharbor for img in harbor-core:v2.4.0 harbor-jobservice:v2.4.0 \ harbor-portal:v2.4.0 harbor-registryctl:v2.4.0 \ registry-photon:v2.4.0 nginx-photon:v2.4.0 \ harbor-db:v2.4.0 redis-photon:v2.4.0 harbor-log:v2.4.0; do docker pull ${REGISTRY_NS}/${img} done docker save \ goharbor/harbor-core:v2.4.0 goharbor/harbor-jobservice:v2.4.0 \ goharbor/harbor-portal:v2.4.0 goharbor/harbor-registryctl:v2.4.0 \ goharbor/registry-photon:v2.4.0 goharbor/nginx-photon:v2.4.0 \ goharbor/harbor-db:v2.4.0 goharbor/redis-photon:v2.4.0 \ goharbor/harbor-log:v2.4.0 \ -o /opt/harbor-images/harbor-arm64-images.tar这段代码的逻辑先把 Harbor 依赖的九张镜像逐一拉取下来然后合并导出为一个 tar。拉取命名空间固定为goharbor版本 tag 全部锁定v2.4.0防止镜像漂移带来的不一致。参数说明docker save -o指定输出文件多个镜像写在一行里会合并成一个 tar复制内网时只传一个文件降低出错的概率。这里故意没有加入trivy-adapter-photon:v2.4.0。如果初装阶段不打算启用漏洞扫描就不需要这张镜像如果后面要加单独docker pull goharbor/trivy-adapter-photon:v2.4.0并追加到 save 列表里即可。3.3 用三条命令验证镜像架构镜像导出前先确认每张镜像确实是 arm64避免把问题带到内网。uname -m docker image inspect goharbor/harbor-core:v2.4.0 --format {{.Architecture}} docker image inspect goharbor/harbor-core:v2.4.0 --format {{.Os}}第一条看宿主机的 CPU 架构ARM64 下输出是aarch64。第二条看镜像的 CPU 架构期望输出arm64。第三条看镜像的操作系统类型期望linux。如果 inspect 结果显示amd64说明这张镜像是在 x86 机器上拉取的必须重新拉。提示docker load不校验架构docker run才校验。这是整个镜像架构问题里最迷惑人的环节——tar 能加载进去不代表容器能跑起来。所以自组包校验的环节别跳过。4. 配置 harbor.yml 并启动六个必改项与执行顺序4.1 从模板到可用配置六个必改项把上一章导出的 tar 拷到目标机器后先导入镜像再解压安装包并生成配置docker load -i /opt/harbor-images/harbor-arm64-images.tar tar -xzvf harbor-offline-installer-v2.4.0.tgz cd harbor cp harbor.yml.tmpl harbor.ymlHarbor 的配置入口只有一个harbor.yml改完再执行 install.sh。我每次部署都固定检查以下六处hostname: 192.168.10.20 http: port: 8080 harbor_admin_password: YourStrongPass2024 database: password: YourDBPass2024 data_volume: /data/harbor log: level: info第一处hostname写成实际 IP 或域名不要写 localhost否则从别的机器访问时会全部指向本机。第二处http.port默认 80但麒麟V10 上常有别的 web 服务占用 80改成 8080 后后续 docker login 都要写成192.168.10.20:8080这样的完整地址。第三处harbor_admin_password默认是 Harbor12345首次登录前必须改。第四处database.password这是 postgres 的密码默认值很容易被扫描工具探测生产环境必须改。第五处data_volume默认 /data建议改成独立数据盘挂载点比如 /data/harbor避免镜像数据和系统盘抢空间导致磁盘写满。第六处log.level平时用 info排障时临时改 debug排查完一定要改回。这里特别提醒一点如果你没有准备 trivy 镜像就不要在 harbor.yml 里启用相关配置install.sh 检测到配置里声明了组件但镜像不存在时安装过程会在启动阶段失败。4.2 执行 install.sh参数选择与安装过程的关键输出镜像导入、配置改完就可以执行安装了。./install.sh不带任何参数是最小化安装只起 core 组件加 registry、db、redis、nginx、portal、log这个组合最稳定适合先搭起来再扩展。如果你确定需要 Helm Chart 管理功能加--with-chartmuseum确定需要漏洞扫描加--with-trivy。ARM64 下我对这两个参数的态度是chartmuseum 可以用trivy 优先不加原因在第 5 章里展开。install.sh 执行时脚本会先检查 docker 与 docker-compose 是否可用然后校验 harbor.yml 格式最后调用 docker-compose 启动。全程盯住两个东西有没有 ERROR 字样docker-compose 阶段有没有报配置解析错误。很多人习惯执行完就切走等回来发现容器全没起来还得回头翻日志白白浪费时间。4.3 启动后第一轮检查容器、端口、日志启动完成后按下面的顺序做第一轮检查docker ps --format table {{.Names}}\t{{.Status}} curl -k https://127.0.0.1:8080/api/v2.0/ping第一条看所有 Harbor 相关容器是否都在 Up 状态第二条确认 API 是否响应。注意这里用了 8080因为你刚把 http.port 改成了 8080如果保持默认 80就把端口换回去。如果某个容器反复重启用docker logs 容器名单独看输出这是定位问题最快的路径。5. 麒麟V10 ARM64 部署 Harbor 的踩坑记录五个高频事故现场5.1 docker-compose 版本太老导致配置解析直接失败现象./install.sh跑到 docker-compose 阶段直接报类似Version in ./docker-compose.yml is unsupported或 yaml 解析错误进程秒退。原因系统自带的 docker-compose 版本太老解析器认不出新版模板里的语法。这种情况在麒麟V10 上尤其常见自带软件源的 compose 往往停留在很旧的版本。解决把 docker-compose 升级到新版本去官方 release 页拿对应平台 aarch64 的二进制放到 /usr/local/bin/docker-compose 并加执行权限然后重跑 install.sh。这是整个部署流程里最容易踩的坑也是第一个要先解决的。5.2 镜像架构不匹配manifest unknown 与 exec format error现象容器起不来docker logs 里出现exec user process caused: exec format error或者拉取镜像时报manifest unknown。原因镜像平台是 amd64跑在 aarch64 上。常见来源是团队里有人从 x86 机器上导出了镜像传到 ARM 机器上用load 成功但 run 失败。解决回到第 3 章的架构校验流程重新在 ARM64 机器上拉取镜像并打包。血泪经验是load 不检查架构run 才检查。所以「能 load 不代表能用」这个问题第一次遇到时最容易迷惑人。5.3 trivy 漏洞扫描器更新失败别在内网死磕这个组件现象加了--with-trivy启动后trivy-adapter 容器日志里反复出现漏洞库同步失败定时任务一直重试。原因内网环境访问公共漏洞库超时或不通再加上 ARM64 的漏洞库同步链路本身就比 x86 慢。解决初装阶段先不要启用 trivy用最小化模式把仓库跑稳。等仓库已经承载业务了再把 trivy 部署到能访问漏洞库且网络质量好的节点上或者设计离线同步方案。我的原则是不要在内网环境死磕 trivy 的首次同步它不是一个「多等等就能好」的问题。5.4 harbor.yml 改了没生效旧配置残留的坑现象改了端口或 hostname重新执行 install.sh 之后访问还是旧配置。原因Harbor 的 config 目录里保留了旧配置install.sh 在部分场景下不会重建全部配置尤其是 nginx 的配置没有重新生成。解决初次部署阶段最稳妥的做法是docker-compose down -v后重新 install。注意-v会删数据卷首次部署没有业务数据时可以用如果已经有数据就备份 data_volume再重来。另一个常见误操作是只改 harbor.yml 不重跑 install.sh那必然不生效这一点要形成肌肉记忆。5.5 麒麟V10 防火墙与 SELinux 拦路本机能通、外网不通现象在本机 curl 127.0.0.1 一切正常从另一台机器访问 IP 却打不开页面。原因firewalld 没放行端口或者 SELinux 拦截了 nginx 容器对外访问。解决firewall-cmd --zonepublic --add-port8080/tcp --permanent firewall-cmd --reload getenforce setsebool -P httpd_can_network_connect 1前两条把 8080 端口写进防火墙持久规则并重载。第三条先确认 SELinux 状态如果输出是 Disabled第四条直接跳过如果是 Enforcing执行第四条放行 nginx 的网络连接。注意这个 setsebool 是全局开关对容器网络访问有效执行完再刷新页面看效果。6. 部署后的验证闭环从 docker login 到长稳自检6.1 三条命令验证仓库可读写部署完成不等于交付完成。我每次都会跑一遍完整的读写链路docker login 192.168.10.20:8080 -u admin -p YourStrongPass2024 docker tag busybox:latest 192.168.10.20:8080/library/smoke-test:arm64 docker push 192.168.10.20:8080/library/smoke-test:arm64第一条验证认证链路第二条验证镜像打标签第三条验证镜像上行写入。推完之后再找一台干净的节点docker pull一次能拉回来才算完整闭环。这里的 busybox 换成任意一个 arm64 的小镜像即可目的只是冒烟测试不占多少磁盘。提示如果 Harbor 用的是 HTTP 或自签名证书每台要访问仓库的 Docker 节点都需要在 /etc/docker/daemon.json 里添加insecure-registries: [192.168.10.20:8080]然后重启 docker。不配置的话login 会直接报证书错误。这是 Harbor 部署后最常被问到的后续操作。6.2 通过 API 确认组件健康状态读写链路通了之后再用 API 看一眼整体状态curl -k -u admin:YourStrongPass2024 https://192.168.10.20:8080/api/v2.0/health curl -k https://192.168.10.20:8080/api/v2.0/systeminfohealth 接口返回各组件的健康状态systeminfo 返回版本和存储信息。这两条命令的价值在于它们验证的是 core 与 db 之间的连接而不仅仅是 nginx 通不通。很多「页面能打开但登录后报错」的问题就是 core 连不上数据库这个场景用 API 一眼就能看出来。6.3 长期维护的习惯磁盘、备份与配置快照处理完初装后面真正考验人的是维护。我的习惯是建立两个固定动作。第一每周看一次磁盘占用重点是 data_volume 下的 database 和 registry 目录镜像仓库是个磁盘黑洞GC 只清理不活跃的镜像层不解决增长问题。第二每次升级前把 harbor.yml、docker-compose.yml、data_volume 下的关键配置目录一起打包备份数据库用容器自带的 dump 工具导一份元数据。这样即使版本回退也有后悔药可吃。我自己吃过一次亏升级时没有备份配置结果新版本起不来旧版本也被覆盖最后重新配了一遍才恢复。从那以后配置快照成了每次操作的固定前置动作。希望这篇笔记能帮你在自己的环境里少踩几个坑把 Harbor 真正用起来。本文还有配套的精品资源点击获取
