发布日期: 2026-08-14
版本号: v1.12.1

Longhorn v1.12.1 版本引入了 V2 数据引擎的快速卷克隆和存储分片（实验性）功能，并包含多项重要改进与错误修复，提升了系统的质量、韧性、稳定性和安全性。主要变更包括：自 v1.12.1 起，旧版链接克隆卷被标记为已弃用，升级后仅支持分离和删除操作，建议使用新架构创建替代卷。新功能方面，快速卷克隆支持链接克隆卷执行快照、扩容等更多操作；存储分片作为实验性功能，通过纠删码技术将数据分布于多个节点以节省空间。改进措施涵盖默认启用内部网络策略、扩展实例管理器 gRPC 服务的 mTLS 覆盖、支持 Kubernetes CPU 管理器分配专属 CPU 核心、优化主机 CPU 隔离、允许配置 SPDK iobuf 池大小，以及修正加密卷的容量计算。此外，本版本解决了大量问题，涉及稳定性、性能及功能修复，并要求 Kubernetes 版本不低于 v1.25。

更新内容（中文）

Longhorn v1.12.1 发布说明

Longhorn v1.12.1 引入了 V2 数据引擎的快速卷克隆和存储分片（实验性）功能，并包含重要的改进和缺陷修复，提升了系统质量、韧性、稳定性和安全性。

我们欢迎反馈和贡献，以帮助持续改进 Longhorn。

关于 Longhorn 版本的术语和背景，请参阅发布版本。

重大变更

废弃传统 V2 链接克隆卷

在 v1.12.0 或更早版本中创建的 V2 链接克隆卷，从 v1.12.1 开始被标记为传统版本并已废弃。在问题 #12552 中引入的新链接克隆架构与传统设计不兼容。

升级到 v1.12.1 后，传统链接克隆卷除了分离和删除操作外，不能进行其他任何操作。

要替换这些卷，请从支持传统卷的相同源卷创建新的链接克隆卷。只要传统卷存在，其源卷保证仍然存在，因此您可以直接创建替代的链接克隆卷；无需进行数据复制。

更多信息，请参阅问题 #12552。

重点功能

快速卷克隆

Longhorn v1.12.1 增强了 V2 数据引擎的快速卷克隆功能。linked-clone 卷通过共享数据块而非复制数据来与源卷共享数据。通过新架构，一个源副本可以与多个链接克隆卷共享其数据块，并且可以并行创建多个克隆副本。

链接克隆卷现在支持大多数常规卷可用的操作，包括快照、扩展、副本重建以及用作嵌套链接克隆的源卷。

更多信息，请参阅问题 #12552 和 CSI 卷克隆。

[!NOTE] V2 快速克隆目前不支持卷备份和恢复。此改进的跟踪链接为问题 #13714。

存储分片（实验性）

Longhorn v1.12.1 引入了存储分片作为一项基于 V2 数据引擎的实验性数据保护和存储布局功能。分片不存储卷的完整副本，而是使用纠删码将写入的数据编码为数据块和校验块，并将其分布在多个节点上。这使得卷可以增长到超出单个磁盘或节点的容量，同时使用更少的磁盘空间实现相同级别的容错能力。

由于此功能是实验性的，仅用于评估和测试，不建议用于生产环境。

更多信息，请参阅问题 #1061 和使用纠删码的分片。

重要改进与修复

此版本包含若干重要改进和关键稳定性修复。

内部网络策略

Longhorn v1.12.1 默认为内部组件端点和 RPC 启用入口 NetworkPolicy 资源，通过限制对 Longhorn 内部服务（包括用于引擎控制的 instance-manager gRPC 端点）的访问来提高安全性。这些策略仅在集群中有可用的 NetworkPolicy 提供者时生效。

Longhorn 已使用以下 Kubernetes 发行版和 CNI 插件组合验证了内部网络策略。有关已验证的组合，请参阅 CNI 插件兼容性表。所需的最低 Kubernetes 版本是 v1.25。

更多信息和故障排除指南，请参阅内部网络策略和问题 #13438。

[!NOTE] ServiceMonitor 发现不会自动授权网络流量。跨命名空间的 Prometheus 抓取器可能会被 Longhorn Manager 的网络策略阻止。要允许此流量，请按照 Prometheus 和 Grafana 设置指南应用一个有限范围的附加策略。

