feat(installer): 「为所有用户安装」那趟自动放行防火墙入站 19540（装时加 / 卸时回收）

- deploy/prepare-extra.mjs 生成的安装器脚本新增两个 !define（规则名 / 端口）与两段逻辑： customInstall 里当 $installMode == "all" 且当前是提权进程时，先删后加一条入站放行规则； customUnInstall 里只要是管理员就回收同一条规则。失败一律忽略，绝不因此让安装/卸载失败。 - 订正 docs 里「安装包按用户安装、不申请提权、改不了防火墙」这句错话（部署指南 7.5/7.9、上线检查清单、常见问题 Q101、升级说明）：选「为所有用户安装」会 UAC 提权，那一趟就把规则加好了；「仅为我安装」才需要现场手工放行。手工规则名与自动规则名不同，卸载只删自动那条。 - .gitignore 注释补上「防火墙入站规则」。验证：四套自检全绿（服务端 13 包 / 前端 vue-tsc + 680 例 + build / Console 20 文件 + 68 例）；生成器重跑幂等（.nsh 哈希 9edcdc31… 不变）；本机 wine 用 makensis v3.04 编译含该 .nsh 的脚本 0 error。未验证（需真机）：提权安装后防火墙里真的出现该规则、卸载真的删掉、失败分支真机表现。
2026-09-12 19:42:23 +08:00
1 parent c97d3150c9
commit 78b14efaa9
@@ -17,7 +17,7 @@ deploy/signature.local.txt
 deploy/signature.build.txt
 # 版本注入脚本（构建时由 deploy/prepare-extra.mjs 从仓库根 VERSION 生成）
 deploy/version.gen.bat
-# 安装器自定义脚本：许可页署名 + 上次安装目录记忆（构建时生成）
+# 安装器自定义脚本：许可页署名 + 上次安装目录记忆 + 防火墙入站规则（构建时生成）
 console/resources/installer-custom.nsh

 # 开发文档（内部设计文档，不进仓库）
@@ -1,7 +1,9 @@
 // 构建前准备三样东西：
 // 1) 把 docs/ 下的使用说明与报名名单导入规范暂存到 console/extra/，供 electron-builder 的 extraFiles 平铺到部署包根目录；
 // 2) 生成安装器自定义脚本（console/resources/installer-custom.nsh）：许可页顶部文案（署名来自构建机本地文件）
-//    + 记住上次安装目录（重装时沿用，而不是退回系统默认路径）；
+//    + 记住上次安装目录（重装时沿用，而不是退回系统默认路径）
+//    + 按安装模式放行/回收防火墙入站 19540（「为所有用户安装」那一趟本来就提了权，顺手做掉，
+//      省得现场再拿管理员 cmd 手工敲 netsh）；
 // 3) 读仓库根 VERSION 文件：生成 deploy/version.gen.bat（供 build.bat 注入 Go 二进制）
 //    并同步 console/package.json 的 version（决定安装包/免安装包的文件名）。
 // 用 Node 而不是批处理：中文文件名/中文内容在 .bat 里会被 cmd 解析错乱。
@@ -32,7 +34,7 @@ for (const doc of docsToStage) {
 }

 // ---- 2. installer custom script ---------------------------------------------
-// electron-builder 的 nsis.include 只收一个文件，所以许可页文案与安装目录记忆写在同一个 .nsh 里。
+// electron-builder 的 nsis.include 只收一个文件，所以许可页文案、安装目录记忆与防火墙规则写在同一个 .nsh 里。
 const signatureFile = join(root, 'deploy', 'signature.local.txt')
 const nshDir = join(root, 'console', 'resources')
 const nshFile = join(nshDir, 'installer-custom.nsh')
