简介面向需要在 ARM 架构服务器上私有化部署容器镜像仓库的运维与开发人员这份资源提供 Harbor v2.4.0 的离线安装包可解决内网环境无法拉取镜像、部署流程繁琐的问题。压缩包共 6 个文件约 402.34MB包含 sh 安装与辅助脚本、gz 镜像归档、yml 配置文件以及 license 等覆盖从环境准备到服务启动的完整链路其中 prepare 与 common.sh 负责前置检查与公共逻辑install.sh 承担一键安装入口。使用前需自行准备 docker 与 docker-compose 环境执行安装脚本即可完成部署适合具备一定 Linux 基础、希望快速搭建企业级镜像仓库的读者。目前已有 1574 人学习下载可作为 ARM 平台 Harbor 落地的参考方案帮助减少离线环境下的配置与排错成本。1. 从一台内网 ARM 服务器说起harbor-v2.4.0 离线安装到底解决什么很多做信创或边缘计算项目的同行都遇到过这种场景客户现场给了一台 ARM 架构的服务器系统是麒麟或者 openEuler网络完全隔离连个 yum 源都连不上但项目要求必须有一套私有镜像仓库来管理容器镜像。这时候你打开 Harbor 官方文档发现全是 x86 的在线安装脚本./install.sh一跑就卡在拉取镜像那一步因为docker pull根本出不去。harbor-v2.4.0 离线安装包就是为这种场景准备的——它把 Harbor 核心组件、依赖镜像、Docker Compose 编排文件全部打包成一个压缩包你只需要在 ARM 服务器上解压、改配置、执行安装脚本就能在纯内网环境里跑起一套功能完整的私有仓库。这套方案适合两类人一是需要在 ARM 服务器上搭建内网镜像仓库的运维工程师二是做国产化替代项目、必须用离线方式交付的交付工程师。它不解决镜像构建问题也不解决跨架构镜像转换问题它只解决一件事让 Harbor 在 ARM 架构、无外网的环境里跑起来。2. 动手之前先把 ARM 离线包的组成和依赖理清楚2.1 离线包里到底有什么harbor-v2.4.0 的 ARM 离线安装包通常是一个.tgz文件解压后你会看到harbor/目录下包含这几类东西harbor.v2.4.0.tar.gz是 Harbor 自身所有组件的镜像归档docker-compose.yml是编排模板prepare脚本负责根据harbor.yml生成最终配置install.sh是入口脚本。另外还有common.sh、harbor.yml.tmpl这些辅助文件。和在线安装最大的区别在于离线包里已经包含了registry、portal、core、jobservice、redis、postgresql、nginx、trivy等组件的 ARM 架构镜像你不需要再联网拉取。但要注意这些镜像的架构必须是arm64如果你拿到的是 x86 的离线包在 ARM 机器上docker load之后启动会直接报exec format error这是第一个要确认的点。2.2 系统层面的依赖检查在解压安装包之前先在目标服务器上确认三件事。第一Docker 和 Docker Compose 是否已经安装并且 Docker 版本不低于 17.06Compose 版本不低于 1.18.0。ARM 架构下 Docker 的安装本身也可能需要离线包常见做法是提前准备好docker-ce和docker-compose的 ARM 版本二进制文件。第二检查内核参数Harbor 的prepare脚本会读取vm.max_map_count如果这个值小于 262144Elasticsearch 组件如果你启用了 Trivy 扫描可能启动失败。第三确认 80、443、5432、6379 这些端口没有被占用尤其是 80 端口Harbor 默认用 nginx 监听它。# 检查 Docker 和 Compose 版本 docker --version docker-compose --version # 检查内核参数 sysctl vm.max_map_count # 如果小于 262144临时调整 sysctl -w vm.max_map_count262144 # 检查端口占用 ss -tlnp | grep -E :(80|443|5432|6379)\s上面这几条命令是安装前的例行检查。docker --version输出里如果看到arm64或aarch64字样说明 Docker 本身是 ARM 版本。sysctl vm.max_map_count返回的值如果偏小用sysctl -w临时改大但重启后会失效持久化需要写进/etc/sysctl.conf。端口检查那一条如果发现 80 被 nginx 或 httpd 占了要么停掉对应服务要么在harbor.yml里把http.port改成其他值。2.3 解压与目录规划我一般会把离线包放在/opt下面解压后得到/opt/harbor目录。不要放在/root或/home下因为 Harbor 运行时会挂载一些卷路径权限容易出问题。解压命令很简单但要注意tar的参数-xzf是解压 gzip 压缩的 tar 包-C指定目标目录。# 创建安装目录 mkdir -p /opt/harbor-install cd /opt/harbor-install # 解压离线包 tar -xzf harbor-offline-installer-v2.4.0-arm64.tgz # 进入解压后的目录 cd harbor # 查看目录结构 ls -la解压完成后你会看到harbor.v2.4.0.tar.gz这个镜像包它可能有几个 GB取决于是否包含了 Trivy 的漏洞库。harbor.yml.tmpl是配置模板你需要把它复制成harbor.yml再修改。prepare和install.sh是两个关键脚本前者负责校验配置和生成docker-compose.yml后者负责加载镜像并启动容器。目录权限方面确保当前用户对/opt/harbor-install/harbor有读写权限否则prepare脚本生成配置文件时会失败。3. 配置 harbor.yml 与执行安装参数怎么改、脚本怎么跑3.1 harbor.yml 里必须改的四个参数复制模板之后用编辑器打开harbor.yml重点改四个地方。第一是hostname改成目标服务器的 IP 地址或者域名不要用localhost或127.0.0.1否则客户端推送镜像时会报dial tcp连接错误。第二是http.port默认是 80如果被占用就改成 8080 或其他端口。第三是harbor_admin_password这是管理员初始密码不改的话默认是Harbor12345生产环境必须改掉。第四是data_volume默认是/data如果服务器上/data分区空间不够改成其他大容量路径。# 复制配置文件模板 cp harbor.yml.tmpl harbor.yml # 编辑关键参数示例片段 hostname: 192.168.1.100 http: port: 80 harbor_admin_password: YourStrongPassword123 data_volume: /data上面这段 YAML 是harbor.yml里最核心的几行。hostname填 IP 时不要带端口端口在http.port里单独指定。harbor_admin_password要满足复杂度要求至少 8 位包含大小写字母和数字。data_volume指向的目录如果不存在prepare脚本会自动创建但前提是父目录有写权限。另外如果你不需要 HTTPS就把https那段整个注释掉否则prepare会要求你提供证书文件。3.2 执行 prepare 和 install.sh 的完整流程配置改好之后先跑./prepare它会做几件事检查harbor.yml语法、根据配置生成docker-compose.yml、创建数据目录、检查端口冲突。如果这一步报错通常是 YAML 缩进问题或者端口被占用。prepare成功后再跑./install.sh它会先docker load加载离线镜像包然后docker-compose up -d启动所有容器。# 执行准备脚本 ./prepare # 如果 prepare 成功执行安装 ./install.sh # 查看容器状态 docker-compose ps # 查看 Harbor 核心服务日志 docker-compose logs -f core./prepare的输出里会显示它生成了哪些配置文件如果看到Generated configuration file: ./common/config/...就说明成功了。./install.sh执行时间取决于镜像包大小和磁盘速度ARM 服务器上可能跑几分钟。docker-compose ps里所有容器的状态应该是Up或Up (healthy)如果有Exit或Restarting就要看对应容器的日志。docker-compose logs -f core是排查启动问题最常用的命令core是 Harbor 的核心 API 服务它起不来后面都白搭。3.3 验证安装是否成功安装完成后打开浏览器访问http://hostname用admin和你设置的密码登录。如果能进到项目列表页面说明 Web 层没问题。然后在本机用docker login测试一下再推送一个测试镜像。# 登录 Harbor docker login 192.168.1.100 -u admin -p YourStrongPassword123 # 拉一个 ARM 架构的测试镜像如果本地没有 docker pull arm64v8/nginx:latest # 打标签 docker tag arm64v8/nginx:latest 192.168.1.100/library/nginx:test # 推送 docker push 192.168.1.100/library/nginx:testdocker login如果返回Login Succeeded就说明认证通了。推送镜像时要注意Harbor 的项目名必须提前在 Web 界面创建或者用library这个默认项目。docker push如果卡住或者报dial tcp错误多半是hostname配置不对或者防火墙没放行端口。推送成功后在 Harbor 的 Web 界面里能看到这个镜像说明整套流程闭环了。4. 避坑与排查ARM 离线安装最容易翻车的五个地方4.1 镜像架构不匹配导致容器起不来现象docker-compose up -d之后docker-compose ps显示某些容器状态是Exit 255或者Restarting看日志报exec format error。原因离线包里的镜像不是arm64架构可能是 x86 的或者混合了多种架构。ARM 服务器上的 Docker 无法运行 x86 镜像除非你装了 QEMU 模拟但 Harbor 这种 IO 密集型的服务用模拟跑性能极差。解决用docker inspect image | grep Architecture确认每个镜像的架构。如果发现是amd64必须换一个正确的 ARM 离线包。不要试图用--platform参数强行指定docker load加载的镜像架构是固定的改不了。4.2 hostname 配成 localhost 导致推送失败现象docker push报Get https://127.0.0.1/v2/: dial tcp 127.0.0.1:443: connect: connection refused或者类似的连接错误。原因harbor.yml里的hostname写成了localhost或127.0.0.1Harbor 的 nginx 配置和证书都是基于这个 hostname 生成的客户端从其他机器访问时解析不到。解决把hostname改成服务器的真实 IP 或域名然后重新跑./prepare和./install.sh。如果已经安装过需要先docker-compose down停掉旧容器再重新安装。注意改 hostname 后原来的镜像数据还在但配置会重新生成。4.3 磁盘空间不足导致 postgresql 启动失败现象docker-compose ps显示postgresql容器不断重启日志里报No space left on device或者could not write to file。原因data_volume指向的目录所在分区空间不够PostgreSQL 启动时需要初始化数据库文件至少需要几百 MB 的可用空间。ARM 服务器上如果/data分区很小就容易出这个问题。解决用df -h检查data_volume所在分区的可用空间如果不足 5GB把data_volume改到一个大容量分区然后重新./prepare和./install.sh。如果数据已经写入需要先备份再迁移。4.4 防火墙未放行端口导致客户端无法访问现象浏览器打不开 Harbor 页面或者docker login超时但服务器本机curl http://localhost是通的。原因服务器防火墙firewalld 或 iptables没有放行 Harbor 使用的端口默认是 80 和 443如果改了http.port就要放行对应端口。解决用firewall-cmd --list-ports查看已放行端口如果没有 80执行firewall-cmd --add-port80/tcp --permanent然后firewall-cmd --reload。如果是 iptables用iptables -I INPUT -p tcp --dport 80 -j ACCEPT临时放行持久化需要保存规则。4.5 docker-compose 版本过低导致语法不兼容现象./install.sh执行到docker-compose up -d时报Unsupported config option for services或者Version in ./docker-compose.yml is unsupported。原因ARM 服务器上安装的docker-compose版本太老不支持 Harbor v2.4.0 生成的docker-compose.yml里的某些语法比如depends_on的条件格式。解决升级docker-compose到 1.18.0 以上版本。ARM 架构下可以从 GitHub Releases 下载对应的二进制文件或者用 pip 安装。升级后重新跑./install.sh不需要重新./prepare。5. 进阶技巧离线环境下的镜像同步与版本升级验证5.1 用 skopeo 在离线环境里同步镜像Harbor 跑起来之后你可能会遇到一个新问题怎么把外网的镜像弄到内网的 Harbor 里常见做法是在一台能上网的机器上用skopeo把镜像复制成 tar 包再拷贝到内网机器上推送到 Harbor。skopeo支持copy命令可以直接从 registry 复制到本地目录不需要 Docker daemon。# 在外网机器上复制镜像到本地目录 skopeo copy docker://nginx:latest dir:/tmp/nginx-image # 打包拷贝到内网 tar -czf nginx-image.tar.gz -C /tmp nginx-image # 在内网机器上从目录复制到 Harbor skopeo copy dir:/tmp/nginx-image docker://192.168.1.100/library/nginx:latestskopeo copy的第一个参数是源docker://表示从 registry 拉取dir:表示存到本地目录。第二个参数是目标反过来就是推送到 Harbor。这种方式比docker save和docker load更灵活因为它不需要本地 Docker daemon而且可以跨架构复制。注意skopeo本身也有 ARM 版本在内网机器上安装时同样需要离线包。5.2 验证 Harbor 版本升级的兼容性如果你后续要升级 Harbor比如从 v2.4.0 升到 v2.5.0在离线环境里不能直接跑在线升级脚本。正确做法是下载新版本的 ARM 离线包解压后把旧的harbor.yml复制过去然后执行./prepare和./install.sh。但升级前必须做一件事备份数据库和镜像数据。# 备份 PostgreSQL 数据库 docker exec -it harbor-db pg_dump -U postgres registry /backup/registry.sql # 备份镜像存储目录 tar -czf /backup/registry-storage.tar.gz /data/registry # 备份配置文件 cp harbor.yml /backup/harbor.yml.bak上面三条命令分别备份了数据库、镜像文件和配置。pg_dump导出的是 registry 数据库包含了项目、用户、权限等元数据。/data/registry是镜像层实际存储的位置备份它才能保证镜像不丢。升级完成后如果新版本启动失败可以用这些备份回滚到旧版本。我一般会在升级前把旧版本的离线包也留着万一新版本跑不起来直接解压旧包恢复。5.3 一个容易被忽略的细节时间同步ARM 服务器如果长时间运行在内网系统时间可能会漂移。Harbor 的 token 认证机制依赖时间戳如果服务器时间和客户端时间相差太大docker login会报token expired或者unauthorized。这个坑很隐蔽因为 Harbor 本身运行正常Web 界面也能打开就是推送和拉取镜像时认证失败。# 检查系统时间 date # 如果时间偏差大手动同步需要外网 NTP 或内网 NTP 源 ntpdate ntp.aliyun.com # 或者用 chrony 配置内网时间源 chronyc sources -vdate命令输出的时间如果和实际时间差了几分钟甚至几小时就要同步。内网环境如果没有 NTP 服务器可以在 Harbor 服务器上手动设置一个接近的时间然后让客户端也同步到这个时间。chrony是 CentOS 和 openEuler 上常用的时间同步工具配置内网 NTP 源后可以自动校准。从那以后我每次部署 Harbor 之前都会先跑一遍date和chronyc sources确认时间没问题再往下走这个习惯帮我省了好几次排查认证问题的时间。希望帮到你。本文还有配套的精品资源点击获取