一、背景与需求分析

随着国产芯片的普及，越来越多的企业选择基于ARM架构的服务器部署容器化应用。Harbor作为开源的企业级私有镜像仓库，其2.9.0版本对ARM64架构提供了原生支持。然而，在离线环境下完成Harbor的安装与升级存在诸多挑战：官方未提供ARM64离线包、依赖管理复杂、版本升级风险高等。本文将系统性解决这些问题，提供可复用的操作方案。

1.1 离线安装的核心价值

离线部署Harbor的核心优势体现在三个方面：

• 安全可控：避免互联网暴露风险，符合等保2.0要求
• 环境一致性：通过定制化离线包确保部署环境标准化
• 效率提升：减少重复下载依赖的时间消耗

1.2 ARM64架构适配要点

与x86架构相比，ARM64环境需要特别注意：

• 基础镜像选择：必须使用arm64v8标签的基础镜像
• 二进制文件兼容性：确保Harbor及其组件（如Clair、Notary）编译为ARM64架构
• 依赖库版本：部分C库（如openssl）需要特定版本支持

二、离线安装包制作流程

2.1 环境准备

2.1.1 基础环境要求

项目	要求说明
操作系统	CentOS 7.9/Ubuntu 20.04（ARM64版）
Docker版本	≥19.03（支持Buildx多架构构建）
磁盘空间	≥50GB（含依赖缓存）
网络要求	可访问Docker Hub等源（制作阶段）

2.1.2 工具链安装

# 安装Docker Buildx（多架构构建支持）
mkdir -p ~/.docker/cli-plugins
curl -L https://github.com/docker/buildx/releases/download/v0.9.0/buildx-v0.9.0.linux-arm64 -o ~/.docker/cli-plugins/docker-buildx
chmod +x ~/.docker/cli-plugins/docker-buildx
# 配置Buildx多平台构建
docker buildx create --name multiarch --use
docker buildx inspect --bootstrap

2.2 依赖收集与打包

2.2.1 基础依赖清单

Harbor 2.9.0的核心依赖包括：

• 数据库：PostgreSQL 12+（ARM64版）
• 存储后端：Redis 6+（ARM64版）
• 证书工具：cfssl 1.4.1+
• 核心组件：Harbor二进制、Clair扫描器、Notary签名服务

2.2.2 自动化收集脚本

#!/bin/bash
# 创建依赖目录结构
mkdir -p harbor-offline/{binaries,images,configs}
# 收集ARM64基础镜像
IMAGES=(
  "postgres:12-alpine"
  "redis:6-alpine"
  "goharbor/harbor-core:v2.9.0"
  "goharbor/harbor-jobservice:v2.9.0"
  "goharbor/harbor-registryctl:v2.9.0"
  "goharbor/clair-adapter:v2.9.0"
  "goharbor/notary-server:v2.9.0"
  "goharbor/notary-signer:v2.9.0"
)
for img in "${IMAGES[@]}"; do
  docker pull $img
  docker save -o harbor-offline/images/$(basename $img).tar $img
done
# 收集二进制文件
wget https://github.com/cloudflare/cfssl/releases/download/v1.4.1/cfssl_1.4.1_linux_arm64 -O harbor-offline/binaries/cfssl
chmod +x harbor-offline/binaries/cfssl

2.3 安装包验证

验证离线包完整性的关键步骤：

1. 镜像校验：使用docker load -i逐个验证镜像
2. 哈希比对：对二进制文件生成SHA256校验和
3. 依赖树检查：通过ldd确认无缺失动态库

# 示例：验证cfssl二进制
file harbor-offline/binaries/cfssl
# 应输出：ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV)...
ldd harbor-offline/binaries/cfssl
# 应无"not found"项

三、离线环境部署实施

3.1 基础服务部署

3.1.1 数据库初始化

-- PostgreSQL初始化脚本（harbor_db）
CREATE DATABASE registry;
CREATE DATABASE clair;
CREATE DATABASE notaryserver;
CREATE DATABASE notarysigner;
CREATE USER harbor WITH PASSWORD 'Harbor12345';
GRANT ALL PRIVILEGES ON DATABASE registry TO harbor;
GRANT ALL PRIVILEGES ON DATABASE clair TO harbor;

3.1.2 Redis配置优化

修改redis.conf关键参数：

maxmemory 4gb
maxmemory-policy allkeys-lru
timeout 300

3.2 Harbor核心组件安装

3.2.1 配置文件定制

编辑harbor.yml重点配置项：

hostname: registry.example.com
http:
  port: 80
