2. 卷生命周期管理：卷创建、挂载、快照、备份、恢复、删除的完整流程与API调用链
Longhorn 卷的生命周期是存储变更门禁的核心管控对象。从创建到销毁，每个阶段都对应明确的 API 入口、状态机转换和底层引擎操作。理解这一完整链路，是设计自动化迁移策略与故障恢复流程的前提。
2.1 卷生命周期全景状态机
Longhorn 卷在生命周期中经历以下核心状态：Detached → Attaching → Attached → Detaching → Detached。快照、备份、恢复等操作在 Attached 或 Detached 状态下均可触发，但删除操作仅在 Detached 状态下允许。
关键原则：卷的挂载状态与副本健康状态解耦。即使某个副本故障，卷仍可保持 Attached 状态，仅触发副本重建流程。
2.2 卷创建与挂载流程
2.2.1 创建卷 API 调用链
卷创建由 Longhorn Manager 的 VolumeController 处理，核心调用链如下：
- 用户请求：通过 Longhorn UI 或 kubectl 创建 Volume CR（Custom Resource）。
- Webhook 校验：Admission Webhook 检查参数合法性（大小、副本数、磁盘选择器）。
- VolumeController 编排：生成 Volume CR，状态置为
Detached。 - ReplicaScheduler 调度：根据调度策略选择 3 个副本所在节点与磁盘。
- InstanceManager 启动：在每个目标节点上启动 replica 进程。
- Engine 初始化：在卷挂载时启动 engine 进程，连接所有 replica。
| 步骤 | API 对象 | 控制器 | 说明 |
|---|---|---|---|
| 1 | Volume CR | Webhook | 校验 size、numberOfReplicas、diskSelector |
| 2 | Volume CR | VolumeController | 设置状态为 Detached，创建 Replica CR 列表 |
| 3 | Replica CR | ReplicaScheduler | 调度到满足条件的节点与磁盘 |
| 4 | InstanceManager CR | InstanceManagerController | 启动 replica 进程，等待 engine 连接 |
2.2.2 挂载卷 API 调用链
挂载操作将卷从 Detached 转换到 Attached 状态，并暴露块设备给工作负载：
# 挂载卷的典型 kubectl 操作
kubectl -n longhorn-system patch volume pvc-xxxx --type=merge \
-p '{"spec":{"nodeID":"worker-1","disableFrontend":false}}'
# 底层 API 调用链
POST /v1/volumes/{volumeName}?action=attach
→ VolumeController.Attach()
→ InstanceManager.CreateEngine()
→ Engine 进程启动，连接所有 replica
→ 创建 /dev/longhorn/volumeName 块设备
→ CSI NodePublishVolume 挂载到 Pod
生产建议：挂载操作是变更门禁的关键检查点。建议在挂载前校验目标节点磁盘余量、网络连通性、副本健康度，避免挂载到故障节点。
2.3 快照与备份流程
2.3.1 快照创建流程
Longhorn 快照基于 Copy-on-Write 机制，创建过程不阻塞 I/O：
- 用户触发快照请求（API 或 UI）。
- Engine 向所有 replica 发送
snapshot create命令。 - 每个 replica 创建新的差异文件（
.img），原文件变为只读快照。 - Engine 更新 volume meta，记录快照链。
- 快照创建完成，状态为
Ready。
2.3.2 备份到远程存储
备份将快照数据导出到 S3/NFS 等远程备份目标：
| 阶段 | 组件 | 操作 |
|---|---|---|
| 1. 备份触发 | BackupController | 创建 Backup CR，指定 snapshot 与 backupTarget |
| 2. 数据读取 | Engine → Replica | Engine 从 replica 读取快照数据块 |
| 3. 数据上传 | BackupStore | 分块上传到 S3/NFS，生成备份元数据 |
| 4. 备份完成 | BackupController | 更新 Backup CR 状态为 Completed，记录备份 URL |
2.4 恢复与删除流程
2.4.1 从备份恢复卷
恢复操作创建一个新卷，并从远程备份目标拉取数据：
# 从备份恢复的 API 调用
POST /v1/backups/{backupName}?action=restore
→ BackupController.Restore()
→ 创建新 Volume CR（状态 Detached）
→ 创建 Replica CR（初始为空）
→ Engine 启动，从备份目标流式拉取数据
→ 数据填充完成后，卷状态变为 Ready
恢复性能注意：从 S3 恢复大卷（>1TB）时，建议先恢复到本地快照再挂载，避免挂载后 I/O 阻塞。Longhorn 支持后台恢复（background restore），卷在数据完全恢复前即可挂载，但首次读取未恢复区域会触发同步等待。
2.4.2 卷删除流程
删除操作是生命周期中最危险的一步，变更门禁必须严格管控：
- 前置检查：卷必须处于
Detached状态，且无关联的 Pod 或 PVC。 - 删除 Volume CR：触发
VolumeController.Delete()。 - 清理 Replica：删除所有关联的 Replica CR，停止 replica 进程，清理磁盘数据。
- 清理 Engine：删除 Engine CR，停止 engine 进程。
- 清理快照/备份元数据：删除快照 CR，但备份数据保留在远程目标。
- 最终确认：Volume CR 从 etcd 中移除。
2.5 关键 API 调用链汇总
| 操作 | HTTP 方法 | API 路径 | 状态转换 |
|---|---|---|---|
| 创建卷 | POST | /v1/volumes | → Detached |
| 挂载卷 | POST | /v1/volumes/{name}?action=attach | Detached → Attaching → Attached |
| 卸载卷 | POST | /v1/volumes/{name}?action=detach | Attached → Detaching → Detached |
| 创建快照 | POST | /v1/volumes/{name}?action=snapshotCreate | 不改变卷状态 |
| 创建备份 | POST | /v1/volumes/{name}?action=backupCreate | 不改变卷状态 |
| 恢复备份 | POST | /v1/backups/{name}?action=restore | → Detached（新卷） |
| 删除卷 | DELETE | /v1/volumes/{name} | Detached → 移除 |
2.6 变更门禁集成点
在卷生命周期的以下节点，自动化迁移策略与故障恢复逻辑应插入门禁检查：
- 挂载前：校验目标节点磁盘余量 > 卷大小 20%、副本健康度 >= 2、网络延迟 < 10ms。
- 快照前：检查快照配额（单卷最多 256 个快照）、磁盘空间余量。
- 备份前：验证备份目标可达性、认证凭据有效性。
- 删除前：确认无 PVC 引用、无正在进行的迁移/重建任务。
自动化迁移策略示例：当节点进入维护模式时，门禁自动触发卷迁移流程：
1. 对卷创建快照 → 2. 在目标节点创建新副本 → 3. 等待数据同步完成 → 4. 切换 engine 到新副本 → 5. 卸载旧副本 → 6. 删除旧副本数据。
1. 对卷创建快照 → 2. 在目标节点创建新副本 → 3. 等待数据同步完成 → 4. 切换 engine 到新副本 → 5. 卸载旧副本 → 6. 删除旧副本数据。
掌握卷生命周期各阶段的 API 调用链与状态转换，是构建可靠存储变更门禁的基础。下一层我们将深入副本数据同步机制与故障检测策略。