设计以 Proxmox VE 为 backend 的北向 VM 生命周期 API #46

New Issue

2026-09-10T15:47:21Z

panxiao81 commented

2026-09-10 15:47:21 +00:00

背景

PVE 提供了成熟的 QEMU/KVM、存储、迁移、HA 与集群能力，但北向 API 抽象不完整，部分官方操作仍要求 SSH 到节点使用 qm、pvesh 或修改 pmxcfs 配置。典型例子是 args 等配置被写死为 root@pam，OIDC/AD 主要只能用于 UI 登录，难以形成可用的机器身份和完整 RBAC。现有 floppy web UI 已经证明：在可信 PVE 节点上通过 pvesh/qm 可以跨节点代理并补齐原生 API 缺口。

目标不是重新实现 hypervisor，而是将 PVE 作为计算 backend，建立独立、headless 的 VM 生命周期与授权控制面。相当于把最难的虚拟化、存储和迁移能力外包给 PVE，同时架空其不足的北向管理面。

设计原则

优先复用 PVE 原生能力；只有原生平面无法可靠表达的功能才越过 API
daemon 运行在受信任的 PVE 节点或独立控制区，通过 qm、pvesh 和受控 pmxcfs 写入执行操作
北向调用者永远不获得节点 root 或通用 PVE token
所有操作经过自有 IAM/RBAC、幂等键、审计和策略校验
将长期声明式基础设施与 CI 产生的短命实例分开：OpenTofu 管长期对象，controller 管临时生命周期
保留 PVE UI/API/SSH 作为 break-glass，不使集群恢复依赖新控制面

第一批用例

从版本化 cloud image/golden template 创建临时 Gitea Actions runner
注入 Cloud-Init、QEMU Guest Agent 或未来 vsock bootstrap 数据
管理原生 API 难以覆盖的 QEMU args、serial、vsock 和 PCI passthrough
job 完成、TTL 到期或 controller 崩溃恢复后回收实例
查询 VM 实际状态、任务进度、节点、存储和迁移结果

最小资源模型

Instance：稳定 UUID、PVE VMID、generation、owner/project、backend、desired/observed state
Image：来源、构建版本、校验值、兼容能力
Flavor/Resource：vCPU、RAM、磁盘、网络、GPU/PCI capability
Network attachment 与 storage attachment
Service account binding、TTL、lease 与幂等 request ID
Operation：异步状态、错误、重试与审计记录

必须解决的问题

多节点 daemon 的 leader/locking 模型，避免重复执行
PVE task UPID 与自有 operation 状态的映射
VMID 复用与 instance generation 防混淆
pmxcfs 写入和 qm/pvesh 调用的最小权限边界
migration、HA、备份、删除、孤儿资源和部分失败的协调
节点离线时的 reconciliation 行为
PVE 升级造成 CLI/配置格式变化时的兼容测试
API 的 project RBAC、quota、lease 与审计

分阶段交付

整理现有 floppy 工具，拆出 PVE command adapter 与只读 inventory
实现单实例 create/get/delete 和异步 operation
接入 Gitea workflow job，完成 ephemeral runner 闭环
加入 lease/garbage collection、RBAC 和 OpenBao bootstrap
再评估 migration、HA、PCI/vsock 与多 backend 调度

本 issue 不要求 fork 或 patch PVE，也不以完全替代 PVE 管理面为第一阶段目标。

## 背景 PVE 提供了成熟的 QEMU/KVM、存储、迁移、HA 与集群能力，但北向 API 抽象不完整，部分官方操作仍要求 SSH 到节点使用 `qm`、`pvesh` 或修改 pmxcfs 配置。典型例子是 `args` 等配置被写死为 `root@pam`，OIDC/AD 主要只能用于 UI 登录，难以形成可用的机器身份和完整 RBAC。现有 floppy web UI 已经证明：在可信 PVE 节点上通过 `pvesh`/`qm` 可以跨节点代理并补齐原生 API 缺口。目标不是重新实现 hypervisor，而是将 PVE 作为计算 backend，建立独立、headless 的 VM 生命周期与授权控制面。相当于把最难的虚拟化、存储和迁移能力外包给 PVE，同时架空其不足的北向管理面。 ## 设计原则 - 优先复用 PVE 原生能力；只有原生平面无法可靠表达的功能才越过 API - daemon 运行在受信任的 PVE 节点或独立控制区，通过 `qm`、`pvesh` 和受控 pmxcfs 写入执行操作 - 北向调用者永远不获得节点 root 或通用 PVE token - 所有操作经过自有 IAM/RBAC、幂等键、审计和策略校验 - 将长期声明式基础设施与 CI 产生的短命实例分开：OpenTofu 管长期对象，controller 管临时生命周期 - 保留 PVE UI/API/SSH 作为 break-glass，不使集群恢复依赖新控制面 ## 第一批用例 - 从版本化 cloud image/golden template 创建临时 Gitea Actions runner - 注入 Cloud-Init、QEMU Guest Agent 或未来 vsock bootstrap 数据 - 管理原生 API 难以覆盖的 QEMU `args`、serial、vsock 和 PCI passthrough - job 完成、TTL 到期或 controller 崩溃恢复后回收实例 - 查询 VM 实际状态、任务进度、节点、存储和迁移结果 ## 最小资源模型 - Instance：稳定 UUID、PVE VMID、generation、owner/project、backend、desired/observed state - Image：来源、构建版本、校验值、兼容能力 - Flavor/Resource：vCPU、RAM、磁盘、网络、GPU/PCI capability - Network attachment 与 storage attachment - Service account binding、TTL、lease 与幂等 request ID - Operation：异步状态、错误、重试与审计记录 ## 必须解决的问题 - 多节点 daemon 的 leader/locking 模型，避免重复执行 - PVE task UPID 与自有 operation 状态的映射 - VMID 复用与 instance generation 防混淆 - pmxcfs 写入和 `qm`/`pvesh` 调用的最小权限边界 - migration、HA、备份、删除、孤儿资源和部分失败的协调 - 节点离线时的 reconciliation 行为 - PVE 升级造成 CLI/配置格式变化时的兼容测试 - API 的 project RBAC、quota、lease 与审计 ## 分阶段交付 1. 整理现有 floppy 工具，拆出 PVE command adapter 与只读 inventory 2. 实现单实例 create/get/delete 和异步 operation 3. 接入 Gitea workflow job，完成 ephemeral runner 闭环 4. 加入 lease/garbage collection、RBAC 和 OpenBao bootstrap 5. 再评估 migration、HA、PCI/vsock 与多 backend 调度本 issue 不要求 fork 或 patch PVE，也不以完全替代 PVE 管理面为第一阶段目标。

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: panxiao81/homelab-infra#46