https:
  certificate: /data/cert/server.crt
  private_key: /data/cert/server.key
storage_driver:
  name: filesystem
  settings:
    rootdirectory: /var/data/registry
database:
  password: Harbor12345
clair:
  updaters_interval: 12

3.2.2 离线安装命令

# 解压离线包
tar -xzf harbor-offline-installer-v2.9.0.tgz
cd harbor
# 加载所有镜像
for img in ../harbor-offline/images/*.tar; do
  docker load -i $img
done
# 安装Harbor
./install.sh --offline --with-clair --with-notary

3.3 部署后验证

关键验证点：

1. 服务状态检查：docker-compose ps应显示所有容器为”Up”
2. API连通性测试：

   curl -k https://registry.example.com/api/v2.0/health
   # 应返回：{"status":"healthy"}

3. 镜像推送测试：

   docker push registry.example.com/library/nginx:latest
   # 应成功返回Digest值

四、版本升级策略

4.1 升级前准备

4.1.1 数据备份方案

# 数据库备份
pg_dump -U harbor -h localhost registry > registry_backup.sql
pg_dump -U harbor -h localhost clair > clair_backup.sql
# 存储目录备份
tar -czf registry_data.tar.gz /var/data/registry

4.1.2 兼容性检查

升级前必须验证：

• 存储驱动兼容性（filesystem/s3等）
• 数据库schema变更
• 配置文件参数变化

4.2 升级实施步骤

4.2.1 增量升级包制作

# 对比新旧版本差异
DIFF_IMAGES=(
  "goharbor/harbor-core:v2.9.0"
  "goharbor/harbor-jobservice:v2.9.0"
)
# 制作增量包
mkdir -p upgrade-package/images
for img in "${DIFF_IMAGES[@]}"; do
  docker pull $img
  docker save -o upgrade-package/images/$(basename $img).tar $img
done

4.2.2 升级执行流程

# 1. 停止服务
cd harbor
docker-compose down
# 2. 加载新镜像
for img in ../upgrade-package/images/*.tar; do
  docker load -i $img
done
# 3. 执行数据库迁移（如有）
# 通常Harbor自带迁移脚本，需检查release notes
# 4. 重启服务
docker-compose up -d

4.3 升级后验证

关键验证项：

1. 版本号确认：

   docker exec harbor-core cat /harbor/VERSION
   # 应输出：2.9.0

2. 功能测试：
   • 镜像推送/拉取
   • 漏洞扫描（Clair）
   • 镜像签名（Notary）
3. 性能监控：

   docker stats --no-stream
   # 观察CPU/内存使用率是否在合理范围

五、常见问题解决方案

5.1 镜像架构不匹配错误

现象：standard_init_linux.go exec user process caused: exec format error

解决方案：

1. 确认所有容器镜像均为arm64v8标签
2. 使用docker inspect <镜像ID> | grep Architecture验证
3. 重新构建错误镜像：

   docker buildx build --platform linux/arm64 -t goharbor/harbor-core:v2.9.0 .

5.2 数据库连接失败

现象：pq: password authentication failed for user "harbor"

排查步骤：

1. 检查pg_hba.conf配置：

   host    all             harbor         127.0.0.1/32            md5
   host    all             harbor         ::1/128                 md5

2. 验证密码是否包含特殊字符（建议使用简单密码测试）
3. 检查PostgreSQL日志：

   journalctl -u postgresql -f

5.3 存储权限问题

现象：permission denied while creating volume directory

解决方案：

1. 检查存储目录权限：

   chown -R 10000:10000 /var/data/registry

2. 确认SELinux状态：

   getenforce
   # 如为Enforcing，临时设置为Permissive：
   setenforce 0

六、最佳实践建议

1. 版本管理：

   • 建立版本基线，记录所有组件版本号
   • 使用标签管理离线包（如harbor-offline-v2.9.0-arm64-20230801）

2. 自动化部署：

   • 使用Ansible/Terraform实现部署自动化
   • 示例Ansible任务片段：

     - name: Load Harbor images
       command: "docker load -i {{ item }}"
       with_fileglob: "/offline/images/*.tar"

3. 监控告警：

   • 配置Prometheus监控Harbor指标
   • 关键告警规则：
     • 存储空间使用率>85%
     • 镜像扫描任务积压>10
     • API响应时间>500ms

通过本文提供的系统化方案，企业可以在ARM64架构下高效完成Harbor 2.9.0的离线部署与升级，实现私有镜像仓库的安全可控运行。实际实施时，建议先在测试环境验证全部流程，再推广到生产环境。