Instance Manager gRPC mTLS 覆盖

在之前的版本中，为 instance-manager gRPC 端点配置的相互 TLS (mTLS) 仅在配置了 longhorn-grpc-tls secret 时覆盖实例和代理服务。其他服务，包括磁盘服务和 SPDK 服务，接受明文连接。

Longhorn v1.12.1 将 mTLS 扩展到所有剩余的 instance-manager gRPC 服务，因此当配置了 longhorn-grpc-tls secret 时，每个 gRPC 端口现在都需要有效的客户端证书。

更多信息，请参阅问题 #7787。

使用 Kubernetes CPU 管理器进行 CPU 核心分配

Longhorn v1.12.1 可以通过 Kubernetes CPU 管理器，使用 data-engine-number-of-cpu-cores 设置为在每个 V2 Instance Manager Pod 中运行的 SPDK 目标守护进程分配独占的 CPU 核心。

仅当所有工作节点的 kubelet CPU 管理器策略设置为 static 时，才能应用此设置；否则，更新将被拒绝。当该值为正数时，其优先级更高，data-engine-cpu-mask 将被忽略。

更多信息，请参阅问题 #13248。

宿主 CPU 隔离

data-engine-cpu-isolation-enabled 设置现在除了硬件 IRQ 和未绑定的工作队列工作者外，还配置了宿主网络的接收包转向 (RPS)，将 RX 软中断处理从 SPDK 目标守护进程使用的 CPU 核心上移开。如果不这样做，内核可能会将传入的网络数据包分发到 SPDK 反应器核心，导致软中断工作与反应器的忙轮询循环竞争，从而在高网络负载下降低卷 I/O 性能。

更多信息，请参阅问题 #13483 和问题 #13502。

V2 数据引擎 SPDK iobuf 池大小配置

Longhorn v1.12.1 允许调整 V2 数据引擎使用的 SPDK iobuf 缓冲区池。data-engine-iobuf-large-pool-size 和 data-engine-iobuf-small-pool-size 设置分别配置大型和 8 KiB 小型缓冲池。增大小型池可以缓解在高队列深度、小 I/O 大小的工作负载下的缓冲区耗尽问题。由于 iobuf 池只能在 SPDK 目标启动时设置大小，更改任一设置都会重建没有运行实例的 V2 Instance Manager Pod。

更多信息，请参阅问题 #13322 和问题 #13674。

加密卷容量修正

Longhorn 为加密卷使用的 LUKS2 元数据预留了额外的 16 MiB 原始容量，允许映射设备暴露工作负载请求的完整容量。之前，元数据从可用容量中扣除，因此请求的 1 GiB 加密卷仅暴露 1008 MiB。此差异可能导致在大小相同的非加密和加密卷之间进行块级复制等操作失败。

V1 数据引擎：此修正已在 Longhorn v1.12.0 中引入。使用 v1.11.x 或更早版本创建的现有加密 V1 卷，在其引擎镜像升级到 v1.12 或更高版本时会自动获得额外容量。加密的可迁移 V1 卷在升级到该版本 (>= v1.12.0) 之前无法进行实时迁移。
V2 数据引擎：Longhorn v1.12.1 将此修正应用于新创建的加密 V2 卷。

[!NOTE] 在 v1.12.1 之前创建的加密 V2 卷，以及从这些卷的备份恢复的卷，不会获得额外的 16 MiB 原始容量，并且继续比请求的容量少 16 MiB。现有数据会被保留。

更多信息，请参阅问题 #9205 和问题 #13163。

安装

[!IMPORTANT] 在安装 Longhorn v1.12.1 之前，请确保您的集群运行的是 Kubernetes v1.25 或更高版本。

您可以使用多种工具安装 Longhorn，包括 Rancher、Kubectl 和 Helm。有关安装方法和要求的更多信息，请参阅 Longhorn 文档中的快速安装。

升级

[!IMPORTANT] 在安装 Longhorn v1.12.1 之前，请确保您的集群运行的是 Kubernetes v1.25 或更高版本。

Longhorn 仅允许从受支持的版本升级。有关升级路径和过程的更多信息，请参阅 Longhorn 文档中的升级。

