简介：面向需要在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版实际操作中更快的办法是直接检查镜像包的manifest：
tar -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编排起来的一套系统，核心组件包括：
- core：Harbor的核心API服务
- portal：Web管理界面
- registry：镜像存储与分发，底层是Docker Distribution
- jobservice：异步任务处理
- database：PostgreSQL，存元数据
- 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里的password：PostgreSQL的密码
- redis的password：Redis的密码
我在帮别人排查时发现，很多人只改了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 解压并执行准备脚本
环境准备好后，正式进入安装。先把离线包放到计划安装的目录，我习惯放/opt：
cd /opt tar -zxvf harbor-offline-installer-v2.9.0.tgz cd harbor在真正install之前，先跑一遍prepare脚本：
./prepareprepare脚本的作用是：校验harbor.yml配置、生成docker-compose.yml、生成各类内部证书和密钥文件。很多人跳过prepare直接install，install脚本其实也会自动调用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正常状态是各个服务显示Up，health状态慢慢从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版本再save：
docker 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 docker |
| docker compose缺失或版本低 | docker: 'compose' is not a docker command | 安装docker compose v2插件 |
| Python版本低 | SyntaxError: invalid syntax | 确认python3版本，安装Python 3.6+ |
| OpenSSL缺失 | openssl: command not found | 安装openssl和openssl-devel |
| 磁盘空间不足 | no space left on device | df -h检查数据盘，清理或扩容 |
| 端口冲突 | address already in use | ss -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留一份输出，记录正常状态下的容器列表和健康状态，以后机器重启或环境异常时，拿出来对比一下就能快速定位问题。
本文还有配套的精品资源，点击获取
