Harvester 从入门到精通 · HCI 虚拟化平台实战全书

基于 Harvester v1.8.2 的两套真实环境实测沉淀（2026-09）： ① ISO 一体机——3 节点 Harvester OS，netboot 无人值守装机，总编排 42 分钟； ② 容器化形态——把 Harvester/KubeVirt 以 Helm 装进既有 RKE2 集群，VM 全生命周期端到端跑通。
全书 14 章 + 2 个附录，含 46 个实测故障案例、6 个端到端实战场景、以及**「公有云 IaaS / 传统虚拟化 / 裸 KubeVirt / Harvester 容器化 / Harvester ISO 一体机」五方对比**。所有命令均可直接复制执行；标注 ✓ 的结论为实测验证，标注 ⚠️/❌ 的为已定位的坑与阻塞点。

1. 这本书解决什么问题

你的处境	直接看
第一次听说 Harvester，想知道它和 KubeVirt / OpenStack / 云厂商 ECS 有什么关系	01 入门篇 → 10 五方对比
想在一台机器上 30 分钟跑出第一台虚拟机	02 快速上手
要交付一套裸金属 HCI 集群（装机、网络、HA、验收）	03 ISO 无人值守装机 → 11 生产落地
已有 K8s/RKE2 集群，想叠加虚拟化能力	04 容器化部署
日常运维：建机、镜像、快照、备份、迁移、维护模式	05 06 07 08
要被 Rancher 纳管、接私仓、做 GitOps	09 生态集成
出故障了	13 故障排查手册 + 附录A 速查

2. 全书地图

第一部分 · 认知与上手

章节	内容	关键产出
01 入门篇 · 架构全景与核心概念	HCI 是什么、七层技术栈、20+ 组件职责、CRD 资源模型、VM 状态机、术语表	一张能画出来的架构图
02 快速上手 · 从零到第一台虚拟机	三条上手路径、硬件与嵌套虚拟化门槛、首登认证与改密、UI/YAML 双路建机	一台能 SSH 的 VM

第二部分 · 部署实战（两种形态）

章节	内容	关键产出
03 部署实战 A · ISO 一体机无人值守装机	netboot 引导链路、cmdline 逐项、libvirt 域定义、`config.yaml` 逐字段、编排状态机、三层自愈、耗时基线	42 分钟出 3 节点 HA
04 部署实战 B · 容器化 KubeVirt 装进既有 K8s	`promote` 模式、values 关键项、与既有组件的冲突预判、部署后必做 4 项固化、升级与回滚	既有集群叠加虚拟化

第三部分 · 运维精通

章节	内容	关键产出
05 虚拟机生命周期实战	创建/启停/重启、镜像导入四源、cloud-init、快照与恢复、删除与无残留核查、状态速查	全生命周期 SOP
06 存储实战 · Longhorn 快照与备份选型	`accessModes × volumeMode` 矩阵、`snap` vs `bak`、backup target、恢复后数据面四元组核对	不丢数据的存储规范
07 网络实战 · VLAN、负载均衡与 DNS	管理网/VLAN 网络、masquerade 与 bridge、whereabouts、kube-vip VIP、NodePort+SNI、CoreDNS 随机上游陷阱	内外网分离方案
08 高可用与迁移实战	冷迁移 SOP、热迁移硬性前提与阻塞点、维护模式策略、etcd quorum、节点自动提升、容灾演练	HA 能力矩阵
09 接入 Rancher 与生态集成	Virtualization Management 导入六步、`cluster-registration-url`、UI 数据面代理路径、私仓与 `containerd-registry`	统一纳管

第四部分 · 选型与生产

章节	内容	关键产出
10 五方对比 · 云厂商 VM / 传统虚拟化 / 裸 KubeVirt / 容器化 / ISO 一体机	★ 14 个维度横向对比、成本模型、能力矩阵、选型决策树、混合架构与迁移路径	一张选型决策表
11 生产落地 · 容量规划与安全加固	硬件与磁盘布局、超分比、网络规划、备份容灾、监控告警指标、安全加固、交付验收清单	可交付的上线方案
12 实战案例集 · 端到端场景演练	6 个完整场景：无人值守装机、VM e2e、快照恢复竞态取证、热迁移修复、Rancher 接入、镜像内网化	可复演的案例
13 故障排查手册 · 实测案例与方法论	46 个案例索引（症状→根因→修复）、精选案例详解、14 条排障方法论	排障手册
14 运维 SOP · 巡检、升级与自动化	日/周/月巡检项、升级与回滚、扩缩容、集群重置、脚本设计约定、告警白名单	值班手册
附录 A · 命令与 CRD 速查	一页命令卡、CRD/API group 清单、kubectl 短名陷阱	贴墙速查
附录 B · 配置字段与 Helm values 速查	`config.yaml` 全字段、Helm values 关键项、VolumeSnapshotClass 参数	填空式模板

