145 lines
9.6 KiB
Markdown
145 lines
9.6 KiB
Markdown
# RemoteDesk 开发指南
|
||
|
||
## 1. 环境
|
||
|
||
- Rust stable，包含 rustfmt 和 Clippy。
|
||
- Windows 管理界面使用 Flutter/Dart；原生媒体与 helper 继续使用 Rust、Media Foundation 和 D3D11。仓库不需要 Node.js、npm、JavaScript、C# 编译器或 WebView 构建链。
|
||
- Linux PipeWire、Portal、DRI3 与硬件编码器必须在对应 Linux 测试机执行 M0 Spike。
|
||
- Drone CI 的 Linux/Android/Windows/macOS 打包流水线、Android tag 签名 secrets、Runner 前置条件和产物留存约定见 [Drone CI 打包](ci-drone.md)。仓库不使用 GitHub Actions。
|
||
|
||
## 1.1 Windows Headless compatibility 验收
|
||
|
||
无 GPU 兼容模式必须覆盖仅 WARP、Microsoft Basic Display Adapter、Intel 核显和虚拟 GPU 环境；验证 DDA 的 DuplicateOutput/AcquireNextFrame 成功与失败、硬件编码器不可用时的软件编码选择、自动降到 1080p30/60 或更低档位、输入延迟不受软件编码阻塞、视频丢帧和关键帧恢复。诊断必须明确显示 software、cpu_upload、degraded 和不支持 4K/120。
|
||
|
||
兼容模式只在用户显式选择时启用。没有可复制的 DXGI Output 时应返回结构化 capture unavailable；WARP 或 Basic Display Adapter 不得被报告为硬件 GPU 或硬件编码。
|
||
|
||
## 2. Rust workspace
|
||
|
||
```powershell
|
||
cargo fmt --all -- --check
|
||
cargo clippy --workspace --all-targets -- -D warnings
|
||
cargo test --workspace
|
||
```
|
||
|
||
当前 crate：
|
||
|
||
- `remotedesk-protocol`：required features、显示拓扑/选择、协商摘要、双端内存路径报告和严格聚合。
|
||
- `remotedesk-agent-core`：Linux 单/多屏捕获能力、逐屏 GPU import probe、编码器选择和分辨率/布局重验证。
|
||
- `remotedesk-agent-runtime`：Linux `agentd`、用户会话 IPC、设备配对/WSS 认证、PAM/PTY 终端 helper，以及 Edge Presence、设备签名 poll/ack 和本地 Session Intent 授权。
|
||
- `remotedesk-client-core`：会话状态、helper 身份验证、RDP 凭据引用、多屏布局、GPU 计划和本地呈现报告。
|
||
- `remotedesk-control-service`：仅监听回环地址，提供静态界面、RDP 探测和三种 RDP 启动方式编排。
|
||
- `remotedesk-rdp-session`：独立的无凭据 IronRDP 协议与 TLS 证书探针，只从 stdin 接受目标和超时。
|
||
- `remotedesk-rdp-viewer`：独立 IronRDP 原生窗口；Windows 优先使用 D3D11 swap chain CPU 上传呈现，失败时回退 software framebuffer，不经过 React IPC。
|
||
- `remotedesk-native-video`：输出 D3D11 管线计划，并可在 Windows 真实创建硬件 device/immediate context。
|
||
- `remotedesk-edge-service`：独立 Edge Presence、有界签名 Session Intent 队列、Allocator/coturn credential 服务和限额透明 TCP byte relay；不随控制端或 Agent 进程启动。
|
||
- `remotedesk-update-manifest`：保留的签名清单工具；当前 Windows 便携发布链不调用它。
|
||
|
||
运行 native-video 规划：
|
||
|
||
```powershell
|
||
cargo run -p remotedesk-native-video -- --dry-run --window-adapter gpu-0
|
||
```
|
||
|
||
`--dry-run` 输出中的 `d3d11_created=false` 仅表示该规划命令不创建设备。真实设备探针使用：
|
||
|
||
```powershell
|
||
cargo run -p remotedesk-native-video -- --probe-d3d11
|
||
```
|
||
|
||
创建真实 H.264/DXVA decoder 对象、NV12 texture array 和 output view（仍不提交样本，也不证明零拷贝）：
|
||
|
||
```powershell
|
||
cargo run -p remotedesk-native-video -- --probe-h264-decoder
|
||
```
|
||
|
||
使用本地 H.264 MP4/M4V/MOV 文件验证首个解码样本必须以同一 device 上的 NV12 DXGI texture 返回：
|
||
|
||
```powershell
|
||
cargo run -p remotedesk-native-video -- --probe-h264-file C:\samples\baseline.mp4
|
||
```
|
||
|
||
在原生窗口按媒体时间戳播放同一受限 H.264 文件，并通过同 device D3D11 VideoProcessor 呈现 NV12 surface：
|
||
|
||
```powershell
|
||
cargo run -p remotedesk-native-video -- --play-h264-file C:\samples\baseline.mp4
|
||
```
|
||
|
||
窗口按启动配置进入全屏；按 `Ctrl+Alt+F` 在全屏与窗口模式之间切换，其余键盘输入直接转发到远端。该入口不映射 CPU frame，但在 ETW/GPUView 验证前仍不声明硬解或零拷贝。
|
||
|
||
输入必须是本地常规文件且不超过 512 MiB；UNC、空文件、非 H.264 video stream、CPU media buffer、错误 subresource 或不同 D3D11 device 均失败。成功只证明样本进入 DXGI surface，正式 `hardware_decode`/`zero_copy` 仍要求 ETW/GPUView 和完整呈现链验证。
|
||
|
||
成功时必须输出 `d3d11_created=true`、hardware driver type 和实际 feature level；这仍不代表解码器或端到端零拷贝已经接入。IronRDP viewer 的 swap chain 是独立 CPU 上传呈现路径。
|
||
|
||
控制服务还提供 `GET /api/v1/capabilities`。新增实际能力时，应同时更新 [实现状态](implementation-status.md) 和接口测试。
|
||
|
||
## 3. Flutter 管理界面
|
||
|
||
```powershell
|
||
cd client\flutter_control
|
||
flutter run -d windows
|
||
```
|
||
|
||
Flutter 只发送 loopback 控制命令；桌面会话视频由 Rust native-video helper 在独立原生窗口呈现，不经过 Flutter Texture。
|
||
|
||
## 4. Windows 便携包
|
||
|
||
```powershell
|
||
.\packaging\build-all.ps1
|
||
|
||
# 重新生成全部产物前清空 artifacts
|
||
.\packaging\build-all.ps1 -CleanArtifacts
|
||
```
|
||
|
||
输出目录只包含 `RemoteDesk-<version>-windows-<arch>-portable.zip` 和 `BUILD-SHA256SUMS.txt`，不调用 WiX、NuGet 或 .NET。解压后运行根目录 `RemoteDesk.exe` 启动 Client GUI；在被控 Windows 上运行 `host\RemoteDesk-Host.exe`，确认后提权、备份并启用 Windows Remote Desktop。配置程序完成后正常退出。
|
||
|
||
该组合包不包含 Linux Agent。Windows Client 提供 Flutter 管理界面、`mstsc`、独立 IronRDP viewer、native-video 和 Windows Credential Manager 凭据适配器；原生 viewer 支持固定/自定义初始尺寸、窗口动态分辨率、全屏和主动退出，协议探针会确认服务端 RDP 协商与 TLS 证书，但不会尝试账号登录。
|
||
|
||
## 5. Linux 被控端包
|
||
|
||
Ubuntu/Fedora 构建机生成 Linux DEB/RPM：
|
||
|
||
```sh
|
||
sh ./packaging/linux/package-deb.sh
|
||
sh ./packaging/linux/package-rpm.sh
|
||
```
|
||
|
||
Windows 开发机如已安装 Rust musl target、Android NDK LLVM 和 Git for Windows，可生成静态 x64 便携包与 musl DEB：
|
||
|
||
```powershell
|
||
.\packaging\linux\package-musl.ps1
|
||
```
|
||
|
||
Linux 包的 `/etc/remotedesk/agent.env` 包含默认监听地址和可选 Edge Presence 注释模板。Presence 配置必须四项同时存在；测试只能使用专用的非生产令牌，公网 URL 必须为 HTTPS。`remotedesk-agentd status --json` 可检查持久化的非敏感健康状态，SIGINT/SIGTERM 会触发限时 connection-bound 注销。
|
||
|
||
Ubuntu 22.04 CI 会对 Linux 目标执行测试和 Clippy，再构建原生 DEB/RPM。Windows 上的 musl 交叉构建只验证静态 ELF 和包结构，不能替代 systemd、PAM、PTY 和发行版安装测试。
|
||
|
||
独立 Edge 服务在 Ubuntu 构建原生 DEB：
|
||
|
||
```sh
|
||
sh ./packaging/edge/package-deb.sh
|
||
```
|
||
|
||
Windows 开发机生成静态 Edge TAR 和 musl DEB：
|
||
|
||
```powershell
|
||
.\packaging\edge\package-musl.ps1
|
||
```
|
||
|
||
输出为 `artifacts/RemoteDesk-Edge-<version>-linux-x64.tar.gz` 和 `artifacts/remotedesk-edge_<version>_amd64-musl.deb`。配置与部署边界见 `packaging/edge/README.md`：HTTP API 只能监听 loopback 并经 HTTPS reverse proxy 发布，TCP relay 应经 TLS/L4 入口发布，安装包不生成密钥且不会自动启动服务。CI 对 Edge crate 单独执行测试、Clippy 和 DEB 构建。
|
||
|
||
本地联合验证可让 Agent 使用 Presence 专用令牌注册，再在 Windows 控制端“全局设置 > Edge 会话授权”填写 HTTPS Origin。Client 的 Session Intent 提交和状态查询由 Client Ed25519 key 认证，不要把 `REMOTEDESK_EDGE_API_TOKEN` 写入 Windows 设置。首次配对时录入 Agent 本地 `pairing-code` 命令输出的设备公钥和证书指纹；只要 Agent 已在线且本机配对窗口仍有效，未配对 Client 即可提交独立 `pairing` Intent，经角色票据和 opaque relay 完成证书固定 TLS/WSS、Agent 公钥核对、Client challenge 签名及一次性码验证，无需连接 Agent listener。成功后 Agent 公钥按证书指纹保存在 `RemoteDesk/Linux/agent/<certificate-sha256>` Windows Credential Manager 条目；缺少 Edge 或设备公钥时保留直连配对回退。后续已知设备同样直接向 Edge 建立，控制端可检查或显式删除身份映射。自动化联合测试连续覆盖远程首次配对、已知设备重连、双向 TLS/WebSocket 字节和两类票据重放；另一组联合 API 测试覆盖接受会话内签名 SDP/ICE mailbox 的双向 offer/answer、伪造、重放和顺序/代际冲突。这些测试仍不能替代端点 WebRTC、真实 TURN POP 或跨网络媒体验证。
|
||
|
||
## 6. 实现边界
|
||
|
||
首轮代码只实现可测试的策略和状态模型。以下能力仍必须由 M0 实验验证：
|
||
|
||
- PipeWire DMA-BUF 到硬件编码器无 CPU 回读。
|
||
- Xorg 捕获后端；Portal/PipeWire 优先，DRI3 只能按环境验证。
|
||
- GStreamer D3D11 decoder、allocator、sink 和 Adapter LUID 一致。
|
||
- IronRDP NLA、动态分辨率服务端兼容性、UDP multitransport 和图形 surface 的真实 Windows 主机验证。
|
||
- TWCC/GCC、RTX/FEC 与硬件编码器码率动态更新。
|
||
- RDP viewer Named Pipe/Job Object 尚需 Windows 实机完成 ACL、PID/创建时间、镜像 hash、challenge MAC、控制服务崩溃回收和 helper 失败诊断验收；Tauri 壳需完成依赖解析、Windows 编译、随机端口导航限制、控制服务异常退出和升级重启验收，native-video 管道仍未接入。
|
||
- Windows Credential Manager 与 RDP NLA 凭据交付的真实远端登录验收。
|
||
- RDP Display Control 与 Linux Portal/XRandR 多显示器平台适配、热插拔和混合 DPI 实测。
|
||
- Linux WSS 配对、`SO_PEERCRED` IPC、PAM/PTY 和 systemd 在真实发行版的端到端实测。
|