驱动安装排障指南

[qiin2333]

驱动安装排障指南

Sunshine Foundation 集成了两个自定义驱动：

• ZakoVDD — 虚拟显示器驱动（IddCx）
• ZakoVirtualMouse — 虚拟鼠标驱动（UMDF HID）

常见问题

1. 驱动安装失败

症状: 安装过程中提示驱动安装失败，或安装完成后设备管理器中看不到虚拟设备

解决方案:

1. 确认 Windows 版本 ≥ Windows 10 1903
2. 以管理员身份运行安装程序
3. 如果使用测试签名驱动，需要开启测试模式：

   bcdedit /set testsigning on

   然后重启电脑

2. 虚拟显示器 (ZakoVDD) 不工作

症状: 串流时 Moonlight 客户端黑屏或无法捕获画面

排查步骤:

1. 打开设备管理器 → 显示适配器，确认 ZakoVDD 存在且无感叹号
2. 检查显示设置中是否出现虚拟显示器
3. 确认 vdd_settings.xml 配置正确（分辨率/刷新率）
4. 尝试手动启用/禁用虚拟显示器

3. 虚拟鼠标 (ZakoVirtualMouse) 不工作

症状: 串流时鼠标移动异常或无法点击

排查步骤:

1. 打开设备管理器 → 人体学输入设备 (HID)，确认虚拟鼠标存在
2. 检查 Sunshine 日志中是否有 HID 相关错误
3. 确认没有其他虚拟鼠标驱动冲突

4. 驱动更新

新版本 Sunshine Foundation 会自动更新驱动。如需手动更新：

1. 在设备管理器中卸载旧驱动
2. 重新运行安装程序

---

如果以上步骤无法解决问题，请在下方附上：

1. Windows 版本信息
2. 设备管理器截图
3. Sunshine 日志文件

[dukiii1928]

[Bug]: 冷启动后 Zako VDD 无法切换为唯一显示器，重新枚举 NVIDIA 设备后立即恢复

🏷️ 问题类型

虚拟显示器 / Windows 显示拓扑问题

📝 问题描述

Windows 冷启动或重启后，Sunshine 可以创建并配置 Zako 虚拟显示器，也能正确收到 Moonlight 请求的分辨率，但 Windows 无法将显示拓扑切换为“仅启用 Zako 虚拟显示器”。

失败时返回：

ERROR_GEN_FAILURE
failed to create new topology configuration
设置拓扑失败

此时物理显示器不会关闭，Sunshine 最终捕获物理显示器的 2560x1440 桌面，并缩放编码为客户端请求的 2340x1080。

仅执行一次 NVIDIA 显示设备重新枚举后，不重启 Sunshine、不重启 Zako、不更改任何配置，Zako-only 拓扑立即恢复正常，并且可以连续多次串流。

🔄 稳定复现步骤

1. 在安全模式使用 DDU 完整卸载 NVIDIA 驱动。
2. 进入正常 Windows，安装 NVIDIA 616.56。
3. 安装完成后暂不重启电脑。
4. 使用 Moonlight 串流，Zako VDD 工作正常：
   • 物理显示器自动关闭；
   • Zako 成为唯一显示器；
   • 桌面和编码均为 2340x1080；
   • 连续测试三次均正常。
5. 重启电脑。
6. 再次使用同一 Moonlight 客户端和相同设置串流。
7. Zako 创建成功，但 Windows 切换拓扑失败，物理显示器仍保持启用。
8. 重启 Sunshine 服务，无效。
9. 重新启动 Zako Display Adapter，无效。
10. 执行以下命令重新枚举 NVIDIA 显示设备：

pnputil /restart-device "PCI\VEN_10DE&DEV_2C05&SUBSYS_20007377&REV_A1\91D6BE02BE2DB04800"

11. 不更改任何 Sunshine 配置，再次串流，立即恢复正常。

🔁 可复现性

重启 Windows 后 100% 复现。

