简介面向需要在ARM架构或内网环境部署容器镜像仓库的运维与开发人员Harbor v2.7.0 ARM64离线安装包提供完整部署所需的核心组件包括shell安装脚本、部署准备脚本、配置模板、许可证说明以及离线镜像压缩包共6个文件包体约704.87MB。利用该离线包可规避外网拉取镜像的不便在企业内网快速搭建私有Harbor并借助RBAC权限控制、审计日志与镜像复制同步等功能保障镜像的安全存储与跨地域分发满足企业级容器镜像管理需求。即使网络受限也能依靠离线镜像包完成从环境初始化到镜像上传的完整闭环。不同于Docker Hub的公网镜像仓库Harbor更注重企业私有化部署与安全管控支持标准Docker客户端直接使用对需要镜像签名、合规审计或跨机房同步的团队尤为适用。已有150人学习适合初次接触Harbor或计划在国产化/ARM服务器上落地容器仓库的工程师参考使用。 拿到harbor-offline-installer-v2.7.0-arm64.tar.gz这个安装包的时候别急着解压就跑。文件名里每一段都不是白写的harbor是目标软件offline-installer决定了你的安装方式v2.7.0是版本号arm64是最不能搞错的 CPU 架构tar.gz则是压缩格式。这套组合出现频率最高的场景就是内网环境里要给 ARM 服务器鲲鹏、飞腾、树莓派、部分国产化机器搭一套私有容器镜像仓库。这篇文章就围绕这个包把部署前的前置检查、配置改动、安装验证、HTTP 转 HTTPS 的完整过程以及我实际踩过的坑一次讲清楚。我是在帮客户部署一套基于 ARM 的 CI/CD 环境时第一次认真研究这个包的。当时手头就是一台飞腾 CPU 的服务器内网环境连不了 Docker Hub所有组件都要离线装。如果你也正在给 ARM 机器部署 Harbor或者准备做这件事这篇文章可以省你至少半天查文档和试错的时间。1. 部署前必须想清楚的 3 个问题1.1 为什么 Harbor 要专门提供离线安装包Harbor 的安装方式从官方渠道看分两种在线安装器和离线安装包。在线安装器其实是一个install.sh脚本加一个远程下载地址执行脚本的时候它会去 Docker Hub 或者 GitHub 拉取必要的容器镜像。这套方案在公网环境没问题但到了内网环境就有大麻烦了——无法拉取镜像安装直接卡死。离线安装包则是把 Harbor 运行所需的全部容器镜像、配置文件、启动脚本全部打进一个tar.gz里。它的核心逻辑是先把压缩包里的镜像 tar 文件用docker load加载到本地再基于自带配置启动容器。整个过程不依赖外部网络只要机器上有 Docker 环境镜像就能本地加载。这一点在军工、政企、内网开发环境里是刚需也是我几乎只选用离线包的原因。还有一层好处是版本可控。在线安装器可能在你不知情的情况下拉取到更新版本的镜像导致配置文件不兼容离线包锁定了 v2.7.0 的所有组件版本行为可预期出问题也好排查。1.2 arm64 架构标识怎么确认为什么不能混用文件名里的arm64是指 CPU 架构对应的是 Linux 系统常用的aarch64标识。你可以在要部署的机器上执行uname -m如果返回aarch64那这个包就是对的。如果返回x86_64那就是 AMD64 架构必须去找harbor-offline-installer-v2.7.0-amd64.tar.gz这个包。为什么这个区分如此重要因为 Harbor 离线包里的容器镜像是按架构编译的。ARM 架构的镜像比如goharbor/registry-photon:v2.7.0-arm64和 AMD64 架构的镜像是不同的文件强制在 x86 上加载 ARM 镜像Docker 会直接报exec format error容器根本跑不起来。反过来也一样。我在一台 x86 笔记本上试着把 ARM 包 load 进去过结果是镜像列表里能看到但一启动就失败白折腾了半小时。1.3 v2.7.0 这个版本有哪些值得注意的变化Harbor 的版本号从 v2.6 到 v2.7 有一个重要改变harbor.yml配置结构发生了变化。v2.7.0 开始把 HTTP 和 HTTPS 的监听端口拆得更细支持同时启用 HTTP 和 HTTPS增加了http.port和https.port这样的显式配置项。这一点在热词里提到的“harbor 的 http 协议改成 https”操作中非常关键后面我会专门开辟一节来讲。另外v2.7.0 的组件构成包括nginx、harbor-core、harbor-portalWeb 前端、harbor-registry负责镜像存储、harbor-dbPostgreSQL、redis、harbor-jobservice如果你需要做镜像漏洞扫描还会用到trivy。了解这些组件名称对排查启动失败很有用因为docker ps一看哪个容器没起来基本能定位问题方向。2. 环境准备与包体校验别急着解压2.1 硬件配置与操作系统兼容性Harbor 官方文档写的最低配置是 2 核 CPU、4GB 内存但我的实测经验是4GB 内存跑起来非常紧张。Harbor 的容器组里PostgreSQL 和 Redis 都是吃内存大户再加上harbor-core、harbor-registry开机内存占用直接到 3GB 以上。如果机器还跑着其他应用很容易触发 OOM表现就是容器反复重启。建议内网部署至少给 4 核 8GB磁盘有条件就分 100GB 以上毕竟镜像仓库的存储是持续增长的。操作系统层面Harbor 官方支持主流 Linux 发行版Ubuntu 22.04 LTS、20.04 LTS、Debian 11、CentOS 7.9 都验证过。ARM 平台上我实际试过 Ubuntu 22.04 和 openEuler都能正常跑起来。需要留意的是tar命令在精简系统上可能没装先执行tar --version确认一下没有就通过apt install tar或yum install tar装好这是最基础的前置检查。2.2 Docker 和 Compose 的版本决定后面少踩多少坑Harbor v2.7.0 官方要求 Docker 版本 17.06.0 以上Docker Compose 1.18.0 以上。但这里有个容易踩坑的点现在很多新系统只装了 Docker 本身没有 Docker Compose v1即docker-compose命令或者只装好了 Compose v2 插件即docker compose子命令。Harbor 的install.sh脚本默认调用docker-compose命令如果你只有 v2 插件脚本会提示找不到命令。解决办法有两种。第一种安装 Docker Compose v1 的二进制文件但 ARM 架构的 Compose v1 二进制不太好找第二种更推荐的做法是创建一个软链接把docker composev2 映射成docker-compose命令。在 Ubuntu 22.04 上我先确认 Docker 已装好然后再看一下 compose 是否可用docker --version docker compose version如果docker compose version正常而docker-compose不存在就手动建一个软链接sudo ln -s /usr/libexec/docker/cli-plugins/docker-compose /usr/local/bin/docker-compose路径因发行版而异可以用which docker-compose验证。建好后再执行docker-compose --version确认能输出版本号。这一步做对了后面install.sh才能走下去。2.3 校验包体完整性与 MD5 值我见过不止一次因为下载不完整导致解压失败的情况。尤其是走内网传输工具拷贝安装包中途断流是家常便饭。所以解压前先做完整性校验是我的固定动作。官方发布页面会给每个安装包附一个.md5或.sha256校验文件。下载后把包和校验文件放在同一目录执行md5sum -c harbor-offline-installer-v2.7.0-arm64.tar.gz.md5输出OK就说明文件完整。如果没有校验文件也可以直接解压测试tar -tzf只列出内容不解压也能间接判断完整性tar -tzf harbor-offline-installer-v2.7.0-arm64.tar.gz | head -20如果输出一堆文件名而不是报错说明包基本没问题。3. 解压、配置、安装一步步来3.1 解压与目录结构解读校验通过后进入目标目录执行解压tar -xzf harbor-offline-installer-v2.7.0-arm64.tar.gz解压后会出现一个harbor目录。进入目录你会看到这些关键文件harbor.yml.tmpl配置模板必须复制成harbor.yml再做修改install.sh主安装脚本common.sh公共函数库install.sh 会引用它prepare预编译脚本负责根据 harbor.yml 生成 docker-compose.yamlharbor.v2.7.0.tar.gzDocker 镜像的离线归档包包含所有组件镜像这里要重点说一句不要手动去docker load这个harbor.v2.7.0.tar.gz因为install.sh会自动完成镜像加载。你手动 load 不但重复操作还可能因为加载顺序问题导致后续脚本判断出错出现一些莫名其妙的“已存在”报错。我第一次部署就是手贱手动 load 了一次结果 install.sh 执行时走了另一条分支搞了半天才理清楚。3.2 配置 harbor.yml关键参数逐个说首次部署先把模板复制成正式配置cp harbor.yml.tmpl harbor.yml然后编辑harbor.yml。以下是我实测好用的一份最小配置关键项都加了注释说明hostname: 192.168.1.100 http: port: 80 https: port: 443 certificate: /data/cert/server.crt private_key: /data/cert/server.key harbor_admin_password: Harbor12345 database: password: root123 data_volume: /data/harbor trivy: ignore_unfixed: false skip_update: false insecure: false jobservice: max_job_workers: 10 notification: webhook_job_max_retry: 3 log: level: info local: rotate_count: 50 rotate_size: 200M location: /var/log/harbor这里有几个坑要特别提一下hostname不能乱填。它会被写进 UI 访问地址、镜像推送地址、以及产生的访问凭证中。如果是内网 IP 访问直接填 IP 地址即可如果配置了域名解析就填域名。我见过有人填localhost导致从外部机器推送镜像时报Hostname mismatch排查半天。harbor_admin_password是初始管理员密码默认是Harbor12345。第一次登录一定要进 UI 改掉。如果上面配置了 HTTPS先准备好证书路径否则 prepare 阶段会报证书不存在。data_volume是镜像和数据库存储目录这个路径要选在空间充足的磁盘不要放在根分区。我就是踩过根分区打满导致镜像仓库彻底只读的亏。如果不想配 HTTPS可以把 https 整段注释掉只保留 HTTP。3.3 执行 install.sh脚本到底做了什么配置完成后运行sudo ./install.sh脚本会依次做这些事检查docker和docker-compose是否可用读取harbor.yml把配置转换成环境变量和证书参数向 Docker 加载离线镜像归档调用prepare脚本生成docker-compose.yaml通过docker-compose up -d启动所有 Harbor 容器如果你需要启用漏洞扫描功能执行sudo ./install.sh --with-trivy注意如果安装后想补装 trivy 或 chartmuseumHelm Chart 仓库不能直接重跑 install.sh那样会重建整组容器并可能丢数据。正确做法是重新执行带扩展参数的./prepare再docker-compose down和docker-compose up -d。安装过程如果一路没报错最后会提示Harbor has been installed and started successfully.此时执行docker ps正常情况下你会看到harbor-core、harbor-db、harbor-registry、harbor-portal、nginx、redis、harbor-jobservice等容器都在运行状态。3.4 首次访问验证与登录浏览器访问http://192.168.1.100替换成你的 hostname能出现 Harbor 的 Web 登录页面就是第一步成功。用admin和刚配置的密码登录。然后建议马上做一次镜像推送验证。随便找一个本地小镜像打个 Harbor 标签推送试试docker tag busybox:latest 192.168.1.100/library/busybox:latest docker push 192.168.1.100/library/busybox:latest首次推送会弹出登录提示用刚才的账号密码即可。push 成功说明仓库的存储、认证、网络转发链路都通了。这一步非常关键——只看到 UI 能打开不一定代表仓库可用很多排障问题都要靠 push/pull 才能暴露出来。4. 把 Harbor 从 HTTP 改成 HTTPS完整操作实录热词里有“harbor 的 http 协议改成 https”这是生产环境非常高频率的真实需求。镜像仓库默认走 HTTP但 Docker 客户端对 HTTP 仓库默认是不信任的Linux 上 push/pull 会报server gave HTTP response to HTTPS client错误。改成 HTTPS 是必须的一步。好消息是 v2.7.0 的harbor.yml同时支持 HTTP 和 HTTPS 配置切换起来比老版本优雅得多。4.1 生成自签证书内网环境一般没有正规 CA 签发的证书自签证书是最常用方案。先建证书目录mkdir -p /data/cert cd /data/cert用 OpenSSL 生成私钥和自签证书以 IP 为例openssl genrsa -out server.key 4096 openssl req -new -x509 -days 3650 -key server.key -out server.crt -subj /CN192.168.1.100 -addext subjectAltNameIP:192.168.1.100这里强调一点-addext subjectAltName一定要加。如果 CN 填了 IP 但 SAN 里没有 IPDocker、浏览器在验证证书时依然会报“证书对 IP 无效”。这个坑让我专门花过一下午时间排查。4.2 修改配置文件并重新构建容器编辑harbor.yml先把 https 段的证书路径填好并保留 http 段以做过渡http: port: 80 https: port: 443 certificate: /data/cert/server.crt private_key: /data/cert/server.key然后按顺序执行。注意顺序不能乱先备份配置再执行 prepare最后重启容器cp harbor.yml harbor.yml.bak sudo ./prepare --with-trivy sudo docker-compose down sudo docker-compose up -dprepare会重新生成 docker-compose.yaml并为 nginx 容器挂载新证书。因为保留了 http.port 80重启后 HTTP 依然可用不会出现切完 HTTPS 后旧客户端全断连的“一刀切”事故。等所有客户端都切到 HTTPS 后再注释掉 http 段并再次执行prepare和重启彻底关闭 HTTP。4.3 配置 Docker 客户端信任证书HTTPS 部署完成后最容易被忽略的是 Docker 客户端侧的证书信任。Linux 上通过自签证书访问 Harbor需要在/etc/docker/certs.d/下按仓库地址建目录并放入ca.crtmkdir -p /etc/docker/certs.d/192.168.1.100 cp /data/cert/server.crt /etc/docker/certs.d/192.168.1.100/ca.crt systemctl restart docker注意/etc/docker/certs.d/下的目录名必须与仓库地址严格一致。如果你是用 IP 访问 Harbor目录名就是 IP如果用域名目录名就是域名。改完重启 Docker才能让客户端读入新的 CA 证书。之后执行docker login就能走 HTTPS 正常登录。4.4 切换后最常见的报错与解决切换过程里我遇到最多的是两种报错。第一种是x509: certificate relies on legacy Common Name field这通常出现在新版本 Docker 或 Go 版本较新的系统上解决办法是确保证书 SAN 里有正确的 IP 或域名重新生成证书后覆盖server.crt并重启容器。第二种是connect: connection refused说明 443 端口没监听先看docker ps里 nginx 容器是否正常再用docker logs nginx看日志多半是证书路径配错或 prepare 没执行成功。5. 常见问题与排查技巧实录5.1 容器起不来先看内存Harbor 在低配 ARM 机器上最常见的问题就是内存不足。表现是docker ps能看到部分容器反复重启尤其是harbor-db和redis。排查命令是free -h dmesg | tail -20如果看到Out of memory相关输出就是内存不够。临时办法是停掉不用的服务释放内存治本的办法是加内存或加大 swap。也可以在/etc/docker/daemon.json里加一句log-driver: json-file, log-opts: {max-size: 10m, max-file: 3}避免容器日志撑爆磁盘。5.2 Harbor 目录结构备份与升级注意事项如果将来要升级 Harbor 版本最重要的三样东西是harbor.yml配置、/data/harbor/databasePostgreSQL 数据目录、/data/harbor/registry镜像存储。升级前把这三个都备份好尤其是数据库目录可以通过pg_dump导出或者直接停服后压缩整个数据卷。我习惯在升级前做一个完整的快照备份哪怕机器不支持快照用 tar 打包data_volume也比不备份强。升级完成后用prepare加docker-compose up -d重建容器不要直接跑install.sh否则会重新初始化数据库。5.3 ARM 平台特有的依赖问题ARM 平台部署不像 x86 那样“开箱即用”多常见问题是缺底层工具。热词里有e2fsprogs这是文件系统工具包某些精简系统连mkfs.ext4都没有。建议提前安装apt install e2fsprogs tar openssl curl -y还有一点ARM 机器如果时间不同步会有 HTTPS 证书验证失败、Token 失效等诡异问题。部署前务必确认系统时间正确date不准的话同步一下。这个细节容易被忽略但确实让我踩过坑值得单独列出来。问题现象排查方向镜像无法加载docker load 报 exec format error确认架构包是否匹配uname -minstall.sh 找不到 docker-compose提示命令不存在安装 Compose 或建立软链接浏览器能开 UIpush 失败报 server gave HTTP response改用 HTTPS 并在 Docker 客户端配置 certs.d容器反复重启内存不足 OOMfree -h 查看增加资源或精简组件证书无效x509 报错检查证书 SAN 字段确保 IP/域名匹配升级失败数据不一致备份 harbor.yml 和 data_volume使用 prepare 重建6. 从个人经验角度最后分享几个小技巧我实际操作中发现ARM 设备上跑 Harbor性能虽然不如 x86 服务器平滑但胜在功耗低、环境安静适合做边缘节点和小团队的镜像分发中心。如果只是内部使用不必追求高可用部署单机离线安装完全够用。还有个实用技巧在harbor.yml里把log.level调成debug再来排障问题解决后再改回info。这个操作能让docker logs harbor-core输出更多有效信息很多莫名其妙的问题都能在这里面找到线索。排障完记得改回去否则日志量会非常大。最后如果你打算长期使用 Harbor建议把客户端的docker login信息通过docker config管理不要再手工输入密码既安全又方便自动化流水线引用。镜像仓库是整个 CI/CD 链路的心脏前期花点时间把架构、版本、证书理清楚后面能省下的是连续不断的运维麻烦。本文还有配套的精品资源点击获取