发布后已知问题

有关此版本发布后发现的问题信息，请参阅发布已知问题。

此版本已解决的问题

重点

[BACKPORT][v1.12.1][UI][FEATURE] V2 数据引擎快速克隆 13672 - @shuo-wu @roger-ryao
[BACKPORT][v1.12.1][FEATURE] V2 数据引擎分片 - 实验性 13176 - @c3y1huang @chriscchien
[BACKPORT][v1.12.1][FEATURE] V2 数据引擎快速克隆 13174 - @shuo-wu @roger-ryao

功能

[BACKPORT][v1.12.1][FEATURE] 支持 Kubernetes CPU 管理器用于 Longhorn V2 instance-manager SPDK CPU 分配 13320 - @yangchiu @mantissahz @Copilot

改进

[BACKPORT][v1.12.1][IMPROVEMENT] 允许配置 SPDK iobuf 小型池大小 13675 - @yangchiu @hookak
[BACKPORT][v1.12.1][IMPROVEMENT] go-common-libs: 当命令执行超时时终止子进程 13621 - @hookak
[BACKPORT][v1.12.1][IMPROVEMENT] 始终为内部通信设置 NetworkPolicy 13439 - @COLDTURNIP @roger-ryao
[BACKPORT][v1.12.1][IMPROVEMENT] 将宿主 RPS 从 SPDK 反应器核心上移开 13502 - @bachmanity1 @roger-ryao
[BACKPORT][v1.12.1][IMPROVEMENT] updateBackupCompressionMethod 即使方法未更改也可能写入卷 13480 - @yangchiu
[BACKPORT][v1.12.1][IMPROVEMENT] 添加指标以收集 V2 数据引擎使用情况信息 13262 - @derekbit @chriscchien
[BACKPORT][v1.12.1][IMPROVEMENT] 提升卷附加失败时的错误透明度 13431 - @derekbit @chriscchien
[BACKPORT][v1.12.1][IMPROVEMENT] 允许配置 SPDK iobuf 大型池大小 13415 - @chriscchien @bachmanity1
[BACKPORT][v1.12.1][IMPROVEMENT] 迁移过程中删除副本时 V2 卷写入 I/O 停顿约 10 秒 13310 - @hookak @chriscchien
[BACKPORT][v1.12.1][IMPROVEMENT] 支持 instance manager 中剩余 gRPC 服务的 mTLS 加密通信 13299 - @COLDTURNIP @yangchiu
[BACKPORT][v1.12.1][IMPROVEMENT] 添加指标以收集 LONGHORN_DISTRO 信息 13253 - @derekbit @chriscchien

缺陷

