Bug：桌面端在 listen EACCES（Windows 保留端口区间）时误报「文件损坏请重装」

[WJMACTD]

摘要

当桌面端的本地 webserver 因端口落入 Windows 保留端口区间（由 Hyper-V / WSL 通过 winnat 服务动态预留）而无法绑定时，net.Server.listen() 会以 EACCES: permission denied 拒绝——而不是 EADDRINUSE。

fatal-recovery 弹窗目前只特殊处理 listen EADDRINUSE，因此 EACCES 会落到通用路径。结果用户看到的是误导性的提示「如果应用文件缺失或损坏，请关闭应用并重新安装」，并被提供「禁用第三方插件」按钮——这两者都与实际问题毫无关系。

复现步骤

在启用了 Hyper-V / WSL / Docker Desktop（WSL2 后端）的 Windows 机器上，winnat 服务会预留一段动态 TCP 端口区间：

netsh interface ipv4 show excludedportrange protocol=tcp
#   19291   19390

1. 确认桌面启动器的目标端口落在某个保留区间内。
2. 启动桌面应用。
3. webserver 插件报错：listen EACCES: permission denied 127.0.0.1:<port>。
4. 致命错误弹窗显示「重新安装」建议，而非「端口/地址冲突」。

崩溃日志片段：

DesktopHostFatalError: dsh: startup failed: 2 required plugins did not activate
Failed plugins (1):
  webserver (required)
    Package: @deepseek-ai/dsh-host-webserver
    Error: listen EACCES: permission denied 127.0.0.1:19387

当前行为

• 弹窗显示「如果应用文件缺失或损坏，请关闭应用并重新安装」。
• 弹窗提供「禁用第三方插件、备份 profile patch 并重启」，而该操作无法解决端口被保留的问题。

期望行为

• 弹窗应能识别由 EACCES（端口被保留 / 权限拒绝）导致的监听地址冲突，并给出准确建议（例如「该端口被系统保留；重启以获得其他端口，或停止 Hyper-V / WSL」）。
• 应只提供「退出 / 重启」按钮，与现有 EADDRINUSE 的处理保持一致。

根因分析

apps/desktop/src/fatal-recovery.ts 用以下方式判断监听冲突：

const addressInUse = /\blisten EADDRINUSE\b/u.test(detail)

该正则只匹配 EADDRINUSE。Windows 的保留端口冲突表现为 EACCES（其他地址失败表现为 EADDRNOTAVAIL），因此被误判为通用启动失败。

修复建议

扩大监听冲突的检测范围，覆盖其余 listen 地址错误，并使用准确、可操作的文案：

const addressUnavailable = /\blisten E(?:ADDRINUSE|ACCES|ADDRNOTAVAIL)\b/u.test(detail)

并新增 startupAddressUnavailable 文案（中英文），同时覆盖「已有其他实例运行」与「端口被系统保留（如 Hyper-V / WSL）」两种情况。

完整的补丁（含测试）附在下方。全部 24 个 fatal-recovery 测试均通过。

补丁（diff）

diff --git a/apps/desktop/src/fatal-recovery.ts b/apps/desktop/src/fatal-recovery.ts
@@ -70,17 +70,17 @@
-      const addressInUse = /\blisten EADDRINUSE\b/u.test(detail)
+      const addressUnavailable = /\blisten E(?:ADDRINUSE|ACCES|ADDRNOTAVAIL)\b/u.test(detail)
       const { response } = await this.operations.show({
         type: 'error',
         title: messages.startupFailed,
         message,
-        detail: addressInUse
-          ? `${messages.startupAddressInUse}${reportLine(messages, reportPath)}`
+        detail: addressUnavailable
+          ? `${messages.startupAddressUnavailable}${reportLine(messages, reportPath)}`
           : dialogDetail(detail, messages, reportPath),
-        buttons: addressInUse
+        buttons: addressUnavailable
           ? [messages.exitApplication, messages.restartApplication]
           : [messages.exitApplication, messages.restartApplication, messages.disableThirdPartyPlugins],

环境

• 应用：@deepseek-ai/dsh-desktop 0.2.0-rc.2
• 平台：win32 x64，Electron 44.0.0，Node 24.18.1
• 触发条件：Windows TCP 保留端口区间（winnat / Hyper-V / WSL）

[MalikAhed]

The diagnosis and regex change are correct. For an affected user, first confirm the reservation with netsh interface ipv4 show excludedportrange protocol=tcp; do not treat EACCES as an installation failure. The safest immediate workaround is to restart the desktop host so it selects a port outside the excluded ranges, or configure the webserver to use a free port if that setting is available. Stopping Hyper-V/WSL/Docker only to free a port is a heavier workaround and can disrupt unrelated workloads.

For the recovery path, classify listen EADDRINUSE, listen EACCES, and listen EADDRNOTAVAIL together as address-unavailable, but keep the displayed cause specific: EACCES on Windows commonly means the port is in a system-excluded range, while EADDRINUSE usually means another process owns it. Logging the attempted address and port in the dialog will make the next step obvious. Your proposed regression cases should cover both a reserved port and an occupied port so the message does not regress. If this is useful, please click Mark as answer.