@@ -50,13 +52,19 @@ const nsh = [
  '!include "LogicLib.nsh"',
  '',
  '; 安装器自定义脚本：由 deploy/prepare-extra.mjs 生成，不要手改。',
-  '; 内容只有三块：许可页文案、上次安装目录记忆、卸载钩子。',
+  '; 内容：许可页文案、上次安装目录记忆、防火墙入站规则（装时放行 / 卸时回收）、卸载钩子。',
  '',
  '; 自己记的安装目录（per-user 落 HKCU，per-all-users 落 HKLM）。',
  '; electron-builder 自带的 ${INSTALL_REGISTRY_KEY} 在卸载时会被整键删掉，',
  '; 「先卸载再装新版」或换过安装模式就会退回系统默认路径，所以另存一份不会被卸载器清理的。',
  '!define SCOREBOARD_INSTALL_KEY "Software\\Scoreboard Console"',
  '',
+  '; 防火墙入站规则的规则名：安装与卸载共用这一个字面量，改它两处一起改（名字对不上就删不掉）。',
+  '; 端口写死安装包的默认端口：现场改过 config.yaml 里的 server.port 时，这条规则对不上实际端口，',
+  '; 得按实际端口现场再放行一次（见 docs/部署指南.md 7.5）。',
+  '!define SCOREBOARD_FIREWALL_RULE "Scoreboard Console (TCP 19540)"',
+  '!define SCOREBOARD_FIREWALL_PORT "19540"',
+  '',
  '!macro customHeader',
  `  !define MUI_LICENSEPAGE_TEXT_TOP "${topText}"`,
  '!macroend',
@@ -93,13 +101,48 @@ const nsh = [
  '!macro customInstall',
  '  ; SHELL_CONTEXT 跟随安装模式：per-user → HKCU，per-all-users → HKLM。',
  '  WriteRegStr SHELL_CONTEXT "${SCOREBOARD_INSTALL_KEY}" "InstallLocation" "$INSTDIR"',
+  '',
+  '  ; 放行防火墙入站端口，只在「为所有用户安装」这一路做。依据：',
+  '  ;   $installMode 由 electron-builder 的安装模式页写定（multiUser.nsh 里就是 "all" / "CurrentUser"）；',
+  '  ;   选「为所有用户安装」时安装器先弹 UAC 提权、提权成功的那个进程才继续跑安装段',
+  '  ;   （multiUserUi.nsh 里对「all users」单选钮的处理：UAC_RunElevated，外层进程直接 Quit），',
+  '  ;   所以走到这里时进程已经是管理员，netsh 才有权限改防火墙。',
+  '  ;   选「仅为我安装」全程不提权（installer.nsi 里 RequestExecutionLevel user），netsh 必然失败，',
+  '  ;   所以这里连试都不试：省一次注定失败的调用，也不往安装日志里塞看不懂的报错。',
+  '  ;   UAC_IsAdmin 再确认一次当前确实是提权进程（宏来自 UAC.nsh，multiUser.nsh 已经 include 过），',
+  '  ;   两个条件都成立才动手，任何情况下都不会拿普通用户权限去调 netsh。',
+  '  ${If} $installMode == "all"',
+  '  ${AndIf} ${UAC_IsAdmin}',
+  '    ; 先删后加：覆盖安装/重装时把上一条同名规则清掉，免得同名规则越积越多。',
+  '    ; ExecToLog = 隐藏执行、不弹黑窗，输出只进安装日志（装完展开「显示细节」才看得到）。',
+  '    nsExec::ExecToLog \'netsh advfirewall firewall delete rule name="${SCOREBOARD_FIREWALL_RULE}"\'',
+  '    Pop $0',
+  '    ; 失败一律忽略：netsh 返回非 0（被组策略禁用、杀软拦截、防火墙服务被拆……）就只留一行日志，',
+  '    ; 绝不能因为防火墙这一步让安装失败——规则没加上，现场还能按 docs/部署指南.md 7.5 手工补。',
+  '    nsExec::ExecToLog \'netsh advfirewall firewall add rule name="${SCOREBOARD_FIREWALL_RULE}" dir=in action=allow protocol=TCP localport=${SCOREBOARD_FIREWALL_PORT}\'',
+  '    Pop $0',
+  '    ClearErrors',
+  '  ${EndIf}',
  '!macroend',
  '',
  '!macro customUnInstall',
-  '  ; 故意什么都不删：需求就是「卸载后重装仍沿用上次的目录」。',
+  '  ; 安装目录记忆故意不删：需求就是「卸载后重装仍沿用上次的目录」。',
  '  ; 若改成卸载即遗忘，在这里补两行（卸载时 SHELL_CONTEXT 不一定已设定，要写死根键）：',
  '  ;   DeleteRegValue HKCU "${SCOREBOARD_INSTALL_KEY}" "InstallLocation"',
  '  ;   DeleteRegValue HKLM "${SCOREBOARD_INSTALL_KEY}" "InstallLocation"',
+  '',
+  '  ; 回收安装时加的那条入站规则。卸载走哪条路要看当初是怎么装的：',
+  '  ;   按「为所有用户安装」装的：卸载器进卸载段之前会先 UAC 提权',
+  '  ;   （multiUserUi.nsh 里发现只有 per-machine 安装、且当前不是管理员时 UAC_RunElevated），',
+  '  ;   当前进程是管理员，netsh 能删掉；',
+  '  ;   按「仅为我安装」装的：全程不提权，netsh 必然失败——需求是「失败就算了」。',
+  '  ; 所以这里只判断「是不是管理员」，不判断安装模式：非管理员时连试都不试，不报错、不留提示，',
+  '  ; 免得卸载日志里多出一行用户看不懂的 netsh 报错。',
+  '  ${If} ${UAC_IsAdmin}',
+  '    nsExec::ExecToLog \'netsh advfirewall firewall delete rule name="${SCOREBOARD_FIREWALL_RULE}"\'',
+  '    Pop $0',
+  '    ClearErrors',
+  '  ${EndIf}',
  '!macroend',
  '',
 ].join('\r\n')
@@ -17,9 +17,12 @@

 - [ ] Windows 10/11 x64，接市电（建议接 UPS）
 - [ ] 端口 **19540** 未被占用：`netstat -ano | findstr 19540`
- [ ] **防火墙已放行入站 19540**（局域网设备才能连上）：在**管理员** cmd 里执行
-      `netsh advfirewall firewall add rule name="Scoreboard 19540" dir=in action=allow protocol=TCP localport=19540`
-      —— 安装包是**按用户安装、不申请管理员提权**，改不了防火墙，这一步必须手动做一次；临时「关闭防火墙」只用于**验证**是不是它挡的，验证完要恢复；正式开赛前请用上面这条命令放行，不要一直关着防火墙（改过端口就把 `19540` 换成实际端口）
+- [ ] **防火墙已放行入站 19540**（局域网设备才能连上）—— **自检口径：用另一台设备（平板 / 手机）浏览器打开 `http://<主机IP>:19540/display` 能出画面，就算放行过了**；打不开时先确认装的时候选的是哪一项：
+      - 装的时候选了**「为所有用户安装」**：安装程序提权时**已经自动放行**（防火墙里能看到规则 `Scoreboard Console (TCP 19540)`），不用再手工加；
+      - 装的时候选了**「仅为我安装」**：不申请提权、装不了规则，在**管理员** cmd 里手工放行一次
+        `netsh advfirewall firewall add rule name="Scoreboard 19540" dir=in action=allow protocol=TCP localport=19540`
+        （也可以改用「为所有用户安装」重跑一次安装程序，让它自动放行）
+      —— 临时「关闭防火墙」只用于**验证**是不是它挡的，验证完要恢复；正式开赛前一定放行，不要一直关着防火墙。改过端口就把 `19540` 换成实际端口，安装程序只会自动放行默认端口 `19540`，改过端口的一律手工放行
 - [ ] 数据/配置目录可写：默认 `%LOCALAPPDATA%\ScoreboardConsole\`（数据在 `data\`，配置与规则是 `console\config.json`、`config.yaml`、`rules\`；都在安装目录之外，升级/卸载都不会删），需要放行杀毒/防火墙
 - [ ] 大屏通过 HDMI 接在**同一台机器**上（系统显示模式设为「扩展」）
 - [ ] 显示器数量确认：只接一块屏时大屏只能窗口化（按 F11 可切全屏）；要每屏一个 kiosk 全屏窗口就得接第二块屏（见部署指南 7.3、7.5）
@@ -44,7 +44,7 @@
 2. 用录入员及以上账号进「大屏控制」页，确认「局域网大屏」卡片列出地址；只有 `169.254.x.x` 的机器上应能看到它、并带「自动配置地址」那句说明；
 3. 用平板 / 手机扫第一个地址的二维码，确认能打开大屏；
 4. 自动检测为空时试一次「手动添加地址」（填 `ipconfig` 里的地址），确认立刻出链接与二维码；
-5. 局域网设备连不上的机器，按《部署指南》7.5 的命令放行入站 **19540**；
+5. 局域网设备连不上的机器，先确认装的时候选的是哪一项：选**「为所有用户安装」**的，安装程序提权时已经自动放行入站 **19540**（防火墙里能看到规则 `Scoreboard Console (TCP 19540)`）；选「仅为我安装」的，按《部署指南》7.5 的命令手工放行一次；
 6. 用《上线检查清单》过一遍。

 ### ⑥ 详细说明在哪
@@ -687,5 +687,5 @@ Console 启动的多屏窗口默认每屏锁定一页。到「大屏控制」点
 1. **先看卡片列出的「已检查」原因**：新版空态会逐条列出检查过的网卡与各自被跳过的原因，例如「没找到可用的局域网地址。已检查：以太网（接口未连接）、WLAN（只有 IPv6 地址）。」——原因有「**接口未连接**」「**只有 IPv6 地址**」「**接口没有地址**」「**回环接口**」四种；最多列 5 条，网卡更多时其余折叠成「**等共 N 块网卡**」。照着原因去修那一张网卡（插好网线 / 给它一个 IPv4 地址 / 看看 DHCP）。如果看到的仍是旧句「未检测到局域网地址（可能是没插网线 / 只有回环）。」，说明这台机器上的前后端还没更新到最新版，按下面几步照样能排查；
 2. **`ipconfig` 确认有没有 IPv4 地址**：在 cmd / PowerShell 里跑 `ipconfig`。注意 **Windows 里「网线插着、网卡显示 Up」不等于拿到了 IP**；如果只看到 `169.254.x.x`，说明**本网段没有 DHCP**，地址是设备自配的——这在**独立小网络**（没有路由器、设备直连或只接一台交换机）里是**正常用法，不是故障**，同网段的平板 / 手机照样能访问；
 3. **手动添加地址**：自动检测不到、或者列出来的不是你要的那个网段时，把 `ipconfig` 里那条 IPv4 地址填进卡片下方的「手动添加地址」再点「添加」——立刻出链接和二维码（排第一条、带「手动」徽标、刷新不丢，最多 10 个）；
-4. **放行防火墙入站 19540**：地址对了、别的设备还是打不开，多半是主机防火墙挡了。在**管理员** cmd 里执行 `netsh advfirewall firewall add rule name="Scoreboard 19540" dir=in action=allow protocol=TCP localport=19540`（改过端口就换成实际端口）；临时关闭防火墙只用于**验证**是不是它挡的，验证完要恢复；
+4. **放行防火墙入站 19540**：地址对了、别的设备还是打不开，多半是主机防火墙挡了。装的时候选的是**「为所有用户安装」**的话，安装程序提权时**已经自动放行**（防火墙里能看到规则 `Scoreboard Console (TCP 19540)`），不用再手工加；选「仅为我安装」的机器要手工放行——在**管理员** cmd 里执行 `netsh advfirewall firewall add rule name="Scoreboard 19540" dir=in action=allow protocol=TCP localport=19540`（改过端口就换成实际端口；也可以改用「为所有用户安装」重跑一次安装程序让它自动放行，但自动放行只认默认端口 19540）；临时关闭防火墙只用于**验证**是不是它挡的，验证完要恢复；
 5. **还不行就跑自检**：运行 `debug\诊断\局域网地址自检.exe`，把它的输出发回给我们。
@@ -403,13 +403,20 @@ scoreboard.exe passwd -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -da

 另外两种来源会各带一句提示、**照常能用**：网卡状态读不到时提示「网卡状态读不到（可能是驱动或虚拟网卡），地址本身可用，打不开就换下面一条」；按系统默认路由推断出来时提示「这条地址是按系统默认路由推断出来的（网卡枚举里没有它），地址本身可用，打不开就换下面一条」。

-**防火墙必须放行入站 19540**（默认端口，改过端口就换成实际端口）。在**管理员** cmd 里跑：
+**防火墙要放行入站 19540**（默认端口，改过端口就换成实际端口）。安装包会替你放行，分两种情况：
+
+- 安装时选了**「为所有用户安装」**：安装程序会弹 UAC 提权，**提权那一趟就顺手把入站 19540 放行了**（规则名 `Scoreboard Console (TCP 19540)`），装完不用再管；卸载时会自动把这条规则删掉。
+- 安装时选了**「仅为我安装」**：全程不申请提权，装不了防火墙规则，**必须手工放行**。也可以重新跑一次安装程序、这次选「为所有用户安装」，让它自动放行。
+
+手工兜底（给「仅为我安装」的机器，以及改过端口、装了才发现要放行的机器）——在**管理员** cmd 里跑：

 ```bat
 netsh advfirewall firewall add rule name="Scoreboard 19540" dir=in action=allow protocol=TCP localport=19540
 ```

-为什么安装包不能替你加这条：安装包是**免管理员的按用户安装**（默认装到当前用户目录），**不申请管理员提权**，所以改不了系统防火墙规则；这一步必须由现场用管理员身份手动做一次。临时关掉防火墙只能用来**验证**「是不是防火墙挡的」，验证完要恢复；正式开赛前一定用上面这条命令放行，而不是一直关着防火墙。
+注意这条手工规则的名字（`Scoreboard 19540`）与安装程序自动加的那条（`Scoreboard Console (TCP 19540)`）**不一样**：卸载时安装程序只会删掉自己加的那条，手工加的这条要自己 `netsh advfirewall firewall delete rule name="Scoreboard 19540"` 删；两条同时存在只是重复放行，不影响使用。
+
+临时关掉防火墙只能用来**验证**「是不是防火墙挡的」，验证完要恢复；正式开赛前一定用上面这条命令（或改用「为所有用户安装」重跑一次安装程序）放行，而不是一直关着防火墙。

 **排障常识**：Windows 里「网线插着、网卡显示 Up」**不等于拿到了 IP**；`ipconfig` 里看到 `169.254.x.x` 说明**本网段没有 DHCP**（地址是设备自配的）——这在**独立小网络**里是正常用法，**不是故障**，同网段的平板 / 手机照样能访问。

@@ -446,7 +453,7 @@ http://<主机IP>:19540/display

 - 这个地址不用手敲：管理端「大屏控制 → 局域网大屏」卡片里有**可复制的完整链接**与**二维码**（第一个地址），别的设备扫码或在浏览器里粘贴即可打开（该卡片需录入员及以上登录才看得到）；
 - 需要主机设置固定 IP，且设备与主机在同一局域网；
- **主机防火墙要放行入站 19540**（默认端口）：安装包是按用户安装、不申请管理员提权，改不了防火墙规则，需要在**管理员** cmd 里手动执行一次，命令与说明见 7.5；
+- **主机防火墙要放行入站 19540**（默认端口）：装的时候选**「为所有用户安装」**，安装程序提权时会自动放行，不用再管；选了「仅为我安装」就得手工放行一次，命令与说明见 7.5；
 - 安卓电视一般常亮，无需额外防熄屏；
 - 浏览器方案**不受** Console 的 kiosk、防熄屏、选屏控制，字体与动画表现以实际设备为准；
 - 现场以 Console + HDMI 为主方案，浏览器访问作为备用。