重新启动 NVIDIA 显示设备后 100% 恢复，且可连续多次正常创建和销毁 Zako VDD。

💻 系统环境

• 操作系统：Windows 11
• Windows 版本：10.0.26200.9168
• Sunshine：v2026.827.104139.杂鱼
• GPU：NVIDIA GeForce RTX 5070 Ti
• NVIDIA 驱动：616.56
• 驱动内部版本：32.0.16.1656
• 编码器：NVENC
• 捕获方式：VDD
• Zako VDD：100.0.17.2
• Zako 驱动日期：2026-07-31
• Zako 设备实例：ROOT\DISPLAY\0000
• Zako 驱动包：oem271.inf

📱 客户端

• Android Moonlight
• 客户端设备：Samsung Galaxy S24 Ultra
• 请求分辨率：2340x1080
• 请求刷新率：60Hz
• HDR：启用时也能复现

⚙️ 相关 Sunshine 配置

adapter_name = NVIDIA GeForce RTX 5070 Ti
address_family = both
av1_mode = 3
capture = vdd
display_device_prep = ensure_only_display
dynamic_resolution_follow_display = true
encoder = nvenc
fps = [60,90,120,144]
gamepad = x360
hevc_mode = 3
locale = zh
notify_pre_releases = true
output_name = ZakoHDR
resolutions = [1280x720,1920x1080,2560x1080,2560x1440,2560x1600,3440x1440,3840x2160,2340x1080,3120x1440]
setup_wizard_completed = true
upnp = enabled
vdd_reuse = enabled

❌ 冷启动后的失败日志

Info: VDD live mode list updated via SETMODES: 36 modes; requested 2340x1080@60Hz
Info: VDD会话模式列表更新完成（未写入XML）: 2340x1080@60
Info: 创建虚拟显示器
Info: 成功配置VDD设备
Info: 使用pre-VDD设备列表: 2个物理显示器
Info: 应用vdd_prep: 关闭物理显示器
Info: vdd_prep 目标拓扑: [[{ZAKO_DEVICE_GUID}]]

Warning: [code: ERROR_GEN_FAILURE]
failed to change topology using the topology from Windows DB!
Asking Windows to create the topology.

Error: [code: ERROR_GEN_FAILURE]
failed to create new topology configuration!

Error: 设置拓扑失败
Warning: Display configuration failed; continuing with current display settings
Info: Client requested stream resolution (clientViewport): 2340x1080
Info: Desktop resolution [2560x1440]
Info: Initial display: 2560x1440, encoding: 2340x1080, scale: 0.914062x0.75

后续 VDD 直接捕获也会失败：

Warning: [vdd] no valid sealed VDD producer found for 2560x1440
Warning: [vdd] no valid VDD producer found
Warning: [vdd] direct capture initialization failed; trying DDX capture

✅ 重新启动 NVIDIA 设备后的成功日志

执行：

pnputil /restart-device "PCI\VEN_10DE&DEV_2C05&SUBSYS_20007377&REV_A1\91D6BE02BE2DB04800"

随后日志变为：

Info: VDD live mode list updated via SETMODES: 36 modes; requested 2340x1080@60Hz
Info: 创建虚拟显示器
Info: 成功配置VDD设备
Info: 使用pre-VDD设备列表: 2个物理显示器
Info: 应用vdd_prep: 关闭物理显示器
Info: vdd_prep 目标拓扑: [[{ZAKO_DEVICE_GUID}]]
Info: 成功应用vdd_prep设置

Info: Desktop resolution [2340x1080]
Info: Display refresh rate [60Hz]
Info: Client requested stream resolution (clientViewport): 2340x1080

Info: [vdd] resolved sealed monitor index 0 for 2340x1080
Info: [vdd] backend ready
Info: Initial display: 2340x1080, encoding: 2340x1080, scale: 1x1

重新枚举后，VDD producer 使用了重新生成的 DXGI adapter LUID：

[vdd_capture] opened sealed monitor 0 2340x1080
luid=11794218:0

