企业官网建设流程全解析

简介：面向ARM64架构的Harbor v2.8.2离线安装包，专为需要在ARM环境（如边缘计算、物联网、国产化服务器）中部署企业级容器镜像仓库的运维与开发人员准备。包内包含完整的安装脚本、离线镜像包、配置模板及准备脚本，共6个文件，压缩包整体约639.65MB，可在无外网或网络受限的隔离环境中顺利完成安装，无需在线拉取镜像，特别适合内网私有化部署场景。资源适用于对Harbor已有一定基础、需要快速在ARM64平台上落地镜像管理服务的团队，安装后可启用用户权限控制、镜像复制、漏洞扫描等企业功能，满足生产级镜像生命周期管理需求。目前已有254人学习使用，包内脚本与模板组织清晰，安装流程自动化程度高，许可证及镜像文件一应俱全，能够显著缩短部署与调试周期，帮助用户快速构建稳定高效的容器镜像管理环境，降低ARM平台落地的复杂度。 前一阵子在给一台ARM64服务器搭内网镜像仓库，环境完全离线，拿到的输入物就一个：harbor-offline-installer-v2.8.2-arm64.tar.gz。这个包解决了我的核心痛点——不用联网拉镜像，也不用在ARM板子上现编译，解压后跑脚本就能把Harbor v2.8.2完整拉起来。本来是奔着“三步搞定”去的，结果在证书配置、docker client信任、开机自启上折腾了不少时间。这篇文章就把我从拿到这个离线包到最终稳定运行的全过程拆开讲，覆盖了架构确认、依赖安装、HTTPS/HTTP配置、install.sh执行细节和常见坑，适合正在ARM环境（比如鲲鹏、飞腾、树莓派、ARM云主机）上部署Harbor的运维和开发同学参考。

1. 先搞清楚这个离线包，到底解决了什么问题

1.1 ARM服务器为什么需要专门的Harbor包

很多第一次接触ARM服务器的人容易忽略一个事实：Harbor本身是分架构发布的。官方发布页会同时提供amd64、arm64、ppc64le、s390x等不同架构的离线包，而不是一个包通吃。因为Harbor由一堆容器组成，这些容器镜像里的二进制程序必须和宿主机CPU指令集匹配。

你拿到的这个harbor-offline-installer-v2.8.2-arm64.tar.gz，从文件名就能读出来三层意思：

• arm64：这个包里的镜像全部是linux/arm64/v8 架构，适用于aarch64 CPU。
• v2.8.2：Harbor版本是2.8.2。
• offline-installer：所有镜像都提前打包好放在压缩包里，安装时不依赖外网。

如果你的服务器是x86_64，那应该去下载文件名里带amd64的包。反过来，ARM机器上如果强行用amd64包，容器运行时会直接报exec format error，这个我在后面第5节会专门讲。

提示：uname -m输出aarch64就是arm64，输出x86_64就是amd64。这是选包时最基础的一步，但也是最常出错的一步。

1.2 离线包和在线安装包怎么选

Harbor官方提供两种安装方式：在线安装包（online installer）和离线安装包（offline installer）。两者区别很直接：

• 在线安装包：压缩包只有几MB，只包含安装脚本和配置模板，安装时要从Docker Hub拉取Harbor的全部镜像。适合测试环境，且机器能访问外网。
• 离线安装包：压缩包几百MB到1GB以上，里面除了安装脚本，还包括所有Harbor组件镜像的tar包，如harbor-core、harbor-registry、harbor-portal、harbor-nginx等，安装时通过docker load导入镜像。

选择离线包的核心场景就是生产内网。很多企业机房的ARM服务器不能访问外网，或者安全策略不允许直接从Docker Hub拉镜像。这时候离线包就是唯一选择，因为它把“拉镜像”这一步提前到了你下载包的这台机器上。

我当时选择离线包还有一个原因：在线安装时如果网络不稳定，Docker拉镜像跑到一半断了，重来很麻烦。离线包在导入镜像时是本地磁盘I/O，速度和稳定性都可控。

1.3 v2.8.2版本有哪些值得关注的变化

Harbor 2.x系列整体架构相对成熟，v2.8.x算是比较稳定的一个版本线。我选择v2.8.2而不是更新的版本，主要考虑两点：

• 稳定性优先：2.8.2是2.8系列的一个补丁版本，修复了之前一些安全问题，相比大版本刚发布时更适合生产。
• 依赖门槛适中：它对Docker Engine版本要求没那么苛刻，17.06.0以上即可，Docker Compose V2插件也能用，兼容性较好。

另外一个细节：Harbor v2.8已经支持通过harbor.yml同时配置HTTP和HTTPS，但默认配置模板harbor.yml.tmpl打开后，http和https两段都在，注释状态不同。安装时install.sh会根据你配置的内容生成最终的Docker Compose文件。这一点在后面配置时会具体说。

