KnoAI 技术站

主题

Harvester v1.8.2 容器化部署与运维文档集 ​

形态：Helm Chart 部署在已有 RKE2 集群（非 Harvester ISO 一体机）。 本目录所有结论、命令、脚本均在真实环境实测验证，日期 2026-09-05 ~ 09-06。

环境信息 ​

项值
Harvesterv1.8.2（chart harvester-1.8.2，appVersion v1.8.2）
KubeVirtv1.7.4-150700.3.24.2
Longhornv1.11.2
KubernetesRKE2 v1.34.4-rc11+rke2r1
节点3（sza122100/101/102.local，均为 control-plane），每节点可用存储 ≈110GB
API/UINodePort 32735，https://harvester.local:32735
CNICalico（VXLAN）
存储默认类harvester-longhorn（numberOfReplicas=3）

文档导航 ​

文档内容
01-部署实施手册.md一键部署流程、前置条件、Helm values、API/UI 访问、版本升级、回滚
02-故障排查与修复记录.md18 个实测案例：根因、修复命令、验证结果、排障方法论
03-运维手册-虚拟机生命周期.md创建/镜像导入/启停/快照恢复/清理，磁盘选型矩阵，状态速查表
04-运维手册-迁移与高可用.md冷迁移（可用）、热迁移（阻塞与修复路线）、节点维护模式、HA 与容量规划
scripts/部署、部署后固化、健康巡检、VM 端到端验证脚本
scripts/manifests/VM、快照、恢复、迁移、VolumeSnapshotClass 清单

30 秒速览（TL;DR） ​

bash
# 部署 → 固化 → 巡检 → 能力验证
bash scripts/deploy-harvester.sh --nodeport 32735
bash scripts/post-install.sh          # ★ 必做；每次 helm upgrade 后都要重跑
bash scripts/healthcheck.sh
bash scripts/vm-e2e-test.sh

能力矩阵（实测） ​

能力状态关键条件
部署 / API / UI✅NodePort + SNI（--resolve harvester.local:32735:<node-ip>）
创建 VM（RWO+Filesystem）✅masquerade 接口必需；默认 SC 指向 harvester-longhorn
冷迁移✅停机 → 改 nodeSelector → 启动
VM 快照创建✅gate=Snapshot（单数）；实测 5~11s 即 readyToUse=true
VM 快照恢复⚠️ 不可靠（勿用于生产）type: snap 下源卷被 restore 替换→Longhorn Snapshot 被 GC，与 full-copy 克隆竞态；4 次实测 2 失败、2 成功但卷遗留 degraded。须 type: bak + backup target，见 02 案例 17
热迁移❌ 阻塞KubeVirt 要求所有 PVC 为 RWX；Longhorn RWX 数据面不可用
节点维护模式⚠️ 需改策略默认 Migrate 依赖热迁移 → 本环境须用 ShutdownAndRestartAfterEnable
备份容灾⚠️ 待配置未配置 Longhorn backup target，type: bak 会失败

三条最容易踩的坑 ​

  1. KubeVirt feature gate 是 Snapshot（单数），不是 Snapshots 写错时 Helm 渲染通过、--set 无报错、CR 也能被 patch，但 virt-api 校验直接拒绝： snapshot feature gate not enabled。改 CR 后必须滚动重启 virt-api 才生效。
  2. helm upgrade 会覆盖 kubevirt CR，导致 gate 静默失效 → 每次升级后重跑 post-install.sh，并把 gate 检查纳入巡检（healthcheck.sh 已包含）。
  3. type: snap 的 VM 恢复不可靠：控制面全绿，数据面看运气VirtualMachineRestore complete=true、CSI VolumeSnapshot readyToUse=true、DV Succeeded、 甚至 DataVolumesReady=True 全部正常，但 Longhorn 卷可能 robustness=degraded、 cloneStatus 卡在 initiated、副本 mode=<none> → VM 卡 Scheduling。 机制：restore 会替换 VM 的 PVC → 源卷被删 → Longhorn Snapshot CR 因 ownerReference 指向源卷而被 GC，与 full-copy 克隆形成竞态。 4 次实测：2 次失败、2 次成功但卷仍 degraded（3 副本只建出 1 个）。 生产必须用 type: bak + backup target；恢复后务必核对卷的四元组 （state/robustness/replicas[*].mode/cloneStatus.state）。详见 02 案例 17。

磁盘规格选型（唯一可靠组合） ​

accessModesvolumeMode结论
ReadWriteOnceFilesystem✅ 推荐基线（全流程实测通过）
ReadWriteOnceBlock✅ 可用
ReadWriteManyBlock❌ blockdev: Permission denied（Longhorn RWX 无块设备）
ReadWriteManyFilesystem❌ 本环境不可用（无 share-manager/NFS）；修好后可支持热迁移

验证记录（2026-09-06，均在真实集群执行） ​

验证项命令结果
平台健康巡检bash scripts/healthcheck.shPASS=30 / WARN=6 / FAIL=0（6 条 WARN 均为真实或已知非致命）
VM 端到端bash scripts/vm-e2e-test.sh全流程通过：创建(DV 22s→Running) → 冷迁移(sza122100→sza122101，卷 healthy) → 快照(5s readyToUse=true) → 恢复(complete=true，VM 回到 Running) → 清理
无残留核查kubectl get vm,vmi,dv,pvc,pod -n default / volumes.longhorn.io全部 No resources found / 卷数 0（存储空间已释放）
快照类对象volumesnapshots / volumesnapshotcontents / KubeVirt virtualmachinesnapshots,virtualmachinerestores均为 0（无卡住的 content）
清单校验kubectl apply --dry-run=server -f scripts/manifests/*.yaml5/6 通过；vm-migrate.yaml 因要求存在运行中的同名 VMI 而被 webhook 拒绝（属预期，见 scripts/README.md）
脚本语法bash -n scripts/*.sh4/4 通过
节点与组件kubectl get nodes / deploy -n harvester-system3 节点 Ready；harvester 3/3、harvester-webhook 3/3、CDI 各组件 1/1

巡检脚本自身也曾误报（首版 7 个 FAIL 全为假警报），已定位六类取值缺陷并修复， 过程沉淀为 02 案例 16；vm-e2e-test.sh 首版亦因漏写 volumes: 段与 featureGates 解析错误被实测拦下 —— 两个脚本都是"跑过才算写完"。

遗留事项（Follow-up） ​

优先级事项参考
高如需热迁移：修复 Longhorn RWX（确认节点 NFS 客户端能力、share-manager 能否拉起）04 §3.3
高配置 Longhorn backup target 并改用 type: bak —— 这是 VM 快照可靠恢复的前提（type: snap 存在克隆/GC 竞态，实测 4 次 2 失败）02 案例 17、04 §5.2
中含 VM 的节点维护前，为 VM 打 ShutdownAndRestartAfterEnable 策略标签04 §4.2
中镜像源内网化（勿用公网 URL 作为生产镜像源）02 案例 13
低Steve/Rancher 聚合拨号、ssl-certificates requeue 属非致命噪声，可加告警白名单02 案例 11/12