简介这份资源是 Harbor 最新 v2.13.1 的 ARM64 架构离线安装包面向在 ARM64 服务器或 Kubernetes 集群上部署私有镜像仓库的运维与开发人员解决国产化平台、信创环境及边缘节点无法直接拉取官方 x86 安装包的问题。压缩包为 tgz 格式共 6 个文件约 679.05MB包含安装脚本、公共函数脚本、核心镜像归档、许可证文件、配置模板等覆盖从环境准备到服务启动的完整离线部署链路无需联网即可完成安装。目前已有 528 人学习下载适合具备 Docker 与 Kubernetes 基础、需要快速搭建 ARM64 私有镜像仓库的中高级用户。借助该包可省去自行编译与镜像搬运的繁琐过程直接获得可复用的部署脚本与配置模板便于在离线环境中验证 Harbor 的镜像管理、权限控制与复制分发能力也为后续版本升级和排错提供参考。1. 内网交付 Harbor v2.13.1 ARM64为什么离线包比在线装更值得做在信创机房、边缘节点、麒麟/鲲鹏服务器上装 Harbor最怕的不是配置复杂而是机器根本连不上外网。Harbor v2.13.1 的 ARM64 离线安装包解决的正是这个场景把镜像、二进制、compose 编排文件全部预先打包拷进内网后一条命令拉起私有镜像仓库。它适合三类人一是要在国产 ARM 服务器上搭镜像仓库的运维二是被 arm64 和 x64 有什么区别坑过一次、发现官方镜像拉不下来的开发者三是需要给离线环境做版本升级、又不想动外网的老手。这篇不讲概念讲的是我实际把 v2.13.1 ARM64 离线包在内网跑通的全过程包括包怎么来、参数怎么改、哪一步最容易翻车。2. 先搞清楚 ARM64 离线包里到底装了什么2.1 离线包与在线安装的本质差别在线安装 Harbor 时install.sh会去 Docker Hub 拉十几个镜像再逐个docker pull。内网机器一旦没有出口这一步直接卡死报错通常是dial tcp: i/o timeout或manifest unknown。离线安装包把这一步提前做完了发布方在能联网的 ARM64 机器上把所有镜像docker save成 tar连同harbor.yml、prepare、install.sh、docker-compose一起打进压缩包。你拿到的是一个自包含的交付物安装过程不产生任何外网请求。这里有个容易混淆的点Harbor 的离线包分 x64 和 ARM64 两个架构文件名里带arm64的才是给鲲鹏、飞腾、Ampere 这类机器用的。x64 的包在 ARM64 上跑docker load阶段就会报no matching manifest for linux/arm64。所以第一步不是急着解压而是确认机器架构。uname -m # 期望输出aarch64 # 如果输出 x86_64说明你拿错包了别往下走uname -m在 ARM64 服务器上返回aarch64这是判断包对不对的唯一硬标准。有些国产系统会返回arm64也属于正常。参数上没什么可调的就是确认架构但这一步省掉后面全是白费功夫。2.2 离线包解压后的目录结构与关键文件解压后典型结构是这样的不同打包方式略有差异但核心文件一致文件/目录作用是否必须改harbor.yml主配置域名、密码、存储路径必须改install.sh安装入口内部调 prepare 和 compose一般不改prepare渲染配置模板生成最终 compose 文件不改harbor.v2.13.1.tar.gz所有镜像的打包文件不改common.sh公共函数库不改docker-compose.yml由 prepare 生成不要手改不改真正需要你动手的只有harbor.yml。其余文件是发布方固化好的改了反而容易出问题。我见过有人为了“优化”去改docker-compose.yml结果prepare重新生成时覆盖掉白忙一场。tar -xzf harbor-offline-installer-v2.13.1-arm64.tgz cd harbor ls -lh # 确认能看到 harbor.yml、install.sh、harbor.v2.13.1.tar.gz解压命令本身没难度关键是解压后先ls确认文件齐全。如果harbor.v2.13.1.tar.gz缺失或大小异常正常在 1GB 以上说明包在传输中损坏重新拷贝比继续折腾划算。2.3 为什么 v2.13.1 这个版本值得单独做离线包Harbor 的版本升级节奏里v2.13.x 是一个相对稳定的分支v2.13.1 修了早期 2.13.0 的一些镜像清理和权限同步问题。对离线环境来说选一个补丁版本比选大版本首发更稳因为大版本首发经常有 compose 模板和数据库迁移的小毛病而离线环境排查这些问题的成本极高——你没法随手docker pull一个新镜像来对比。另一个现实原因是很多内网机器的 Docker 版本停留在 20.10 或 24.xv2.13.1 对这两个区间的兼容性经过较多验证。如果你手上是更老的 19.03建议先升 Docker否则docker load大镜像时可能触发存储驱动问题。3. 在 ARM64 机器上把离线包跑起来的最小步骤3.1 前置检查Docker、compose 与内核参数装之前先过一遍环境这几项不满足install.sh会在不同阶段报错而且报错信息不一定直白。docker version --format {{.Server.Version}} # 建议 20.10.10 以上24.x 更稳 docker compose version # v2.13.1 用 compose v2命令是 docker compose 而非 docker-compose sysctl net.ipv4.ip_forward # 期望 1否则容器网络不通 free -h # 内存建议 4G 以上2G 会在启动多个组件时 OOMdocker compose version这条要特别注意Harbor v2.13.1 的install.sh内部调用的是 compose v2 插件形式。如果你的机器只有老的docker-compose独立二进制脚本可能找不到命令。解决办法是装 compose v2 插件或者确认install.sh里的调用方式与你的环境匹配。net.ipv4.ip_forward为 0 时Harbor 的容器之间无法转发流量表现是网页能打开但推送镜像超时。临时开启用sysctl -w net.ipv4.ip_forward1永久生效写进/etc/sysctl.conf。3.2 改 harbor.yml四个必须动的参数harbor.yml是从harbor.yml.tmpl复制来的直接编辑它。下面四个参数不改装完要么访问不了要么不安全。# harbor.yml 关键片段 hostname: harbor.internal.example.com # 改成你的内网域名或IP http: port: 80 # 内网用80省事冲突就换 https: # 内网没证书时整段注释掉否则 install.sh 会因缺证书报错 # port: 443 # certificate: /your/cert.crt # private_key: /your/cert.key harbor_admin_password: YourStrongPass123 # 默认Harbor12345必须改 data_volume: /data/harbor # 确认该路径所在磁盘空间充足hostname填 IP 也可以但填了 IP 后推送镜像的地址就是 IP证书和 DNS 都要跟着调整。内网纯 IP 访问时把 https 整段注释掉是最省事的做法代价是走明文 HTTP仅限可信内网。data_volume是镜像和数据库的落盘位置默认/data。如果/data挂的是小盘装到一半磁盘满Harbor 的数据库会损坏恢复很麻烦。装之前df -h /data看一眼。3.3 执行 install.sh 与验证服务状态配置改完一条命令拉起sudo ./install.sh # 脚本会依次加载镜像 - 渲染配置 - 启动容器 # 看到 Harbor has been installed and started successfully. 才算成功install.sh内部先docker load那个大 tar 包这一步在 ARM64 上可能持续几分钟取决于磁盘 IO。加载完成后prepare生成docker-compose.yml最后docker compose up -d。如果中途失败先看它停在哪一步再针对性排查。装完验证docker compose ps # 期望看到 harbor-core、harbor-db、harbor-portal、registry 等均为 Up curl -I http://harbor.internal.example.com # 期望返回 200 或 302docker compose ps里如果有容器反复重启Restarting大概率是数据库没起来或配置里的密码与数据库不匹配。这时候看docker compose logs harbor-db比瞎猜快。3.4 推送第一个镜像验证仓库可用服务起来不等于能用推一个镜像才算真正跑通。docker login harbor.internal.example.com # 输入 harbor.yml 里设的 admin 密码 docker tag nginx:latest harbor.internal.example.com/library/nginx:test docker push harbor.internal.example.com/library/nginx:testdocker login报http: server gave HTTP response to HTTPS client说明你用了 HTTP 但 Docker 默认走 HTTPS。需要在/etc/docker/daemon.json里把该地址加进insecure-registries然后重启 Docker。这是内网 HTTP 部署最常见的坑没有之一。推送成功后在 Harbor 网页的项目列表里能看到library/nginx说明整条链路通了。4. 离线安装最容易翻车的几个地方4.1 现象install.sh 卡在 docker load 不动原因ARM64 机器磁盘 IO 慢或者 tar 包在拷贝过程中损坏。离线包动辄 1GB 以上用 U 盘或 scp 传输时中断过文件就不完整了。解决先校验文件大小和 md5如果发布方给了校验值。没有校验值时tar -tzf harbor.v2.13.1.tar.gz /dev/null能检测压缩包是否可读。损坏就重新拷贝别试图修复。4.2 现象网页打不开容器全是 Up原因hostname填的域名在客户端解析不了或者防火墙没放行 80 端口。容器 Up 只代表进程活着不代表网络可达。解决在客户端ping harbor.internal.example.com和telnet harbor.internal.example.com 80各试一次。域名不通就改 hosts 或 DNS端口不通就查 firewalld/iptables。4.3 现象推送镜像报 413 Request Entity Too Large原因Harbor 前面的 nginx 默认限制请求体大小大镜像层被拦。解决这个限制在 Harbor 的 nginx 配置模板里离线包环境下改common/config/nginx/nginx.conf后重新prepare再docker compose up -d。改之前先确认你改的是模板文件而不是生成后的文件。4.4 现象升级时数据库迁移失败原因从旧版本升到 v2.13.1数据库 schema 有变更如果旧库有脏数据或迁移中途断电会卡住。解决升级前必须备份data_volume里的database目录。这是唯一的后悔药。迁移失败时回滚到备份再排查不要在失败状态下反复重启。4.5 现象ARM64 上某些组件镜像 manifest 不匹配原因包里混入了 x64 镜像或者 Docker 版本太老不认识 ARM64 manifest。解决docker inspect出问题的镜像看Architecture字段是不是arm64。不是就说明包有问题。Docker 版本低于 19.03 时对多架构 manifest 支持差升级 Docker 是正解。5. 把离线包用成可复制的交付流程单次装通只是开始真正省事的是把整个过程固化成可重复的流程。我现在的习惯是拿到一个新环境的 ARM64 机器先跑一个检查脚本把架构、Docker 版本、compose 版本、磁盘、内存、ip_forward 一次性打出来全绿了再解压安装。这样能把大部分翻车挡在动手之前。#!/bin/bash # precheck.sh - Harbor ARM64 离线安装前置检查 echo arch: $(uname -m) echo docker: $(docker version --format {{.Server.Version}} 2/dev/null || echo missing) echo compose: $(docker compose version 2/dev/null || echo missing) echo ip_forward: $(sysctl -n net.ipv4.ip_forward) echo mem: $(free -h | awk /Mem/{print $2}) echo data_disk: $(df -h /data 2/dev/null | awk NR2{print $4} || echo no /data)这个脚本不复杂但把最容易出问题的六项集中暴露。arch不对直接换包docker或compose缺失先补环境ip_forward为 0 先开转发内存和磁盘不够先扩容。全绿之后再走安装成功率会高很多。另一个进阶技巧是版本升级的验证方法。离线环境升级 Harbor不能像在线那样拉最新镜像对比我的做法是升级前用docker compose ps和curl记录当前所有容器的镜像 tag 和服务状态升级后再跑一遍逐项对比。重点看harbor-db和harbor-core的镜像 tag 是否变了、数据库迁移日志里有没有ERROR。如果升级后网页能开但推送失败八成是 registry 组件没起来docker compose logs registry里会有线索。最后说个我踩过的坑有次在内网升级图省事没备份数据库迁移到一半机器断电恢复时发现旧库和新 schema 混在一起只能重装。从那以后我给自己定了条死规矩——离线环境动 Harbor 之前先tar一份data_volume/database哪怕磁盘紧张也要留出这份空间。离线环境的排查成本比在线高一个数量级能提前留的后悔药一定要留。希望帮到你。本文还有配套的精品资源点击获取