[BACKPORT][v1.12.1][BUG] 宿主操作系统 nvmf-autoconnect 将内核发起者连接到 v2 副本子系统，导致卷附加/分离操作延迟数分钟 13660 - @hookak @chriscchien
[BACKPORT][v1.12.1][BUG] Longhorn Helm Chart NetworkPolicies 不尊重新的 RKE2 "rke2-traefik" 入口控制器 13665 - @COLDTURNIP @roger-ryao
[BACKPORT][v1.12.1][BUG] 克隆过程中，Longhorn 可能尝试将卷附加到没有有效 IM Pod 的节点 13640 - @yangchiu @shuo-wu
[BACKPORT][v1.12.1][BUG] 测试用例 test_volume_scheduling_failure 在 v2 卷上失败 13656 - @yangchiu @c3y1huang
[BACKPORT][v1.12.1][BUG] Backup Listing With More Than 1000 Backups 在 v2 卷上因备份状态中副本地址为空而失败 13612 - @COLDTURNIP @chriscchien
[BACKPORT][v1.12.1][BUG] GUI 中的网络链接不正确 13539 - @yangchiu @sushant-suse
[BACKPORT][v1.12.1][BUG] 加密 V2 卷大小比声称的大小少 16MB 13175 - @mantissahz @roger-ryao
[BACKPORT][v1.12.1][BUG] CSI Pod 不遵守反亲和性预设更新 13548 - @chriscchien @carterli0407-cell
[BACKPORT][v1.12.1][BUG] 使用 virtio-scsi BDF 路径添加 v2 块磁盘失败 13475 - @chriscchien @carterli0407-cell
[BACKPORT][v1.12.1][BUG] V2 加密卷在扩展操作后持续在附加和分离状态之间切换 13562 - @mantissahz @roger-ryao
[BACKPORT][v1.12.1][BUG] GCS 备份目标：大容量备份在最终 .cfg PUT 操作时因 SignatureDoesNotMatch 失败（v1.12.0 中 #12676 的残留） 13574 - @derekbit @chriscchien
[BACKPORT][v1.12.1][BUG] 如果先前的备份已损坏，则无法从完整备份恢复卷 13538 - @yangchiu @derekbit
[BACKPORT][v1.12.1][BUG] 测试用例 Recurring Job Pod Should Not Crash 失败 13568 - @yangchiu @c3y1huang
[BACKPORT][v1.12.1][BUG] Longhorn 1.12.0：AWS 分块编码不支持 OCI S3 存储桶 13478 - @derekbit @mantissahz @roger-ryao
[BACKPORT][v1.12.1][BUG] longhorn-uninstall job 中的错误日志 13549 - @yangchiu @c3y1huang
[BACKPORT][v1.12.1][BUG] V2 数据引擎：UBLK 在 Linux 内核 6.17.0 上因 EINVAL 失败 13274 - @chriscchien @carterli0407-cell
[BACKPORT][v1.12.1][BUG] 在 Harvester 中启用 LH V2 后内核工作队列锁定和 RKE2 服务不稳定 13495 - @derekbit @chriscchien
[BACKPORT][v1.12.1][BUG] V2 扩展可能报告成功而引擎仍保持旧大小 13380 - @davidcheng0922 @chriscchien
[BACKPORT][v1.12.1][BUG] 内核 >= 6.12 时从未检测到 FilesystemReadOnly —— ext4 报告 emergency_ro，而不是 ro；只读自动重新挂载静默失效 13482 - @yangchiu
[BACKPORT][v1.12.1][BUG] csi.ReplicaCount Helm 值在现有 csi- 部署上静默无操作（仅在首次创建时应用） 13465 - @roger-ryao
[BACKPORT][v1.12.1][BUG] v2 卷在自动重新附加后可能再次崩溃 13337 - @shuo-wu @roger-ryao
[BACKPORT][v1.12.1][BUG] 启用存储网络时 V2 卷无法附加 13490 - @c3y1huang
[BACKPORT][v1.12.1][BUG] v2 卷重复副本重用失败 13336 - @shuo-wu @chriscchien
[BACKPORT][v1.12.1][BUG] V2 加密卷恢复失败 13365 - @mantissahz @roger-ryao
[BACKPORT][v1.12.1][BUG] V2 备份/快照可能遗留 NVMe/TCP 前端或 dm 设备过时状态，导致附加卷的 Pod EIO 错误 13332 - @davidcheng0922 @chriscchien
[BACKPORT][v1.12.1][BUG] (chart) 使用 Gateway API 时 ArgoCD OutOfSync 13446 - @yangchiu
[BACKPORT][v1.12.1][BUG] 如果目标节点仍在就绪过渡中，迁移引擎可能被意外删除 13367 - @COLDTURNIP @yangchiu
[BACKPORT][v1.12.1][BUG] 循环 trim 任务因死锁而失败 13425 - @c3y1huang @roger-ryao
[BACKPORT][v1.12.1][BUG] 卷扩展卡住 13368 - @shuo-wu @chriscchien
[BACKPORT][v1.12.1][BUG] iscsid 重启后 pvc 调整大小失败 13412 - @yangchiu @shuo-wu
[BACKPORT][v1.12.1][BUG] 扩展卷失败 13384 - @chriscchien
[BACKPORT][v1.12.1][BUG] 测试用例 test_rwx_delete_share_manager_pod 失败，因为删除并重启后无法在共享管理器 Pod 中找到导出的卷 13226 - @davidcheng0922 @roger-ryao
[BACKPORT][v1.12.1][BUG] 系统备份 RecurringJob 保留策略会修剪最新的 CR —— 按 Status.CreatedAt 排序（对于 Error/竞争 CR 为零） 13209 - @roger-ryao
[BACKPORT][v1.12.1][BUG] 升级过程中 CSI 组件可能有 0 个运行的副本 13348 - @yangchiu @carterli0407-cell
[BACKPORT][v1.12.1][BUG] 节点更新强制完全重建 13357 - @mantissahz
[BACKPORT][v1.12.1][BUG] 为 v2 卷创建备份可能失败 13191 - @mantissahz
[BACKPORT][v1.12.1][BUG] 将备份上传到 S3 存储（NetApp 设备）时失败 13297 - @mantissahz
[BACKPORT][v1.12.1][BUG] spdk 中断模式值在 chart/values.yaml 中缺失 13269 - @yangchiu

