麒麟V10 ARM64信创环境 Harbor 2.10.3 阶梯升级 2.15.2 全程踩坑实录（离线升级+Valkey兼容报错终极解决）

一、前言 & 升级背景

1.1 环境现状

操作系统：银河麒麟 V10（ARM64 架构）
服务器架构：aarch64（鲲鹏/飞腾信创服务器）
部署模式：纯离线部署（无外网、无法在线拉取镜像）
初始 Harbor 版本：v2.10.3
内核页大小：64K（信创ARM服务器默认配置）

1.2 升级动因

项目安全测评扫描发现，当前线上 Harbor v2.10.3 存在多个高危漏洞，包含镜像仓库权限绕过、组件漏洞、远程代码执行等风险，不满足等保合规要求，需要升级至最新稳定版 v2.15.2 完成漏洞修复。

1.3 核心升级限制（重点）

查阅 Harbor 官方升级文档，明确两大硬性限制，也是本次升级复杂度的核心原因：

版本迭代限制：Harbor 不支持跨多版本跳跃升级，仅支持最多跨 2 个小版本升级。
v2.10.3 无法直接升级 v2.15.2，必须阶梯式迭代：
2.10.3 → 2.12.2 → 2.14.2 → 2.15.2
架构资源限制：Harbor 官方仅提供 x86_64 离线安装包，无官方 ARM64 离线介质。信创ARM环境只能使用社区第三方编译适配的ARM镜像包，存在底层编译兼容隐患。

二、升级前置准备（离线环境必备）

2.1 介质准备

离线环境提前下载、上传三套第三方 ARM64 适配离线安装包：

harbor-offline-installer-v2.12.2-arm64.tgz
harbor-offline-installer-v2.14.2-arm64.tgz
harbor-offline-installer-v2.15.2-arm64.tgz

2.2 预处理操作

依次解压所有安装包，导入对应版本Docker镜像，保证后续升级镜像环境完整：

# 解压安装包
tar -zxvf harbor-offline-installer-v2.12.2-arm64.tgz
tar -zxvf harbor-offline-installer-v2.14.2-arm64.tgz
tar -zxvf harbor-offline-installer-v2.15.2-arm64.tgz

# 离线导入镜像（每个版本目录执行）
docker load -i harbor-images.tar

2.3 全量数据备份（重中之重）

升级前停止服务，备份核心数据（镜像存储、数据库、配置文件），防止升级失败数据丢失：

# 进入旧版本安装目录停止服务
cd /data/harbor_install/harbor2.10.3
docker-compose down

# 进入旧版本数据目录，备份数据
cp -r /data/harbor /data/harbor_bak

三、阶梯式升级流程（2.10.3→2.12.2→2.14.2 正常流程）

v2.12.2、v2.14.2 两个过渡版本升级逻辑完全一致，无架构变更、无组件替换，升级过程丝滑稳定。

3.1 配置文件迁移

将旧版本可正常运行的 harbor.yml 拷贝至新版本目录，保留原有域名、端口、密码、HTTPS、存储路径、权限配置，无需重新配置。

# 以2.12.2为例，2.14.2操作一致
cp /data/harbor_install/harbor2.10.3/harbor.yml /data/harbor_install/harbor2.12.2/

3.2 执行数据库迁移与配置适配

使用对应版本的 prepare 镜像，执行官方迁移命令，自动适配新版本参数、升级数据库schema、回写优化配置文件：

# 2.12.2 迁移命令
docker run -it --rm -v /:/hostfs goharbor/prepare:2.12.2 migrate -i /data/harbor_install/harbor2.12.2/harbor.yml

# 2.14.2 迁移命令
docker run -it --rm -v /:/hostfs goharbor/prepare:2.14.2 migrate -i /data/harbor_install/harbor2.14.2/harbor.yml

执行完成后，工具会自动修正 harbor.yml 中适配新版本的参数，保证配置兼容性。

3.3 生成编排文件并启动服务

# 生成docker-compose.yml配置
./prepare

# 安装并启动Harbor
./install.sh

3.4 升级结果

v2.12.2、v2.14.2 全部升级成功，Redis、PostgreSQL、核心服务、日志服务正常启动，原有镜像、项目、用户、权限、仓库数据全部平滑迁移，无数据丢失、无服务异常。

四、v2.15.2 升级致命报错（核心踩坑点）

4.1 版本重大架构变更

