arm64离线部署Harbor 2.13.1：从踩坑到跑通全指南

简介：这份资源是面向 ARM 架构服务器环境的 Harbor 2.13.1 离线安装包，适合需要在国产化平台或 ARM 服务器上私有化部署容器镜像仓库的运维与 DevOps 人员。包内共 6 个文件，以 shell 脚本、配置模板、压缩镜像包和许可证文件为主，其中安装脚本与准备脚本负责部署流程，模板文件用于生成服务配置，镜像压缩包则承载 Harbor 各核心组件，整体约 513.28MB，可脱离外网直接完成安装。资源围绕 Harbor 的离线部署场景组织，读者可借此在 ARM 环境下快速搭建镜像仓库，理解组件构成与配置项含义，并掌握离线安装的排错思路。目前已有 414 人学习下载，适合具备一定 Linux 与容器基础、需要落地 ARM 私有仓库的中高级用户参考。

1. arm环境harbor2.13.1离线包：从踩坑到跑通，一个包解决的事

在国产化替代和信创项目里，arm架构服务器上部署私有镜像仓库已经成了标配需求。harbor-offline-installer-v2.13.1-arm64.tgz 这个包，说白了就是把 Harbor 2.13.1 在 arm64 平台上跑起来所需的所有镜像、二进制和配置模板打成一个压缩包，让你在没有外网、没有 Docker Hub 拉取权限的内网环境里，也能把镜像仓库完整搭起来。我见过太多人在 x86 上搭 Harbor 轻车熟路，一换到鲲鹏、飞腾或者麒麟系统的 arm64 机器上就翻车——要么 docker compose 拉不到镜像，要么镜像架构不对跑不起来，要么离线包解压后 install.sh 直接报错退出。这个包解决的就是这三个问题：架构匹配、离线可用、版本锁定。适合谁看？正在做信创迁移的后端运维、需要在 arm 服务器上搭建 CI/CD 镜像仓库的 DevOps、以及第一次接触 arm 环境 Harbor 部署的工程师。下面把我自己从零跑通的完整路径拆开讲，包括参数怎么调、坑在哪、怎么验证。

2. 先搞清楚这个离线包里到底装了什么

2.1 为什么 arm64 的 Harbor 不能直接用 x86 的包

Harbor 的离线安装包本质上是一组 Docker 镜像的 tar 归档加上编排脚本。x86 的包里所有镜像都是 amd64 架构，你把它拿到 arm64 机器上，docker load 能成功，但 docker run 的时候会直接报exec format error，因为镜像里的二进制指令集不匹配。这不是配置问题，是 CPU 指令集层面的硬性不兼容。arm64 和 x64 的区别在这里体现得非常直接：x64 用 CISC，arm64 用 RISC，编译出来的机器码完全不同。所以 harbor-offline-installer-v2.13.1-arm64.tgz 这个包的核心价值就在于，里面每一个镜像——harbor-core、harbor-portal、harbor-jobservice、harbor-registry、harbor-db、redis、nginx——全部是 arm64 架构编译的。你拿到包之后第一件事应该是确认这一点，而不是急着解压安装。

# 解压离线包 tar -xzf harbor-offline-installer-v2.13.1-arm64.tgz # 进入解压目录 cd harbor # 查看包内镜像清单文件（如果有的话） ls -lh harbor.v2.13.1.tar.gz # 确认当前机器架构 uname -m # 期望输出：aarch64 或 arm64

逻辑说明：tar -xzf解压后你会看到 harbor 目录，里面包含harbor.v2.13.1.tar.gz（镜像归档）、harbor.yml.tmpl（配置模板）、install.sh（安装脚本）、prepare（环境准备脚本）。uname -m必须输出 aarch64 或 arm64，如果是 x86_64 说明你拿错机器了。参数上没什么可调的，但这一步不做后面全是白费功夫。

2.2 离线包的目录结构和关键文件

解压后的目录结构是固定的，每个文件都有明确用途。我列一个表，你对照着看：

这里有个容易忽略的点：harbor.yml.tmpl是模板，你不能直接改它然后跑 install.sh，必须先cp harbor.yml.tmpl harbor.yml，再编辑 harbor.yml。install.sh 读的是 harbor.yml，不是 tmpl。这个设计是为了让你升级的时候能保留自己的配置，但第一次部署的人经常在这里翻车。