韧性

[BACKPORT][v1.12.1][BUG] 瞬态 SPDK lvol 元数据故障可能永久使健康的 v2 副本失效 13542 - @roger-ryao

其他

[BACKPORT][v1.12.1][DOC] NetworkPolicy 设置指南 13622 - @COLDTURNIP @roger-ryao
[BACKPORT][v1.12.1][DOC] Chart values.yaml 仍引用数据引擎 V2 为实验性 13615 - @sushant-suse
[BACKPORT][v1.12.1][DOC] 将最低 Kubernetes 版本要求更新为 v1.34 13577 - @derekbit @roger-ryao
[BACKPORT][v1.12.1][BUG] 启用存储网络时，v2 卷卡在 attaching 状态，因为 EngineFrontend 目标使用引擎 Pod IP 而非 StorageIP 13353 - @yangchiu @c3y1huang

贡献者

@COLDTURNIP
@bachmanity1
@c3y1huang
@carterli0407-cell
@chriscchien
@davidcheng0922
@derekbit
@hookak
@innobead
@mantissahz
@roger-ryao
@shuo-wu
@sushant-suse
@yangchiu
@rebeccazzzz
@forbesguthrie
@asettle

更新内容（原始）

Longhorn v1.12.1 Release Notes

Longhorn v1.12.1 introduces V2 Data Engine fast volume cloning and storage sharding (experimental), along with important improvements and bug fixes that enhance system quality, resilience, stability, and security.

We welcome feedback and contributions to help continuously improve Longhorn.

For terminology and context on Longhorn releases, see Releases.

Breaking Changes

Deprecation of Legacy V2 Linked Clone Volumes

V2 linked-clone volumes created in v1.12.0 or earlier are marked as legacy and deprecated starting in v1.12.1. The new linked-clone architecture introduced in Issue #12552 is not compatible with the legacy design.

After upgrading to v1.12.1, legacy linked-clone volumes cannot be operated on except for detachment and deletion.

To replace, create new linked-clone volumes from the same source volumes that back the legacy ones. As long as a legacy volume exists, its source volume is guaranteed to still be present, so you can create a replacement linked clone directly; no data copy is required.

For more information, see Issue #12552.

Highlighted Features

Fast Volume Cloning

Longhorn v1.12.1 enhances fast volume cloning for the V2 Data Engine. A linked-clone volume shares data blocks with its source instead of copying data. With the new architecture, a source replica can share its data blocks with multiple linked-clone volumes, and multiple clone replicas can be created in parallel.

Linked-clone volumes now support most operations available to regular volumes, including snapshots, expansion, replica rebuilding, and use as the source of nested linked clones.

For more information, see Issue #12552 and CSI Volume Clone.

[!NOTE] V2 fast cloning does not currently support volume backup and restore. This improvement is tracked in Issue #13714.

Storage Sharding (Experimental)

Longhorn v1.12.1 introduces storage sharding as an experimental data protection and storage layout feature built on the V2 Data Engine. Instead of storing a full copy of the volume on each replica, sharding uses erasure coding to encode written data into data and parity chunks, which are distributed across multiple nodes. This allows a volume to grow beyond the capacity of a single disk or node while using less disk space to achieve the same level of fault tolerance.

Because this feature is experimental, it is intended for evaluation and testing only and is not recommended for production use.

For more information, see Issue #1061 and Sharding with Erasure Coding.

Important Improvements and Fixes

This release includes several important improvements and critical stability fixes.

Internal Network Policies

