Harvester 集群在离线环境下的镜像上传与下载问题分析

问题背景

在离线环境（air-gapped）部署的Harvester集群中，用户尝试通过文件上传或内部URL下载方式创建虚拟机镜像时遇到了操作失败的情况。这个问题在标准网络环境下不会出现，但在离线部署场景下会稳定复现。

错误现象

当用户尝试创建镜像时，系统会返回以下错误信息：

Retry attempted 3/3 failed due to error: BackingImage.longhorn.io "vmi-2618f2cc-546a-4147-85ed-a33282cd9bc8" is invalid: spec.dataEngine: Unsupported value: "": supported values: "v1", "v2"

根本原因分析

经过深入排查，发现问题源于Longhorn组件的镜像版本不匹配：

1. 镜像拉取失败：Longhorn的三个关键组件（manager、share-manager和UI）在离线环境中无法正确获取，因为这些组件尝试拉取的是特定版本标签（v1.8.0）而非Harvester ISO中打包的版本（v1.8.x-head）。

2. Mutator功能失效：由于Longhorn manager未能正常运行，导致BackingImage资源的dataEngine字段无法被自动设置为默认值"v1"。这个字段是Longhorn v2数据引擎引入的新特性，必须明确指定为"v1"或"v2"。

3. 离线环境特殊性：在标准网络环境中，系统可以自动拉取所需镜像；但在离线环境中，必须确保所有依赖镜像都已正确打包并部署到本地镜像仓库。

解决方案

要解决此问题，需要采取以下措施：

1. 手动部署正确的Longhorn镜像：将Longhorn v1.8.0的所有相关组件镜像手动部署到离线环境中，包括：

   • longhornio/longhorn-manager
   • longhornio/longhorn-share-manager
   • longhornio/longhorn-ui

2. 等待官方修复：Harvester团队正在准备Longhorn v1.8.1的集成，该版本将包含正确的镜像列表，从根本上解决此问题。

技术细节

当Longhorn manager正常运行时，它会通过Mutator webhook自动为BackingImage资源设置dataEngine字段的默认值"v1"。但在当前问题场景下，由于manager组件未能启动，这个自动化过程失效，导致API验证失败。

结论

这个问题凸显了在离线环境中部署云原生系统时版本管理和组件依赖的重要性。Harvester团队已经识别到问题根源，并将在后续版本中提供官方修复方案。对于急需在离线环境中使用此功能的用户，目前可以通过手动部署正确版本的Longhorn组件作为临时解决方案。