简介本资源为面向国产化 ARM 架构环境的 Harbor 容器镜像仓库离线安装包版本为 v2.10.2适合在信创服务器、麒麟/统信等国产操作系统上部署私有镜像仓库的运维与开发人员使用可解决内网无外网条件下快速搭建镜像仓库的问题。压缩包共包含 6 个文件以 shell 脚本、gz 压缩包、license 许可文件、prepare 预处理文件及 tmpl 配置模板为主分别承担安装执行、镜像数据打包、许可声明与配置生成等职责整体约 650.11MB属于典型的离线全量安装形态。目前已有 98 人学习下载说明该版本在国产化替代场景中具备一定关注度。借助该包读者可省去逐一下载组件与镜像的繁琐过程直接完成 Harbor 的离线部署与初始化配置并基于模板文件调整端口、存储与认证参数快速获得可用的私有镜像仓库环境。1. 从 harbor-offline-installer-aarch64-v2.10.2.tgz 说起ARM 内网私有镜像仓库到底难在哪如果你手上正好有一台鲲鹏、飞腾或者银河麒麟的 ARM 服务器又恰好被要求「在内网搭一个 Harbor」那你大概率已经搜到了harbor-offline-installer-aarch64-v2.10.2.tgz这个包。它不是一个普通的压缩包而是 Harbor 官方为 aarch64 架构准备的离线安装器——里面打包了所有容器镜像的 tar 包、docker-compose 编排文件、prepare 脚本和 install.sh解压即用不需要在目标机器上再拉任何外网镜像。这件事在 x86 上早就被写烂了但在 aarch64 上坑的数量至少翻一倍镜像架构不匹配、Docker Compose 版本对不上、内核参数没调、证书路径写死、离线包解压后目录权限丢失任何一个都能让你在客户现场耗掉一整个下午。这篇文章面向的是真正要在 ARM 内网里把 Harbor 跑起来的人——不是看个热闹而是明天就要去机房的那种。我会按「这个包到底是什么 → 环境怎么准备 → 怎么装 → 怎么验证 → 坑在哪 → 怎么进阶」的顺序把 v2.10.2 这个版本在 aarch64 上的完整落地路径讲清楚。中间会给出可直接抄的命令和配置也会说明每个参数为什么这么设。如果你用的是 CentOS 7.9 aarch64、银河麒麟 V10 或者类似的国产 ARM 系统这篇的步骤基本可以直接复用。2. 拆开这个 tgz离线安装器里到底装了什么2.1 离线包与在线安装的本质区别Harbor 的安装方式分两种在线安装器online-installer和离线安装器offline-installer。在线安装器只包含编排文件和脚本安装时通过docker pull从 Docker Hub 拉取 harbor-core、harbor-portal、harbor-db、redis、nginx 等镜像。离线安装器则把这些镜像提前docker save成 tar 包一并塞进压缩包里。harbor-offline-installer-aarch64-v2.10.2.tgz就是后者而且文件名里的aarch64明确告诉你里面的镜像全是 ARM64 架构的。这个区别在纯内网环境里是致命的。很多客户的服务器根本不通外网甚至连内网的 yum 源都不一定有 Harbor 需要的依赖。在线安装器在这种环境下第一步docker pull就会卡死而离线安装器解压后直接docker load全程不需要网络。这也是为什么标题里这个包在 ARM 内网场景下几乎是唯一选择。从体积上看离线包通常在 600MB 到 1GB 之间解压后镜像 tar 包会占用更多空间。所以第一件事是确认/var/lib/docker所在分区至少有 20GB 可用空间/data分区Harbor 默认数据目录至少 50GB。这不是保守估计是血泪经验——harbor-db 的 PostgreSQL 数据、registry 的 blob 存储、redis 的持久化文件都会往/data写镜像一多空间消耗比你想的快得多。2.2 包内目录结构与关键文件解压后你会看到这样的结构harbor/ ├── harbor.v2.10.2.tar.gz # 所有容器镜像的打包文件 ├── harbor.yml.tmpl # 配置模板 ├── prepare # 生成最终 docker-compose.yml 的脚本 ├── install.sh # 一键安装脚本 ├── common.sh # 公共函数库 └── docker-compose.yml.tmpl # 编排模板harbor.yml.tmpl是你要改的核心文件。prepare脚本会读取harbor.yml你从模板复制出来的结合docker-compose.yml.tmpl生成最终的docker-compose.yml。install.sh则依次执行prepare、docker load、docker-compose up -d。理解这个流程很重要因为出问题时你需要知道是哪一步挂了。提示不要直接改docker-compose.yml.tmpl那个文件是模板prepare每次都会重新生成docker-compose.yml你的修改会被覆盖。所有配置改动都在harbor.yml里做。2.3 aarch64 架构带来的额外约束x86 上装 Harbor你基本不用操心镜像架构。但在 aarch64 上如果镜像 tag 对应的 manifest 不是 ARM64docker load之后docker-compose up会直接报exec format error。v2.10.2 的 aarch64 离线包已经帮你处理好了这个问题——里面的镜像都是官方构建的 ARM64 版本。但如果你中途想升级某个组件或者从别处拷了一个 x86 的镜像 tar 包进来就会翻车。另一个约束是 Docker 和 Docker Compose 的版本。Harbor v2.10.2 要求 Docker 20.10 以上、Docker Compose v2 以上。CentOS 7.9 aarch64 默认 yum 源里的 Docker 版本往往偏低需要手动指定版本安装。银河麒麟 V10 的情况类似系统自带的容器工具链版本参差不齐建议统一用 Docker 官方提供的 aarch64 静态二进制包来装。3. 装之前先把地基打好ARM 服务器环境准备清单3.1 系统层内核参数、SELinux 与防火墙在 aarch64 的 CentOS 7.9 或银河麒麟 V10 上装 Harbor 之前有几件事必须先做。第一是内核参数Harbor 的 nginx 和 harbor-core 在高并发下会打开大量文件描述符默认的 1024 不够用# 查看当前限制 ulimit -n # 永久修改写入 /etc/security/limits.conf cat /etc/security/limits.conf EOF * soft nofile 65536 * hard nofile 65536 EOF # 内核层面也调一下 cat /etc/sysctl.conf EOF net.ipv4.ip_forward 1 net.bridge.bridge-nf-call-iptables 1 net.bridge.bridge-nf-call-ip6tables 1 vm.max_map_count 262144 EOF sysctl -pnet.ipv4.ip_forward 1是 Docker 网络转发的前提vm.max_map_count是 Elasticsearch 组件Harbor 的日志存储需要的不设的话 ES 容器会启动失败。bridge-nf-call-iptables这两个参数在 CentOS 7.9 aarch64 上默认可能是关闭的不打开会导致容器间网络不通。第二是 SELinux。Harbor 的容器需要挂载宿主机目录SELinux enforcing 模式下会拒绝这些挂载# 查看状态 getenforce # 临时设为 permissive setenforce 0 # 永久关闭编辑 /etc/selinux/config把 SELINUXenforcing 改为 SELINUXdisabled sed -i s/SELINUXenforcing/SELINUXdisabled/ /etc/selinux/config第三是防火墙。如果你只是内网测试可以直接systemctl stop firewalld systemctl disable firewalld。如果必须开防火墙需要放行 Harbor 用到的端口80HTTP、443HTTPS、4443如果启用 Notary。注意 Harbor 的 nginx 容器会占用宿主机 80 和 443如果宿主机上已经有 nginx 或 httpd 在跑先停掉。3.2 容器运行时Docker 与 Docker Compose 的 aarch64 安装CentOS 7.9 aarch64 的默认 yum 源里Docker 版本通常是 1.13 或更早完全不满足 Harbor v2.10.2 的要求。推荐用 Docker 官方的静态二进制包安装# 下载 aarch64 版本的 Docker 静态包 # 注意这里需要你提前把对应的 tgz 传到内网或者从内网源获取 tar -xzvf docker-24.0.7.tgz cp docker/* /usr/bin/ # 创建 systemd 服务文件 cat /etc/systemd/system/docker.service EOF [Unit] DescriptionDocker Application Container Engine Afternetwork-online.target firewalld.service Wantsnetwork-online.target [Service] Typenotify ExecStart/usr/bin/dockerd ExecReload/bin/kill -s HUP \$MAINPID LimitNOFILEinfinity LimitNPROCinfinity TimeoutStartSec0 Delegateyes KillModeprocess Restarton-failure StartLimitBurst3 StartLimitInterval60s [Install] WantedBymulti-user.target EOF systemctl daemon-reload systemctl enable docker systemctl start docker docker versionDocker Compose 在 v2 之后变成了一个 Go 二进制不再依赖 Python。aarch64 版本可以从内网源获取放到/usr/local/bin/docker-compose并加执行权限即可。验证docker-compose version # 应该输出 Docker Compose version v2.x.x注意Harbor v2.10.2 的install.sh会检查docker-compose命令是否存在。如果你只装了docker compose插件而没有独立的docker-compose二进制脚本会报错。建议两个都装上或者做一个软链接。3.3 存储与目录规划Harbor 默认把数据放在/data目录下包括/data/databasePostgreSQL、/data/registry镜像 blob、/data/redis、/data/log等。在生产环境里建议把/data单独挂一块盘或者至少确保它所在的分区有足够空间。# 创建数据目录 mkdir -p /data # 如果 /data 是单独分区确认挂载 df -h /data # 设置权限Harbor 容器内以特定 UID 运行需要目录可写 chmod 755 /data另外harbor.yml里可以配置data_volume来改变数据目录位置。如果你想把数据放到/opt/harbor-data就在配置里改这一项而不是去改 docker-compose 文件。4. 从解压到登录harbor-offline-installer-aarch64-v2.10.2.tgz 的完整安装流程4.1 解压与 harbor.yml 的最小化配置把 tgz 包传到目标服务器后第一步是解压tar -xzvf harbor-offline-installer-aarch64-v2.10.2.tgz cd harbor ls -lh你会看到harbor.v2.10.2.tar.gz这个镜像包以及harbor.yml.tmpl。复制一份作为实际配置cp harbor.yml.tmpl harbor.yml然后编辑harbor.yml最小化配置只需要改这几项# 主机名可以是 IP 或域名。内网环境建议直接用 IP hostname: 192.168.1.100 # HTTP 配置内网如果不做 HTTPS只留 http 段 http: port: 80 # HTTPS 配置如果不用就整段注释掉 # https: # port: 443 # certificate: /your/certificate/path # private_key: /your/private/key/path # Harbor 管理员初始密码务必改掉默认的 Harbor12345 harbor_admin_password: YourStrongPassword123 # 数据目录 data_volume: /data # 数据库密码离线安装会自动生成也可以手动指定 database: password: root123 max_idle_conns: 100 max_open_conns: 900 # 日志配置 log: level: info local: rotate_count: 50 rotate_size: 200M location: /data/loghostname这一项特别关键。如果你填了 IP后面docker login就必须用这个 IP如果填了域名需要确保内网 DNS 能解析或者在各客户端的/etc/hosts里加记录。填错了会导致docker push时报dial tcp: lookup xxx: no such host。harbor_admin_password是 admin 用户的初始密码v2.10.2 默认是Harbor12345但很多安全扫描会直接把这个默认密码列为高危项。建议在安装前就改掉而不是装完再去 UI 里改。4.2 执行 install.sh 与各阶段日志解读配置改好后执行安装脚本./install.sh这个脚本会依次做几件事每件事的输出都值得关注第一阶段是prepare它会检查harbor.yml的语法然后生成docker-compose.yml。如果这一步报错通常是 YAML 缩进问题或者某个必填项没填。比如hostname为空、data_volume路径不存在等。第二阶段是docker load把harbor.v2.10.2.tar.gz里的镜像逐个加载到本地。这一步在 ARM 服务器上可能比较慢因为镜像层解压和写入磁盘需要时间。如果中途报no space left on device就是/var/lib/docker空间不够。第三阶段是docker-compose up -d启动所有容器。启动完成后脚本会输出----Harbor has been installed and started successfully.----但这不代表所有容器都健康。用以下命令检查docker-compose ps正常情况下你会看到 9 到 10 个容器状态都是Up或Up (healthy)。如果有容器是Exit或Restarting就需要看日志docker-compose logs -f harbor-core docker-compose logs -f harbor-dbharbor-db启动失败最常见的原因是数据目录权限问题或者 PostgreSQL 版本与数据目录不兼容如果你之前装过旧版本/data/database里有旧数据。4.3 验证安装API 健康检查与 docker login容器都起来后先做 API 健康检查curl -k https://192.168.1.100/api/v2.0/health # 如果只配了 HTTP curl http://192.168.1.100/api/v2.0/health正常返回是一个 JSON包含status: healthy。如果返回 502说明 nginx 容器起来了但后端 harbor-core 还没就绪等几十秒再试。然后验证docker logindocker login 192.168.1.100 -u admin -p YourStrongPassword123如果报Error response from daemon: Get https://192.168.1.100/v2/: dial tcp ...: connect: connection refused说明你配了 HTTPS 但证书有问题或者端口不对。如果报x509: certificate signed by unknown authority说明用的是自签证书但 Docker 不信任。内网环境最简单的做法是只配 HTTP然后在 Docker 的 daemon.json 里加insecure-registries{ insecure-registries: [192.168.1.100] }改完重启 Dockersystemctl restart docker。注意重启 Docker 会导致 Harbor 容器全部停止需要重新docker-compose up -d。登录成功后可以做一个完整的 push/pull 测试# 拉一个小的 ARM64 镜像做测试 docker pull arm64v8/alpine:latest # 打 tag docker tag arm64v8/alpine:latest 192.168.1.100/library/alpine:test # push docker push 192.168.1.100/library/alpine:test # 删掉本地镜像再拉回来 docker rmi 192.168.1.100/library/alpine:test docker pull 192.168.1.100/library/alpine:test这一套走通说明 Harbor 的存储、认证、registry 组件都正常。5. 避坑指南aarch64 内网装 Harbor 最容易翻车的 5 个点5.1 现象docker load 报 exec format error原因镜像 tar 包里的镜像不是 ARM64 架构。这种情况通常发生在你从 x86 环境拷贝了某个镜像 tar 包或者离线包在传输过程中被替换过。docker load本身不检查架构但docker-compose up启动时会因为无法执行而报错。解决用docker inspect检查镜像的 Architecture 字段docker inspect harbor-core:v2.10.2 | grep Architecture # 应该输出 Architecture: arm64如果是amd64说明镜像不对。重新从官方 aarch64 离线包里获取或者用docker pull --platform linux/arm64从内网源拉取正确的镜像。5.2 现象harbor-db 容器反复重启日志显示 permission denied原因/data/database目录的属主或权限不对。Harbor 的 PostgreSQL 容器以 UID 999 运行如果宿主机上这个目录是 root 所有且权限是 700容器内进程无法写入。解决chown -R 999:999 /data/database chmod 700 /data/database docker-compose restart harbor-db如果之前已经因为权限问题导致数据目录损坏可能需要清空/data/database重新初始化。注意这会丢失所有 Harbor 的元数据项目、用户、策略但 registry 里的镜像 blob 还在需要重新扫描。5.3 现象docker push 时卡在 Waiting 然后报 413 Request Entity Too Large原因Harbor 的 nginx 容器默认限制请求体大小为 0但某些版本的 nginx 配置模板里可能带了限制。另外如果 Harbor 前面还有一层负载均衡或反向代理那一层也可能有限制。解决检查common/config/nginx/nginx.conf里的client_max_body_sizev2.10.2 默认是 0不限制。如果前面有代理在代理层也放开。另外harbor.yml里可以配max_job_workers和registry的max_threads但 413 通常不是这些参数导致的。5.4 现象安装完成后浏览器访问显示 502 Bad Gateway原因harbor-core 容器还没完全启动或者 harbor-core 依赖的 redis、db 没就绪。Harbor 的组件启动有顺序依赖docker-compose up -d虽然会按 depends_on 顺序启动但容器内的服务就绪还需要时间。解决等 1 到 2 分钟然后看 harbor-core 的日志docker-compose logs --tail100 harbor-core如果日志里还在输出waiting for db或waiting for redis说明依赖组件还没好。如果日志里有panic或fatal那就是配置问题需要根据具体错误排查。5.5 现象重启服务器后 Harbor 没有自动启动原因docker-compose up -d启动的容器默认 restart policy 是no服务器重启后容器不会自动拉起。Harbor 的install.sh没有配置 systemd 服务。解决手动创建一个 systemd 服务cat /etc/systemd/system/harbor.service EOF [Unit] DescriptionHarbor Afterdocker.service systemd-networkd.service systemd-resolved.service Requiresdocker.service Documentationhttp://github.com/vmware/harbor [Service] Typesimple Restarton-failure RestartSec5 ExecStart/usr/bin/docker-compose -f /root/harbor/docker-compose.yml up ExecStop/usr/bin/docker-compose -f /root/harbor/docker-compose.yml down [Install] WantedBymulti-user.target EOF systemctl daemon-reload systemctl enable harbor注意ExecStart里的路径要改成你实际的 harbor 目录。这样服务器重启后 Harbor 会自动拉起。6. 进阶让 ARM 内网 Harbor 真正扛住生产流量装完只是开始。在 aarch64 内网环境里Harbor 要真正当生产仓库用还有几件事值得做。第一是启用 HTTPS。内网虽然可以走 HTTP但 Docker 客户端对 insecure-registry 的支持在有些版本上不稳定而且很多 CI/CD 工具链默认要求 HTTPS。用自签证书的话需要把 CA 证书分发到所有客户端的/etc/docker/certs.d/192.168.1.100/目录下。具体做法是生成 CA 和服务器证书在harbor.yml里配好https段重新执行./install.sh。注意重新执行 install.sh 会重新生成 docker-compose.yml 并重启容器但不会丢失数据。第二是配置存储后端。Harbor 默认把镜像存在本地文件系统对于多节点或需要共享存储的场景可以配 S3 兼容对象存储。在harbor.yml里加storage_service: s3: accesskey: your_access_key secretkey: your_secret_key region: us-west-1 bucket: harbor-registry endpoint: http://minio.internal:9000 insecure: true改完同样需要重新./install.sh。注意切换存储后端不会自动迁移已有镜像需要手动用docker pulldocker push或者 Harbor 的复制功能来迁移。第三是垃圾回收。Harbor 删除镜像后registry 的 blob 不会立即释放需要手动触发 GC# 进入 harbor-db 容器执行 GC docker-compose exec harbor-db psql -U postgres -d registry -c SELECT * FROM blob_upload; # 或者用 Harbor 的 API 触发 curl -u admin:YourPassword -X POST http://192.168.1.100/api/v2.0/system/gc/schedule \ -H Content-Type: application/json \ -d {schedule:{type:Manual}}GC 期间 registry 会进入只读模式建议在业务低峰期做。在 ARM 服务器上GC 的 CPU 和 IO 消耗比 x86 更明显因为 ARM 的单核性能通常弱一些大仓库的 GC 可能跑几十分钟。第四是监控。Harbor 暴露了 Prometheus 格式的 metrics在harbor.yml里可以配metrics段开启。对于 ARM 内网环境建议至少监控/data分区使用率、harbor-core 的 JVM 堆内存如果用的是 Java 组件、以及 registry 的请求延迟。我一般会在 Harbor 同一台机器上跑一个轻量级的 node_exporter 和 cAdvisor用 Prometheus 抓取Grafana 出图。ARM 上跑这些监控组件资源消耗不大但能让你在磁盘写满之前收到告警。最后说一个我自己的习惯每次在客户现场装完 Harbor我都会立刻做一个「恢复演练」——把/data目录打包备份然后故意删掉一个测试项目再从备份里恢复。这个动作花不了十分钟但能让你在真正出问题时心里有底。ARM 内网环境往往没有外网可以查资料现场能依靠的只有自己的笔记和备份。希望帮到你。本文还有配套的精品资源点击获取 ARM内网离线部署Harbor v2.10.2：aarch64私有镜像仓库实战指南
简介本资源为面向国产化 ARM 架构环境的 Harbor 容器镜像仓库离线安装包版本为 v2.10.2适合在信创服务器、麒麟/统信等国产操作系统上部署私有镜像仓库的运维与开发人员使用可解决内网无外网条件下快速搭建镜像仓库的问题。压缩包共包含 6 个文件以 shell 脚本、gz 压缩包、license 许可文件、prepare 预处理文件及 tmpl 配置模板为主分别承担安装执行、镜像数据打包、许可声明与配置生成等职责整体约 650.11MB属于典型的离线全量安装形态。目前已有 98 人学习下载说明该版本在国产化替代场景中具备一定关注度。借助该包读者可省去逐一下载组件与镜像的繁琐过程直接完成 Harbor 的离线部署与初始化配置并基于模板文件调整端口、存储与认证参数快速获得可用的私有镜像仓库环境。1. 从 harbor-offline-installer-aarch64-v2.10.2.tgz 说起ARM 内网私有镜像仓库到底难在哪如果你手上正好有一台鲲鹏、飞腾或者银河麒麟的 ARM 服务器又恰好被要求「在内网搭一个 Harbor」那你大概率已经搜到了harbor-offline-installer-aarch64-v2.10.2.tgz这个包。它不是一个普通的压缩包而是 Harbor 官方为 aarch64 架构准备的离线安装器——里面打包了所有容器镜像的 tar 包、docker-compose 编排文件、prepare 脚本和 install.sh解压即用不需要在目标机器上再拉任何外网镜像。这件事在 x86 上早就被写烂了但在 aarch64 上坑的数量至少翻一倍镜像架构不匹配、Docker Compose 版本对不上、内核参数没调、证书路径写死、离线包解压后目录权限丢失任何一个都能让你在客户现场耗掉一整个下午。这篇文章面向的是真正要在 ARM 内网里把 Harbor 跑起来的人——不是看个热闹而是明天就要去机房的那种。我会按「这个包到底是什么 → 环境怎么准备 → 怎么装 → 怎么验证 → 坑在哪 → 怎么进阶」的顺序把 v2.10.2 这个版本在 aarch64 上的完整落地路径讲清楚。中间会给出可直接抄的命令和配置也会说明每个参数为什么这么设。如果你用的是 CentOS 7.9 aarch64、银河麒麟 V10 或者类似的国产 ARM 系统这篇的步骤基本可以直接复用。2. 拆开这个 tgz离线安装器里到底装了什么2.1 离线包与在线安装的本质区别Harbor 的安装方式分两种在线安装器online-installer和离线安装器offline-installer。在线安装器只包含编排文件和脚本安装时通过docker pull从 Docker Hub 拉取 harbor-core、harbor-portal、harbor-db、redis、nginx 等镜像。离线安装器则把这些镜像提前docker save成 tar 包一并塞进压缩包里。harbor-offline-installer-aarch64-v2.10.2.tgz就是后者而且文件名里的aarch64明确告诉你里面的镜像全是 ARM64 架构的。这个区别在纯内网环境里是致命的。很多客户的服务器根本不通外网甚至连内网的 yum 源都不一定有 Harbor 需要的依赖。在线安装器在这种环境下第一步docker pull就会卡死而离线安装器解压后直接docker load全程不需要网络。这也是为什么标题里这个包在 ARM 内网场景下几乎是唯一选择。从体积上看离线包通常在 600MB 到 1GB 之间解压后镜像 tar 包会占用更多空间。所以第一件事是确认/var/lib/docker所在分区至少有 20GB 可用空间/data分区Harbor 默认数据目录至少 50GB。这不是保守估计是血泪经验——harbor-db 的 PostgreSQL 数据、registry 的 blob 存储、redis 的持久化文件都会往/data写镜像一多空间消耗比你想的快得多。2.2 包内目录结构与关键文件解压后你会看到这样的结构harbor/ ├── harbor.v2.10.2.tar.gz # 所有容器镜像的打包文件 ├── harbor.yml.tmpl # 配置模板 ├── prepare # 生成最终 docker-compose.yml 的脚本 ├── install.sh # 一键安装脚本 ├── common.sh # 公共函数库 └── docker-compose.yml.tmpl # 编排模板harbor.yml.tmpl是你要改的核心文件。prepare脚本会读取harbor.yml你从模板复制出来的结合docker-compose.yml.tmpl生成最终的docker-compose.yml。install.sh则依次执行prepare、docker load、docker-compose up -d。理解这个流程很重要因为出问题时你需要知道是哪一步挂了。提示不要直接改docker-compose.yml.tmpl那个文件是模板prepare每次都会重新生成docker-compose.yml你的修改会被覆盖。所有配置改动都在harbor.yml里做。2.3 aarch64 架构带来的额外约束x86 上装 Harbor你基本不用操心镜像架构。但在 aarch64 上如果镜像 tag 对应的 manifest 不是 ARM64docker load之后docker-compose up会直接报exec format error。v2.10.2 的 aarch64 离线包已经帮你处理好了这个问题——里面的镜像都是官方构建的 ARM64 版本。但如果你中途想升级某个组件或者从别处拷了一个 x86 的镜像 tar 包进来就会翻车。另一个约束是 Docker 和 Docker Compose 的版本。Harbor v2.10.2 要求 Docker 20.10 以上、Docker Compose v2 以上。CentOS 7.9 aarch64 默认 yum 源里的 Docker 版本往往偏低需要手动指定版本安装。银河麒麟 V10 的情况类似系统自带的容器工具链版本参差不齐建议统一用 Docker 官方提供的 aarch64 静态二进制包来装。3. 装之前先把地基打好ARM 服务器环境准备清单3.1 系统层内核参数、SELinux 与防火墙在 aarch64 的 CentOS 7.9 或银河麒麟 V10 上装 Harbor 之前有几件事必须先做。第一是内核参数Harbor 的 nginx 和 harbor-core 在高并发下会打开大量文件描述符默认的 1024 不够用# 查看当前限制 ulimit -n # 永久修改写入 /etc/security/limits.conf cat /etc/security/limits.conf EOF * soft nofile 65536 * hard nofile 65536 EOF # 内核层面也调一下 cat /etc/sysctl.conf EOF net.ipv4.ip_forward 1 net.bridge.bridge-nf-call-iptables 1 net.bridge.bridge-nf-call-ip6tables 1 vm.max_map_count 262144 EOF sysctl -pnet.ipv4.ip_forward 1是 Docker 网络转发的前提vm.max_map_count是 Elasticsearch 组件Harbor 的日志存储需要的不设的话 ES 容器会启动失败。bridge-nf-call-iptables这两个参数在 CentOS 7.9 aarch64 上默认可能是关闭的不打开会导致容器间网络不通。第二是 SELinux。Harbor 的容器需要挂载宿主机目录SELinux enforcing 模式下会拒绝这些挂载# 查看状态 getenforce # 临时设为 permissive setenforce 0 # 永久关闭编辑 /etc/selinux/config把 SELINUXenforcing 改为 SELINUXdisabled sed -i s/SELINUXenforcing/SELINUXdisabled/ /etc/selinux/config第三是防火墙。如果你只是内网测试可以直接systemctl stop firewalld systemctl disable firewalld。如果必须开防火墙需要放行 Harbor 用到的端口80HTTP、443HTTPS、4443如果启用 Notary。注意 Harbor 的 nginx 容器会占用宿主机 80 和 443如果宿主机上已经有 nginx 或 httpd 在跑先停掉。3.2 容器运行时Docker 与 Docker Compose 的 aarch64 安装CentOS 7.9 aarch64 的默认 yum 源里Docker 版本通常是 1.13 或更早完全不满足 Harbor v2.10.2 的要求。推荐用 Docker 官方的静态二进制包安装# 下载 aarch64 版本的 Docker 静态包 # 注意这里需要你提前把对应的 tgz 传到内网或者从内网源获取 tar -xzvf docker-24.0.7.tgz cp docker/* /usr/bin/ # 创建 systemd 服务文件 cat /etc/systemd/system/docker.service EOF [Unit] DescriptionDocker Application Container Engine Afternetwork-online.target firewalld.service Wantsnetwork-online.target [Service] Typenotify ExecStart/usr/bin/dockerd ExecReload/bin/kill -s HUP \$MAINPID LimitNOFILEinfinity LimitNPROCinfinity TimeoutStartSec0 Delegateyes KillModeprocess Restarton-failure StartLimitBurst3 StartLimitInterval60s [Install] WantedBymulti-user.target EOF systemctl daemon-reload systemctl enable docker systemctl start docker docker versionDocker Compose 在 v2 之后变成了一个 Go 二进制不再依赖 Python。aarch64 版本可以从内网源获取放到/usr/local/bin/docker-compose并加执行权限即可。验证docker-compose version # 应该输出 Docker Compose version v2.x.x注意Harbor v2.10.2 的install.sh会检查docker-compose命令是否存在。如果你只装了docker compose插件而没有独立的docker-compose二进制脚本会报错。建议两个都装上或者做一个软链接。3.3 存储与目录规划Harbor 默认把数据放在/data目录下包括/data/databasePostgreSQL、/data/registry镜像 blob、/data/redis、/data/log等。在生产环境里建议把/data单独挂一块盘或者至少确保它所在的分区有足够空间。# 创建数据目录 mkdir -p /data # 如果 /data 是单独分区确认挂载 df -h /data # 设置权限Harbor 容器内以特定 UID 运行需要目录可写 chmod 755 /data另外harbor.yml里可以配置data_volume来改变数据目录位置。如果你想把数据放到/opt/harbor-data就在配置里改这一项而不是去改 docker-compose 文件。4. 从解压到登录harbor-offline-installer-aarch64-v2.10.2.tgz 的完整安装流程4.1 解压与 harbor.yml 的最小化配置把 tgz 包传到目标服务器后第一步是解压tar -xzvf harbor-offline-installer-aarch64-v2.10.2.tgz cd harbor ls -lh你会看到harbor.v2.10.2.tar.gz这个镜像包以及harbor.yml.tmpl。复制一份作为实际配置cp harbor.yml.tmpl harbor.yml然后编辑harbor.yml最小化配置只需要改这几项# 主机名可以是 IP 或域名。内网环境建议直接用 IP hostname: 192.168.1.100 # HTTP 配置内网如果不做 HTTPS只留 http 段 http: port: 80 # HTTPS 配置如果不用就整段注释掉 # https: # port: 443 # certificate: /your/certificate/path # private_key: /your/private/key/path # Harbor 管理员初始密码务必改掉默认的 Harbor12345 harbor_admin_password: YourStrongPassword123 # 数据目录 data_volume: /data # 数据库密码离线安装会自动生成也可以手动指定 database: password: root123 max_idle_conns: 100 max_open_conns: 900 # 日志配置 log: level: info local: rotate_count: 50 rotate_size: 200M location: /data/loghostname这一项特别关键。如果你填了 IP后面docker login就必须用这个 IP如果填了域名需要确保内网 DNS 能解析或者在各客户端的/etc/hosts里加记录。填错了会导致docker push时报dial tcp: lookup xxx: no such host。harbor_admin_password是 admin 用户的初始密码v2.10.2 默认是Harbor12345但很多安全扫描会直接把这个默认密码列为高危项。建议在安装前就改掉而不是装完再去 UI 里改。4.2 执行 install.sh 与各阶段日志解读配置改好后执行安装脚本./install.sh这个脚本会依次做几件事每件事的输出都值得关注第一阶段是prepare它会检查harbor.yml的语法然后生成docker-compose.yml。如果这一步报错通常是 YAML 缩进问题或者某个必填项没填。比如hostname为空、data_volume路径不存在等。第二阶段是docker load把harbor.v2.10.2.tar.gz里的镜像逐个加载到本地。这一步在 ARM 服务器上可能比较慢因为镜像层解压和写入磁盘需要时间。如果中途报no space left on device就是/var/lib/docker空间不够。第三阶段是docker-compose up -d启动所有容器。启动完成后脚本会输出----Harbor has been installed and started successfully.----但这不代表所有容器都健康。用以下命令检查docker-compose ps正常情况下你会看到 9 到 10 个容器状态都是Up或Up (healthy)。如果有容器是Exit或Restarting就需要看日志docker-compose logs -f harbor-core docker-compose logs -f harbor-dbharbor-db启动失败最常见的原因是数据目录权限问题或者 PostgreSQL 版本与数据目录不兼容如果你之前装过旧版本/data/database里有旧数据。4.3 验证安装API 健康检查与 docker login容器都起来后先做 API 健康检查curl -k https://192.168.1.100/api/v2.0/health # 如果只配了 HTTP curl http://192.168.1.100/api/v2.0/health正常返回是一个 JSON包含status: healthy。如果返回 502说明 nginx 容器起来了但后端 harbor-core 还没就绪等几十秒再试。然后验证docker logindocker login 192.168.1.100 -u admin -p YourStrongPassword123如果报Error response from daemon: Get https://192.168.1.100/v2/: dial tcp ...: connect: connection refused说明你配了 HTTPS 但证书有问题或者端口不对。如果报x509: certificate signed by unknown authority说明用的是自签证书但 Docker 不信任。内网环境最简单的做法是只配 HTTP然后在 Docker 的 daemon.json 里加insecure-registries{ insecure-registries: [192.168.1.100] }改完重启 Dockersystemctl restart docker。注意重启 Docker 会导致 Harbor 容器全部停止需要重新docker-compose up -d。登录成功后可以做一个完整的 push/pull 测试# 拉一个小的 ARM64 镜像做测试 docker pull arm64v8/alpine:latest # 打 tag docker tag arm64v8/alpine:latest 192.168.1.100/library/alpine:test # push docker push 192.168.1.100/library/alpine:test # 删掉本地镜像再拉回来 docker rmi 192.168.1.100/library/alpine:test docker pull 192.168.1.100/library/alpine:test这一套走通说明 Harbor 的存储、认证、registry 组件都正常。5. 避坑指南aarch64 内网装 Harbor 最容易翻车的 5 个点5.1 现象docker load 报 exec format error原因镜像 tar 包里的镜像不是 ARM64 架构。这种情况通常发生在你从 x86 环境拷贝了某个镜像 tar 包或者离线包在传输过程中被替换过。docker load本身不检查架构但docker-compose up启动时会因为无法执行而报错。解决用docker inspect检查镜像的 Architecture 字段docker inspect harbor-core:v2.10.2 | grep Architecture # 应该输出 Architecture: arm64如果是amd64说明镜像不对。重新从官方 aarch64 离线包里获取或者用docker pull --platform linux/arm64从内网源拉取正确的镜像。5.2 现象harbor-db 容器反复重启日志显示 permission denied原因/data/database目录的属主或权限不对。Harbor 的 PostgreSQL 容器以 UID 999 运行如果宿主机上这个目录是 root 所有且权限是 700容器内进程无法写入。解决chown -R 999:999 /data/database chmod 700 /data/database docker-compose restart harbor-db如果之前已经因为权限问题导致数据目录损坏可能需要清空/data/database重新初始化。注意这会丢失所有 Harbor 的元数据项目、用户、策略但 registry 里的镜像 blob 还在需要重新扫描。5.3 现象docker push 时卡在 Waiting 然后报 413 Request Entity Too Large原因Harbor 的 nginx 容器默认限制请求体大小为 0但某些版本的 nginx 配置模板里可能带了限制。另外如果 Harbor 前面还有一层负载均衡或反向代理那一层也可能有限制。解决检查common/config/nginx/nginx.conf里的client_max_body_sizev2.10.2 默认是 0不限制。如果前面有代理在代理层也放开。另外harbor.yml里可以配max_job_workers和registry的max_threads但 413 通常不是这些参数导致的。5.4 现象安装完成后浏览器访问显示 502 Bad Gateway原因harbor-core 容器还没完全启动或者 harbor-core 依赖的 redis、db 没就绪。Harbor 的组件启动有顺序依赖docker-compose up -d虽然会按 depends_on 顺序启动但容器内的服务就绪还需要时间。解决等 1 到 2 分钟然后看 harbor-core 的日志docker-compose logs --tail100 harbor-core如果日志里还在输出waiting for db或waiting for redis说明依赖组件还没好。如果日志里有panic或fatal那就是配置问题需要根据具体错误排查。5.5 现象重启服务器后 Harbor 没有自动启动原因docker-compose up -d启动的容器默认 restart policy 是no服务器重启后容器不会自动拉起。Harbor 的install.sh没有配置 systemd 服务。解决手动创建一个 systemd 服务cat /etc/systemd/system/harbor.service EOF [Unit] DescriptionHarbor Afterdocker.service systemd-networkd.service systemd-resolved.service Requiresdocker.service Documentationhttp://github.com/vmware/harbor [Service] Typesimple Restarton-failure RestartSec5 ExecStart/usr/bin/docker-compose -f /root/harbor/docker-compose.yml up ExecStop/usr/bin/docker-compose -f /root/harbor/docker-compose.yml down [Install] WantedBymulti-user.target EOF systemctl daemon-reload systemctl enable harbor注意ExecStart里的路径要改成你实际的 harbor 目录。这样服务器重启后 Harbor 会自动拉起。6. 进阶让 ARM 内网 Harbor 真正扛住生产流量装完只是开始。在 aarch64 内网环境里Harbor 要真正当生产仓库用还有几件事值得做。第一是启用 HTTPS。内网虽然可以走 HTTP但 Docker 客户端对 insecure-registry 的支持在有些版本上不稳定而且很多 CI/CD 工具链默认要求 HTTPS。用自签证书的话需要把 CA 证书分发到所有客户端的/etc/docker/certs.d/192.168.1.100/目录下。具体做法是生成 CA 和服务器证书在harbor.yml里配好https段重新执行./install.sh。注意重新执行 install.sh 会重新生成 docker-compose.yml 并重启容器但不会丢失数据。第二是配置存储后端。Harbor 默认把镜像存在本地文件系统对于多节点或需要共享存储的场景可以配 S3 兼容对象存储。在harbor.yml里加storage_service: s3: accesskey: your_access_key secretkey: your_secret_key region: us-west-1 bucket: harbor-registry endpoint: http://minio.internal:9000 insecure: true改完同样需要重新./install.sh。注意切换存储后端不会自动迁移已有镜像需要手动用docker pulldocker push或者 Harbor 的复制功能来迁移。第三是垃圾回收。Harbor 删除镜像后registry 的 blob 不会立即释放需要手动触发 GC# 进入 harbor-db 容器执行 GC docker-compose exec harbor-db psql -U postgres -d registry -c SELECT * FROM blob_upload; # 或者用 Harbor 的 API 触发 curl -u admin:YourPassword -X POST http://192.168.1.100/api/v2.0/system/gc/schedule \ -H Content-Type: application/json \ -d {schedule:{type:Manual}}GC 期间 registry 会进入只读模式建议在业务低峰期做。在 ARM 服务器上GC 的 CPU 和 IO 消耗比 x86 更明显因为 ARM 的单核性能通常弱一些大仓库的 GC 可能跑几十分钟。第四是监控。Harbor 暴露了 Prometheus 格式的 metrics在harbor.yml里可以配metrics段开启。对于 ARM 内网环境建议至少监控/data分区使用率、harbor-core 的 JVM 堆内存如果用的是 Java 组件、以及 registry 的请求延迟。我一般会在 Harbor 同一台机器上跑一个轻量级的 node_exporter 和 cAdvisor用 Prometheus 抓取Grafana 出图。ARM 上跑这些监控组件资源消耗不大但能让你在磁盘写满之前收到告警。最后说一个我自己的习惯每次在客户现场装完 Harbor我都会立刻做一个「恢复演练」——把/data目录打包备份然后故意删掉一个测试项目再从备份里恢复。这个动作花不了十分钟但能让你在真正出问题时心里有底。ARM 内网环境往往没有外网可以查资料现场能依靠的只有自己的笔记和备份。希望帮到你。本文还有配套的精品资源点击获取