Longhorn v1.12.1 enables ingress NetworkPolicy resources for internal component endpoints and RPCs by default to improve security by restricting access to Longhorn internal services, including the instance-manager gRPC endpoint used for engine control. These policies only take effect when a NetworkPolicy provider is available in the cluster.

Longhorn has validated the internal network policies with the following Kubernetes distribution and CNI plugin combinations. See the CNI Plugin Compatibility table for the validated combinations. The minimum required Kubernetes version is v1.25.

For more information and troubleshooting guidance, see Internal Network Policies and Issue #13438.

[!NOTE] ServiceMonitor discovery does not automatically authorize network traffic. Cross-namespace Prometheus scrapers might be blocked by the Longhorn Manager’s network policy. To allow this traffic, apply a scoped additive policy as detailed in the Prometheus and Grafana setup guide.

Instance Manager gRPC mTLS Coverage

In previous versions, mutual TLS (mTLS) for the instance-manager gRPC endpoint only covered the instance and proxy services when the longhorn-grpc-tls secret was configured. Other services, including the disk service and the SPDK service, accepted plaintext connections.

Longhorn v1.12.1 extends mTLS to all remaining instance-manager gRPC services, so every gRPC port now requires a valid client certificate when the longhorn-grpc-tls secret is configured.

For more information, see Issue #7787.

CPU Core Allocation with the Kubernetes CPU Manager

Longhorn v1.12.1 can allocate exclusive CPU cores to the SPDK target daemon, which runs in each V2 Instance Manager pod, through the Kubernetes CPU Manager by using the data-engine-number-of-cpu-cores setting.

The setting can be applied only when the kubelet CPU Manager policy is set to static on all worker nodes; otherwise, the update is rejected. When the value is positive, it takes precedence, and data-engine-cpu-mask is ignored.

For more information, see Issue #13248.

Host CPU Isolation

The data-engine-cpu-isolation-enabled setting now also configures host network Receive Packet Steering (RPS) to steer RX softirq processing away from the CPU cores used by the SPDK target daemon, in addition to hardware IRQs and unbound kernel workqueue workers. Without this, the kernel can distribute incoming network packets to the SPDK reactor cores, and the resulting softirq work competes with the reactor’s busy-poll loop, degrading volume I/O under network load.

For more information, see Issue #13483 and Issue #13502.

V2 Data Engine SPDK iobuf Pool Size Configuration

Longhorn v1.12.1 allows tuning the SPDK iobuf buffer pools used by the V2 Data Engine. The data-engine-iobuf-large-pool-size and data-engine-iobuf-small-pool-size settings configure the large and 8 KiB small buffer pools, respectively. Increasing the small pool can relieve buffer exhaustion under high-queue-depth workloads with small I/O sizes. Because iobuf pools can only be sized at SPDK target startup, changing either setting recreates V2 Instance Manager pods that have no running instances.

For more information, see Issue #13322 and Issue #13674.

Encrypted Volume Size Correction

Longhorn reserves an additional 16 MiB of raw capacity for the LUKS2 metadata used by encrypted volumes, allowing the mapped device to expose the full capacity requested by the workload. Previously, the metadata was taken from usable capacity, so a requested 1 GiB encrypted volume exposed only 1008 MiB. This discrepancy could cause operations such as block-level copies between equally sized unencrypted and encrypted volumes to fail.

V1 Data Engine: This correction was introduced in Longhorn v1.12.0. Existing encrypted V1 volumes created with v1.11.x or earlier receive the additional capacity automatically when their engine image is upgraded to v1.12 or later. Encrypted migratable V1 volumes cannot be live-migrated until they are upgraded to the version (>= v1.12.0).
V2 Data Engine: Longhorn v1.12.1 applies the correction to newly created encrypted V2 volumes.

[!NOTE] Encrypted V2 volumes created before v1.12.1, and volumes restored from the backup of such volumes, do not receive the additional 16 MiB of raw capacity and continue to expose 16 MiB less than requested. Existing data is preserved.

For more information, see Issue #9205 and Issue #13163.

Installation

[!IMPORTANT] Ensure that your cluster is running Kubernetes v1.25 or later before installing Longhorn v1.12.1.

You can install Longhorn using a variety of tools, including Rancher, Kubectl, and Helm. For more information about installation methods and requirements, see Quick Installation in the Longhorn documentation.

Upgrade