ARM64离线部署Harbor v2.13.1：信创环境私有镜像仓库实战指南

简介：这份资源是 Harbor 最新 v2.13.1 的 ARM64 架构离线安装包，面向在 ARM64 服务器或 Kubernetes 集群上部署私有镜像仓库的运维与 DevOps 人员，解决国产化平台、信创环境或边缘节点无法直接拉取官方 x86 镜像、在线安装受网络限制的问题。压缩包共 6 个文件，以 sh 安装脚本、gz 镜像归档、prepare 预处理脚本、tmpl 配置模板及 LICENSE 许可文件为主，整体约 679.05MB，覆盖从环境准备、参数配置到一键安装的完整离线流程。内容包含 Harbor 核心镜像归档与可编辑的 harbor.yml 模板，便于按需调整存储、端口、HTTPS 与外部数据库等参数，适合具备 Docker 与 Kubernetes 基础的中高级用户快速搭建私有镜像仓库。目前已有 528 人学习下载，可作为 ARM64 环境下 Harbor 部署与排错的实用参考。

1. 离线部署 Harbor v2.13.1 ARM64：为什么这件事比你想的更值得做

在国产化替代和信创环境里摸爬滚打过的工程师，大概率都遇到过同一个尴尬：机房里的服务器是 ARM64 架构，网络是物理隔离的，而你需要一套私有容器镜像仓库。x86 的 Harbor 离线包满地都是，ARM64 的却要自己从源码编译，或者从零散的地方拼凑。Harbor v2.13.1 的 ARM64 离线安装包解决的正是这个场景——它把 registry、portal、core、jobservice、trivy 等所有组件的 ARM64 镜像和部署编排文件打包成一个压缩包，让你在无外网的 ARM64 机器上一条命令拉起完整的镜像仓库服务。

这篇文章面向三类人：一是在 ARM64 服务器上部署私有仓库的运维工程师，二是需要在离线环境搭建 CI/CD 镜像中转站的 DevOps，三是正在做信创适配、需要验证 Harbor 在 ARM64 上可用性的架构师。我会把整个流程拆成可复现的步骤，包括环境准备、安装包结构解析、配置参数怎么调、启动后怎么验证、以及我踩过的那些坑。读完你至少能判断：这套方案在你的环境里能不能跑通，需要提前准备什么，哪些参数不改会出事。

2. 动手之前：ARM64 离线安装包的结构与依赖清单

2.1 安装包里到底有什么

拿到一个 Harbor 离线安装包，第一件事不是急着解压执行，而是先看清楚它的目录结构。ARM64 版本的离线包和 x86 版本在文件组织上是一致的，核心区别在于images目录下所有镜像的架构标签都是arm64。解压后你会看到这样的结构：

harbor/ ├── harbor.yml.tmpl # 配置模板，需要复制为 harbor.yml 后修改 ├── install.sh # 主安装脚本 ├── prepare # 环境预检脚本 ├── common.sh # 公共函数库 ├── docker-compose.yml # 容器编排定义 ├── images/ # 所有组件的离线镜像 tar 包 │ ├── harbor-core.tar │ ├── harbor-portal.tar │ ├── harbor-registry.tar │ ├── harbor-jobservice.tar │ ├── harbor-db.tar │ ├── harbor-redis.tar │ ├── harbor-trivy.tar │ ├── nginx-photon.tar │ └── ... └── LICENSE

images目录是离线安装的核心价值所在。在线安装时，install.sh会从远程仓库拉取镜像；离线安装时，脚本会先执行docker load把这些 tar 包导入本地镜像库，然后再用docker-compose启动服务。所以判断一个离线包是否完整，最直接的方法就是看images目录下的 tar 包数量和大小是否正常——完整的 v2.13.1 ARM64 离线包解压后大约在 2GB 到 3GB 之间，如果只有几百 MB，大概率是缺了 trivy 或者 registry 的镜像。

2.2 系统层面的前置条件

Harbor 对宿主机的依赖不算复杂，但在 ARM64 平台上有几个容易忽略的点。下面这张表是我整理的最低要求和推荐配置：

确认 Docker 和 Compose 是否就绪，执行下面这组命令：

# 确认 CPU 架构，输出必须是 aarch64 或 arm64 uname -m # 确认 Docker 版本，需要 20.10 以上 docker version --format '{{.Server.Version}}' # 确认 Docker Compose 版本，v2 语法和 v1 有差异 docker compose version # 确认内核版本，低版本内核可能有 cgroup 兼容问题 uname -r

