简介面向需要在内网、隔离网或信创环境中离线部署容器镜像仓库的运维工程师这套Harbor v2.9.0 ARM64架构离线安装包提供了可直接落地的完整方案。压缩包内已经封装Harbor核心服务镜像、安装脚本及默认配置模板配合预先安装的Docker与Docker Compose环境执行install.sh即可自动完成归档解压、镜像加载、配置生成与服务启动免去手动逐项配置和依赖网络拉取镜像的繁琐步骤。资源包含6个文件以shell脚本install.sh、common.sh、Harbor离线主包.tar.gz、prepare预处理工具、harbor.yml.tmpl配置模板及License文件为主体整体大小约722.35MB目录结构清晰其中prepare负责构建动态配置common.sh提供公共函数模板则允许自定义端口、存储路径、数据库密码等关键参数适配不同生产环境。已有962名开发者学习使用适合具备Docker基础、希望快速交付生产级镜像仓库的中高级运维人员。借助这一离线安装包用户可显著缩短环境搭建时间规避因网络波动造成的安装中断尤其适合ARM64服务器、国产化硬件及无外网机房的部署场景。1. Harbor v2.9.0 ARM 架构离线安装你以为难点是 Harbor其实是这些前置依赖真正上手 ARM 架构的离线部署时你会发现 Harbor 本身的安装包反而是最省事的环节。v2.9.0 的官方离线安装包已经包含 Docker 镜像拉下来解压就能用。真正让人翻车的是 ARM 环境下的前置依赖链——Docker Engine、Docker Compose、Python 版本、OpenSSL 兼容性以及prepare脚本在生成配置文件时对架构的隐式依赖。这套组合拳打下来新手容易卡在「为什么镜像加载了但容器起不来」熟手则容易栽在「为什么 x86 上能跑的配置在 ARM 上就是不行」。本文按我实际拆过的部署路径走一遍先讲清楚 ARM 版 Harbor 与 x86 版的本质差异再给出一套可直接抄作业的离线部署流程最后把我在 debian/麒麟/统信等 ARM 环境里踩过的坑逐个列出来。这份资源适合三类人正在做信创适配的运维、在树莓派或 RK3588 板子上跑私有仓库的嵌入式工程师以及需要在内网环境交付 Harbor 的实施人员。2. 先搞清楚 v2.9.0 的 ARM 版本差异不是换个镜像那么简单2.1 Harbor 二进制对架构的隐性依赖Harbor 官方发布页面提供harbor-offline-installer-v2.9.0.tgz和harbor-offline-installer-v2.9.0-arm64.tgz两个离线包。很多人以为这两个包只是镜像架构不同实际差异比想象中大得多。离线安装包里的harbor.yml.tmpl模板文件在两个版本中基本一致但prepare工具和registry组件的二进制文件是重新编译过的。ARM 版的prepare依赖 Python 3.8 且需要pyyaml库而 x86 版在 Python 3.6 上也能跑。这个差异直接决定了你在 ARM 机器上准备配置文件时必须先确认 Python 版本和 pip 源是否可用。另一个隐性依赖是chartmuseum和trivy这两个可选组件。在 v2.9.0 的 ARM 版里trivy的漏洞扫描数据库需要单独下载 ARM64 架构的trivy-offline.tar.gz官方的离线包并不包含这个文件。如果你在部署时开启了trivy组件而没有手动补充漏洞库扫描器会在启动后不停报错日志里会出现failed to download vulnerability database之类的信息。2.2 Docker Engine 与 Compose 的版本红线Harbor v2.9.0 官方要求 Docker Engine 版本不低于 20.10Docker Compose 版本不低于 2.0。在 x86 环境这个要求很容易满足但 ARM 环境下有两个问题第一ARM 架构的 Docker Engine 包名和源不一样。Debian/Ubuntu 系使用docker-ce的arm64变体而 CentOS/麒麟等使用docker-ce或docker-engine的aarch64变体。如果不匹配docker info会报错误架构。第二Docker Compose v2 默认以 Docker 插件形式存在文件名为docker-compose放在/usr/libexec/docker/cli-plugins/目录下。但很多 ARM 环境的发行版把 Docker 装成了旧版只支持docker-composePython 实现的 v1。Harbor 的install.sh脚本会检测docker-compose命令是否存在检测不到就直接退出报docker-compose not found。提示在 ARM 架构下优先确认docker compose versionv2 插件形式是否可用不要依赖docker-composev1 独立二进制。如果发行版只有 v1可以手动下载 compose v2 的 arm64 二进制放到 cli-plugins 目录。2.3 离线包内部结构拆解把harbor-offline-installer-v2.9.0-arm64.tgz解压后关键文件如下文件/目录作用install.sh主安装脚本负责加载镜像并启动容器harbor.yml.tmpl配置模板需要复制为harbor.yml并修改prepare配置生成工具运行后生成 docker-compose.ymlcommon.sh公共函数库包含版本检测和硬件检测逻辑harbor.v2.9.0.tar.gz所有 Harbor 组件的 Docker 镜像压缩包LICENSE开源协议文件install.sh脚本在执行时会先加载harbor.v2.9.0.tar.gz中的镜像然后调用prepare生成配置最后用docker compose up -d启动容器。我一般会先手动拆包看一遍common.sh里的检测逻辑确认它对架构的判断方式避免 install.sh 在某个检测环节直接退出。3. 部署前置条件准备ARM 环境下的依赖清单与验证命令3.1 操作系统与内核要求我实测过的 ARM 环境包括 Debian 11/12、Ubuntu 22.04、银河麒麟 V10、统信 UOS 1060内核版本都在 5.4 以上满足 Harbor 对内核的最低要求。但要注意Kylin 和 UOS 的 Docker 包来源可能与 Debian 官方不同建议优先使用发行版自带的软件源里的 Docker而不是从 Docker 官方源拉取——离线环境下后者根本不可用。验证内核架构和操作系统版本uname -m # 期望输出aarch64 或 arm64 cat /etc/os-release # 确认发行版类型和版本这个命令输出的aarch64是 ARM 64 位架构的标准标识。Harbor 的 ARM 离线包在install.sh里会检查这个值如果输出的是armv7l32 位 ARM安装会直接失败。我遇到过一台国产 ARM 服务器uname -m输出是aarch64但/proc/cpuinfo显示的是飞腾 FT-2000兼容性没问题但性能上对 Harbor 这种多容器应用有些吃力建议至少 4 核 8G 内存。3.2 Docker 离线安装包准备在能联网的 ARM 机器上用apt download或yumdownloader拉取 Docker 及相关依赖的 deb/rpm 包。以 Debian/Ubuntu 系为例# 在联网的 ARM 机器上执行 mkdir -p docker-offline cd docker-offline apt-get download docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # 同时下载依赖包 apt-get download libltdl7 libseccomp2拉下来的 deb 包拷贝到目标机器后离线安装# 在离线 ARM 机器上执行 sudo dpkg -i *.deb # 如果报依赖缺失用以下命令修复 sudo apt-get -f install -y参数说明docker-ce是 Docker 守护进程docker-ce-cli是命令行工具containerd.io是容器运行时docker-compose-plugin提供 compose v2 插件。libltdl7是 Docker CLI 的运行时库libseccomp2是安全隔离依赖。在 Kylin 等基于 CentOS 的系统上需要改用yumdownloader拉取 rpm 包并补充container-selinux依赖。注意apt-get -f install在无外网环境下只能修复本地已下载的依赖如果缺包会在输出中明确提示缺哪个包名记下来再去联网机器补齐。3.3 Docker 配置与启动验证安装完成后需要配置 Docker 的镜像加速和日志策略。对 ARM 离线环境我习惯把 daemon.json 写成这样{ log-driver: json-file, log-opts: { max-size: 100m, max-file: 3 }, data-root: /data/docker, iptables: true, ip6tables: false }配置说明log-driver设为json-file并限制单文件 100M、最多 3 个文件防止 Harbor 的日志在长时间运行后占满磁盘。>sudo systemctl enable docker sudo systemctl start docker sudo docker info # 关注 Server Version、Architecture 字段docker info输出里的Architecture: aarch64说明 Docker 守护进程正常工作。此时可以跑一个 hello-world 镜像验证容器能正常创建和销毁但要先确认镜像的架构是 arm64否则会报exec format error。4. 离线部署 Harbor v2.9.0从解压到 HTTPS 访问的完整流程4.1 解压离线包并准备配置获取harbor-offline-installer-v2.9.0-arm64.tgz后上传到目标机器并解压mkdir -p /opt/harbor tar -xzf harbor-offline-installer-v2.9.0-arm64.tgz -C /opt/harbor cd /opt/harbor cp harbor.yml.tmpl harbor.yml解压后的目录里会有一个harbor.v2.9.0.tar.gz镜像包和一个install.sh脚本。在修改配置前先确认磁盘空间——这个镜像包解压后大约占 3-5G如果/opt所在分区空间不足需要换成其他挂载点。4.2 修改 harbor.yml主机名、端口、证书与存储路径用 vim 编辑harbor.yml重点修改以下几项hostname: registry.internal.example.com http: port: 8080 https: port: 443 certificate: /data/certs/server.crt private_key: /data/certs/server.key data_volume: /data/harbor log: level: info rotate_count: 20 rotate_size: 100M trivy: ignore_unfixed: true skip_update: true offline_scan: true参数说明hostname是 Harbor 对外提供服务的域名或 IP。如果没有 DNS 解析条件可以直接填 IP但后续使用docker login或docker pull时需要加上端口号。http.port我改成了 8080避免和机器上其他服务冲突https.port保持 443。data_volume指定 Harbor 的数据目录包括数据库、证书、镜像存储等。log的rotate_count和rotate_size控制日志轮转。trivy的三个参数在离线环境非常重要skip_update禁止扫描器联网更新漏洞库offline_scan启用离线扫描模式ignore_unfixed忽略未被修复的漏洞否则扫描任务会一直卡在等待漏洞库更新。4.3 自签名证书生成SAN 扩展必须配置ARM 环境下的部署大多是内网环境通常没有正规 CA 签发的证书需要自签名。用 openssl 生成证书时容易出现x509: certificate relies on legacy Common Name field的报错因为新版 Docker 和 curl 默认不再信任 CN 字段必须使用 Subject Alternative NameSAN扩展。mkdir -p /data/certs cd /data/certs openssl genrsa -out ca.key 4096 openssl req -new -x509 -days 3650 -key ca.key -out ca.crt -subj /CNHarbor-CA openssl genrsa -out server.key 2048 openssl req -new -key server.key -out server.csr \ -subj /CNregistry.internal.example.com cat ext.cnf EOF subjectAltNameDNS:registry.internal.example.com,IP:192.168.1.100 EOF openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \ -out server.crt -days 3650 -extfile ext.cnf参数说明第一段生成 CA 根证书第二段生成 Harbor 服务器私钥和证书签名请求第三段是关键——ext.cnf里的subjectAltName必须同时包含访问 Harbor 用的域名和 IP否则docker login时会出现证书校验失败。.crt文件和.key文件的权限建议设为 644 和 600Harbor 容器内的 nginx 进程以非 root 用户运行权限过严会导致无法读取。提示如果后续用 IP 访问 HarborIP 必须写进 SAN。只写域名而不写 IP浏览器可以访问但docker login直接报certificate signed by unknown authority的变体错误。4.4 执行 install.sh加载镜像与启动容器配置和证书准备好后运行安装脚本cd /opt/harbor sudo ./install.shinstall.sh会按顺序执行加载harbor.v2.9.0.tar.gz中的所有镜像、运行prepare生成 docker-compose.yml、检查端口占用、最后启动容器。整个加载过程耗时取决于磁盘性能机械硬盘可能需要 5-10 分钟SSD 通常在 2 分钟内完成。如果只需要核心功能registry 管理界面可以在./install.sh后面加--with-trivy等参数按需启动组件。默认情况下只启动核心组件不包含 trivy 和 chartmuseum。我建议首次部署不启用 trivy先保证镜像仓库可用后续需要时再改配置重启。4.5 验证服务状态与控制台登录安装完成后用以下命令确认容器状态docker ps # 期望看到 harbor-core、harbor-registry、harbor-portal 等容器都是 Up 状态 docker compose -f /opt/harbor/docker-compose.yml ps然后访问https://registry.internal.example.com使用默认管理员账号admin登录。默认密码在harbor.yml同目录的harbor.yml文件的harbor_admin_password参数里如果没改就是Harbor12345。首次登录后必须立即修改密码因为 Harbor 的默认密码是公开写死在文档里的内网环境也不能裸奔。登录成功后在「系统管理 → 仓库管理」里添加一个 Docker Hub 镜像代理然后在「项目」里创建一个测试项目验证镜像的上传和拉取功能是否正常。5. 避坑与常见问题排查ARM 环境下最常踩的五个坑5.1 镜像加载报 exec format error现象docker runHarbor 组件镜像时容器创建成功但立即退出docker logs显示exec format error。原因目标机器的 Docker 架构是aarch64但加载的镜像是amd64架构。很可能是下载错了离线包——Harbor 官方从 v2.5.0 之后同时在 release 页面提供 amd64 和 arm64 两个安装包有些第三方镜像源只同步了 amd64 版本。解决检查镜像架构docker inspect 镜像名 | grep Architecture # 如果输出 amd64说明镜像架构不匹配重新下载harbor-offline-installer-v2.9.0-arm64.tgz或者手动用docker pull --platform linux/arm64拉取基础镜像后重新打标签。5.2 prepare 脚本报 Python 版本错误现象./install.sh执行到prepare阶段时报错提示This system does not support Harbor或者出现 Python 语法错误。原因ARM 版 Harbor 的prepare脚本依赖 Python 3.8 以上的语法特性而 Debian 11 等系统的默认 Python 是 3.7或者系统里同时安装了多个 Python 版本prepare的 shebang 指向了错误解释器。解决手动指定 Python 版本并安装pyyaml# 确认 Python 版本 python3 --version # 如果低于 3.8安装更高版本或手动符 pip3 install pyyaml更常见的解决方式是直接修改prepare脚本的 shebang 行指向系统里已有的高版本 Pythonhead -1 prepare # 如果是 #!/usr/bin/env python3改成 #!/usr/bin/python3.9 sudo sed -i s|#!/usr/bin/env python3|#!/usr/bin/python3.9| prepare5.3 docker-compose.yml 未生成导致容器无法启动现象./install.sh执行时提示docker-compose.yml not found或直接报prepare之后找不到 compose 文件。原因prepare脚本执行失败比如 Python 依赖缺失、harbor.yml 格式错误导致 docker-compose.yml 没有被生成。install.sh脚本不会因为 prepare 失败而中断它会继续执行后续步骤导致在空目录下启动容器。解决先手动运行 prepare 看详细报错sudo ./prepare # 观察输出修改 harbor.yml 或修复 Python 依赖后重试harbor.yml 是 YAML 格式注意缩进不能用 Tab布尔值不能写成yes/no必须写成true/false。我遇到过一次因为http:和https:的缩进不一致导致 prepare 报错的情况。5.4 端口被 nginx 或已存在的服务占用现象./install.sh运行时提示listen tcp 0.0.0.0:80: bind: address already in use或者 Harbor 启动后访问不到页面。原因目标机器上已经运行了 nginx、Apache 或其他占用 80/443 端口的服务。ARM 开发板和国产服务器往往预装了 web 服务做管理界面。解决确认占用端口的进程sudo ss -tlnp | grep -E :80|:443 # 输出中能看到占用端口的进程名和 PID改harbor.yml里的端口号把http.port改为 8080、https.port改为 8443或者停掉已有服务。我的习惯是改 Harbor 的端口而不是杀已有服务——生产环境里你永远不知道那个 nginx 是不是承载着别的业务。5.5 磁盘空间不足导致镜像导入失败现象docker load时提示空间不足或者 Harbor 运行一段时间后系统盘满日志出现no space left on device。原因Harbor 的镜像仓库数据、数据库文件和日志都写在data_volume指定的目录如果这个目录和系统盘在同一分区长时间运行会被日志和镜像占满。解决在部署前用df -h确认磁盘挂载情况把 Harbor 和 Docker 的数据目录都放到独立的数据盘。我一般在/etc/docker/daemon.json里把># 在需要访问 Harbor 的客户端机器上操作 sudo mkdir -p /etc/docker/certs.d/registry.internal.example.com:443 sudo cp /data/certs/ca.crt /etc/docker/certs.d/registry.internal.example.com:443/ca.crt sudo systemctl restart docker之后在内网机器上执行docker login registry.internal.example.com输入 Harbor 的用户名密码即可通过校验。这个操作的本质是把 Harbor 的 CA 证书放到 Docker 的证书信任目录目录名必须与hostname:port完全一致少一个端口或改了端口都会导致信任失效。另一个实用技巧是用docker compose命令管理 Harbor 的启停和日志排查。Harbor 的容器全部由/opt/harbor/docker-compose.yml定义手动维护时比install.sh更灵活cd /opt/harbor # 停止所有 Harbor 容器 docker compose stop # 查看所有容器的日志输出 docker compose logs -f --tail100 # 只查看 harbor-core 的日志 docker compose logs -f harbor-coredocker compose logs在排障时比docker logs更好用因为 Harbor 的容器名带有随机后缀用服务名如harbor-core、harbor-registry可以直接过滤。日志文件默认放在/var/lib/docker/containers/容器ID/下但通过 compose 命令查看更方便。最后提一个调优项Harbor 默认使用 PostgreSQL 存储元数据其中registry数据库的blobs表会随镜像数量增长变得很大。如果内网镜像积累超过几百 GB建议定期清理未引用的 blob# 进入 harbor-db 容器执行清理 docker exec -it harbor-db psql -U postgres -d registry # 在 psql 中执行 SELECT COUNT(*) FROM blobs; VACUUM ANALYZE blobs;VACUUM ANALYZE不会删除数据但会回收已删除行占用的空间并更新统计信息让查询计划更优。真正的空间回收需要在 Harbor 的「系统管理 → 垃圾回收」里执行那个操作会扫描并删除未被任何镜像引用的 blob。我通常每两个月做一次先执行VACUUM ANALYZE再触发垃圾回收——从最初一次误操作删掉生产仓库镜像后我所有的清理动作都强制加一步docker compose ps确认容器健康再加一步pg_dump备份数据库希望这个习惯也能帮到你。本文还有配套的精品资源点击获取