Sunshine 虚拟显示器(ZakoVDD)前置条件闭环:状态契约、安装/修复入口与快速失败设计

原创2026-10-02 10:54:461,910 阅读
文章标签:音视频视频处理音频处理桌面应用跨平台网络

Sunshine 虚拟显示器(ZakoVDD)前置条件闭环:状态契约、安装/修复入口与快速失败设计

本文基于 docs/vdd-prerequisite-closure.md 设计文档,并结合本仓库(foundation-sunshine,Sunshine fork)的源码、测试与随附脚本展开。它系统讲解 ZakoVDD 虚拟显示器驱动前置条件如何从"模糊状态"走向"可判定的状态契约",以及桌面 GUI、Core 运行时与 Web 三条路径如何围绕同一契约实现安装、修复、快速失败与用户引导。读完你将掌握:VDD 状态如何被分类、is_usable() 可用性不变量的判定依据、GET /api/vdd/status 与 window.vddDriver 桥的调用关系、随附的 install-vdd.bat / uninstall-vdd.bat / vdd_rc_smoke.ps1 脚本用法,以及发布候选阶段的干净主机验证清单。

问题背景:为什么 VDD 前置条件需要一个"闭环"

Sunshine 有多个功能依赖 ZakoVDD 虚拟显示驱动,但绝大多数入口点此前并不区分以下几种截然不同的状态:

  • VDD 适配器驱动已安装且健康;
  • 驱动已安装但不可用或不兼容;
  • VDD 虚拟显示器(monitor)当前处于激活状态;
  • 驱动完全未安装。

这种"一锅端"的处理方式带来了多个实际后果:

  1. 设置向导在驱动缺失时仍推荐 VDD;
  2. 桌面 VDD 页面在没有驱动配置时回退到可编辑的默认值(给用户一种"可以配置"的假象);
  3. 流启动会耗费时间反复重试一个根本不可能存在的控制通道;
  4. 用户最终只得到一个泛化的"流失败"错误,除了重新运行安装器外没有恢复路径。

设计文档的目标不是简单加一个"检查驱动是否安装"的标志,而是建立一套状态契约:让 Core、桌面 GUI、Web 和托盘共享同一套状态词汇与判定逻辑,并把"驱动不可用"从流启动之前就拦截下来。

目标与非目标

Goals

  1. 继续保持 VDD 作为设置向导中的推荐选择(不因前置条件缺失而改推荐);
  2. 在保存引导式设置或改变显示拓扑之前检测前置条件;
  3. 在桌面 GUI 中提供安装/修复入口,复用 Sunshine 随附的驱动载荷(bundled payload);
  4. 驱动安装后进行验证,并将用户带回被中断的操作;
  5. 给独立的浏览器用户一个准确的状态和具体的宿主机侧操作指引;
  6. 避免静默安装驱动、自动重启,或流会话进行中执行修复。

Non-goals

  • 不做通用的 Core 驱动管理任务框架;
  • 不在运行时下载驱动(只使用随附载荷);
  • 不把"当前有 VDD monitor 激活"等同于"驱动已安装"(两者独立);
  • 不阻止高级用户在尚未完成驱动安装时保存一份他们打算稍后补全的配置。

状态契约:Core 与桌面 GUI 共用的状态词汇

Core 和桌面 GUI 暴露同一套紧凑的状态词汇。Core 的快速探测(fast probe)可能无法获取某些事实,此时这些字段保持为空。

state:
  ready | degraded | not_installed | unhealthy | reboot_required |
  payload_missing | unsupported | unknown

facts:
  installed
  running
  control_available
  installed_version
  bundled_version
  version_match
  monitor_active
  problem_code
  status_text

关键语义

  • monitor_active 独立于 installed 和 running。UI 动作完全由 state 派生,后端不需要第二个"推荐动作"枚举。这意味着:即使驱动健康,也可能当前没有激活的虚拟显示器;反之,一个已安装但失效的驱动也可能残留激活的显示器。

  • control_available 属于"可用性不变式"的一部分,而不是建议性元数据。它报告驱动是否发布了控制接口 GUID_DEVINTERFACE_ZAKO_VDD_CONTROL。一个"已安装但不吭声"的适配器是无法被驱动的,因此:

    • is_usable()(见 src/display_device/vdd_utils.h);
    • Web 侧的 vddReady computed 属性;
    • 安装器的"是否保留健康既有安装"(reconciliation)决策;

    三者都要求 control_available 为真。一个已安装且 running、但从未发布控制接口的适配器会被归类为 degraded,并走修复(reconcile)路径,而不是被当作健康的既有安装予以保留。

