企业官网建设流程全解析

• 云原生
• 存储
• 高可用
• 容器编排

本文围绕 Longhorn 官方 v1.10.1 发布说明（CHANGELOG-1.10.1.md）展开，逐项解析该补丁版本聚焦的系统质量、韧性、稳定性与安全改进，并深入 V2 数据引擎中断模式（Interrupt Mode）在仓库中的设计与实现落点。读完本文，你将掌握 v1.10.1 的关键修复内容、升级前置条件（Kubernetes v1.25+）、变更清单，以及如何结合仓库源码与 Helm 配置理解并规避这些已知问题。

版本定位：1.10 系列的首个补丁版本

Longhorn v1.10.1 是 v1.10.0 大版本（该版本集中引入了 V2 数据引擎中断模式、卷克隆、副本重建 QoS、卷扩容、无大页运行等能力，见 CHANGELOG-1.10.0.md）之后的补丁版本。根据仓库根目录 README.md 中的版本表，1.10 系列当前维护版本即为 1.10.2，而本仓库 support-versions.txt 显示当前处于活跃支持期的版本线已推进到 1.11/1.12——阅读本文时可将 v1.10.1 视为 1.10 系列稳定化过程中的一个关键节点。

官方定位上，v1.10.1 的核心诉求是改善系统的质量、韧性、稳定性与安全性。具体而言，它包含 4 项重点修复、7 项改进、28 项缺陷修复与 2 项杂项变更。

重点修复详解

发布说明中的 "Important Fixes" 节明确指出本版本包含若干关键稳定性与性能改进，以下逐项展开。

V2 数据引擎实例管理器 Goroutine 泄漏（Issue #11962）

修复了使用 V2 数据引擎时实例管理器（Instance Manager）中的 goroutine 泄漏问题。该问题若长期存在，会导致内存占用持续增长，进而引发潜在的稳定性故障。

从架构上看，V2 数据引擎基于 SPDK 实现（对应设计文档 20221213-reimplement-longhorn-engine-with-SPDK.md），而实例管理器负责控制器/副本实例的生命周期管理（见 README.md 组件表）。goroutine 泄漏通常发生在 SPDK 进程与实例管理器之间的长连接、轮询或请求处理协程未正确退出的场景，长期累积会侵蚀节点内存，属于"慢病型"稳定性缺陷，正适合在补丁版本中集中收敛。

V2 卷在中断模式下挂载失败：补齐 NVMe 磁盘支持（Issue #11816 / #11976）

这是 v1.10.1 中最值得关注的能力变化：

• 在 v1.10.0 中，中断模式（Interrupt Mode）仅支持 AIO 磁盘；
• 自 v1.10.1 起，中断模式正式支持 NVMe 磁盘。

修复前，使用中断模式且搭配 NVMe 磁盘的 V2 卷可能无法完成挂载流程，导致卷无限期停留在attaching状态。

仓库中与中断模式相关的完整设计与配置证据如下：

• 设计文档：20250721-v2-engine-interrupt-mode.md 详细描述了混合实现方案——NVMe-oFtarget使用epoll等待 socket 就绪事件，NVMe-oFinitiator则以固定周期轮询bdev_nvme_poll冲刷 I/O 完成事件；未来迭代计划探索epoll+eventfd的完全事件驱动模型。
• 全局设置项（Phase 1）：data-engine-interrupt-mode-enabled，布尔类型，默认false（默认仍为轮询模式）；
• 全局设置项（Phase 2）：data-engine-nvme-ioq-poll-period-us，整数，范围>= 1，默认100微秒；
• CRD 状态字段：InstanceManager.status.dataEngineStatus.v2.interruptModeEnabled用于指示 V2 数据引擎当前运行于中断模式（true）还是轮询模式（false），由 Longhorn Manager 维护、对用户只读。

与本次修复同批收敛的 V2/NVMe 相关缺陷还包括：

UI 在仅启用 IPv4 的节点上部署失败（Issue #11875）

