# RemoteDesk

> 架构决策（2026-08-14）：所有发布运行时统一使用 Rust。Agent 是服务端；
> 原生 Client 使用 winit、wgpu 和 egui；两端使用 str0m WebRTC。Go、
> Hysteria2、Tauri、WebView、React 和软件兼容路径仅属于迁移期旧代码，
> 不属于目标架构。详见 [ADR 0001](docs/adr/0001-all-rust-runtime.md)。

RemoteDesk 是一套面向个人工作站的 Windows 远程桌面客户端。项目不包含 VDI、桌面池或多租户调度，重点是从 Windows 控制端连接 Windows 和现代 Linux 被控端。

## 产品定位

RemoteDesk 采用双通道设计：

- Windows 被控端：使用系统自带的 RDP 服务，由独立 Rust/IronRDP 原生会话进程连接。
- Linux 被控端：安装自研 RemoteDesk Linux Agent，支持 Wayland、Xorg 桌面和纯命令行终端。
- Windows 控制端：提供唯一的桌面客户端，Linux 不提供控制端 UI。

```text
                         +----------------------+
                         |   RemoteDesk Client  |
                         | winit + wgpu + egui  |
                         +----------+-----------+
                                    |
                     +--------------+--------------+
                     |                             |
                  RDP channel                Native channel
                     |                    WebRTC + DataChannel
                     |                             |
              Windows RDP               RemoteDesk Linux Agent
```

## 目标能力

以下内容是项目路线目标，不表示当前仓库已经全部实现。实际可运行范围以 [实现状态](docs/implementation-status.md) 和 [使用指南](docs/user-guide.md) 为准。

- Windows 和 Linux 连接配置统一管理。
- RDP 全屏、动态分辨率、多显示器、音频和剪贴板。
- 远程分辨率支持自动跟随、原始分辨率、720p/1080p/1440p/4K 固定档和自定义尺寸。
- 自研 Linux Agent 支持 Wayland、Xorg 当前会话和无桌面的命令行终端。
- 命令行会话使用 PTY，以指定普通用户运行，不要求图形桌面已登录。
- H.264 默认视频编码，按硬件能力扩展 HEVC 和 AV1。
- Linux 桌面默认要求双端零拷贝：Agent 使用 DMA-BUF 硬件编码，Windows 原生 helper 使用 D3D11 surface 解码与呈现。
- 客户端 GPU 默认自动选择，也支持全局或单主机手动指定。
- 多显示器支持主屏、全部和自定义子集，保留负坐标、混合 DPI 与布局 generation。
- RDP 主机使用 Windows Credential Manager 引用，HostProfile 不保存账号密码。
- 断线重连、连接质量统计和自适应画质。
- 智能比较直连与 CDN 路径；CDN 模式让两端进入最近 POP，并通过优质骨干网传输。
- 使用系统密钥库保存凭据。

## 明确不做

- 不从零实现 RDP 协议，也不引入 C++/FreeRDP 客户端。
- 不承诺 Windows 系统 RDP 服务端内部零拷贝；只能验证并报告 IronRDP 客户端实际得到 GPU surface 还是 CPU bitmap。
- 发布客户端不包含 JavaScript、Tauri、WebView 或 C# 启动器，远程媒体也不经过这些运行时。
- 不提供 VDI 桌面池、模板克隆和用户调度。
- 不承诺所有 Wayland 合成器均支持无人值守控制。
- 不使用缓存型 CDN 转码或缓存远程桌面内容。
- 首期边缘模式不依赖完整云账号体系，设备权限仍由 Agent 本地保存。
- 不依赖 xrdp、GNOME Remote Desktop 或 KDE KRdp。
- 首个稳定版本不承诺在所有 Wayland 桌面上控制登录界面。

## 技术基线

| 模块 | 技术 |
|---|---|
| Windows 桌面客户端 | Rust、winit、wgpu、egui |
| RDP 通道 | 独立 Rust helper、IronRDP、D3D11 |
| Linux Agent | Rust、Tokio、PipeWire/Portal/libei、X11、PTY/PAM |
| 媒体 | str0m、GStreamer、平台硬件编解码、纯 Rust Opus |
| Linux 会话显示 | Rust/wgpu 与平台原生 GPU surface |
| 命令行显示 | Rust 原生终端 + WebRTC DataChannel |
| 本地数据 | SQLite |
| 凭据 | Windows Credential Manager |
| 边缘中继 | Rust Rendezvous/Allocator、双 POP TURN、优质骨干网 |
| 静态 CDN | 签名 MSI/DEB/RPM、更新 manifest、SBOM |

具体依赖版本在进入编码阶段时锁定到当时可用的稳定版本。

## 仓库规划

```text
RemoteDesk/
├── client/                     # Rust 原生 GUI、helpers 与共享 crate
├── agent/                      # Rust Linux Agent workspace
├── protocol/                   # Protobuf 契约和兼容性测试
├── edge/                       # 独立 Edge Presence/Allocator/byte relay
├── packaging/                  # Windows、Linux Agent 和 Edge 打包
├── tests/                      # 集成和端到端测试
└── docs/
    ├── architecture.md
    └── roadmap.md
```

## 设计文档

