Harbor v2.13.1 ARM64离线安装实战：从架构校验到镜像推送全流程-北京尧图网络

简介本资源为 Harbor 最新 v2.13.1 的 ARM64 架构离线安装包面向在 ARM64 服务器或 Kubernetes 集群上部署私有镜像仓库的运维与 DevOps 人员。相比在线安装方式离线包可避免拉取镜像受网络限制适合内网、信创及国产化平台环境使用。压缩包共 6 个文件以 sh 安装脚本、gz 镜像归档、tmpl 配置模板及 license 许可文件为主整体约 679.05MB覆盖从环境准备到服务启动的完整部署链路。目前已有 527 人学习下载说明该版本在 ARM64 场景下具备一定关注度。借助其中的安装脚本与配置模板读者可快速完成 Harbor 的部署与参数调整并在此基础上理解镜像仓库的组件构成与配置项含义为后续的镜像管理、权限控制与集群集成打下基础。1. 拿到 Harbor v2.13.1 ARM64 离线包先搞清楚它到底解决什么问题如果你手上是一台飞腾、鲲鹏或者 Ampere 的 ARM64 服务器跑在麒麟 V10、统信 UOS 或者 Ubuntu 22.04 ARM64 上内网又不允许直接拉公网镜像那么 Harbor 的 ARM64 离线安装包基本就是刚需。Harbor 是 CNCF 毕业的容器镜像仓库项目负责镜像的存储、签名、扫描、复制和权限控制Kubernetes 集群拉镜像时走的就是它。v2.13.1 这个版本把 Trivy 扫描、OCI Artifact、配额管理都整合进了离线包装完即用不需要再单独联网补组件。离线包的核心价值在于「不依赖外网」。它把 Harbor 的十几个容器镜像、docker-compose 编排文件、安装脚本、证书生成工具全部打包成一个 tar.gz。你在 x64 机器上习惯的那套./install.sh流程在 ARM64 上同样成立但前提是包本身必须是 ARM64 架构编译的。很多人踩的第一个坑就是拿 x64 的离线包往 ARM64 机器上装镜像 manifest 对不上docker load 直接报no matching manifest。这份资源解决的正是「ARM64 架构内网离线」这两个约束叠加的场景适合运维、K8s 平台工程师、信创环境交付人员。2. 离线包结构拆解从 tar.gz 到 docker load 的完整链路2.1 解压后先看目录别急着 install拿到harbor-offline-installer-v2.13.1-arm64.tar.gz之后第一步不是解压完就冲install.sh而是先看清楚里面有什么。标准离线包的目录结构大致如下tar -xzf harbor-offline-installer-v2.13.1-arm64.tar.gz cd harbor ls -lh你会看到这些关键文件文件/目录作用是否必须harbor.v2.13.1.tar.gz所有 Harbor 组件的镜像归档是harbor.yml.tmpl配置文件模板是install.sh安装入口脚本是prepare生成配置、加载镜像是common.sh公共函数库是LICENSE许可文件否harbor.v2.13.1.tar.gz是重头戏里面打包了harbor-core、harbor-portal、harbor-jobservice、harbor-registry、harbor-db、redis、trivy-adapter、nginx等镜像。ARM64 版的这些镜像全部是linux/arm64架构用docker load导入后docker images能看到对应的 arm64 标签。2.2 镜像加载与架构校验在正式安装前建议先手动验证镜像架构避免装到一半才发现包不对# 先加载镜像归档 docker load -i harbor.v2.13.1.tar.gz # 查看导入的镜像列表 docker images | grep goharbor # 校验单个镜像的架构信息 docker inspect goharbor/harbor-core:v2.13.1 --format {{.Architecture}}正常输出应该是arm64。如果输出amd64说明你拿到的不是 ARM64 版离线包后续所有容器都跑不起来。docker load这一步在 ARM64 机器上耗时比 x64 略长因为镜像层解压涉及 CPU 指令集差异一般 3 到 5 分钟属于正常范围。提示如果docker load报no space left on device先检查/var/lib/docker所在分区Harbor 全量镜像加载后大约占用 3 到 4 GB。2.3 harbor.yml 里必须改的四个参数harbor.yml.tmpl复制成harbor.yml后以下参数在 ARM64 离线环境里必须调整# 1. 主机名写实际 IP 或内网 DNS hostname: 192.168.1.100 # 2. HTTP 端口离线环境通常不开 HTTPS http: port: 80 # 3. 注释掉 HTTPS 段除非你有内部 CA # https: # port: 443 # certificate: /your/certificate/path # private_key: /your/private/key/path # 4. 数据目录确保分区容量足够 data_volume: /data/harbor # 5. Trivy 扫描器离线环境需要手动更新漏洞库 trivy: ignore_unfixed: false skip_update: true offline_scan: truehostname如果写成localhost或127.0.0.1K8s 节点无法通过这个地址拉镜像必须写节点能访问到的真实 IP。data_volume默认是/data生产环境建议单独挂一块盘因为镜像层和数据库都会往这里写。trivy.skip_update: true在离线环境里很关键否则 Trivy 启动时会尝试联网更新漏洞库卡住整个安装流程。3. 在麒麟 V10 / Ubuntu 22.04 ARM64 上跑通安装3.1 系统前置条件检查Harbor v2.13.1 对 ARM64 系统的要求不算苛刻但有几项必须提前确认# 确认 CPU 架构 uname -m # 期望输出aarch64 # 确认 Docker 和 docker-compose 版本 docker --version docker compose version # 确认内核参数 sysctl net.ipv4.ip_forward # 期望输出net.ipv4.ip_forward 1 # 确认 80 端口未被占用 ss -tlnp | grep :80Docker 版本建议 20.10 以上docker compose 用 v2 插件版docker compose而不是docker-compose。麒麟 V10 自带的 Docker 版本可能偏低如果低于 20.10需要先升级 Docker 本身。net.ipv4.ip_forward如果为 0Harbor 内部容器网络不通执行sysctl -w net.ipv4.ip_forward1并写入/etc/sysctl.conf。3.2 执行安装脚本与参数说明配置改好后直接跑安装脚本# 生成配置并启动所有容器 ./install.sh # 如果需要带 Trivy 扫描和 Notary 签名 ./install.sh --with-trivy --with-notary # 只装核心组件不装扫描器 ./install.shinstall.sh内部会依次调用prepare生成docker-compose.yml然后执行docker compose up -d。ARM64 上首次启动大约需要 2 到 4 分钟因为数据库初始化和 Trivy 适配器启动比 x64 慢一些。安装完成后脚本会输出访问地址和默认账号密码。# 检查容器状态 docker compose ps # 查看核心服务日志 docker compose logs -f harbor-core # 验证 API 是否就绪 curl -k https://192.168.1.100/api/v2.0/healthdocker compose ps里所有服务状态应该是healthy或running。如果harbor-db一直处于starting多半是data_volume权限问题检查目录属主是否为当前用户。harbor-core日志里出现failed to connect to database时等 30 秒再试数据库初始化在 ARM64 上偶尔会慢一拍。3.3 登录 Web 控制台并推送第一个 ARM64 镜像安装完成后浏览器打开http://192.168.1.100默认账号admin密码在harbor.yml里配置的harbor_admin_password。登录后先建一个项目比如arm64-test然后从命令行推送镜像# 登录 Harbor docker login 192.168.1.100 -u admin -p Harbor12345 # 给本地 ARM64 镜像打标签 docker tag nginx:latest 192.168.1.100/arm64-test/nginx:latest # 推送镜像 docker push 192.168.1.100/arm64-test/nginx:latest推送成功后在 Web 界面能看到镜像的架构标签是arm64。这一步验证了整个链路Docker 客户端 → Harbor 仓库 → 存储后端。如果推送报denied: requested access to the resource is denied检查项目是否设为公开或者用户是否有推送权限。4. 避坑与排查ARM64 离线安装的五个血泪经验4.1 镜像 manifest 不匹配docker load 报错现象docker load -i harbor.v2.13.1.tar.gz执行到一半报no matching manifest for linux/arm64。原因离线包里的镜像归档是 x64 架构编译的或者打包时混入了多架构 manifest 但 ARM64 层缺失。解决确认文件名带arm64标识用docker manifest inspect检查镜像架构。如果确实拿错了包重新获取 ARM64 版本不要试图用--platform强制加载。4.2 Trivy 扫描器启动后一直 unhealthy现象docker compose ps里trivy-adapter状态一直是starting或unhealthy。原因离线环境下 Trivy 尝试联网更新漏洞库超时后反复重试。解决在harbor.yml里设置trivy.skip_update: true和trivy.offline_scan: true然后重新执行./prepare和docker compose up -d。如果需要漏洞库手动下载trivy-db的 OCI 制品导入。4.3 麒麟 V10 上 Docker 版本过低导致 compose 失败现象./install.sh报docker compose command not found或unsupported Compose file version。原因麒麟 V10 自带 Docker 18.09不支持 compose v2 语法。解决升级 Docker 到 20.10 以上安装docker-compose-plugin。如果无法升级改用docker-composev1 并手动转换 compose 文件格式但不推荐Harbor v2.13.1 官方只支持 compose v2。4.4 数据目录权限导致数据库启动失败现象harbor-db容器反复重启日志报Permission denied或data directory has wrong ownership。原因data_volume指定的目录属主不是 UID 999PostgreSQL 容器内用户。解决chown -R 999:999 /data/harbor/database或者直接用默认的/data目录安装脚本会自动处理权限。4.5 推送大镜像时 nginx 超时现象推送超过 1GB 的镜像时docker push报received unexpected HTTP status: 504。原因Harbor 前端 nginx 的proxy_read_timeout默认 900 秒大镜像层上传超时。解决修改common/config/nginx/nginx.conf把proxy_read_timeout和proxy_send_timeout调到 1800 秒然后docker compose restart proxy。5. 进阶离线环境下的镜像复制与漏洞库手动更新5.1 用 Harbor 复制策略打通多集群离线环境里往往不止一个 Harbor 实例比如开发集群和生产集群各一套。Harbor 的复制策略可以在两个实例之间同步镜像但前提是两边网络互通。配置路径是「仓库管理 → 新建目标 → 复制规则」目标 URL 填对端 Harbor 地址认证用对端账号。复制模式选「Push-based」还是「Pull-based」取决于哪边主动发起。ARM64 镜像复制时注意勾选「覆盖」选项否则同名镜像不会更新。# 通过 API 创建复制策略 curl -X POST http://192.168.1.100/api/v2.0/replication/policies \ -H Content-Type: application/json \ -u admin:Harbor12345 \ -d { name: sync-to-prod, src_registry: {id: 0}, dest_registry: {id: 1}, dest_namespace: library, trigger: {type: manual}, filters: [{type: name, value: arm64-*}] }dest_registry.id需要先通过/api/v2.0/registries接口创建目标仓库后获取。filters里的arm64-*是镜像名称匹配规则只复制以arm64-开头的镜像避免把 x64 镜像也同步过去。5.2 Trivy 漏洞库离线更新Trivy 的漏洞库更新在离线环境里是个老大难。常见做法是找一台能联网的机器用trivy image --download-db-only下载trivy-db的 OCI 制品然后导出成 tar 包拷贝到离线环境导入。# 联网机器上下载漏洞库 trivy image --download-db-only --cache-dir /tmp/trivy-cache # 打包缓存目录 tar -czf trivy-db-offline.tar.gz -C /tmp/trivy-cache . # 离线机器上导入 tar -xzf trivy-db-offline.tar.gz -C /data/harbor/trivy-adapter/trivy-cache # 重启 Trivy 适配器 docker compose restart trivy-adapter导入后在 Harbor 界面触发一次扫描确认漏洞库版本号更新。如果扫描结果为空检查trivy-cache目录权限确保容器内用户可读。5.3 验证安装是否真正可用装完不是看到登录页就完事了我一般会走一遍完整验证推一个 ARM64 镜像、拉一个 ARM64 镜像、触发一次漏洞扫描、创建一个复制规则、检查数据库持久化。这套流程走完基本能确认 Harbor 在生产环境可用。# 拉取刚推送的镜像 docker pull 192.168.1.100/arm64-test/nginx:latest # 检查镜像架构 docker inspect 192.168.1.100/arm64-test/nginx:latest --format {{.Architecture}} # 通过 API 触发扫描 curl -X POST http://192.168.1.100/api/v2.0/projects/arm64-test/repositories/nginx/artifacts/latest/scan \ -u admin:Harbor12345从那以后我每次交付 ARM64 离线环境都强制走一遍「架构校验 → 配置检查 → 安装 → 推送拉取 → 扫描」这五步少一步都可能在上线后翻车。希望帮到你。本文还有配套的精品资源点击获取

