文档：归档历史记录并同步云管与终端验收资料

2026-11-09 17:55:16 +08:00
1 parent 3fb7b4da8c
commit d87fa47e24
@@ -1,164 +1,46 @@
 # VDI 云桌面项目

-本项目是一套面向企业云桌面场景的“云—管—端”VDI 解决方案，目标是在 RK3528 云终端上提供统一的用户登录、云桌面选择、远程会话接入、设备管理和运维能力。
+面向 RK3528 云终端的“云—管—端”VDI 项目。当前已接通 Windows、Ubuntu、麒麟的 Moonlight/Sunshine 会话，仍处于终端 POC 与产品流程验证阶段。

-当前仓库采用 monorepo 结构，包含终端嵌入式软件、云端服务、Web 管理控制台、部署配置和配套工具。
+## 文档入口

-> 当前开发阶段：终端 POC 与产品流程验证。仓库内已实现的功能、已验证的功能和规划功能会在本文档中分别标注。
+| 文档 | 内容 |
+| --- | --- |
+| [文档索引](docs/README.md) | 全部维护文档、历史归档与原始需求 |
+| [当前状态](docs/current-status.md) | 三系统配置、最新实施结果与验证边界 |
+| [终端说明](docs/terminal-guide.md) | 开机直达选择页、进出交接、快捷键、显示与构建 |
+| [云桌面说明](docs/desktop-guide.md) | 编码、光标、客体电源按钮、USB |
+| [运维说明](docs/operations.md) | 日志、监控分工、排障和回退 |
+| [云管开发说明](docs/cloud-platform-development.md) | Go API、Vue 控制台、本机启动、接口与联调边界 |
+| [未来计划](docs/roadmap.md) | 产品化与明确暂缓的 VPN、软件白名单、品牌画面 |

-## 一、项目目标
-
-终端产品的目标使用流程：
+## 当前流程与边界

 ```text
-盒子开机
-  -> 设备身份自动登录
-  -> 获取并展示可用云桌面列表
-  -> 用户选择 Windows / Ubuntu / 麒麟等桌面
-  -> 获取一次性连接票据
-  -> 启动 Moonlight 会话
-  -> 会话结束后返回桌面列表
+盒子开机 → LightDM 独占 kiosk → 选择云桌面 → Moonlight 串流 → 返回选择页
 ```

-总体系统关系：
+盒子使用私有 RKMPP 硬解/EGL，Windows 使用 NVENC，Linux 仍以软件编码为主。当前是 Xorg POC，Weston/Wayland 是后续方向；现场盒子已接入平台设备认证、授权列表和一次性连接票据，详见[真实接入说明](docs/cloud-live-integration.md)。正式边界为终端 → 自研平台 API → Proxmox，终端不直接管理 VM。

-```text
-RK3528 云终端
-  -> 自研管理平台 API
-  -> Proxmox VE / KVM 虚拟化平台
-  -> Windows / Ubuntu / 麒麟云桌面
-```
+11-09 已修复退出露出绿色桌面和进入左上角小窗；三系统 X11 采样通过，尚无外置逐帧采集。详细版本与证据见当前状态，不将历史性能测试当作实时健康报告。

-终端不会直接调用 Proxmox API。桌面生命周期、用户授权、连接信息和协议策略统一由管理平台下发。
+## 仓库结构

-## 二、仓库结构
+| 目录 | 职责 |
+| --- | --- |
+| `terminal/kiosk-shell/` | Qt 全屏入口、会话、看门狗和显示守护 |
+| `terminal/moonlight/`、`terminal/native-cursor/` | 私有硬解客户端补丁、Linux 原生光标 |
+| `terminal/usb-monitor/` | USB 存储设备透传 POC |
+| `terminal/meta-vdi/`、`terminal/vdt-agent/`、`terminal/ota-updater/` | 系统层、Agent 与 OTA 后续工作 |
+| `platform/`、`console/`、`deploy/` | Go API、Vue 管理台；演示部署与独立真实现场环境 |
+| `tools/` | 管理员构建、部署、诊断与测试工具 |
+| `docs/` | 主题说明、需求原件、历史归档与测试证据 |

