249 lines
27 KiB
Markdown
249 lines
27 KiB
Markdown
# RemoteDesk 使用指南
|
||
|
||
## 1. 当前可用范围
|
||
|
||
当前仓库处于工程开发阶段。Windows 控制端包含 Tauri 2 桌面壳源码、Rust 本地控制服务、RDP 协议探针、系统 `mstsc` 启动、独立 IronRDP 原生窗口、Linux Terminal 控制 helper ；Tauri 壳尚未按要求解析依赖、编译或运行验收。Windows 被控端另有 Host MSI。Linux 被控端已提供配对/WSS/IPC/PTY 基础和安装包，终端可由控制端在独立本地窗口打开。源码中的协议 minor 9 已接入 X11 `GetImage`/XTEST、有界 zlib BGRA 帧、Windows 软件桌面窗口、帧率/压缩等级自适应、短时恢复令牌、Linux GStreamer H.264 编码到 Agent WebRTC sender，以及 Windows RFC 6184 RTP 重组到 Media Foundation/D3D11 原生呈现。第一张原生帧呈现后会在完整帧边界切换到 H.264-only，不再并行传输完整 zlib 帧；H.264 呈现 ACK 驱动下一次捕获，丢包、积压、解码、媒体或 ACK 失败会恢复 zlib。新增源码尚未编译或在真实 Windows/Xorg 主机验收，当前发布包不能据此宣称 WebRTC 图形会话可用，`linux.native_video` 仍为 `false`；Wayland 仍关闭。Linux Agent 可选接入 Edge Presence；首次配对、终端和文件会话均可通过 Agent 出站 Edge relay 完成。Edge 服务已提供签名 SDP/ICE mailbox 和端点 PeerConnection；完整 CDN 媒体/RDP 链路仍未完成。
|
||
|
||
完整的已实现/未实现清单见 [实现状态](implementation-status.md)。界面会读取控制服务的运行时能力，只启用当前构建真实支持的操作。
|
||
|
||
非敏感主机设置和明暗主题保存在浏览器 `localStorage`。默认不再创建示例主机；Windows 账户不会写入持久化的主机配置，密码不会进入页面状态或浏览器存储。
|
||
|
||
## 2. 启动管理界面
|
||
|
||
### Windows 安装包
|
||
|
||
运行 `RemoteDesk-M0-<version>-windows-<arch>.msi` 后，RemoteDesk 会安装到当前用户目录，不要求管理员权限。从开始菜单打开 `RemoteDesk`；使用期间保留启动窗口，关闭窗口会停止本地控制服务。通过 Windows“已安装的应用”卸载。
|
||
|
||
当前已有开发安装包尚未使用 Authenticode 证书签名，Windows 可能显示“未知发布者”。源码新增的受保护正式标签工作流会强制签署并验证控制端/Host MSI、内部 EXE 和 PowerShell，再发布 Ed25519 签名更新清单；该工作流按本轮要求尚未实际执行，因此不能把现有包视为已签名。运行时能力接口决定当前包可用的操作；设计文档中的 Linux 图形、D3D11 呈现和 CDN 能力不会因为安装 MSI 自动启用。
|
||
|
||
### Windows 被控端
|
||
|
||
在支持 RDP Host 的 Windows Pro/Enterprise/Server 上安装 `RemoteDesk-Host-<version>-windows-x64.msi`。安装不会直接开启远程桌面。打开开始菜单中的 `Configure RemoteDesk Host`，阅读变更说明并输入 `ENABLE`，再确认 Windows 管理员提权。
|
||
|
||
配置过程保持 NLA 开启，启用 Microsoft 内置 RDP 防火墙规则并确保 `TermService` 运行，不创建账户或保存密码。首次变更前的 RDP/NLA/服务/防火墙状态保存在 `%ProgramData%\RemoteDesk\Host\original-state.json`。开始菜单的恢复入口或正常 MSI 卸载会恢复该状态；版本升级不会中途回滚。
|
||
|
||
### Linux 被控端
|
||
|
||
Debian/Ubuntu 安装静态 DEB：
|
||
|
||
```sh
|
||
sudo apt install ./remotedesk-agent_<version>_amd64-musl.deb
|
||
sudo remotedesk-agentd pairing-code --allow-user "$USER"
|
||
```
|
||
|
||
其他 x64 systemd 发行版可解压 `RemoteDesk-Agent-<version>-linux-x64.tar.gz` 后运行 `sudo ./install.sh`。RPM 由 Linux CI 生成。安装包不会修改 UFW、firewalld、nftables、SELinux 或 AppArmor；需要管理员按网络边界显式放行默认 TCP 39500。
|
||
|
||
如已单独部署 Edge 服务，可在 `/etc/remotedesk/agent.env` 同时配置 `REMOTEDESK_EDGE_API_URL`、`REMOTEDESK_EDGE_PRESENCE_TOKEN`、`REMOTEDESK_EDGE_REGION` 和 `REMOTEDESK_EDGE_GATEWAY_ID`，然后重启 `remotedesk-agentd`。公网 URL 必须使用 HTTPS，令牌必须是至少 32 字节的 Agent Presence 专用令牌。用 `sudo remotedesk-agentd status --json` 检查 `edge_presence`；这只发布短 TTL 在线路由，不会启用控制端 CDN 选项或建立媒体会话。
|
||
|
||
控制端“全局设置 > Edge 会话授权”可填写同一 HTTPS Edge API Origin。首次配对时，把 Agent 本地 `pairing-code` 命令输出的 `device_public_key` 填入主机配置；Agent 已在线且本机配对窗口有效时，Client 以自己的 Ed25519 key 签名 `pairing` Intent，Agent 验证窗口的用户/terminal 范围后签发 relay。控制端随后在 opaque relay 内核对 Agent 公钥、签名 challenge，并提示输入八位一次性码；配对码不进入 Edge API。缺少 Edge URL 或设备公钥时仍可直连配对。公网 relay 使用系统信任 TLS，明文仅允许 loopback 测试；媒体/RDP CDN 策略仍不开放。
|
||
|
||
Linux Terminal 面板会显示该身份条目的 `已保存/未保存/待检查` 状态。刷新按钮读取 Credential Manager；删除按钮在确认后显式忘记身份，下一次会话必须重新配对，但仍可使用上述 Edge 路径。删除主机配置时也会单独询问是否同时忘记身份；选择保留时，可在 Windows Credential Manager 中按上述目标手工维护。Agent 公钥不是秘密，但它决定签名请求的目标设备，只能使用 Agent 本地命令输出核对。
|
||
|
||
配对命令输出八位一次性代码和设备公钥。控制端不要求配置或固定 TLS 证书指纹。当前 Windows 控制端可从 Linux Terminal 主机入口配对并打开终端；源码已为 Xorg 主机开放独立 Linux 桌面窗口入口，但该新增链路尚未编译和真实主机验收，当前发布包仍不可用。
|
||
|
||
### 开发模式
|
||
|
||
环境要求：
|
||
|
||
- Rust stable
|
||
- Windows 图形与媒体开发组件
|
||
|
||
直接启动 Rust 原生管理界面：
|
||
|
||
```powershell
|
||
cargo run --locked -p remotedesk-native-gui
|
||
```
|
||
|
||
生产构建和检查：
|
||
|
||
```powershell
|
||
cargo fmt --all -- --check
|
||
cargo test --workspace --locked
|
||
cargo build --release -p remotedesk-native-gui
|
||
```
|
||
|
||
## 3. 切换白色主题
|
||
|
||
点击顶栏右侧的太阳或月亮图标切换白色主题和深色主题。首次打开时跟随 Windows 系统主题；手动切换后，RemoteDesk 会在当前浏览器或 WebView 配置中记住选择。
|
||
|
||
## 4. 添加主机
|
||
|
||
点击“新增主机”，填写名称、连接类型和地址或设备 ID。
|
||
|
||
主机配置由本地控制服务保存到 `%LOCALAPPDATA%\\RemoteDesk\\hosts.db`。重新安装或升级客户端不会清理该目录，主机名称、地址、显示和连接选项会自动保留；Windows 密码仍单独保存到 Windows Credential Manager，不写入主机数据库。
|
||
|
||
Windows 主机添加后会立即检测，刷新按钮会重新检测全部 Windows 主机。打包版本会在 TCP 可达后继续解析 RDP Negotiation Confirm；“RDP 协商成功”仍不表示账号密码正确，也不表示 NLA 已完成。Linux Agent 探测使用 TLS/WSS 加密并校验协议 `Hello`，显示握手耗时、终端/桌面/文件能力和 Edge 在线状态，不要求配置证书指纹。
|
||
|
||
### Windows RDP
|
||
|
||
- 类型选择 `Windows RDP`。
|
||
- 地址填写 Windows 主机的 IP、域名或 `host:port`，默认端口为 `3389`；IPv6 自定义端口使用 `[IPv6]:port`。
|
||
- 账户可填写 `DOMAIN\user`、`COMPUTER\user` 或 UPN 格式，仅传给本次启动的 RDP 客户端；密码不会进入页面或命令行。`mstsc` 使用的临时 `.rdp` 文件也不含密码。
|
||
- 被控 Windows 需要启用远程桌面，并允许目标账户登录。
|
||
- 在“RDP 客户端”中选择一种方式：
|
||
- `mstsc`：系统远程桌面，支持当前版本最完整的多显示器能力，认证由 Windows 窗口处理。
|
||
- `客户端内`：随安装包提供的独立 IronRDP 原生窗口，密码从 Windows Credential Manager 读取或只在 helper 的本地遮罩提示中输入；支持主显示器或启动时枚举的全部本地显示器，优先使用 D3D11 swap chain CPU 上传呈现，失败时回退 software framebuffer。
|
||
|
||
RDP 端口与协议检测只用于状态诊断，不是 `mstsc` 或原生 IronRDP 的连接前置条件。协议探针可以显示服务器协商结果，但不会要求用户确认或配置证书指纹；连接失败时仍会显示实际错误。
|
||
|
||
控制服务源码通过仅限当前 Windows 用户、拒绝远程客户端的 Named Pipe 启动原生 viewer。命令行只携带随机 pipe name；目标、用户名、opaque 凭据引用、分辨率和全屏设置在控制服务核对 pipe 客户端 PID、进程创建时间、实际镜像路径、build hash 及一次性 challenge MAC 后才发送。viewer 完成严格 JSON schema 和全部配置字段校验后，才返回绑定该载荷摘要的认证 ACK；未 ACK、摘要不符或 MAC 错误都会使控制服务终止启动。连接、认证、配置和 ACK 共用 10 秒绝对 deadline，helper 即使已经连接，后续停滞也会超时。viewer 同时加入随控制服务关闭的 Job Object，握手失败会在质量诊断中报告 `secure_pipe_failed`。该新增链路按本轮要求尚未编译和 Windows 实机验收，旧安装包不包含此行为。
|
||
|
||
IronRDP 原生窗口获得焦点后，物理键盘扫描码、鼠标移动、左/右/中键、前进/后退键和水平/垂直滚轮会发送到远端，鼠标坐标按当前窗口与远程桌面尺寸换算。当前构建显式启用 Windows CLIPRDR 双向剪贴板并默认启用 RDPSND 本地音频。切换到其他窗口、关闭会话或执行本地保留快捷键时，客户端会先释放远端已按下的按键和鼠标按钮，避免 Ctrl/Alt 或拖拽状态卡住。
|
||
|
||
IronRDP 原生窗口支持 `F11` 或 `Alt+Enter` 切换全屏，处于全屏时按 `Esc` 返回窗口，按 `Ctrl+Shift+Q` 关闭当前会话。按 `Ctrl+Alt+Home` 会向远端发送标准 RDP `Ctrl+Alt+End` 序列，用于打开远程 Windows 安全界面；它不能拦截或直接发送本机 Windows 保留的 `Ctrl+Alt+Del`。这些组合键作为本地命令处理：触发时立即释放远端输入，命令按键不会重复转发；点击窗口关闭按钮也会先释放输入状态，再向 RDP 客户端发送关闭事件。
|
||
|
||
Windows 系统 RDP 服务端是否提供 GPU surface 取决于服务端、编码模式和 IronRDP 能力。当前原生 viewer 只转换 IronRDP dirty region 的像素块，将其合并到持久 CPU framebuffer，只把变化区域上传到持久 D3D11 texture，再呈现到 swap chain；质量详情显示最近一次像素转换量、上传模式和上传像素数。该路径仍不能报告硬件解码或端到端零拷贝。
|
||
|
||
### Linux Agent
|
||
|
||
- 类型选择 `Linux Agent`。
|
||
- 地址填写 Agent 设备 ID。
|
||
- 图形会话可选择 Wayland 或 Xorg，纯命令行使用 Terminal。
|
||
- Linux 只作为被控端，不提供控制端界面。
|
||
|
||
Linux Agent 已提供 DEB、静态便携包和 RPM 构建链。协议 minor 9 源码已增加 X11 `GetImage` 捕获、XTEST 输入、有界 zlib BGRA 帧、全屏/退出、自适应、短时恢复、质量遥测、原生包的 GStreamer H.264 编码/有界媒体 IPC/WebRTC sender、Windows 控制 helper 的远端 H.264 RTP 重组、Media Foundation 解码和 D3D11 呈现，以及经服务端确认的 H.264-only/呈现 ACK/zlib 回退状态机。静态 musl 包不包含动态 GStreamer 特性。协议 minor 11 的 Wayland 源码会在远端认证和 `desktop` 权限检查后的 `OpenDesktop` 中启动 Portal 授权，仅接受 PipeWire DMABUF 到 VA surface/H.264 的严格管线；首个 IDR 和 EIS 键盘/指针设备就绪后才打开桌面，按 Windows 实际呈现 ACK 发送后续帧，并通过 `reis`/XKB 注入映射到所选 stream region 的鼠标、滚轮和键盘。协议 minor 12 进一步增加绑定 Client 指纹和用户的 15 秒 Portal/EIS 恢复租约，断线立即释放输入，恢复时使用新的 WebRTC sender 和新 IDR。协议 minor 13 增加认证 WSS 直连 WebRTC：Client/Agent 交换有界 SDP/ICE，授权绑定 Client 指纹、用户、尺寸和 FPS，双方 ICE 完成后才发送对应 `OpenDesktop`；失败完成 abort/unavailable 同步后，X11 才回退 zlib，Wayland 不提供原始帧 CPU/zlib 回退。新增依赖、管线、恢复和直连链路尚未编译、进入安装包或在 GNOME/KDE/VA 驱动上验收，因此运行时能力仍关闭，不能据授权弹窗或源码入口宣称 Wayland 可用。
|
||
|
||
源码中的 Linux X11 桌面窗口使用 `F11` 或 `Alt+Enter` 切换全屏，全屏时 `Esc` 返回窗口，`Ctrl+Shift+Q` 退出会话。协议 minor 10 可在主机设置中启用相对鼠标；光标抓取成功后 Windows Raw Input 位移会合并并发送到 XTEST，`Ctrl+Alt+Home` 可随时切换捕获。窗口失焦、重连或退出会解除光标抓取并释放远端按键和鼠标按钮；切换全屏也会释放远端输入状态。主动退出等待被控端完成释放并返回关闭确认。画面保持宽高比居中显示，黑边区域不会生成远端鼠标坐标。选择“跟随窗口”时，窗口尺寸稳定 500 ms 后才提交一次 200..8192 范围内的新捕获上限；它只调整捕获缩放，不修改被控 Xorg 的物理分辨率。协议 minor 15 源码按 `clipboard_read`、`clipboard_write` 两个配对权限启用 X11 与 Windows 控制端的双向纯文本剪贴板；主机设置可分别关闭“读取被控端”和“写入被控端”，实际协商结果是本地开关与 Agent 授权的交集。主界面的“当前会话剪贴板”在连接后读取 helper 诊断中的最终交集；连接或重连期间显示等待协商，双方均未授权时显示“Agent 未授权”。单项限制 32 KiB，只有接收方请求后才发送内容，并校验序号、UTF-8 长度、SHA-256 和 canonical Base64。Wayland 剪贴板尚不可用。异常断线后按 1、2、4 秒最多重连三次，每次重新固定证书并认证；Edge 路径会申请新的一次性票据。被控端保留同一 X11 会话 15 秒，恢复令牌绑定已认证客户端与 Linux 用户并在成功恢复后旋转；断线期间的旧输入、未完成帧和 ACK 不会重放。Windows 控制 helper 会把最新令牌按 Agent 证书和 Linux 用户隔离保存到当前用户 Credential Manager；helper 异常退出后，在 15 秒租约内重新启动同一主机和用户即可尝试恢复。正常关闭、服务端关闭或令牌拒绝会清除记录。新增剪贴板路径按要求尚未编译或在真实 Windows/Xorg 主机验收。
|
||
|
||
新增 Linux Terminal 主机时填写 Agent `host[:port]` 和允许登录的普通用户。首次点击“配对并打开终端”，在新本地窗口遮罩输入八位一次性配对码；后续直接连接使用 Windows Credential Manager 中的客户端 Ed25519 身份完成 challenge 签名，不再发送配对码。私钥、配对码和终端内容不经过 React 或控制服务。
|
||
|
||
协议 minor 14 源码增加显式 Opus 音频协商。只有同版本 Client 明确请求且本次桌面已取得授权 WebRTC media sender 时，Linux 用户会话才捕获系统输出 monitor；minor 13 及更旧客户端缺少该字段时默认关闭，不会收到 Opus packet 或 unavailable 事件。音频使用固定 48 kHz 双声道、20 ms 包，经有界 IPC/SRTP 传输并在 Windows 通过有界队列、IronRDP Opus 解码和 WASAPI 播放。音频捕获、发送、解码或播放失败只关闭音频，不中断 H.264 或 zlib 视频。该路径仍需 Linux/Windows 音频设备端到端验收。
|
||
|
||
## 5. RDP 凭据维护
|
||
|
||
选择 Windows 主机后，可以在右侧“Windows 凭据”区域为该主机打开独立本地遮罩窗口，保存或覆盖 Windows 账号和密码，也可检查状态、删除条目或打开系统凭据管理器。`mstsc` 继续使用 Windows 登录窗口；原生 IronRDP 通过主机的 opaque 引用直接读取系统凭据。
|
||
|
||
RemoteDesk 的 React/HTTP 层不收集或保存 RDP 账号密码，只处理 `RemoteDesk/RDP/<profile-id>` 形式的 `credential_ref` 和 `ready/missing` 状态。录入窗口和 IronRDP viewer 直接调用 Windows Credential Manager；控制服务只负责启动 helper，主机配置只保存无法推出密码的引用。
|
||
|
||
## 6. 会话设置
|
||
|
||
选中主机后，可在右侧检查器调整：
|
||
|
||
- 连接模式：Windows 使用 RDP；Linux 使用 Wayland、Xorg 或 Terminal。
|
||
- 显示器：主显示器、全部显示器或自定义显示器子集。
|
||
- 分辨率：跟随窗口、1280x720、1600x900、1920x1080、2560x1440、3840x2160，或输入 200 到 8192 的自定义宽高；终端模式不使用像素分辨率。
|
||
- 启动时全屏：“客户端内”IronRDP 和源码中的 Linux Xorg 桌面窗口可用，启动后仍可用快捷键切换；Linux 新链路尚未编译验收。
|
||
- 网络策略：`Smart`、`Direct preferred` 或 `CDN preferred`。
|
||
- 双端严格零拷贝：仅在运行时报告 `linux.native_video=true` 时显示；当前 X11 zlib 软件帧路径不显示该开关。
|
||
|
||
“跟随窗口”在 `mstsc` 中写入动态分辨率配置，在 IronRDP 原生窗口中以 1600x900 建立会话并在窗口尺寸稳定 1 秒后向远端提交带 generation 的新尺寸；只有收到匹配尺寸的远端图像才确认成功。服务端不支持动态调整或 5 秒内没有确认时，原生窗口会询问是否重连应用目标尺寸；取消会保持当前会话，控制端不会静默重连。Linux X11 窗口则以 500 ms 防抖提交新的捕获上限。固定和自定义尺寸作为初始远程桌面尺寸。
|
||
|
||
IronRDP 会话异常中断时会先释放全部远端按键和鼠标状态，再按 1、2、4 秒间隔最多自动重连三次。由分辨率失败触发的重连不属于异常恢复，必须先由用户确认；确认后的目标尺寸会用于后续故障重试。窗口标题和主界面诊断会显示当前重连或 resize 状态；正常退出和用户关闭窗口不会触发重连。
|
||
|
||
`CDN preferred` 表示优先让客户端和 Agent 分别接入最近边缘节点，再通过优质骨干网传输。它不是缓存视频内容的传统静态 CDN。
|
||
|
||
当前控制端的 `edge.relay` 能力仍为 `false`，网络策略固定为 `Direct preferred`，不能通过选择框启用 CDN。仓库已经提供 Edge Presence/Allocator、透明 TCP byte relay、Windows Client 签名 Session Intent、Linux Agent 本地授权，以及只在授权成功后向双方下发 session-bound coturn 短期凭据的响应；接受的桌面会话会由两端 `webrtc-rs` PeerConnection 通过设备签名 mailbox 交换 SDP/ICE，并协商 H.264/RTX/Opus 与控制 DataChannel。Linux X11 捕获、GStreamer H.264 sender 和 Windows native-video 远端 RTP 解码/呈现均已有源码接线，但尚未解析依赖、编译或实机运行，实际 coturn POP 和双 POP 骨干也未部署验收。配置 Edge 会话授权或安装 Edge DEB 不会开放 CDN 选项。
|
||
|
||
## 8. 多显示器
|
||
|
||
Windows RDP 与 Linux Agent 的显示器来源不同：
|
||
|
||
- Windows RDP：`mstsc` 支持单屏、“全部显示器” `/multimon` 和自定义本地子集。IronRDP 原生单屏通过 RDP resize 事件跟随窗口动态调整远程桌面；选择“全部本地显示器”时，viewer 通过 Win32 枚举 2..16 个实际显示器并发送 RDPEDISP 多屏布局，窗口覆盖本地虚拟桌面。自定义显示器子集在原生模式下暂不开放。
|
||
- Linux Agent（目标设计，当前未实现）：选择被控 Linux 的 Wayland Portal 或 XRandR 显示器。Agent 保持实体桌面布局不变，只捕获所选屏幕并按编码上限缩放。
|
||
|
||
显示器可以位于主屏左侧或上方，因此协议保留负坐标。输入事件携带显示器 ID、布局 generation 和源桌面坐标；热插拔、旋转、DPI、分辨率或选择变化都会递增 generation，旧坐标事件和旧零拷贝证明立即失效。
|
||
|
||
严格零拷贝模式要求所有选中屏幕的捕获、合成、编码、解码和最终显示位于可验证的同卡路径。跨 GPU 屏幕组合只能在 Compatibility 模式中使用，并明确报告 `CrossAdapterCopy`。
|
||
|
||
## 9. GPU 与严格零拷贝
|
||
|
||
默认模式选择窗口所在显示器对应的 GPU。手动模式固定使用指定 GPU，但仍会验证完整链路：
|
||
|
||
```text
|
||
decode GPU -> render GPU -> window display GPU
|
||
```
|
||
|
||
严格模式下，三者必须位于同一 Adapter，且 Agent 端也必须证明捕获到编码过程中没有 CPU map 或跨 GPU copy。手动 GPU 与窗口显示 GPU 不同时，严格模式会拒绝会话；显式 Compatibility 模式可允许跨卡或软件路径，但界面必须显示实际降级状态。
|
||
|
||
切换 GPU、显示器或远程分辨率后，旧的零拷贝证明立即失效，双方必须使用新的 epoch 和 challenge 重新验证。
|
||
|
||
## 10. 验证原生视频管线计划
|
||
|
||
native-video Helper 支持管线规划和真实 D3D11 硬件设备探针。同卡严格模式规划：
|
||
|
||
```powershell
|
||
cargo run -p remotedesk-native-video -- --dry-run --window-adapter gpu-0
|
||
```
|
||
|
||
严格模式验证跨卡拒绝：
|
||
|
||
```powershell
|
||
cargo run -p remotedesk-native-video -- --dry-run --window-adapter gpu-0 --manual-adapter gpu-1
|
||
```
|
||
|
||
兼容模式允许跨卡并明确报告 `CrossAdapterCopy`：
|
||
|
||
```powershell
|
||
cargo run -p remotedesk-native-video -- --dry-run --window-adapter gpu-0 --manual-adapter gpu-1 --compatibility
|
||
```
|
||
|
||
`--dry-run` 输出 `d3d11_created=false` 是预期行为，只表示该命令没有调用平台 API。验证当前 Windows 是否能真实创建 D3D11 device 与 immediate context：
|
||
|
||
```powershell
|
||
cargo run -p remotedesk-native-video -- --probe-d3d11
|
||
```
|
||
|
||
H.264 decoder allocation probe 会实际创建 decoder 与 NV12 output surface，但不会把“对象可创建”标记为已完成硬解或零拷贝：
|
||
|
||
```powershell
|
||
cargo run -p remotedesk-native-video -- --probe-h264-decoder
|
||
```
|
||
|
||
使用本地 H.264 容器做真实首帧解码与 DXGI surface 验证：
|
||
|
||
```powershell
|
||
cargo run -p remotedesk-native-video -- --probe-h264-file C:\samples\baseline.mp4
|
||
```
|
||
|
||
支持 MP4、M4V、MOV，文件上限 512 MiB；不会接受 UNC 地址或把 CPU buffer 当作 DXGI 解码结果。`sample_decoded=true` 只表示真实文件产生了同 device NV12 surface，仍需查看同时输出的 `hardware_decode_verified=false` 与 `zero_copy_verified=false` 边界。
|
||
|
||
本地 DXGI surface 窗口呈现：
|
||
|
||
```powershell
|
||
cargo run -p remotedesk-native-video -- --play-h264-file C:\samples\baseline.mp4
|
||
```
|
||
|
||
播放器按媒体时间戳调度 NV12 surface，通过同一 D3D11 device 的 VideoProcessor 转换、等比缩放并写入 swap chain，不读取 CPU 原始帧。使用 `F11` 或 `Alt+Enter` 切换全屏、`Esc` 返回窗口、`Ctrl+Shift+Q` 退出。该本地文件入口不等于远程 Linux 桌面媒体链路，当前仍不会开放 `linux.native_video`。
|
||
|
||
成功时输出 `d3d11_created=true` 和实际 feature level。IronRDP viewer 已独立接入 swap chain CPU 上传呈现；本探针尚未创建视频解码器，也不能证明端到端零拷贝。
|
||
|
||
## 11. 在线升级
|
||
|
||
Windows 控制端支持在线检查和原位升级，但仓库不内置生产更新地址或信任公钥。在顶栏打开“全局设置”，于“在线升级”中同时填写 HTTPS 清单 URL 和 Base64 Ed25519 公钥，保存后可手动检查；开启“自动检查更新”时，每次打开控制端会检查一次。两项配置必须同时存在，也可以同时清空以关闭更新。
|
||
|
||
发现新版本后，顶栏会显示下载图标，设置页会显示版本、发布时间、包大小和发行说明。点击“下载并安装”并确认后，控制服务重新下载并验签清单，只接受匹配当前产品和 Windows 架构且高于当前版本的三段式版本；MSI 下载完成后校验签名清单中的精确大小和 SHA-256。控制服务随后退出，独立 helper 再次校验文件，使用 `/passive /norestart` 执行 MSI 升级，并在成功后重新启动 RemoteDesk。
|
||
|
||
更新目录和安装日志位于 `%LOCALAPPDATA%\RemoteDesk\updates`。传输必须使用 HTTPS，但 HTTPS/CDN 本身不作为发布身份：客户端只信任本机配置的 Ed25519 公钥。普通开发 MSI 仍不签名；受保护标签工作流先签署和验证控制端/Host payload 与 MSI，再对最终控制端 MSI 字节生成清单，并在版本资产发布成功后更新固定 `stable-channel`。清单生成、密钥保管和发布配置见 [在线升级](online-updates.md)。
|
||
|
||
## 12. 常见问题
|
||
|
||
### 点击连接后没有远程画面
|
||
|
||
先检查状态是否为“端口可达”。若为“端口拒绝连接”，请在被控 Windows 启用远程桌面并确认系统防火墙允许目标端口；若“连接超时”，检查地址、端口和路由。状态可达但 `mstsc` 登录失败时，应在系统窗口中检查账号、密码、NLA 和账户远程登录权限。
|
||
|
||
### 严格模式报告跨 GPU
|
||
|
||
把客户端窗口移动到手动 GPU 所连接的显示器，或改回“窗口显示器 GPU”。只有明确接受性能下降时才启用 Compatibility。
|
||
|
||
### RemoteDesk 中没有密码输入框
|
||
|
||
`mstsc` 的密码由 Windows 登录窗口和凭据管理器维护；IronRDP 的密码在独立 helper 本地遮罩窗口中保存到 Windows Credential Manager，并由 viewer 直接读取。密码不进入 RemoteDesk 的 HTTP、React 状态、`localStorage`、日志、命令行或临时 `.rdp` 文件。
|
||
|
||
### Linux Wayland 无法无人值守控制
|
||
|
||
Wayland 权限由桌面环境和 Portal 决定。首个稳定版本不会承诺控制所有桌面环境的登录界面；桌面未登录时可使用 Terminal 会话。
|
||
|
||
### 差网络下画面不稳定
|
||
|
||
完整 H.264/Opus 链路仍将使用拥塞控制、动态码率、帧率和分辨率降档，并在直连、Single Edge 和 Dual Edge 之间重新探测。当前顶栏显示控制端本地时间；Windows 在原生会话建立前显示 TCP/RDP 探针耗时，IronRDP 收到服务器 `NetworkCharacteristicsResult` 后改为显示真实会话平均 RTT，并在详情中显示基础 RTT 和服务器估算带宽。服务器未发送该结果时不会生成替代值。IronRDP 原生会话还会通过不含地址、账户、凭据和原始错误的诊断文件回传等待凭据、连接中、已连接、失败或结束状态，以及帧数、远程尺寸、本地解码处理耗时和本地呈现耗时。解码计时从网络图形 PDU 进入 IronRDP active stage 开始，覆盖 framebuffer 像素转换；输入、resize、网络 RTT 和帧间隔不会被用作替代值。RDP 服务端不提供编码耗时，因此 Windows RDP 的编码延迟仍明确显示“暂无数据”。Linux X11 helper 源码使用当前直连 WSS 或 Edge relay 内的 Ping/Pong 回传真实会话 RTT；zlib 画面回传实际采集、zlib 编码、完整性校验和软件呈现耗时。原生 H.264 画面使用 H.264 元数据中的真实采集与编码耗时，并分别测量 Windows MFT 解码和 D3D11 呈现耗时；切换确认后不再生成完整 zlib 帧，因此不会用兼容链路覆盖原生指标。最近一秒帧率只统计实际呈现的当前画面。新增指标链路尚未编译及真实主机验收。`?demo=1` 下的质量数字仅用于界面演示。
|
||
|
||
## 12. 相关文档
|
||
|
||
- [开发指南](development.md)
|
||
- [Windows 客户端设计](windows-client.md)
|
||
- [Linux Agent 设计](linux-agent.md)
|
||
- [GPU 加速](gpu-acceleration.md)
|
||
- [差网络自适应](network-adaptation.md)
|
||
- [CDN 与边缘中继](edge-relay.md)
|
||
- [在线升级](online-updates.md)
|