简介面向需要在ARM64架构服务器上离线部署镜像仓库Harbor的运维或开发人员一份v2.9.0版本离线安装包专为无外网或内网受限环境设计是信创场景下搭建私有镜像仓库的实用物料。资源共6个文件以shell脚本、gz压缩包及配置文件为主install.sh与common.sh负责一键安装与公共逻辑gz离线镜像包为核心安装内容另有license、prepare和harbor.yml.tmpl配置模板覆盖从环境检查、配置生成到镜像加载、服务启动的完整流程。整个压缩包约722MB体量适中。使用前仅需预先安装Docker与Docker Compose然后执行install.sh即可完成部署大幅降低手动搭建门槛。该资源已有959人学习下载适合在国产化ARM平台中快速落地Harbor尤其适用于离线交付、内网生产环境及需要自建镜像仓库的中高级运维工程师。 如果你手上正好有一台ARM架构的服务器又需要在完全隔离的内网里部署一套Harbor私有镜像仓库这篇文章应该能帮你少走不少弯路。Harbor是目前企业里用得最多的开源镜像仓库之一v2.9.0这个版本在稳定性和功能上都比较适中而ARM架构下的离线安装因为缺少现成文档和二进制包往往比x86机器上要多折腾几个小时。这篇文章我会从环境确认、离线包选择、配置文件修改、安装执行到常见问题排查完整走一遍harbor-v2.9.0在arm64机器上的离线安装过程。适合正在做内网环境交付的运维、需要在ARM服务器上搭建镜像仓库的开发以及第一次接触Harbor但不想踩坑的新手。我会把每个步骤背后的原因也讲清楚这样你遇到问题时不至于只会照着抄还能自己判断问题出在哪一环。1. 安装前的准备工作与整体思路1.1 先确认机器架构和系统版本很多人拿到安装包就开始解压执行结果跑到一半才发现架构不对白忙活。第一步一定是确认机器架构uname -m # 在ARM64机器上会输出 aarch64注意aarch64就是ARM的64位架构Harbor的镜像、安装脚本都是按这个标识来区分架构的。如果输出结果是x86_64那你下载的就是另一套离线包下面讲的内容同样适用只是选包时要换x86版本。接着看系统发行版和版本cat /etc/os-release不同发行版会影响两个关键点一是Docker和docker compose的安装方式二是OpenSSL、Python等工具链的默认版本。Harbor的prepare脚本依赖Python和OpenSSL如果系统很老比如CentOS 7默认Python 2.7跑prepare时可能会遇到兼容性问题需要提前装好Python 3.6。1.2 离线安装包怎么选、怎么校验Harbor官方每个release版本都会提供离线安装包v2.9.0的完整文件名一般是harbor-offline-installer-v2.9.0.tgz。这个包的特点是把Harbor运行所需的全部Docker镜像打包在一个tar文件里安装时通过docker load本地加载不需要访问外网。在ARM机器上选包时要特别留意架构。Harbor官方release页面的Assets里有些版本会直接提供arm64专用离线包有些版本只提供默认的x86_64包。判断方法很简单下载后先解压看一下里面的镜像tar是否包含ARM架构的镜像tar -zxvf harbor-offline-installer-v2.9.0.tgz cd harbor tar -tf harbor.v2.9.0.tar.gz | head -20 # 若镜像tar包内manifest.json中均为amd64架构则这不是ARM版实际操作中更快的办法是直接检查镜像包的manifesttar -xOf harbor.v2.9.0.tar.gz manifest.json | python3 -m json.tool | grep -i architecture | sort -u输出如果都是amd64说明这个离线包只能在x86_64机器上直接安装。这对ARM机器是个坑后面我会专门讲怎么处理。校验完整性也不能省。GitHub release页面每个安装包都会给一个.sha256后缀的校验文件下载后执行sha256sum harbor-offline-installer-v2.9.0.tgz和自己算出来的值对比不一致说明文件损坏或下载不完整。离线包通常有1GB以上下载中断是常事别省这一步。1.3 磁盘空间、内存和Docker版本底线Harbor离线安装最容易被忽视的就是磁盘空间。离线包本身约1GB多解压后增加约2GB镜像docker load时又需要一份空间真正跑起来后镜像数据、数据库、日志都会写在data_volume目录下。我的建议是/opt或数据盘所在分区至少预留50GB生产环境建议100GB以上。检查命令df -h再说Docker版本。Harbor v2.9.0要求Docker 18.06.0以上docker compose插件建议使用v2版本。安装前务必确认docker version --format {{.Server.Version}} docker compose version docker-compose version # 旧版兼容写法有则更好我在实际环境里见过好几次Docker老版本导致容器启动后网络异常的情况Harbor的容器网络依赖Docker内置DNS和自定义网络版本太老会出很诡异的问题比如服务都起来了但UI页面登录不了。1.4 离线安装的整体思路Harbor本质上是多个容器服务通过docker compose编排起来的一套系统核心组件包括coreHarbor的核心API服务portalWeb管理界面registry镜像存储与分发底层是Docker Distributionjobservice异步任务处理databasePostgreSQL存元数据redis缓存trivy漏洞扫描v2.9.0默认的扫描引擎离线安装做的事情本质上就三步把离线包里的镜像tar全部docker load进本机然后基于harbor.yml生成docker-compose配置最后用docker compose把容器全部拉起来。理解了这个逻辑你在排查问题时就知道该往哪个方向找镜像没加载成功、配置生成失败、还是容器起不来。2. Harbor配置文件的深度拆解2.1 hostname与端口规划是第一个大坑解压后的目录里有两个配置文件模板harbor.yml和harbor.yml.tmpl。先复制一份再改cp harbor.yml.tmpl harbor.yml vim harbor.yml开头这段是必须改的hostname: registry.example.com http: port: 80hostname不能用localhost或127.0.0.1。这个值会被写进Harbor内部服务的访问地址、镜像推送地址的回显还会用于生成证书的CN字段。如果你写localhost本机docker login也许能用但其他机器访问你的仓库时推送命令里的地址就是localhost根本连不通。我建议这里直接写这台服务器的内网IP比如192.168.1.100或者一个能被所有客户端解析的域名。如果后续要走HTTPS必须是域名或固定IP因为自签证书是按这个字段生成的。hostname: 192.168.1.100 http: port: 8080端口方面很多内网机器的80端口已经被占了或者出于安全策略不允许用80那就改成8080这类高位端口。但要注意如果改端口docker login时就必须带上端口比如docker login 192.168.1.100:8080。2.2 密码和数据目录的坑继续往下看Harbor.yml里有三处密码要主动设置harbor_admin_password管理员密码默认是Harbor12345必须改且不能太短database里的passwordPostgreSQL的密码redis的passwordRedis的密码我在帮别人排查时发现很多人只改了admin密码database和redis还是默认值。这在暴露到网络上的环境里是安全隐患因为Harbor的容器端口如果被映射到公网数据库和Redis就可能被直接访问。建议三个密码一起改掉并记录好。data_volume是Harbor所有持久化数据的存放目录data_volume: /data/harbor建议不用默认的./data而是放到独立的挂载数据盘避免系统盘满了把整个机器搞挂。后面做备份、迁移时也只要打包这个目录。2.3 从HTTP改HTTPS的关键配置热搜词里有一个很典型的诉求Harbor的HTTP协议改成HTTPS。默认配置走的是HTTP密码在网络上明文传输这对镜像仓库这种核心系统来说不够安全。而且不少内网的K8s集群拉取镜像时containerd或kubelet会强制校验仓库证书没有HTTPS根本拉不下来。改HTTPS不复杂核心是生成证书和修改harbor.yml两件事。先给自己生成一张自签证书mkdir -p /data/cert cd /data/cert openssl genrsa -out ca.key 2048 openssl req -new -x509 -days 3650 -key ca.key -out ca.crt openssl genrsa -out server.key 2048 openssl req -new -key server.key -out server.csr openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 3650然后修改harbor.yml关键动作是注释掉HTTP段、启用HTTPS段hostname: 192.168.1.100 # http: # port: 8080 https: port: 443 certificate: /data/cert/server.crt private_key: /data/cert/server.key这里有个细节我经常强调证书路径必须是Harbor机器上的绝对路径且Harbor的prepare脚本和容器都需要读这个文件。如果提示permission denied先把证书目录的权限放开一点比如chmod 755 cert目录。改完配置后重新生成配置并启动./prepare docker compose down -v # 只有在首次修改配置时才需要已有数据时慎用-v docker compose up -d客户端docker login时如果是自签证书会报x509错误。解决办法有两个推荐第一个把ca.crt拷贝到客户端的/etc/docker/certs.d/ : /目录下mkdir -p /etc/docker/certs.d/192.168.1.100:443 cp ca.crt /etc/docker/certs.d/192.168.1.100:443/ systemctl restart docker这样Docker就会信任你的自签证书。第二个办法是在客户端的/etc/docker/daemon.json里配置insecure-registries但这样等于跳过证书校验不建议在生产用。3. 离线安装全流程实战3.1 解压并执行准备脚本环境准备好后正式进入安装。先把离线包放到计划安装的目录我习惯放/optcd /opt tar -zxvf harbor-offline-installer-v2.9.0.tgz cd harbor在真正install之前先跑一遍prepare脚本./prepareprepare脚本的作用是校验harbor.yml配置、生成docker-compose.yml、生成各类内部证书和密钥文件。很多人跳过prepare直接installinstall脚本其实也会自动调用prepare但提前跑一遍能尽早暴露问题。ARM机器上常见的一个报错是Python版本太低prepare脚本本身是Python写的某些旧系统上会报语法错误。处理办法是确保系统默认python3版本在3.6以上。3.2 执行install.sh并选择合适的组件接下来是核心命令./install.sh不带任何参数时默认安装的是基础组件core、portal、registry、jobservice、database、redis。如果还需要漏洞扫描加上--with-trivy./install.sh --with-trivyHarbor v2.9.0使用的扫描引擎是Trivy。离线环境下漏洞扫描有个需要特别注意的问题Trivy启动后默认会尝试从外部下载漏洞数据库如果下载不了扫描器会一直处于未就绪状态。后面我会专门讲这个问题。install.sh执行过程中主要做三件事先docker load离线包里的所有镜像再调用prepare最后docker compose up -d启动全部容器。整个镜像加载过程可能会持续几分钟取决于磁盘IO如果你看到卡在load那一步很久不要慌是正常的。到这里可以验证一下镜像和容器状态docker images | grep -E goharbor|trivy docker compose ps正常状态是各个服务显示Uphealth状态慢慢从healthy开始变化刚启动时有些服务还在初始化给个一二十秒再观察。3.3 验证Harbor是否真正可用容器全部起来只是第一步还要验证功能。首先验证UI浏览器访问https://192.168.1.100或你设置的域名和端口用admin和设置的管理员密码登录UI能打开只能说明portal服务正常还要验证API和镜像推送curl -k https://192.168.1.100/api/v2.0/ping # 返回 Pong 说明API正常接着在UI里创建一个测试项目比如叫test然后在本机或任意客户端做一次完整的登录和推送docker login 192.168.1.100 -u admin docker tag nginx:latest 192.168.1.100/test/nginx:v1 docker push 192.168.1.100/test/nginx:v1 docker pull 192.168.1.100/test/nginx:v1能push能pull这个Harbor才算是真正装好了。4. 常见问题与排查技巧实录这里整理几个我在ARM离线安装Harbor时真正踩过、以及帮别人排查过的典型问题按出现频率排序。4.1 ARM机器上容器报exec format error这是ARM离线安装最典型的坑。现象是docker load一切正常但容器一启动就反复重启日志里能看到exec format error或not found。原因离线包里的镜像是x86_64架构。Harbor官方离线包默认构建在amd64平台如果你在ARM机器上直接装load进去的镜像在运行时根本无法被内核执行。判断方法docker inspect --format {{.Architecture}} goharbor/harbor-core:v2.9.0解决思路有两种。第一种去GitHub release页面找专门的arm64离线包有些版本社区或官方会额外发布arm64版本。第二种如果确实没有现成arm64包就得自己构建镜像列表在能联网的ARM机器上按docker-compose.yml里的镜像清单逐一拉取arm64版本再savedocker pull --platform linux/arm64 goharbor/harbor-core:v2.9.0 docker save goharbor/harbor-core:v2.9.0 -o harbor-core.v2.9.0.tar然后把所有arm64的镜像tar合并替换到离线包的harbor.v2.9.0.tar.gz中再重新install。这种做法工作量不小所以我在前面反复强调下载离线包前一定要确认架构这是ARM机器安装Harbor时最重要的一步没有之一。4.2 docker login报x509证书错误docker login 192.168.1.100 Error response from daemon: Get https://192.168.1.100/v2/: x509: certificate signed by unknown authority原因很明确用了自签证书客户端不信任。解决方式在2.3节已经写过核心就是让客户端把你的ca.crt加到Docker的信任列表里或者临时用insecure-registries绕过。注意insecure-registries要在daemon.json里配置后重启Docker{ insecure-registries: [192.168.1.100:443] }重启后docker login应该就能通过。但这里有个隐患HTTPS证书的CN必须和访问域名或IP一致否则即使加了信任列表也会报IP不匹配的错误。所以自签证书的CN字段一定要用你实际访问Harbor的地址。4.3 Trivy漏洞扫描器一直未就绪或镜像扫不了症状是UI里漏洞扫描页面一直转圈或者扫描任务卡住。原因在于Trivy引擎启动时需要从外部拉取漏洞数据库离线环境拉不到自然就扫不了。Harbor v2.9.0的离线包其实会尝试打包一份Trivy离线数据库但很多情况下数据库版本和漏洞库不匹配或者数据目录没挂对。我的建议是如果你的使用场景不强制要求漏洞扫描先在install.sh时不加--with-trivy先把镜像仓库稳定跑起来这是最省事的做法。如果确实需要扫描可以在有外网的办公网络环境里把Trivy的离线数据库文件下载好再根据Harbor官方文档放到Trivy容器挂载的指定数据目录下。这个操作对Harbor版本比较敏感我没有办法给一个放之四海而皆准的路径需要以你下载的v2.9.0离线包实际解压出来的说明为准。4.4 prepare或install.sh常见的环境类报错我整理了实际中最常见的几个做成速查表问题典型报错排查思路Docker版本过低Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?检查docker version、systemctl status dockerdocker compose缺失或版本低docker: compose is not a docker command安装docker compose v2插件Python版本低SyntaxError: invalid syntax确认python3版本安装Python 3.6OpenSSL缺失openssl: command not found安装openssl和openssl-devel磁盘空间不足no space left on devicedf -h检查数据盘清理或扩容端口冲突address already in usess -ltnp查看端口占用改harbor.yml端口这些环境类问题的排查逻辑其实很一致Harbor的install.sh依赖Docker CLI、docker compose、Python3、OpenSSL四样基础工具缺哪个补哪个装完后重新跑install.sh就行。我已经不止一次看到有人在prepare报错后慌着从头再来其实只需要补齐依赖再执行一次最多五分钟的事。4.5 卸载重装的操作要点ARM机上反复调试配置很常见卸载重装时有个地方要特别小心不要一上来就把data_volume整个删掉特别是你已经存了镜像的情况下。正确的卸载顺序是cd /opt/harbor docker compose down # 停止并删除容器保留数据卷如果要彻底重置确认数据不需要备份后docker compose down -v rm -rf /data/harbor # 数据目录谨慎操作这个顺序能避免你在调试时误删了已经推送进去的镜像数据。我个人在实际部署中最大的体会是ARM离线安装Harbor九成的问题都出现在安装前的确认工作上尤其是镜像架构和Docker环境这两件事确认到位后面基本就是按部就班地执行命令而已。很多人在坑里浪费时间不是因为操作复杂而是因为一开始就跳过了前置检查。动手之前把系统架构、磁盘空间、Docker版本、离线包架构这四个基础项核对一遍比任何技巧都管用。最后再补充一个小操作装好之后第一时间用docker compose ps留一份输出记录正常状态下的容器列表和健康状态以后机器重启或环境异常时拿出来对比一下就能快速定位问题。本文还有配套的精品资源点击获取 
长河君 · 2026/9/8 9:22:02 · 阅读 1.2k ARM架构下Harbor v2.9.0离线安装全攻略：内网部署避坑指南
简介面向需要在ARM64架构服务器上离线部署镜像仓库Harbor的运维或开发人员一份v2.9.0版本离线安装包专为无外网或内网受限环境设计是信创场景下搭建私有镜像仓库的实用物料。资源共6个文件以shell脚本、gz压缩包及配置文件为主install.sh与common.sh负责一键安装与公共逻辑gz离线镜像包为核心安装内容另有license、prepare和harbor.yml.tmpl配置模板覆盖从环境检查、配置生成到镜像加载、服务启动的完整流程。整个压缩包约722MB体量适中。使用前仅需预先安装Docker与Docker Compose然后执行install.sh即可完成部署大幅降低手动搭建门槛。该资源已有959人学习下载适合在国产化ARM平台中快速落地Harbor尤其适用于离线交付、内网生产环境及需要自建镜像仓库的中高级运维工程师。 如果你手上正好有一台ARM架构的服务器又需要在完全隔离的内网里部署一套Harbor私有镜像仓库这篇文章应该能帮你少走不少弯路。Harbor是目前企业里用得最多的开源镜像仓库之一v2.9.0这个版本在稳定性和功能上都比较适中而ARM架构下的离线安装因为缺少现成文档和二进制包往往比x86机器上要多折腾几个小时。这篇文章我会从环境确认、离线包选择、配置文件修改、安装执行到常见问题排查完整走一遍harbor-v2.9.0在arm64机器上的离线安装过程。适合正在做内网环境交付的运维、需要在ARM服务器上搭建镜像仓库的开发以及第一次接触Harbor但不想踩坑的新手。我会把每个步骤背后的原因也讲清楚这样你遇到问题时不至于只会照着抄还能自己判断问题出在哪一环。1. 安装前的准备工作与整体思路1.1 先确认机器架构和系统版本很多人拿到安装包就开始解压执行结果跑到一半才发现架构不对白忙活。第一步一定是确认机器架构uname -m # 在ARM64机器上会输出 aarch64注意aarch64就是ARM的64位架构Harbor的镜像、安装脚本都是按这个标识来区分架构的。如果输出结果是x86_64那你下载的就是另一套离线包下面讲的内容同样适用只是选包时要换x86版本。接着看系统发行版和版本cat /etc/os-release不同发行版会影响两个关键点一是Docker和docker compose的安装方式二是OpenSSL、Python等工具链的默认版本。Harbor的prepare脚本依赖Python和OpenSSL如果系统很老比如CentOS 7默认Python 2.7跑prepare时可能会遇到兼容性问题需要提前装好Python 3.6。1.2 离线安装包怎么选、怎么校验Harbor官方每个release版本都会提供离线安装包v2.9.0的完整文件名一般是harbor-offline-installer-v2.9.0.tgz。这个包的特点是把Harbor运行所需的全部Docker镜像打包在一个tar文件里安装时通过docker load本地加载不需要访问外网。在ARM机器上选包时要特别留意架构。Harbor官方release页面的Assets里有些版本会直接提供arm64专用离线包有些版本只提供默认的x86_64包。判断方法很简单下载后先解压看一下里面的镜像tar是否包含ARM架构的镜像tar -zxvf harbor-offline-installer-v2.9.0.tgz cd harbor tar -tf harbor.v2.9.0.tar.gz | head -20 # 若镜像tar包内manifest.json中均为amd64架构则这不是ARM版实际操作中更快的办法是直接检查镜像包的manifesttar -xOf harbor.v2.9.0.tar.gz manifest.json | python3 -m json.tool | grep -i architecture | sort -u输出如果都是amd64说明这个离线包只能在x86_64机器上直接安装。这对ARM机器是个坑后面我会专门讲怎么处理。校验完整性也不能省。GitHub release页面每个安装包都会给一个.sha256后缀的校验文件下载后执行sha256sum harbor-offline-installer-v2.9.0.tgz和自己算出来的值对比不一致说明文件损坏或下载不完整。离线包通常有1GB以上下载中断是常事别省这一步。1.3 磁盘空间、内存和Docker版本底线Harbor离线安装最容易被忽视的就是磁盘空间。离线包本身约1GB多解压后增加约2GB镜像docker load时又需要一份空间真正跑起来后镜像数据、数据库、日志都会写在data_volume目录下。我的建议是/opt或数据盘所在分区至少预留50GB生产环境建议100GB以上。检查命令df -h再说Docker版本。Harbor v2.9.0要求Docker 18.06.0以上docker compose插件建议使用v2版本。安装前务必确认docker version --format {{.Server.Version}} docker compose version docker-compose version # 旧版兼容写法有则更好我在实际环境里见过好几次Docker老版本导致容器启动后网络异常的情况Harbor的容器网络依赖Docker内置DNS和自定义网络版本太老会出很诡异的问题比如服务都起来了但UI页面登录不了。1.4 离线安装的整体思路Harbor本质上是多个容器服务通过docker compose编排起来的一套系统核心组件包括coreHarbor的核心API服务portalWeb管理界面registry镜像存储与分发底层是Docker Distributionjobservice异步任务处理databasePostgreSQL存元数据redis缓存trivy漏洞扫描v2.9.0默认的扫描引擎离线安装做的事情本质上就三步把离线包里的镜像tar全部docker load进本机然后基于harbor.yml生成docker-compose配置最后用docker compose把容器全部拉起来。理解了这个逻辑你在排查问题时就知道该往哪个方向找镜像没加载成功、配置生成失败、还是容器起不来。2. Harbor配置文件的深度拆解2.1 hostname与端口规划是第一个大坑解压后的目录里有两个配置文件模板harbor.yml和harbor.yml.tmpl。先复制一份再改cp harbor.yml.tmpl harbor.yml vim harbor.yml开头这段是必须改的hostname: registry.example.com http: port: 80hostname不能用localhost或127.0.0.1。这个值会被写进Harbor内部服务的访问地址、镜像推送地址的回显还会用于生成证书的CN字段。如果你写localhost本机docker login也许能用但其他机器访问你的仓库时推送命令里的地址就是localhost根本连不通。我建议这里直接写这台服务器的内网IP比如192.168.1.100或者一个能被所有客户端解析的域名。如果后续要走HTTPS必须是域名或固定IP因为自签证书是按这个字段生成的。hostname: 192.168.1.100 http: port: 8080端口方面很多内网机器的80端口已经被占了或者出于安全策略不允许用80那就改成8080这类高位端口。但要注意如果改端口docker login时就必须带上端口比如docker login 192.168.1.100:8080。2.2 密码和数据目录的坑继续往下看Harbor.yml里有三处密码要主动设置harbor_admin_password管理员密码默认是Harbor12345必须改且不能太短database里的passwordPostgreSQL的密码redis的passwordRedis的密码我在帮别人排查时发现很多人只改了admin密码database和redis还是默认值。这在暴露到网络上的环境里是安全隐患因为Harbor的容器端口如果被映射到公网数据库和Redis就可能被直接访问。建议三个密码一起改掉并记录好。data_volume是Harbor所有持久化数据的存放目录data_volume: /data/harbor建议不用默认的./data而是放到独立的挂载数据盘避免系统盘满了把整个机器搞挂。后面做备份、迁移时也只要打包这个目录。2.3 从HTTP改HTTPS的关键配置热搜词里有一个很典型的诉求Harbor的HTTP协议改成HTTPS。默认配置走的是HTTP密码在网络上明文传输这对镜像仓库这种核心系统来说不够安全。而且不少内网的K8s集群拉取镜像时containerd或kubelet会强制校验仓库证书没有HTTPS根本拉不下来。改HTTPS不复杂核心是生成证书和修改harbor.yml两件事。先给自己生成一张自签证书mkdir -p /data/cert cd /data/cert openssl genrsa -out ca.key 2048 openssl req -new -x509 -days 3650 -key ca.key -out ca.crt openssl genrsa -out server.key 2048 openssl req -new -key server.key -out server.csr openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 3650然后修改harbor.yml关键动作是注释掉HTTP段、启用HTTPS段hostname: 192.168.1.100 # http: # port: 8080 https: port: 443 certificate: /data/cert/server.crt private_key: /data/cert/server.key这里有个细节我经常强调证书路径必须是Harbor机器上的绝对路径且Harbor的prepare脚本和容器都需要读这个文件。如果提示permission denied先把证书目录的权限放开一点比如chmod 755 cert目录。改完配置后重新生成配置并启动./prepare docker compose down -v # 只有在首次修改配置时才需要已有数据时慎用-v docker compose up -d客户端docker login时如果是自签证书会报x509错误。解决办法有两个推荐第一个把ca.crt拷贝到客户端的/etc/docker/certs.d/ : /目录下mkdir -p /etc/docker/certs.d/192.168.1.100:443 cp ca.crt /etc/docker/certs.d/192.168.1.100:443/ systemctl restart docker这样Docker就会信任你的自签证书。第二个办法是在客户端的/etc/docker/daemon.json里配置insecure-registries但这样等于跳过证书校验不建议在生产用。3. 离线安装全流程实战3.1 解压并执行准备脚本环境准备好后正式进入安装。先把离线包放到计划安装的目录我习惯放/optcd /opt tar -zxvf harbor-offline-installer-v2.9.0.tgz cd harbor在真正install之前先跑一遍prepare脚本./prepareprepare脚本的作用是校验harbor.yml配置、生成docker-compose.yml、生成各类内部证书和密钥文件。很多人跳过prepare直接installinstall脚本其实也会自动调用prepare但提前跑一遍能尽早暴露问题。ARM机器上常见的一个报错是Python版本太低prepare脚本本身是Python写的某些旧系统上会报语法错误。处理办法是确保系统默认python3版本在3.6以上。3.2 执行install.sh并选择合适的组件接下来是核心命令./install.sh不带任何参数时默认安装的是基础组件core、portal、registry、jobservice、database、redis。如果还需要漏洞扫描加上--with-trivy./install.sh --with-trivyHarbor v2.9.0使用的扫描引擎是Trivy。离线环境下漏洞扫描有个需要特别注意的问题Trivy启动后默认会尝试从外部下载漏洞数据库如果下载不了扫描器会一直处于未就绪状态。后面我会专门讲这个问题。install.sh执行过程中主要做三件事先docker load离线包里的所有镜像再调用prepare最后docker compose up -d启动全部容器。整个镜像加载过程可能会持续几分钟取决于磁盘IO如果你看到卡在load那一步很久不要慌是正常的。到这里可以验证一下镜像和容器状态docker images | grep -E goharbor|trivy docker compose ps正常状态是各个服务显示Uphealth状态慢慢从healthy开始变化刚启动时有些服务还在初始化给个一二十秒再观察。3.3 验证Harbor是否真正可用容器全部起来只是第一步还要验证功能。首先验证UI浏览器访问https://192.168.1.100或你设置的域名和端口用admin和设置的管理员密码登录UI能打开只能说明portal服务正常还要验证API和镜像推送curl -k https://192.168.1.100/api/v2.0/ping # 返回 Pong 说明API正常接着在UI里创建一个测试项目比如叫test然后在本机或任意客户端做一次完整的登录和推送docker login 192.168.1.100 -u admin docker tag nginx:latest 192.168.1.100/test/nginx:v1 docker push 192.168.1.100/test/nginx:v1 docker pull 192.168.1.100/test/nginx:v1能push能pull这个Harbor才算是真正装好了。4. 常见问题与排查技巧实录这里整理几个我在ARM离线安装Harbor时真正踩过、以及帮别人排查过的典型问题按出现频率排序。4.1 ARM机器上容器报exec format error这是ARM离线安装最典型的坑。现象是docker load一切正常但容器一启动就反复重启日志里能看到exec format error或not found。原因离线包里的镜像是x86_64架构。Harbor官方离线包默认构建在amd64平台如果你在ARM机器上直接装load进去的镜像在运行时根本无法被内核执行。判断方法docker inspect --format {{.Architecture}} goharbor/harbor-core:v2.9.0解决思路有两种。第一种去GitHub release页面找专门的arm64离线包有些版本社区或官方会额外发布arm64版本。第二种如果确实没有现成arm64包就得自己构建镜像列表在能联网的ARM机器上按docker-compose.yml里的镜像清单逐一拉取arm64版本再savedocker pull --platform linux/arm64 goharbor/harbor-core:v2.9.0 docker save goharbor/harbor-core:v2.9.0 -o harbor-core.v2.9.0.tar然后把所有arm64的镜像tar合并替换到离线包的harbor.v2.9.0.tar.gz中再重新install。这种做法工作量不小所以我在前面反复强调下载离线包前一定要确认架构这是ARM机器安装Harbor时最重要的一步没有之一。4.2 docker login报x509证书错误docker login 192.168.1.100 Error response from daemon: Get https://192.168.1.100/v2/: x509: certificate signed by unknown authority原因很明确用了自签证书客户端不信任。解决方式在2.3节已经写过核心就是让客户端把你的ca.crt加到Docker的信任列表里或者临时用insecure-registries绕过。注意insecure-registries要在daemon.json里配置后重启Docker{ insecure-registries: [192.168.1.100:443] }重启后docker login应该就能通过。但这里有个隐患HTTPS证书的CN必须和访问域名或IP一致否则即使加了信任列表也会报IP不匹配的错误。所以自签证书的CN字段一定要用你实际访问Harbor的地址。4.3 Trivy漏洞扫描器一直未就绪或镜像扫不了症状是UI里漏洞扫描页面一直转圈或者扫描任务卡住。原因在于Trivy引擎启动时需要从外部拉取漏洞数据库离线环境拉不到自然就扫不了。Harbor v2.9.0的离线包其实会尝试打包一份Trivy离线数据库但很多情况下数据库版本和漏洞库不匹配或者数据目录没挂对。我的建议是如果你的使用场景不强制要求漏洞扫描先在install.sh时不加--with-trivy先把镜像仓库稳定跑起来这是最省事的做法。如果确实需要扫描可以在有外网的办公网络环境里把Trivy的离线数据库文件下载好再根据Harbor官方文档放到Trivy容器挂载的指定数据目录下。这个操作对Harbor版本比较敏感我没有办法给一个放之四海而皆准的路径需要以你下载的v2.9.0离线包实际解压出来的说明为准。4.4 prepare或install.sh常见的环境类报错我整理了实际中最常见的几个做成速查表问题典型报错排查思路Docker版本过低Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?检查docker version、systemctl status dockerdocker compose缺失或版本低docker: compose is not a docker command安装docker compose v2插件Python版本低SyntaxError: invalid syntax确认python3版本安装Python 3.6OpenSSL缺失openssl: command not found安装openssl和openssl-devel磁盘空间不足no space left on devicedf -h检查数据盘清理或扩容端口冲突address already in usess -ltnp查看端口占用改harbor.yml端口这些环境类问题的排查逻辑其实很一致Harbor的install.sh依赖Docker CLI、docker compose、Python3、OpenSSL四样基础工具缺哪个补哪个装完后重新跑install.sh就行。我已经不止一次看到有人在prepare报错后慌着从头再来其实只需要补齐依赖再执行一次最多五分钟的事。4.5 卸载重装的操作要点ARM机上反复调试配置很常见卸载重装时有个地方要特别小心不要一上来就把data_volume整个删掉特别是你已经存了镜像的情况下。正确的卸载顺序是cd /opt/harbor docker compose down # 停止并删除容器保留数据卷如果要彻底重置确认数据不需要备份后docker compose down -v rm -rf /data/harbor # 数据目录谨慎操作这个顺序能避免你在调试时误删了已经推送进去的镜像数据。我个人在实际部署中最大的体会是ARM离线安装Harbor九成的问题都出现在安装前的确认工作上尤其是镜像架构和Docker环境这两件事确认到位后面基本就是按部就班地执行命令而已。很多人在坑里浪费时间不是因为操作复杂而是因为一开始就跳过了前置检查。动手之前把系统架构、磁盘空间、Docker版本、离线包架构这四个基础项核对一遍比任何技巧都管用。最后再补充一个小操作装好之后第一时间用docker compose ps留一份输出记录正常状态下的容器列表和健康状态以后机器重启或环境异常时拿出来对比一下就能快速定位问题。本文还有配套的精品资源点击获取