fix(admin): 局域网大屏卡片按「地址类别」判定 + 三层兜底 + 手填入口(dev_0.5.0)

## 判断失误的修正(主人现场实测出来的)
主人现场是 **169.254 自动配置网段**(没有 DHCP,设备靠链路本地地址互访),
平板实测能访问 `http://169.254.79.190:19540/display`;而卡片一开始把链路本地地址
**排除**了,于是显示「未检测到局域网地址」。
根因:`usableLanIPv4` 排除了 `IsLinkLocalUnicast()`,理由写的是「169.254 说明没拿到 IP」
——那是**对网络健不健康的猜测**,不是**地址能不能用的事实**。

现改为按**地址类别**判定(`ipv4Scope`,全部用标准库谓词,**代码里没有任何网段字面量**):
只排除「作为对端访问目标没有意义」的四类(回环 / 未指定 / 组播 / 广播),
链路本地与私网、全局一样进候选,只**排在最后**并带说明
「自动配置地址:本网段没有 DHCP,同网段设备可以互相访问」。
新增**反硬编码护栏用例**:函数体内不得出现 `x.x.x.x` 字面量,且必须用满 6 个谓词。
顺带修掉新用例抓出的真 bug:`ipv4Scope(nil)` 曾落进 default 被当成「可用的 global」,
而 IPv6 的 `To4()` 正是 nil → 「只有 IPv6 的网卡」会被误判成有可用地址。

## 三层兜底(离线现场必须拿得到地址)
1. **严格轮**:接口 up 且非回环;
2. **宽松轮**:严格轮为空时不再要求 up 位(某些驱动/虚拟网卡读不到),命中标 `confidence: low`;
3. **默认路由探测**:两轮皆空时用 `net.Dial("udp4", …)` 问出本机源地址
   (UDP connect 只查路由表、不握手不发包,离线安全;TCP 会等 SYN 超时,不能用),标 `confidence: route`。
接口同时回 `scope`(private/global/link-local)与 `skipped`(被跳过的网卡 + 原因,
code 收敛为 no-address / only-ipv6 / not-up / loopback——link-local 不再是「被跳过」的理由)。

## 手填入口(最后一道保险)
自动检测不到、或不是现场要用的网段时,操作员把 `ipconfig` 里的地址填进卡片,
立刻生成链接 + 二维码;排在第一条、带「手动」徽标、可删除、localStorage 持久化、
四条就地校验文案(空/含空格/不像 IP/重复),IPv6 也支持。

## 自检工具
`debug/诊断/局域网地址自检.exe` + 说明:只读、不写文件、不需管理员,
打印系统给 Go 看的网卡列表(含类别)、默认路由探测结果与可用大屏地址。
(正是它把现场定性成 169.254 网段的。)

## 真浏览器验证(四场景,非源码断言)
链接本地地址出链接+二维码+说明句 / 空态列出被跳过网卡并折叠(5 条 + 等共 N 块)/
low 与 route 两种来源提示各占一行互不顶掉 / 手填地址排第一并刷新不丢 —— 全部通过,0 页面错误。

## 文档
使用手册 §9、部署指南 7.5/7.9、上线检查清单(**防火墙放行入站 19540** 与
「另一台设备能打开局域网大屏」两条新增)、常见问题 Q101、升级说明 dev_0.5.0;
devdocs 05/07/13 同步(含这次误判的来龙去脉与「Get-NetAdapter 显示 Up ≠ 有 IP」)。
**没有数据迁移**,旧赛事包照常导入。

自检:服务端 13 包 ×2;前端 vue-tsc + 680 例 ×2 + build;Console 20 文件 + 68 例。
This commit is contained in:
AskaEth committed 2026-09-12 18:30:46 +08:00
1 parent 9ef68c2589
commit c97d3150c9
18 files changed
+2425 -79

No files matched your search