源码印证:状态分类与可用性判定

classify_vdd_state 与 vdd_status_t::is_usable() 在 src/display_device/vdd_utils.h 中以 constexpr 实现,逻辑完全对应文档契约:

constexpr bool
is_usable() const {
  return installed && problem_code_valid && running && control_available;
}

constexpr std::string_view
classify_vdd_state(bool installed, bool running, bool control_available,
                   bool problem_code_valid, std::uint32_t problem_code) {
  if (!installed) {
    return "not_installed";
  }
  if (!problem_code_valid) {
    return "unknown";
  }
  if (!running) {
    return problem_code == 14 ? "reboot_required" : "unhealthy";
  }
  return control_available ? "ready" : "degraded";
}

get_vdd_status() 在 src/display_device/vdd_utils.cpp 中通过 vdd_ioctl::query_adapter_status() 与 vdd_ioctl::ping() 完成只读探测:installed 来自适配器是否存在,running 由"已安装 + problem code 有效且为 0"推导,control_available 则通过向控制接口发送 ping 确认;monitor_active 通过按友好名查找 ZakoVDD 设备判定,与安装状态彼此独立。

单测 tests/unit/test_vdd_prerequisite.cpp 逐项固定了这些判定:

classify_vdd_state(false, false, false, false, 0)  == "not_installed"
classify_vdd_state(true,  false, false, false, 0)  == "unknown"
classify_vdd_state(true,  false, false, true,  14) == "reboot_required"
classify_vdd_state(true,  false, false, true,  10) == "unhealthy"
classify_vdd_state(true,  true,  false, true,  0)  == "degraded"
classify_vdd_state(true,  true,  true,  true,  0)  == "ready"

以及"只有已安装、running 且控制接口可用的驱动才 usable"的递增断言:单独置位 installed、running、problem_code_valid 均不改变 is_usable() == false,直到 control_available = true 才变为可用——这正是文档强调的"可用性不变式"。

架构:三条路径如何收敛到同一契约

桌面管理路径(Tauri 控制面板)

Tauri 控制面板拥有安装与修复的最终执行权。它复用现有的 bat_runner::run_elevated() 实现和随附脚本:

  • install-vdd.bat --probe-only:只做详细、非变更(non-mutating)的状态探测;
  • install-vdd.bat:幂等安装/修复到随附的兼容版本;
  • uninstall-vdd.bat:卸载。

桌面外壳中内嵌的 Web UI 会收到一个 window.vddDriver 桥,与既有的 virtual-mouse 和 ViGEm 桥模式一致。不会新增有特权的 Core HTTP 操作端点——安装/卸载这类变更动作被刻意限制在桌面进程内,通过 UAC 提权执行。

脚本本体位于 src_assets/windows/misc/vdd/install-vdd.bat 与 src_assets/windows/misc/vdd/uninstall-vdd.bat,二者都委托给 PowerShell 实现 vdd-device-helper.ps1。从该 helper 的开头可以看到关键事实:

  • 硬件 ID 为 Root\ZakoVDD(旧路径 ROOT\iddsampledriver 已废弃);
  • 显示设备类 GUID 4d36e968-e325-11ce-bfc1-08002be10318;
  • 驱动服务名 ZAKO_HDR_FOR_SUNSHINE;
  • 控制接口 GUID DA9F8C2B-7E4F-49A1-9D4E-6F2B0E1A0C4D;
  • 必需的驱动文件 ZakoVDD.inf、ZakoVDD.dll、zakovdd.cat、ZakoVDD.cer;
  • 通过 cfgmgr32.dll(CM_* 系列)读取设备状态与 problem code,并对控制接口列表进行枚举。

install-vdd.bat 支持三个开关:--resolve-only(仅解析)、--probe-only(仅探测,不改变已安装驱动)、--preserve-healthy-existing(保留健康既有安装)。

Core 运行时路径

Core 在 VDD 准备(VDD preparation)之前执行一次快速、非变更的原生探测。该探测检查适配器/控制传输,不创建显示器。Core 同时暴露 GET /api/vdd/status,让独立浏览器也能解释问题所在。

