arm64离线部署Harbor 2.13.1：信创环境私有镜像仓库搭建实战

简介这是一份面向 ARM 架构服务器环境的 Harbor 容器镜像仓库离线部署包对应 Harbor 2.13.1 版本适合在国产化平台、ARM 服务器或内网隔离环境中搭建私有镜像仓库的运维与开发人员使用。压缩包为 tgz 格式共包含 6 个文件整体约 513.28MB其中以 shell 脚本、gz 压缩包、license 授权文件、prepare 预处理文件及 tmpl 配置模板为主分别承担安装执行、镜像数据承载、许可声明与配置生成等职责可满足离线场景下从解压到初始化的完整流程。资源内已集成 Harbor 核心组件与安装脚本读者可据此在无外网条件下完成私有仓库的部署与验证省去逐一下载依赖的繁琐过程同时便于理解 ARM 环境下各组件的组织方式与配置模板结构。目前已有 414 人学习下载适合需要快速落地 ARM 版 Harbor 的技术人员参考使用。1. arm 环境离线部署 Harbor 2.13.1为什么这个 tgz 包值得你花时间在国产化替代和信创项目里arm64 服务器已经不是什么新鲜事但真正让人头疼的往往不是业务代码而是基础设施组件的离线安装。最近接手的一个项目客户环境是纯内网、无外网出口、CPU 是 arm 架构要求部署一套私有镜像仓库。手里只有一个文件harbor-offline-installer-v2.13.1-arm64.tgz。这个包解决的核心问题就一个——在没有外网、没有 x86 转译、没有包管理器的 arm 机器上把 Harbor 2.13.1 完整跑起来。它适合两类人一是做信创交付的一线实施二是需要在 arm 开发板上搭本地 registry 的嵌入式团队。下面把我踩过的路完整拆一遍包括参数怎么调、坑在哪、怎么验证。2. 拆包之前先搞懂Harbor 离线包在 arm 上到底装了什么2.1 离线包与在线安装的本质区别在线安装 Harbor 时install.sh会调用 docker pull 从 Docker Hub 拉取十几个镜像再通过 docker-compose 启动。离线包则把所有这些镜像提前docker save成 tar 文件打包进 tgz。harbor-offline-installer-v2.13.1-arm64.tgz解压后你会看到几个关键部分harbor/目录下是各个组件的镜像 tar 包prepare脚本负责生成配置install.sh负责加载镜像并启动。arm64 版本的特殊之处在于所有镜像的 manifest 都是 arm64 架构如果你拿 x86 的离线包在 arm 上跑docker load阶段就会报no matching manifest。这一点在信创环境里是第一个分水岭很多人拿到包不确认架构就直接解压结果卡在镜像加载。2.2 组件构成与资源预估Harbor 2.13.1 的核心组件包括nginx前端代理、harbor-coreAPI、harbor-dbPostgreSQL、harbor-jobservice、harbor-portal、registry镜像存储、redis、trivy漏洞扫描可选。离线包解压后总大小通常在 2GB 到 3GB 之间具体取决于是否包含 trivy 的漏洞库。arm 环境下内存建议不低于 4GB因为 PostgreSQL 和 core 组件在 arm 上的内存占用比 x86 略高。磁盘方面/data目录要预留至少 40GBregistry 的存储会随着镜像推送持续增长。我一般会在部署前用df -h和free -m确认这两个指标避免装到一半因为磁盘满导致 jobservice 反复重启。2.3 部署前的系统检查清单在解压之前有几项系统层面的检查必须做否则后面会出各种玄学问题。第一确认内核版本uname -r建议 4.19 以上低于这个版本 docker 的 overlay2 存储驱动在 arm 上可能不稳定。第二确认 docker 和 docker-compose 已安装docker 版本建议 20.10 以上docker-compose 建议 v2 版本因为 Harbor 2.13.1 的 compose 文件用了name字段老版本 compose 不识别。第三关闭 swapswapoff -a并写入/etc/fstab否则 harbor-db 在内存压力下会触发 OOM。第四确认 80、443、5432、6379 端口没有被占用。这些检查看起来琐碎但每一条对应一个真实的翻车场景。# 系统检查脚本部署前逐条执行 uname -r # 内核版本建议 4.19 docker --version # 建议 20.10 docker-compose --version # 建议 v2.x free -m # 内存建议 4GB df -h /data # 数据盘建议 40GB swapoff -a # 关闭 swap grep -E 80|443|5432|6379 (ss -tlnp) # 检查端口占用上面这段脚本里ss -tlnp列出所有监听端口配合 grep 过滤出 Harbor 要用的四个端口。如果 80 被 nginx 占用要么停掉现有服务要么在harbor.yml里改http.port。swapoff -a是临时关闭要永久生效还得注释掉/etc/fstab里的 swap 行。这些操作在 arm 服务器上执行时注意有些国产 OS 的ss命令路径可能不同可以用netstat -tlnp替代。3. 从解压到启动arm 环境下的完整操作链路3.1 解压与目录结构确认拿到 tgz 后先校验文件完整性。虽然没有官方提供的 sha256 文件但可以用tar -tzf列出内容确认没有报错。解压命令很简单但要注意解压后的目录权限。我一般会创建一个专用目录比如/opt/harbor-install把包放进去再解压避免污染当前目录。# 解压与结构确认 mkdir -p /opt/harbor-install cd /opt/harbor-install tar -xzf harbor-offline-installer-v2.13.1-arm64.tgz ls -lh harbor/ # 预期看到 harbor.v2.13.1.tar.gz、harbor.yml.tmpl、prepare、install.sh 等解压后harbor/目录下最重要的三个文件是harbor.yml.tmpl配置模板、prepare生成最终配置和 compose 文件、install.sh加载镜像并启动。harbor.v2.13.1.tar.gz是镜像包大小通常在 2GB 左右。如果ls发现这个文件缺失或大小异常说明下载或拷贝过程中断了需要重新获取。arm 环境下解压大文件时如果磁盘 IO 较慢tar可能会跑几分钟耐心等它结束不要中途 CtrlC。3.2 harbor.yml 关键参数逐项说明harbor.yml.tmpl是模板复制成harbor.yml后修改。下面这张表列出了 arm 离线部署必须关注的参数每一项都对应一个实际影响。参数默认值建议值说明hostnamereg.mydomain.com实际 IP 或域名必须与客户端访问地址一致http.port8080 或自定义若被占用需改https注释状态内网可先不启用启用需提供证书路径harbor_admin_passwordHarbor12345强密码首次登录后立即改data_volume/data/data 或大容量盘镜像存储根目录database.passwordroot123强密码PostgreSQL 密码trivy.enabledtrue按需关闭可省资源修改时用cp harbor.yml.tmpl harbor.yml再编辑。hostname这一项在 arm 环境里特别容易翻车如果填了域名但内网 DNS 没解析客户端docker login会报no such host。我一般直接填服务器 IP简单可靠。data_volume如果指向一个不存在的目录prepare脚本会自动创建但前提是父目录有写权限。trivy在 arm 上扫描速度比 x86 慢如果只是做镜像存储可以设enabled: false省掉一个容器。3.3 执行 prepare 与 install 的完整流程配置改好后依次执行./prepare和./install.sh。prepare会做三件事检查配置、生成docker-compose.yml、创建数据目录。install.sh会加载镜像、启动容器、等待健康检查。整个过程在 arm 上大概需要 3 到 8 分钟取决于磁盘速度。# 执行安装 cd /opt/harbor-install/harbor ./prepare # 观察输出确认没有 ERROR ./install.sh # 安装完成后检查容器状态 docker-compose ps # 预期看到 9 个左右容器状态为 Up (healthy)prepare阶段如果报cannot find harbor.yml说明你忘了复制模板。如果报data_volume is not writable检查目录权限。install.sh阶段最常见的报错是docker load失败通常是镜像包损坏或磁盘空间不足。安装完成后docker-compose ps里 harbor-core 和 harbor-db 的 healthy 状态需要等一会儿如果超过 2 分钟还是 starting用docker-compose logs harbor-core看日志。arm 环境下 PostgreSQL 初始化比 x86 慢耐心等是常态。3.4 验证部署是否真正可用容器全部 Up 不代表 Harbor 就能用。我一般做三层验证第一层curl -I http://hostname看是否返回 200第二层用浏览器或curl访问/api/v2.0/systeminfo看 API 是否响应第三层在另一台机器上docker login并推送一个测试镜像。# 三层验证 curl -I http://192.168.1.100 curl -s http://192.168.1.100/api/v2.0/systeminfo | head -c 200 # 客户端操作 docker login 192.168.1.100 -u admin -p Harbor12345 docker pull alpine:latest docker tag alpine:latest 192.168.1.100/library/alpine:test docker push 192.168.1.100/library/alpine:test第一层如果返回 502说明 nginx 起来了但 core 没起来去看 core 日志。第二层如果返回{error:Unauthorized}说明 API 正常只是需要认证。第三层推送时如果报denied: requested access to the resource is denied通常是项目不存在需要先在 Harbor 界面创建library项目或者用docker push时带上正确的项目名。arm 环境下推送 arm64 镜像没问题但如果推的是 x86 镜像Harbor 不会拦截但拉取到 arm 机器上跑不了这是使用层面的坑不是部署的坑。4. arm 离线部署 Harbor 的避坑与排查实录4.1 镜像加载失败no matching manifest现象执行install.sh时docker load报no matching manifest for linux/arm64 in the manifest list entries。原因你拿到的 tgz 虽然文件名带 arm64但内部镜像包可能是 x86 的或者下载过程中被替换。解决用docker load -i harbor.v2.13.1.tar.gz手动加载观察具体是哪个镜像报错。如果确认是架构不匹配只能重新获取正确的 arm64 离线包。在信创环境里这个错误出现频率最高因为很多下载渠道不区分架构。4.2 harbor-core 反复重启数据库连接超时现象docker-compose ps显示 harbor-core 状态一直是Restarting日志里报dial tcp 172.x.x.x:5432: connect: connection refused。原因harbor-db 启动慢core 在 db 还没就绪时就尝试连接重试几次后放弃。解决先单独启动 dbdocker-compose up -d harbor-db等它 healthy 后再docker-compose up -d。另外检查harbor.yml里的database.password是否和 db 容器环境变量一致。arm 上 PostgreSQL 首次初始化要建表时间比 x86 长不要急着判定失败。4.3 磁盘满导致 jobservice 异常现象镜像推送成功但日志清理任务不执行docker-compose logs harbor-jobservice报no space left on device。原因/data目录所在分区满了registry 的 blob 文件把磁盘撑爆。解决df -h确认后清理无用镜像或扩容。Harbor 的垃圾回收需要手动触发在界面里选项目执行或者调 API。我一般会在部署时就给/data单独挂一块盘避免和系统盘混用。arm 服务器通常磁盘接口有限提前规划很重要。4.4 客户端登录报证书错误现象docker login报x509: certificate signed by unknown authority。原因Harbor 启用了 https 但用的是自签证书客户端不信任。解决内网环境可以先不启用 https把harbor.yml里 https 段全部注释重新./prepare ./install.sh。如果必须用 https把 CA 证书放到客户端的/etc/docker/certs.d/hostname/ca.crt并重启 docker。arm 客户端上这个路径同样适用注意目录名要和 hostname 完全一致。4.5 prepare 脚本报 Python 相关错误现象./prepare执行时报python: command not found或SyntaxError。原因Harbor 2.13.1 的 prepare 脚本依赖 python3有些精简版 arm OS 没预装。解决安装 python3apt install python3或yum install python3。如果系统里只有 python2需要显式建软链或改脚本 shebang。这个坑在定制化国产 OS 上很常见因为系统裁剪时把 python 去掉了。5. 进阶技巧让 arm 离线 Harbor 跑得更稳的几个习惯部署完成只是开始长期稳定运行靠的是几个日常习惯。第一个习惯是定期备份harbor.yml和/data/database目录。Harbor 的元数据都在 PostgreSQL 里镜像 blob 丢了可以重新推但项目、用户、权限配置丢了就得重建。我一般写一个 cron每天凌晨pg_dump一次保留最近 7 天。第二个习惯是监控/data磁盘使用率超过 80% 就触发告警因为 registry 的 blob 增长是线性的不会自动清理。# 每日备份 database 的 cron 示例 0 2 * * * docker exec harbor-db pg_dump -U postgres registry /backup/registry_$(date \%F).sql # 磁盘监控 */30 * * * * df -h /data | awk NR2 $50 80 {print disk warning} | mail -s harbor disk adminlocal上面第一行是备份 registry 数据库-U postgres是默认用户如果改了要对应调整。第二行是磁盘监控$50把百分比转成数字比较。arm 环境下 cron 服务默认可能没启动记得systemctl enable cron。第三个习惯是升级前先做快照。Harbor 2.13.1 到后续版本的升级路径需要逐版本迁移不能跨大版本直接升。离线升级时新版本的离线包会自带迁移脚本但前提是旧版本的数据库结构完整。我一般会在升级前把整个/opt/harbor-install和/data打包一份出问题能回滚。这个习惯救过我一次某次升级后 core 起不来回滚只花了 10 分钟。第四个习惯是给 arm 服务器设置合理的 ulimit。Harbor 的 nginx 和 core 在高并发推送时会打开大量文件描述符默认 1024 不够用。在/etc/security/limits.conf里加上* soft nofile 65535和* hard nofile 65535重启后生效。这个参数在 x86 上可能不明显但 arm 服务器如果同时跑其他服务文件描述符耗尽会导致 Harbor 间歇性 502。最后一个习惯是记录每次变更。harbor.yml改了什么、什么时候改的、为什么改写在一个文本文件里放在同目录。arm 离线环境的交付周期长半年后回来维护时没有记录就得重新读配置。我见过太多因为改了一个端口没记录导致后续排查花半天的情况。这些习惯看起来不起眼但能让你的 arm Harbor 从“能跑”变成“敢用”。希望帮到你。本文还有配套的精品资源点击获取