修复了 v1.10.0 引入的一个回归：在仅启用 IPv4 的节点上，Longhorn UI 无法完成部署。修复后 UI 无需 IPv6 即可正确支持纯 IPv4 配置。这一点对于禁用 IPv6 的 Kubernetes 集群（例如部分合规或受限网络环境）尤为重要，涉及清单位于 deployment-ui.yaml，相关配置（副本数、亲和性、PDB）可参考 values.yaml 中的longhornUI段。

Share Manager 内存异常占用（RWX 卷，Issue #12043）

修复了 RWX（ReadWriteMany）卷场景下 Share Manager 组件内存消耗过高的问题，修复后组件在正常运行状态下维持稳定内存使用。Share Manager 本质上是将 Longhorn 卷以 NFS 形式暴露为 ReadWriteMany 卷的组件（见 README.md 组件表），其内存异常通常与句柄泄漏、缓存未回收或文件系统事件堆积相关。同批还修复了RWX volume causes process uninterruptible sleep（Issue #11958，进程进入不可中断睡眠 D 状态）的问题，两者共同提升了 RWX 卷的长稳表现。

安装与升级前置条件

发布说明用两个高优先级提示（[!IMPORTANT]）框定了安装与升级的硬性门槛：

• 安装：集群必须运行Kubernetes v1.25 或更高版本，方可安装 Longhorn v1.10.1；
• 升级：从 Longhorn v1.9.x 升级到 v1.10.1 同样要求Kubernetes v1.25 及以上；
• 升级路径约束：Longhorn 仅允许从受支持的版本升级，升级路径与流程以官方 "Upgrade" 文档为准。

本仓库为部署与卸载提供了现成清单：使用 kubectl 安装时可基于 deploy/longhorn.yaml（及 deploy/longhorn-okd.yaml 等变体），使用 Helm 时可参考 Chart.yaml 与 values.yaml，卸载流程见 uninstall/uninstall.yaml。

升级路径上值得特别留意的背景是：v1.10.0 已经移除了longhorn.io/v1beta1API（详见 CHANGELOG-1.10.0.md）。v1.10.1 修复了由此衍生的一批升级问题：

本次引入的改进

v1.10.1 通过 backport 收编了 7 项改进，覆盖控制器行为、调度容量、可观测性与配置易用性：

其中 #12020 与本文主题强相关：v1.10 起 Longhorn 设置统一采用"单一值适用于所有数据引擎 / JSON 对象按数据引擎区分"的新格式（如{"v1":"value1","v2":"value2"}，见 CHANGELOG-1.10.0.md），Helm 模板的自动引号与多类型渲染正是为了适配data-engine-interrupt-mode-enabled、data-engine-hugepage-enabled这类{"v2": ...}形态的取值，避免布尔值/数值在 YAML 渲染过程中被错误转义。

其余缺陷修复分类梳理

除重点修复外，v1.10.1 还通过 backport 修复了一批分散在 V2 引擎、备份、CSI、卷状态机与磁盘管理等模块的缺陷：

V2 数据引擎与 SPDK 相关

• #11901：longhorn-engine 的 UI 组件 panic；
• #12088 / #11942：空指针解引用（invalid memory address or nil pointer dereference，其中 #12088 定位于 longhorn-engine 控制器 control.go:218 附近）；
• #11998：附加节点上的引擎镜像被删除后，DR 卷卡在unknown状态；
• #11996：引擎镜像未部署到全部节点时，卷卡在attaching状态。

备份、恢复与周期任务

• #12089：备份目标（Backup Target）指标损坏；
• #11926：周期任务执行期间的 NPE 错误；
• #12005：test_system_backup_and_restore测试用例失败；
• #11964：残留 BackupTarget 阻塞卸载（已在升级部分列出）。

CSI 与挂载

• #12008：CSI node publish volume 阶段的挂载错误未被妥善处理；
• #11918：dataEngine参数缺失时，csi-provisioner 静默创建 CSIStorageCapacity 失败。

磁盘、节点与网络

• #12018：同一节点并发添加多个磁盘时偶发失败；
• #11954：块磁盘删除失败且无错误消息；
• #12094：网络断开后 backing image 下载卡住；
• #11970：SPDK v25.05 的 CVE 修复（已在重点修复部分列出）。

