简介本资源为 Harbor v2.4.0 的 arm 架构离线安装包面向需要在 ARM 服务器或国产化平台上私有化部署容器镜像仓库的运维与开发人员。相比在线安装离线包可规避网络受限环境下的镜像拉取难题适合内网、信创及边缘计算等场景快速落地。压缩包共 6 个文件约 402.34MB包含 sh 安装脚本、gz 镜像归档、yml 配置文件及 license 等覆盖部署所需的脚本、配置与镜像数据解压后执行 install.sh 即可一键完成安装前置依赖为 docker 与 docker-compose。目前已有 1576 人学习下载说明该版本在 ARM 环境部署中具备一定参考价值。借助该资源读者可省去逐一下载组件与手动配置的繁琐过程直接获得可复用的离线部署方案并对照配置文件理解 Harbor 各组件的参数组织方式为后续版本升级与故障排查提供基础。1. 从一台 ARM 服务器的离线部署说起harbor 2.4.0 到底能解决什么手里有一台 ARM 架构的服务器网络隔离不能连外网但团队需要一个私有镜像仓库来管理容器镜像。这时候 Docker Hub 用不了公有云仓库又不放心harbor 就成了最现实的选择。harbor 2.4.0 这个版本在 ARM 平台上已经能跑但离线安装的坑比 x86 多不少——镜像包要自己凑齐、docker-compose 的 ARM 兼容性要确认、离线包的目录结构跟在线安装完全不是一回事。这篇笔记面向的是手里有 ARM 服务器、需要在内网搭私有仓库的运维或后端从离线包准备到 harbor 服务拉起再到日常运维的坑一步步拆开讲。如果你之前只在 x86 上装过 harborARM 这套流程值得重新走一遍。2. 离线包准备与 ARM 架构适配从下载到目录结构2.1 为什么 harbor 2.4.0 的离线包在 ARM 上要单独处理harbor 官方发布的离线安装包默认是 x86_64 架构ARM 平台不能直接用。harbor 2.4.0 的离线包本质上是一个压缩包里面包含 harbor 各组件的 Docker 镜像 tar 包、docker-compose 模板、配置文件模板和安装脚本。在 x86 上你下载harbor-offline-installer-v2.4.0.tgz解压就能用但 ARM 上这个包里的镜像全是 amd64 的docker load之后启动会直接报exec format error。常见做法是两条路一是找社区构建好的 ARM 版离线包二是自己从源码构建 ARM 镜像再打包。我一般会先确认服务器 CPU 架构再决定用哪种方式。uname -m返回aarch64就是 ARM64返回x86_64就是 amd64。这个判断不做后面全是白费功夫。# 确认服务器架构 uname -m # 输出 aarch64 表示 ARM64 架构 # 确认 Docker 和 docker-compose 版本 docker --version docker-compose --version # harbor 2.4.0 要求 docker 17.06 和 docker-compose 1.18.0逻辑说明uname -m是最直接的架构判断命令ARM64 服务器通常返回aarch64。docker 和 docker-compose 的版本检查不能省harbor 2.4.0 对 docker-compose 的版本有硬性要求低于 1.18.0 会在prepare阶段直接报错退出。参数说明docker-compose 在 ARM 上建议用 1.29.x 版本2.x 版本虽然也能用但 harbor 2.4.0 的模板文件是按 1.x 语法写的混用可能出现version字段不识别的问题。2.2 离线包目录结构与关键文件说明假设你已经拿到了 ARM 版的 harbor 离线包解压后目录结构大致如下harbor/ ├── harbor.v2.4.0.tar.gz # 各组件镜像的 tar 包集合 ├── harbor.yml.tmpl # 配置文件模板 ├── install.sh # 安装脚本 ├── prepare # 环境准备脚本 ├── docker-compose.yml # 容器编排模板 ├── common.sh # 公共函数脚本 └── LICENSE这里最关键的是harbor.v2.4.0.tar.gz它里面包含了 harbor-core、harbor-portal、harbor-jobservice、registry、registryctl、postgresql、redis、nginx 等组件的镜像。ARM 版和 x86 版的区别就在这个 tar 包里——镜像的架构不同。# 解压离线包 tar -xzvf harbor-offline-installer-v2.4.0-arm64.tgz # 进入解压目录 cd harbor # 查看镜像 tar 包大小确认是否完整 ls -lh harbor.v2.4.0.tar.gz # ARM 版通常在 1.5GB 左右明显偏小说明包不完整逻辑说明解压后先看 tar 包大小ARM 版 harbor 的镜像包通常在 1.5GB 上下。如果只有几百 MB大概率是下载不完整或者拿错了包。这一步花几秒钟能省掉后面反复排查的时间。参数说明tar -xzvf中的z表示 gzip 解压x是解压v显示过程f指定文件名。如果包是.tar而非.tgz去掉z参数即可。2.3 导入镜像与配置文件修改镜像导入是离线安装的核心步骤。harbor 的install.sh脚本会自动执行docker load但前提是harbor.v2.4.0.tar.gz在正确的位置。如果你手动导入可以这样做# 手动导入所有镜像 docker load -i harbor.v2.4.0.tar.gz # 导入完成后查看镜像列表 docker images | grep goharbor # 应该能看到 harbor-core、harbor-portal、harbor-jobservice 等逻辑说明docker load会把 tar 包里的所有镜像层导入本地 Docker 存储。导入完成后用docker images过滤goharbor前缀确认各组件镜像都在。如果某个组件缺失启动时对应的容器会一直重启。参数说明-i指定输入文件。如果 tar 包是 gzip 压缩的docker load 会自动识别不需要额外解压。配置文件harbor.yml是从harbor.yml.tmpl复制来的需要改几个关键项# harbor.yml 关键配置 hostname: 192.168.1.100 # 改成服务器实际 IP 或域名 http: port: 80 # HTTP 端口按需修改 https: # 如果不用 HTTPS整段注释掉 port: 443 certificate: /path/to/cert.pem private_key: /path/to/key.pem harbor_admin_password: Harbor12345 # 管理员初始密码建议改掉 database: password: root123 # 数据库密码建议改掉 data_volume: /data # 数据存储目录确保磁盘空间充足逻辑说明hostname必须改成实际可访问的 IP 或域名否则客户端docker login会失败。data_volume是镜像和数据库的存储位置默认/data如果根分区空间不够改成独立数据盘挂载点。参数说明harbor_admin_password是 admin 用户的初始密码首次登录后建议在界面修改。database.password是内部 PostgreSQL 的密码改掉能减少被扫描的风险。3. 执行安装与验证从 prepare 到 docker login3.1 运行安装脚本与常见报错处理配置改完后执行安装脚本# 执行安装 ./install.sh # 如果只想安装核心组件不带 Notary 和 Clair ./install.sh --without-notary --without-clair逻辑说明install.sh会依次执行prepare生成最终 docker-compose.yml、docker load导入镜像、docker-compose up -d启动容器。--without-notary和--without-clair用于跳过可选组件ARM 平台上 Notary 的兼容性一般建议先不装。参数说明--with-notary和--with-clair是显式启用默认不启用。如果后续需要漏洞扫描可以再单独装 Clair。安装过程中最常见的报错是端口占用和镜像架构不匹配# 检查端口占用 netstat -tlnp | grep -E 80|443|5432|6379 # 如果 80 被 nginx 占用改 harbor.yml 的 http.port # 然后重新执行 ./install.sh逻辑说明harbor 默认用 80 和 443如果服务器上已有 nginx 或其他 Web 服务会冲突。netstat检查后改端口是最快的解决方式。ARM 上如果报exec format error说明镜像架构不对需要重新获取 ARM 版镜像包。参数说明netstat -tlnp中t是 TCPl是监听状态n是数字显示端口p显示进程。需要 root 权限才能看到进程名。3.2 验证 harbor 服务状态与 docker login安装完成后用 docker-compose 查看容器状态# 查看容器运行状态 docker-compose ps # 正常情况应该看到 9 个左右的容器状态都是 Up # 如果有 Exit 或 Restarting查看对应日志 docker-compose logs harbor-core逻辑说明docker-compose ps列出所有容器的状态。harbor 2.4.0 正常运行时harbor-core、harbor-portal、harbor-jobservice、registry、registryctl、postgresql、redis、nginx 这些容器都应该是 Up 状态。如果有容器反复重启用docker-compose logs看具体报错。参数说明docker-compose logs后面跟服务名不加服务名则输出所有日志。-f参数可以实时跟踪日志输出。服务起来后在另一台机器上测试登录# 在客户端机器上登录 harbor docker login 192.168.1.100 -u admin -p Harbor12345 # 如果 harbor 配了 HTTPS 但证书是自签的需要加信任 # 或者直接在 docker daemon 配置里加 insecure-registries逻辑说明docker login验证 harbor 的认证服务是否正常。如果返回Error response from daemon: Get https://...: x509: certificate signed by unknown authority说明证书不被信任。测试环境可以在/etc/docker/daemon.json里加insecure-registries。参数说明-u和-p分别是用户名和密码。生产环境建议用--password-stdin从标准输入读取密码避免密码出现在命令历史里。3.3 推送和拉取镜像的完整流程登录成功后测试镜像推送# 给本地镜像打 tag docker tag nginx:latest 192.168.1.100/library/nginx:latest # 推送镜像 docker push 192.168.1.100/library/nginx:latest # 拉取镜像 docker pull 192.168.1.100/library/nginx:latest逻辑说明harbor 的镜像路径格式是hostname/project/image:tag。library是默认项目也可以先在 harbor 界面创建新项目再推送。推送成功后在 harbor 的 Web 界面能看到镜像列表和大小。参数说明docker tag只是给镜像加一个别名不产生新镜像。推送时 harbor 会校验认证信息如果项目不存在或权限不足会返回denied。4. 避坑与常见问题ARM 离线安装的五个血泪教训4.1 镜像架构不匹配导致容器反复重启现象docker-compose ps显示 harbor-core 状态为Restarting日志里报exec format error。原因离线包里的镜像还是 amd64 架构ARM 服务器无法执行。解决确认离线包是 ARM64 版本或者用docker inspect查看镜像架构docker inspect goharbor/harbor-core:v2.4.0 | grep Architecture # 输出 Architecture: arm64 才是正确的4.2 docker-compose 版本过高导致语法不兼容现象./install.sh执行到prepare阶段报Unsupported config option for services或version is unsupported。原因docker-compose 2.x 版本对version字段的处理和 1.x 不同harbor 2.4.0 的模板是按 1.x 写的。解决降级到 docker-compose 1.29.x或者手动修改docker-compose.yml去掉version: 2这一行。4.3 数据目录磁盘空间不足导致安装中断现象安装过程中报no space left on devicepostgresql 容器启动失败。原因data_volume默认指向/data如果根分区空间不够镜像和数据库写入会失败。解决安装前用df -h /data确认空间建议至少预留 50GB。如果不够在harbor.yml里把data_volume改到大容量挂载点。4.4 端口冲突导致 nginx 容器无法启动现象docker-compose ps显示 nginx 状态为Exit日志报bind: address already in use。原因服务器上已有服务占用了 80 或 443 端口。解决netstat -tlnp | grep 80找到占用进程要么停掉冲突服务要么在harbor.yml里改http.port为其他端口。4.5 离线环境下时间不同步导致证书校验失败现象docker login报x509: certificate has expired or is not yet valid。原因内网服务器时间偏差过大HTTPS 证书校验不通过。解决安装前用date检查时间偏差超过几分钟就手动校准或配置内网 NTP 源。这个坑很隐蔽日志里不会直接说时间问题只会报证书错误。5. 进阶技巧ARM 离线环境的日常运维与镜像清理harbor 跑起来只是第一步日常运维里最头疼的是镜像清理和存储管理。harbor 2.4.0 自带的垃圾回收功能在 ARM 上同样可用但触发方式和 x86 略有不同。我一般会先配好保留策略再手动触发 GC避免存储被旧镜像撑满。保留策略在 harbor 界面的「项目」→「策略」里配置可以按镜像标签数量或保留天数来清理。比如设置「保留最近 10 个标签」超过的自动删除。这个策略对 ARM 环境尤其重要因为 ARM 镜像的层复用率不如 x86同样的镜像数量占用的存储可能更多。手动触发垃圾回收# 停止 harborGC 需要停服务 docker-compose stop # 执行 GC docker run -it --name gc --rm --volumes-from registry \ goharbor/registry-photon:v2.4.0 garbage-collect \ /etc/registry/config.yml # 重新启动 harbor docker-compose start逻辑说明harbor 的 GC 需要 registry 容器停止写入所以要先docker-compose stop。--volumes-from registry让 GC 容器挂载 registry 的数据卷garbage-collect是 registry 自带的命令/etc/registry/config.yml是配置文件路径。参数说明--rm表示容器退出后自动删除避免残留。GC 完成后用docker-compose start恢复服务。整个过程通常几分钟到十几分钟取决于镜像数量。另一个实用技巧是定期备份数据库和配置文件# 备份 PostgreSQL 数据库 docker exec harbor-db pg_dump -U postgres registry backup_$(date %Y%m%d).sql # 备份 harbor.yml 和 docker-compose.yml cp harbor.yml /backup/harbor.yml.$(date %Y%m%d) cp docker-compose.yml /backup/docker-compose.yml.$(date %Y%m%d)逻辑说明harbor 的元数据存在 PostgreSQL 里镜像层存在文件系统里。数据库备份能恢复项目、用户、策略等信息配置文件备份能快速重建环境。这两个备份加起来基本能覆盖大部分故障场景。参数说明pg_dump -U postgres registry导出 registry 数据库$(date %Y%m%d)生成日期后缀方便区分版本。从那以后我每次在 ARM 上部署 harbor都会先跑一遍uname -m和docker inspect确认架构再检查磁盘和端口最后才执行安装脚本。这套流程走下来基本没再翻过车。希望帮到你。本文还有配套的精品资源点击获取