3. 控制平面组件详解（上）
Longhorn 的控制平面由 Longhorn Manager 驱动，它是整个系统的“大脑”。本章深入剖析 Longhorn Manager 的核心职责、与 Kubernetes API Server 的交互机制，以及支撑整个系统的 CRD 资源模型（Volume、Engine、Replica）。理解这些组件是排查控制平面故障的基础。
3.1 Longhorn Manager 的核心职责
Longhorn Manager 以 DaemonSet 形式运行在每个 Kubernetes 节点上，但只有其中一个实例（Leader）执行全局协调任务。其核心职责可归纳为以下五点：
| 职责 | 说明 | 故障影响 |
|---|---|---|
| CRD 控制器 | 监听 Volume、Engine、Replica 等 CRD 对象的变化，驱动实际状态向期望状态收敛。 | CRD 状态停滞，卷无法创建/挂载 |
| 调度决策 | 为新卷选择最优节点放置 Engine 和 Replica，考虑磁盘容量、节点标签、反亲和性等。 | 卷调度失败，Replica 分布不均 |
| 健康监控 | 定期检查 Engine 和 Replica 进程的健康状态，触发故障转移或重建。 | 故障无法自动恢复，数据冗余降低 |
| API 网关 | 对外暴露 Longhorn API（默认端口 9500），供 UI、CLI 和外部系统调用。 | UI 无法访问，自动化工具失效 |
| 事件与指标 | 将系统事件写入 Kubernetes Event，暴露 Prometheus 指标用于监控。 | 监控数据缺失，告警失灵 |
kubectl logs -n longhorn-system <pod> -c longhorn-manager），重点关注 CRD 控制器循环的报错信息。
3.2 与 Kubernetes API Server 的交互
Longhorn Manager 与 Kubernetes API Server 的交互是控制平面工作的核心。它通过 Informer 机制 监听 CRD 和原生资源（Pod、Node、PV、PVC）的变化，并利用 WorkQueue 进行异步处理。
下图展示了 Longhorn Manager 与 API Server 之间的主要交互流程：
kubectl describe pod -n longhorn-system <longhorn-manager-pod> 中的 Events 部分，寻找与 API Server 通信相关的错误。
3.3 CRD 资源模型详解
Longhorn 通过自定义资源定义（CRD）将存储系统的状态映射到 Kubernetes 原生对象上。核心 CRD 包括 Volume、Engine、Replica、Node、Disk 等。本节重点讲解 Volume、Engine 和 Replica 三个核心资源。
3.3.1 Volume CRD
Volume CRD 是用户最直接接触的资源，它定义了逻辑卷的规格和当前状态。一个 Volume 对应一个 Kubernetes PV。
| 字段 | 类型 | 说明 |
|---|---|---|
spec.size |
string | 卷大小，例如 "10Gi" |
spec.numberOfReplicas |
int | 期望的副本数，默认 3 |
spec.staleReplicaTimeout |
int | 副本失效超时时间（分钟） |
spec.accessMode |
string | 访问模式：ReadWriteOnce / ReadWriteMany |
status.state |
string | 当前状态：creating / attached / detached / faulted |
status.robustness |
string | 健康度：healthy / degraded / faulted |
creating 或 detached，检查 Engine 和 Replica 的 CRD 状态是否正常。Volume 的 status.conditions 字段会提供详细的错误原因。
3.3.2 Engine CRD
Engine CRD 代表卷的 数据平面控制器。每个 Volume 对应一个 Engine 实例（故障转移时可能短暂存在多个）。Engine 负责处理来自前端（iSCSI/NFS）的 I/O 请求，并将数据复制到所有健康的 Replica。
- 关键字段：
spec.volumeName：关联的 Volume 名称。spec.replicaAddressMap：当前管理的 Replica 地址列表（IP:Port）。status.currentState：running / stopped / error。status.endpoint：Engine 暴露的前端端点（例如 iSCSI IQN）。
- 故障场景： 如果 Engine 状态为
error，通常意味着 Engine 进程崩溃或与所有 Replica 失去连接。检查 Engine Pod 日志（kubectl logs -n longhorn-system <engine-pod>）定位具体原因。
3.3.3 Replica CRD
Replica CRD 代表数据的 物理副本。每个 Replica 运行在一个单独的 Pod 中，负责将数据持久化到宿主机的磁盘上。
| 字段 | 类型 | 说明 |
|---|---|---|
spec.volumeName |
string | 所属 Volume 名称 |
spec.engineName |
string | 所属 Engine 名称 |
spec.diskUUID |
string | 数据存放的磁盘 UUID |
spec.nodeID |
string | 运行 Replica 的节点 |
status.currentState |
string | running / stopped / rebuilding / error |
status.failedAt |
string | 故障时间戳（如果 Replica 失败） |
status.currentState。如果某个 Replica 处于 rebuilding 状态，说明系统正在重建副本，此时 I/O 可能受到影响。使用 kubectl get replica -n longhorn-system -o wide 快速查看所有 Replica 的状态和分布。
3.4 资源模型关系图
下图展示了 Volume、Engine、Replica 三者之间的逻辑关系：
3.5 控制平面故障排查清单
基于以上组件分析，当控制平面出现问题时，可以按照以下清单进行排查：
- 检查 Longhorn Manager Pod 状态：
kubectl get pods -n longhorn-system -l app=longhorn-manager kubectl logs -n longhorn-system <pod> -c longhorn-manager --tail=100 - 检查 CRD 资源状态：
kubectl get volume -n longhorn-system kubectl get engine -n longhorn-system kubectl get replica -n longhorn-system - 检查 API Server 连通性：
kubectl get apiservice | grep longhorn kubectl describe pod -n longhorn-system <longhorn-manager-pod> | grep -A5 Events - 检查 Informer 同步状态： 查看 Longhorn Manager 日志中是否有
Failed to list或Watch channel closed等关键字。 - 检查 RBAC 权限：
kubectl get clusterrole longhorn-manager-role -o yaml kubectl get clusterrolebinding longhorn-manager-binding -o yaml