2. 安装前的准备工作：架构确认、依赖安装、包校验

2.1 确认机器架构与操作系统

拿到包后，先别急着解压。第一步是在目标服务器上执行：

uname -m

如果输出是aarch64，说明系统是arm64架构，这个包没问题。如果输出是x86_64，那你下错包了。

另外要看系统发行版。Harbor离线包本身是跨发行版的，底层用Docker跑，所以Ubuntu、Debian、CentOS、openEuler理论上都行。但不同发行版的Docker安装方式不一样。我这里用的Ubuntu 22.04 arm64 server，这也是目前ARM服务器上比较常见的组合。

再检查内核版本：

uname -r

Harbor对内核没有硬性版本要求，但如果内核太老（比如3.x），Docker本身就跑不起来。建议至少Linux Kernel 4.4以上。

2.2 安装Docker与Compose插件

Harbor offline installer没有内置Docker，它依赖宿主机已经装好Docker。在Ubuntu 22.04 arm64上，安装Docker最省事的方案：

sudo apt update sudo apt install -y docker.io docker-compose-v2

Ubuntu软件源里的docker.io版本可能不是最新，但对Harbor v2.8.2来说完全够用。装完检查：

docker --version docker compose version

如果docker compose提示找不到命令，可能是软件源里包名不同，或者你需要手动装Docker Compose V2插件。这里有个坑：Harbor的install.sh会优先用docker compose（V2插件），如果没有，再找docker-compose（V1独立二进制）。老系统上如果只有V1版本，执行./install.sh有可能报错。解决办法很简单：

sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-linux-aarch64" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose

不过在不能访问外网的机器上，curl下载可能也走不通。更稳妥的做法是用发行版自带的包管理器装好Compose V2，再在harbor目录下执行的install.sh一般能识别到。

2.3 校验安装包完整性

离线包动辄几百MB，传输过程中可能损坏，所以拿到包之后第一件事就是算哈希，不要跳过。

sha256sum harbor-offline-installer-v2.8.2-arm64.tar.gz

把计算出来的哈希值和官方release页面上的sha256sum.txt对照。一致再解压，不一致就重新传输。

这一步看起来多余，但你真踩到一次“解压到一半报错”或者“load镜像时提示tar包损坏”的坑就知道值了。我第一次在ARM机器上部署时，就是因为包从移动硬盘拷贝过来时扇区有问题，后面排错花了一个多小时。

2.4 磁盘、内存与目录规划

Harbor离线包解压后，harbor目录下会有一个harbor.v2.8.2.tar.gz，这是所有Harbor组件镜像的归档文件，通常有几百MB。安装后Harbor的容器数据、数据库、镜像存储会占用更多空间。

建议给Harbor预留至少50GB磁盘空间。如果还要存大量镜像，根据镜像量规划更大的数据盘。默认情况下，Harbor的持久化数据在/data目录（harbor.yml里配置的data_volume），包括数据库和registry存储。安装前先把数据目录挂到大容量磁盘上。

查看资源：

free -h df -h

最低配置：2核CPU、4GB内存。如果是生产环境，建议4核8GB起步。Harbor由内部多个容器组成，其中PostgreSQL和Registry相对吃内存，内存太小很容易在某一步容器启动失败。

3. 动手安装：从解压到Harbor跑起来

3.1 解压并生成harbor.yml配置文件

把离线包上传到/opt目录，然后解压：

cd /opt tar -zxvf harbor-offline-installer-v2.8.2-arm64.tar.gz cd harbor

解压后目录里有一个harbor.yml.tmpl模板文件。复制一份：

cp harbor.yml.tmpl harbor.yml

打开harbor.yml，最核心的几项配置：

hostname: 192.168.1.100 http: port: 8080 harbor_admin_password: Harbor12345 data_volume: /data

hostname可以直接写IP，也可以写域名。要特别注意：这里写什么，后续docker login就登录什么。如果写的是域名，域名必须能解析到这个机器；如果写IP，就登录IP。

3.2 配置HTTP访问和HTTPS证书（关键一步）

这是很多人会卡住的地方，也是Harbor最常见的调整点。默认模板中http和https两段都会被读取，install.sh会判断：如果你配置了https，就启用HTTPS；如果你只保留http，就启用HTTP。

这里根据你的实际场景选择：

场景A：内网环境用HTTP，简单省事

保留：

http: port: 8080

把https整段注释掉（注意YAML缩进，整段用#注释）。这样做的问题是：所有客户端机器上的Docker都要配置insecure-registries，否则docker login会报HTTPS错误。

场景B：有域名和证书，直接上HTTPS