- [实现状态](docs/implementation-status.md)
- [使用指南](docs/user-guide.md)
- [总体架构](docs/architecture.md)
- [Windows 客户端设计](docs/windows-client.md)
- [Linux 被控端设计](docs/linux-agent.md)
- [技术栈规划](docs/technology-stack.md)
- [协议设计](docs/protocol.md)
- [安全设计](docs/security.md)
- [差网络自适应](docs/network-adaptation.md)
- [CDN 与边缘中继](docs/edge-relay.md)
- [客户端 GPU 加速](docs/gpu-acceleration.md)
- [在线升级](docs/online-updates.md)
- [M0 技术验证](docs/m0-validation.md)
- [实施路线](docs/roadmap.md)
- [开发指南](docs/development.md)

## 当前代码

本节仅描述当前 Rust workspace；迁移前的 Tauri、React、WebView 和 Hysteria2 文字只保留在历史设计文档中，不属于构建或发布入口。

当前工程已包含 Rust workspace、协议状态模型、多显示器布局、Windows Client Core、RDP 地址校验、回环控制服务、无凭据 IronRDP 协议与 TLS 证书探测、证书指纹固定、Windows Credential Manager 凭据适配器、外部 `mstsc`、带有界自动重连和 D3D11 CPU-upload swap chain 的 IronRDP 原生窗口、Ed25519 签名清单在线升级、native-video 管线规划与真实 D3D11 设备探针，以及 React 管理界面。被控端新增了可逆配置 Microsoft RDP 的独立 Windows Host MSI，以及包含 `agentd`、用户会话进程、PAM/PTY 终端进程、支持双向断点续传的文件进程、配对/WSS/Unix IPC、systemd、DEB/RPM/静态便携构建链的 Linux Agent 基础。独立 Edge 服务已实现短 TTL Presence、测量路径分配、coturn REST 短期凭据、限额透明 TCP byte relay 和接受会话内两端设备 key 签名的 SDP/ICE mailbox，并已接通 Linux 首次配对、终端/文件的签名准入、角色票据及端到端 TLS/WSS opaque relay。接受的桌面会话新增双方 PeerConnection、逐候选 ICE、session-bound TURN 凭据和 H.264/RTX/Opus/DataChannel 传输内核源码；Linux 用户会话将同一次 X11 BGRA 捕获送入 GStreamer H.264 编码器，经严格有界、分块和 SHA-256 校验的 root/user IPC 交给精确绑定用户及 Client 指纹的 WebRTC sender。Windows 控制 helper 已接入有界 RFC 6184 RTP 重组、丢包/积压后 PLI 与关键帧恢复，以及 Media Foundation H.264 MFT 到同 device NV12/D3D11 VideoProcessor/swap-chain 的原生呈现源码。协议 minor 14 还接入显式协商的 Linux 系统输出 Opus 捕获、有界 IPC/WebRTC 发送和 Windows WASAPI 本地播放；minor 15 增加独立 `clipboard_read`/`clipboard_write` 授权、X11 与 Windows `CF_UNICODETEXT` 双向文本剪贴板和 Offer/Request/Data 按需传输源码；RDP Edge 尚未接入。

Linux 图形的 X11 zlib 兼容捕获/输入、GStreamer H.264 WebRTC 发送端和 Windows 原生远端 H.264 接收/解码/呈现已接入源码；协议 minor 9 在首张原生帧后切换到 H.264-only，以呈现 ACK 驱动捕获并在丢包或媒体失败时恢复 zlib，避免长期双路传输完整画面。协议 minor 10 进一步接入显式光标抓取、Windows Raw Input 合并、有界相对鼠标和 XTEST 相对移动，失焦/重连/退出会解除抓取并释放远端输入。协议 minor 11 已接入认证后的 Wayland Portal、严格 PipeWire DMABUF-to-VA-H.264、呈现 ACK、resize 重建和 `reis` EIS 输入源码；minor 12 在断线后释放全部输入并保留 15 秒 Portal/EIS 租约，只有相同 Client 指纹、Linux 用户和轮换令牌才能使用新 WebRTC sender 恢复，并从新 IDR 继续。协议 minor 13 将现有 PeerConnection 媒体内核抽象为认证信令接口，直连 Client/Agent 可在证书固定、Ed25519 认证后的 WSS 上交换严格有界的 SDP/ICE，使用 host-candidate ICE 建立 H.264/RTX/Opus/DataChannel；失败经显式 abort/unavailable 同步后，X11 才回到 zlib，Wayland 仍拒绝 CPU 回退。minor 14 为直连和 Edge 桌面请求增加默认关闭的 Opus 协商，只有同版本 Client 显式开启且已取得授权媒体 sender 时才捕获 Linux 输出 monitor，并在 Windows 通过 IronRDP Opus 解码器和 WASAPI 播放；视频与音频失败互不连带。minor 15 的 X11 文本剪贴板只在双方显式协商对应方向且配对授权包含相同权限时启用，内容限制为规范化 UTF-8 文本和 32 KiB；Wayland 剪贴板仍未接入。新增媒体、音频、剪贴板路径和 GNOME/KDE/Xorg 实机验证仍未执行，因此运行时继续报告 `linux.wayland_desktop=false` 与 `linux.native_video=false`。Linux Terminal 的 Windows 控制 helper 已接通 WSS、证书固定、Ed25519 配对认证和 PTY 字节流，但尚未在真实 Linux/PAM 主机完成端到端运行验证。真实 PipeWire/DRI3/D3D11 呈现/Tauri 继续按 M0 技术验证计划逐项实现，不以模拟代码或仅存在安装包来代替平台验证。Windows Credential Manager 的写入、状态、删除、IronRDP NLA 凭据读取和 Linux 客户端身份存储已接入。