Harbor 在 v2.15.2 版本进行了核心组件迭代：正式废弃 Redis，全面替换为 Valkey 缓存组件。这也是本次升级报错的根本诱因。

第三方社区仅简单交叉编译打包了 ARM64 镜像，未针对信创ARM 64K页内核做适配编译，导致底层兼容故障。

4.2 报错现象

执行 install.sh 启动服务后，所有服务正常拉起，唯独 Valkey 容器反复重启、启动失败。

查看容器日志，核心报错信息：

<jemalloc>: Unsupported system page size

报错释义：当前系统内核页大小与程序编译页大小不匹配，jemalloc内存分配器初始化失败，进程直接退出。

4.3 报错根因深度分析

第三方打包的 goharbor/valkey-photon:v2.15.2 镜像，基于 x86_64 平台 4K 内存页 编译；
国产化麒麟ARM服务器内核为 64K 系统页大小；
jemalloc 内存分配器编译时硬编码页大小，运行时校验不通过，容器直接崩溃；
常规通用解决方案 MALLOC=libc 环境变量绕过方案完全失效，属于镜像底层编译级别兼容问题，无法通过配置修复。

4.4 无效方案验证（避坑）

网络通用解决方式为在 compose 中添加环境变量规避 jemalloc 校验，但本次实测无效：

environment:
  - MALLOC=libc

原因：第三方镜像底层编译残留问题，部分版本启动阶段优先加载 jemalloc 库，环境变量无法拦截初始化报错。

五、生产级终极解决方案（无需降级、完美适配）

放弃 Harbor 自带的第三方不兼容 valkey-photon 镜像，替换为官方原生适配 ARM64 架构的 Valkey 镜像，适配64K页内核，彻底解决兼容问题。

5.1 离线导入官方ARM64 Valkey镜像

提前下载 valkey/valkey:8.1-arm64 离线镜像包，上传服务器后导入：

docker load -i valkey-8.1-arm64.tar

5.2 修改 docker-compose.yml 配置

保留原有Valkey的容器名、权限、挂载、日志配置，仅替换镜像为官方ARM原生版本，完整可用配置如下：

valkey:
    image: valkey/valkey:8.1-arm64
    container_name: redis
    restart: always
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETGID
      - SETUID
    volumes:
      - /data/harbor/redis:/var/lib/redis
    networks:
      harbor:
    depends_on:
      - log
    logging:
      driver: "syslog"
      options:
        syslog-address: "tcp://localhost:1514"
        tag: "redis"

5.3 重启服务生效

# 停止原有服务
docker-compose down

# 重新拉起所有服务
docker-compose up -d

# 查看Valkey运行状态
docker ps | grep redis

# 查看日志确认无报错
docker logs redis

5.4 升级结果验证

Valkey 容器正常启动，无 jemalloc 页大小报错；
Harbor 所有服务健康就绪，后台可正常访问；
原有镜像、项目、用户、权限数据完全保留；
漏洞扫描复测，高危漏洞全部修复，满足等保要求。

六、本次升级核心踩坑总结

版本升级必须阶梯迭代：Harbor 严格限制跨版本升级，2.10.x 无法直接升级 2.15.x，必须逐版本过渡，跳跃升级必现数据库异常；
ARM离线包存在天然缺陷：无官方ARM介质，第三方编译镜像仅能满足基础运行，高版本核心组件存在底层编译兼容隐患；
2.15.2是架构分水岭：Redis 全面替换为 Valkey，旧版本排错方案、适配经验全部失效，属于结构性变更；
jemalloc报错分场景：普通兼容问题可通过 MALLOC=libc 修复，底层编译不兼容场景只能替换原生架构镜像，软配置无效；
无需盲目降级回滚：遇到高版本兼容问题，优先替换组件镜像，而非降级版本，可保留最新安全版本，兼顾稳定性和安全性。

七、生产环境最终建议

1. 信创ARM64离线环境部署/升级 Harbor，不要完全依赖第三方编译镜像，核心缓存、数据库组件出现兼容问题时，优先替换官方原生ARM架构组件镜像；

2. 跨版本升级务必全程备份，遵循阶梯升级规则，杜绝跳跃升级；

3. 2.15.2 及以上新版本优先采用 Valkey 官方镜像替代 Harbor 内置镜像，完美适配64K页ARM内核，规避jemalloc兼容报错；

4. 安全合规场景下，尽量保持 Harbor 版本最新，通过组件适配解决兼容问题，而非降级牺牲安全性。