# 复制配置模板 cp harbor.yml.tmpl harbor.yml # 编辑关键配置 vi harbor.yml

需要改的核心参数就几个：hostname改成你的服务器 IP 或域名，harbor_admin_password设一个强密码，data_volume指定数据存储路径（默认 /data，如果磁盘空间不够要改），port默认 80 和 443，如果被占用要改。其他像 database、jobservice、log 这些保持默认即可，除非你有特殊需求。

3. 在 arm64 机器上跑通 Harbor 的完整步骤

3.1 前置依赖：Docker 和 Docker Compose 的 arm64 版本

Harbor 2.13.1 依赖 Docker Engine 和 Docker Compose。在 arm64 机器上，这两个东西的安装方式和 x86 略有不同。很多国产 Linux 发行版（麒麟、统信）的默认源里 Docker 版本偏旧，建议用官方二进制包安装。Docker Compose 必须是 v2 版本，v1 的 python 版本在 arm64 上经常出问题。

# 安装 Docker（以二进制方式，适用于无外网或源不可用的情况） # 假设你已经下载了 docker-27.0.3.tgz 的 arm64 版本 tar -xzf docker-27.0.3.tgz cp docker/* /usr/bin/ # 启动 Docker 守护进程 dockerd & # 或者用 systemd 管理 systemctl start docker systemctl enable docker # 验证 Docker 版本和架构 docker version docker info | grep -i architecture # 期望看到：Architecture: aarch64 # 安装 Docker Compose v2 # 下载 docker-compose-linux-aarch64 cp docker-compose-linux-aarch64 /usr/local/bin/docker-compose chmod +x /usr/local/bin/docker-compose # 验证 docker-compose version # 期望输出：Docker Compose version v2.x.x

逻辑说明：Docker 的 arm64 二进制包解压后所有可执行文件在 docker/ 目录下，直接复制到 /usr/bin/ 即可。docker info里的 Architecture 字段必须显示 aarch64，如果显示 x86_64 说明你装错了包。Docker Compose 的二进制文件命名通常是docker-compose-linux-aarch64，复制到 PATH 里并加执行权限。参数上注意：如果你用 systemd 管理 Docker，需要自己写 unit 文件或者用发行版提供的包。

3.2 配置 harbor.yml 的五个必调参数

harbor.yml 里有几十个配置项，但第一次部署真正需要动的就五个。我把它们和常见取值列出来：

# 1. hostname：必须改成实际访问地址 hostname: 192.168.1.100 # 2. http 端口：默认 80，被占用改成其他 http: port: 8080 # 3. https：如果没有证书，先注释掉整个 https 块 # https: # port: 443 # certificate: /your/certificate/path # private_key: /your/private/key/path # 4. harbor_admin_password：初始管理员密码 harbor_admin_password: Harbor12345 # 5. data_volume：数据存储路径 data_volume: /data

逻辑说明：hostname决定你通过什么地址访问 Harbor 的 Web UI 和推送拉取镜像，写 IP 或域名都行，但一旦确定后面改起来麻烦，因为镜像地址会变。http.port如果 80 被 nginx 或其他服务占了，改成 8080 之类的。https块如果你没有正式证书，直接注释掉，Harbor 会只跑 HTTP，内网环境够用了。harbor_admin_password是 admin 用户的初始密码，第一次登录后可以改。data_volume默认 /data，如果 /data 所在分区空间不够，改成大分区的路径，比如 /opt/harbor-data。

注意：harbor.yml 里所有缩进必须是空格，不能用 Tab。YAML 对缩进敏感，一个 Tab 就能让 install.sh 报解析错误。

3.3 执行 install.sh 并验证服务状态

配置改完之后，执行安装脚本。这个脚本会做几件事：检查 Docker 和 Docker Compose、加载镜像归档、生成最终配置、启动所有容器。

# 执行安装 ./install.sh # 如果一切正常，你会看到类似输出： # [Step 0]: checking if docker is installed ... # [Step 1]: checking docker-compose is installed ... # [Step 2]: loading Harbor images ... # [Step 3]: preparing environment ... # [Step 4]: preparing harbor configs ... # [Step 5]: starting Harbor ... # ----Harbor has been installed and started successfully.---- # 验证容器状态 docker-compose ps # 期望看到 9 个容器都是 Up 状态 # 验证 Web UI 可访问 curl -I http://192.168.1.100:8080 # 期望返回 HTTP/1.1 200 OK