-```text
-vdi-cloud/
-├─ terminal/                    # 终端嵌入式软件
-│  ├─ meta-vdi/                 # Yocto 层：BSP、内核、设备树、U-Boot、配方
-│  ├─ kiosk-shell/              # Qt 全屏壳：桌面列表、Moonlight 会话、看门狗
-│  ├─ vdt-agent/                # Rust：注册、心跳、命令、日志
-│  ├─ ota-updater/              # Rust：OTA 签名校验、A/B 切换、回滚
-│  └─ usb-monitor/              # Rust：USB 监听、挂载与重定向策略
-├─ platform/                    # Go 云端服务
-├─ console/                     # Vue 3 + TypeScript Web 管理控制台
-├─ deploy/                      # Docker Compose、Helm、离线部署包
-├─ docs/                        # 方案文档、实施记录、测试证据和运维资料
-└─ tools/                       # 烧录、构建、压测和 CI 工具
-```
+运行监控由独立 [vdi-monitor 项目](../vdi-monitor/README.md) 维护；本仓库保存实现、验证与回退资料。监控最新快照和 7 天指标不能替代全部历史证据。

-当前有实现代码的模块为 `terminal/kiosk-shell`，其余模块保留目录结构，后续按里程碑逐步开发。
+## 构建与配置

-## 三、当前功能
-
-### 1. 终端登录与桌面列表
-
-已实现：
-
- 开机后使用设备 SN 作为当前身份，自动进入桌面列表；
- Windows、Ubuntu、麒麟三类桌面卡片；
- **桌面连接可配置**：每张卡片有“设置”按钮，可配置服务器地址（支持 IP、域名或 VPN 隧道地址）、Sunshine 应用名、分辨率和帧率；
- 连接配置持久化在 `~/.config/vdi-terminal/desktops.json`，
-  地址为空的桌面显示“待分配”且不可连接；
- 老环境自动迁移：首次运行会读取 `client.conf` 里的 server 地址填充 Windows 桌面；
- `Ctrl+Alt+Shift+M` 管理菜单提供“桌面连接设置”统一入口；
- 会话退出后返回桌面列表。
-
-不同客户部署环境的桌面地址不同：换环境时在“设置”里改地址即可，不需要改代码。
-这里的 VPN 仅指网络层能力：盒子上的 VPN 客户端建立隧道后，桌面地址字段可以填写隧道地址。让云桌面内部浏览器和应用通过 Clash/Mihomo 访问 GPT 等外部服务属于后续规划，见“下一步计划”第 8 项。
-
-设备身份自动登录是正式认证 API 上线前的临时实现。后续通过 `DesktopService` 适配层接入真实的用户认证、桌面列表和一次性连接票据接口，页面流程不需要重写。
-
-### 2. Moonlight/Sunshine 会话
-
-已实现：
-
- `MoonlightSession` 使用 `QProcess` 参数数组启动 `moonlight-qt`；
- 不通过 Shell 拼接用户输入，降低命令注入风险；
- H.264 软件解码；
- 绝对鼠标模式；
- 点击连接后立即锁定操作，保证任何时刻最多一个 Moonlight 会话；
- 解析 Moonlight 输出，只有测试解码成功、渲染器选定且全屏串流窗口已激活后才淡出过场；
- ARM/X11 环境通过 `GL_IS_SLOW=0` 缩短不可用 DRM 路径的探测时间；
- 连接阶段有结构化耗时日志和 30 秒就绪超时，失败时自动关闭错误窗口并返回列表；
- 会话进程退出后自动返回桌面列表；
- `vsync`、`frame-pacing`、性能叠图等低延迟参数可配置；
- 独立 Moonlight 启动脚本保留作调试用途，但不再作为产品开机入口。
-
-2026-11-04 现场已接通 Windows、Ubuntu、麒麟三种桌面的正常选择与连接流程。Ubuntu 与麒麟现均为真实 2K / 30 FPS 请求配置与30Mbps，使用 `libx264` 软件编码和逐主机limited范围协商，盒子使用 RKMPP 硬解。2026-11-05 两套 Linux 已启用受限 X11 原生独立光标：同步实际形状/热点/显隐，由盒子显示指针位置，移动不再等待视频；Ubuntu恢复Adwaita/24px及默认鼠标加速，保留关闭动画。Windows保持原视频光标路径。形状、编号点击、断线恢复已实测，完整失焦与物理输入延迟尚未验收；点击页面及拖窗内容仍受软件编码限制，不能称定量等同Windows。方案和边界见 [原生独立光标实施记录](docs/linux-native-cursor-20261105.md)；历史画质证据见 [Linux接入](docs/linux-desktop-onboarding-20261104.md)、[Ubuntu调优](docs/ubuntu-quality-20261105.md)、[麒麟2K调优](docs/kylin-quality-20261104.md)。
-
-2026-11-05 后续只对 Ubuntu VM102 启用 `cpu=host`（AVX2）及 `virtio-gl`（共享Intel核显渲染）。受控长按框选的回显中位数约398→224ms，2K与原生光标保留；45FPS和4编码线程未继续改善延迟，最终仍用30FPS及默认线程。尚未达到Windows/原生目标，仍需解决捕获和软件编码瓶颈，详见 [Ubuntu框选与渲染调优](docs/ubuntu-drag-render-20261105.md)。
-
-### 3. 状态机
-
-当前终端状态机：
-
-```text
-BOOT
-  -> CONFIG / LOGIN
-  -> AUTHENTICATING
-  -> DESKTOP_LIST
-  -> CONNECTING
-  -> SESSION
-  -> RECONNECT
-  -> DESKTOP_LIST / ERROR
-```
-
-### 4. Monitor 看门狗
-
-已实现独立 `vdi-kiosk-monitor` 进程：
-
- 监控 kiosk-shell 进程是否退出；
- 通过心跳文件检测主进程假死；
- 异常退出后自动重启；
- 连续启动失败后熔断；
- 子进程独立进程组，结束时清理整棵进程树，避免遗留孤儿串流进程。
-
-## 四、技术栈
-
-### 终端
-
- C++17
- Qt 5 Widgets / Qt Test
- Moonlight Qt
- 当前开发环境：Armbian + LightDM + Xorg
- 正式目标环境：Weston + Wayland
-
-### 云端（规划）
-
- Go
- PostgreSQL
- VictoriaMetrics
- HTTPS + MQTT
- Proxmox VE / KVM / VFIO
-
-### Web 控制台（规划）
-
- Vue 3
- TypeScript
- Vite
- Element Plus
-
-## 五、构建 kiosk-shell
-
-### 1. 依赖
-
-目标设备或 ARM64 构建环境需要：
-
-```bash
-sudo apt install \
-  build-essential cmake ninja-build pkg-config \
-  qtbase5-dev libqt5widgets5 libqt5test5
-```
-
-Moonlight 会话还需要安装：
-
-```bash
-sudo apt install moonlight-qt
-```
-
-### 2. 编译
+在具备 Qt5 开发依赖的 ARM64 环境：

 ```bash
 cd terminal/kiosk-shell
@@ -167,101 +49,10 @@ cmake --build build
 QT_QPA_PLATFORM=offscreen ctest --test-dir build --output-on-failure
 ```

