3. 部署 Longhorn：环境要求与安装方式
Longhorn 作为云原生分布式块存储，对 Kubernetes 集群版本、节点资源及内核模块有明确要求。本章将系统梳理部署前的环境检查清单，并分别演示 Helm CLI 和 Rancher Marketplace 两种主流部署路径。
3.1 环境要求总览
部署 Longhorn 前，必须逐项确认以下条件，否则可能出现数据面异常或控制面不可用。
| 类别 | 最低要求 | 推荐配置 | 说明 |
|---|---|---|---|
| Kubernetes 版本 | v1.21+ | v1.27+ | 需启用 CSIDriver、VolumeSnapshot、ExpandInUsePersistentVolume 特性门控 |
| 节点数量 | 3 个 worker 节点 | ≥5 个 worker 节点 | 副本默认 3 份，节点数少于 3 将无法调度副本 |
| 每节点 CPU | 2 核 | 4 核 | Longhorn 引擎 + replica 进程各占 1 核 |
| 每节点内存 | 4 GiB | 8 GiB | 引擎约 512 MiB，每个 replica 约 256 MiB |
| 每节点磁盘 | 40 GiB 可用 | 100 GiB+ | 建议使用独立数据盘，不占用系统盘 |
| 文件系统 | ext4 / xfs | xfs | 必须支持 d_type（xfs 默认支持） |
| 内核模块 | iscsi_tcp、nbd |
同左 | 用于 iSCSI 发起端和块设备映射 |
| open-iscsi | v2.0.877+ | 最新稳定版 | 所有节点需安装 iscsiadm |
| NFS 客户端 | nfs-common / nfs-utils | 同左 | 仅在使用 ReadWriteMany 卷时需要 |
⚠ 版本漂移风险提示： Longhorn 的 CRD 版本与 Kubernetes API 版本强绑定。若集群从 v1.21 升级到 v1.28 后未同步升级 Longhorn，可能导致 CRD 存储版本不一致，引发卷挂载失败或数据不可用。本课程第 5 章将专门讲解版本漂移校准方案。
3.2 节点前置准备
在所有 worker 节点上执行以下操作：
- 安装 open-iscsi（Ubuntu/Debian 示例）
sudo apt-get update
sudo apt-get install -y open-iscsi
sudo systemctl enable --now iscsid
- 加载内核模块
sudo modprobe iscsi_tcp
sudo modprobe nbd
echo "iscsi_tcp" | sudo tee /etc/modules-load.d/longhorn.conf
echo "nbd" | sudo tee -a /etc/modules-load.d/longhorn.conf
- 确认节点标签（可选但推荐）
kubectl label node <node-name> node.longhorn.io/create-default-disk=true
💡 生产建议： 使用独立数据盘时，先格式化并挂载到统一路径（如
/var/lib/longhorn），再通过 Longhorn 的 default-disk 配置指定该路径，避免系统盘被存储流量打满。
3.3 使用 Helm 部署 Longhorn
Helm 是 Kubernetes 生态中最灵活的部署方式，适合 GitOps 和 CI/CD 集成场景。
3.3.1 添加 Helm 仓库
helm repo add longhorn https://charts.longhorn.io
helm repo update
3.3.2 创建命名空间
kubectl create namespace longhorn-system
3.3.3 安装 Longhorn（带自定义参数）
helm install longhorn longhorn/longhorn \
--namespace longhorn-system \
--set persistence.defaultClassReplicaCount=3 \
--set defaultSettings.replicaSoftAntiAffinity=false \
--set defaultSettings.guaranteedEngineManagerCPU=0.25 \
--set defaultSettings.guaranteedReplicaManagerCPU=0.25
| 参数 | 默认值 | 说明 |
|---|---|---|
persistence.defaultClassReplicaCount |
3 | 默认 StorageClass 的副本数 |
defaultSettings.replicaSoftAntiAffinity |
true | 设为 false 强制硬反亲和，避免副本分布在同一节点 |
defaultSettings.guaranteedEngineManagerCPU |
0.12 | 引擎管理器预留 CPU，生产建议 0.25 |
defaultSettings.guaranteedReplicaManagerCPU |
0.12 | 副本管理器预留 CPU，生产建议 0.25 |
3.3.4 验证部署
kubectl -n longhorn-system get pods -w
kubectl -n longhorn-system get svc longhorn-frontend
当所有 Pod 进入 Running 状态后，通过 longhorn-frontend 的 NodePort 或 Ingress 访问 UI。
3.4 使用 Rancher Marketplace 部署
对于已部署 Rancher 管理平台的团队，Marketplace 提供图形化一键部署，降低操作门槛。
3.4.1 进入 Apps & Marketplace
- 登录 Rancher UI，选择目标集群。
- 左侧导航栏点击 Apps > Charts。
- 搜索 Longhorn，点击进入详情页。
3.4.2 配置安装参数
Rancher 会以表单形式展示关键参数，与 Helm values 一一对应：
- Namespace：默认
longhorn-system，建议保持。 - Replica Count：生产环境设为 3。
- Default Data Path：指定数据盘挂载路径，如
/var/lib/longhorn。 - Ingress：可选启用，配合 TLS 证书暴露 UI。
3.4.3 启动安装
点击 Install，Rancher 会自动执行 Helm 安装并等待 Pod 就绪。安装完成后，可在 Apps > Installed Apps 中查看状态。
🔑 关键差异： Rancher Marketplace 本质是对 Helm Chart 的封装，底层安装逻辑相同。区别在于：Marketplace 提供图形化参数校验和依赖检查，适合运维经验较少的团队；Helm CLI 更适合自动化流水线和版本锁定场景。
3.5 部署架构与组件关系
下图展示了 Longhorn 部署后的核心组件及其交互关系，帮助理解控制面与数据面的分离设计。
3.6 部署后验证清单
无论使用哪种部署方式，安装完成后都应执行以下验证：
| 检查项 | 命令 / 方法 | 预期结果 |
|---|---|---|
| Pod 状态 | kubectl -n longhorn-system get pods |
所有 Pod 均为 Running 或 Completed |
| StorageClass | kubectl get sc |
存在 longhorn（默认）或自定义名称 |
| 节点磁盘 | Longhorn UI → Node → 查看 Disk | 每个节点显示可用磁盘容量 |
| 卷创建 | kubectl create -f test-pvc.yaml |
PVC 状态 Bound，Pod 可正常读写 |
| iSCSI 连接 | iscsiadm -m session |
显示 Longhorn 引擎的 iSCSI 会话 |
📌 版本漂移预防： 部署完成后，立即记录 Longhorn 版本与 Kubernetes 版本的对应关系：
kubectl -n longhorn-system get deployment longhorn-manager -o jsonpath='{.spec.template.spec.containers[0].image}'。将此信息纳入集群版本变更的准入检查项。