🔍 已完成的排除测试

以下操作均无法解决冷启动后的问题：

• 重启 Sunshine 服务；
• 将 Sunshine 改为延迟启动；
• 重新启动 Zako Display Adapter；
• 卸载并重新安装 Zako VDD；
• 删除并重新配对 Moonlight 客户端；
• 删除客户端尺寸/HDR 配置；
• 修改 Moonlight 请求分辨率；
• 修改 Sunshine 分辨率列表；
• 启用或禁用 vdd_reuse；
• 暂时禁用 UU/GameViewer Virtual Display Adapter；
• 暂时禁用 ToDesk Virtual Display Adapter；
• 只保留 NVIDIA、物理显示器和 Zako VDD 后重启，问题仍然存在。

NVIDIA 设备重新枚举前后使用的驱动版本始终是 616.56 / 32.0.16.1656，因此恢复并不是驱动版本发生变化。

📋 Windows 事件记录

冷启动时曾出现 Zako UMDF 驱动初始加载警告：

Provider: Microsoft-Windows-Kernel-PnP
Event ID: 219
Device: ROOT\DISPLAY\0000
Driver: \Driver\WUDFRd
Status: 0xC0000365

系统稍后显示 Zako 设备状态为 Started，但 Sunshine 调用 Windows DisplayConfig 创建 only-display 拓扑时仍返回 ERROR_GEN_FAILURE。

另外，部分重启/关机过程中出现：

Application: Sunshine.exe
Faulting module: KERNELBASE.dll
Exception code: 0x80000003

该崩溃可能属于退出清理问题，不确定是否与拓扑故障直接相关。

🧠 初步判断

现象更像是 Windows 冷启动后，NVIDIA 显示 miniport 与 Windows DisplayConfig 建立的显示路径或拓扑状态异常。

Zako 设备本身能够：

• 接受 SETMODES；
• 创建虚拟显示器；
• 返回设备 GUID；
• 接受硬件光标 IOCTL。

真正失败的位置是将显示拓扑切换为仅包含 Zako VDD。

重新启动 Zako 设备无效，而重新启动 NVIDIA 设备立即恢复，可能涉及：

• 冷启动后的 NVIDIA display source/path 状态；
• DisplayConfig 数据库中的失效路径；
• DXGI adapter LUID 或 source/target 关联未刷新；
• NVIDIA 与 Zako IDD 初始化顺序；
• Zako VDD 创建时使用了尚未完全可用的物理 GPU 显示路径；
• SetDisplayConfig 在当前路径状态下返回 ERROR_GEN_FAILURE。

🛠️ 当前临时解决方法

开机后执行一次：

pnputil /restart-device "PCI\VEN_10DE&DEV_2C05&SUBSYS_20007377&REV_A1\91D6BE02BE2DB04800"

执行时物理显示器会短暂黑屏，随后 Sunshine/Zako 恢复正常。

目前将其设置为开机延迟执行可以稳定规避问题，但希望能够从驱动初始化、拓扑刷新或错误重试逻辑上解决，而不是每次启动后重新枚举 NVIDIA 设备。

🙏 希望开发者协助确认

1. Zako 创建完成后，Windows DisplayConfig 返回 ERROR_GEN_FAILURE 时，是否需要重新枚举或刷新 GPU display paths？
2. 是否存在冷启动后缓存了失效 adapter LUID/source path 的可能？
3. ensure_only_display 是否可以在 ERROR_GEN_FAILURE 后重新查询路径并延迟重试？
4. Zako VDD 是否可能早于 NVIDIA 显示路径完全初始化？
5. 能否在拓扑创建失败时记录具体的 DISPLAYCONFIG_PATH_INFO、source/target adapter LUID 和 mode index，便于进一步对比重启 NVIDIA 设备前后的差异？
6. 是否建议在此环境使用其他 Zako VDD 版本，或者已有相关修复分支可供测试？

[Yundi339]

#1003