简介面向ARM64架构服务器与Kubernetes/Docker环境提供Harbor最新v2.13.1离线安装包解决ARM平台镜像仓库部署时下载慢、依赖难配的问题。压缩包共6个文件涵盖安装脚本sh、离线镜像归档gz、配置文件模板tmpl及许可与准备脚本license、prepare整包679.05MB结构清晰可直接用于内网安装。已有522人学习下载适合运维工程师、K8s集群管理员及信创环境开发者。基于官方发行版打包持续更新版本用户可获得完整可用的离线部署文件省去逐一下载组件与镜像的环节显著提升在ARM平台搭建Harbor的效率。 最近在做 ARM64 架构下的容器服务部署绕不开的一个东西就是 Harbor。作为业界用得较多的开源镜像仓库Harbor 在权限管理、镜像复制、漏洞扫描这些场景里几乎是标配。可真正动起手来很多人会卡在同一个问题上官方 release 里的离线安装包大多面向 x86_64网上搜出来的 ARM64 版本要么是别人编译好的老版本要么折腾半天还是跑不起来。我这次在一台 Ubuntu 22.04 的 ARM64 服务器上把 Harbor v2.13.1 的 ARM64 版离线安装包完整部署了一遍从下载校验到配置 HTTPS再到后面 push/pull 验证整个过程踩了不少坑。这篇文章就把完整流程和问题排查写出来给准备在内网 ARM 环境搭镜像仓库的朋友一份能直接照做的作业。无论你是刚接触 Harbor 的新手还是已经被 amd64 和 arm64 镜像不兼容搞到头大的老手这篇内容都能帮你少走弯路。1. 先说清楚为什么 ARM64 离线包这么难找1.1 官方离线包和“架构”之间的关系Harbor 的离线安装包本质是一个压缩包里面既有安装脚本、配置模板也有一大坨打包好的 Docker 镜像。镜像本身是分架构的amd64 镜像在 arm64 机器上不能直接运行反过来也一样。官方离线包为了覆盖绝大多数用户很长时间里只重点维护 x86_64 版本这也就导致 ARM64 用户如果直接拿官方离线包执行 install.sh脚本跑到加载镜像的那一步就会直接报“exec format error”。对个人开发者来说网络方便的时候用 online installer 在线拉取镜像不是不行但企业内网往往有隔离要求生产环境也不可能随便连公网所以离线包反而是最合适的交付形式。这也是为什么“ARM64 版 Harbor 离线安装包”这个需求一直存在却很难找到开箱即用的现成包。1.2 哪些场景真的需要 ARM64 版离线包根据我这段时间和不少同行的交流以下几类场景最常见机房或办公内网完全隔离只有一台有外网权限的跳板机需要先下好套装再拷贝进内网企业内部常见的 ARM 服务器比如鲲鹏、飞腾这些平台系统装好了、Docker 也装好了就差一个能和企业账号体系接上的镜像仓库边缘计算节点或者开发桌面本身就是 ARM 架构M 系列芯片的 Mac、树莓派集群这类想跑一套和 x86 生产环境一致的 Harbor 做联调虚拟化环境里手动创建 ARM64 虚机想复刻一套内网应用栈。这些场景有一个共同点对系统可用性要求高没时间也没条件去折腾源码编译。因此拿到一个靠谱的 ARM64 离线包比任何优化技巧都来得实在。1.3 和 x86 版安装过程的核心差异从安装流程来看ARM64 版离线包大体上仍然遵循“解压—配置—执行 install.sh—验证”的路线和 x86_64 版没有本质差别。真正的差异集中在两个地方一是包内的镜像必须是 arm64 版本这决定了解压后能不能直接跑二是某些辅助工具或数据库镜像在不同架构上有兼容性问题比如个别旧版 Postgres 镜像缺少针对 ARM 的构建会导致数据库容器起来就挂。所以从下载到安装之前先确认包来源和内部镜像架构是非常重要的后面我会详细写怎么确认。2. 了解你的安装包Harbor v2.13.1 离线包构成2.1 v2.13.1 值得关注的点v2.13.1 是 Harbor 2.13 系列的一个修复版本。从 2.x 中后期开始Harbor 的核心功能逐渐成熟重点转向安全补丁、依赖升级和一些 API 细节修复。对使用方来说选这个版本的好处是“新但不激进”既能有较新的漏洞数据库和 Trivy 扫描组件又不至于踩到大版本切换的坑。尤其当你是离线部署、后续不方便频繁升级的时候选一个处于成熟迭代期的版本比追最新功能要明智得多。这里多说一句Harbor 的版本节奏比较快v2.13.1 之后可能很快又有小版本。如果你所在团队有安全合规要求记得后续关注 release notes把补丁版本同步更新到内网环境。2.2 离线包解压后里面有什么以官方离线安装包为例解压后会看到这样几个核心文件harbor/ ├── harbor.yml.tmpl // 配置模板 ├── install.sh // 安装启动脚本 ├── prepare // 配置生成器 ├── common.sh // 公共函数库 ├── harbor.v2.13.1.tar.gz // 镜像包ARM64版就是arm64镜像 └── LICENSE 等这里最重要的是 harbor.v2.13.1.tar.gz 和 harbor.yml.tmpl。前者决定了安装包能不能在目标架构上运行后者决定了 Harbor 启动后的基本行为比如主机名、端口、证书、数据存储位置等。install.sh 本质上做了两件事一是把镜像包 load 进本地 Docker二是基于 harbor.yml 生成 docker-compose.yml 并启动服务。理解了这个结构你就知道离线安装过程中哪些文件能碰、哪些不能碰。比如 harbor.yml.tmpl 不要直接改正确做法是先复制成 harbor.yml 再修改。2.3 拿到离线包后先做架构检查这一步非常容易忽略但我强烈建议在任何 ARM64 机器上执行安装之前先看一眼镜像包里的架构信息。最直接的办法是先解压离线包然后用 docker load 把镜像包载入当前环境再用 docker images 查看镜像平台信息tar -xvzf harbor-offline-installer-v2.13.1-arm64.tgz cd harbor docker load harbor.v2.13.1.tar.gz docker images | head -20如果镜像的平台字段显示为 amd64那说明包拿错了后面安装没有意义。ARM64 离线包里的镜像平台信息会显示为 linux/arm64。这个检查只需要一两分钟却可以避免后面“脚本卡在加载镜像”这类让人抓狂的问题。3. 下载前准备环境要求和包校验3.1 目标机器的前置条件在 ARM64 机器上部署 Harbor系统本身不需要很特殊的配置但下面几项必须提前确认操作系统建议 Ubuntu 22.04 或等价发行版主要考虑 systemd、网络管理和默认内核版本对 Docker 的兼容性。CentOS、openEuler 也可以只是个别命令略有差异。Docker建议版本 20.10 以上安装 Docker Engine 并启用 docker compose plugin也就是 docker compose 命令要可用。磁盘空间Harbor 的镜像包解压后大约会有 2 到 4GB运行时数据库、registry 日志和镜像存储会持续占空间建议数据盘预留 50GB 以上。端口Harbor 默认监听 80 或 443如果和现有服务冲突需要在 harbor.yml 里改端口。我在实际部署中发现很多报错并不是出在 Harbor 本身而是基础环境没准备好。尤其 docker compose plugin 没有安装的话install.sh 执行到后面会报docker: compose is not a docker command这个错的关键不是去改 Harbor而是回去装 Docker 插件。3.2 校验下载包的完整性离线安装包体积不小从外网或者内网中转拷贝的过程中很容易因为网络问题造成文件损坏。所以拿到安装包后第一件事就是做校验。官方 release 页面一般会附上 sha256sum 的值在下载后对比一下就行sha256sum harbor-offline-installer-v2.13.1-arm64.tgz如果暂时没有官方校验值也可以解压后看关键文件大小是否正常。但说实话最可靠的还是下载时同时拿到发布方的 SHA256 文件到目标机器上核对一遍。不要嫌这一步啰嗦损坏的离线包会在 docker load 阶段报tar: Error exit delayed from previous errors这时候再回头重传反而更浪费时间。3.3 关于在线安装器和离线包的选择如果你的架构比较特殊或者一时找不到合适的 ARM64 离线包还有一个折中方案是用官方 online installer 在 ARM64 机器上直接拉取镜像。优点是省掉了自己打包的步骤缺点是目标环境必须能正常连接镜像源而且拉取速度完全依赖网络。对于完全隔离的内网环境还是老老实实把离线包备好再带进内网更踏实。后面我会单独讲一下怎么从一台能联网的 ARM64 机器自制离线包方便以后在内网里重复部署。4. 实操从零开始部署 Harbor v2.13.1 ARM64 离线包4.1 解压并创建基础配置把安装包上传到目标机器后进入一个你希望放置 Harbor 的目录比如 /opt/harbor然后解压cd /opt sudo tar -xvzf harbor-offline-installer-v2.13.1-arm64.tgz cd harbor sudo cp harbor.yml.tmpl harbor.yml这一步没什么技术含量但要注意目录权限。install.sh 执行过程中会创建数据目录和日志目录如果当前用户没有相应权限建议整条链路都用 sudo或者提前把目录 owner 改成当前用户。我习惯用 sudo 执行安装避免意料之外的权限问题。4.2 配置 harbor.yml主机名、密码、端口harbor.yml 是本次安装最核心的配置文件。打开之后至少要修改这几项hostname: registry.internal.example.com # 改成你的访问域名或IP http: port: 80 # 默认HTTP端口 harbor_admin_password: Harbor12345 # 管理员初始密码务必修改 data_volume: /data/harbor # 镜像与数据库所在目录 log: level: info local: rotate_count: 50 rotate_size: 200M如果你的内网没有域名解析hostname 可以直接写服务器 IP 地址客户端机器上通过 IP 访问也没问题。data_volume 建议单独挂载到大容量数据盘不要放在系统盘否则后期镜像一多系统盘很容易被打满。4.3 从 HTTP 改成 HTTPS 的实操重点很多人在内网部署完 Harbor 后会遇到一个经典问题镜像推送时报http: server gave HTTP response to HTTPS client。这个报错本质上是因为 Docker 客户端默认用 HTTPS 访问 registry而 Harbor 只开了 HTTP。解决办法有两个方向一是让客户端容忍 HTTP也就是配置 insecure-registries二是给 Harbor 配上 HTTPS 证书。后者更符合生产习惯也是“harbor 的 http 协议改成 https”这个问题的标准解法。先看怎么生成一份自签名证书sudo mkdir -p /data/cert cd /data/cert openssl req -newkey rsa:4096 -nodes -sha256 -keyout ca.key -x509 -days 3650 -out ca.crt -subj /CNHarbor-CA openssl req -newkey rsa:4096 -nodes -sha256 -keyout server.key -out server.csr -subj /CNregistry.internal.example.com openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 3650 -sha256如果客户端通过 IP 访问证书里的 CN 最好写成 IP或者在生成证书请求时加上 SAN否则浏览器或 docker 客户端校验主机名时会失败。然后回到 harbor.yml把 http 段注释掉启用 https 段# http: # port: 80 https: port: 443 certificate: /data/cert/server.crt private_key: /data/cert/server.key修改配置后重新运行 prepare 再重启服务sudo ./prepare sudo docker compose down sudo docker compose up -d这里有一个细节很多教程只改 harbor.yml 然后重新执行 install.sh其实不对。install.sh 里已经包含了 prepare 和 docker compose up 的过程但对于已经启动过的环境直接执行 install.sh 有时候不会干净地重建所有配置所以我习惯先 down 再 prepare 再 up。4.4 执行安装脚本配置完成并保存后执行sudo ./install.shinstall.sh 会先检查 docker 和 docker compose 环境然后把 harbor.v2.13.1.tar.gz 里的镜像 load 进本地再调用 prepare 生成配置最终通过 docker compose up -d 把各个服务拉起来。整个过程耗时取决于磁盘读写速度一般几分钟到十几分钟不等。如果你需要启用额外功能可以加参数例如sudo ./install.sh --with-trivyTrivy 是漏洞扫描组件离线部署时它需要下载漏洞数据库。如果内网不能联网扫描功能可能无法及时更新数据库部署时可以考虑先不加等有空再把离线漏洞库导进去。安装完成后脚本会输出 Harbor 的访问地址和初始管理员账号。此时 docker compose ps 应该能看到常见的服务在运行nginx、registry、core、portal、database、redis、registryctl、jobservice、trivy-adapter如果启用了等。4.5 客户端配置与功能验证Harbor 起来之后先在本机验证登录和推送docker login registry.internal.example.com # 输入 admin 和密码 docker pull busybox:latest docker tag busybox:latest registry.internal.example.com/library/busybox:latest docker push registry.internal.example.com/library/busybox:latest如果登录报错大概率是 HTTPS 证书信任问题。把 CA 证书加到客户端信任列表或者在 /etc/docker/daemon.json 里配置 insecure-registries{ insecure-registries: [registry.internal.example.com] }这里要特别提醒insecure-registries 是跳过证书校验而不是加密传输仅在完全可信的内网环境使用。生产环境建议把 CA 证书分发到各客户端这样不用关闭 TLS 校验安全性和便利性都能兼顾。5. 常见问题与排查记录5.1 在 x86 机器上用 qemu 模拟 ARM64 的坑如果手上暂时没有 ARM64 实机又想在 x86 机器上验证 ARM64 版 Harbor有人会想到 qemu 模拟。qemu-user-static 配合 binfmt_misc 确实能让 x86 的 Docker 直接跑 arm64 容器但对于 Harbor 这种多容器协作的系统模拟执行的效率问题很明显数据库容器尤其明显跑一会儿就可能出现 IO 卡顿、日志写入延迟甚至容器无响应。我不建议用它做生产部署最多用来做配置正确性的验证。换个思路直接在 ARM64 云主机或者一台 ARM 开发板上部署反而比在本机开 qemu 省心得多。5.2 Harbor 起来了但 docker push 一直失败这个问题十有八九是 http/https 不匹配。前面已经写了配置 HTTPS 的完整流程这里再补充一种快速定位方法curl -v https://registry.internal.example.com/v2/ curl -v http://registry.internal.example.com/v2/如果 https 请求返回证书提示而 http 请求能正常返回 401 或 200基本可以确定是服务端证书或客户端信任的问题按 4.3 节的方式重新配置。5.3 安装脚本执行到一半卡住常见原因有两个一是系统内存不足Harbor 包含多个容器建议至少 4GB 可用内存低于 2GB 时 Postgres 和 registry 很容易启动失败二是 docker load 阶段因为磁盘空间不足中断用 df -h 检查数据盘。如果是内存不足临时加 swap 可以应急但长期跑不建议依赖 swap还是要把实例规格提上来。5.4 ARM64 环境下部分组件兼容性问题我遇到过一种情况包本身确实是 ARM64 的但 Helm Chart 相关组件或者某些辅助容器在启动时报 segmentation fault。这种大多和镜像构建的架构有关解决思路是不要执着于旧版本优先换一个更新、维护更积极的版本。这也是我最后选择 v2.13.1 的一个原因版本越新ARM64 的构建链通常越完整。5.5 自制 ARM64 离线包的思路如果你的内网环境很封闭又担心社区包的来源安全最好的办法是在同样架构的联网机器上自制离线包。思路很清晰先通过官方 online installer 或 docker compose 方案在 ARM64 机器上拉齐所有镜像然后把这些镜像导出成 tar再配合 install.sh 和配置模板组成离线包。第一次做的时候会慢一些但之后每次部署都是开箱即用长期价值很高。上面这些问题都是我在实际部署 ARM64 版 Harbor 时踩过的。最大的体会是离线安装这件事把基础环境和架构问题搞清楚比急着执行安装脚本重要得多。你要是第一次弄建议先在测试机上完整走一遍再上生产如果临时遇到报错先去看日志docker compose logs -f 能给出最直接的提示。祝各位在 ARM64 上顺利把 Harbor 跑起来。本文还有配套的精品资源点击获取 
长河君 · 2026/9/8 9:03:57 · 阅读 1.2k ARM64 离线部署 Harbor v2.13.1 完整指南：从下载到 HTTPS 配置
简介面向ARM64架构服务器与Kubernetes/Docker环境提供Harbor最新v2.13.1离线安装包解决ARM平台镜像仓库部署时下载慢、依赖难配的问题。压缩包共6个文件涵盖安装脚本sh、离线镜像归档gz、配置文件模板tmpl及许可与准备脚本license、prepare整包679.05MB结构清晰可直接用于内网安装。已有522人学习下载适合运维工程师、K8s集群管理员及信创环境开发者。基于官方发行版打包持续更新版本用户可获得完整可用的离线部署文件省去逐一下载组件与镜像的环节显著提升在ARM平台搭建Harbor的效率。 最近在做 ARM64 架构下的容器服务部署绕不开的一个东西就是 Harbor。作为业界用得较多的开源镜像仓库Harbor 在权限管理、镜像复制、漏洞扫描这些场景里几乎是标配。可真正动起手来很多人会卡在同一个问题上官方 release 里的离线安装包大多面向 x86_64网上搜出来的 ARM64 版本要么是别人编译好的老版本要么折腾半天还是跑不起来。我这次在一台 Ubuntu 22.04 的 ARM64 服务器上把 Harbor v2.13.1 的 ARM64 版离线安装包完整部署了一遍从下载校验到配置 HTTPS再到后面 push/pull 验证整个过程踩了不少坑。这篇文章就把完整流程和问题排查写出来给准备在内网 ARM 环境搭镜像仓库的朋友一份能直接照做的作业。无论你是刚接触 Harbor 的新手还是已经被 amd64 和 arm64 镜像不兼容搞到头大的老手这篇内容都能帮你少走弯路。1. 先说清楚为什么 ARM64 离线包这么难找1.1 官方离线包和“架构”之间的关系Harbor 的离线安装包本质是一个压缩包里面既有安装脚本、配置模板也有一大坨打包好的 Docker 镜像。镜像本身是分架构的amd64 镜像在 arm64 机器上不能直接运行反过来也一样。官方离线包为了覆盖绝大多数用户很长时间里只重点维护 x86_64 版本这也就导致 ARM64 用户如果直接拿官方离线包执行 install.sh脚本跑到加载镜像的那一步就会直接报“exec format error”。对个人开发者来说网络方便的时候用 online installer 在线拉取镜像不是不行但企业内网往往有隔离要求生产环境也不可能随便连公网所以离线包反而是最合适的交付形式。这也是为什么“ARM64 版 Harbor 离线安装包”这个需求一直存在却很难找到开箱即用的现成包。1.2 哪些场景真的需要 ARM64 版离线包根据我这段时间和不少同行的交流以下几类场景最常见机房或办公内网完全隔离只有一台有外网权限的跳板机需要先下好套装再拷贝进内网企业内部常见的 ARM 服务器比如鲲鹏、飞腾这些平台系统装好了、Docker 也装好了就差一个能和企业账号体系接上的镜像仓库边缘计算节点或者开发桌面本身就是 ARM 架构M 系列芯片的 Mac、树莓派集群这类想跑一套和 x86 生产环境一致的 Harbor 做联调虚拟化环境里手动创建 ARM64 虚机想复刻一套内网应用栈。这些场景有一个共同点对系统可用性要求高没时间也没条件去折腾源码编译。因此拿到一个靠谱的 ARM64 离线包比任何优化技巧都来得实在。1.3 和 x86 版安装过程的核心差异从安装流程来看ARM64 版离线包大体上仍然遵循“解压—配置—执行 install.sh—验证”的路线和 x86_64 版没有本质差别。真正的差异集中在两个地方一是包内的镜像必须是 arm64 版本这决定了解压后能不能直接跑二是某些辅助工具或数据库镜像在不同架构上有兼容性问题比如个别旧版 Postgres 镜像缺少针对 ARM 的构建会导致数据库容器起来就挂。所以从下载到安装之前先确认包来源和内部镜像架构是非常重要的后面我会详细写怎么确认。2. 了解你的安装包Harbor v2.13.1 离线包构成2.1 v2.13.1 值得关注的点v2.13.1 是 Harbor 2.13 系列的一个修复版本。从 2.x 中后期开始Harbor 的核心功能逐渐成熟重点转向安全补丁、依赖升级和一些 API 细节修复。对使用方来说选这个版本的好处是“新但不激进”既能有较新的漏洞数据库和 Trivy 扫描组件又不至于踩到大版本切换的坑。尤其当你是离线部署、后续不方便频繁升级的时候选一个处于成熟迭代期的版本比追最新功能要明智得多。这里多说一句Harbor 的版本节奏比较快v2.13.1 之后可能很快又有小版本。如果你所在团队有安全合规要求记得后续关注 release notes把补丁版本同步更新到内网环境。2.2 离线包解压后里面有什么以官方离线安装包为例解压后会看到这样几个核心文件harbor/ ├── harbor.yml.tmpl // 配置模板 ├── install.sh // 安装启动脚本 ├── prepare // 配置生成器 ├── common.sh // 公共函数库 ├── harbor.v2.13.1.tar.gz // 镜像包ARM64版就是arm64镜像 └── LICENSE 等这里最重要的是 harbor.v2.13.1.tar.gz 和 harbor.yml.tmpl。前者决定了安装包能不能在目标架构上运行后者决定了 Harbor 启动后的基本行为比如主机名、端口、证书、数据存储位置等。install.sh 本质上做了两件事一是把镜像包 load 进本地 Docker二是基于 harbor.yml 生成 docker-compose.yml 并启动服务。理解了这个结构你就知道离线安装过程中哪些文件能碰、哪些不能碰。比如 harbor.yml.tmpl 不要直接改正确做法是先复制成 harbor.yml 再修改。2.3 拿到离线包后先做架构检查这一步非常容易忽略但我强烈建议在任何 ARM64 机器上执行安装之前先看一眼镜像包里的架构信息。最直接的办法是先解压离线包然后用 docker load 把镜像包载入当前环境再用 docker images 查看镜像平台信息tar -xvzf harbor-offline-installer-v2.13.1-arm64.tgz cd harbor docker load harbor.v2.13.1.tar.gz docker images | head -20如果镜像的平台字段显示为 amd64那说明包拿错了后面安装没有意义。ARM64 离线包里的镜像平台信息会显示为 linux/arm64。这个检查只需要一两分钟却可以避免后面“脚本卡在加载镜像”这类让人抓狂的问题。3. 下载前准备环境要求和包校验3.1 目标机器的前置条件在 ARM64 机器上部署 Harbor系统本身不需要很特殊的配置但下面几项必须提前确认操作系统建议 Ubuntu 22.04 或等价发行版主要考虑 systemd、网络管理和默认内核版本对 Docker 的兼容性。CentOS、openEuler 也可以只是个别命令略有差异。Docker建议版本 20.10 以上安装 Docker Engine 并启用 docker compose plugin也就是 docker compose 命令要可用。磁盘空间Harbor 的镜像包解压后大约会有 2 到 4GB运行时数据库、registry 日志和镜像存储会持续占空间建议数据盘预留 50GB 以上。端口Harbor 默认监听 80 或 443如果和现有服务冲突需要在 harbor.yml 里改端口。我在实际部署中发现很多报错并不是出在 Harbor 本身而是基础环境没准备好。尤其 docker compose plugin 没有安装的话install.sh 执行到后面会报docker: compose is not a docker command这个错的关键不是去改 Harbor而是回去装 Docker 插件。3.2 校验下载包的完整性离线安装包体积不小从外网或者内网中转拷贝的过程中很容易因为网络问题造成文件损坏。所以拿到安装包后第一件事就是做校验。官方 release 页面一般会附上 sha256sum 的值在下载后对比一下就行sha256sum harbor-offline-installer-v2.13.1-arm64.tgz如果暂时没有官方校验值也可以解压后看关键文件大小是否正常。但说实话最可靠的还是下载时同时拿到发布方的 SHA256 文件到目标机器上核对一遍。不要嫌这一步啰嗦损坏的离线包会在 docker load 阶段报tar: Error exit delayed from previous errors这时候再回头重传反而更浪费时间。3.3 关于在线安装器和离线包的选择如果你的架构比较特殊或者一时找不到合适的 ARM64 离线包还有一个折中方案是用官方 online installer 在 ARM64 机器上直接拉取镜像。优点是省掉了自己打包的步骤缺点是目标环境必须能正常连接镜像源而且拉取速度完全依赖网络。对于完全隔离的内网环境还是老老实实把离线包备好再带进内网更踏实。后面我会单独讲一下怎么从一台能联网的 ARM64 机器自制离线包方便以后在内网里重复部署。4. 实操从零开始部署 Harbor v2.13.1 ARM64 离线包4.1 解压并创建基础配置把安装包上传到目标机器后进入一个你希望放置 Harbor 的目录比如 /opt/harbor然后解压cd /opt sudo tar -xvzf harbor-offline-installer-v2.13.1-arm64.tgz cd harbor sudo cp harbor.yml.tmpl harbor.yml这一步没什么技术含量但要注意目录权限。install.sh 执行过程中会创建数据目录和日志目录如果当前用户没有相应权限建议整条链路都用 sudo或者提前把目录 owner 改成当前用户。我习惯用 sudo 执行安装避免意料之外的权限问题。4.2 配置 harbor.yml主机名、密码、端口harbor.yml 是本次安装最核心的配置文件。打开之后至少要修改这几项hostname: registry.internal.example.com # 改成你的访问域名或IP http: port: 80 # 默认HTTP端口 harbor_admin_password: Harbor12345 # 管理员初始密码务必修改 data_volume: /data/harbor # 镜像与数据库所在目录 log: level: info local: rotate_count: 50 rotate_size: 200M如果你的内网没有域名解析hostname 可以直接写服务器 IP 地址客户端机器上通过 IP 访问也没问题。data_volume 建议单独挂载到大容量数据盘不要放在系统盘否则后期镜像一多系统盘很容易被打满。4.3 从 HTTP 改成 HTTPS 的实操重点很多人在内网部署完 Harbor 后会遇到一个经典问题镜像推送时报http: server gave HTTP response to HTTPS client。这个报错本质上是因为 Docker 客户端默认用 HTTPS 访问 registry而 Harbor 只开了 HTTP。解决办法有两个方向一是让客户端容忍 HTTP也就是配置 insecure-registries二是给 Harbor 配上 HTTPS 证书。后者更符合生产习惯也是“harbor 的 http 协议改成 https”这个问题的标准解法。先看怎么生成一份自签名证书sudo mkdir -p /data/cert cd /data/cert openssl req -newkey rsa:4096 -nodes -sha256 -keyout ca.key -x509 -days 3650 -out ca.crt -subj /CNHarbor-CA openssl req -newkey rsa:4096 -nodes -sha256 -keyout server.key -out server.csr -subj /CNregistry.internal.example.com openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 3650 -sha256如果客户端通过 IP 访问证书里的 CN 最好写成 IP或者在生成证书请求时加上 SAN否则浏览器或 docker 客户端校验主机名时会失败。然后回到 harbor.yml把 http 段注释掉启用 https 段# http: # port: 80 https: port: 443 certificate: /data/cert/server.crt private_key: /data/cert/server.key修改配置后重新运行 prepare 再重启服务sudo ./prepare sudo docker compose down sudo docker compose up -d这里有一个细节很多教程只改 harbor.yml 然后重新执行 install.sh其实不对。install.sh 里已经包含了 prepare 和 docker compose up 的过程但对于已经启动过的环境直接执行 install.sh 有时候不会干净地重建所有配置所以我习惯先 down 再 prepare 再 up。4.4 执行安装脚本配置完成并保存后执行sudo ./install.shinstall.sh 会先检查 docker 和 docker compose 环境然后把 harbor.v2.13.1.tar.gz 里的镜像 load 进本地再调用 prepare 生成配置最终通过 docker compose up -d 把各个服务拉起来。整个过程耗时取决于磁盘读写速度一般几分钟到十几分钟不等。如果你需要启用额外功能可以加参数例如sudo ./install.sh --with-trivyTrivy 是漏洞扫描组件离线部署时它需要下载漏洞数据库。如果内网不能联网扫描功能可能无法及时更新数据库部署时可以考虑先不加等有空再把离线漏洞库导进去。安装完成后脚本会输出 Harbor 的访问地址和初始管理员账号。此时 docker compose ps 应该能看到常见的服务在运行nginx、registry、core、portal、database、redis、registryctl、jobservice、trivy-adapter如果启用了等。4.5 客户端配置与功能验证Harbor 起来之后先在本机验证登录和推送docker login registry.internal.example.com # 输入 admin 和密码 docker pull busybox:latest docker tag busybox:latest registry.internal.example.com/library/busybox:latest docker push registry.internal.example.com/library/busybox:latest如果登录报错大概率是 HTTPS 证书信任问题。把 CA 证书加到客户端信任列表或者在 /etc/docker/daemon.json 里配置 insecure-registries{ insecure-registries: [registry.internal.example.com] }这里要特别提醒insecure-registries 是跳过证书校验而不是加密传输仅在完全可信的内网环境使用。生产环境建议把 CA 证书分发到各客户端这样不用关闭 TLS 校验安全性和便利性都能兼顾。5. 常见问题与排查记录5.1 在 x86 机器上用 qemu 模拟 ARM64 的坑如果手上暂时没有 ARM64 实机又想在 x86 机器上验证 ARM64 版 Harbor有人会想到 qemu 模拟。qemu-user-static 配合 binfmt_misc 确实能让 x86 的 Docker 直接跑 arm64 容器但对于 Harbor 这种多容器协作的系统模拟执行的效率问题很明显数据库容器尤其明显跑一会儿就可能出现 IO 卡顿、日志写入延迟甚至容器无响应。我不建议用它做生产部署最多用来做配置正确性的验证。换个思路直接在 ARM64 云主机或者一台 ARM 开发板上部署反而比在本机开 qemu 省心得多。5.2 Harbor 起来了但 docker push 一直失败这个问题十有八九是 http/https 不匹配。前面已经写了配置 HTTPS 的完整流程这里再补充一种快速定位方法curl -v https://registry.internal.example.com/v2/ curl -v http://registry.internal.example.com/v2/如果 https 请求返回证书提示而 http 请求能正常返回 401 或 200基本可以确定是服务端证书或客户端信任的问题按 4.3 节的方式重新配置。5.3 安装脚本执行到一半卡住常见原因有两个一是系统内存不足Harbor 包含多个容器建议至少 4GB 可用内存低于 2GB 时 Postgres 和 registry 很容易启动失败二是 docker load 阶段因为磁盘空间不足中断用 df -h 检查数据盘。如果是内存不足临时加 swap 可以应急但长期跑不建议依赖 swap还是要把实例规格提上来。5.4 ARM64 环境下部分组件兼容性问题我遇到过一种情况包本身确实是 ARM64 的但 Helm Chart 相关组件或者某些辅助容器在启动时报 segmentation fault。这种大多和镜像构建的架构有关解决思路是不要执着于旧版本优先换一个更新、维护更积极的版本。这也是我最后选择 v2.13.1 的一个原因版本越新ARM64 的构建链通常越完整。5.5 自制 ARM64 离线包的思路如果你的内网环境很封闭又担心社区包的来源安全最好的办法是在同样架构的联网机器上自制离线包。思路很清晰先通过官方 online installer 或 docker compose 方案在 ARM64 机器上拉齐所有镜像然后把这些镜像导出成 tar再配合 install.sh 和配置模板组成离线包。第一次做的时候会慢一些但之后每次部署都是开箱即用长期价值很高。上面这些问题都是我在实际部署 ARM64 版 Harbor 时踩过的。最大的体会是离线安装这件事把基础环境和架构问题搞清楚比急着执行安装脚本重要得多。你要是第一次弄建议先在测试机上完整走一遍再上生产如果临时遇到报错先去看日志docker compose logs -f 能给出最直接的提示。祝各位在 ARM64 上顺利把 Harbor 跑起来。本文还有配套的精品资源点击获取