+4
View File
@@ -17,6 +17,9 @@
- [ ] 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` 换成实际端口)
- [ ] 数据/配置目录可写:默认 `%LOCALAPPDATA%\ScoreboardConsole\`(数据在 `data\`,配置与规则是 `console\config.json`、`config.yaml`、`rules\`;都在安装目录之外,升级/卸载都不会删),需要放行杀毒/防火墙
- [ ] 大屏通过 HDMI 接在**同一台机器**上(系统显示模式设为「扩展」)
- [ ] 显示器数量确认:只接一块屏时大屏只能窗口化(按 F11 可切全屏);要每屏一个 kiosk 全屏窗口就得接第二块屏(见部署指南 7.3、7.5)
@@ -57,6 +60,7 @@
- [ ] **调试标识已隐藏**:多屏 kiosk 全屏画面上不该出现「实例 … · 屏 …」;窗口化窗口(单屏)里显示这一行属正常,按 F11 全屏后它与自绘标题栏一起消失(版本号角标已移除,任何画面都不该出现)
- [ ] **显示器菜单可用**:在服务管理窗口里点「打开服务端管理面板」,进「大屏控制 → 显示器」,能看到每块屏;副屏点「创建全屏窗口」能重新开出来(单屏 / 主显示器只能窗口化,属正常)
- [ ] **在线大屏与逐屏切页**:同页右侧「在线大屏」列表能看到本机每块屏的在线实例(局域网设备也已在这一列表里,标记为「局域网浏览器」),每行显示当前所在页;用某一行自己的下拉 +「切到此页」能把那一块屏 / 那台设备单独切走,其余屏不受影响(离线实例的控件为灰色,属正常)
- [ ] **局域网大屏能在别的设备打开**:用另一台设备(平板 / 手机)浏览器打开 `http://<主机IP>:19540/display` 能出画面,或直接扫「大屏控制 → 局域网大屏」卡片第一个地址的**二维码**;打不开时先看卡片列出的地址与提示,再按常见问题「大屏控制页显示未检测到局域网地址怎么办?」逐条排查(若卡片地址是 `169.254.x.x`,说明本网段没有 DHCP,同网段的设备照样能连)
- [ ] **公告可用**:推送一条测试公告 → 大屏全屏显示 → 到时退回原页且**底栏公告栏仍常驻显示正文** → 点「清除公告」后底栏回到「暂无公告」
- [ ] **实时赛况配置正确**:「大屏控制 → 实时赛况」卡片里模式与项目已按今天赛程选好(自动判定 / 人工指定),「当前生效」显示的就是此刻该显示的项目;大屏切到「实时赛况」页能看到该项目**已发布**成绩的实时排名(两个项目同时进行时应自动左右分栏)
- [ ] **分批发布演练**:选一个分多场跑的项目,先只填一批成绩发布 → 大屏立即出现这一批的排名 → 补录下一批再发布 → 排名自动重算(未录的行不会被当成 0 分,也不挡发布)
+9 -1
View File
@@ -430,7 +430,15 @@
- 卡片右上角徽标显示「N 个可用地址」;每个地址一行,**点链接**直接在新标签页打开,点旁边的**复制**按钮把完整地址(形如 `http://192.168.1.5:19540/display`)复制到剪贴板,按钮会短暂变成「已复制」;
- **第一个地址带一个二维码**(下方注明「手机扫码直接打开」),手机相机一扫即可打开,省去手敲长地址;
- **空态**:显示「未检测到局域网地址(可能是没插网线 / 只有回环)。」——意思是主机当前没有别的设备能用上的地址(网线没插、网卡没起来,或只剩本机回环地址),先在 Windows 网络设置里确认主机已连上局域网;如果显示的是「服务端没有下发大屏端口,暂时拼不出能在别的设备打开的地址。」,那是服务端异常,重启 Console / 服务端后再看;
- **地址分三类**,卡片会照实把可用地址都列出来(排除的只有回环、未指定、组播、广播这四类对本机之外没有意义的地址):
- **内网地址**(`192.168.x.x`、`10.x.x.x`、`172.16–31.x.x` 这类):路由器 / 交换机分配或手工设好的地址,也是最常见的现场用法,**排在最前**;
- **全局地址**:不在上面这些网段里的地址(运营商专线等),能用就照常列出来,只是**排在私网地址之后**;
- **自动配置地址**(`169.254` 开头):说明**本网段没有 DHCP**、地址是设备自己配的——在**独立小网络**(没有路由器、设备直连或只接一台交换机)里这是**正常用法**,同网段设备可以互相访问。这类地址**排在最后**,旁边有一句「自动配置地址:本网段没有 DHCP,同网段设备可以互相访问」;
- **两种「不那么确定」的来源会各带一句提示,照常能用**(链接与二维码照给,只是说清这条是怎么来的,打不开时换下一条):
- 网卡状态读不到(驱动或虚拟网卡)时:「网卡状态读不到(可能是驱动或虚拟网卡),地址本身可用,打不开就换下面一条」;
- 按系统默认路由推断出来时:「这条地址是按系统默认路由推断出来的(网卡枚举里没有它),地址本身可用,打不开就换下面一条」;
- **手动添加地址**:自动检测不到、或者列出来的不是你要的那个网段时,用卡片下方的「手动添加地址」(说明「自动检测不到时,把 ipconfig 里的 IPv4 地址填进来」)把 `ipconfig` 里那个地址填进去、点「添加」——**立刻出链接和二维码**。手填的**排在第一条**、带「手动」徽标,右边多一个「删除」可以撤掉;它记在浏览器本地(localStorage),**刷新不丢**,最多记 10 个。填错不会没反应,而是就地红字说明:没填「请先填一个 IP 地址」、带空格「地址里不能有空格,请重新复制一次 ipconfig 里的地址」、不像地址「这不像一个 IP 地址,请填 ipconfig 里的 IPv4 地址」、重复「这个地址已经在列表里了」;
- **空态**:会**列出检查过哪些网卡、各自为什么被跳过**,例如「没找到可用的局域网地址。已检查:以太网(接口未连接)、WLAN(只有 IPv6 地址)。」——原因有「**接口未连接**」「**只有 IPv6 地址**」「**接口没有地址**」「**回环接口**」四种,最多列 5 条,网卡更多时其余折叠成「**等共 N 块网卡**」。老版本服务端不返回这份清单时,显示的仍是「未检测到局域网地址(可能是没插网线 / 只有回环)。」;如果显示的是「服务端没有下发大屏端口,暂时拼不出能在别的设备打开的地址。」,那是服务端异常,重启 Console / 服务端后再看;
- 卡片底部注明「地址由服务端下发的端口与路径拼成;平板上打开后不必登录,大屏本身是只读的」——**平板 / 电视那边不用登录**,只有看这张卡片(也就是本管理面板)才需要身份;
- **权限**:这张卡片需要**录入员(recorder)及以上**登录才看得到,只读访客(guest)看到的是「只有登录后的录入员 / 管理员能查看局域网地址,当前为只读访客。」;账号权限不足时提示「当前账号没有查看权限,请先登录(该接口需要录入员及以上)。」;
- 复制失败(浏览器不允许自动复制)时会提示「复制失败 / 浏览器不允许自动复制,请手动选中地址复制」,手动选中地址复制即可。
+53 -1
View File
@@ -6,7 +6,59 @@
---
## dev_0.4.0(当前版本)
## dev_0.5.0(当前版本)
### 一句话
**没有数据迁移,旧赛事项目包照常导入**:本版改的是「大屏控制 → 局域网大屏」卡片的取证逻辑——地址改为**按地址类别**判定(`169.254` 自动配置地址不再被排除),并新增**宽松兜底 / 默认路由推断 / 手动添加地址**三层,空态会说明被跳过的网卡与原因。以前卡片会把「自动配置地址」当成没有可用地址,现已修正。
### ① 局域网大屏卡片改为按地址类别判定
- **以前**:只取「接口 Up 且非回环」的网卡,并把**链路本地地址(`169.254.x.x`)也排除**,理由写的是「DHCP 没拿到地址才自配的,说明网络不健康」——那是对网络健不健康的**猜测**,不是地址能不能用的**事实**。
- **现场形态**:有机器就在 **`169.254` 自动配置网段**(本网段没有 DHCP,设备靠链路本地地址互访),平板实测能访问 `http://169.254.79.190:19540/display`,网络与防火墙全通;而卡片却因为那条猜测显示「未检测到局域网地址」——**那是误判**。
- **现在**:只排除四类「作为对端访问目标没有意义」的地址——**回环、未指定(`0.0.0.0`)、组播、广播**;**链路本地(自动配置)地址与私网、全局地址一样进候选**,只是**排在最后**并带一句说明「自动配置地址:本网段没有 DHCP,同网段设备可以互相访问」。判定全部走标准库谓词,**不抄一份网段字面量到代码里**(抄错或漏一段就会变成「明明有地址却说没有」,正是这次要修的毛病)。
### ② 新增三层兜底(宽松兜底 / 默认路由推断 / 手动添加地址)
| 层次 | 触发时机 | 卡片表现 |
| --- | --- | --- |
| 严格轮 | 正常机器(网卡 up 位读得到) | 地址照常列出,不加提示 |
| **宽松兜底** | 严格轮一无所获时(Windows 上部分驱动 / 虚拟网卡**读不到 up 位**) | 不再要求 up 位,把地址捡回来并提示「网卡状态读不到(可能是驱动或虚拟网卡),地址本身可用,打不开就换下面一条」 |
| **默认路由推断** | 前两轮都为空时 | 问操作系统「去局域网走哪块网卡」(UDP Dial:只查路由表、**不发一个包**),地址提示「这条地址是按系统默认路由推断出来的(网卡枚举里没有它),地址本身可用,打不开就换下面一条」 |
| **手动添加地址** | 以上都没给出你要的网段时 | 卡片下方「手动添加地址」填入 `ipconfig` 里的 IPv4 地址,点「添加」立刻出链接与二维码;手填的**排第一条**、带「手动」徽标、可「删除」,记在浏览器本地**刷新不丢**(最多 10 个) |
严格轮有结果就绝不跑宽松轮,前两轮任意一轮有结果就绝不跑路由探测——只有真的一个地址都拿不到时才会多花那几次本地 UDP connect,正常机器上一次都不会发生。
### ③ 空态会说明被跳过的网卡与原因
- 空态从一句「未检测到局域网地址(可能是没插网线 / 只有回环)。」改成逐条列出**检查过、但没贡献地址**的网卡与原因,例如「没找到可用的局域网地址。已检查:以太网(接口未连接)、WLAN(只有 IPv6 地址)。」;四种原因是「接口未连接」「只有 IPv6 地址」「接口没有地址」「回环接口」,**最多列 5 条**,网卡更多时其余折叠成「**等共 N 块网卡**」;
- 老服务端不返回这份清单时,显示的仍是原来那句,行为与升级前完全一致。
### ④ 没有数据迁移
- 本版**没有任何数据库迁移**,也没有设置项迁移;旧赛事项目包照常导入、切换、导出,已有榜单数字与升级前一致。
### ⑤ 升级后 3 分钟核对
1. 启动 Console,打开 `logs\console.log`:没有意外报错;正常应有一行「局域网地址:…(网卡名)」,一个地址都没有时会是一条带原因的 WARN,方便直接看出该修哪张网卡;
2. 用录入员及以上账号进「大屏控制」页,确认「局域网大屏」卡片列出地址;只有 `169.254.x.x` 的机器上应能看到它、并带「自动配置地址」那句说明;
3. 用平板 / 手机扫第一个地址的二维码,确认能打开大屏;
4. 自动检测为空时试一次「手动添加地址」(填 `ipconfig` 里的地址),确认立刻出链接与二维码;
5. 局域网设备连不上的机器,按《部署指南》7.5 的命令放行入站 **19540**;
6. 用《上线检查清单》过一遍。
### ⑥ 详细说明在哪
| 想了解 | 看 |
| --- | --- |
| 三类地址的含义、手动添加地址 | 《使用手册》第 9 节 |
| 防火墙放行与排障常识 | 《部署指南》7.5、7.9 |
| 空态原因与自检工具 | 《常见问题》Q101 |
| 接口字段与判定顺序 | `devdocs/05` 大屏控制与运维 |
---
## dev_0.4.0
### 一句话
+10
View File
@@ -679,3 +679,13 @@ Console 启动的多屏窗口默认每屏锁定一页。到「大屏控制」点
新录的这条会成为该小项该级别的**当前纪录**,原来那条自动变成非当前(仍留在库里)。纪录库的 **「来源」列**因此有了两种值:**历史** = 赛前手工登记的旧资料,**本届** = 本场赛事批准破纪录时自动写入的(以前没有历史录入入口,实际只会看到「本届」)。
**删除**:每行右端有「删除」(需**录入员及以上**)。确认框会说明「若它是当前纪录,会恢复上一条」,并注明「删除只影响纪录库,不会改动任何已发布的成绩与积分」;删除不会触发重算。
**Q101:大屏控制页显示「未检测到局域网地址」怎么办?**
先说结论:这多半不是故障,而是主机此刻没有「别的设备能连上」的地址被系统枚举出来。按下面顺序排查:
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`(改过端口就换成实际端口);临时关闭防火墙只用于**验证**是不是它挡的,验证完要恢复;
5. **还不行就跑自检**:运行 `debug\诊断\局域网地址自检.exe`,把它的输出发回给我们。
+26
View File
@@ -388,6 +388,31 @@ scoreboard.exe passwd -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -da
副屏的全屏窗口被误关时,用这里的「创建全屏窗口」就能恢复,不必重启 Console。
**「局域网大屏」卡片:怎么拿到地址(两条路)**
1. **卡片自动检测**:「大屏控制 → 局域网大屏」卡片会列出主机上可用的地址,直接点开或扫码;第一个地址(也就是二维码那一条)就是现场最可能要用的;
2. **`ipconfig` 手填**:自动检测不到、或者列出来的不是你那张网卡时,在管理员 cmd / PowerShell 里跑 `ipconfig`,把对应网卡的 **IPv4 地址**抄进卡片下方的「手动添加地址」再点「添加」——手填的排在第一条、带「手动」徽标,记在浏览器本地,刷新不丢(最多 10 个,可「删除」)。
**三类地址的含义**(卡片按类别判定,只排除回环 / 未指定 / 组播 / 广播这四类对本机之外没有意义的地址):
| 类别 | 形如 | 现场含义 | 排序 |
| --- | --- | --- | --- |
| 内网地址 | `192.168.x.x`、`10.x.x.x`、`172.16–31.x.x` | 路由器 / 交换机分配或手工设的地址,最常用的现场形态 | 最前 |
| 全局地址 | 其它网段(运营商专线等) | 能用就照常列出,但多半要经中间设备才通,不一定平板能直连 | 居中 |
| **自动配置地址** | **`169.254.x.x`** | **本网段没有 DHCP**,地址是设备自己配的;在独立小网络(没路由器、设备直连或只接交换机)里是**正常用法**,同网段设备可互相访问 | 最后 |
另外两种来源会各带一句提示、**照常能用**:网卡状态读不到时提示「网卡状态读不到(可能是驱动或虚拟网卡),地址本身可用,打不开就换下面一条」;按系统默认路由推断出来时提示「这条地址是按系统默认路由推断出来的(网卡枚举里没有它),地址本身可用,打不开就换下面一条」。
**防火墙必须放行入站 19540**(默认端口,改过端口就换成实际端口)。在**管理员** cmd 里跑:
```bat
netsh advfirewall firewall add rule name="Scoreboard 19540" dir=in action=allow protocol=TCP localport=19540
```
为什么安装包不能替你加这条:安装包是**免管理员的按用户安装**(默认装到当前用户目录),**不申请管理员提权**,所以改不了系统防火墙规则;这一步必须由现场用管理员身份手动做一次。临时关掉防火墙只能用来**验证**「是不是防火墙挡的」,验证完要恢复;正式开赛前一定用上面这条命令放行,而不是一直关着防火墙。
**排障常识**:Windows 里「网线插着、网卡显示 Up」**不等于拿到了 IP**;`ipconfig` 里看到 `169.254.x.x` 说明**本网段没有 DHCP**(地址是设备自配的)——这在**独立小网络**里是正常用法,**不是故障**,同网段的平板 / 手机照样能访问。
### 7.6 公告
管理端「大屏控制 → 公告」推送后:
@@ -421,6 +446,7 @@ http://<主机IP>:19540/display
- 这个地址不用手敲:管理端「大屏控制 → 局域网大屏」卡片里有**可复制的完整链接**与**二维码**(第一个地址),别的设备扫码或在浏览器里粘贴即可打开(该卡片需录入员及以上登录才看得到);
- 需要主机设置固定 IP,且设备与主机在同一局域网;
- **主机防火墙要放行入站 19540**(默认端口):安装包是按用户安装、不申请管理员提权,改不了防火墙规则,需要在**管理员** cmd 里手动执行一次,命令与说明见 7.5;
- 安卓电视一般常亮,无需额外防熄屏;
- 浏览器方案**不受** Console 的 kiosk、防熄屏、选屏控制,字体与动画表现以实际设备为准;
- 现场以 Console + HDMI 为主方案,浏览器访问作为备用。