3. 30 秒速览（两条主线）

主线 A：ISO 一体机（裸金属 / 交付型）

bash

# 前置检查（不改任何状态）→ 一键部署（下载介质 → 建盘 → HTTP 引导 → 装机 → 改密 → 验证）
bash scripts/run-all.sh --preflight
setsid bash scripts/run-all.sh </dev/null >/tmp/run-all.log 2>&1 &
tail -f /tmp/run-all.log          # 全程约 42 分钟（不含 9.5GB 介质下载约 44 分钟）
bash scripts/70-verify.sh         # 9 段体检：3 节点 Ready / etcd 3 / 异常 Pod 0 / VIP 200

主线 B：容器化装进既有 K8s（叠加型）

bash

export KUBECONFIG=/etc/rancher/rke2/rke2.yaml
bash scripts/deploy-harvester.sh --nodeport 32735   # 探测 CIDR → dry-run 预检 → helm install
bash scripts/post-install.sh                        # ★ 必做；每次 helm upgrade 后都要重跑
bash scripts/healthcheck.sh                         # PASS=30 / WARN=6 / FAIL=0
bash scripts/vm-e2e-test.sh                         # 创建→冷迁移→快照→恢复→清理，全自动

4. 五种形态一句话对比

形态	你管到哪一层	一句话
公有云 IaaS（EC2/ECS/Azure VM/GCE）	只管 Guest OS	能力最全、按量付费、热迁移对你透明；但数据出域、长期成本高、无法定制底层
传统虚拟化（vSphere/OpenStack/Proxmox）	管到宿主机 OS	成熟稳定、vMotion/HA 完备；但与 K8s 两套体系，无法 GitOps 统一
裸 KubeVirt（自建在任意 K8s 上）	管到 K8s + KubeVirt	最灵活、最轻量；但 UI/镜像/网络/LB/多租户全要自己拼
Harvester 容器化（Helm 装进既有 RKE2/K8s）	管到既有 K8s	复用现有集群与 CNI，叠加虚拟化；`promote` 告知真实网段是关键
Harvester ISO 一体机（Harvester OS）	管到裸金属	装完即用、VIP+UEFI+自动提升 etcd；交付最省心，但节点 OS 不可变、定制受限

完整 14 维度对比、成本模型与决策树见 10 五方对比。

5. 能力矩阵（两套环境实测汇总）

能力	ISO 一体机	容器化（Helm on RKE2）	关键条件
部署 / API / UI	✅ VIP `https://<VIP>/`	✅ NodePort + SNI	容器化形态直连 IP 会因 SNI/Host 校验失败
节点角色与 etcd HA	✅ 自动提升 3×`control-plane,etcd`	⚠️ 取决于既有集群	`harvester-promote-node-controller`
创建 VM（RWO+Filesystem）	✅	✅	`masquerade` 接口必需；默认 SC = `harvester-longhorn`
镜像导入（HTTP/PVC/registry/blank）	✅	✅	生产勿用公网 URL（实测卡在 99.62% 回退）
冷迁移	✅	✅（`sza122100→101`，卷 `healthy`）	停机 → 改 nodeSelector → 启动
热迁移	⚠️ 需 Longhorn RWX 数据面	❌ 阻塞	KubeVirt 硬性要求所有 PVC 为 RWX
VM 快照创建	✅	✅（5~11s `readyToUse=true`）	gate = `Snapshot`（单数）
VM 快照恢复	⚠️	⚠️ 不可靠（`type: snap`）	源卷被 GC 与 full-copy 克隆竞态：4 次实测 2 失败、2 成功但卷 `degraded`
备份容灾	⚠️ 需配 backup target	⚠️ 需配 backup target	`type: bak` 是可靠恢复的前提
节点维护模式	✅	⚠️ 需改策略	默认 `Migrate` 依赖热迁移 → 用 `ShutdownAndRestartAfterEnable`
接入 Rancher	✅（`provider=harvester`，`state=active`）	✅（同理）	见 09

6. 十大铁律（血泪教训 Top 10）