如果你有正式证书（或者测试环境用的自签名证书），先把证书和私钥放到指定目录，比如：

mkdir -p /data/cert cp harbor.crt /data/cert/ cp harbor.key /data/cert/

然后在harbor.yml中配置：

https: port: 443 certificate: /data/cert/harbor.crt private_key: /data/cert/harbor.key

同时把上面http那段注释掉，或者保留一个不同的端口用于同时监听。Harbor支持同时开HTTP和HTTPS，但一般不用。

我当时为了让开发机上的docker能直接docker login，一开始用了HTTP模式，后来发现每次都要给新同事配daemon.json，太烦了，索性生成了自签名证书改成HTTPS，然后在各客户端也信任了这个证书。实际用下来，HTTPS比HTTP省心。

注意：自签名证书会导致客户端报x509: certificate signed by unknown authority，需要在每台客户端机器的/etc/docker/daemon.json里把Harbor地址加入insecure-registries，或者在系统里安装根证书。如果你有企业内部的CA证书，那是最好的方案。

3.3 运行install.sh，等待镜像导入

配置好harbor.yml后，直接执行：

sudo ./install.sh

脚会做几件事：

1. 检查Docker和docker compose是否可用；
2. 加载harbor.v2.8.2.tar.gz里的镜像；
3. 根据harbor.yml生成docker-compose.yml；
4. 创建并启动Harbor所有容器。

第一次执行会看到类似Loaded image: goharbor/...的大量输出，这是在本地导入镜像。镜像加载完成后，容器启动大约需要1~2分钟。安装脚本最后会显示✔ ----Harbor has been installed and started successfully----。

如果中间报错，别慌，检查Screen输出。常见卡点在第5节说。

Harbor装好后，会有这些容器在跑：

harbor-core harbor-registry harbor-registryctl harbor-portal harbor-nginx harbor-log harbor-jobservice harbor-db harbor-redis

核心是harbor-nginx，它负责统一入口，对外暴露HTTP/HTTPS端口，再把请求转发给portal和core。

3.4 验证服务状态和Web界面

安装完成后，用以下命令确认容器都处于Up状态：

docker ps

然后打开浏览器访问：

https://192.168.1.100 # 如果你配置的是HTTP+8080端口，则访问 http://192.168.1.100:8080

默认管理员账号是admin，密码就是你在harbor.yml中设置的harbor_admin_password。

登录进去后，建议先建一个项目，比如叫test-project，然后从命令行验证整个拉推链路。这里我先不展开，下一节讲客户端配置。

4. 部署后必做的三件事：配置docker、开机自启、日常运维

4.1 让docker客户端信任Harbor地址

无论你是HTTP还是HTTPS模式，客户端机器上都要让Docker“认”这个仓库地址。

HTTP模式：在每台客户端机器的/etc/docker/daemon.json中加：

{ "insecure-registries": ["192.168.1.100:8080"] }

然后重启Docker：

sudo systemctl restart docker

这样做的原理是：Docker客户端默认用HTTPS访问所有registry地址，如果发现仓库返回的是HTTP响应，就会拒绝认证。insecure-registries的作用是告诉Docker：这个地址可以跳过HTTPS。

HTTPS模式且使用正式CA证书：不需要额外配置，直接：

docker login https://192.168.1.100

HTTPS模式且使用自签名证书：还是要把这个地址加入insecure-registries，或者让客户端信任你的自签名CA。二选一，前者简单，后者更安全。

登录完成后，就可以推送镜像了：

docker tag nginx:latest 192.168.1.100:8080/test-project/nginx:v1 docker push 192.168.1.100:8080/test-project/nginx:v1 docker pull 192.168.1.100:8080/test-project/nginx:v1

4.2 设置Harbor服务自启动

Harbor本身没有自动注册systemd服务，服务器重启后不会自动拉起所有容器。如果你不希望每次重启都手动进目录执行docker compose up -d，建议做一个Systemd Unit。

在/etc/systemd/system/harbor.service里写：

[Unit] Description=Harbor Container Registry After=docker.service Requires=docker.service [Service] Type=oneshot RemainAfterExit=yes WorkingDirectory=/opt/harbor ExecStart=/usr/bin/docker compose up -d ExecStop=/usr/bin/docker compose down TimeoutStartSec=0 [Install] WantedBy=multi-user.target

然后：

sudo systemctl daemon-reload sudo systemctl enable harbor sudo systemctl start harbor

注意docker compose的路径，Ubuntu 22.04上一般是/usr/bin/docker，但有些系统Compose插件安装后docker compose是ok的，而systemd里建议写完整路径。如果不确定，执行which docker查询。

另外，docker compose down会停止并移除容器，但不会删除/data下的数据，所以用于日常维护是安全的。

4.3 备份与升级注意点

