远程桌面连接医生
- 作者仓库星标 0
- 作者更新于 2026年8月24日 07:33
- 作者仓库 claude-code-skills
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @daymade · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Windows · WSL
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
在收集证据之前,确定您要诊断的场景: 场景 · 主要特征 · 主要证据源 AVD/WVD/W365 · 用户通过工作区/网关连接到云桌面 · 连接信息面板、网关运行状况检查、UDP 短路径日志 直接 PC · 用户通过主机名或 IP 连接到指定 PC(例如家庭工作站) · RDP 协议探测、Windows 应用程序日志身份验证链、Windows 端重启事件
并行收集证据——不要做出假设。同时运行以下检查: 2A:网络接口和路由 查找:utun 接口:识别 VPN/代理 TUN 隧道(ShadowRocket、Clash、Tailscale) 默认路由优先级:哪个接口处理默认流量
这是最关键的一步。 Windows 应用程序日志包含任何网络级测试都无法揭示的传输协商详细信息。 macOS 上的日志位置:文件名为:`com.microsoft.rdc.macos_v<version>_<date>_<time>.log` 重要提示:Windows 应用程序日志时间戳为 UTC。用户的时钟和Windows 事件日志通常是当地时间。在构建时间线之前将所有时间戳转换为单个时区。
根据收集的证据,确定根本原因类别: 类别 A:VPN/代理干扰证据:Windows 应用程序源 IP 为`198.18.0.x`,STUN/TURN 通过 VPN 路由,无 UDP 连接。修复:在代理工具中添加 AVD 流量的直接规则:验证:暂时禁用 VPN/代理,重新连接 VDI,检查传输是否更改为 UDP。
应用修复后,重新连接并验证相应的症状: 对于 AVD/WVD/W365:检查连接信息 — 传输协议应显示 `UDP` 或 `UDP Multicast`。 RTT 应显着下降(例如,从 165 毫秒降至 40-60 毫秒)。使用 lsof 验证:
# Windows Remote Desktop Connection Doctor
Diagnose and fix Windows App (Microsoft Remote Desktop / AVD / WVD / W365 / direct PC) connection issues on macOS, with focus on transport protocol optimization and root-cause falsification.
> **Methodology base:** the general evidence-driven diagnosis discipline lives in the **debugging-network-issues** skill. This skill is the Windows-App / AVD transport *domain* layer — it leans toward connection-quality optimization more than root-cause falsification, so the methodology overlap is lighter.
## Background
**Azure Virtual Desktop** transport priority: **UDP Shortpath > TCP > WebSocket**. UDP Shortpath provides the best experience (lowest latency, supports UDP Multicast). When it fails, the client falls back to WebSocket over TCP 443 through the gateway, adding significant latency overhead.
**Direct PC connections** use plain RDP over TCP 3389 (usually TLS-wrapped). They have no Connection Info panel, no gateway reachability tests, and no transport optimization step. For direct PC, the dominant failure modes are:
1. The remote PC is off or unreachable (network/firewall).
2. The Windows App client has a stale or expired Microsoft work/school account that poisons the auth orchestration, leaving the connection stuck at "Configuring remote PC...".
3. The remote PC rebooted (often Windows Update), and the client cannot recover cleanly.
This skill handles both scenarios.
## Diagnostic Workflow
### Step 1: Determine the Connection Type and Symptom
Before collecting evidence, identify which scenario you are diagnosing:
| Scenario | Key Characteristic | Primary Evidence Source |
|---|---|---|
| **AVD/WVD/W365** | User connects to a cloud desktop through a workspace/gateway | Connection Info panel, gateway health checks, UDP Shortpath logs |
| **Direct PC** | User connects to a named PC by hostname or IP (e.g., a home workstation) | RDP protocol probe, Windows App log auth chain, Windows-side reboot events |
For **AVD/WVD/W365**, ask the user to provide the Connection Info from Windows App (click the signal icon in the toolbar). Key fields to extract:
| Field | What It Tells |
|-------|--------------|
| Transport Protocol | Current transport: `UDP`, `UDP Multicast`, `WebSocket`, or `TCP` |
| Round-Trip Time (RTT) | End-to-end latency in ms |
| Available Bandwidth | Current bandwidth in Mbps |
| Gateway | The AVD gateway hostname and port |
| Service Region | Azure region code (e.g., SEAS = South East Asia) |
If Transport Protocol is `UDP` or `UDP Multicast`, the connection is optimal — no further diagnosis needed.
If Transport Protocol is `WebSocket` or `TCP`, proceed to Step 2.
For **Direct PC**, the Connection Info panel does not exist. Instead, first run the **RDP protocol probe** in Step 2E to prove the server is reachable, then analyze the Windows App log for auth poisoning or reconnect failures. If the progress dialog is stuck at "Configuring remote PC...", strongly suspect client-side identity issues (see Category E).
### Step 2: Collect Network Evidence
Gather evidence in parallel — do NOT make assumptions. Run the following checks simultaneously:
#### 2A: Network Interfaces and Routing
```bash
ifconfig | grep -E "^[a-z]|inet |utun"
netstat -rn | head -40
scutil --proxy
```
Look for:
- **utun interfaces**: Identify VPN/proxy TUN tunnels (ShadowRocket, Clash, Tailscale)
- **Default route priority**: Which interface handles default traffic
- **Split routing**: `0/1 + 128.0/1 → utun` pattern means a VPN captures all traffic
- **System proxy**: HTTP/HTTPS proxy enabled on localhost ports
#### 2B: RDP Client Process and Connections
```bash
# Find the Windows App process (NOT "msrdc" — the new client uses "Windows" as process name)
ps aux | grep -i -E 'msrdc|Windows' | grep -v grep
# Check its network connections
lsof -i -n -P 2>/dev/null | grep -i "Windows" | head -20
# Check for UDP connections
lsof -i UDP -n -P 2>/dev/null | head -30
```
Key evidence to look for:
- **Source IP `198.18.0.x`**: Traffic is being routed through ShadowRocket/proxy TUN tunnel
- **No UDP connections from Windows process**: Shortpath not established
- **Only TCP 443**: Fallback to gateway WebSocket transport
#### 2C: VPN/Proxy State
```bash
# Environment proxy variables
env | grep -i proxy
# System proxy via scutil
scutil --proxy
# ShadowRocket config API (if accessible on local network)
NO_PROXY="<local-ip>" curl -s --connect-timeout 5 "http://<local-ip>:8080/api/read"
```
#### 2D: Tailscale State (if running)
```bash
tailscale status
tailscale netcheck
```
The `netcheck` output reveals NAT type (`MappingVariesByDestIP`), UDP support, and public IP — valuable even when Tailscale is not the problem.
#### 2E: Independent RDP Server Health Check (Direct PC)
This step is critical for **direct PC connections** and useful for AVD/WVD/W365 as a falsification test: it proves the server-side RDP stack is alive without relying on the Windows App client or any credentials.
Use the bundled probe script:
```bash
python3 scripts/probe_rdp_server.py <host> [port]
```
Example:
```bash
python3 scripts/probe_rdp_server.py my-pc.local 3389
```
A successful probe reports `RDP server <host>:<port> is reachable and healthy (RDP + TLS).` and means the problem is **client-side** (auth, app state, proxy, or identity). A failed probe means the problem is **server-side or network** (PC off, firewall, port unreachable, TLS interception).
See `references/direct_pc_and_auth_diagnostics.md` for detailed interpretation of probe results.
### Step 3: Analyze Windows App Logs
This is the most critical step. Windows App logs contain transport negotiation details that no network-level test can reveal.
**Log location on macOS:**
```
~/Library/Containers/com.microsoft.rdc.macos/Data/Library/Logs/Windows App/
```
Files are named: `com.microsoft.rdc.macos_v<version>_<date>_<time>.log`
**Important:** Windows App log timestamps are **UTC**. The user's clock and Windows Event logs are usually local time. Convert all timestamps to a single timezone before building a timeline.
**Per-session tracking:** each connection attempt gets a unique activity GUID in braces. Aggregate events by GUID to understand the lifecycle of one attempt. See [references/windows_app_log_analysis.md](references/windows_app_log_analysis.md) for the GUID aggregation technique and [references/direct_pc_and_auth_diagnostics.md](references/direct_pc_and_auth_diagnostics.md) for the direct-PC failure signatures.
See [references/windows_app_log_analysis.md](references/windows_app_log_analysis.md) for detailed log parsing guidance.
#### Quick Log Search
```bash
LOG_DIR=~/Library/Containers/com.microsoft.rdc.macos/Data/Library/Logs/Windows\ App
# Find the most recent log
LATEST_LOG=$(ls -t "$LOG_DIR"/*.log 2>/dev/null | head -1)
# Search for transport-critical entries (filter out noise)
grep -i -E "STUN|TURN|VPN|Routed|Shortpath|FetchClient|clientoption|GATEWAY.*ERR|Certificate.*valid|InternetConnectivity|Passed URL" "$LATEST_LOG" | grep -v "BasicStateManagement\|DynVC\|dynvcstat\|asynctransport"
```
#### Key Log Patterns
| Log Pattern | Meaning |
|-------------|---------|
| `Passed: InternetConnectivity` | Health check completed successfully |
| `TCP/IP Traffic Routed Through VPN: No/Yes` | Client detected VPN routing for TCP |
| `STUN/TURN Traffic Routed Through VPN: Yes` | Client detected VPN routing for STUN/TURN |
| `Passed URL: https://...wvd.microsoft.com/ Response Time: Nms` | Gateway reachability confirmed |
| `FetchClientOptions exception: Request timed out` | **Critical**: Client cannot get transport options from gateway |
| `Certificate validation failed` | TLS interception or DNS poisoning detected |
| `OnRDWebRTCRedirectorRpc rtcSession not handled` | WebRTC session setup not handled by client |
| `OneAuthError_InteractionRequired` | A cached Microsoft account token cannot be refreshed silently |
| `No valid refresh tokens available in the cache` | No usable cached credentials for the auth request |
| `credential completion has been canceled` | The interactive sign-in prompt was canceled |
| `GATEWAY(ERR): ... UserCancelled(8)` | Auth orchestration failed because sign-in was canceled |
| `RDP_WAN: Client connMonitor goto CMSTATE_DROPPED` | Connection monitor detected a dropped session |
| `Channel::StartWrite failed` / `GetBuffer failed` | Transport is dead; client is writing to a closed socket |
| `ParseUserData: No data of type 0xc09` | **Non-fatal** — server answered MCS Connect; proves TCP path works |
| `IHAddMouseEventToPDU` / `IHAddMouseWheelEventToPDU` | Session is alive and receiving input |
#### Compare Working vs Broken Logs
When possible, compare a log from when the connection worked (UDP) with the current log:
```bash
# Compare startup health check blocks
for f in "$LOG_DIR"/*.log; do
echo "=== $(basename "$f") ==="
grep -E "InternetConnectivity|Routed Through VPN|Passed URL|FetchClient" "$f" | head -10
echo ""
done
```
A working log will contain the full health check block (InternetConnectivity, VPN routing detection, gateway URL tests). A broken log may show these entries missing entirely, or show certificate/timeout errors instead.
### Step 4: Determine Root Cause
Based on collected evidence, identify the root cause category:
#### Category A: VPN/Proxy Interference
**Evidence**: Windows App source IP is `198.18.0.x`, STUN/TURN routed through VPN, no UDP connections.
**Fix**: Add DIRECT rules for AVD traffic in the proxy tool:
```
DOMAIN-SUFFIX,wvd.microsoft.com,DIRECT
DOMAIN-SUFFIX,microsoft.com,DIRECT
IP-CIDR,13.104.0.0/14,DIRECT
```
**Verify**: Temporarily disable VPN/proxy, reconnect VDI, check if transport changes to UDP.
#### Category B: ISP/Network UDP Restriction
**Evidence**: Even with all VPNs off, still WebSocket. No UDP connections. `FetchClientOptions` timeout.
**Verify**:
```bash
# Test STUN connectivity to a known server
python3 -c "
import socket, struct, os
header = struct.pack('!HHI', 0x0001, 0, 0x2112A442) + os.urandom(12)
for srv in [('stun.l.google.com', 19302), ('stun1.l.google.com', 19302)]:
try:
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
s.settimeout(3)
s.sendto(header, srv)
data, addr = s.recvfrom(1024)
print(f'STUN from {srv[0]}: OK')
s.close(); break
except: print(f'STUN from {srv[0]}: FAILED'); s.close()
"
```
**Fix options**:
- Try mobile hotspot (isolate home network from ISP)
- Check router NAT type (Full Cone NAT preferred)
- Enable UPnP on router
- Try IPv6 if available
- Contact ISP about UDP restrictions
#### Category C: Client Health Check Failure
**Evidence**: Log shows certificate validation errors at startup, health check block (InternetConnectivity, STUN/TURN detection) missing from log, `FetchClientOptions` timeout.
This means the client cannot complete its diagnostic/capability discovery, preventing Shortpath negotiation.
**Possible causes**:
- ISP HTTPS interception/MITM (especially in China)
- DNS poisoning returning incorrect IPs for Microsoft diagnostic endpoints
- Firewall blocking Microsoft telemetry endpoints
**Fix options**:
- Change DNS to 8.8.8.8 or 1.1.1.1 (bypass ISP DNS)
- Route Microsoft traffic through a clean proxy
- Check if ISP injects certificates
#### Category D: Server-Side Shortpath Not Enabled
**Evidence**: Log shows no STUN/TURN or Shortpath related entries at all (not even detection), but health checks pass and no errors.
This means the AVD host pool does not have RDP Shortpath enabled. This requires admin action on the Azure portal.
#### Category E: Client Identity / Expired Microsoft Account Poisoning (Direct PC and AVD)
**Evidence**: The RDP protocol probe succeeds (server is healthy), but the Windows App log shows the OneAuth/MSAL chain:
- `OneAuthError_InteractionRequired`
- `No valid refresh tokens available in the cache`
- `AcquireTokenInteractively`
- `credential completion has been canceled`
- `User canceled sign in`
- `GATEWAY(ERR): CWVDTransport::OnOrchestrationHttpError error: UserCancelled(8)`
- `Fail OnDisconnected call`
The progress dialog may stay at "Configuring remote PC..." because the app is waiting for an interactive sign-in prompt that is hidden or canceled. This can affect **direct PC connections** even when the expired account is unrelated to that PC, because the Windows App client shares the same auth orchestration across all connection types.
**Fix**: Open Windows App → Settings → Accounts, sign out or remove the stale Microsoft work/school account, then fully quit (Cmd+Q) and relaunch the app. Retry the connection.
See `references/direct_pc_and_auth_diagnostics.md` for the full signature set and troubleshooting steps.
#### Category F: Server-Side Reboot / Windows Update
**Evidence**: A previously working session dropped suddenly, followed by reconnect failures. The Windows App log shows `CMSTATE_DROPPED` and possibly `Channel::StartWrite failed`. The Windows PC's `LastBootUpTime` is close to the drop time, and Event ID 1074 shows `MoNotificationUx.exe` (Windows Update orchestrator) or another planned restart reason.
**Fix**: Wait for the PC to finish booting, then reconnect. To prevent recurrence, set active hours / disable automatic restart during active hours in Windows Update settings, or schedule reboots when the user is not using the machine.
If you have admin access, use `Get-CimInstance Win32_OperatingSystem` for `LastBootUpTime` and `Get-WinEvent` for Event ID 1074. See `references/direct_pc_and_auth_diagnostics.md` for the WSL/SSH encoded-command technique.
### Step 5: Verify Fix
After applying a fix, reconnect and verify the appropriate symptoms:
**For AVD/WVD/W365:**
1. Check Connection Info — Transport Protocol should show `UDP` or `UDP Multicast`.
2. RTT should drop significantly (e.g., from 165ms to 40-60ms).
3. Verify with lsof:
```bash
lsof -i UDP -n -P 2>/dev/null | grep -i "Windows"
# Should show UDP connections if Shortpath is active
```
**For Direct PC:**
1. The progress dialog should disappear and the session window should appear.
2. The Windows App log for the new session should show mouse/keyboard input events (`IHAddMouseEventToPDU`, `IHAddKeyboardEventToPDU`) and no `UserCancelled(8)` errors.
3. If the issue was an expired Microsoft account, confirm that only valid accounts remain in Windows App → Settings → Accounts.
**For server reboots:**
1. Verify the PC is reachable again with `ping` and `scripts/probe_rdp_server.py`.
2. Confirm `LastBootUpTime` is recent and matches the outage window.
## References
- [references/windows_app_log_analysis.md](references/windows_app_log_analysis.md) — Detailed log parsing patterns, error signatures, GUID lifecycle analysis, and comparison methodology
- [references/avd_transport_protocols.md](references/avd_transport_protocols.md) — How AVD transport selection works, STUN/TURN/ICE overview, Shortpath architecture
- [references/direct_pc_and_auth_diagnostics.md](references/direct_pc_and_auth_diagnostics.md) — Direct PC connection failures, expired Microsoft account poisoning, RDP protocol probe usage, Windows-side reboot correlation, stuck-dialog vs. live-session discrimination
- [scripts/probe_rdp_server.py](scripts/probe_rdp_server.py) — Standalone RDP protocol + TLS health probe
按说明文件中的顺序排列。
背景
步骤 1:确定连接类型和症状
第二步:收集网络证据
步骤 3:分析 Windows 应用程序日志
第 4 步:确定根本原因
文件/命令 -> UDP · UDP Multicast · WebSocket · TCP · 0/1 + 128.0/1 → utun · 198.18.0.x · netcheck · MappingVariesByDestIP
内容校验值 -> 40885f732cb3
当前原文的自动摘译,尚未人工审校。
背景
Azure 虚拟桌面传输优先级:UDP 短路径 > TCP > WebSocket。 UDP Shortpath 提供最佳体验(最低延迟,支持 UDP 组播)。当失败时,客户端会通过网关回退到 TCP 443 上的 WebSocket,从而显着增加延迟开销。直接 PC 连接使用基于 TCP 3389 的普通 RDP(通常采用 TLS 封装)。他们没有连接信息面板,没有网关可达性测试,也没有传输优化步骤。对于直接 PC,主要的故障模式是: