# VDI 云端服务与 Web 控制台功能设计

版本：v0.1 讨论稿 · 日期：2026-11-09 · 用途：产品范围讨论、UI 页面设计和后端任务拆分。

本稿保留设计时的现状基线。11-09 后续已开始第一阶段实现，最新代码能力、启动方式和未完成边界见[云管开发说明](cloud-platform-development.md)。

建议将产品定位为“基于 Proxmox 的云桌面业务管理平台”。管理员在我们的控制台完成桌面发放、终端管理和运维，平台在后端调用 Proxmox 等组件。画质和延迟优化继续独立推进，本轮不改串流链路。

## 1. 文档依据与当前状态

- `VDI云桌面软件开发方案(1).docx`：第 4 章七个云端服务，第 5 章控制台页面与三角色，以及 R8–R20 中的平台相关需求。
- `VDI云桌面完整方案-云管端.docx`：第 3 章虚拟化、模板、桌面池与 GPU，第 4 章管理平台。
- `VDI云终端产品方案-定版摘要(1).docx`：第 8 章“管终端 + 管桌面”的最小闭环。
- `web-console-mvp-plan-20261028.md`：既有控制台 MVP、接口和 Mock 策略，原件见[历史归档](archive/README.md)，日常计划见[未来计划](roadmap.md)。
- 仓库现状：`platform/`、`console/` 目前仅有占位文件；终端已有桌面列表和 Moonlight 接入，平台认证、注册、授权和连接票据尚未接通。

以下是基于原文档整理的功能建议，不代表已经实现或替换定版需求。页面原型全部采用演示数据。

## 2. “类似 Proxmox”具体做什么

```text
管理员浏览器 → 自研 Web 控制台 → 自研 Go 平台 → Proxmox API → VM / 模板 / 节点
                                        ↕
                               PostgreSQL / 指标存储
                                        ↕ HTTPS + MQTT
                                终端 Agent 与 Kiosk

实际桌面画面：终端 Moonlight ↔ VM 内 Sunshine
```

控制台提供面向云桌面的资源视图和管理操作。虚拟机运行、克隆、节点资源查询复用 Proxmox；用户能用哪些桌面、哪台盒子归谁、终端配置、命令执行、会话记录由平台维护。管理员控制台与盒子的桌面选择页是两个产品界面。

| 能力 | 现成组件提供什么 | 我们需要开发什么 |
| --- | --- | --- |
| 节点与 VM | Proxmox 提供资源查询、开关机、配置、模板和克隆等 API | 接入配置、资源同步、桌面业务映射、任务跟踪和页面 |
| 桌面池 | Proxmox 提供 VM、模板、克隆、快照等基础能力 | 公共/专属池、容量、分配、占用、回收和还原编排 |
| 用户与授权 | 可选 AD/LDAP 提供身份来源 | 平台账号、管理权限、用户/终端/桌面授权关系 |
| 终端管理 | MQTT 提供消息传输 | Agent 注册、设备认证、心跳、分组、配置、命令回执 |
| GPU 管理 | Proxmox 提供 PCI 配置；驱动工具提供设备信息 | 卡清单、独占占用、绑定校验、失败处理、健康状态 |
| 监控 | Proxmox 提供节点/VM 指标；VictoriaMetrics 保存时序数据 | Agent 会话采样、采集汇总、告警规则和查询权限 |
| OTA | 对象存储提供包下载 | 签名元信息、版本、灰度批次、Agent 安装和 A/B 回滚闭环 |
| 桌面连接 | Moonlight/Sunshine 提供串流 | 授权检查、端点发现、会话跟踪及配对/连接凭据集成 |

文档中 `/api/v1/...` 是自研平台的接口设计，不是 Proxmox 已经提供的同名接口。现有其他外部系统如能提供其中某部分，应以其真实接口清单、认证方式、版本和测试环境为准；目前仓库未见完整清单。