这里有个血泪经验：很多 ARM64 服务器出厂预装的是 Docker 18.09 或 19.03，这些版本对 compose v2 的支持不完整，install.sh执行到一半会报unknown flag: --compatibility之类的错误。遇到这种情况不要试图改脚本绕过，直接升级 Docker 到 20.10 以上更省事。另外，如果你的环境用的是 podman 而不是 Docker，Harbor 的官方安装脚本是不认的，需要手动把docker命令替换成podman并调整 compose 调用方式，这个改造成本不低，建议还是用 Docker。

2.3 网络与端口规划

离线环境虽然不需要外网，但端口该占的还是要占。Harbor 默认使用 80 和 443 端口，如果你打算用自定义端口或者前面挂一层负载均衡，需要在harbor.yml里改。下面这几个端口是 Harbor 组件之间内部通信用的，不需要对外暴露，但也不能和宿主机上已有服务冲突：

• 8080：Harbor core 的内部 API 端口
• 5432：PostgreSQL 数据库
• 6379：Redis 缓存
• 9090：Jobservice 的指标端口

我一般会在部署前先跑一遍ss -tlnp看看这些端口有没有被占用。如果 80 端口被 nginx 占了，要么改 Harbor 的端口，要么把宿主机的 nginx 停掉——后者在测试环境可以，生产环境千万别这么干。

3. 从解压到启动：ARM64 离线安装的完整操作链

3.1 解压与配置文件的生成

把离线包上传到目标服务器后，找一个空间充足的目录解压。我习惯放在/opt下面，方便后续管理：

# 创建安装目录并解压 mkdir -p /opt/harbor-install tar -xzf harbor-offline-installer-v2.13.1-arm64.tgz -C /opt/harbor-install # 进入解压后的目录 cd /opt/harbor-install/harbor # 从模板生成配置文件 cp harbor.yml.tmpl harbor.yml

解压完成后不要急着执行install.sh，先把harbor.yml改对。这个文件里每一项都影响最终部署结果，下面我挑几个 ARM64 环境下必须关注的参数逐个说明。

3.2 harbor.yml 里必须改的五个参数

打开harbor.yml，找到下面这几个配置项：

# 1. 主机名，改成服务器的实际 IP 或域名 hostname: 192.168.1.100 # 2. HTTP 端口，如果 80 被占用改成其他值 http: port: 80 # 3. HTTPS 配置，离线环境如果没有证书可以先注释掉 # https: # port: 443 # certificate: /your/certificate/path # private_key: /your/private/key/path # 4. 管理员初始密码，第一次登录后立即改掉 harbor_admin_password: Harbor12345 # 5. 数据存储路径，确保磁盘空间充足 data_volume: /data/harbor # 6. 数据库密码，生产环境必须改 database: password: root123 max_idle_conns: 100 max_open_conns: 900

hostname这一项特别容易翻车。如果你填的是localhost或者127.0.0.1，安装能成功，但其他机器推送镜像时会解析失败。正确做法是填服务器的局域网 IP 或者内网 DNS 能解析的域名。另外，data_volume指向的目录如果不存在，install.sh会自动创建，但如果父目录权限不对，创建会失败，报permission denied。我一般提前手动建好并确认权限：

# 提前创建数据目录并确认权限 mkdir -p /data/harbor chmod 750 /data/harbor

还有一个 ARM64 特有的注意点：harbor.yml里有一个trivy配置段，控制镜像漏洞扫描功能。如果你的 ARM64 环境内存比较紧张（比如只有 4GB），建议把 trivy 关掉，否则启动后 trivy 容器会频繁 OOM：

# 内存不足时关闭 trivy trivy: ignore_unfixed: false skip_update: false enabled: false

3.3 执行安装脚本与启动过程观察

配置改好后，执行安装脚本。这个脚本会依次完成镜像导入、配置渲染、容器启动三个阶段：

# 执行安装，--with-trivy 表示启用漏洞扫描 # 如果前面关了 trivy，这里就不要加这个参数 ./install.sh --with-trivy

脚本执行过程中，你会看到类似下面的输出：

[Step 0]: checking if docker is installed ... [Step 1]: checking docker-compose is installed ... [Step 2]: loading Harbor images ... Loaded image: harbor-core:v2.13.1 Loaded image: harbor-portal:v2.13.1 ... [Step 3]: preparing environment ... [Step 4]: preparing harbor configs ... [Step 5]: starting Harbor ... Creating network "harbor_harbor" with the default driver Creating harbor-log ... done Creating harbor-db ... done Creating harbor-redis ... done Creating harbor-core ... done Creating harbor-portal ... done Creating harbor-jobservice ... done Creating nginx ... done ✔ ----Harbor has been installed and started successfully.----