逻辑说明：./install.sh不带参数时默认执行完整安装流程。如果中途报错，最常见的三个原因：Docker 没启动、端口被占用、harbor.yml 格式错误。docker-compose ps会列出所有 Harbor 相关容器，正常情况应该有 harbor-core、harbor-db、harbor-jobservice、harbor-portal、harbor-registry、harbor-registryctl、nginx、redis、harbor-exporter 这 9 个。如果有容器状态是 Exit 或 Restarting，用docker-compose logs <服务名>看日志。curl -I返回 200 说明 nginx 和 harbor-portal 正常。

4. 避坑指南：arm 环境 Harbor 部署的五个血泪教训

4.1 坑一：docker load 报错 “no space left on device”

现象：执行 install.sh 到 Step 2 加载镜像时，终端输出no space left on device，脚本退出。

原因：Harbor 2.13.1 的镜像归档解压后大约 2.5GB，加载到 Docker 后占用更多空间。默认 Docker 数据目录在 /var/lib/docker，如果 /var 分区小，直接爆盘。

解决：先df -h看 /var/lib/docker 所在分区剩余空间，至少留 10GB。不够的话，改 Docker 数据目录到大数据分区：编辑 /etc/docker/daemon.json，加"data-root": "/opt/docker"，然后systemctl restart docker。注意改之前先把已有镜像和容器清理掉，否则 Docker 启动会报错。

4.2 坑二：install.sh 报 “Cannot connect to the Docker daemon”

现象：脚本第一步检查 Docker 时就失败，提示无法连接 Docker 守护进程。

原因：Docker 服务没启动，或者当前用户没有权限访问 Docker socket。

解决：systemctl status docker确认服务状态，没启动就systemctl start docker。如果是权限问题，把当前用户加入 docker 组：usermod -aG docker $USER，然后重新登录。注意在 arm64 的麒麟系统上，Docker 的 systemd unit 文件可能叫docker.service也可能叫docker.socket，用systemctl list-units | grep docker确认。

4.3 坑三：Web UI 能打开但推送镜像报 “connection refused”

现象：浏览器能访问 Harbor 页面，但docker push或docker pull时提示连接被拒绝。

原因：Docker 客户端默认走 HTTPS 推送，但你的 Harbor 只配了 HTTP。Docker 对非 HTTPS 的 registry 需要显式信任。

解决：编辑 /etc/docker/daemon.json，加"insecure-registries": ["192.168.1.100:8080"]，然后systemctl restart docker。注意 IP 和端口要和你 harbor.yml 里的 hostname 和 http.port 完全一致。改完之后docker info应该能看到 Insecure Registries 列表里有你的地址。

4.4 坑四：harbor-db 容器反复重启

现象：docker-compose ps显示 harbor-db 状态是 Restarting，其他容器正常。

原因：PostgreSQL 数据目录权限不对，或者之前部署过 Harbor 残留了旧数据。arm64 环境下，如果 data_volume 指向的目录是从 x86 机器迁移过来的，文件权限和所有者可能不匹配。

解决：先docker-compose down -v停掉所有容器并删除数据卷，然后检查data_volume指向的目录，确保是空的或者权限为 999:999（Harbor 的 postgres 用户 UID）。如果目录里有旧数据且你不需要保留，直接rm -rf /data/database再重新./install.sh。

4.5 坑五：install.sh 执行成功但 8080 端口访问不了

现象：脚本输出 “Harbor has been installed and started successfully”，但浏览器打不开页面，curl 也超时。

原因：防火墙没放行端口，或者 nginx 容器绑定的端口和你以为的不一样。

解决：firewall-cmd --list-ports看端口有没有放行，没有就firewall-cmd --add-port=8080/tcp --permanent && firewall-cmd --reload。如果是 iptables，用iptables -L -n | grep 8080检查。另外docker-compose ps里 nginx 容器的端口映射列会显示实际绑定，确认是0.0.0.0:8080->8080/tcp而不是127.0.0.1:8080->8080/tcp。如果是后者，说明 harbor.yml 里 hostname 配成了 localhost，改成实际 IP 重新 prepare。

5. 进阶技巧：离线环境下的镜像同步与版本升级验证