如果一次启动要求 VDD 而驱动缺失或不健康,启动会在拓扑被保存或修改之前就失败。启动响应区分两个稳定的错误码:

  • VDD_DRIVER_NOT_INSTALLED:驱动未安装;
  • VDD_DRIVER_UNAVAILABLE:驱动已安装但不可用。

两者都指引用户前往桌面 VDD 页面处理。

源码印证:HTTP 状态端点与守卫式 monitor 创建

GET /api/vdd/status 注册在 src/confighttp.cpp:

void
getVddStatus(resp_https_t response, req_https_t request) {
  if (!authenticate(response, request)) return;

  const auto status = display_device::vdd_utils::get_vdd_status();
  send_response(response, nlohmann::json {
    {"status", true},
    {"state", status.state},
    {"installed", status.installed},
    {"running", status.running},
    {"control_available", status.control_available},
    {"monitor_active", status.monitor_active},
    {"problem_code_valid", status.problem_code_valid},
    {"problem_code", status.problem_code},
    {"version_supported", false},
  });
}

注意该端点要求认证(authenticate),且只暴露只读探测结果,version_supported 固定为 false——版本比对等更详细的事实由桌面桥提供。

而最低层级的显示器创建原语 create_vdd_monitor() 在 src/display_device/vdd_utils.cpp 中本身就是"fail fast"的:

bool
create_vdd_monitor(const std::string &client_identifier, ...) {
  const auto status = get_vdd_status();
  if (!status.is_usable()) {
    const auto error_code = status.installed ? "VDD_DRIVER_UNAVAILABLE"
                                             : "VDD_DRIVER_NOT_INSTALLED";
    BOOST_LOG(error) << error_code << ": ZakoVDD must be installed and healthy "
                     << "before creating a virtual display. ...";
    return false;
  }
  // ... CREATEMONITOR IOCTL
}

也就是说,即使上层入口漏判,底层原语也会在发送 CREATEMONITOR 之前再次校验 is_usable(),从而保证"不会在拓扑被修改之前等待 legacy 管道重试"。

Web 状态组合式(composable)

Web 侧新增的 useVddStatus composable(src_assets/common/assets/web/composables/useVddStatus.js)优先使用 window.vddDriver 桥,回退到 /api/vdd/status:

  • refreshVddStatus():若 window.vddDriver.getStatus 存在则调用之,否则请求 apiJson('/api/vdd/status');
  • installVdd():仅当 window.vddDriver.install 存在(即运行在桌面外壳中)时才可用,否则抛出"VDD 安装仅在宿主机上的 Sunshine 桌面应用中可用";
  • vddReady computed:要求 installed && running && control_available 且 state 属于 ['ready', 'degraded']——与后端 is_usable() 语义一致(degraded 在本处被当作"可用但需注意版本"处理);
  • 空状态常量 EMPTY_STATUS 覆盖全部字段,避免探测失败时出现"假配置"。

Web 单测 src_assets/common/assets/web/tests/vddStatus.test.js 覆盖了浏览器回退、桌面桥优先、未安装→就绪的过渡等场景。

UX 策略:不同入口的差异化策略

  • 设置向导:硬前置条件门(hard prerequisite gate)。VDD 保持选中状态,主操作按钮变为 Install and continue(安装并继续)或 Repair and continue(修复并继续)。对应实现见 src_assets/common/assets/web/components/SetupWizard.vue:第 3 步选择虚拟显示器且 !vddReady 时显示前置条件警示,并在保存/继续前重新刷新状态。
  • 高级配置:内联警告 + 恢复入口,但允许保存(为分阶段/远程配置留出空间)。
  • 运行时(流启动):硬门 + 可操作的错误提示。
  • 桌面 VDD 设置页:不可用状态时,编辑器被替换为状态 + 修复面板;验证成功后才恢复编辑器——绝不展示"虚假的可编辑默认值"。
  • 托盘创建动作:前置条件不可用时打开 VDD 设置页,而不是变成一个禁用的死胡同。
  • 托盘 keep-enabled / headless-create 动作与远程 VDD 快捷方式:遵循同样的前置条件策略;而"禁用一个已配置的选项"仍然可用。
  • 通用提示组件见 src_assets/common/assets/web/components/common/VddPrerequisiteNotice.vue,它加载同一 composable,在非就绪状态渲染警告并暴露"刷新状态"入口。

交付变更(三个 Change,同一版本发布)

