简介Harbor v2.7.0 离线安装包arm64位为需要在ARM架构服务器或国产化环境中部署企业级镜像仓库的运维人员、DevOps工程师提供了一体化解决方案。相比在线安装离线包可直接绕过外网限制内置镜像签名、内容信任、RBAC等安全机制适配私有化交付场景。资源包共6个文件包括Shell安装与配置脚本、Harbor主镜像压缩包、许可证、预检文件和yml配置模板整体约704.87MB结构清晰便于快速部署。已有150人学习/下载。借助该包可一键式完成Harbor的离线安装与初始化减少依赖排查和版本兼容成本同时可通过模板灵活调整存储、网络及认证参数Harbor自带的图形界面、审计日志和复制功能也能帮助企业实现多实例容灾与安全合规管理适合企业内网批量交付或教学研究环境搭建。 最近在 ARM64 的 Ubuntu 22.04 服务器上部署镜像仓库手里只有harbor-offline-installer-v2.7.0-arm64.tar.gz这一个离线安装包。文件名看着简单实际装起来却有不少坑架构选错直接exec format error、Docker Compose 版本太老解析不了配置、HTTP 协议登录时被 Docker 拒绝还有“要不要改成 HTTPS”这个绕不开的问题。这篇就把我从解压、配置到跑起来的完整过程写出来包括 HTTP 转 HTTPS 的两种做法和常见报错排查。适合同样要在 ARM64 Linux 环境里离线部署 Harbor 的同学直接参考不用再从头踩一遍。1. 先搞清楚这个离线安装包是什么1.1 文件名拆解harbor-offline-installer-v2.7.0-arm64.tar.gz这个名字其实已经把关键信息都交代清楚了harborHarbor 镜像仓库一个开源的企业级 Docker Registry 管理平台带 Web UI、权限管理、项目隔离、镜像复制扫描这些能力。offline-installer离线安装器区别是online-installer。在线版安装时要从 Docker Hub 拉镜像离线版则把所有需要的镜像打包在安装包里。v2.7.0版本号。arm64CPU 架构说明这个包是给 ARM64 / AArch64 平台准备的。tar.gz压缩包格式需要先解压。我下载这个包是因为目标服务器在客户内网没有外网权限Docker Hub 根本连不上。这种场景下离线包是唯一现实的选择。如果只是自己在本地拿online-installer装外网一断就卡死在拉镜像那一步。1.2 离线包和在线包差在哪在线安装包小因为它的install.sh在安装时要动态拉取goharbor/*的一系列镜像。离线安装包大但它把harbor、nginx、postgresql、redis、trivy这些组件镜像提前打包成了harbor.v2.7.0.tar.gz安装脚本检测到本地有镜像包后直接docker load进去整个安装过程不依赖外网。所以判断依据很简单只要环境是内网或者 Docker Hub 拉取经常不稳定直接选 offline-installer。内网部署时还要把 tar 包通过光盘、USB 或者内网 FTP 传到服务器上这一步倒是没什么技术含量只是文件大传的时候注意校验一下 md5。1.3 arm64 和 amd64 为什么不能混用amd64对应 Intel / AMD 的 x86_64 架构arm64对应 ARM 的 64 位架构。两者的指令集完全不同Harbor 的镜像中很多二进制程序是编译型产物比如registry、core、nginx架构不匹配时 Docker 启动容器就会报exec /usr/bin/registry: exec format error有人会说“我在 x86 上用 QEMU 模拟 arm64 行不行”。模拟确实能跑但那是在用软件翻译指令性能折损大而且 Harbor 一套组件十来个容器每个都要翻译一层内存和 CPU 压力会明显放大日志里还容易出现莫名其妙的超时。建议遵守一个原则什么架构的机器就下什么架构的安装包。先确认再动手。2. 环境准备装之前先做三件事2.1 确认你的 CPU 和操作系统判断机器架构最直接的方式uname -m arch在 ARM64 机器上输出通常是aarch64看到aarch64就说明这台机器是 ARM64 架构和arm64是同一回事可以放心用这个离线包。如果输出是x86_64那就得重新下amd64版本。操作系统方面Harbor 官方没有把 Ubuntu、Debian、CentOS 严格区分开只要内核支持 Docker 就行。我这次用的是 Ubuntu 22.04.5 ARM64整体很顺利。如果看到某个教程里一堆 Ubuntu 换源、安装 e2fsprogs 的操作那是准备基础系统环境时的事跟 Harbor 本身关系不大但也别跳过系统太干净的话缺依赖也闹心。2.2 Docker 与 Docker Compose 版本要求Harbor 2.7.0 依赖 Docker 20.10 以上和 Docker Compose v2。如果机器上装的是 Ubuntu 自带的旧版本docker.ioDocker 引擎版本可能偏低docker-compose甚至可能没装或者装的是老旧的 Python 版1.x。先检查docker --version docker compose versionHarbor 官方推荐用 Docker Compose v2也就是docker compose这种插件式写法。如果执行docker compose version提示找不到命令就先安装sudo apt update sudo apt install -y docker.io docker-compose-v2 sudo systemctl enable --now docker这里有个容易踩坑的地方Ubuntu 的软件源里docker.io版本不算新如果后续安装时提示 Docker 版本不满足要去 Docker 官方 apt 源安装docker-ce。不过在内网环境里只要当前版本能跑起来我一般不追求最新能用就行。2.3 磁盘、内存和端口规划Harbor 离线包解压后占用空间不小数据卷目录也会持续增长。我的最低建议是CPU2 核以上。内存4 GB 以上。低于 2 GB 时 Harbor 的core服务经常会启动失败现象是网页 502。磁盘数据目录独立分区至少 50 GB 空余。如果要做镜像复制和扫描趋势会更大。端口默认 HTTP 80、HTTPS 443如果想改端口要提前确认对应端口没被系统服务占用。在安装前我把防火墙和端口占用都检查了一遍ss -lnpt | grep -E :80|:443 sudo ufw status如果 80 端口被 nginx 占了要么停掉占用服务要么在 Harbor 配置里改成 8080 之类的高位端口。ss检查比netstat在 Ubuntu 22.04 上更顺手。3. 正式安装从解压到把 HTTP 改成 HTTPS3.1 解压和准备配置文件我习惯把 Harbor 放在/opt/harbor下和压缩包分开sudo mkdir -p /opt/harbor sudo tar -zxvf harbor-offline-installer-v2.7.0-arm64.tar.gz -C /opt/harbor cd /opt/harbor/harbor解压后目录里主要文件是harbor.yml.tmpl # 配置模板 harbor.v2.7.0.tar.gz # 组件镜像离线包 install.sh # 安装脚本 prepare # 配置生成工具 common.sh # 脚本公共函数注意解压这个包用的是tar -zxvf不是unzip后缀是 gz 而不是 zip。如果在 Windows 上习惯性右键解压到了 Linux 命令行容易记错。正式配置前先复制模板cp harbor.yml.tmpl harbor.ymlHarbor 启动时只会读harbor.yml直接改模板文件也能跑但不利于以后和升级包对比差异所以规范做法是复制一份再改。3.2 修改 hostname 与基础参数编辑harbor.yml最核心的几项hostname: registry.example.com http: port: 80 https: port: 443 certificate: /data/cert/registry.crt private_key: /data/cert/registry.key harbor_admin_password: Harbor12345 data_volume: /data/harborhostname一定要填会被客户端访问到的域名或 IP不要填localhost否则其他机器执行docker login时地址对不上。如果是内网测试环境可以填服务器 IP比如192.168.1.100。YAML 文件对缩进很敏感http、https下面的子项必须用两个空格缩进别用 Tab。harbor_admin_password是初始管理员密码部署后可以登录 Web 再改但有个坑如果配置里不写这一项install.sh 会自动生成随机密码并打印在屏幕上。要是不小心把这个日志弄丢了后面登录会费劲我一般是显式设置。3.3 快速方案HTTP insecure-registries如果只是内网测试不想折腾证书可以只保留 HTTP 配置把https整段注释掉。直接用 HTTP 有一个连锁问题Docker 客户端默认用 HTTPS 访问 registry。你执行docker login 192.168.1.100时Docker 会尝试访问https://192.168.1.100/v2/而 Harbor 只监听 80 端口于是报错Error response from daemon: Get http://192.168.1.100/v2/: http: server gave HTTP response to HTTPS client解决方式是在 Docker daemon 配置里把这个地址加入insecure-registriessudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json EOF { insecure-registries: [192.168.1.100] } EOF sudo systemctl restart docker这里写192.168.1.100不带端口是因为默认 80 端口可以省略。之后docker login 192.168.1.100就能通过。这个方案速度快适合开发、测试、内网临时环境。3.4 正式方案给 Harbor 配置 HTTPSHTTP 方案在跨网段、多团队、公网场景下不够安全镜像内容会被明文抓包篡改。正式环境建议走 HTTPS而且 Docker 客户端对 HTTPS registry 的兼容性也最好。配置 HTTPS 有两种证书来源企业内网 CA 签发每个客户端都要信任这个 CA适合公司内部统一分发证书。自签名证书只给少数几台机器用每台客户端都要手动配信任。公网证书机构签发适合有公网域名的情况最省事。下面是自签名证书的完整命令在/data/cert下操作sudo mkdir -p /data/cert cd /data/cert # 1. 生成 CA 私钥和自签名根证书 openssl genrsa -out ca.key 4096 openssl req -x509 -new -nodes -sha512 -days 3650 \ -subj /CCN/STBeijing/LBeijing/OExample/OUIT/CNregistry.example.com \ -key ca.key -out ca.crt # 2. 生成 Harbor 服务端私钥和证书请求 openssl genrsa -out registry.key 4096 openssl req -new -sha256 \ -subj /CCN/STBeijing/LBeijing/OExample/OUIT/CNregistry.example.com \ -key registry.key -out registry.csr # 3. 创建扩展文件写入 SAN cat registry.ext EOF authorityKeyIdentifierkeyid,issuer basicConstraintsCA:FALSE keyUsage digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment subjectAltName alt_names [alt_names] DNS.1registry.example.com IP.1192.168.1.100 EOF # 4. 用 CA 签署服务端证书 openssl x509 -req -sha512 -days 3650 \ -extfile registry.ext \ -CA ca.crt -CAkey ca.key -CAcreateserial \ -in registry.csr -out registry.crt不要跳过第三步的 SAN 配置。现在 Docker 新版校验证书会看subjectAltName如果证书里只有CN没有 SAN登录时照样报证书不合法。在harbor.yml里启用 HTTPShttps: port: 443 certificate: /data/cert/registry.crt private_key: /data/cert/registry.key并把http那一段注释掉。注意HTTPS 和 HTTP 不建议同时开启虽然 Harbor 允许但维护两份入口容易造成混淆也增加暴露面。客户端那端要做信任配置。如果用的是自签名 CAsudo mkdir -p /etc/docker/certs.d/registry.example.com sudo cp /data/cert/ca.crt /etc/docker/certs.d/registry.example.com/ca.crt sudo systemctl restart docker/etc/docker/certs.d目录名必须和 registry 地址完全一致如果是 IP 访问就写 IP。这一步让 Docker 在访问registry.example.com时信任我们的 CA就不需要加insecure-registries了。3.5 执行 install.sh 并验证配置好后执行sudo ./install.sh整个安装过程分三个阶段生成配置、加载离线镜像、启动所有容器。中间会打印很多日志看到最后出现✔ ----Harbor has been installed and started successfully----就可以验证了docker compose ps正常情况下能看到harbor-core、harbor-portal、harbor-registry、nginx、postgresql、redis等容器处于running状态。然后在一台客户端机器上执行docker login registry.example.com输入 admin 账号密码看到Login Succeeded就说明整个链路通了。浏览器访问https://registry.example.com时如果证书不受信任会提示风险把ca.crt导入浏览器信任列表即可。4. 常见问题与排查速查表4.1 镜像启动报 exec format errorexec /usr/bin/registry: exec format error这个问题十有八九是架构不匹配。我在 ARM64 机器上见过有人误下amd64包还在怀疑系统环境有问题。排查步骤uname -m docker images | grep harbor docker inspect 镜像ID | grep Architecture最后一条命令能直接看到镜像声明的架构。如果系统是aarch64而镜像架构是amd64重新到 Harbor 官方发布页下载arm64的离线包即可。顺带说一句如果你手上只有 x86 电脑想通过 QEMU 模拟 arm64 并部署 Harbor我建议只把它当功能验证别当生产方案中文环境里很多教程不强调这点结果装完才发现慢到没法用。4.2 Docker 登录报 HTTP/HTTPS 协议错误分两种情况http: server gave HTTP response to HTTPS client这是 Harbor 在用 HTTP但 Docker 在尝试 HTTPS。处理方式是往daemon.json的insecure-registries里加地址重启 Docker。x509: certificate signed by unknown authority这是 Harbor 在用 HTTPS但客户端不信任证书。处理方式是把 CA 证书放到/etc/docker/certs.d/registry地址/ca.crt下。两种情况不要搞混否则会来回折腾。4.3 端口被占用、502、数据目录权限端口被占用启动 nginx 容器失败docker compose logs nginx里能看到bind: address already in use。先ss -lnpt看端口归属再决定停服务还是改 Harbor 端口。网页 502最常见是内存不足导致harbor-core起不来docker compose logs core能看到退出。加内存到 4 GB 后docker compose up -d再试。数据目录权限/data/harbor属于 root但容器内进程可能不是 root 用户。遇到 Permission denied 时把数据目录属主调整一下sudo chown -R 10000:10000 /data/harborHarbor 容器内部常用 UID 10000 来运行这是官方镜像的惯例。4.4 旧版 docker-compose 不兼容报错形如ERROR: The Compose file ./docker-compose.yml is invalid because: Unsupported config option for services.harbor: ...这是 docker-compose 1.x 的问题它解析不了新版 Harbor 生成的 compose 文件。解决sudo apt remove docker-compose sudo apt install -y docker-compose-v2 docker compose version装好后确认docker compose命令可用再重新跑./install.sh。这里我踩过坑就是压根没装 docker-compose-v2运行 install.sh 时脚本报找不到 docker compose当时以为是脚本坏了其实只是插件没装。4.5 修改了配置但没生效改harbor.yml后直接docker compose up -d是不行的Harbor 需要通过prepare工具把配置重新渲染出来docker compose down sudo ./prepare sudo docker compose up -d改了证书、端口、hostname 这些关键参数时都要走这套流程。直接重启单个容器通常没用我最初没想到这点改完配置怎么重启都是老配置看日志才反应过来。5. 关于 ARM64 部署的几点体感建议整套走下来我的体感是 Harbor 官方对 ARM64 的支持已经比较成熟了只要安装包下载对、Docker 和 Compose 版本到位流程跟 x86 没有本质区别。有几个细节值得特别提醒下载离线包前先确认包文件完整。tar解压报unexpected EOF时往往是传输过程中文件损坏重新传一遍就行别急着怀疑系统。内网环境如果要用 HTTPS一次把 CA 证书和certs.d目录配好比后续一堆机器挨个补insecure-registries更省事。Harbor 的 Web 界面只负责管理真正给 Docker 用的其实是内置的registry组件。平时排查优先看harbor-core和nginx日志这两个容器能解释大多数登录和访问问题。ARM64 的机器架构标识通常显示为aarch64不要因为名字里没有 arm64 就以为包下错了。如果后面踩到不常见的坑先记住一条排查路径uname -m确认架构docker compose ps看状态docker compose logs --tail 100 服务名看日志再加内存和磁盘。Harbor 部署本身不复杂但前置条件缺一个后面就是连环坑。本文还有配套的精品资源点击获取