From 42697abe20e78769aa6f57a692f3f9e0a50ee939 Mon Sep 17 00:00:00 2001 From: songyiming <1000000008@qq.com> Date: Fri, 30 Oct 2026 15:14:33 +0800 Subject: [PATCH] =?UTF-8?q?=E5=8A=9F=E8=83=BD=EF=BC=9A=E8=A1=A5=E5=85=85?= =?UTF-8?q?=20README=20=E4=B8=8E=E5=90=84=E6=A8=A1=E5=9D=97=E5=8D=A0?= =?UTF-8?q?=E4=BD=8D=E7=9B=AE=E5=BD=95=EF=BC=88RDP=20=E9=81=97=E7=95=99?= =?UTF-8?q?=E4=BB=A3=E7=A0=81=E4=B8=8D=E6=81=A2=E5=A4=8D=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 281 ++++++++++++++++++++++++++++++ console/.gitkeep | 1 + deploy/.gitkeep | 1 + docs/.gitkeep | 1 + platform/.gitkeep | 1 + terminal/freerdp-rk/.gitkeep | 1 + terminal/meta-vdi/.gitkeep | 1 + terminal/ota-updater/src/.gitkeep | 1 + terminal/usb-monitor/src/.gitkeep | 1 + terminal/vdt-agent/src/.gitkeep | 1 + tools/.gitkeep | 1 + 11 files changed, 291 insertions(+) create mode 100644 README.md create mode 100644 console/.gitkeep create mode 100644 deploy/.gitkeep create mode 100644 docs/.gitkeep create mode 100644 platform/.gitkeep create mode 100644 terminal/freerdp-rk/.gitkeep create mode 100644 terminal/meta-vdi/.gitkeep create mode 100644 terminal/ota-updater/src/.gitkeep create mode 100644 terminal/usb-monitor/src/.gitkeep create mode 100644 terminal/vdt-agent/src/.gitkeep create mode 100644 tools/.gitkeep diff --git a/README.md b/README.md new file mode 100644 index 0000000..1375b21 --- /dev/null +++ b/README.md @@ -0,0 +1,281 @@ +# VDI 云桌面项目 + +本项目是一套面向企业云桌面场景的“云—管—端”VDI 解决方案，目标是在 RK3528 云终端上提供统一的用户登录、云桌面选择、远程会话接入、设备管理和运维能力。 + +当前仓库采用 monorepo 结构，包含终端嵌入式软件、云端服务、Web 管理控制台、部署配置和配套工具。 + +> 当前开发阶段：终端 POC 与产品流程验证。仓库内已实现的功能、已验证的功能和规划功能会在本文档中分别标注。 + +## 一、项目目标 + +终端产品的目标使用流程： + +```text +盒子开机 + -> kiosk-shell 登录/首配 + -> 用户认证 + -> 获取可用云桌面列表 + -> 用户选择 Windows / Ubuntu / 麒麟等桌面 + -> 获取一次性连接票据 + -> 根据协议启动 RDP 或 Moonlight 会话 + -> 会话结束后返回桌面列表 +``` + +总体系统关系： + +```text +RK3528 云终端 + -> 自研管理平台 API + -> Proxmox VE / KVM 虚拟化平台 + -> Windows / Ubuntu / 麒麟云桌面 +``` + +终端不会直接调用 Proxmox API。桌面生命周期、用户授权、连接信息和协议策略统一由管理平台下发。 + +## 二、仓库结构 + +```text +vdi-cloud/ +├─ terminal/ # 终端嵌入式软件 +│ ├─ meta-vdi/ # Yocto 层：BSP、内核、设备树、U-Boot、配方 +│ ├─ kiosk-shell/ # Qt 全屏壳：登录、桌面列表、远程会话 +│ ├─ freerdp-rk/ # FreeRDP 3 与 Rockchip MPP/VPU 适配 +│ ├─ 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/ # OpenAPI、MQTT、数据库等正式协议文档 +└─ tools/ # 烧录、构建、压测和 CI 工具 +``` + +当前有实现代码的模块为 `terminal/kiosk-shell`，其余模块保留目录结构，后续按里程碑逐步开发。 + +## 三、当前功能 + +### 1. 终端登录与桌面列表 + +已实现： + +- Qt 全屏登录页； +- 设备 SN 和网络状态显示； +- 本地演示认证（当前账号和密码非空即可通过）； +- Windows、Ubuntu、麒麟三类桌面卡片； +- **桌面连接可配置**：每张卡片有“设置”按钮，可配置协议（Moonlight/RDP）、 + 服务器地址（支持 IP、域名或 VPN 隧道地址）、应用名、分辨率和帧率； +- 连接配置持久化在 `~/.config/vdi-terminal/desktops.json`， + 地址为空的桌面显示“待分配”且不可连接； +- 老环境自动迁移：首次运行会读取 `client.conf` 里的 server 地址填充 Windows 桌面； +- `Ctrl+Alt+Shift+M` 管理菜单提供“桌面连接设置”统一入口； +- 退出登录后返回登录页；会话退出后返回桌面列表。 + +不同客户部署环境的桌面地址不同：换环境时在“设置”里改地址即可，不需要改代码。 +VPN 属于网络层能力（盒子上的 VPN 客户端建立隧道后），地址字段直接填隧道地址即可。 + +本地演示认证是后端 API 上线前的临时实现。后续通过 `DesktopService` 适配层接入真实的用户认证、桌面列表和一次性连接票据接口，页面流程不需要重写。 + +### 2. RDP 会话 + +已实现： + +- 基于 `libfreerdp3` API 内嵌，不拉起外部 `xfreerdp` 进程； +- FreeRDP GDI/GFX 画面接入 Qt； +- 键盘、鼠标输入转发； +- X11 键盘码到 RDP 扫描码映射； +- 鼠标缩放坐标转换； +- 会话状态与断线重连； +- `Ctrl+Alt+Shift+M` 管理菜单； +- RDP 后端代码保留，可由连接票据选择启用。 + +当前 RDP 路径仍处于 POC 阶段，证书忽略、测试账号等配置不能直接用于正式环境。 + +### 3. Moonlight/Sunshine 会话 + +已实现： + +- `MoonlightSession` 使用 `QProcess` 参数数组启动 `moonlight-qt`； +- 不通过 Shell 拼接用户输入，降低命令注入风险； +- H.264 软件解码； +- 绝对鼠标模式； +- 会话进程退出后自动返回桌面列表； +- `vsync`、`frame-pacing`、性能叠图等低延迟参数可配置； +- 独立 Moonlight 启动脚本保留作调试用途，但不再作为产品开机入口。 + +当前联调环境中，Sunshine 服务端仍使用 `libx264` 软件编码。1080p 实际帧率约 13～22 FPS，鼠标体感延迟主要来自服务端软编码和客户端帧队列/VSync。后续需要完成 GPU 直通并启用 NVENC。 + +### 4. 状态机 + +当前终端状态机： + +```text +BOOT + -> CONFIG / LOGIN + -> AUTHENTICATING + -> DESKTOP_LIST + -> CONNECTING + -> SESSION + -> RECONNECT + -> DESKTOP_LIST / ERROR +``` + +### 5. Monitor 看门狗 + +已实现独立 `vdi-kiosk-monitor` 进程： + +- 监控 kiosk-shell 进程是否退出； +- 通过心跳文件检测主进程假死； +- 异常退出后自动重启； +- 连续启动失败后熔断； +- 子进程独立进程组，结束时清理整棵进程树，避免遗留孤儿串流进程。 + +## 四、技术栈 + +### 终端 + +- C++17 +- Qt 5 Widgets +- FreeRDP 3 +- 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 \ + freerdp3-dev +``` + +Moonlight 会话还需要安装： + +```bash +sudo apt install moonlight-qt +``` + +### 2. 编译 + +```bash +cd terminal/kiosk-shell +cmake -G Ninja -B build -DCMAKE_BUILD_TYPE=Release +cmake --build build +``` + +编译产物： + +```text +build/kiosk-shell +build/vdi-kiosk-monitor +``` + +### 3. 运行 + +在当前 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. RDP 证书校验、短期凭据和正式安全策略尚未完成； +7. USB 重定向、OTA、Agent、管理平台和 Web 控制台尚未开发完成。 + +## 九、下一步计划 + +按优先级： + +1. 恢复 RK3528 盒子网络并部署登录/桌面列表新版本； +2. 实测 Moonlight `no-vsync` / `no-frame-pacing` 对鼠标延迟的改善； +3. 将 GTX 965M 直通 Windows VM，使 Sunshine 使用 NVENC； +4. 定义并联调终端用户认证、桌面列表和一次性连接票据 API； +5. 实现 Ubuntu、麒麟桌面连接配置； +6. 适配 RK3528 MPP/VPU 硬解； +7. 切换到 Weston/Wayland 正式显示路径； +8. 开发 `vdt-agent`、OTA、USB、云端服务和 Web 控制台。 + +## 十、开发规范 + +- 已验证、已实现、待验证和规划中必须明确区分； +- 终端不能直接调用 Proxmox API； +- RDP 和 Moonlight 协议选择由管理平台连接票据决定； +- 所有密钥和密码只能通过安全配置注入，不得提交到 Git； +- 正式代码变更应通过编译、真机测试和会话恢复测试； +- 本 README 随功能、接口、目录和验证结论持续更新。 diff --git a/console/.gitkeep b/console/.gitkeep new file mode 100644 index 0000000..728945f --- /dev/null +++ b/console/.gitkeep @@ -0,0 +1 @@ +# Keep the monorepo directory structure in Git. diff --git a/deploy/.gitkeep b/deploy/.gitkeep new file mode 100644 index 0000000..728945f --- /dev/null +++ b/deploy/.gitkeep @@ -0,0 +1 @@ +# Keep the monorepo directory structure in Git. diff --git a/docs/.gitkeep b/docs/.gitkeep new file mode 100644 index 0000000..728945f --- /dev/null +++ b/docs/.gitkeep @@ -0,0 +1 @@ +# Keep the monorepo directory structure in Git. diff --git a/platform/.gitkeep b/platform/.gitkeep new file mode 100644 index 0000000..728945f --- /dev/null +++ b/platform/.gitkeep @@ -0,0 +1 @@ +# Keep the monorepo directory structure in Git. diff --git a/terminal/freerdp-rk/.gitkeep b/terminal/freerdp-rk/.gitkeep new file mode 100644 index 0000000..728945f --- /dev/null +++ b/terminal/freerdp-rk/.gitkeep @@ -0,0 +1 @@ +# Keep the monorepo directory structure in Git. diff --git a/terminal/meta-vdi/.gitkeep b/terminal/meta-vdi/.gitkeep new file mode 100644 index 0000000..728945f --- /dev/null +++ b/terminal/meta-vdi/.gitkeep @@ -0,0 +1 @@ +# Keep the monorepo directory structure in Git. diff --git a/terminal/ota-updater/src/.gitkeep b/terminal/ota-updater/src/.gitkeep new file mode 100644 index 0000000..728945f --- /dev/null +++ b/terminal/ota-updater/src/.gitkeep @@ -0,0 +1 @@ +# Keep the monorepo directory structure in Git. diff --git a/terminal/usb-monitor/src/.gitkeep b/terminal/usb-monitor/src/.gitkeep new file mode 100644 index 0000000..728945f --- /dev/null +++ b/terminal/usb-monitor/src/.gitkeep @@ -0,0 +1 @@ +# Keep the monorepo directory structure in Git. diff --git a/terminal/vdt-agent/src/.gitkeep b/terminal/vdt-agent/src/.gitkeep new file mode 100644 index 0000000..728945f --- /dev/null +++ b/terminal/vdt-agent/src/.gitkeep @@ -0,0 +1 @@ +# Keep the monorepo directory structure in Git. diff --git a/tools/.gitkeep b/tools/.gitkeep new file mode 100644 index 0000000..728945f --- /dev/null +++ b/tools/.gitkeep @@ -0,0 +1 @@ +# Keep the monorepo directory structure in Git.