Change 1:桌面闭环

  • 新增 Tauri 命令:get_vdd_status、install_vdd_driver、脚本支撑的 uninstall_vdd_driver;
  • 替换旧卸载路径(旧路径针对 ROOT\iddsampledriver,现改为 Root\ZakoVDD);
  • 向注入的 Web UI API 增加 VDD 桥;
  • 桌面 VDD 编辑器以验证后的状态为门槛;
  • 流会话进行中拒绝安装,并在可能干扰正在激活的 VDD monitor 前给出警告。

Change 2:Core 快速失败

  • 新增快速 VDD 前置条件探测与已认证的 GET /api/vdd/status;
  • VDD 准备返回类型化结果,并传播 monitor 创建失败;
  • 适配器不存在时跳过 legacy 管道重试;
  • 返回稳定的 VDD 启动错误与可操作提示。

Change 3:Web 入口

  • 新增小型 VDD 状态 composable(优先 window.vddDriver,回退 /api/vdd/status);
  • 设置向导设门,验证成功后恢复;
  • 输出(output)与直接捕获(direct-capture)配置增加非阻塞警告;
  • 增加聚焦的单元测试与本地化用户字符串。

已实现的入口收敛

当前仓库中,所有可能创建或依赖 VDD 的路径都已收敛到同一状态契约:

入口 行为
设置向导 安装/复检门,完成后恢复到当前向导步骤
独立 Web 配置 非阻塞状态提示 + 宿主机侧指引
桌面 VDD 编辑器 不可用状态替换为安装/修复面板
桌面流配置 状态、安装/修复、复检动作
桌面托盘创建/保持/无头动作 前置检查,路由到 VDD 设置
Core 托盘 HTTP 动作 在更改配置前拒绝缺失前置条件
原生托盘与远程 VDD 快捷方式 解释前置条件并打开/通知桌面管理路径
流启动与最低层 monitor 创建原语 在拓扑变更或 legacy 管道重试前快速失败

被废弃的独立 renderer/vdd 编辑器已移除,桌面应用现在只有一个权威的 VDD 管理界面。

验证体系:五层验证

  1. 已安装布局的 install-vdd.bat --probe-only 冒烟测试:验证载荷发现与机器可读状态契约,不改变已安装驱动。
  2. 专用 vdd_prerequisite_unit_tests CTest:覆盖 Core 每个状态与"可用驱动不变式",不依赖无关的完整测试可执行文件(见 tests/unit/test_vdd_prerequisite.cpp)。
  3. Web 测试:覆盖浏览器回退、桌面桥优先、UAC 取消/重试、未安装→就绪过渡;Tauri 测试覆盖详细状态分类与托盘行为。
  4. 生产 Web 与桌面 renderer 构建、Tauri 测试、完整 Core sunshine.exe 链接:验证所有集成边界。
  5. 源码审计:验证每个 CREATEMONITOR 调用都收敛到受守卫的 create_vdd_monitor() 原语;旧的独立 VDD renderer 不出现在生产输出中。

真实的驱动安装/卸载有意不作为常规验证的一部分,因为它会改变宿主显示驱动与拓扑。这类发布候选检查属于一次性干净 Windows 主机;取消与失败仍然可见,因为提权 runner 会传播真实退出码,UI 保留被中断的选择。

2026-07-22 本地安装验证记录(开发主机)

在改动任何驱动之前,scripts/vdd_rc_smoke.ps1 -ValidateOnly 记录了 build/vdd_local_install/vdd-before.json,事实如下:

  • 已安装版本 100.0.16.6,随附版本 100.0.16.4;
  • PnP 状态 OK、problem code 0;
  • 桌面流页面把"可用但版本不匹配"分类为 degraded,并暴露 Install / Repair Driver;
  • 桌面 VDD 设置主页在可用状态下保留编辑器,同时在版本警告旁暴露相同的 Install / Repair Driver 动作。

该检查在安装前发现并修复了一个 Windows 专属的探测缺陷:Rust 曾通过 Command::arg 传递内嵌引号的批处理路径,导致引号被转义成 cmd.exe 的 \" 字面量,使每个健康安装都在 GUI 中显示为 unknown。修复后探测改用 raw_arg 配合 call "..." --probe-only 命令行,并新增一个 Windows 执行级单测,从含空格的路径运行真实批处理文件,防止此类"看起来可行但实际不可执行"的引号改动再次回归。

