简介这份资源是面向 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 用 CISCarm64 用 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配置模板含 hostname、端口、密码等必须复制为 harbor.yml 并修改install.sh主安装脚本调用 prepare 和 docker compose一般不改prepare环境准备脚本生成配置和证书一般不改harbor.v2.13.1.tar.gz所有组件的 arm64 镜像归档不修改common.sh公共函数库被 install.sh 引用不修改docker-compose.yml由 prepare 生成定义服务编排不直接改改 harbor.yml这里有个容易忽略的点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:999Harbor 的 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-port8080/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。# 安装 skopeoarm64 版本 # 假设你已经有了 skopeo 的 arm64 二进制 cp skopeo /usr/local/bin/ chmod x /usr/local/bin/skopeo # 从源 Harbor 复制镜像到目标 Harbor skopeo copy \ --src-tls-verifyfalse \ --dest-tls-verifyfalse \ --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-verifyfalse \ --creds admin:DestPassword \ docker://192.168.1.101:8080/library/nginx:latest逻辑说明skopeo copy直接在两个 registry 之间传输镜像层不落地到本地磁盘适合离线环境批量同步。--src-tls-verifyfalse和--dest-tls-verifyfalse是因为内网 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 上的经验能直接平移。架构差异带来的问题往往不是配置层面的而是二进制层面的排查起来更费时间。所以每次拿到新包先验架构、再验完整性、最后跑闭环测试这三步做完后面基本不会出大问题。希望帮到你。本文还有配套的精品资源点击获取