Harbor的数据都在data_volume下，包括数据库、证书、registry存储。日常备份最简单粗暴的方式是直接备份整个/data目录。但要注意：如果Harbor正在运行，直接拷贝文件有可能导致数据不一致。稳妥的做法是先停掉Harbor再备份：

cd /opt/harbor sudo docker compose down sudo tar -czf /backup/harbor-data-$(date +%F).tar.gz /data sudo docker compose up -d

升级场景要特别留意：从旧版本升级到v2.8.2时，官方要求先备份数据库，然后运行新版离线包里的./upgrade.sh脚本。升级脚本会尝试更新数据库schema，旧版本的数据通常能兼容，但不排除部分插件不向下兼容。我自己在v2.5升v2.8的时候，数据库迁移大约花了10分钟，期间服务不可用，建议放在维护窗口做。

5. 常见问题与排查技巧实录

5.1 在qemu模拟的arm64环境里安装时，容器报exec format error

有一种情况很典型：你手上没有物理ARM机器，想先用QEMU模拟ARM64环境测试。如果你是用qemu-system-aarch64跑一个完整的ARM虚拟机，然后在虚拟机里装Docker和Harbor，这种没问题。

真正会踩坑的是：在x86_64宿主机上直接安装arm64的容器镜像，或者用docker run --platform linux/arm64强行模拟。Docker会尝试用qemu-user翻译ARM指令，但Harbor的容器里有一些二进制程序，在非原生ARM环境下很容易报：

standard_init_linux.go:228: exec user process caused: exec format error

这不是Harbor的问题，而是架构不匹配。生产环境不要试图用各种模拟方式跑ARM包，老老实实用真机或同一架构的云主机。

5.2 docker login报http: server gave HTTP response to HTTPS client

这个报错信息基本是“因”的。完整报错通常在：

Error response from daemon: Get "http://192.168.1.100:8080/v2/": http: server gave HTTP response to HTTPS client

原因就是我前面说的，Docker客户端默认走HTTPS，而你的Harbor配置的是HTTP。解决方法是修改客户端的/etc/docker/daemon.json，把Harbor地址加到insecure-registries，然后重启Docker。注意重启Docker会使当前运行的容器全部重启，建议在维护时间操作。

5.3 install.sh提示“docker: command not found”或者compose版本不对

Harbor的install.sh对Docker和Compose的检测比较严格。如果执行时提示找不到docker，可能是当前用户没有/usr/bin/docker的执行路径，或者你用非root用户跑脚本但Docker不在PATH里。解决方法：

export PATH=$PATH:/usr/bin:/usr/local/bin sudo ./install.sh

如果提示docker compose version不支持，查看harbor目录里的common.sh，它会在安装时生成临时脚本。最简单的确认方法是执行：

docker compose version docker-compose --version

两个至少有一个可用。两个都没有，先装Compose V2插件。

5.4 安装后服务起不来，或者nginx报502

如果docker ps显示有个别容器反复重启，或者访问页面时502，通常原因有三类：

1. hostname配置异常：Harbor内部容器之间通过harbor.yml里的hostname互相通信。如果hostname写的是一个无法解析的域名，nginx转发到core时可能失败。最简单的解决办法是先用IP当hostname。
2. 磁盘空间不足：docker exec harbor-db df -h /看看，如果目录满了，PostgreSQL会启动失败。
3. harbor-core启动慢：首次启动时core要初始化数据库，耗时较长。如果nginx容器起来了，core还没起来，浏览器访问会502。等1~2分钟再刷新。

排查时看日志最直接：

docker logs harbor-core --tail 100 docker logs harbor-nginx --tail 100

大部分问题在日志里能找到根因。

5.5 离线包里的镜像load失败

安装脚本如果报Error processing tar file，说明离线包里的镜像归档文件可能损坏。这时候回到第2.3节，重新校验整个tar.gz的SHA256，确认无误后再解压。如果包是在Windows下解压再传到Linux的，建议在Linux下重新解压一次，避免文件权限和符号链接丢失。

最后再分享一点我的体会

用这个harbor-offline-installer-v2.8.2-arm64.tar.gz在ARM环境部署Harbor，难点不在安装本身，而在于环境差异。同样一个包，在Ubuntu上顺利跑起来，换到另一个发行版可能就卡在Compose插件上。我的习惯是：不管什么机器，安装前先把Docker和Compose的版本确认好，再动Harbor。另外，包虽然写着offline，但你在下载阶段最好找一个网络好的机器，下载后立刻用SHA256校验。等到内网环境再发现问题，浪费的可不只是带宽。最后一个小技巧：安装后立刻把harbor.yml备份一份，附上一段注释写明hostname、证书路径是什么时候配置的，下次升级或者迁移时你会感谢当时的自己。

本文还有配套的精品资源，点击获取