5.1 用 skopeo 在 arm64 机器间同步镜像

Harbor 跑起来之后，你可能会遇到多台 arm64 机器需要共享镜像的场景。没有外网的情况下，可以用 skopeo 直接从一台 Harbor 同步到另一台，不需要经过本地 Docker daemon。

# 安装 skopeo（arm64 版本） # 假设你已经有了 skopeo 的 arm64 二进制 cp skopeo /usr/local/bin/ chmod +x /usr/local/bin/skopeo # 从源 Harbor 复制镜像到目标 Harbor skopeo copy \ --src-tls-verify=false \ --dest-tls-verify=false \ --src-creds admin:SourcePassword \ --dest-creds admin:DestPassword \ docker://192.168.1.100:8080/library/nginx:latest \ docker://192.168.1.101:8080/library/nginx:latest # 验证目标 Harbor 里的镜像 skopeo inspect --tls-verify=false \ --creds admin:DestPassword \ docker://192.168.1.101:8080/library/nginx:latest

逻辑说明：skopeo copy直接在两个 registry 之间传输镜像层，不落地到本地磁盘，适合离线环境批量同步。--src-tls-verify=false和--dest-tls-verify=false是因为内网 Harbor 通常用自签证书或纯 HTTP。--src-creds和--dest-creds分别是源和目标的认证信息。skopeo inspect用来确认镜像确实同步过去了，返回的 JSON 里能看到架构信息，确认是 arm64 而不是 amd64。

5.2 验证离线包完整性的三个命令

拿到 harbor-offline-installer-v2.13.1-arm64.tgz 之后，别急着解压安装，先做三个验证，能省掉后面很多麻烦。

# 1. 校验文件完整性（如果你有官方提供的 sha256 值） sha256sum harbor-offline-installer-v2.13.1-arm64.tgz # 2. 查看压缩包内容，确认关键文件都在 tar -tzf harbor-offline-installer-v2.13.1-arm64.tgz | head -20 # 3. 解压后检查镜像归档的架构 tar -xzf harbor-offline-installer-v2.13.1-arm64.tgz cd harbor docker load -i harbor.v2.13.1.tar.gz docker images | grep harbor # 查看每个镜像的架构标签，确认没有 amd64

逻辑说明：sha256sum用来确认下载的包没有损坏，如果你是从内部文件服务器拿的包，这一步尤其重要。tar -tzf不解压只列出内容，快速确认 harbor.yml.tmpl、install.sh、harbor.v2.13.1.tar.gz 都在。docker load之后docker images列出的镜像，虽然不直接显示架构，但你可以用docker inspect <image> | grep Architecture逐个确认。如果发现任何一个镜像是 amd64，说明这个包不是真正的 arm64 离线包，后面肯定跑不起来。

5.3 我自己的习惯：部署完先做一次推送拉取闭环测试

每次部署完 Harbor，我不会只看 Web UI 能不能打开，而是立刻做一次完整的推送拉取测试。这个习惯帮我提前发现了无数次配置问题。

# 打标签 docker tag nginx:latest 192.168.1.100:8080/library/nginx:test # 推送 docker push 192.168.1.100:8080/library/nginx:test # 删掉本地镜像 docker rmi 192.168.1.100:8080/library/nginx:test # 重新拉取 docker pull 192.168.1.100:8080/library/nginx:test # 如果推送和拉取都成功，说明 Harbor 完全正常

这个闭环测试覆盖了认证、存储、网络三个环节。推送成功说明 harbor-core 和 harbor-registry 正常，拉取成功说明数据持久化没问题。如果推送报 413 错误，是 nginx 的 client_max_body_size 太小，改 harbor.yml 里的相关配置或者直接在 nginx 容器里调。如果拉取报 manifest unknown，说明 registry 存储有问题，看 harbor-registry 的日志。

提示：测试完记得把 test 标签的镜像从 Harbor 里删掉，不然时间长了仓库里全是垃圾标签。

我在 arm64 环境部署 Harbor 最大的教训就是：不要假设 x86 上的经验能直接平移。架构差异带来的问题往往不是配置层面的，而是二进制层面的，排查起来更费时间。所以每次拿到新包，先验架构、再验完整性、最后跑闭环测试，这三步做完，后面基本不会出大问题。希望帮到你。

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