Proxmox 的 REST/JSON API 支持第三方管理系统集成，依据：[Proxmox 官方管理手册](https://pve.proxmox.com/pve-docs/pve-admin-guide.pdf)。具体端点和权限以现场版本 API Viewer 为准。

## 3. 第一版先交付什么

第一版验收场景：**接入 Proxmox → 纳管已有桌面 → 注册终端 → 授权桌面 → 盒子获取列表并连接 → 控制台查看状态 → 执行操作并追踪结果。**

| 阶段 | 功能范围 | 完成标准 |
| --- | --- | --- |
| A 基础闭环 | 管理员登录与三角色；接入一个 Proxmox 集群；同步节点和已有 VM；终端注册心跳；桌面授权；桌面启停；任务与审计；总览 | 一台真实盒子通过平台获得授权桌面并连接；管理员操作有真实最终回执 |
| B 发放与运维 | 模板登记与检查；克隆发放；桌面池；配置版本下发；日志收集；监控告警；GPU 清单和经验证的独占绑定 | 从模板发放一台可用桌面；执行配置下发；可查故障原因和 GPU 占用 |
| C 完整交付 | OTA 签名包与灰度/A-B 回滚；CSV 导入；公共池还原；可选 AD/LDAP；跨网段接入 | OTA 失败可回滚、公共池按策略回收；各可选能力单独完成联调验收 |

这是建议的实施顺序，不覆盖原文档 M1–M4 的项目里程碑。阶段 A 先纳管现有 Windows/Ubuntu/麒麟 VM，减少等待模板自动化的依赖；B/C 在首轮页面原型中保留功能入口。

## 4. 控制台页面清单

整体采用“左侧导航 + 顶部账号栏 + 主内容区 + 全局任务入口”。资源列表优先，详情使用详情区或抽屉；UI 同事负责视觉稿、品牌、颜色和组件规范。

| 导航 | 页面展示的核心信息 | 主要操作 | 阶段 |
| --- | --- | --- | --- |
| 总览 | 在线终端/总数、运行桌面/总数、活跃会话、待处理告警、节点水位、最近失败任务 | 点击指标进入对应列表；进入任务详情 | A |
| 计算资源 | 集群、节点状态、CPU/内存/存储水位、最近同步时间、接口连通性 | 接入 Proxmox、验证连接、同步资源；节点详情 | A |
| 桌面管理 / 桌面 | 名称、OS、VMID、节点、池、所有者、VM 电源状态、连接服务状态、当前会话 | 纳管已有 VM、从模板创建、授权、开机、正常关机、重启、还原镜像 | A/B/C |
| 桌面管理 / 桌面池 | 公共/专属、模板版本、总量/空闲/占用、最大容量、回收方式 | 新建、扩容、发放、回收、维护 | B/C |
| 桌面管理 / 镜像模板 | Windows/Ubuntu/麒麟、版本、源 VM、适用节点/存储、连接服务检查 | 登记已有模板、验证、发布/停用 | B |
| 终端管理 | SN、名称、分组、网络在线状态、会话状态、IP、系统/Agent 版本、最近心跳 | 激活/停用、改分组、授权、重启盒子、重置会话、配置下发、收集日志 | A/B |
| 用户与授权 | 终端用户、启用状态、可用桌面、关联终端；管理员账号与角色另设子页 | 创建/停用、分配/撤销桌面、终端关联；CSV 导入 | A/C |
| GPU 资源 | 厂商/型号、节点、PCI 地址、健康、可分配状态、占用桌面 | 查询、绑定、解绑、维护；实际温度/显存按采集能力展示 | B |
| 监控告警 | 会话数、FPS、网络 RTT、终端温度；节点水位；告警级别/对象/时间 | 时间范围筛选、查看会话、确认告警、规则配置 | B |
| OTA 中心 | 版本/签名状态/适配机型、批次、目标终端、成功/失败/回滚数量 | 登记升级包、测试批次、灰度发布、暂停/继续、查失败设备 | C |
| 任务与审计 | 任务类型、目标、操作者、提交/开始/结束时间、状态、错误；审计记录 | 查询、展开执行日志、按权限重试可重试任务 | A |
| 系统设置 | 平台管理员、角色、Proxmox 接入、配置模板；可选身份源 | 维护权限和接入；检查依赖服务 | A/B/C |

补充基础页面：管理员登录、登录过期、无权限、接口异常、空列表。PVE 不可达时显示最后同步时间和“数据可能过期”，不能继续展示为实时正常。

### 4.1 桌面列表布局

```text
桌面管理                                [纳管已有 VM] [从模板创建]
[名称/VMID 搜索] [OS] [电源状态] [桌面池] [查询]
名称       OS       节点    电源     连接服务   授权用户   操作
设计桌面   Windows  node-a  运行中   可连接     张三       详情 / 更多
办公桌面   Ubuntu   node-a  已关机   未就绪     李四       详情 / 开机

详情：基本信息 | 资源配置 | 用户与终端 | 会话 | 任务记录
底部/全局任务入口：克隆 / 启停 / 配置下发的执行状态和错误原因
```

“重置会话”只结束终端连接；“重启桌面”重启 VM；“还原镜像”会回退系统盘数据，三者分别命名。PVE `status/reset` 是硬重启，不等于还原镜像。还原实现依赖已经验证的快照或重建流程，并明确用户数据盘是否保留。

### 4.2 创建与发放桌面

向导字段：桌面名称 → OS/模板版本 → 目标节点/存储 → CPU/内存/磁盘规格 → 专属/公共池 → 可选 GPU → 可选授权用户 → 确认创建。

检查项：模板能否在目标存储克隆、容量是否充足、GPU 是否空闲、连接服务是否已预装。完成克隆之后，还需要 VM 内机器标识/账号/IP 初始化、Sunshine 服务可用性与配对准备检查；不能把“VM 克隆成功”直接显示成“桌面可连接”。

### 4.3 用户 终端 桌面的关系

- 平台管理员账号与最终桌面使用者分开管理，管理员角色不自动获得桌面使用权限。
- 用户可以获得多个桌面；终端显示当前身份有权使用的列表，保留现有 Windows/Ubuntu/麒麟选择能力。
- 第一版建议保留设备绑定模式：终端注册认证后按设备授权取得列表；后续可启用账号登录模式。SN 是标识，预置密钥等才用于设备身份验证。
- 一个盒子同时只允许一个活动桌面会话；专属桌面同一时刻的占用规则由平台检查。
- 修改授权后刷新列表；撤销授权至少阻止后续连接，是否立即中断现有会话需形成明确策略。

## 5. 云端服务怎么落地

沿用正式文档的 Go、PostgreSQL、VictoriaMetrics、HTTPS/MQTT 和七个服务职责。首期优先实现 A 阶段路径，部署数量按原方案执行；本稿不将微服务部署形态另行改成定版结论。

| 服务 | 首期开发职责 |
| --- | --- |
| api-gateway | 统一 API、管理员认证/权限、请求 ID、审计、错误码 |
| auth-svc | 管理账号、终端用户、授权关系；设备/用户连接授权检查 |
| terminal-svc | 注册、在线判断、设备列表、配置版本、命令与回执 |
| desktop-svc | PVE 接入、资源同步、VM 纳管与启停、异步任务；随后增加模板和桌面池 |
| mqtt-bus | 心跳消费、命令投递、seq/commandId 去重、回执关联 |
| metric-svc | 首期基础状态汇总；随后增加会话指标和告警 |
| gpu-broker | 后续接卡清单、独占分配、直通配置和健康探测 |

业务表沿用原文档的 terminal、desktop、pool、user、binding、gpu_card、config_template、ota_batch、session_log；补充平台接入记录、task、command、audit_log。desktop 保存 PVE 集群/节点/VMID 映射；GPU 锁定和公共池占用必须在后端保证原子性。

状态分别存储：终端网络状态、终端会话状态、VM 电源状态、VM 内连接服务状态、任务状态；避免“VM 开机 = Sunshine 就绪 = 用户已连接”的错误推断。

## 6. 接口先定哪些

原文档已有接口语义优先沿用，下面的“建议补充”路径是讨论用契约，实施前统一到 OpenAPI。旧文档中 singular/plural、监控路径和方法存在差异，需要统一，不能同时做成多套业务逻辑。

| 接口组 | 原文档已有 | 建议补充的能力 |
| --- | --- | --- |
| 身份与权限 | `/api/v1/auth/login`、用户 CRUD | 当前账号/退出、角色、终端身份验证、授权查询 |
| PVE 接入 | PVE client 职责 | 接入配置、验证连接、资源同步与纳管；接入凭据仅后端保管 |
| 终端 | `/terminal/register`、`/terminal/{id}/config`、`/terminal/{id}/status` | 管理列表/详情、远程命令、回执、配置版本 |
| 桌面和池 | `/desktop/assign`、`/pool`、`/pool/{id}/action` | 桌面列表/详情、VM 纳管、模板、单桌面动作 |
| GPU | `/gpu/cards`、`/gpu/bind` | 独占校验、解绑、健康状态 |
| 任务和审计 | 原文档有审计要求 | `GET /api/v1/tasks/{id}`、任务列表、审计列表 |
| 终端连接 | 旧 MVP 提出终端登录/列表/票据 | 当前身份可用桌面、连接申请、短期凭据及会话事件 |
| 监控和 OTA | `/monitor/query`、`/ota/manifest` | 受权限约束的指标查询、告警、版本/批次管理 |

命令型请求返回 `taskId` 或 `commandId`。页面先显示“已提交”，随后显示“排队/执行中/成功/失败/超时”；按 PVE 任务或 Agent 回执确认最终结果。超时表示结果尚未确认，需要核对实际状态后再决定能否重试；不自动重放克隆、还原等操作。MQTT QoS1 仍需业务去重。

连接票据是平台授权的一部分，不能凭空替代 Moonlight/Sunshine 配对和协议认证。需要单独验证“平台放行 → 终端可安全连接”的桥接方式。Guacamole/RDP 的 443 网关也不能直接作为当前 Moonlight 的网关方案。本轮先以局域网的现有串流链路接平台。

监控界面把指标写清楚：网络 RTT、解码耗时、FPS 分开；未采集的显示“暂无数据”，不填 0，不把 RTT 标成整体输入延迟。SN、令牌和配对信息不出现在审计正文。

## 7. UI 同事可以据此出什么稿

建议先出：应用框架/登录、桌面列表与详情、终端列表与详情、授权弹窗、创建桌面向导、任务详情六组主稿，再复用表格/表单扩展其他模块。

通用组件：筛选栏、状态标签、资源表格、详情抽屉、批量操作条、确认弹窗、步骤表单、任务进度、空态/错误态。规格包括正常/加载/无数据/失败/无权限，以及桌面运行中/关机/创建中/故障等状态。

权限沿用三角色：超级管理员负责接入、用户授权与 GPU；运维负责常规设备/桌面操作和升级；只读账号只查看。最终按服务端 RBAC 执行，原型的角色切换仅用于交互演示。

附带功能原型展示十个导航模块及桌面操作、终端命令、授权和任务回执。所有变更只影响演示数据，UI 可整体替换视觉；阶段 B/C 的原型页面不代表对应后台已经可用。

## 8. 开工前需要形成结论的三个问题

1. 外部接口清单：除了 PVE，是否还有既有账号、设备管理、OTA 或 GPU 调度服务？提供方和责任边界是什么？
2. 身份模式：首发保持“盒子绑定后自动显示桌面”，还是增加“使用者输入账号登录”？两者页面和认证接口不同。
3. 首发范围：建议 A 阶段作为首轮联调，B/C 作为后续功能包；是否有客户必须首发验收的模板、公共池或 OTA 功能？

这些问题不影响当前功能稿和原型评审；真实接口联调和最终排期以结论为准。