看到最后那行成功提示，说明安装流程走完了。但别急着庆祝，先确认所有容器都处于healthy状态：

# 查看容器状态，注意 STATUS 列 docker compose -f /opt/harbor-install/harbor/docker-compose.yml ps # 如果有容器不是 healthy，看它的日志 docker logs harbor-core --tail 50

正常情况下，harbor-db、harbor-redis、harbor-core这几个容器需要十几秒到一分钟才能变成healthy。如果超过两分钟还是starting或者unhealthy，大概率是数据库初始化失败或者 Redis 连接不上，这时候看harbor-core的日志能快速定位问题。

3.4 安装后的验证步骤

安装成功只是第一步，真正要确认的是这套仓库能不能正常推拉镜像。下面这组验证步骤我每次部署完都会跑一遍：

# 1. 确认 Harbor API 可访问 curl -s http://192.168.1.100/api/v2.0/systeminfo | head -20 # 2. 在 Docker 配置里添加 insecure-registry（因为没有配 HTTPS） # 编辑 /etc/docker/daemon.json，加入： # { "insecure-registries": ["192.168.1.100"] } # 然后重启 Docker systemctl restart docker # 3. 登录 Harbor docker login 192.168.1.100 -u admin -p Harbor12345 # 4. 拉一个小镜像打标签并推送 docker pull alpine:3.19 docker tag alpine:3.19 192.168.1.100/library/alpine:3.19 docker push 192.168.1.100/library/alpine:3.19 # 5. 从 Harbor 拉回来验证 docker rmi 192.168.1.100/library/alpine:3.19 docker pull 192.168.1.100/library/alpine:3.19

这五步全部通过，才能说 Harbor 真正可用了。第 2 步的insecure-registries配置是离线环境下的常见做法——因为没有公网 CA 签发的证书，Docker 默认拒绝向 HTTP 仓库推送。生产环境建议还是配 HTTPS，可以用内部 CA 签发证书，然后把 CA 证书放到/etc/docker/certs.d/对应目录下。

4. 避坑指南：ARM64 离线部署 Harbor 的五个真实翻车记录

4.1 镜像导入失败：no space left on device

现象：install.sh执行到docker load阶段报错，提示no space left on device，但df -h看根分区还有空间。

原因：Docker 的默认数据目录是/var/lib/docker，如果这个目录挂载的分区比较小，导入几个 GB 的镜像就满了。ARM64 服务器上这种情况很常见，因为出厂分区方案往往给根分区分配得比较保守。

解决：把 Docker 数据目录迁移到大分区。编辑/etc/docker/daemon.json，加入"data-root": "/data/docker"，然后systemctl stop docker、迁移数据、systemctl start docker。或者更简单的方式，在安装前先确认/var/lib/docker所在分区的可用空间大于离线包解压后的大小。

4.2 容器启动后不断重启：数据库连接超时

现象：harbor-core容器状态一直是restarting，日志里反复出现failed to connect to database。

原因：harbor-db容器初始化数据库需要时间，而harbor-core启动时如果数据库还没就绪，就会连接失败并退出。Docker Compose 的depends_on只保证启动顺序，不保证服务就绪。

解决：这种情况通常等一两分钟会自愈，因为harbor-core会不断重试。如果超过五分钟还在重启，检查harbor-db的日志，看是不是数据目录权限问题导致 PostgreSQL 无法启动。ARM64 上 PostgreSQL 镜像对数据目录的权限要求比较严格，data_volume指向的目录必须是999:999属主。

4.3 推送镜像报错：received unexpected HTTP status: 500

现象：docker push时镜像层上传到一半报 500 错误，Harbor 日志里显示blob upload invalid。

原因：这种错误在 ARM64 环境下多半是存储驱动的问题。如果 Docker 用的是overlay2但底层文件系统是某些网络文件系统，镜像层写入会失败。

解决：确认/data/harbor所在的分区是本地文件系统，不要放在 NFS 或 CIFS 挂载点上。如果必须用网络存储，建议把 Harbor 的存储后端改成 S3 兼容对象存储，而不是依赖本地文件系统。

4.4 管理界面能打开但登录报 401