杂项（Misc）

• #11992：为 UI 组件增加 SAST 静态安全扫描检查（重构项）；
• #11951：为longhorn-manager:v1.10.0创建 hotfix 镜像（热修复项）。

源码佐证：中断模式在仓库中的完整落点

由于"NVMe 磁盘中断模式支持"是 v1.10.1 最有技术含量的一项变更，以下沿仓库文件链完整梳理其实现落点，便于读者按图索骥：

1. 设计文档20250721-v2-engine-interrupt-mode.md：

   • 混合模式设计：target 端epoll等待 socket 就绪 + initiator 端周期轮询bdev_nvme_poll；
   • 阶段划分：Phase 1 固定nvme_ioq_poll_period_us = 100（微秒）并提供开关；Phase 2 将该参数外部化；
   • 依赖：要求 SPDK v25.x，Longhorn 的 SPDK fork 需 rebase 到 v25.x，并移除event_iscsi以避免不必要的 iSCSI 子系统初始化；
   • 文中给出的基准数据（AWS SLES 15 SP7、k3s v1.32、t2.2xlarge）表明：中断模式在空闲/低 I/O 场景下显著降低 CPU 消耗，100ms轮询周期在读延迟与 IOPS 之间取得较好平衡。

2. Helm 默认设置values.yaml：defaultSettings.dataEngineInterruptModeEnabled注释明确"仅适用于 V2 数据引擎，控制 SPDK target 守护进程运行于中断模式还是默认轮询模式"，默认值{"v2":"false"}。

3. 模板渲染default-setting.yaml：将dataEngineInterruptModeEnabled通过include "longhorn.multiTypeSetting"渲染为data-engine-interrupt-mode-enabled配置项（该文件同时渲染data-engine-cpu-isolation-enabled、data-engine-memory-size等 V2 专属设置）。

4. CRD 定义crds.yaml：InstanceManager.status.dataEngineStatus.v2.interruptModeEnabled字段，枚举值""/"true"/"false"，描述明确标注"由 Longhorn Manager 设置，用户只读"。

5. Rancher 问答questions.yaml：为defaultSettings.dataEngineInterruptModeEnabled提供了 UI 层的描述与默认值{"v2":"false"}，归入 "Longhorn V2 Data Engine Settings" 分组。

升级与使用建议

基于 v1.10.1 的变更内容，给出如下实操建议：

• 升级前自查：确认集群版本不低于 Kubernetes v1.25；若从 1.9.x 升级，先核对是否存在遗留的 v1beta1 资源（v1.10 系列已移除该 API 版本），避免触发 #11886、#11865 一类升级失败；
• 中断模式按需开启：中断模式是 opt-in 特性，默认关闭，无需迁移。若集群存在大量空闲或低 I/O 的 V2 卷且对 CPU 利用率敏感，可通过data-engine-interrupt-mode-enabled开启；自 v1.10.1 起 NVMe 磁盘同样受支持；
• RWX 与 UI 场景：1.10.1 已修复 Share Manager 内存异常与纯 IPv4 节点 UI 部署问题，升级后可重点观察这两个组件的稳定性；
• 安全项：SPDK v25.05 CVE（#11970）已在本版本修复，建议及时升级以消除该安全隐患；
• 发布后已知问题：官方在版本发布后仍会持续跟踪并维护已知问题清单（Release-Known-Issues 页面），升级前可先查阅该页面确认是否存在影响自身部署环境的新发现。

致谢与贡献者

本版本由 15 位贡献者共同完成：@COLDTURNIP、@PhanLe1010、@bachmanity1、@c3y1huang、@chriscchien、@davidcheng0922、@derekbit、@forbesguthrie、@innobea、@mantissahz、@rebeccazzzz、@roger-ryao、@sushant-suse、@shuo-wu、@yangchiu。Longhorn 欢迎社区反馈与贡献以持续改进（贡献指引见 CONTRIBUTING.md）。

• 云原生
• 存储
• 高可用
• 容器编排