简介面向在麒麟V10与ARM64架构下部署容器镜像仓库的运维及开发人员这套资源提供了完整的Harbor v2.4.0离线安装方案。压缩包内含离线安装主程序、Harbor镜像压缩包以及环境准备、证书生成、安装启动等多类shell脚本并配有可自定义的配置模板和使用许可文件支持docker-compose编排启动可解决国产化平台上依赖获取难、手动配置易出错的问题同时为Kubernetes集群提供稳定的镜像存储与分发能力。包体共8个文件以shell脚本、YAML配置与gz压缩包为主总大小约407MB各脚本与模板职责划分明确便于按实际网络环境调整参数。目前已有314人学习下载适合掌握Docker及docker-compose基本操作并希望深入ARM环境部署的读者。利用这份资源读者可以按序完成从系统环境预检、证书签发、配置文件调整到服务初始化的完整部署同时能借助其中的自动脚本沉淀一套可复用的国产化Harbor安装流程节省大量排错与编译时间。1. 为什么在麒麟 V10 ARM64 上Harbor v2.4.0 是镜像仓库的首选落地姿势在一台华为泰山 200 这类 ARM 服务器上系统是银河麒麟 V10 服务器版装完操作系统后第一件事往往是“怎么把生产环境的容器镜像管起来”。这时候照着 x86 教程走几乎每一步都碰壁下载的 Harbor 离线包不识别、Docker 装不上、拉镜像报 no matching manifest甚至软件源里的版本只能跑通 hello-world。这篇笔记把基于麒麟 V10 ARM64 架构部署 harbor v2.4.0 镜像仓库工具这条链路拆到底先看架构边界再给离线可行的安装步骤最后把信创环境里最容易翻车的坑和验证手段全部说清楚。适合正在做信创适配、内网无外网环境、手上只有 ARM 机器的朋友也适合刚从 x86 迁移过来、想少走弯路的运维同事。2. 先探底 ARM64麒麟 V10 能不能托住 Harbor关键看这几点2.1 用三条命令确认机器真 ARM64而不是“看起来像”在实际部署时我遇到过把 x86 镜像包硬塞进 ARM 机器的例子也遇到过 ARMv7 当作 ARM64 的案例。开始装 Harbor 之前先把机器身份确认清楚避免后续所有报错都指向同一个错误前提。三条命令足够uname -m cat /etc/os-release lscpu | grep -E Architecture|CPU op-modeuname -m输出aarch64才是 ARM64出现armv8l反而要警惕那通常意味着内核或用户态工作在 32 位兼容模式。cat /etc/os-release确认系统确实是麒麟 V10重点看 VERSION 字段是 SP1 还是 SP2不同服务包内核对 Docker 和 Harbor 的支持度会有细微差别。lscpu里 Architecture 是aarch64、CPU op-mode 同时列出32-bit, 64-bit说明硬件和内核都支持 64 位操作系统。确认无误后后面下载包、拉镜像才谈得上“按架构选”否则一切安装动作都是白费。同一台机器上如果还打算部署 mysql 5.7 arm64 这类国产化数据库也建议先跑一次ldd --version确认 glibc 版本Harbor 的组件镜像多数基于 sle/ubuntu 基础镜像运行宿主机 glibc 版本太低时容器内程序虽然不受影响但 docker 自身的 runc、containerd 会依赖较新的 libseccomp所以 glibc 版本这一步宁可多花一分钟确认也不要等到启动 Docker 时报version GLIBC_2.28 not found再回头查。2.2 Harbor v2.4.0 在 ARM64 上的兼容边界在哪里Harbor 本身是 CNCF 下的开源项目从 v2.0 开始官方就发布了多架构镜像。v2.4.0 这个版本在信创项目里被大量使用原因是它和 ARM64 的匹配度已经足够成熟核心组件 registry、core、portal、database、redis 都做了 arm64 的 manifest。但有两个容易忽略的点一是离线包里的 trivy 漏洞扫描组件在 v2.4.0 的 arm64 清单里有时不完整二是 chartmuseum 组件在离线环境下偶尔会拉不到 arm64 仓库镜像。所以在解压离线包之后先做一次架构审查别急着执行 install.sh。tar tzf harbor-offline-installer-v2.4.0.tgz | head -30 docker manifest inspect --verbose goharbor/harbor-core:v2.4.0 | grep platform第一条命令看离线包结构harbor.yml.tmpl、镜像 tar 包等关键文件是否齐全。第二条命令直接对 harbor-core 做 manifest 审查输出里 platform 部分能看到architecture: arm64还是amd64。如果 offline installer 里所有镜像都带 arm64 清单直接走离线安装如果某个组件只有 amd64就需要从公共仓库单独拉 arm64 版本再改 tag或者干脆不开--with-trivy/--with-chartmuseum只把 Harbor 当作纯镜像仓库用这样组件最少、问题面也最小。这里顺便说明一下为什么选择 v2.4.0 而不是更新的版本。Harbor v2.5 虽然也支持 ARM64但 x86 生态里常用的很多 CI/CD 工具链在 v2.4.0 上验证得最充分信创环境里的甲方验收文档、等保测评要求里出现的也多是 v2.4.0 这个版本号。技术选型不是越新越好而是要选“在这个操作系统和架构组合下被验证次数最多”的版本。2.3 没有真 ARM 机器时用 qemu 模拟 arm64 做预验证如果手头暂时只有 x86 机器想先跑一遍 Harbor 安装流程可以用 qemu 系统级模拟 arm64 环境提前踩坑。常见做法是准备一个 arm64 的 Ubuntu 或麒麟镜像用qemu-system-aarch64配合-M virt机型启动qemu-system-aarch64 -M virt -cpu cortex-a57 -smp 4 -m 8192 \ -bios QEMU_EFI.fd \ -drive ifnone,filedisk.img,formatraw \ -device virtio-blk-device,drivehd \ -device virtio-net-device,netdevnet0 \ -netdev user,idnet0模拟环境的好处是可以在没有真实 ARM 硬件时提前验证 harbor-offline-installer 的包结构、harbor.yml 的语法、docker-compose 版本要求但性能、存储驱动和内核模块行为与真实 ARM 服务器差距很大。qemu 里虚拟的 virtio 磁盘和真实泰山服务器的 RAID 卡、SAS 磁盘行为完全不同所以预验证只能作为“安装步骤能不能走通”的参考不能作为生产环境性能依据。生产部署务必在真机上完成别把模拟器的验证结果直接当作验收数据。3. 在无网麒麟 V10 上离线装 Docker两条可行路径与三个必改参数3.1 路径一从麒麟软件源离线同步 rpm 包一次性装齐 docker 全家桶麒麟 V10 的软件源里自带 docker 相关 rpm 包版本虽然不是最新但胜在与系统 glibc、内核的耦合经过厂商验证。有网环境下先在镜像服务器上用dnf download把包下载到本地然后拷贝到内网机器上逐个安装这是最稳妥的离线路径。# 在能访问外网的麒麟机器上执行 dnf install --downloadonly --downloaddir/opt/docker-rpm docker \ docker-client docker-common containerd # 在内网麒麟 V10 上执行 cd /opt/docker-rpm rpm -ivh *.rpm --nodeps--nodeps是双刃剑离线环境下依赖链上的包如果没下载完整加上这个参数能强行装上但如果系统本身缺少 libseccomp 这类基础库运行 dockerd 时仍然会报错。我一般会先不用--nodeps装一遍报缺什么就从有网机器上把对应依赖 rpm 下载下来补齐实在补不齐再用--nodeps。装完执行systemctl enable --now docker然后docker info看输出里的 Storage Driver 和 Cgroup Driver确认后端存储不是空白的。3.2 路径二静态二进制方式彻底绕开 rpm 依赖地狱离线环境最怕的就是缺依赖而缺的依赖本身又依赖别的依赖一层层追下去非常耗时。如果麒麟自带源里的 docker 版本太旧或者 rpm 依赖互相打架可以直接下载 docker 官方静态二进制包解压后覆盖到系统目录再用 systemd 托管。这个方式在 ARM64 上完全适用因为官方静态包已经交叉编译好。tar xzf docker-20.10.24.tgz cp docker/* /usr/bin/ mkdir -p /etc/docker cat /etc/docker/daemon.json EOF { data-root: /data/docker, log-driver: json-file, log-opts: { max-size: 50m, max-file: 3 }, storage-driver: overlay2, iptables: false, exec-opts: [native.cgroupdriversystemd] } EOF动态二进制包路径依赖 libltdl 等库静态包则没有这个问题这也是它在无网环境下最省心的原因。exec-opts里强制使用 systemd 作为 cgroup 驱动是为了和后续 Harbor 的 docker-compose 行为对齐同时避免与麒麟系统自带的 cgroupfs 模式冲突。注意静态包不会安装 containerd 到系统目录所以还需要单独准备 containerd 的可执行文件通常解压到/usr/local/bin然后由 dockerd 通过--containerd参数找到它。3.3 三个必改参数data-root、log-opts、iptables改错一个都是坑>firewall-cmd --permanent --add-port80/tcp --add-port8080/tcp firewall-cmd --reload4. 部署 Harbor v2.4.0harbor.yml 配置细节与 ARM64 镜像选择4.1 下载离线包并确认架构别让下载环节成为第一个翻车点Harbor 官方 release 页对 v2.4.0 同时提供 x86_64 和 arm64 两个离线安装包命名上会区分架构。下载时第一眼就要确认手里的包对应uname -m的架构不要等到install.sh执行到一半才发现镜像全是 amd64。下载完成后先做架构审查再解压md5sum harbor-offline-installer-v2.4.0.tgz tar tzf harbor-offline-installer-v2.4.0.tgz | grep -E harbor|docker-compose如果tar tzf列出的是harbor/harbor.v2.4.0.tar.gz、harbor/harbor.yml.tmpl、install.sh这类常见结构说明包是完整的。接下来把包里的harbor.v2.4.0.tar.gz解压出来用docker load加载镜像然后对关键组件做 manifest 检查确认 arm64 清单存在。这一步相当于给后面的安装上一道保险。4.2 修改 harbor.ymlhostname、端口、密码和数据盘是关键从离线包解压出配置模板之后复制为harbor.yml并编辑。hostname务必改成本机内网 IP不要用默认的reg.mydomain.com内网环境通常没有 DNS 解析用 IP 最直接如果后续要对接 Kubernetes 集群这里可以是集群内可解析的服务名。hostname: 192.168.10.20 http: port: 8080 harbor_admin_password: YourStrongAdminPass123 data_volume: /data/harbor database: password: root123456 max_idle_conns: 50 max_open_conns: 100 log: level: info local: rotate_count: 20 rotate_size: 20Mhttp.port设成 8080 而不用默认 80是因为麒麟 V10 上经常有其他服务占着 80 端口比如内网代理或 nginx避免端口冲突。data_volume指到/data/harbor这里强调一下这个路径是 Harbor 存储镜像层、数据库文件的根目录必须和数据盘绑定并且所有子目录的属主要改成 10000:10000Harbor 容器默认以 UID 10000 运行权限不对会直接导致 push 镜像失败。database.password设置的是 Harbor 内部 postgres 数据库的密码虽然只在容器内通信但信创环境安全扫描会检查弱口令还是设一个符合要求的复杂密码。rotate_count和rotate_size是日志轮转参数这里 20M × 20 个文件是常见配置日志量再大也不会无限制增长。4.3 启动前检查与 install.sh 参数决策执行install.sh之前先确认 docker-compose 可用。Harbor v2.4.0 的 install.sh 脚本内部调用的是docker-compose命令麒麟 V10 默认不带这个命令需要单独准备 arm64 版本的 docker-compose 二进制并放到/usr/local/bin。这一步漏了install.sh 会在启动阶段直接报docker-compose: command not found。chmod x /usr/local/bin/docker-compose docker-compose --version cd /path/to/harbor sudo sh install.sh --with-trivy--with-trivy开启漏洞扫描组件--with-chartmuseum开启 Helm Chart 仓库支持。是否开启完全取决于业务需要只做容器镜像分发两个都不开镜像数量最少故障面最小要扫描镜像漏洞就加--with-trivy但注意 v2.4.0 的 trivy 镜像有时候在 arm64 下没有对应清单如果安装脚本在这一步失败最直接的解决办法是去掉这个参数重跑一次 install.sh先保证核心仓库能起来扫描能力后续再单独部署。Chartmuseum 在内网离线环境里意义不大我的经验是默认不开省去一个 java 组件的内存占用。install.sh 运行完毕后docker-compose ps应该能看到 8 个左右容器处于 Up 状态。访问http://192.168.10.20:8080用harbor_admin_password里设置的账号登录能看到完整的项目管理界面就说明 Harbor v2.4.0 已经在麒麟 V10 ARM64 上站住了。5. 避坑排查麒麟 V10 上 Harbor 最常翻车的 5 个场景5.1 拉取 Harbor 组件镜像报 no matching manifest for linux/arm64现象执行install.sh后docker 拉 goharbor 相关镜像时报no matching manifest for linux/arm64或者启动的容器在docker ps里看到镜像架构是 amd64。原因离线包里部分组件镜像只有 x86 的 manifest尤其是 trivy、chartmuseum 这类扩展组件另一种可能是离线包本身就是 x86 版本在 ARM 机器上硬跑。解决先用docker manifest inspect逐个确认组件的架构如果确实缺 arm64 清单就把对应组件关掉重跑install.sh如果只是个别镜像缺可以手动从公共仓库拉 arm64 镜像再重新docker tag但生产环境不推荐这种手工方式因为后续更新维护的复杂度会成倍增加。5.2 Harbor 页面打不开但容器状态全显示 Up现象docker-compose ps全部 Up端口也在监听但浏览器访问就是白屏或一直转圈。原因这种情况十有八九不是 Harbor 本身挂了而是宿主机上的日志或临时文件把 inode 占满了或者防火墙规则拦住了访问。麒麟 V10 的 /var/log 和 /tmp 如果不定期清理小分区很快就吃满。解决先df -h和df -i看磁盘空间与 inode空间满就清 docker 日志和 harbor 的/data/harbor/logs目录inode 满就删掉容器内产生的大量小文件比如 trivy 的漏洞数据库缓存。清完再重启 harbor页面通常就恢复了。5.3 push 镜像报 409 Conflict 或权限不足现象docker login 到 Harbor 成功但docker push到某个项目时服务端返回 409 Conflict或者提示 blob upload 失败。原因Harbor 的 registry 容器以 UID 10000 运行而/data/harbor下的 registry、database 目录属主如果不是 10000容器内进程无法写入。解决对数据根目录执行一次权限修复chown -R 10000:10000 /data/harbor然后重启 harbor。信创环境里如果数据盘是用 admin 用户手工挂载并创建的目录这一步几乎必做因为目录建立时的属主默认是 root 或者其他普通用户。5.4 自签证书配置后docker login 报 x509 certificate signed by unknown authority现象给 Harbor 配置了 HTTPS 之后客户端执行docker login报x509: certificate signed by unknown authority。原因docker 客户端不信任自签 CA。麒麟 V10 的 openssl 3.0 在生成证书时的-extfile语法和旧版本有细微差别常见的openssl req -extensions v3_ca方式在部分环境里不会把 SAN 正确写入证书导致证书连本机校验都过不去。解决用正确姿势生成带 SAN 的证书然后让 docker 客户端信任该 CAopenssl genrsa -out ca.key 4096 openssl req -new -x509 -days 3650 -key ca.key -out ca.crt -subj /CNHarbor-CA openssl req -newkey rsa:4096 -nodes -keyout server.key -out server.csr -subj /CN192.168.10.20 echo subjectAltNameIP:192.168.10.20 extfile.cnf openssl x509 -req -days 3650 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -extfile extfile.cnf关键在最后一步的-extfile extfile.cnfopenssl 3.0 对 SAN 的强制程度比旧版高不显式写 SAN证书校验直接失败。生成后拷贝到所有需要登录 Harbor 的客户机的/etc/docker/certs.d/192.168.10.20:8080/ca.crt重启 docker 再 login 就能通过。5.5 系统盘和数据盘同时增长占满两个分区现象部署时明明把data_volume和 docker 的>systemctl stop docker mv /var/lib/harbor/logs /data/docker-harbor-logs ln -s /data/docker-harbor-logs /var/lib/harbor/logs systemctl start docker同时建议在 crontab 里加一条脚本定期清理容器日志防止 json-file 日志堆积。磁盘巡检这种“日常小事”在信创环境里尤其重要因为很多光口机器根本没有接入统一监控全靠人工定期看df -h。6. 落地之后用 API 做健康体检用两条腿做离线镜像搬运Harbor 部署完成只是开始内网环境的日常维护核心是两件事确认 Harbor 还活着以及离线机器怎么把镜像搬进搬出。第一件事用 API 就能完成不需要打开浏览器curl -k https://192.168.10.20:8080/api/v2.0/health curl -k -u admin:YourPassword https://192.168.10.20:8080/api/v2.0/systeminfo第一个接口返回各组件状态第二个接口看存储总量和可用量。我在实际维护中会把这些命令写成一个 shell 脚本配合 cron 每天跑一次任何组件异常就报警比登录 web 页面肉眼检查靠谱得多。第二件事是镜像搬运。两台 ARM64 机器之间的镜像同步docker pulldocker tagdocker push的组合足够但要完整搬运镜像的 manifest 和所有层还想要跨仓库复制skopeo更方便skopeo copy --src-tls-verifyfalse \ docker://192.168.10.20:8080/library/nginx:1.24 \ docker://10.0.0.5:80/library/nginx:1.24skopeo 在无网环境里要先离线准备好 arm64 版本的二进制但它的优势是复制过程不经过本地 docker 存储不会额外消耗系统盘空间。如果设备上实在装不了 skopeo回到 docker save/load 的路子也完全可以docker pull 192.168.10.20:8080/library/nginx:1.24 docker save 192.168.10.20:8080/library/nginx:1.24 | gzip nginx-arm64.tgz导入端直接docker load nginx-arm64.tgz就能用。这条路径特别适合批次升级的场景把多个镜像合成一个大 tar 包一次拷贝比逐个 pull 快得多。最后说一个我自己踩过的教训某次机房断电后 Harbor 的容器没有全部自启动原因是 install.sh 生成的 docker-compose.yml 里部分服务没有配restart: always加上宿主机重启后 docker 服务还没完全就绪容器就停在 Exited 状态。后来我养成的习惯是安装完立刻检查一遍 compose 文件里的 restart 策略把核心服务统一改为restart: always同时把systemctl enable docker确认到位。这件事看起来小但在无人值守的国产化服务器上它就是决定整套镜像仓库在重启之后能不能自动恢复的开关。希望这些经验能在你的麒麟 V10 ARM64 部署路上帮到你少走几段弯路。本文还有配套的精品资源点击获取