主题
01 · 总体方案设计
| 项目 | 内容 |
|---|---|
| 文档编号 | HV-ADMIN-DOC-01 |
| 文档名称 | Harvester 虚拟机运维管理平台 · 总体方案设计（Solution Design） |
| 版本 | v0.1（初稿，待评审） |
| 状态 | 待评审 |
| 作者 | 架构组 |
| 评审人 | 产品、K8s 专家、K8s 运维、服务器运维、网络运维、应用运维、监控中心、CMDB |
| 关联文档 | 02-需求规格说明书、03-数据模型与接口设计、04-角色分工与风险 |
修订记录
| 版本 | 日期 | 修订人 | 说明 |
|---|---|---|---|
| v0.1 | 2026-09-07 | 架构组 | 初稿 |
1. 背景与问题定义
1.1 现状
公司已上线 Harvester 超融合平台（Kubernetes + KubeVirt + Longhorn），承载业务虚拟机。目前虚拟机的创建、变更、迁移、备份等操作主要依赖 Harvester 原生 UI + kubectl + 人工工单，运维团队（服务器/网络/K8s/应用）与研发团队之间通过 IM、邮件、Excel 台账协作。
1.2 痛点
| # | 痛点 | 现状表现 | 业务影响 | 量化现状（待各组补充实际值） |
|---|---|---|---|---|
| P1 | VM 交付慢、纯人工 | 研发提工单 → 应用运维确认规格 → K8s 运维在 UI 建机 → 网络运维配 IP → 回填台账 | 交付周期长，紧急扩容响应不及时 | 平均 ~1-3 个工作日 |
| P2 | 无「一键创建」模板 | 每台机器手工填 CPU/内存/镜像/网络/cloud-init，参数不一致 | 规格漂移、初始化脚本缺失、故障排查困难 | 规格组合 30+ 种，无标准 |
| P3 | 静态 IP 人工管理 | Excel/网管台账记录，手工写 cloud-init 或 DHCP 保留 | IP 冲突、回收不及时、跨网段混乱 | 冲突事件 ？次/季度 |
| P4 | 归属不清 | VM 上无「研发负责人工号 / 部门负责人工号 / 服务名」标识 | 故障找不到人、无法按部门核算成本、无法治理僵尸机器 | 元数据完整率 ？% |
| P5 | 备份无策略、无验证 | 手工点备份，或根本没有；无保留策略、无恢复演练 | 数据丢失风险、审计不合规 | 备份覆盖率 ？% |
| P6 | 热迁移靠人肉判断 | 宿主机维护前逐台判断能否迁移、手工触发、无进度跟踪 | 维护窗口拉长、迁移失败影响业务、批量维护风险高 | 单台宿主机排空 ~？小时 |
| P7 | CMDB 与实际不一致 | 台账与集群实际状态脱节，靠人工月度对账 | 资产盘点失真、审计问题 | 差异率 ？% |
| P8 | 操作无审计闭环 | 谁在什么时候删了/改了哪台机器，难追溯 | 合规风险、故障定责困难 | 审计覆盖率 低 |
| P9 | 多集群割裂 | 多个 Harvester 集群各自登录，无统一视图与配额 | 容量看不清、跨集群调度无从下手 | 集群数 ？ |
| P10 | 高危操作无管控 | 生产 VM 可被误删/误覆盖恢复 | 重大故障风险 | — |
1.3 建设目标
| 目标 | 度量指标（验收基线） |
|---|---|
| 交付提效 | 标准 VM 交付从「工单级（小时/天）」降到「自助级（≤5 分钟下发，≤15 分钟可用）」 |
| 一键创建 | ≥90% 新建 VM 通过模板一键创建，规格标准化率 100% |
| 静态 IP 零冲突 | 平台分配 IP 冲突事件 = 0；IP 使用率可视、可回收 |
| 归属完整 | 研发负责人工号、部门负责人工号、服务名 三项元数据完整率 ≥ 98% |
| 备份合规 | 生产 VM 备份策略覆盖率 100%，备份成功率 ≥ 99%，季度恢复演练 100% 通过 |
| 迁移可控 | 宿主机排空（批量迁移）平均耗时下降 ≥ 50%，迁移失败自动告警并给出原因 |
| 数据一致 | 平台 ↔ CMDB ↔ 集群实际状态 差异率 ≤ 1%，每日自动对账 |
| 操作可审计 | 变更类操作审计覆盖率 100%，高危操作 100% 经审批 |
1.4 设计原则
- Kubernetes/Harvester 为唯一事实源（Single Source of Truth for Runtime）：运行态（是否存在、是否运行、在哪台宿主机、实际 IP）一律以集群为准；平台数据库只做缓存 + 业务元数据，任何时候可重建。
- 平台无侵入：不修改 Harvester 组件、不引入自定义 CRD 到业务集群（Phase 1/2）；平台宕机不影响 Harvester 原生 UI/kubectl 的使用。
- 幂等 + 可重放 + 可回滚：所有编排动作具备幂等键（idempotency-key），失败可续跑或回滚；长流程用状态机而非同步阻塞。
- 最小权限：每个集群一个受限 ServiceAccount，按动词/资源白名单授权；高危操作（删除、覆盖恢复）二次确认 + 审批 + 强制快照。
- 审计优先：先记审计再执行操作；审计含操作前后 diff。
- 版本兼容：以「能力探测（capability probe）」替代硬编码版本判断，兼容 Harvester v1.2 ~ v1.8 的差异（详见 §4.4）。
- 元数据回标：业务元数据同时写入 VM 的 labels/annotations，使 kubectl/Harvester UI 侧也能看到归属信息，避免「只有平台知道」。
- 先 MVP 后运营：Phase 1 打通「看得见 + 建得出 + 记得住」，Phase 2 打通「迁得动 + 备得住 + IP 管得住」，Phase 3 做「运营与多集群」。
2. 名词与术语
| 术语 | 说明 |
|---|---|
| Harvester | SUSE/Rancher 开源超融合（HCI）平台：Elemental OS + Kubernetes + KubeVirt（虚拟化）+ Longhorn（分布式存储）+ Multus/Bridge（网络）+ Prometheus/Grafana（监控） |
| KubeVirt | Kubernetes 上的虚拟机管理组件，提供 VirtualMachine 等 CRD |
| VM / VMI | kubevirt.io/v1 VirtualMachine（虚机定义，含运行策略）/ VirtualMachineInstance（运行中的实例，含节点、IP、迁移状态） |
| VMIM | kubevirt.io/v1 VirtualMachineInstanceMigration，热迁移任务对象 |
| NAD | k8s.cni.cncf.io/v1 NetworkAttachmentDefinition，Harvester 中的「VM Network」（VLAN/Untagged） |
| mgmt 网络 | Harvester 内置管理网络（Canal/Calico+Flannel overlay），IP 重启后会变、仅集群内可达 |
| backup-target | Harvester 备份目标（NFS 或 S3），全局 Setting，未配置则无法备份 |
| VM Backup / Restore | harvesterhci.io/v1beta1 VirtualMachineBackup / VirtualMachineRestore |
| VM 快照 | Harvester 基于卷快照的 VM Snapshot（版本相关，v1.2+） |
| IPAM | IP Address Management，本方案指平台自建的 IP 地址台账/分配/回收模块 |
| cloud-init | 虚机首次启动初始化机制，本平台用它注入 hostname、SSH Key、用户、网络配置（静态 IP） |
| qemu-guest-agent | 虚机内代理，提供文件系统冻结（备份一致性）、动态 SSH Key 注入、网卡/IP 上报能力 |
| 工号（empno） | 公司员工唯一编号，本方案作为「研发负责人」「部门负责人」的关联主键 |
| CMDB | 配置管理数据库，公司资产与配置权威台账 |
3. 范围
3.1 本期范围（In Scope）
| 域 | 能力 |
|---|---|
| 集群纳管 | 多 Harvester 集群注册、连通性健康检查、能力探测、节点/宿主机视图、存储与网络资源视图、镜像与 SSH Key 视图 |
| 虚拟机管理 | 列表/检索/详情/YAML/事件/状态历史；创建（单台、批量、模板一键创建）、编辑配置、克隆、删除（软删除+保护）、电源操作（启动/停止/强制停止/重启）、控制台（VNC/Serial）跳转或代理 |
| 热迁移 | 单台迁移、批量迁移、可迁移性预检、进度跟踪、失败原因归类、宿主机维护排空编排、迁移窗口与并发限流 |
| 备份恢复 | 手动备份、定时备份策略（Cron/保留数/失败熔断）、VM 快照、恢复为新 VM、覆盖恢复原 VM、恢复演练记录、备份容量与成功率看板 |
| 网络与 IP | 网段/VLAN 台账、IPAM（分配/保留/回收/冲突检测）、MAC 分配、静态 IP 注入（cloud-init）、IP 与 CMDB/DNS 联动（P1） |
| 元数据 | 研发负责人工号、部门负责人工号、所属服务名、环境、成本中心、应用 ID、业务等级、自定义标签；批量编辑、变更历史、完整率报表 |
| 集成 | 统一身份认证（LDAP/OIDC）、CMDB 双向同步与对账、Prometheus/Grafana、告警平台、企微/钉钉/邮件通知、工单/OA 审批 |
| 治理能力 | RBAC + 数据权限 + 配额、审批流、全量审计、报表看板、开放 API/Webhook |
3.2 不在本期范围（Out of Scope）
见 02-需求规格说明书.md §4.2。要点：容器负载管理、Harvester 安装与升级、Longhorn 底层运维、Guest OS 内部配置管理、计费结算、VMware/OpenStack 纳管、AIOps。
3.3 关键约束与应对
| 约束 | 说明 | 设计应对 |
|---|---|---|
| 只读优先、写操作受控 | 平台不得随意改写非自己创建的资源 | 资源打「管理者标记」ops.example.com/managed-by=harvester-admin；未纳管资源默认只读 + 显式「接管」动作 |
| 版本差异 | Harvester v1.2 ~ v1.8 能力不同（快照、原生定时备份、Managed DHCP、CPU/内存热插拔、NIC 热插拔等） | 能力探测 + feature flag + 降级提示（§4.4） |
| mgmt 网络 IP 不固定 | Harvester 管理网络为 overlay（Canal/Calico+Flannel），VM 重启后 mgmt IP 会变，且默认仅集群内可达 | 静态 IP 一律落在 VLAN/Untagged VM Network；平台展示的「业务 IP」= VLAN 网卡 IP |
| 双网卡默认路由陷阱 | 同时接 mgmt 与 VLAN 时，VLAN 网关会覆盖默认路由，导致节点侧访问不到 mgmt IP | 模板中明确「主网卡 + 默认路由」策略；文档与告警提示；必要时只保留 VLAN 网卡 |
| 备份仅支持 Longhorn 卷 | 外部存储卷无法备份 | 创建时校验卷的 StorageClass，非 Longhorn 卷给出「不可备份」警示 |
| 静态 IP 依赖 Guest OS | 需镜像内置 cloud-init；用户后续可在 OS 内改网络 | IPAM 记录「期望 IP」，周期比对「实测 IP」（guest agent 上报/探测），差异告警 |
| 内网离线 | 无公网 | 依赖离线镜像仓库；文档/告警/通知全部内网 |
4. Harvester 能力基线（技术底座）
4.1 Harvester 架构要点
Harvester 是基于 Kubernetes 的超融合平台：Elemental（不可变 OS）+ Kubernetes + KubeVirt（KVM 虚拟化）+ Longhorn（分布式块存储）+ Multus/Bridge CNI（VM 网络）+ Prometheus/Grafana（监控）。虚拟机的全部能力都以 CRD（自定义资源） 暴露在 kube-apiserver 上。因此「管理平台」的本质是：面向 CRD 的编排 + 业务元数据 + 流程治理，而不是重新实现虚拟化。
4.2 平台会用到的关键对象（CR）
| 能力 | API Group / Kind | 简称 | 平台用途 | 读/写 |
|---|---|---|---|---|
| 虚机定义 | kubevirt.io/v1 VirtualMachine | vm | 增删改查、启停（spec.running / spec.runStrategy）、规格、磁盘、网卡、cloud-init、调度约束、labels/annotations | R/W |
| 虚机实例 | kubevirt.io/v1 VirtualMachineInstance | vmi | 运行态：所在节点 status.nodeName、status.phase、网卡与 IP status.interfaces[].ipAddress(es)、status.migrationState、guest agent 信息 | R |
| 热迁移 | kubevirt.io/v1 VirtualMachineInstanceMigration | vmim | 触发迁移、跟踪 status.phase（Pending/Scheduling/Running/Succeeded/Failed）、中止迁移 | R/W |
| 数据卷导入 | cdi.kubevirt.io/v1beta1 DataVolume | dv | 镜像导入/克隆产生的卷状态跟踪 | R |
| 持久卷声明 | core/v1 PersistentVolumeClaim | pvc | 磁盘容量、扩容、StorageClass | R（扩容 W） |
| VM 备份 | harvesterhci.io/v1beta1 VirtualMachineBackup | vmbackup | 手动/定时备份；状态 status.readyToUse、status.phase | R/W |
| VM 恢复 | harvesterhci.io/v1beta1 VirtualMachineRestore | vmrestore | 恢复为新 VM / 覆盖原 VM | R/W |
| VM 快照 | harvesterhci.io/v1beta1 VolumeSnapshot（版本相关） | volumesnapshot | 删除前强制快照、恢复点 [PoC 验证] | R/W |
| VM 镜像 | harvesterhci.io/v1beta1 VirtualMachineImage | vmimage | 镜像清单、可用性、大小、来源 | R |
| VM 模板 | harvesterhci.io/v1beta1 VirtualMachineTemplate / ...TemplateVersion | vmtemplate | 复用 Harvester 原生模板（可选） | R/W |
| SSH Key | harvesterhci.io/v1beta1 SSHKey（Namespaced Key Pair） | sshkey | 注入密钥清单 | R/W |
| VM 网络 | k8s.cni.cncf.io/v1 NetworkAttachmentDefinition | nad | VLAN/Untagged 网络清单、VLAN ID、MTU | R |
| 集群网络 | network.harvesterhci.io/v1beta1 ClusterNetwork（版本相关） | — | 上联网卡与 VLAN 能力 | R |
| LB 地址池 | networking.harvesterhci.io/v1beta1 IPPool | ippool(lb) | 仅用于 Harvester 负载均衡 VIP，不用于 VM 静态 IP（易混淆点，见 §6.4） | R |
| 托管 DHCP | network.harvesterhci.io/v1alpha1 IPPool + VirtualMachineNetworkConfig | ippool(dhcp) / vmnetcfg | 实验性 addon：为无 DHCP 的 VLAN 网络按 MAC→IP 提供固定租约 [PoC 验证] | R/W |
| 节点 | core/v1 Node | node | 宿主机容量水位、可调度状态（cordon）、标签 | R（cordon W） |
| 全局设置 | harvesterhci.io/v1beta1 Setting | setting | backup-target、overcommit-config 等（只读展示） | R |
| 事件 | core/v1 Event | event | 故障诊断、时间线 | R |
⚠️ 上表的 API Group / 字段名以实际集群 CRD为准，Phase 0 用
kubectl api-resources、kubectl explain逐一校验（见00§7 PoC-01）。字段级映射见03§5。
4.3 平台接入方式选型
| 方案 | 说明 | 优点 | 缺点 | 结论 |
|---|---|---|---|---|
| A. kube-apiserver + CRD | 用 client-go / kubernetes-python-client 直接读写 KubeVirt、Harvester CR，支持 watch | 语义稳定（跨 Harvester 版本变化小）、支持增量 watch、RBAC 精细、支持 dry-run/Server-Side Apply、生态成熟 | 需自行组装 YAML、需处理 resourceVersion 冲突 | ✅ 主方案 |
B. Harvester HTTP API（Steve 风格 /v1/harvester/<type>/<ns>/<name>，Basic/Bearer 认证） | Harvester UI 使用的 API 层 | 与 UI 行为一致；部分「动作型」接口开箱即用（如控制台代理） | 属 UI 内部接口，跨版本兼容性弱；账号体系与 Harvester 用户耦合 | ⚠️ 补充方案：仅用于 VNC/Serial 控制台代理等 A 难覆盖的场景 |
| C. Harvester Terraform Provider | harvester_virtualmachine 等资源块 | 声明式、可版本化 | 面向 IaC 批处理，不适合交互式高频操作与状态回读；state 管理复杂 | ❌ 不作主链路；可作为批量导入旁路工具（P2） |
| D. 自研 Operator（Go + controller-runtime） | 平台 CRD + 控制器调谐 | 云原生、自愈能力强 | 需在业务集群安装 CRD 与控制器（违背「无侵入」）；团队 Go 储备成本 | ⏭ Phase 3 评估：多集群/大规模自愈需求强烈时再引入 |
结论：Phase 1/2 采用 A 为主、B 为辅；写操作统一遵循五步法：期望态生成 → 服务端校验（dry-run）→ 提交（带 resourceVersion 乐观锁）→ watch 回执 → 状态回写 + 审计。
4.4 版本兼容矩阵（需在 PoC-01 用实际集群校正）
| 能力 | v1.1 | v1.2 | v1.3 | v1.4 | v1.5+ | v1.8 | 平台策略 |
|---|---|---|---|---|---|---|---|
| VM CRUD / 启停 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 全版本支持 |
| 热迁移（VMIM） | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 全版本支持；进度可见性按版本降级 |
| VM 备份/恢复（NFS/S3） | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 需 backup-target；仅 Longhorn 卷 |
| VM 快照（卷快照） | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | 能力探测；不支持则隐藏入口 |
| 原生定时备份/快照（VM Schedules：Cron/Retain/Max Failure） | ❌ | ❌ | ❌ | 部分 | ✅ | ✅ | 默认用平台内置调度器；原生可用时可选「下发原生 Schedule」模式 [PoC-13] |
| TPM 设备 | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | 表单按能力显示 |
| CPU/内存热插拔 | ❌ | ❌ | ❌ | 部分 | ✅ | ✅ | 能力探测；不支持走「改配置 + 重启」 |
| 网卡 / CD-ROM 热插拔 | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | 能力探测 |
| Managed DHCP addon（MAC→IP 固定租约） | ❌ | ❌ | ❌ | 实验 | 实验 | 实验 | 默认不依赖；作为静态 IP 可选实现 [PoC-07] |
| CloudInit CRD addon | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | 可选：集中管理 cloud-init 模板 |
| Kube-OVN overlay / VPC | ❌ | ❌ | ❌ | ❌ | 部分 | 实验 | 若现网用 overlay：静态 IP 需改用 Kube-OVN 子网 DHCP/保留（§6.4 方案对比） |
能力探测实现：启动时 + 定时（默认 10 分钟）对每个集群执行
api-resources与关键 CRD 存在性检查、只读Setting检查（如 backup-target 是否配置），结果写入cluster.capabilities（jsonb）。前端按能力位控制入口可见性（灰显 + 原因提示），避免出现「点了报错」的体验。