-编译产物：
+产物为 `kiosk-shell`、`vdi-kiosk-monitor`。产品连接配置在盒子 `~/.config/vdi-terminal/desktops.json`，基础配置为 `client.conf`；`moonlight.conf` 仅供旧独立调试入口使用。完整部署和客户端构建入口见[终端说明](docs/terminal-guide.md#build)。

-```text
-build/kiosk-shell
-build/vdi-kiosk-monitor
-```
+## 开发约定

-### 3. 运行
+保留用户已有改动；事实、计划和待验收结论分开记录。正式需求来源保留于 `docs/` 的三份 Word，后续明确确认的实现与当前用户要求优先于旧历史描述。账号、密码、私钥和连接票据通过安全配置提供，不新增到文档或提交。

-在当前 X11 开发环境中：
-
-```bash
-export DISPLAY=:0
-export XAUTHORITY="$HOME/.Xauthority"
-
-./build/vdi-kiosk-monitor -- ./build/kiosk-shell
-```
-
-产品自启入口为：
-
-```text
-vdi-kiosk-monitor -> kiosk-shell
-```
-
-Moonlight 只能在用户登录并选择桌面后由 kiosk-shell 启动，不应与 kiosk-shell 分别设置开机自启。
-
-## 六、本地配置
-
-终端基础配置路径：
-
-```text
-~/.config/vdi-terminal/client.conf
-```
-
-Moonlight 调试配置路径：
-
-```text
-~/.config/vdi-terminal/moonlight.conf
-```
-
-当前配置文件仅用于 POC。正式版本中，终端身份、配置版本和连接策略应由 `vdt-agent` 从管理平台同步。
-
-不要将以下信息提交到仓库：
-
- Windows 或平台账号密码；
- Proxmox root 密码；
- Gitea 密码或访问令牌；
- 终端设备密钥；
- Sunshine 管理账号密码；
- 私钥、证书和一次性连接票据。
-
-## 七、当前联调环境
-
-| 项目 | 当前环境 |
-|---|---|
-| 终端硬件 | RK3528 PRO DDR4 |
-| 终端架构 | ARM64 |
-| 终端系统 | Armbian / Ubuntu Noble |
-| 图形环境 | LightDM + Xorg（POC） |
-| 云平台 | Proxmox VE 9 |
-| Windows 云桌面 | Windows 10 22H2 |
-| Moonlight 服务端 | Sunshine |
-| 当前串流分辨率 | 1920×1080@60Hz |
-
-具体 IP、测试账号和密码不写入 README，统一通过本地配置或部署环境变量管理。
-
-## 八、已知限制
-
-1. 终端用户认证、桌面列表和连接票据目前是本地演示实现，尚未接管理平台 API；
-2. Ubuntu 和麒麟桌面尚未配置实际连接地址；
-3. 当前 Moonlight 使用软件解码，RK3528 的 VPU/MPP 硬解尚未打通；
-4. Sunshine 当前使用软件编码，未启用 NVENC；
-5. 当前仍是 X11 POC，尚未完成 Weston/Wayland/DRM 零拷贝路径；
-6. USB 重定向、OTA、Agent、管理平台和 Web 控制台尚未开发完成。
-
-## 九、下一步计划
-
-按优先级：
-
-1. 保持终端、Sunshine 和虚拟显示器三端分辨率及色彩空间一致；
-2. 将 GTX 965M 直通 Windows VM，使 Sunshine 使用 NVENC；
-3. 定义并联调终端用户认证、桌面列表和一次性连接票据 API；
-4. 实现 Ubuntu、麒麟桌面连接配置；
-5. 适配 RK3528 MPP/VPU 硬解；
-6. 切换到 Weston/Wayland 正式显示路径；
-7. 开发 `vdt-agent`、OTA、USB、云端服务和 Web 控制台；
-8. **云桌面内上网代理（规划）**：在终端登录首页提供代理配置入口，支持导入/更新 Clash 或 Mihomo 订阅、选择节点、启停和连通性测试；由云端服务将策略分别下发到 Windows、Ubuntu 和麒麟云桌面，使桌面内的浏览器和应用可以访问 GPT 等外部服务，同时为 Moonlight 串流、管理平台和必要内网地址保留稳定的直连/专用路由。该功能当前不实现、不部署；
-9. **云桌面软件白名单与商业合规（规划）**：建立按客户/桌面生效的软件允许列表、版本校验、策略下发、审计和回滚流程。Windows 与麒麟计划通过签名的系统插件或代理组件执行白名单策略；Ubuntu 计划在系统底层实施，并在定版前完成权限模型、更新机制和例外流程评审。该功能当前不实现、不部署，正式销售前必须完成授权范围和合规审查；
-10. **退出闪帧防护与盒子品牌安全画面（规划）**：解决云桌面退出、断流、客户端异常退出和 kiosk 重启时可能短暂暴露盒子底层桌面的问题。主方案是完善独立安全遮罩、X11/SDL 窗口交接并最终采用 Weston/Wayland 独占 kiosk；兜底方案是将盒子底层改为全屏公司 Logo、隐藏面板和桌面内容。该功能当前仅列入计划，不实现、不部署。
-
-## 十、开发规范
-
- 已验证、已实现、待验证和规划中必须明确区分；
- 终端不能直接调用 Proxmox API；
- Moonlight 是当前唯一远程会话协议，连接参数由管理平台连接票据决定；
- 所有密钥和密码只能通过安全配置注入，不得提交到 Git；
- 正式代码变更应通过编译、真机测试和会话恢复测试；
- 本 README 随功能、接口、目录和验证结论持续更新。
+日常直接更新对应主题，计划统一维护在 `docs/roadmap.md`；测试输出放入 `docs/evidence/<专题-日期>/`。2026-11-09 以前的零散记录及本次整理前的三份根说明完整保留在[历史归档](docs/archive/README.md)。