现象：浏览器能打开 Harbor 的 Web 界面，但输入admin和配置文件里的密码后提示认证失败。

原因：harbor.yml里的harbor_admin_password只在第一次初始化数据库时生效。如果你改了配置文件重新执行install.sh，但数据库已经存在，新密码不会覆盖旧密码。

解决：要么用旧密码登录后在界面里改，要么删掉数据库数据目录重新初始化。后者会丢失所有已推送的镜像，生产环境慎用。我一般会在第一次部署时就确认好密码，避免后续折腾。

4.5 ARM64 镜像在 x86 节点上无法运行

现象：从 Harbor 拉取镜像到 x86 服务器上运行，报exec format error。

原因：这不是 Harbor 的问题，而是镜像本身只有 ARM64 架构。Harbor 作为仓库只是原样存储和分发，不负责跨架构转换。

解决：如果集群是混合架构，需要用 manifest list 把多架构镜像推送到同一个 tag 下。构建时用docker buildx build --platform linux/amd64,linux/arm64生成多架构镜像，然后docker push到 Harbor。Harbor v2.13.1 对 OCI manifest list 的支持是完整的，只要镜像本身是多架构的，拉取时 Docker 会自动选择匹配当前平台的版本。

5. 进阶技巧：让 ARM64 Harbor 在生产环境跑得更稳

5.1 用外部数据库和 Redis 替代内置容器

内置的 PostgreSQL 和 Redis 容器适合测试和小规模使用，但生产环境建议换成外部实例。原因有两个：一是内置容器的数据持久化依赖本地卷，宿主机故障时恢复麻烦；二是外部数据库可以做主从和高可用，内置容器做不到。修改harbor.yml里的database和redis配置段，把host指向外部实例的地址，然后重新执行./install.sh即可。注意外部数据库需要提前建好registry库，并确保字符集是 UTF-8。

5.2 配置 HTTPS 与证书轮换

离线环境虽然不联外网，但内部 CA 是可以用的。用内部 CA 签发一张包含 Harbor 主机名的证书，把证书和私钥路径填到harbor.yml的https段，然后重新安装。证书快到期时，替换证书文件后执行docker compose restart nginx即可生效，不需要重装整个 Harbor。这里有个细节：证书的 SAN 字段必须包含你访问 Harbor 时用的主机名或 IP，否则 Docker 客户端会报证书不匹配。

5.3 镜像清理与垃圾回收

Harbor 的镜像存储会随着时间不断增长，尤其是 CI/CD 频繁推送的场景。v2.13.1 提供了标签保留策略和垃圾回收功能。在 Web 界面的「系统管理」→「垃圾清理」里可以手动触发 GC，但更推荐配置「标签保留规则」，自动清理超过一定数量或天数的旧标签。GC 执行期间 Harbor 会进入只读模式，建议放在业务低峰期。另外，GC 只删除没有被任何 manifest 引用的 blob，如果镜像标签还在，对应的层不会被清理，所以清理标签和 GC 要配合使用。

5.4 监控与告警的最小配置

Harbor 暴露了 Prometheus 格式的指标，默认在harbor-core的 9090 端口。如果你有 Prometheus 环境，加一个 scrape job 就能采集。关键指标包括harbor_project_repo_total（仓库数量）、harbor_project_artifact_total（制品数量）和harbor_component_health_status（组件健康状态）。没有 Prometheus 的话，至少配一个定时脚本检查/api/v2.0/health接口的返回码，非 200 就发告警。我一般用最土的办法——crontab 里每五分钟 curl 一次，失败就写日志并触发邮件。

5.5 离线包版本升级的注意事项

从 v2.13.1 升级到后续版本时，不要直接覆盖安装。正确流程是：先备份数据库和harbor.yml，然后下载新版本的离线包，解压后把旧的harbor.yml复制过去，执行./install.sh。Harbor 的安装脚本会自动执行数据库迁移。但 ARM64 版本升级有个额外风险：新版本的某些组件可能还没有 ARM64 镜像，导致升级卡在docker load阶段。所以升级前务必确认新版本离线包里images目录的 tar 包是完整的 ARM64 架构。

我在 ARM64 环境里部署 Harbor 最大的教训是：不要假设 x86 上的经验能直接平移。从 Docker 版本、内核参数到镜像架构，每一个环节都可能出问题。最稳妥的做法是在正式部署前，用一台配置相同的测试机完整跑一遍流程，把harbor.yml和验证脚本都固化下来。希望帮到你。

本文还有配套的精品资源，点击获取