简介面向ARM架构服务器环境此离线包提供Harbor 2.13.1版本的完整安装物料适合运维工程师、云原生平台管理员以及需要在无外网或信创环境下搭建镜像仓库的技术人员。在国产化替代与内网隔离需求日益普及的背景下arm64架构的Harbor离线安装资料相对稀缺该tgz资源恰好弥补了这一空白。资源包内共有6个文件主要类型包括安装脚本、镜像归档压缩包、配置模板和许可证文件安装脚本负责环境预检、参数校验与安装流程编排镜像归档解决容器镜像的离线传输配置模板则支持按业务场景修改主机域名、管理员密码、存储路径和TLS证书等关键项整个压缩包体积约513.28MB体积适中便于在内网环境拷贝与分发。借助这套离线物料可有效规避在线拉取镜像时的网络超时、源不可达等问题让安装过程更可控同时可作为批量交付或自动化运维的整洁基础。目前已有414人学习或下载适合需要在ARM服务器上快速搭建生产级Harbor仓库、支撑CI/CD流水线或满足等保合规、离线交付要求的工程师参考使用。1. ARM 服务器上装 Harbor 2.13.1离线包才是真正的省心路径我第一次在 ARM64 服务器上搭 Harbor 2.13.1 镜像仓库时最头疼的不是 Harbor 参数而是安装过程里组件镜像拉取时断时续一个镜像重试五六次都未必成功。后来换成 harbor-offline-installer-v2.13.1-arm64.tgz 离线包问题一次性消失包内已经带齐全套 Harbor 组件镜像和安装脚本install.sh 全程不需要访问外网特别适合内网隔离、出口受限或者基于 ARM 架构的服务器节点。这篇笔记要解决的就是“ARM 环境 离线包”这条完整落地链路包里有什么、装之前要确认什么、怎么改配置、镜像怎么导进去以及那些会让你半夜爬起来看日志的坑。2. 拆解 harbor-offline-installer-v2.13.1-arm64.tgz文件结构与 ARM 前置条件拿到离线包先别急着解压执行。Harbor 的安装脚本对前置环境有隐式要求ARM 平台上这些要求比 x86 更容易踩空。先花十分钟看清包里文件和机器环境能省掉后面大半的排查时间。2.1 解包看结构install.sh、harbor.yml 与 common.sh 的分工# 只列出包内文件清单确认包完整再解压 tar -tzf harbor-offline-installer-v2.13.1-arm64.tgz | head -30 # 解压到 /opt/harbor目录不存在会自动创建 sudo mkdir -p /opt/harbor sudo tar -xzf harbor-offline-installer-v2.13.1-arm64.tgz -C /opt/harbor cd /opt/harbor ls -lhtar -tzf只列出内容不落盘用来快速确认 tgz 没有在传输过程中损坏加head -30是因为离线包里有体积很大的组件镜像归档直接列全会刷屏。解压时用-C指定目标目录避免在当前目录散落一堆文件。解压后用ls -lh看文件大小如果 install.sh 和 harbor.yml 存在但体积对不上说明包不完整别往下走。解压后你会看到几个固定文件各自职责如下文件作用install.sh安装主入口负责加载镜像、执行 prepare、启动服务harbor.yml唯一需要手工修改的配置文件common.sh被 install.sh 调用的公共函数库一般不需要动prepare安装时读取 harbor.yml 并渲染出最终的 docker-compose.yml镜像 tar 归档Harbor 全组件镜像的 docker load 来源占包内绝大部分体积一个理解重点Harbor 的 docker-compose.yml 不是写死的install.sh 会先跑 prepare用 harbor.yml 里的 hostname、端口、数据目录生成最终的编排文件。所以改配置后不需要手改 compose重新执行 install.sh 即可这也是后面反复提到的操作基础。2.2 检查依赖docker、compose 与 arm64 内核参数# 确认 Docker 服务正常Server Arch 应该输出 aarch64 docker version --format Server Arch: {{.Server.Arch}} / Version: {{.Server.Version}} # 确认 compose 插件可用 docker compose version # 确认内核加载了 overlay 模块 lsmod | grep overlay || echo overlay 未加载需要 modprobe overlaydocker version的--format模板直接输出服务端架构和版本一眼就能看出 Docker 装的是不是 aarch64 版本。如果输出 amd64说明装错了安装包后面拉取 arm64 镜像大概率会走弯路。docker compose version是确认 compose v2 插件存在Harbor 2.13 这代安装脚本会优先调用它如果命令不存在需要补齐 docker-compose 插件而不是去装老旧的 docker-compose 独立二进制。lsmod | grep overlay检查的是 overlay2 存储驱动依赖ARM 服务器如果用了精简内核overlay 模块没加载Docker 会退回 vfs 驱动镜像层写盘膨胀数倍推大镜像时慢到让你怀疑网络。提示docker version输出里 Client Arch 是 amd64 没关系只要 Server Arch 是 aarch64 就行Docker 客户端和服务端允许跨架构工作。2.3 别把 qemu 模拟当安装环境原生 aarch64 才是离线包的正主我在开发机上折腾过一段 qemu 模拟 arm64 环境装普通容器还算流畅但 Harbor 这种同时拉起 postgres、redis、registry、core、jobservice 等十来个容器的服务在模拟层上表现很不稳定。qemu 的二进制翻译对 CPU 密集任务损耗明显而容器镜像仓库的每次推送都要做解压、校验、写入IO 放大效应在模拟层被成倍放大。更隐蔽的问题是qemu 环境里容易拉错架构的基础镜像明明跑起来了容器里面却是另一个世界后面排查 exec format error 会查到怀疑人生。所以这条结论放在最前面这个离线包是给原生 aarch64 环境用的请直接装在物理 ARM 服务器、ARM 云主机或者 ARM 架构的虚拟机上。qemu 模拟只适合做安装流程验证不适合做容量评估和性能压测。如果你的服务器本身就是 ARM64 且 Docker 架构输出正确直接进入下一章。3. 最小安装一条命令跑通harbor.yml 改 3 处 install.sh 带 1 个参数Harbor 的安装脚本设计得很收敛不会让你在安装过程中回答一串问题所有偏好都集中在 harbor.yml 里。最小安装只需要改三处配置然后执行一次 install.sh。3.1 改 harbor.yml 的三处必改项hostname、端口与数据卷# /opt/harbor/harbor.yml只列出本次必须动的键 hostname: 192.168.209.133 http: port: 8080 # https: # port: 443 # certificate: /your/cert.pem # private_key: /your/key.pem data_volume: /data/harbor第一个是 hostname写节点对内的管理 IP不要写 127.0.0.1也不要写 localhost。Harbor 会用这个值生成 registry 的访问地址写错了会导致客户端 login 时拿到错误的重定向地址报错信息里能看到 IP 跟实际不符。第二个是 http.port改 8080 是为了避开节点上已经存在的 nginx 或者其它 Web 服务如果 80 端口确认空闲保持默认也行但内网机器上 nginx 几乎必然存在直接改成 8080 更省事。第三个是 data_volume这是 Harbor 全部持久化数据的落盘目录包括镜像层、数据库文件、redis 数据一定要放到剩余空间大的分区。很多 ARM 服务器根分区只有二三十 GB镜像推多了这个目录会写满到时候整个 Harbor 都起不来。内网环境没有现成证书的话就把 https 整段注释掉只用 http 对外服务。改完可以用grep -n ^[a-z] /opt/harbor/harbor.yml快速核对一遍顶层键确认注释没有破坏 YAML 结构。3.2 跑 install.sh先用 --with-trivy其余组件按需加cd /opt/harbor sudo ./install.sh --with-trivy # 脚本执行到最后会输出 docker compose ps 状态看到 UP 就说明核心服务已拉起这个命令会做三件事把离线包里的组件镜像用 docker load 导入本地、执行 prepare 生成 docker-compose.yml、后台启动全部容器。加--with-trivy是开启镜像漏洞扫描组件Harbor 2.13 这代离线包里还保留这个可选组件如果你的内网对安全合规有要求建议打开如果内存紧张直接裸跑./install.sh也可以。老文章里常见的--with-clair、--with-chartmuseum在这代离线包里已经不存在了抄旧命令会直接报参数错误。提示第一次用什么参数装的以后升级或者加组件就继续用同样的参数重跑 install.shHarbor 会基于现有数据卷做增量处理。参数不一致可能导致 compose 文件被重新规划容器状态异常。整个安装过程不需要访问外网因为组件镜像全部来自包内归档。如果脚本执行期间卡在某个镜像的 load 上去检查磁盘空间和 docker 服务状态而不是怀疑网络。3.3 端口占用和防火墙安装时报 “Address already in use” 的处理# 先看 80/8080/443 被哪个进程占用 ss -lntp | grep -E :(80|8080|443)\s # 如果是 nginx 占着先停掉再重跑 sudo systemctl stop nginx sudo systemctl disable nginxinstall.sh 跑的时候如果端口被占会直接报 “Address already in use”这时候不需要卸载重装。两个选择停掉占端口的服务或者改 harbor.yml 里的端口后重新执行 install.sh。我一般优先改 Harbor 端口因为节点上已有的 nginx 可能是其它业务的入口停掉会影响别人。防火墙这块容易被忽略内网节点常见的安全组规则只放行了 22 端口。装完后在客户端机器上执行nc -zv 192.168.209.133 8080如果端口不通检查安全组和 firewalld/ufw 规则Harbor 页面打不开多半是这里的问题不是 Harbor 本身的问题。4. 镜像离线化与推送docker save/load 后如何顺利 push 进 HarborHarbor 装好只是第一步。真正日常要用的是把客户机上现有的镜像灌进 Harbor再让其它 ARM 节点从 Harbor 拉取。这一章解决存量镜像离线搬运和 push 推不上去的问题。4.1 批量导出存量镜像一个循环搞定 docker save 与压缩#!/usr/bin/env bash # 在源节点执行把要迁移的镜像打平成 tar.gz src_images( nginx:1.25-alpine postgres:16-alpine registry.k8s.io/pause:3.9 ) mkdir -p /data/migrate for img in ${src_images[]}; do # 把斜杠和冒号转成下划线避免生成非法文件名 fname$(echo $img | tr /: __) echo saving $img - $fname.tar.gz docker save $img | gzip /data/migrate/${fname}.tar.gz donedocker save输出的是未压缩的镜像层归档直接管道给gzip能省掉一半临时磁盘空间这是我在迁移多份镜像时养成的习惯。目标节点拿到 tar.gz 后执行docker load -i xxx.tar.gz即可不需要解压。注意一个关键点docker save/load 不关心宿主机发行版Ubuntu、Debian、openEuler 的 ARM 节点之间可以互相搬运但 load 进去的镜像 tag 是原始名称不含 Harbor 地址push 前还要重新 tag。如果源节点就是 Ubuntu ARM 环境这个 tar 包在目标 Ubuntu ARM 节点上直接 load 就行这就是常见的“Ubuntu 节点上导入 harbor 镜像包”的完整过程。4.2 push 失败先查 dial tcp从 login 到 retry 的完整链路// 客户端 /etc/docker/daemon.json新增 insecure-registries 字段 { insecure-registries: [192.168.209.133:8080] }# 重启 docker 使配置生效然后登录、打标签、推送 sudo systemctl restart docker echo Harbor12345 | docker login 192.168.209.133:8080 -u admin --password-stdin docker tag nginx:1.25-alpine 192.168.209.133:8080/library/nginx:1.25-alpine docker push 192.168.209.133:8080/library/nginx:1.25-alpine这里要重点说一个高频报错harbor 推送失败提示get https://192.168.209.133/v2/: dial tcp 192.168.209.133:443: connect: connection refused这类信息。看起来像是 Harbor 挂了实际是客户端默认按 https 协议访问 443 端口而你的 Harbor 只监听了 http 8080。处理方式就是上面 daemon.json 里把完整地址写成192.168.209.133:8080加入 insecure-registries重启 docker 后再 push。注意重启 docker 不会重启正在运行的容器但 docker 命令会短暂中断挑业务低峰期做。docker push在网络抖动时会自动重试不需要手动反复重新 push。如果总是推到一半断开不要只盯着网络回到 5.3 的排查思路。登录账号默认是 admin初始密码是 Harbor12345装完第一件事建议改成强密码。4.3 架构混用是最大的雷用 manifest inspect 拦住 amd64 镜像docker manifest inspect 192.168.209.133:8080/library/nginx:1.25-alpine # 输出里重点看 platform.architecture 字段确认是 arm64 还是 amd64Harbor 本身不校验镜像的 CPU 架构同一个仓库里可以同时存 amd64 和 arm64 镜像。但 ARM 节点如果拉错架构容器运行时直接报 exec format error排查起来很隐蔽。我的习惯是在构建阶段就用FROM --platformlinux/arm64固定基础镜像架构push 之前再用 manifest inspect 确认一遍。如果仓库里不得不混存多架构镜像给 tag 加后缀区分比如nginx:1.25-arm64、nginx:1.25-amd64同时用 Harbor 的 robot 账号给 CI 流程最小推送权限避免误推。5. ARM 环境避坑Harbor 2.13.1 离线安装的 5 条真实故障记录以下五条都是我在 ARM 环境装 Harbor 时实际踩过的坑每条按现象、原因、解决的顺序记录。前两条最影响安装成功率后三条更多影响日常使用。5.1 docker load 报 no space left on device先给 /var/lib/docker 腾地方现象install.sh 执行到导入组件镜像阶段终端刷出write /var/lib/docker/overlay2/... no space left on device脚本中断Harbor 起不来。原因离线包本身的体积不算大但镜像 tar 被 docker load 加载后层数据会膨胀/var/lib/docker所在分区只有二十多 GB根本扛不住 Harbor 全家桶。解决先df -h /var/lib/docker看实际用量再用docker system prune -a清理节点上已无主的镜像。如果清理完还是不够最简单的办法是把 docker>sudo systemctl stop docker sudo rsync -a /var/lib/docker/ /data/docker/然后在/etc/docker/daemon.json里加一行data-root: /data/docker再启动 docker 重新执行 install.sh。注意旧数据不会自动搬rsync 必须做在改配置之前。5.2 docker login 报 x509http 与 https 二选一没做干净现象Harbor 页面能打开但客户端docker login报错x509: certificate signed by unknown authority。原因harbor.yml 里 https 段没有完全注释install.sh 用自签生成了一套临时证书客户端不信任它。或者客户端 daemon.json 里的 insecure-registries 写的是192.168.209.133而不是192.168.209.133:8080请求走了 https 443。解决内网环境直接整段注释掉 https 配置只保留 httpdaemon.json 里确认写的是带端口的完整地址改完重启 docker再重新 login。这个问题 80% 是配置两头没对齐不是 Harbor 本身的问题。5.3 大镜像推送中断不全是网速问题先看磁盘 IO现象推 2GB 的应用镜像推到一半连接被重置docker push 反复重试失败Harbor 的 registry 容器日志里出现context deadline exceeded或read: connection reset。原因网络带宽没问题排查到最后发现是客户端机器的/var/lib/docker在机械盘上多个镜像同时推送时 IO 排队超过 registry 侧的读超时阈值。解决错峰推送单批不要超过两个镜像后台如果有备份任务在跑先停掉把 docker>sudo modprobe binfmt_misc docker run --rm --privileged multiarch/qemu-user-static --reset -p yes但这条命令需要这台机器能拉到 multiarch/qemu-user-static 镜像纯内网环境要把这个镜像单独 save/load 过去。生产环境我的建议是别靠模拟层硬扛直接在原生 ARM64 硬件上跑。5.5 版本升级不能跳级从旧版到 2.13.1 的备份与迁移顺序现象直接把旧版 Harbor 的安装目录覆盖成 2.13.1跑完 install.sh 后数据库容器起不来登录页面一直转圈。原因Harbor 的数据库 schema 和内部 API 有版本演进跨大版本直接覆盖时迁移脚本没有机会按顺序做升级数据文件对不上新代码的预期。解决官方支持的升级路径是沿着版本链逐步走旧 2.x 版本要升级到 2.13.1至少先升到中间版本再升到目标版本不能跳级。升级前做两个备份一个给配置一个给数据卷sudo cp -a /opt/harbor/harbor.yml /opt/harbor/harbor.yml.bak.$(date %F) sudo tar -czf /data/backup/harbor-data-$(date %F).tar.gz -C /data harbor数据卷打包可能涉及十几 GB 内容注意目标盘空间。新包解压时不要直接覆盖旧目录解压到全新目录配置里单独指向数据卷路径确认服务正常后再切流量。这个备份习惯在 Harbor 版本升级时就是后悔药没有备份的升级都是在赌运气。6. 部署后的每日自检一条命令看清 Harbor 全家桶状态Harbor 装完能登录不代表它一直会是健康状态。数据盘写满、某个组件容器 OOM、redis 连接数打满这些故障在页面上往往看不出来等用户报推送失败才发现就晚了。我习惯写一个健康检查脚本一条命令把三个关键维度全部打出来#!/usr/bin/env bash # /usr/local/bin/harbor-health.sh HARBOR_DIR/opt/harbor HARBOR_URLhttp://127.0.0.1:8080 HARBOR_ADMINadmin HARBOR_PASSHarbor12345 cd $HARBOR_DIR echo docker compose ps docker compose ps --format table {{.Name}}\t{{.Status}} echo harbor health api curl -fsS -u $HARBOR_ADMIN:$HARBOR_PASS $HARBOR_URL/api/v2.0/health || echo health check failed echo echo data volume df -h /data/harbor | tail -1第一段docker compose ps看的是所有 Harbor 容器是否处于 UP 状态任何一个容器反复重启或退出都能在这个输出里看出来。第二段调用 Harbor 自带的/api/v2.0/health接口返回的是各个核心组件的健康状态比只看页面登录更可靠。第三段df -h看数据盘水位Harbor 的数据盘到 85% 就要开始清日志、清未使用的镜像或者扩容等写满再处理就只能停机。这个脚本配合 crontab 每周跑一次输出重定向到日志文件基本能覆盖日常巡检需求。我的习惯是升级前永远先备份数据卷健康检查做成定时任务宁可多打一条无用日志也不在磁盘写满的凌晨爬起来对着黑匣子瞎猜。希望帮到你。本文还有配套的精品资源点击获取