03 · 数据模型与接口设计

项目	内容
文档编号	HV-ADMIN-DOC-03
文档名称	Harvester 虚拟机运维管理平台 · 数据模型与接口设计
版本	v0.1（初稿，待评审）
关联文档	01-总体方案设计、02-需求规格说明书
约定	数据库 PostgreSQL 14+；ORM SQLAlchemy 2.x（async）+ Alembic 迁移；时间统一 UTC 存储、前端按本地时区展示；主键 id BIGSERIAL，业务唯一键单独索引；所有表含 created_at/updated_at/created_by/updated_by；软删除用 deleted_at

---

1. 数据模型总览（ER）

erDiagram
    CLUSTER ||--o{ NODE : has
    CLUSTER ||--o{ VM : hosts
    CLUSTER ||--o{ VM_NETWORK : defines
    CLUSTER ||--o{ STORAGE_CLASS : defines
    CLUSTER ||--o{ OS_IMAGE : has
    CLUSTER ||--o{ SSH_KEY : has
    VM ||--o{ VM_NIC : has
    VM ||--o{ VM_VOLUME : has
    VM ||--o{ VM_STATUS_HISTORY : has
    VM ||--o{ VM_EVENT : has
    VM ||--o| VM_META : described_by
    VM ||--o{ TASK : operated_by
    VM ||--o{ BACKUP_RECORD : backs_up
    VM ||--o{ MIGRATION_TASK : migrates
    VM }o--|| SERVICE : belongs_to
    SERVICE }o--|| EMPLOYEE : owner_emp
    DEPARTMENT ||--o{ EMPLOYEE : contains
    DEPARTMENT }o--|| EMPLOYEE : head_emp
    SUBNET ||--o{ IP_ADDRESS : contains
    VM_NIC }o--o| IP_ADDRESS : binds
    BACKUP_POLICY ||--o{ BACKUP_RECORD : schedules
    VM_TEMPLATE ||--o{ VM : instantiates
    USER ||--o{ USER_ROLE : has
    ROLE ||--o{ USER_ROLE : granted
    ROLE ||--o{ ROLE_PERMISSION : has
    USER ||--o{ AUDIT_LOG : performs
    USER ||--o{ APPROVAL : approves
    TASK ||--o{ AUDIT_LOG : logs
    TASK ||--o{ TASK_STEP : contains

1.1 表分组

分组	表	说明
集群与资源	cluster, cluster_credential, node, vm_network, storage_class, os_image, ssh_key, vm_template, spec_flavor	纳管对象的缓存与平台侧定义
虚拟机	vm, vm_nic, vm_volume, vm_meta, vm_status_history, vm_event, vm_pending_change	虚机主数据与运行态缓存
IPAM	subnet, ip_address, ip_lease_history, mac_pool	网段、地址、租约、MAC 分配
任务编排	task, task_step, task_idempotency	工作流实例、步骤、幂等键
备份迁移	backup_policy, backup_record, restore_record, snapshot_record, migration_task, node_drain_plan	备份/恢复/快照/迁移/排空
组织与归属	department, employee, service, service_owner_history, cost_center	组织架构、工号、服务目录
权限审计	user, role, permission, user_role, role_permission, data_scope, approval_flow, approval_instance, audit_log	RBAC、数据权限、审批、审计
集成	cmdb_ci_mapping, cmdb_sync_job, cmdb_diff, webhook_subscription, notification_record, prometheus_datasource	CMDB、通知、Webhook、监控
系统	sys_config, sys_dict, quota, quota_usage, sync_job, scheduled_job, feature_flag, api_token	配置、字典、配额、定时任务

---

2. 核心表结构

仅列出关键字段；完整 DDL 在开发阶段以 Alembic 迁移脚本为准。类型使用 PostgreSQL 语法。

2.1 cluster — Harvester 集群

字段	类型	约束	说明
id	bigserial	PK
code	varchar(64)	UK, not null	集群唯一编码，如 hv-prod-01
name	varchar(128)	not null	展示名
env	varchar(16)	not null	prod/pre/test/dev
api_server	varchar(255)	not null	kube-apiserver 地址
harvester_version	varchar(32)		探测到的 Harvester 版本
kubevirt_version	varchar(32)		探测到的 KubeVirt 版本
capabilities	jsonb	default '{}'	能力探测结果：{"backup":true,"snapshot":true,"native_schedule":false,"managed_dhcp":false,"cpu_hotplug":false}
backup_target_type	varchar(16)		nfs / s3 / none
backup_target_ready	boolean	default false
default_namespace	varchar(64)	default 'default'
sync_status	varchar(16)		online/offline/error
last_sync_at	timestamptz		最近一次全量对账时间
node_count / vm_count	int		缓存计数（看板用）
status	varchar(16)	default 'active'	active/disabled/maintenance
remark	text

索引：uk_cluster_code(code)、idx_cluster_env(env)、idx_cluster_sync(sync_status, last_sync_at)

2.2 cluster_credential — 集群凭据（加密存储）

字段	类型	说明
id	bigserial	PK
cluster_id	bigint	FK → cluster.id
auth_type	varchar(16)	kubeconfig / serviceaccount_token / harvester_api_key
kubeconfig_cipher	bytea	AES-GCM 加密的 kubeconfig（密钥托管 KMS/Vault）
sa_namespace	varchar(64)	ServiceAccount 所在命名空间
token_ref	varchar(255)	指向 K8s Secret 的引用（ns/name#key），推荐方式：不落库明文
tls_ca_cipher	bytea	CA 证书
insecure_skip_verify	boolean	default false
expires_at	timestamptz	凭据过期时间（用于到期提醒）
last_verified_at	timestamptz	最近一次连通性校验时间

安全要求：凭据禁止明文入库；优先使用「集群内 ServiceAccount + token 引用」方式；解密只在内存中，禁止打印日志。

2.3 node — 宿主机（缓存自 K8s Node）

字段	类型	说明
id / cluster_id	bigserial / bigint	PK / FK
name	varchar(128)	节点名，UK(cluster_id, name)
hostname / ip	varchar(128)	管理 IP
roles	varchar(64)	如 control-plane,worker
status	varchar(16)	Ready / NotReady / SchedulingDisabled
unschedulable	boolean	cordon 状态
harvester_version	varchar(32)	节点 Harvester 版本（label 探测）
cpu_total_milli / cpu_allocatable_milli / cpu_requested_milli	int	CPU 总量 / 可分配 / 已被 requests 占用
mem_total_mi / mem_allocatable_mi / mem_requested_mi	bigint	内存（Mi）
storage_total_bytes / storage_available_bytes	bigint	Longhorn 容量
vm_count	int	承载 VM 数
disk_info	jsonb	[{"name":"nvme0n1","path":"/dev/nvme0n1","size":1099511627776,"storageClass":"longhorn-xxx","state":"active"}]
networks	jsonb	该节点参与的 Cluster Network / VLAN
labels / annotations / conditions	jsonb	原样缓存（调度约束分析、健康判断）
maintenance_mode	boolean	平台侧维护标记
last_sync_at	timestamptz

索引：uk_node(cluster_id,name)、idx_node_status(cluster_id,status)、idx_node_maint(maintenance_mode)

2.4 vm — 虚拟机主表（核心）

字段	类型	说明
id	bigserial	PK
cluster_id	bigint	FK
namespace	varchar(64)	K8s 命名空间
name	varchar(63)	VM 名（DNS-1123）；UK(cluster_id, namespace, name)
display_name	varchar(128)	展示名
description	text	描述（可同步到 CR 注解，如 field.cattle.io/description [PoC 验证]）
uid	varchar(64)	K8s 对象 UID（识别「同名重建」）
resource_version	varchar(32)	乐观锁
managed_by	varchar(32)	harvester-admin / external（是否平台接管）
power_state	varchar(16)	Running/Stopped/Starting/Stopping/Migrating/Error/Unknown（映射 vm.status.printableStatus）
run_strategy	varchar(24)	Always/RerunOnFailure/Manual/Halted/Once
spec_running	boolean	spec.running
cpu_cores	int	vCPU
memory_mi	bigint	内存（Mi）
machine_type	varchar(16)	q35 / pc
os_type / os_distro / os_version	varchar	linux/windows、ubuntu/22.04
guest_agent_ready	boolean	qemu-guest-agent 是否可用
node_name / node_ip	varchar	当前宿主机（来自 VMI status.nodeName）
hostname	varchar(128)	Guest 内 hostname
mgmt_ip	varchar(64)	管理网 IP（易变，仅参考）
primary_ip	varchar(64)	业务主 IP（VLAN 网卡，权威展示字段）
primary_mac	varchar(32)	主网卡 MAC（平台分配或集群生成）
ip_source	varchar(16)	platform_static / manual_static / dhcp / none
ip_confirmed	boolean	是否已实测确认（guest agent / 探测）
disk_total_gib / volume_count / nic_count	int/smallint
image_id / template_id / flavor_code		源镜像、创建模板、规格族
service_id	bigint	FK → service（所属服务）
env	varchar(16)	prod/pre/test/dev
business_tier	varchar(8)	T0/T1/T2/T3
cost_center / app_id	varchar	成本中心、应用 ID
owner_empno	varchar(32)	研发负责人工号
dept_head_empno	varchar(32)	部门负责人工号
department_id	bigint	冗余部门，便于按部门统计
tags	jsonb	自定义标签
labels / annotations	jsonb	CR 上的原始 labels/annotations 缓存
cmdb_ci_id	varchar(64)	CMDB CI 唯一标识
cmdb_sync_status	varchar(16)	synced/pending/conflict/error
cmdb_synced_at	timestamptz
backup_enabled	boolean	是否纳入备份策略
last_backup_at / last_backup_status
migration_state	varchar(16)	none/in_progress/succeeded/failed
protection_level	varchar(16)	none/soft（软删除保护）/hard（禁止删除）
pending_change	boolean	是否存在「待重启生效」的配置变更
created_at_cluster	timestamptz	CR 的 creationTimestamp
last_sync_at / deleted_at	timestamptz	同步时间 / 软删除

索引：uk_vm(cluster_id,namespace,name)、idx_vm_uid(uid)、idx_vm_owner(owner_empno)、idx_vm_dept(department_id)、idx_vm_service(service_id)、idx_vm_state(power_state)、idx_vm_ip(primary_ip)、idx_vm_node(cluster_id,node_name)、idx_vm_env_tier(env,business_tier)、GIN idx_vm_tags(tags)

2.5 vm_nic — 网卡

字段	类型	说明
id / vm_id	bigserial / bigint	PK / FK
interface_name	varchar(64)	CR 中 interfaces[].name，如 nic-1
network_name	varchar(128)	mgmt 或 namespace/vlan-name
nad_uid	varchar(64)	关联 NAD
model	varchar(16)	virtio / e1000 / sata
mac_address	varchar(32)	平台分配或自动生成
mac_source	varchar(16)	platform / auto
ip_address	varchar(64)	集群上报 IP（VMI status）
ip_addresses	jsonb	多 IP 列表
ip_expected	varchar(64)	IPAM 分配的期望 IP
ip_mode	varchar(16)	static / dhcp
netmask_prefix	smallint	CIDR 前缀长度
gateway / dns_servers	varchar / jsonb
is_primary	boolean	是否业务主网卡
queue_count / pci_address	int / varchar	高级参数
reported_at	timestamptz	IP 上报时间

索引：idx_nic_vm(vm_id)、idx_nic_ip(ip_address)、idx_nic_mac(mac_address)

2.6 subnet / ip_address / ip_lease_history / mac_pool — IPAM

subnet（网段，网络运维维护，权威）

字段	类型	说明
id	bigserial	PK
cluster_id	bigint	可空：全局网段（跨集群）
name	varchar(64)	如 prod-vlan100
cidr	cidr	192.168.100.0/24
vlan_id	int	关联 VLAN
nad_ref	varchar(128)	关联 VM Network ns/name（决定该网段可用于哪些集群/命名空间）
gateway	varchar(64)
dns_servers / domain_search / ntp	jsonb
mtu	int
usable_start / usable_end	inet	可分配范围（不含网关/保留）
reserved_ranges	jsonb	[{"start":"192.168.100.1","end":"192.168.100.20","reason":"网络设备"}]
env / department_id	varchar / bigint	归属（数据权限）
ip_version	smallint	4 / 6
allow_dhcp_fallback	boolean	是否允许 DHCP
status	varchar(16)	active / frozen / deprecated
usage_percent_cache	numeric(5,2)	使用率缓存

ip_address（一 IP 一行）

字段	类型	说明
id / subnet_id	bigserial / bigint
ip	inet	UK(subnet_id, ip)
status	varchar(16)	free / allocated / reserved / conflict / released_pending
allocate_type	varchar(16)	auto / manual / import（存量导入）/ system（网关等）
vm_id / vm_nic_id	bigint	占用者
mac_address	varchar(32)	绑定 MAC（Managed DHCP 场景与冲突定位）
service_id / owner_empno / department_id		冗余归属，便于「按 IP 找人」
dns_record	varchar(255)	DNS 记录名（P1 联动）
cmdb_ci_id	varchar(64)
allocated_at / released_at / allocated_by / released_by
conflict_detail	jsonb	发现时间、涉事对象、探测方式
last_seen_at	timestamptz	最近一次「实测在用」时间
remark	text

ip_lease_history（append-only）：id, ip_address_id, ip, action(allocate/release/change/conflict), from_vm_id, to_vm_id, operator, reason, task_id, created_at

mac_pool：id, subnet_id, mac_prefix(如 52:54:00), seq, mac_address(UK), vm_nic_id, status, created_at

MAC 前缀建议使用 KVM OUI 52:54:00，后 3 字节由平台按 hash(cluster+subnet+seq) 生成并落库，避免与既有设备冲突。创建时固定 MAC 是静态 IP 方案（尤其 Managed DHCP）的关键前置。

2.7 vm_volume — 磁盘

字段	类型	说明
id / vm_id	bigserial / bigint
volume_name	varchar(64)	CR volumes[].name，如 disk-0
type	varchar(16)	image（镜像卷）/ container（容器盘）/ cdrom / pvc
pvc_name / storage_class	varchar
size_gib	int
bus	varchar(16)	virtio / sata / scsi
boot_order	smallint
image_id	bigint	源镜像
is_longhorn	boolean	决定「是否可备份」
backing_up	boolean
status	varchar(16)	bound / pending / lost
hotplugged	boolean	是否热挂载

2.8 vm_meta / vm_status_history / vm_event

vm_meta（元数据扩展，与 vm 1:1；变更历史入 vm_meta_history）

字段	说明
vm_id	FK
owner_empno / owner_name / owner_email / owner_phone	研发负责人工号 + 姓名等快照（来自 employee，冗余便于展示与历史留存）
dept_head_empno / dept_head_name	部门负责人工号 + 姓名
department_id / department_path	部门与全路径，如 技术中心/交易中台部/订单组
service_id / service_name / service_code	所属服务
backup_owner_empno	备份/运维负责人（可选）
cost_center / app_id / business_tier / project_code
vip_flag	是否重保（大促/监管）
data_classification	数据密级（公开/内部/机密）
meta_source	platform / cmdb / manual / import
verified_at / verified_by	元数据确认时间与确认人（治理用）

vm_meta_history：id, vm_id, field, old_value, new_value, changed_by, changed_at, reason, source(platform/cmdb/batch_import), task_id

vm_status_history：id, vm_id, power_state, node_name, primary_ip, resource_version, observed_at, source(watch/poll/reconcile) — 状态时间线与容量趋势。

vm_event：id, vm_id, cluster_id, event_type(Normal/Warning), reason, message, count, first_ts, last_ts, source_component, involved_kind, involved_name — 缓存 K8s Event，供详情页时间线与告警关联。