GeekIt

Longhorn命令速查

Helm 安装、组件巡检、StorageClass 与 PVC、卷管理、快照备份、灾备恢复、节点磁盘、故障排查等 134 条命令

共 134 条命令 · 12 类场景 · 点击右侧图标可复制

命令说明复制
curl -sSfL https://raw.githubusercontent.com/longhorn/longhorn/v1.7.0/scripts/environment_check.sh | bash安装前环境检查:iSCSI、NFS、内核模块与端口
helm repo add longhorn https://charts.longhorn.io && helm repo update添加 Longhorn Helm 仓库
helm install longhorn longhorn/longhorn -n longhorn-system --create-namespace --version 1.7.0安装 Longhorn,指定版本便于环境可复现
kubectl -n longhorn-system get pods -w观察各组件启动过程
kubectl -n longhorn-system get deploy,ds确认 longhorn-manager、ui、driver 等负载就绪
helm upgrade longhorn longhorn/longhorn -n longhorn-system --version 1.7.1升级前先备份并确认兼容性矩阵
kubectl -n longhorn-system get settings.longhorn.io查看全局设置项
kubectl -n longhorn-system get storageclass确认 longhorn StorageClass 已创建
kubectl get csidriver确认 driver.longhorn.io 已注册
helm uninstall longhorn -n longhorn-system卸载前必须先删除所有卷与备份配置
kubectl -n longhorn-system delete pvc --all卸载前清理示例卷,否则卸载会卡住
命令说明复制
kubectl -n longhorn-system get pods -o wide查看所有组件及其所在节点
kubectl -n longhorn-system get pods -l app=longhorn-managerlonghorn-manager 以 DaemonSet 运行在每个节点
kubectl -n longhorn-system get daemonset longhorn-manager确认期望副本数与就绪数一致
kubectl -n longhorn-system get deploy longhorn-uiUI 组件状态
kubectl -n longhorn-system get svc查看 longhorn-frontend/backend 服务
kubectl -n longhorn-system get volumes.longhorn.io列出所有卷及状态与节点
kubectl -n longhorn-system get replicas.longhorn.io查看副本分布与健康状态
kubectl -n longhorn-system get engines.longhorn.io查看引擎状态与实例
kubectl -n longhorn-system get nodes.longhorn.io查看存储节点、磁盘与调度开关
kubectl -n longhorn-system get instancemanagers.longhorn.io实例管理器负责引擎与副本进程
kubectl -n longhorn-system get engineimages.longhorn.io查看引擎镜像版本
kubectl get nodes -o wide确认节点 Ready 与内核版本
命令说明复制
kubectl -n longhorn-system port-forward svc/longhorn-frontend 8080:80本地端口转发访问 UI(http://localhost:8080)
kubectl -n longhorn-system get svc longhorn-frontend -o yaml查看 UI 服务类型与端口
kubectl -n longhorn-system patch svc longhorn-frontend -p '{"spec":{"type":"NodePort"}}'临时改为 NodePort 访问(生产建议走 Ingress + 认证)
kubectl -n longhorn-system get svc longhorn-backend后端 API 服务,默认 9500
kubectl -n longhorn-system get endpoints longhorn-backend确认 backend 有就绪端点
kubectl -n longhorn-system logs deploy/longhorn-ui --tail=100UI 无法打开时查看日志
kubectl -n longhorn-system logs deploy/longhorn-driver-deployerCSI driver 部署异常看这里
UI 中的 Volume/Node/Backup 页面对应 CRDUI 操作与 kubectl 操作等价,排障以 CRD 为准
UI 无鉴权,不要直接暴露公网暴露等于开放卷删除与备份下载权限
命令说明复制
kubectl get storageclass longhorn -o yaml查看默认 StorageClass 参数
kubectl get storageclass确认 longhorn 是否为默认 StorageClass
kubectl patch storageclass longhorn -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'设为默认 StorageClass
kubectl get pvc -A查看所有 PVC 及绑定状态
kubectl describe pvc mydata -n prodPVC 一直 Pending 时看事件与 StorageClass
kubectl get pv查看 PV 与回收策略
kubectl get pv <pv-name> -o yaml查看 PV 关联的 Longhorn 卷与节点
parameters: {numberOfReplicas: "3", staleReplicaTimeout: "30"}StorageClass 关键参数:副本数与失联超时
parameters: {dataLocality: "best-effort"}数据本地化,减少跨节点读取延迟
parameters: {replicaAutoBalance: "least-effort"}副本自动均衡策略
parameters: {diskSelector: "ssd", nodeSelector: "storage"}按磁盘与节点标签调度副本
reclaimPolicy 建议 Retain误删 PVC 时仍可手动恢复 PV
命令说明复制
kubectl -n longhorn-system get volumes.longhorn.io列出卷、状态、副本数与节点
kubectl -n longhorn-system describe volumes.longhorn.io <vol>查看卷详情与事件,状态异常先看这里
kubectl -n longhorn-system get volumes.longhorn.io <vol> -o yaml查看卷完整 spec 与 status
kubectl -n longhorn-system patch volumes.longhorn.io <vol> --type merge -p '{"spec":{"numberOfReplicas":3}}'调整副本数,重建期间会有 IO 影响
kubectl -n longhorn-system patch volumes.longhorn.io <vol> --type merge -p '{"spec":{"nodeID":"node1"}}'指定卷挂载节点(手动 attach)
kubectl -n longhorn-system patch volumes.longhorn.io <vol> --type merge -p '{"spec":{"nodeID":""}}'分离卷(detach)
kubectl -n longhorn-system patch volumes.longhorn.io <vol> --type merge -p '{"spec":{"accessMode":"rwx"}}'调整访问模式(需重建或兼容配置)
kubectl -n longhorn-system delete volumes.longhorn.io <vol>删除卷 CR(会连带删除底层数据)
kubectl -n longhorn-system get replicas.longhorn.io -l longhornvolume=<vol>查看该卷的副本分布
kubectl -n longhorn-system get engines.longhorn.io -l longhornvolume=<vol>查看该卷的引擎实例
kubectl -n longhorn-system get volumes.longhorn.io -o custom-columns=NAME:.metadata.name,STATE:.status.state,ROBUSTNESS:.status.robustness自定义列快速巡检卷健康度
命令说明复制
kubectl -n longhorn-system get snapshots.longhorn.io查看卷快照
kubectl get volumesnapshotclass确认 VolumeSnapshotClass 为 longhorn
kubectl apply -f volumesnapshot.yaml通过 VolumeSnapshot 创建一致性快照
kubectl -n longhorn-system get backups.longhorn.io查看已完成的备份
kubectl -n longhorn-system get backuptargets.longhorn.io查看备份目标(S3/NFS)与可用状态
kubectl -n longhorn-system get backupvolumes.longhorn.io查看备份卷与对应卷的映射
kubectl -n longhorn-system get recurringjobs.longhorn.io查看定时快照与备份任务
kubectl -n longhorn-system patch settings.longhorn.io backup-target --type merge -p '{"value":"s3://longhorn-backup@ap-east-1/"}'配置 S3 备份目标
kubectl -n longhorn-system patch settings.longhorn.io backup-target-credential-secret --type merge -p '{"value":"minio-secret"}'指定存放 AK/SK 的 Secret 名称
kubectl create secret generic minio-secret -n longhorn-system --from-literal=AWS_ACCESS_KEY_ID=AK --from-literal=AWS_SECRET_ACCESS_KEY=SK --from-literal=AWS_ENDPOINTS=http://minio:9000创建备份凭据 Secret(键名固定)
recurringjobs 的 task 可选 snapshot 或 backup先快照再备份,备份是快照上传到对象存储
备份前先确认卷处于 healthy 状态降级的卷做备份可能得到不完整数据
命令说明复制
parameters: {fromBackup: "s3://longhorn-backup@ap-east-1/?backup=backup-xxx&volume=vol-xxx"}从备份创建新卷的标准写法
kubectl apply -f restore-pvc.yaml用 fromBackup 的 StorageClass 创建 PVC 完成恢复
kubectl -n longhorn-system patch volumes.longhorn.io <dr-vol> --type merge -p '{"spec":{"drVolume":true}}'创建 DR 卷,持续同步最新备份
kubectl -n longhorn-system patch volumes.longhorn.io <dr-vol> --type merge -p '{"spec":{"drVolume":false}}'把 DR 卷转为可读写普通卷(激活)
kubectl -n longhorn-system get backups.longhorn.io -o wide确认备份状态与大小
kubectl -n longhorn-system get backuptargets.longhorn.io -o yaml确认备份目标可达
恢复演练要定期做备份成功不等于可恢复,需验证 fromBackup 流程
删除 PV 前先确认备份完成reclaimPolicy=Delete 会连带删除 Longhorn 卷
跨集群恢复需相同的备份目标与凭据目标集群能访问同一 S3 桶才能恢复
命令说明复制
kubectl -n longhorn-system get settings.longhorn.io列出全部设置项与当前值
kubectl -n longhorn-system edit settings.longhorn.io default-replica-count修改默认副本数(需重建卷生效)
kubectl -n longhorn-system patch settings.longhorn.io storage-over-provisioning-percentage --type merge -p '{"value":"200"}'超分比例,按实际磁盘余量谨慎设置
kubectl -n longhorn-system patch settings.longhorn.io replica-soft-anti-affinity --type merge -p '{"value":"true"}'软反亲和,副本尽量分散但不阻塞调度
kubectl -n longhorn-system patch settings.longhorn.io node-down-pod-deletion-policy --type merge -p '{"value":"delete-both-statefulset-and-deployment-pod"}'节点故障时 Pod 处理策略
kubectl -n longhorn-system patch settings.longhorn.io auto-salvage --type merge -p '{"value":"true"}'卷异常时自动尝试恢复
kubectl -n longhorn-system patch settings.longhorn.io concurrent-replica-rebuild-per-node-limit --type merge -p '{"value":"2"}'限制单节点重建并发,控制 IO 压力
kubectl -n longhorn-system patch settings.longhorn.io guaranteed-instance-manager-cpu --type merge -p '{"value":"12"}'为实例管理器预留 CPU(百分比)
kubectl -n longhorn-system patch settings.longhorn.io default-data-locality --type merge -p '{"value":"best-effort"}'默认数据本地化策略
kubectl -n longhorn-system patch settings.longhorn.io backup-compression-method --type merge -p '{"value":"lz4"}'备份压缩算法,节省存储与带宽
改全局设置会影响所有新卷已有卷需单独调整 CR 或重建
命令说明复制
kubectl -n longhorn-system get nodes.longhorn.io查看存储节点与调度状态
kubectl -n longhorn-system get nodes.longhorn.io <node> -o yaml查看磁盘配置、标签与预留空间
kubectl label node <node> node.longhorn.io/create-default-disk=true给节点打标签,自动创建默认磁盘
kubectl annotate node <node> node.longhorn.io/default-disks-config='[{"path":"/data/longhorn","allowScheduling":true}]'通过注解指定默认磁盘路径
kubectl -n longhorn-system edit nodes.longhorn.io <node>手动添加磁盘、设置标签与预留空间
kubectl -n longhorn-system patch nodes.longhorn.io <node> --type merge -p '{"spec":{"allowScheduling":false}}'停止在该节点新建副本(维护前)
kubectl -n longhorn-system patch nodes.longhorn.io <node> --type merge -p '{"spec":{"evictionRequested":true}}'驱逐该节点副本,准备下线
kubectl -n longhorn-system patch nodes.longhorn.io <node> --type merge -p '{"spec":{"tags":["ssd","storage"]}}'给节点打标签,配合 nodeSelector 使用
kubectl -n longhorn-system get nodes.longhorn.io -o custom-columns=NAME:.metadata.name,SCHEDULABLE:.spec.allowScheduling快速检查调度开关
磁盘预留空间默认 30%预留不足会导致副本无法重建
命令说明复制
kubectl -n longhorn-system get events --sort-by=.lastTimestamp | tail -30按时间查看最近事件
kubectl -n longhorn-system logs ds/longhorn-manager --tail=200manager 日志,卷调度与副本异常核心日志
kubectl -n longhorn-system logs -l longhorn.io/component=instance-manager --tail=200实例管理器日志,引擎与副本进程在这里
kubectl -n longhorn-system get pods -l longhorn.io/component=instance-manager -o wide确认实例管理器与卷同节点
kubectl describe pvc <pvc> -n <ns>PVC 挂载失败看事件与 StorageClass
kubectl get volumeattachment查看卷挂载记录,定位 multi-attach
kubectl -n longhorn-system get volumes.longhorn.io -o yaml | grep -A3 robustness批量查看卷健康度
kubectl -n longhorn-system get replicas.longhorn.io -o wide副本所在节点与状态
kubectl -n longhorn-system get events --field-selector reason=FailedAttachVolume只看挂载失败事件
kubectl get pod <pod> -o yaml | grep -A5 volumes确认 Pod 实际引用的 PVC
kubectl -n longhorn-system logs deploy/longhorn-driver-deployerCSI 相关故障看 driver-deployer
kubectl top pod -n longhorn-system查看组件资源占用,实例管理器吃内存要关注
命令说明复制
kubectl -n longhorn-system patch nodes.longhorn.io <node> --type merge -p '{"spec":{"evictionRequested":true}}'节点维护前驱逐副本
kubectl -n longhorn-system get replicas.longhorn.io -o wide | grep <node>确认该节点副本已迁走
kubectl cordon <node> && kubectl drain <node> --ignore-daemonsets --delete-emptydir-data排空业务 Pod
kubectl -n longhorn-system get pods -l longhorn.io/component=instance-manager --field-selector spec.nodeName=<node>确认节点上实例管理器状态
kubectl -n longhorn-system rollout restart deploy/longhorn-ui重启 UI 组件
kubectl -n longhorn-system rollout restart ds/longhorn-manager滚动重启 manager(逐个节点,影响小)
helm upgrade longhorn longhorn/longhorn -n longhorn-system升级前先备份并阅读升级说明
kubectl -n longhorn-system get settings.longhorn.io | grep -i version核对各组件与引擎镜像版本一致
volumes.longhorn.io 与 PV 一一对应迁移存储类时需新建 PV/PVC 再复制数据
nodeID 变更要先把卷 detach直接改 nodeID 可能导致多节点同时挂载
命令说明复制
Volume is degraded(降级)副本缺失或失败:查 replicas 状态与节点磁盘,等待重建或手动触发
Replica failed / replica is not healthy副本进程异常,检查实例管理器与磁盘空间
Failed to attach volume目标节点无实例管理器、磁盘不可调度或副本不足
Multi-Attach error for volumeRWO 卷被多 Pod 使用:改 Deployment 策略为 Recreate 或换 RWX
卷长期 attaching / detaching查 manager 日志与 volumeattachment,常见于节点失联
no available node to schedule replica节点打满、磁盘不可调度或标签不匹配
insufficient storage磁盘剩余低于预留比例,清理或扩容
backup target is not accessibleS3/NFS 不可达或凭据 Secret 键名不对
failed to upload backup网络中断、桶权限不足或备份目标配置错误
PVC PendingStorageClass 不存在、容量不足或 CSI 未就绪
engine dead / engine crashed实例管理器重启或 OOM,检查资源限制与日志
instance manager is not running该节点实例管理器未启动,检查 DaemonSet 与节点状态
kubelet stopped posting node status节点 NotReady,卷会转 degraded,先恢复节点
卷无法删除(一直 terminating)先删使用它的 Pod/PVC,必要时清 finalizer(谨慎)
iSCSI 相关报错节点未安装 iscsi-initiator-utils 或 iscsid 未启动

运维常用组合

安装自检environment_check.sh → helm install → get pods -w → get storageclass → get nodes.longhorn.io
创建高可用卷StorageClass 设 numberOfReplicas=3 → kubectl apply pvc → get volumes.longhorn.io → 确认 robustness healthy
备份配置patch backup-target → create secret → patch backup-target-credential-secret → recurringjob → get backups
故障排查get volumes 看状态 → get replicas 看副本 → logs ds/longhorn-manager → get events → 修复或重建副本
节点维护allowScheduling=false → evictionRequested=true → cordon/drain → 维护 → 恢复调度
灾备恢复get backups → fromBackup 创建 PVC → 挂载校验数据 → 切换业务 → 保留旧卷观察

常见问题排查

1. 先看 robustness

volumes.longhorn.io 的 robustness 为 healthy 才说明副本齐全,degraded 要立刻查副本

2. 副本要跨节点

副本数不能超过可调度节点数,节点数不足时开软反亲和而不是硬性要求

3. 磁盘预留别调太小

预留空间用于副本重建,预留不足会导致失败循环

4. RWO 不是分布式锁

同一 RWO 卷不能同时挂两个节点,滚动更新用 Recreate 策略

5. 备份先快照后上传

recurring job 把 snapshot 与 backup 分开配置,排障时更容易定位

6. 维护前先驱逐

evictionRequested 会把副本迁走,直接关机可能造成长时间降级

共 134 条 Longhorn 命令 · 示例中的卷名、节点名与备份地址请替换为实际环境

关于Longhorn命令速查

在线 Longhorn 命令速查手册,按安装与升级、组件与状态巡检、UI 与访问、StorageClass 与 PVC、卷管理、快照与备份、灾备与恢复、设置与调优、节点与磁盘管理、故障排查与日志、运维操作与迁移、常见报错与排查等 12 类场景整理 140+ 条常用命令,每条附中文说明与可直接复制的写法,支持关键词搜索、分类折叠和一键复制,打开网页即可查阅。涵盖 environment_check.sh 与 helm repo add/install/upgrade/uninstall 与 kubectl -n longhorn-system get pods/deploy/ds/svc 与 storageclass/csidriver、卷 CR 的 volumes.longhorn.io 与 replicas.longhorn.io 与 engines.longhorn.io 与 nodes.longhorn.io 与 instancemanagers.longhorn.io 与 engineimages.longhorn.io 与 snapshots.longhorn.io 与 backups.longhorn.io 与 backuptargets.longhorn.io 与 backupvolumes.longhorn.io 与 recurringjobs.longhorn.io、port-forward svc/longhorn-frontend 8080:80 与 longhorn-backend 9500 与 NodePort 改造、StorageClass 的 numberOfReplicas/staleReplicaTimeout/dataLocality/replicaAutoBalance/diskSelector/nodeSelector 与 is-default-class 与 reclaimPolicy Retain、PVC/PV 排查与 volumeattachment、卷 patch 修改 numberOfReplicas/nodeID/accessMode 与 detach 与删除、VolumeSnapshotClass longhorn 与快照备份、backup-target 与 backup-target-credential-secret 与 AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_ENDPOINTS Secret、fromBackup 恢复与 drVolume 切换、settings 的 default-replica-count/storage-over-provisioning-percentage/replica-soft-anti-affinity/node-down-pod-deletion-policy/auto-salvage/concurrent-replica-rebuild-per-node-limit/guaranteed-instance-manager-cpu/default-data-locality/backup-compression-method、nodes.longhorn.io 的 create-default-disk 标签与 default-disks-config 注解与 allowScheduling/evictionRequested/tags、manager 与 instance-manager 日志与 events 与 FailedAttachVolume 与 top pod,以及 Volume is degraded、Replica failed、Failed to attach volume、Multi-Attach error、attaching/detaching 卡住、insufficient storage、backup target not accessible、PVC Pending、engine dead、instance manager not running、iSCSI 报错等排查。适用于 Longhorn 云原生块存储部署与运维、K8s 有状态应用存储规划、多副本与数据本地化调优、快照与 S3 备份、DR 卷与跨集群恢复、节点扩缩容与维护驱逐、卷降级与副本重建排障,以及 K8s 存储运维与面试复习。

核心能力

  • 涵盖 environment_check.sh 与 helm repo add/install/upgrade/uninstall 与 kubectl -n longhorn-system get pods/deploy/ds/svc 与 storageclass/csidriver、卷 CR 的 volumes.longhorn.io 与 replicas.longhorn.io 与 engines.longhorn.io 与 nodes.longhorn.io 与 instancemanagers.longhorn.io 与 engineimages.longhorn.io 与 snapshots.longhorn.io 与 backups.longhorn.io 与 backuptargets.longhorn.io 与 backupvolumes.longhorn.io 与 recurringjobs.longhorn.io、port-forward svc/longhorn-frontend 8080:80 与 longhorn-backend 9500 与 NodePort 改造、StorageClass 的 numberOfReplicas/staleReplicaTimeout/dataLocality/replicaAutoBalance/diskSelector/nodeSelector 与 is-default-class 与 reclaimPolicy Retain、PVC/PV 排查与 volumeattachment、卷 patch 修改 numberOfReplicas/nodeID/accessMode 与 detach 与删除、VolumeSnapshotClass longhorn 与快照备份、backup-target 与 backup-target-credential-secret 与 AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_ENDPOINTS Secret、fromBackup 恢复与 drVolume 切换、settings 的 default-replica-count/storage-over-provisioning-percentage/replica-soft-anti-affinity/node-down-pod-deletion-policy/auto-salvage/concurrent-replica-rebuild-per-node-limit/guaranteed-instance-manager-cpu/default-data-locality/backup-compression-method、nodes.longhorn.io 的 create-default-disk 标签与 default-disks-config 注解与 allowScheduling/evictionRequested/tags、manager 与 instance-manager 日志与 events 与 FailedAttachVolume 与 top pod,以及 Volume is degraded、Replica failed、Failed to attach volume、Multi-Attach error、attaching/detaching 卡住、insufficient storage、backup target not accessible、PVC Pending、engine dead、instance manager not running、iSCSI 报错等排查

适用场景

适用于 Longhorn 云原生块存储部署与运维、K8s 有状态应用存储规划、多副本与数据本地化调优、快照与 S3 备份、DR 卷与跨集群恢复、节点扩缩容与维护驱逐、卷降级与副本重建排障,以及 K8s 存储运维与面试复习。Longhorn命令速查全程在浏览器中完成,无需安装插件,可放心用于日常办公与排障。

常见问题

Longhorn命令速查是免费的吗?需要注册或安装吗?
Longhorn命令速查完全免费,无需注册、无需下载安装任何软件,用浏览器打开网页即可直接使用,也不限制使用次数。
Longhorn命令速查支持哪些功能?
涵盖 environment_check.sh 与 helm repo add/install/upgrade/uninstall 与 kubectl -n longhorn-system get pods/deploy/ds/svc 与 storageclass/csidriver、卷 CR 的 volumes.longhorn.io 与 replicas.longhorn.io 与 engines.longhorn.io 与 nodes.longhorn.io 与 instancemanagers.longhorn.io 与 engineimages.longhorn.io 与 snapshots.longhorn.io 与 backups.longhorn.io 与 backuptargets.longhorn.io 与 backupvolumes.longhorn.io 与 recurringjobs.longhorn.io、port-forward svc/longhorn-frontend 8080:80 与 longhorn-backend 9500 与 NodePort 改造、StorageClass 的 numberOfReplicas/staleReplicaTimeout/dataLocality/replicaAutoBalance/diskSelector/nodeSelector 与 is-default-class 与 reclaimPolicy Retain、PVC/PV 排查与 volumeattachment、卷 patch 修改 numberOfReplicas/nodeID/accessMode 与 detach 与删除、VolumeSnapshotClass longhorn 与快照备份、backup-target 与 backup-target-credential-secret 与 AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_ENDPOINTS Secret、fromBackup 恢复与 drVolume 切换、settings 的 default-replica-count/storage-over-provisioning-percentage/replica-soft-anti-affinity/node-down-pod-deletion-policy/auto-salvage/concurrent-replica-rebuild-per-node-limit/guaranteed-instance-manager-cpu/default-data-locality/backup-compression-method、nodes.longhorn.io 的 create-default-disk 标签与 default-disks-config 注解与 allowScheduling/evictionRequested/tags、manager 与 instance-manager 日志与 events 与 FailedAttachVolume 与 top pod,以及 Volume is degraded、Replica failed、Failed to attach volume、Multi-Attach error、attaching/detaching 卡住、insufficient storage、backup target not accessible、PVC Pending、engine dead、instance manager not running、iSCSI 报错等排查。
Longhorn命令速查适合哪些场景使用?
适用于 Longhorn 云原生块存储部署与运维、K8s 有状态应用存储规划、多副本与数据本地化调优、快照与 S3 备份、DR 卷与跨集群恢复、节点扩缩容与维护驱逐、卷降级与副本重建排障,以及 K8s 存储运维与面试复习。