Harbor v2.5.5 ARM64离线部署实战：从安装包到避坑指南

简介Harbor v2.5.5 离线安装包 ARM64 专版面向需要在 ARM 架构服务器或内网环境中部署容器镜像仓库的运维与 DevOps 工程师用于解决无公网环境下安装介质获取困难的问题。包体共 24 个文件包含 docker-compose.yml、harbor.yml 及其模板、install.sh/common.sh 脚本、env 与 conf 配置并附带证书、许可证及离线镜像包 harbor.v2.5.5.tar.gz整体约 531.33MB结构清晰便于直接执行。已有 206 人学习下载说明该包在同类场景中具有实际参考价值。下载后可通过 prepare 脚本与 harbor.yml 完成初始化配置灵活调整认证方式、存储后端与镜像复制规则离线镜像包支持受限网络下快速导入组件镜像显著降低 ARM64 架构下自建私有镜像仓库的部署门槛。1. harbor-offline-installer-v2.5.5-arm64.tgzARM离线部署镜像仓库的先手棋当我把 harbor-offline-installer-v2.5.5-arm64.tgz 传到那台银河麒麟V10 ARM服务器上时心里最没底的不是安装流程而是这个离线包到底适配不适配当前环境。它是Harbor v2.5.5的ARM64离线安装包内含镜像仓库全套核心组件和安装脚本专门给无外网的ARM架构生产环境准备的。这套资源解决两个问题一是没外网也能装Harbor二是官方离线包统一了版本避免网上零散方案互相打架。适合国产化替代场景下的运维、需要在飞腾/鲲鹏上搭建CI/CD镜像仓库的开发者。下文从拆包开始一路讲配置、安装、避坑直到把它用起来。2. 拆开离线包先搞懂装了什么再动手离线安装最忌讳的就是拿到包直接解压、直接跑脚本。Harbor 的 offline installer 不是单纯的源码压缩包它里面嵌套了一个镜像 tar.gz安装脚本会把这部分镜像 docker load 进本地。如果版本或架构不对前面所有操作都白做所以拆包这一步要当成验收来做。2.1 离线包内部结构与版本核对先把 tgz 解压到一个独立目录我一般放在 /opt/harbor 下避免临时文件散落。解压完成后先看顶层文件列表确认镜像包能正常读取。tar -xzf harbor-offline-installer-v2.5.5-arm64.tgz -C /opt/harbor cd /opt/harbor/harbor ls -lh tar -tzf harbor.v2.5.5.tar.gz | head -5解压这个动作本身简单但有些同事图省事直接在生产目录解压后来升级时目录结构非常乱。上面第二行进入解压后的目录ls 看文件第三行是快速验证嵌套的镜像包能否完整读取能列出镜像层文件就说明 gzip 没损坏。如果 tar -tzf 报错不用往下走先重新下载包这是离线部署最常见的翻车点。包内至少会有这几个关键文件install.sh 是部署入口harbor.yml 是配置文件模板common.sh 是公共函数库harbor.v2.5.5.tar.gz 是全部容器镜像的集合。有些版本还会附带 LICENSE 和 prepare 脚本。我建议核对一下镜像包的 sha256官方发布离线包时通常会提供哈希值本地计算后对比一致再继续。sha256sum harbor.v2.5.5.tar.gzsha256sum 输出的是本地镜像包的校验值要和下载页给出的哈希逐位比对。这一步能拦截传输过程中的数据损坏也能防止下载到被篡改的文件。离线包体积大在弱网环境传输时偶发位翻转校验就是后悔药。核对完哈希还要确认包名里的 arm64 和当前机器架构一致。2.2 部署环境与软件依赖清单Harbor 2.5.5 官方要求 Docker Engine 17.06.0 和 Docker Compose 1.18.0但我在 ARM64 环境里实际使用的是 docker 20.10 或 23.0docker compose v2。原因很简单新版 Docker 对 ARM 的容器运行时支持更完整特别是涉及 qemu 模拟 arm64 的场景老版本很容易因为内核调用兼容问题报 exec format error。部署前先跑三条检查命令把架构和依赖一次看清。uname -m docker info | grep -i architecture docker compose versionuname -m 输出 aarch64 才是真正的 ARM64如果输出 x86_64 而系统是 ARM说明你在 qemu 用户态模拟下跑这种环境想正常装 Harbor 很难。docker info 里的 Architecture 要和 uname 保持一致否则后面容器启动时会闹鬼。docker compose version 用于确认 compose 可用Harbor 2.5.5 的 install.sh 会同时识别 docker-compose 和 docker compose 两种命令。我整理的依赖清单大致如下依赖项版本要求实际部署建议操作系统Ubuntu 22.04 ARM / Kylin V10 ARM / CentOS 7 ARM内核 4.15 更可靠Docker Engine17.0620.10 或 23.0 优先Docker Compose1.18v2.20 优先磁盘空间数据目录至少 20GB镜像包解压后约 8GB端口80/443 可配置避免和业务端口冲突墙内墙外的机器都一样离线环境最怕空间不足。这里提醒一句arm64 离线包不兼容 amd64 主机反过来也不行。Harbor 镜像的 manifest 写死了平台就算 docker load 成功容器一启动就是 exec format error。所以部署前先确认包名里的 arm64 和当前机器架构一致这一步能避免后续所有玄学问题。2.3 为什么离线包比在线安装更适合生产很多第一次用 Harbor 的人会问官方不是有在线安装脚本吗为什么非要离线包。在线安装脚本 install.sh 不带 offline 参数时会在部署过程中从 Docker Hub 拉取 goharbor 相关的镜像无外网环境直接卡死在 pull 阶段。离线包的核心逻辑是把所有镜像预先打成 tar.gz安装时 docker load 一次完成整个过程不需要外网。离线包的代价是体积大分发时要有心理准备。在几个节点之间传输常见做法是先在堡垒机上解压一次再用 rsync 或局域网私有源分发别每个人都从头下载。离线包安装后的运维行为和在线安装没有区别都是 docker-compose 管理容器所以不要担心以后没法打补丁。3. 部署Harbor v2.5.5从配置到启动拆包验收完接下来就是动真格。整个部署过程的核心只有一个配置文件 harbor.yml其他都是脚本自动完成。这一章我先讲配置里每个必填项的含义再讲 install.sh 的执行逻辑最后讲怎么自查启动结果。3.1 配置harbor.ymlIP、端口、https还是http先看 harbor.yml 里我重点改的是哪些字段。第一次部署建议只改必填项其他保持默认。最怕的是有人一上来就配 HTTPS证书路径又填错最后连登录都进不去。hostname: 192.168.10.50 http: port: 8080 https: # port: 443 # certificate: /path/to/cert.pem # private_key: /path/to/key.pem data_volume: /data/harbor harbor_admin_password: Harbor2008hostname 一定填访问时用的 IP 或域名别填 localhost。填 localhost 会导致 Docker daemon 解析到本机回环地址而 Harbor 的 registry 服务校验请求时会拒绝非仓库名匹配具体表现就是登录成功但 push 镜像时被拒。http.port 默认 80被占用时改成 8080 这类高位端口但要同步调整 Docker daemon 的 insecure-registries。data_volume 是镜像数据存储位置生产上单独挂载一块数据盘避免系统盘被镜像撑满。harbor_admin_password 默认是 Harbor12345生产必须改密码位数不够 install.sh 会直接报错。如果你需要 HTTPS常见做法是把正式证书放到服务器然后在 https 段填绝对路径。我在 ARM64 环境里吃过一次亏证书放在 /etc/ssl 下但 install.sh 生成的 docker-compose 文件里挂载路径却指向 data_volume容器启动直接找不到文件。解决方法是证书文件也放到 data_volume 目录内或者用绝对路径并确保文件权限 644。需要注意的是harbor.yml 不是直接生效的install.sh 会基于它渲染生成 docker-compose.yml。所以每次改完 harbor.yml必须重新跑 install.sh而不是手动执行 docker compose up -d。3.2 执行install.sh与参数说明配置完成后直接执行 sudo ./install.sh。这个脚本做的事情依次是校验当前环境、生成配置目录、docker load 导入镜像包、基于 harbor.yml 渲染 docker-compose.yml、最后启动全部容器。sudo ./install.sh # 如果需要漏洞扫描可以加参数但离线环境慎用 # sudo ./install.sh --with-trivy裸装核心服务就够了。离线包里默认不包含 trivy 扫描器镜像--with-trivy 会在脚本执行时尝试从外部仓库拉取镜像离线环境会卡在“unable to pull image”然后报错。如果是在有外网的镜像站上部署加这个参数确实能用但既然叫离线安装就别给自己找麻烦。install.sh 执行过程中最关键的输出是 “Generated docker-compose.yml” 和 “aborting” 两处。前者表示模板渲染成功后者表示前置检查失败最常见原因是 docker 服务没启动或端口被占。看到 aborting 别慌翻一下终端前面的输出定位原因。脚本不会自动回滚修复完重新执行一次 install.sh 即可。3.3 启动后自查进程与端口install.sh 跑完Harbor 会用 docker-compose 管理一组服务。我习惯用 docker-compose ps 和 ss 命令确认所有核心容器都处于运行状态。cd /opt/harbor/harbor docker-compose ps ss -lntp | grep -E 8080|443docker-compose ps 输出中 State 列要全是 Up如果看到 Restarting说明某个容器循环崩溃需要拉容器日志定位。Harbor 2.5.5 的核心容器包括 nginx、registry、registryctl、core、portal、jobservice、db、redis它们在 Arm64 环境下的启动顺序由 compose 控制正常情况下一分钟内全部就绪。端口检查用 ss 比 netstat 更直观。如果你在 harbor.yml 里配置了 http.port 8080nginx 就会监听 8080。注意如果 docker ps 一切正常但浏览器打不开优先查服务器防火墙和 SELinux这属于部署环境层面的常见问题和 Harbor 本身关系不大。4. ARM64部署避坑指南现象、原因与解决方案这一章记录的是我多次在 ARM64 上部署 Harbor 的血泪经验。这些坑大多不是 Harbor 本身的 bug而是离线模式叠加架构差异后产生的现象。每一条我都严格按照“现象 → 原因 → 解决”来写方便你直接对照排查。4.1 架构与模拟器带来的坑现象一容器启动后立刻退出docker logs 报exec ./start.sh: no such file or directory或exec format error。这个现象最常出现在使用 qemu 模拟 arm64 的环境里。原因宿主是 x86用 qemu-user 模拟 aarch64但 Docker daemon 没有注册 binfmt_misc 处理器导致无法加载 arm64 格式的二进制或者 qemu-user 版本与容器内动态链接库不匹配。解决在宿主机执行docker run --rm --privileged multiarch/qemu-user-static --reset -p yes注册 binfmt然后重启 docker 再重新执行 install.sh。更稳妥的做法是直接换真实的 ARM64 物理机或云主机别在模拟器上耗时间。现象二在一台 ARM64 机器上 push 的镜像到 amd64 机器上 pull 时报no matching manifest for linux/amd64。原因推送的镜像是单架构 arm64manifest 里没有 amd64 条目Harbor 作为 registry 不会自动做多架构聚合。解决用 docker buildx 构建多架构镜像再 push或者在两个架构上分别构建并打不同标签。arm64 环境里我最常用的做法是显式给镜像打arm64标签避免后续在混合架构集群里产生歧义。4.2 配置与部署层面的坑现象三安装成功且 docker-compose ps 全部 Up但浏览器访问页面显示 502 Bad Gateway。原因harbor.yml 中 hostname 填了 localhost而浏览器访问的是服务器 IP导致 nginx 反代目标地址错误。解决修改 harbor.yml 中的 hostname 为服务器实际 IP重新执行sudo ./install.sh。同时检查防火墙有没有放开对应端口CentOS 7 里我常用firewall-cmd --add-port8080/tcp --permanent放行。现象四镜像推送到一半registry 容器变成 Exiteddocker logs 报no space left on device。原因data_volume 和系统根目录在同一分区离线包解压和镜像存储很快把磁盘占满。解决部署前用 df -h 检查分区容量将 data_volume 指向独立数据盘部署后定期清理悬空镜像和容器日志。Harbor 自带的 Garbage Collection 功能能清理未被引用的 blob但前提是磁盘还有空间所以顺序一定是先扩容再 GC。现象五docker login 报x509: certificate signed by unknown authority。原因Docker 默认要求 HTTPS而 Harbor 用的是 HTTP 端口或者自签名证书不被本地 CA 信任。解决在 Docker daemon 配置文件/etc/docker/daemon.json中加入 insecure-registries 数组然后重启 docker。这一步经常有人忘记等 login 报错才想起来。改完 daemon.json 一定要systemctl restart docker否则 daemon 不会重新读取。5. 验证安装与基础使用让镜像仓库真正跑起来装完不代表能用得把认证、推送、拉取这条链路完整走一遍才算数。这一章从 docker login 开始到用 API 检查系统信息全部是可复现的操作。5.1 用docker login验证认证链路Harbor 的 core 服务负责认证和 Docker 自带的 registry 不同它会在登录时签发一个 token后续的 push/pull 请求都依赖这个 token。所以验证的第一步就是登录。docker login 192.168.10.50:8080 -u admin -p Harbor2008登录成功后docker CLI 会把认证信息写入~/.docker/config.json你可以用cat ~/.docker/config.json确认里面有 auth 字段。这一步失败时先检查端口和协议再检查 daemon.json 里的 insecure-registries。如果配置了但没重启 dockerlogin 依旧走 TLS输出会提示 tls 相关错误这是低级错误里最高发的一种。HTTP 环境下daemon.json 需要这样配置{ insecure-registries: [192.168.10.50:8080] }insecure-registries 是一个数组可以配置多个地址。生产环境如果用了正式域名建议把这个域名也加进去避免证书校验失败。配置完重启 docker再重新 login。5.2 推送与拉取镜像的完整流程登录验证通过后用 nginx 镜像走一遍完整流程。镜像 tag 的格式是仓库地址/项目名/镜像名:标签Harbor 自带一个 library 项目默认公开适合存放基础镜像。docker tag nginx:latest 192.168.10.50:8080/library/nginx:arm64 docker push 192.168.10.50:8080/library/nginx:arm64 docker rmi 192.168.10.50:8080/library/nginx:arm64 docker pull 192.168.10.50:8080/library/nginx:arm64这段命令先给镜像打 tag然后 push 到 library 项目接着删掉本地镜像最后从仓库拉取回来验证 push 上去的数据没有损坏。如果拉取下来的镜像能正常运行这条链路就完整了。push 到非 library 项目时需要在 Harbor 界面或 API 里先创建项目并设置好成员权限。新建项目默认私有其他机器想拉镜像除了登录还要把该机器的用户加入项目成员列表。我一般会创建专门的机器人账号给 CI/CD 用避免把 admin 密码暴露给流水线。5.3 用命令与API验证完整服务镜像能 push/pull 只代表核心 registry 链路可用生产上还要验证核心 API。curl 调一下 Harbor 的 systeminfo 接口能快速确认服务状态。cd /opt/harbor/harbor docker-compose logs --tail50 core curl -u admin:Harbor2008 http://192.168.10.50:8080/api/v2.0/systeminfocurl 返回的 JSON 里包含 harbor_version 和 current_time说明 core 服务和数据库都正常。如果返回 401检查用户名密码返回 404检查路径前缀是不是 /api/v2.0。这个接口我经常用在自动化巡检脚本里配合 cron 定时检查 Harbor 是否存活。日常管理 Harbor 也用 docker-compose 命令最常用的几个是 start、stop、restart、logs。注意不要在 install.sh 之外手动 docker-compose up因为 install.sh 每次都会基于 harbor.yml 重新渲染 compose 文件覆盖手动改动。6. 进阶技巧备份、升级与API管理Harbor 部署完只是开始后边的备份、升级和自动化管理才是真正的功夫。这一章我把最常用的进阶操作拆成三个小块每一块都有可复现的命令。6.1 备份Harbor数据与配置Harbor 的数据主要落在两块PostgreSQL 数据库和 registry 镜像存储。备份时先停服务保证数据一致性再分别备份数据库和 data_volume 目录。cd /opt/harbor/harbor docker-compose stop docker run --rm -v harbor_db-volume:/var/lib/postgresql/data -v /data/backup:/backup \ postgres:13-alpine sh -c pg_dump -U postgres -d harbor /backup/harbor.sql上面命令依赖 Harbor 自带的 postgres 卷。备份完数据库直接把 /data/harbor 整个目录压缩一份再 docker-compose start。恢复时把备份文件放回原路径然后 docker-compose start 即可。版本一致的恢复基本不会出错跨版本恢复另说。6.2 升级到更新版本的注意点Harbor 升级要求逐版本走从 2.5.5 升到 2.6.x需要先下载对应版本的 offline installer然后运行它的 install.sh。升级脚本会保留数据卷但一旦数据格式不兼容迁移可能失败所以升级前必须完整备份。升级结束后确认所有容器 Up 且镜像 push/pull 正常再考虑是否回滚。有一次我升级时遇到迁库脚本卡住原因是旧数据里有一个损坏的 blobGC 没做干净。从那以后每次升级前我都强制走一遍全量备份加镜像清单记录这个习惯让我少走很多弯路。当前镜像列表可以用docker images --format {{.Repository}}:{{.Tag}}导出升级完对照一下数量。6.3 用API管理项目与机器人账号Harbor 2.5.5 的 API 可以完全替代 UI 操作。创建项目、创建机器人账号都通过 HTTP 请求完成适合写进部署脚本。curl -X POST -u admin:Harbor2008 http://192.168.10.50:8080/api/v2.0/projects \ -H Content-Type: application/json \ -d {project_name:ci-images,public:false}参数里 project_name 是项目名public 设为 false 表示私有。创建机器人账号时先调用 /api/v2.0/robots 生成只读凭证再用于 CI 拉取镜像。API 返回的 JSON 里会带 token 和过期时间务必保存。如果 token 丢了就只能重建机器人账号旧的直接作废。备份和升级这两步看起来繁琐但全是血泪经验换来的。经历过那次升级事故之后我再不会在没有完整备份的情况下做任何版本操作甚至日常配置改动也会先 dump 一份 YAML。希望这篇文章帮你在 ARM64 环境里少踩一些坑。本文还有配套的精品资源点击获取