简介这份资源是 Harbor 最新 v2.13.1 的 ARM64 架构离线安装包面向在 ARM64 服务器或 Kubernetes 集群上部署私有镜像仓库的运维与 DevOps 人员解决国产化平台、信创环境或边缘节点无法直接拉取官方 x86 镜像、在线安装受网络限制的问题。压缩包共 6 个文件以 sh 安装脚本、gz 镜像归档、prepare 预处理程序、tmpl 配置模板及 license 许可文件为主整体约 679.05MB覆盖从环境准备、配置生成到服务启动的完整离线部署链路。内容预览显示包内包含 Harbor 核心镜像归档与可编辑的 harbor.yml 模板便于按需调整端口、存储与认证参数。目前已有 528 人学习下载适合需要快速搭建 ARM64 私有镜像仓库、研究离线安装流程或排查部署问题的中高级用户参考。1. 离线环境里装 Harbor v2.13.1 ARM64为什么这件事比想象中更折腾在国产化替代和信创场景里ARM64 架构的服务器越来越常见而 Harbor 作为企业级镜像仓库几乎是标配。但真正在离线环境里部署过 Harbor v2.13.1 ARM64 版的人都知道这件事远没有docker compose up -d那么轻松。你面对的是一个没有外网、没有 Docker Hub、甚至连apt都用不了的封闭环境所有镜像、二进制、依赖包都得提前准备好再通过 U 盘或内网传输进去。更麻烦的是Harbor 官方发布的离线安装包默认只覆盖 x86_64 架构ARM64 版本需要自己从源码编译或者找社区构建的产物。这篇文章就是把我自己在某实验室的 ARM64 离线服务器上部署 Harbor v2.13.1 的完整过程拆开讲清楚包括离线包怎么准备、镜像怎么导入、配置怎么改、以及那些让人抓狂的踩坑点。如果你也面临类似场景这篇内容应该能帮你省下至少两天的折腾时间。2. 离线包准备从源码编译到镜像导出的完整链路2.1 为什么官方离线包不够用Harbor 官方在 GitHub Releases 页面提供的harbor-offline-installer-v2.13.1.tgz是 x86_64 架构的里面包含了 Harbor 所有组件的 Docker 镜像 tar 包和安装脚本。但在 ARM64 服务器上这些镜像根本跑不起来因为镜像的 manifest 里指定的架构是amd64。你可能会想Docker 不是支持多架构镜像吗确实Harbor 的某些组件在 Docker Hub 上有 ARM64 版本但离线安装包里打包的是固定架构的镜像不会自动适配。所以第一步就是自己构建 ARM64 的离线安装包。常见做法是找一台能联网的 ARM64 机器比如某高校实验室的 ARM 开发板或者云服务商的 ARM 实例先克隆 Harbor 源码切换到 v2.13.1 标签然后执行make package_offline。这个命令会编译所有组件、构建 Docker 镜像、导出 tar 包最后生成一个离线安装包。但这里有个坑Harbor 的 Makefile 默认会从 Docker Hub 拉取基础镜像如果你的网络环境不稳定编译过程会频繁失败。我一般会先配置好 Docker 的镜像加速或者提前把基础镜像拉到本地。2.2 编译环境的关键依赖在 ARM64 机器上编译 Harbor 需要以下依赖依赖项最低版本说明Docker20.10需要支持 buildx 多架构构建Docker Composev2.0Harbor v2.13.1 要求 Compose V2Go1.21编译 Harbor 核心组件Python3.8部分脚本依赖Git2.30克隆源码安装这些依赖的命令因发行版而异以 Ubuntu 22.04 ARM64 为例# 安装 Docker 和 Compose 插件 sudo apt-get update sudo apt-get install -y docker.io docker-compose-plugin # 安装 Go 1.21 wget https://go.dev/dl/go1.21.5.linux-arm64.tar.gz sudo tar -C /usr/local -xzf go1.21.5.linux-arm64.tar.gz export PATH$PATH:/usr/local/go/bin # 验证版本 docker --version docker compose version go version这段脚本的核心是确保 Docker 和 Go 的版本满足 Harbor 的编译要求。docker-compose-plugin是 Compose V2 的包名和旧的docker-compose不同Harbor v2.13.1 的安装脚本会检查docker compose命令而不是docker-compose。Go 的安装路径要加到PATH里否则make过程会找不到go命令。如果你用的是其他发行版包名可能不同但版本要求是一样的。2.3 执行离线打包依赖装好后克隆源码并打包# 克隆 Harbor 源码 git clone https://github.com/goharbor/harbor.git cd harbor git checkout v2.13.1 # 执行离线打包 make package_offlinemake package_offline会依次执行以下操作编译 Harbor 的 Go 组件core、jobservice、portal 等构建 Docker 镜像拉取依赖组件PostgreSQL、Redis、Nginx 等的 ARM64 镜像最后把所有镜像导出为 tar 包并打包成harbor-offline-installer-v2.13.1.tgz。整个过程大概需要 20 到 40 分钟取决于机器性能和网络速度。打包完成后你会在make目录下找到生成的离线安装包。注意如果你的编译机器和部署机器不是同一台确保两台机器的 Docker 版本兼容。镜像 tar 包在不同 Docker 版本之间导入时偶尔会出现 manifest 不兼容的问题。3. 离线部署实操从导入镜像到启动服务3.1 传输离线包并解压把生成的harbor-offline-installer-v2.13.1.tgz通过 U 盘或内网传到目标 ARM64 服务器上。假设传到/opt目录cd /opt tar -xzf harbor-offline-installer-v2.13.1.tgz cd harbor ls -lh解压后你会看到以下关键文件harbor.v2.13.1.tar.gz所有镜像的压缩包、harbor.yml.tmpl配置文件模板、install.sh安装脚本、prepare环境准备脚本。harbor.v2.13.1.tar.gz通常有 1.5 到 2GB包含了 Harbor 运行所需的全部镜像。3.2 导入镜像的正确姿势导入镜像这一步看似简单但最容易翻车。很多人直接docker load -i harbor.v2.13.1.tar.gz然后发现镜像列表里一堆none:none的悬空镜像。这是因为 Harbor 的镜像 tar 包是多层嵌套的需要先解压再导入# 先解压镜像包 tar -xzf harbor.v2.13.1.tar.gz # 解压后会得到多个 tar 文件 ls *.tar # 逐个导入 for img in $(ls *.tar); do echo Loading $img ... docker load -i $img done这段脚本的逻辑是Harbor 的离线包把每个组件的镜像单独打成了一个 tar 文件比如harbor-core.tar、harbor-portal.tar、postgresql.tar等。逐个导入可以避免一次性加载过大文件导致 Docker daemon 超时。导入完成后用docker images检查应该能看到所有 Harbor 相关镜像标签都是v2.13.1。注意如果导入过程中出现no space left on device说明/var/lib/docker分区空间不够。Harbor 所有镜像解压后大概占用 3 到 4GB提前预留至少 10GB 空间。3.3 配置文件的关键参数复制配置模板并修改cp harbor.yml.tmpl harbor.yml vim harbor.yml需要改的参数不多但每个都很关键# 修改为实际的主机名或 IP hostname: 192.168.1.100 # HTTP 端口如果 80 被占用可以改 http: port: 8080 # 数据存储路径确保磁盘空间充足 data_volume: /data/harbor # 数据库密码生产环境务必修改 database: password: root123 max_idle_conns: 100 max_open_conns: 900 # 如果不需要 HTTPS把 https 段全部注释掉 # https: # port: 443 # certificate: /your/certificate/path # private_key: /your/private/key/pathhostname必须改成部署机器的实际 IP 或域名否则 Docker 客户端无法通过这个地址推送和拉取镜像。data_volume建议单独挂载一块数据盘因为镜像层数据会不断增长。database.password默认是root123生产环境一定要改否则等于把数据库裸奔在内网里。如果暂时没有证书把https段注释掉Harbor 会只监听 HTTP。3.4 执行安装并验证配置改好后执行安装sudo ./install.sh安装脚本会依次执行prepare生成 Docker Compose 文件、docker compose up -d启动所有容器。整个过程大概 2 到 3 分钟。安装完成后用以下命令检查容器状态docker compose ps正常情况下你会看到 9 个容器全部处于running状态。然后用浏览器访问http://192.168.1.100:8080默认用户名admin密码Harbor12345。登录后第一件事就是改密码这个默认密码是公开的不改等于没设防。4. 避坑指南ARM64 离线部署的五个血泪教训4.1 镜像架构不匹配导致容器反复重启现象docker compose ps显示容器状态是restarting查看日志报exec format error。原因导入的镜像虽然是 ARM64 的但某个依赖组件比如 Redis 或 PostgreSQL的镜像标签指向了 x86_64 版本。Harbor 的离线包在构建时如果基础镜像没有指定--platform linux/arm64就会拉取默认架构的镜像。解决用docker inspect image | grep Architecture检查每个镜像的架构。如果发现amd64需要重新构建该组件的 ARM64 镜像或者从其他来源获取正确的镜像后重新打包。4.2 数据目录权限导致启动失败现象install.sh执行到一半报Permission denied日志显示无法写入/data/harbor。原因Harbor 容器内的进程以非 root 用户运行而/data/harbor目录的属主是 root权限是 755。解决提前创建数据目录并放宽权限sudo mkdir -p /data/harbor sudo chmod 777 /data/harbor生产环境可以用chown指定具体用户但离线部署时为了省事777是最快的方案。4.3 Docker Compose 版本不兼容现象install.sh报docker compose command not found或Compose V2 required。原因系统里装的是旧的docker-composePython 版而 Harbor v2.13.1 要求 Compose V2Go 版命令是docker compose。解决卸载旧版安装docker-compose-pluginsudo apt-get remove docker-compose sudo apt-get install docker-compose-plugin4.4 端口冲突导致 Nginx 容器起不来现象docker compose ps显示harbor-nginx状态是exited日志报bind: address already in use。原因宿主机上已经有服务占用了 80 或 443 端口比如系统自带的 Nginx 或 Apache。解决修改harbor.yml里的http.port为其他端口比如 8080然后重新执行./install.sh。或者停掉占用端口的服务。4.5 离线包解压后镜像标签丢失现象docker images里看到的镜像标签是none而不是v2.13.1。原因导入镜像时没有按顺序加载或者 tar 包在传输过程中损坏。解决重新解压harbor.v2.13.1.tar.gz按文件名顺序逐个docker load。如果还是不行检查 tar 包的 MD5 值是否和源文件一致。5. 进阶技巧让离线 Harbor 更稳的几个习惯部署完成后有几个习惯能让你的 Harbor 跑得更稳。第一个是定期备份/data/harbor目录和数据库。Harbor 的元数据都存在 PostgreSQL 里镜像数据存在/data/harbor/registry这两个地方丢了任何一个恢复起来都很麻烦。我一般会写一个 cron 脚本每天凌晨把数据库 dump 出来然后和 registry 目录一起打包到另一块盘上。第二个是监控磁盘空间。Harbor 的镜像层是增量存储的但删除镜像时不会立即释放空间需要定期执行垃圾回收。在 Harbor 的 Web 界面里系统管理 - 垃圾回收可以手动触发。也可以配一个定时任务每周跑一次。第三个是日志轮转。Harbor 的容器日志默认没有大小限制跑久了会把磁盘撑满。在docker-compose.yml里给每个服务加上logging配置logging: driver: json-file options: max-size: 50m max-file: 3这样每个容器的日志最多占用 150MB不会无限增长。最后一个习惯是版本升级前先快照。Harbor 的升级过程涉及数据库迁移一旦失败回滚很麻烦。如果是虚拟机升级前打个快照如果是物理机至少把数据库和配置文件备份一份。我自己就遇到过升级到一半数据库迁移失败的情况幸好有备份回滚后重新升级才成功。这些习惯看起来琐碎但真出事的时候它们就是你的后悔药。希望帮到你。本文还有配套的精品资源点击获取