KubeVirt feature gate 是 Snapshot（单数）。写成 Snapshots 时 Helm 渲染通过、--set 无报错、CR 也能 patch，但 virt-api 直接拒绝：snapshot feature gate not enabled。
改完 CR 必须滚动重启 virt-api——gate 只在进程启动时加载；建议逐个删 Pod 而非 rollout restart。
helm upgrade 会覆盖 KubeVirt CR，后加的 gate 静默失效 → 每次升级后重跑 post-install.sh，并把 gate 检查纳入巡检。
VM 磁盘只有 RWO + Filesystem（或 RWO + Block）可靠。RWX+Block 报 blockdev: Permission denied；RWX+Filesystem 依赖 share-manager/NFS。
type: snap 的恢复「控制面全绿、数据面看运气」：complete=true、readyToUse=true、DV Succeeded 都不代表 VM 能起来。恢复后必须核对 Longhorn 卷四元组：state / robustness / replicas[*].mode / cloneStatus.state。
停机用 runStrategy: Halted，不存在 Stopped 这个值；spec.running 与 runStrategy 互斥。
容器化形态的网络参数必须实测获取（clusterDNS / Pod CIDR / Service CIDR），并通过 promote 告知 Harvester，否则 kube-vip、network-controller、load-balancer 全按默认值算错路由。
ISO 形态 v1.8 起强制 UEFI，且系统盘实体必须在 NVMe/SSD：机械盘会让镜像预加载 >30 分钟，触发 chroot 内引导用 rke2 自杀 → 永久卡死。
节点 DNS 只写一个内网 DNS。并列公网 DNS 时 CoreDNS forward . /etc/resolv.conf + policy=random 会约 50% 概率把内网域名解析到公网（实测 20 次 10 次分裂）。
改「声明源」，不要改「被渲染的产物」。手写 /etc/rancher/rke2/registries.yaml 会在约 1 分钟后被控制器回收成 0 字节；正确做法是设置 containerd-registry。

7. 实测环境档案（本书全部数据的来源）

项	环境 A：ISO 一体机	环境 B：容器化
Harvester	v1.8.2	v1.8.2（chart `harvester-1.8.2`）
承载	KVM/libvirt 8.0，3 台 UEFI 虚拟机（8 vCPU `host-passthrough` + 32 GiB + `pc-q35-6.2`）	既有 RKE2 `v1.34.4-rc11+rke2r1`，3 节点 control-plane
K8s	RKE2 `v1.35.7+rke2r1`（内置）	既有 RKE2
KubeVirt / Longhorn	内置 / 内置	`1.7.4-150700.3.24.2` / `1.11.2`
CNI	Canal（内置）	Calico VXLAN
磁盘	os 250 GiB（NVMe）+ data 400 GiB（机械盘，Longhorn 默认盘）	每节点可用 ≈110 GB（`/var/lib/longhorn`）
入口	VIP `192.168.150.200`（`vip_mode: static`，kube-vip）	NodePort `32735` + SNI `harvester.local`
节点网段	`192.168.150.0/24`（`virbr10` NAT+DHCP，MAC→IP→主机名静态保留）	Pod `10.42.0.0/16`、Svc `10.43.0.0/16`、DNS `10.43.0.10`
实测结果	3 节点 `Ready control-plane,etcd`、etcd 3/3、异常 Pod 0、编排 42 分钟；已导入 Rancher（`c-vd78l`，`provider=harvester`）	巡检 PASS=30/WARN=6/FAIL=0；VM e2e 全流程通过（DV 22s→Running、冷迁移、快照 5s、恢复、清理后卷数 0）

本书所有凭据均以占位符表示（<ADMIN_PW>、<SSH_PW>、<RKE2_TOKEN>）。实验环境请遵循「Dashboard 密码与 SSH 密码故意不同值」——同值时「登录失败」这个信号会失去信息量（见 13 案例 28）。

8. 推荐阅读路径

角色	路径
初学者（想搞懂原理）	01 → 02 → 05 → 06 → 10
实施工程师（要交付集群）	02 → 03（或 04）→ 07 → 08 → 11 → 14
平台架构师（要选型）	01 → 10 → 11 → 09
值班 SRE（要救火）	13 → 附录A → 08 → 06
想复现实战（动手党）	12（6 个端到端场景，每个都有可复演命令与实测输出）

9. 配套可执行资产

书内每章都给出可直接复制的命令与 YAML；两套环境的完整脚本清单与用法：

