From 05ac76daae784dab18e4748f17ccfd207c264db8 Mon Sep 17 00:00:00 2001 From: Haitao Pan Date: Mon, 8 Jun 2026 21:09:23 +0800 Subject: [PATCH] docs: document remote desktop session contention --- ...rtc-remote-desktop-white-screen-runbook.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/runbooks/webrtc-remote-desktop-white-screen-runbook.md b/docs/runbooks/webrtc-remote-desktop-white-screen-runbook.md index 1ada12d..60d7467 100644 --- a/docs/runbooks/webrtc-remote-desktop-white-screen-runbook.md +++ b/docs/runbooks/webrtc-remote-desktop-white-screen-runbook.md @@ -133,6 +133,28 @@ ssh ubuntu@xworkmate-bridge.svc.plus ' - 问题在 Flutter renderer / track attach / view lifecycle / stale stream。 +### 5. Bridge RTP 增长，但同一 `sessionId` 被反复 stop/start + +判断： + +- Bridge 日志里 `WebRTC RTP stats` 持续增长，`writeErrors=0` +- 同一时间段频繁出现： + +```text +Stopping Remote Desktop session: remote-desktop-session +Starting Remote Desktop session: remote-desktop-session +Closing WebRTC server... +``` + +- 本机同时存在多个 `XWorkmate` 进程，或快速断开 / 重连 / 重开窗口 +- APP 仍停在 `WebRTC 已连接，正在等待远程桌面首帧...` + +说明： + +- 问题不是编码器或公网 RTP 发送层，而是客户端会话抢占 / stale PeerConnection。 +- APP 旧版本固定使用 `remote-desktop-session`，多个 app 实例或重连会互相关闭同一个远端 desktop session。被抢占的客户端可能还短暂保持 `connected` 状态，但远端 RTP pipeline 已经被新 offer 替换，表现为等待首帧。 +- 修复方式是 APP 每个 DesktopView / PeerConnection 使用唯一 desktop session id，并且 video-only desktop offer 不再声明无用 audio recvonly transceiver。 + ## 本次修复结论 本次真实根因不是单纯网络延迟，而是两段串联问题： @@ -144,6 +166,12 @@ ssh ubuntu@xworkmate-bridge.svc.plus ' 3. Caddy 公网入口曾只放行主 `BRIDGE_AUTH_TOKEN`，未放行 user service 中的 `BRIDGE_REVIEW_AUTH_TOKEN`。因此 `review@svc.plus` 会看到 `Bridge token expired or rejected`，并且无法发起 `xworkmate.desktop.offer`。 +2026-06-08 复发排查结论： + +4. Bridge 运行版本 `v1.0-beta2` / commit `0a0d04f` 的 H.264 和 RTP 发送链路是健康的：远端日志确认 `format=(string)I420`、`profile=(string)baseline`、`profile-level-id=(string)42c01f`，并且 `WebRTC RTP stats` 持续增长、`writeErrors=0`。 +5. 本机同时运行了多个 `XWorkmate` 进程，且 APP 侧仍使用固定 `sessionId='remote-desktop-session'`。远端日志在同一时间段反复出现同一个 session 的 stop/start，说明新连接抢占并关闭旧 PeerConnection / capture pipeline。这个链路会让被抢占的 APP 视图停在“WebRTC 已连接，正在等待远程桌面首帧...”，属于客户端会话生命周期问题。 +6. 同步修复 APP：为每个 DesktopView 生成唯一 `remote-desktop-*` session id，并将 desktop SDP offer 简化为 video recvonly，避免 video-only Bridge 被无用 audio m-line 干扰。 + 修复后的稳定策略： - 强制把 capture 输出转换到 `I420` @@ -153,6 +181,8 @@ ssh ubuntu@xworkmate-bridge.svc.plus ' - `x264enc` 启用 `zerolatency` - Bridge 定期输出 RTP stats - APP 在等待首帧时输出 inbound video stats +- APP 每个远程桌面视图使用唯一 desktop session id，避免多实例 / 重连抢占同一个 Bridge session +- APP desktop offer 只声明 video recvonly transceiver，避免无用 audio m-line 增加协商不确定性 - Caddy 公网入口同时放行主 token 与 review token，并验证无 token 仍为 `401` - 只保留 user service 作为当前 bridge origin，避免 system service 与 user service 抢占 `127.0.0.1:8787` @@ -172,6 +202,12 @@ APP 诊断： - `/Users/shenlan/workspaces/ai-workspace-lab/xworkmate-app/lib/features/desktop/desktop_view.dart` - `/Users/shenlan/workspaces/ai-workspace-lab/xworkmate-app/test/features/desktop/desktop_client_test.dart` +2026-06-08 复发修复 APP 落点： + +- `desktop_client.dart`：新增唯一 desktop session id helper；desktop offer 只添加 video recvonly transceiver。 +- `desktop_view.dart`：不再硬编码 `remote-desktop-session`。 +- `desktop_client_test.dart`：覆盖并行 app 实例生成不同 session id。 + ## 期望日志 健康的编码与 RTP 发送链路应该出现下面这类信号：