# RDP 浏览器黑屏 / 连接超时 — 根因定位 (2026-06-10)

## 结论（确定）

**Nexus 侧（前端 + 后端 + guacd 链路）全部正常；黑屏来自 RDP 目标主机本身。**

guacd 直连解码证明：RDP 目标 `20.189.75.225`（用户 `azureuserwindwos`）在 NLA 认证成功后，
回传的 **1024×768 主画面 PNG 是纯黑**（`nonblack=0, maxsum=0`），只附带鼠标指针等极小白色缓存图块。
这是 Windows/Azure 典型的「RDP 登录后黑屏（仅有鼠标指针）」现象。

## 证据链

| 检查项 | 方法 | 结果 |
|--------|------|------|
| guacd 握手 | `security=any` / `security=nla` | 均 `ready`（握手成功） |
| **凭据有效性** | `security=nla`（错误凭据必失败） | **握手成功 → 凭据正确**，`azureuserwindwos` 非拼写错误 |
| 帧转发 | WS 长连接探针 100s | `frames=108 sync=5` |
| **ping 回显（防超时）** | 内部空操作码 `0.,4.ping,<ts>` 每秒 | `ping_echo=100, max_gap=1.0s` → 不会触发 90s 超时 |
| **主画面像素** | 直连 guacd 解码 img/blob PNG | `1024x768 nonblack=0 maxsum=0`（纯黑） |
| 小图块 | 同上 | `41x39`/`11x16` 纯白（指针/字形缓存） |
| `resize-method=display-update` | 变体探测等 18s | 仍纯黑，无桌面重绘 |
| 浏览器端 | Playwright 生产 E2E | 到达「已连接」+ 1024×768 画布，但像素全黑 |

## 「连接超时」说明

前端 `tunnelErrorMessage` 中 `server timeout` → 浏览器 90s 内未收到任何帧。
实测 ping 回显使 `max_gap=1.0s`，当前线上 bundle 的 E2E 直接到达「已连接」而非超时。
故该提示是**更早旧缓存版本**的现象；当前版本能连上，仅表现为黑屏。

## 修复方向（在 RDP 目标 Windows VM 上，Nexus 无法代为修改）

按命中概率排序：

1. **关闭 WDDM 远程显示驱动（最常见修复）**  
   `gpedit.msc` → 计算机配置 → 管理模板 → Windows 组件 → 远程桌面服务 →
   远程桌面会话主机 → 远程会话环境 →
   **「将 WDDM 图形显示驱动程序用于远程桌面连接」= 已禁用** → 重启。
2. **重启该 VM**（Azure 门户：重启 / 重新部署 redeploy）。
3. 检查是否有残留断开会话占用 console；或登录脚本/应用全屏绘黑。
4. Azure 门户「运行命令」重启 `explorer.exe` 或图形栈。

## 复现 / 诊断脚本

- `scripts/guacd_rdp_probe.py` — 直连 guacd，解码主画面 PNG 判黑屏
- `scripts/guacd_rdp_variant.py` — `VARIANT=nla|resize|plain` 切换参数变体
- `scripts/rdp_ws_sync_check.py` — 经 WS 长连接，统计 ping 回显与帧间隔