资产	作用	幂等	见
`run-all.sh`	ISO 形态一键部署（`--preflight` / `--skip-download` / `--from <阶段>`）	✅	03
`00`~`99` 共 19 个分步脚本	下载介质、建盘、HTTP 引导、串口录制、三态域定义、生成装机配置、单节点/总编排、验证、改密、smoke VM、三层自愈、接入 Rancher	多数 ✅	03
`deploy-harvester.sh`	容器化形态一键部署（前置检查 → 探测 CIDR → dry-run 预检 → helm install → 等就绪）	✅	04
`post-install.sh`	部署后固化：默认 SC、VolumeSnapshotClass、`Snapshot` gate、滚动重启 virt-api、服务端 dry-run 探测	✅	04
`healthcheck.sh`	平台健康巡检（约 20s，只读，非零退出码可接告警）	✅	14
`vm-e2e-test.sh`	VM 端到端验证：创建 → 冷迁移 → 快照 → 恢复 → 清理（自建自清）	✅	12
`manifests/*.yaml`	VM（cirros/blank）、快照、恢复、热迁移、VolumeSnapshotClass	—	附录B

脚本设计约定（自己写运维脚本时照抄这套）：

统一 set -euo pipefail；用 kc() 封装 kubectl，自动兼容 RKE2 内置 kubectl 与 KUBECONFIG；
所有写操作幂等：apply 而非 create，annotate --overwrite，追加前先 grep -qx 判重；
关键校验不只看控制面：恢复后额外核对 Longhorn 卷 state/robustness/cloneStatus；
失败即返回非 0，并在输出里给出可直接执行的修复命令；
已知非致命噪声降级为 WARN，不计入 FAIL；
脚本本身也要被验证：首版 healthcheck.sh 曾误报 7 个 FAIL（六类取值缺陷），首版 vm-e2e-test.sh 曾因漏写 volumes: 段与 featureGates 解析错误被实测拦下——「跑过才算写完」。

10. 版本与兼容性

项	实测值	注意
Harvester	v1.8.2	v1.8 起 PXE/netboot 安装强制 UEFI，不再支持 Legacy BIOS
内置 RKE2	`v1.35.7+rke2r1`	ISO 形态自带，不可换成其他发行版
KubeVirt	`1.7.4-150700.3.24.2`	`Snapshot` gate 为 Beta（v1.3.0+），`LiveMigration` 已 GA 且不可关闭
Longhorn	1.11.2	RWX 依赖节点 NFS 客户端能力与 share-manager
节点内核	`6.12.0-160000.36-default`	Harvester OS 基于 SUSE 系（Elemental）
子 chart	cdi、harvester-load-balancer、harvester-network-controller、harvester-networkfs-manager、harvester-node-manager、kube-vip、kubevirt、kubevirt-operator、longhorn、whereabouts	容器化形态子 chart 必须齐备

11. 更新记录

日期	内容
2026-09	初版：14 章 + 2 附录，基于 v1.8.2 两套真实环境（ISO 三节点 42 分钟无人值守 + Helm on RKE2 端到端 e2e）

本书写作原则：只写跑通过的。凡是标注 ✓ 的结论都有对应的实测命令与输出；凡是标注 ❌/⚠️ 的都有根因链与取证过程；未解决的（如 ISO 形态 smoke VM 被 maxSockets 补丁路径拒绝）也如实标注为「未解决」，并给出候选修法。

Harvester 从入门到精通 · HCI 虚拟化平台实战全书 ​

1. 这本书解决什么问题 ​

2. 全书地图 ​

第一部分 · 认知与上手 ​

第二部分 · 部署实战（两种形态） ​

第三部分 · 运维精通 ​

第四部分 · 选型与生产 ​

3. 30 秒速览（两条主线） ​

主线 A：ISO 一体机（裸金属 / 交付型） ​

主线 B：容器化装进既有 K8s（叠加型） ​

4. 五种形态一句话对比 ​

5. 能力矩阵（两套环境实测汇总） ​

6. 十大铁律（血泪教训 Top 10） ​

7. 实测环境档案（本书全部数据的来源） ​

8. 推荐阅读路径 ​

9. 配套可执行资产 ​

10. 版本与兼容性 ​

11. 更新记录 ​

Harvester 从入门到精通 · HCI 虚拟化平台实战全书

1. 这本书解决什么问题

2. 全书地图

第一部分 · 认知与上手

第二部分 · 部署实战（两种形态）

第三部分 · 运维精通

第四部分 · 选型与生产

3. 30 秒速览（两条主线）

主线 A：ISO 一体机（裸金属 / 交付型）

主线 B：容器化装进既有 K8s（叠加型）

4. 五种形态一句话对比

5. 能力矩阵（两套环境实测汇总）

6. 十大铁律（血泪教训 Top 10）

7. 实测环境档案（本书全部数据的来源）

8. 推荐阅读路径

9. 配套可执行资产

10. 版本与兼容性

11. 更新记录