第一次真实修复尝试在 UAC 之前被拒绝,因为当时有一条 Moonlight 流处于激活状态——这从已安装的 Core 上确认了 active-stream 安全门;那次尝试没有改动任何驱动文件或显示拓扑。流结束后,经明确批准的提权修复在不重启 Windows的情况下完成:安装日志记录了旧设备移除、以 oem4.inf 发布、适配器重建以及最终的 VDD adapter is ready 检查。安装后证据存于 build/vdd_local_install/vdd-after-durable.json:

  • 已安装与随附版本均为 100.0.16.4;
  • ROOT\DISPLAY\0001 存在,PnP 状态 OK、problem code 0;
  • GUI 恢复到可编辑的 VDD 设置状态;
  • 持久化 VDDPATH 指向 C:\Program Files\Sunshine\config(非隔离测试布局);
  • 修复后活动会话数保持为零。

修复还暴露了一个显示拓扑边界情况:Windows 可能在提权脚本运行期间重置桌面,导致原始 Tauri IPC 响应丢失(即便驱动已健康)。因此安装 UI 现在运行独立的状态验证循环,一旦观察到 ready、running 且随附版本精确匹配即完成。五个聚焦测试覆盖:验证不变式、正常完成、IPC 丢失恢复、立即拒绝、超时清理。

验收标准

  • 全新主机可在桌面 GUI 的设置向导内安装 VDD,并在不重启向导的情况下继续;
  • 取消 UAC 会保留用户的选择并报告取消/失败;
  • 独立 Web UI 显示宿主机侧安装指引,而非一个死控件;
  • VDD 设置编辑器在缺失前置条件时绝不呈现虚假的可编辑默认值;
  • 在无驱动情况下启动依赖 VDD 的流,不修改拓扑、不等待 legacy 管道重试;
  • 健康的既有安装看不到额外阻塞 UI;
  • 流会话进行中拒绝安装/修复,且永不自发重启 Windows;
  • 脚本支撑的卸载路径指向当前的 Root\ZakoVDD 包并报告真实结果。

发布候选(RC)干净主机检查清单

以下破坏性检查只能在一次性干净 Windows 主机上执行。

从仓库检出(checkout)开始,以提权 PowerShell 会话对已安装的 scripts 目录运行生命周期验证器。它拒绝非干净主机,并写出包含 PnP 与 DriverStore 快照的 JSON 证据记录(脚本见 scripts/vdd_rc_smoke.ps1):

powershell -ExecutionPolicy Bypass -File scripts\vdd_rc_smoke.ps1 `
  -ScriptsDirectory "C:\Program Files\Sunshine\scripts" `
  -EvidencePath .\vdd-rc-evidence.json `
  -AllowDestructive
  • [ ] 无 ZakoVDD 安装时,在桌面设置向导中选择 VDD,接受 UAC,验证向导以原选择恢复;
  • [ ] 从干净状态重复,取消 UAC,验证选择保留且取消/失败被显示;
  • [ ] 禁用或使适配器不健康,验证设置、托盘、快捷方式与流入口都路由到修复而非重试 VDD;
  • [ ] 流激活期间,验证安装/修复与卸载被拒绝;
  • [ ] 从 VDD 设置卸载,验证 Root\ZakoVDD 被移除、UI 回到 not_installed,且 Windows 从不自动重启。

实践要点速览

  1. 状态即契约:无论从桌面、浏览器还是 Core 内部查询,VDD 状态都遵循同一词汇表与同一 is_usable() 判定,避免各入口各自为政。
  2. 只读探测 vs 变更动作分离:get_vdd_status() / GET /api/vdd/status / --probe-only 均不改变任何驱动状态;安装与修复只在桌面进程内通过 UAC 提权执行。
  3. 快速失败优于重试:create_vdd_monitor() 在 IOCTL 之前校验可用性,缺失驱动时直接返回 VDD_DRIVER_NOT_INSTALLED,不再空耗 legacy 管道重试。
  4. 安全边界:流激活期间拒绝安装/修复/卸载,Windows 永不自动重启;干扰已激活 monitor 前必有警告。
  5. 回归防线:状态分类与可用性不变式由 tests/unit/test_vdd_prerequisite.cpp 固定;Web 桥偏好与回退由 src_assets/common/assets/web/tests/vddStatus.test.js 固定;含空格路径的批处理执行由 Windows 执行级单测固定。
登录后查看全文
foundation-sunshine