Apollo 虚拟桌面连不上？3步修复 SudoVDA "Watchdog Failed" 驱动异常

【免费下载链接】ApolloSunshine fork - The easiest way to stream with the native resolution of your client device项目地址: https://gitcode.com/gh_mirrors/apollo18/Apollo

用 Apollo 做自托管串流主机时，Windows 上的虚拟桌面靠 SudoVDA 驱动来承载。如果它在 Audio/Video 页面提示SudoVDA Driver status: Watchdog Failed，说明虚拟显示器建不出来，推流自然失败。跟着下面的排查路线走一遍，重置显示设备缓存并重启后，通常几分钟内就能恢复。

30秒定位：驱动状态提示出现在哪

Apollo 的虚拟显示由 SudoVDA 驱动创建，驱动状态就显示在 Web 配置界面Audio/Video页底部，格式是SudoVDA Driver status: <状态>：

• Ready：驱动正常，问题不在驱动这一层。
• Version Incompatible：驱动版本与当前 Apollo 不匹配，优先更新驱动。
• Watchdog Failed：看门狗心跳超时，Apollo 已主动关闭虚拟显示设备句柄，虚拟桌面创建失败基本卡在这一步。

为什么看门狗超时会卡住虚拟桌面

• Windows 用注册表缓存记录显示设备身份，虚拟显示器频繁创建/销毁会积累大量过期条目。
• 缓存里的旧设备信息和新虚拟显示器对不上时，设备枚举就会混乱，最终表现为 Watchdog Timeout，新建的虚拟显示器识别不出来。
• 这也是"同一台主机换个客户端就能连"这类怪现象的常见根源：残留的设备身份缓存在不同客户端间串了位。

3步重置显示设备缓存

1. 打开 Apollo Web 界面，进入Troubleshooting（故障排查）页——只有 Windows 平台会显示下面的重置卡片。
2. 在Reset Persistent Display Device Settings（重置持久化显示设备设置）卡片中点击同名按钮，等待提示。
3. 看到Success resetting persistence!后，在同页点击Restart Apollo（重启 Apollo），让配置重新生效。

该操作对应的后端接口是 POST/api/reset-display-device-persistence，见 docs/api.md。如果弹出Error while resetting persistence!，说明重置未成功，直接去下面核对日志。

重置后核对清单 📋

• 开始推流时应新增一块虚拟显示器，结束推流后自动移除；若始终没有变化，多半是驱动未正确配置，或系统里还有别的常驻虚拟显示方案在占用——README 明确建议移除其他虚拟显示方案以避免身份冲突。
• 回到Audio/Video页确认SudoVDA Driver status已变回Ready。
• 客户端连接后，确认显示分辨率/刷新率仍按客户端请求自动匹配，说明设备身份缓存已重建。

日志里还能确认什么

在Troubleshooting页底部Logs（日志）区，用过滤框输入Watchdog或SUDOVDA：

• 出现[SUDOVDA] Watchdog: Timeout ...：驱动心跳确实超时，属本次故障特征，重置+重启后应消失。
• 出现[SUDOVDA] Watchdog fetch failed!：连驱动状态都读不到，优先检查 SudoVDA 驱动是否安装并启用。

其他 Windows 侧常见问题（手柄、权限等）可参考 docs/troubleshooting.md。

最后两条建议

1. 把 SudoVDA 驱动更新到最新版本并确认已启用，这是拦截Version Incompatible和Watchdog Failed的第一道防线。
2. 重置按钮报错时不要反复点击，先翻 Logs 定位是驱动层还是 Apollo 层的问题，再决定下一步动作。

【免费下载链接】ApolloSunshine fork - The easiest way to stream with the native resolution of your client device项目地址: https://gitcode.com/gh_mirrors/apollo18/Apollo