Harbor v2.13.1 ARM64离线安装实战：从架构校验到镜像推送全流程

相关推荐

C#控制台贪吃蛇实战：从零搭建游戏主循环与集合选型

嵌入式内存管理实战：从内存映射到缓存一致性，避开踩坑

Java图书馆书库管理系统设计：从数据库到借还书实现

更多资讯

YOLOv11工业落地全流程：配置、小目标改进与部署避坑

Yolov11与视觉大模型串联实战：环境配置、小目标优化与Jetson Nano部署

Muscriptor：AI音频转MIDI完整实战指南，从公共实例到本地部署

从激光SLAM到3DGS：机器人建图导航的工程实践与踩坑总结

Omarchy Quattro评测：DHH打造的开发者Linux桌面实战指南

Claude Code 这40个最佳实践彻底改变了我的开发效率：TaoToken 统一 Key 接入 settings.json 配置骨架

今日更新

开源模型端侧落地实战：量化、推理加速与Agent上下文管理

AI Evals实战指南：从零搭建LLM应用评估体系与CI/CD集成

Java采购管理系统实战：从数据库设计到事务一致性

本周精选

如何彻底离线使用 Laya-CoreML：Hugging Face 下载、缓存机制与 local_files_only 详解

基于1Panel 部署MySQL MCP 服务：TaoToken 统一 Key 接入与 config.toml 配置实战

崇州园区营销网站建设避坑指南：5大注意事项保备案安全

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？