packServer/desktop/README.md
liufumingren 1dc3404eae fix(osd): 空闲回退写回摄像头名,不再写工作台名
- DesiredText:60 秒没扫到时还原成**摄像头自己的名字**(摄像头没名字才退回工作台名,
  避免把通道名写空)
- 配置里被移除的摄像头同样还原成摄像头名
- 同步注释与文档(桌面 README / 根 README / 后端接口注释)
- 实测(真实 NVR 通道 35/37):首次="测试A/测试B"、扫码="测试A 7734… / 测试B 7734…"、
  70 秒后回退="测试A/测试B",三个阶段的并行时间差 50~103ms

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-01 06:55:07 +08:00

1024 lines
80 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 云仓视频溯源软件(本机服务 / WPF)
Windows 桌面端,用**前端 `/local` 公共页**和 **Chrome 插件**做对接:
- **登录页**:账号密码登录后端(`POST /api/web/auth/login`)拿 user JWT,令牌存本机;
下次启动先用 `/api/web/me` 验证,还有效就直接进主界面;
- 在 `127.0.0.1:17300` 起一个本机 HTTP 服务,浏览器里的页面直接查询本机数据;
- 注册 `yuncang://` 启动协议,网页可以「叫醒」本软件(前提是已安装);
- **托盘图标**:关窗口只是缩到托盘(本机服务不能因关窗断掉),双击托盘恢复窗口,
右键菜单有「打开主界面 / 重启软件 / 退出」;
- **界面不展示服务地址**:登录页和主界面都不显示后端地址 / 本机端口,它们属于内部实现细节;
后端地址由构建注入(`package.config.json` 的 `serverBaseUrl`),需要临时指向别处时用启动参数
`--server=http://x.x.x.x:7300`(只对本次运行生效,不写进界面)。
- **防多开**:全局互斥体 + 命名管道 —— 第二个实例不会抢 17300 端口,而是把
`yuncang://open?code=xxx` 转给已运行的实例(在托盘里也会被叫出来并直接查询),然后自己退出。
```
desktop/
├── YuncangTrace.LocalService.csproj # net8.0-windows + UseWPF + UseWindowsForms(托盘)
├── app.manifest # 高 DPI / 兼容性声明
├── Assets/app.ico # 程序/托盘图标(tools/make-icon.ps1 生成)
├── App.xaml / App.xaml.cs # 防多开 + 托盘 + 登录流程 + 本机服务生命周期
├── LoginWindow.xaml / .xaml.cs # 账号 / 密码 / 记住账号 / 自动恢复登录(不展示服务地址)
├── MainWindow.xaml / .xaml.cs # 服务状态、测试查询、菜单、退出登录
└── Services/
├── LocalHttpServer.cs # 本机 HTTP(17300):查询 / 唤起登录 / 下载录像
├── LoopbackHttpServer.cs # 回环 HTTP/1.1 服务端(TcpListener 自实现,不依赖 HTTP.sys)
├── LocalWsServer.cs # WebSocket(17301):拉通道 / 预览推帧 / 云台 / 满帧率窗口
├── OrderQueryService.cs # ★ 按运单号查数据(接真实数据源的地方)
├── ApiClient.cs # 登录 / 校验令牌(用到的全部后端接口)
├── SessionStore.cs # 登录态(%LOCALAPPDATA%\YuncangTrace\session.json)
├── AppSettings.cs # 服务器地址 / 记住账号(%LOCALAPPDATA%\YuncangTrace\settings.json)
├── ProtocolHelper.cs # yuncang:// 注册/反注册、解析 code
├── SingleInstance.cs # 互斥体 + 命名管道转发参数(防多开)
├── TrayIconService.cs # 托盘图标与菜单
├── AppLog.cs # 日志落文件:软件目录\logs\log_yyyy-MM-dd.txt(按天一个)
└── JsonUtil.cs # JSON 序列化(中文不转义)
```
## 登录 / 托盘 / 防多开的行为
| 场景 | 行为 |
| --- | --- |
| 首次启动 | 先起本机服务(17300 HTTP + 17301 WS)与托盘,再弹登录页 → 登录成功才出主窗口 |
| 启动时检查更新 | 进登录页的同时就开始查 `GET /download/version.json`(老版本用户卡在登录页也能收到提示)。**查到的版本不会塞进登录窗的模态循环**:登录窗还开着就先记下,等主窗口显示完再弹(`_pendingUpdate`)。以前直接盖在登录页上,会撞上「登录窗要关闭、但它挂着模态子窗」→ 父子窗一起被隐藏、两个模态循环互等,**主界面永远出不来**(日志停在 `已恢复登录` 之后,进程还在但没有任何窗口) |
| 已有令牌 | 登录窗一闪而过:`/api/web/me` 通过就直接进主窗口;失效则清掉令牌留在登录页 |
| 关窗口(X) | 隐藏到托盘,本机服务继续跑(第一次会冒一个气泡提示) |
| 再次双击 exe / 点网页「启动本机软件」 | 不会开第二个:把 `yuncang://open?code=…` 通过命名管道转给已运行实例;**没带参数(双击快捷方式)也会转发一条 `--show`**,让已运行实例把主界面叫到前面 —— 以前这种情况什么都不发、第二个实例直接退出,表现就是「点图标没反应」 |
| 托盘双击 / 右键「打开主界面」 | 恢复窗口 |
| 托盘右键「重启软件」 | 等 2 秒后拉起新进程(先退出才能释放单实例互斥体与 17300) |
| 「退出登录」 | 清令牌 → 关闭主窗口 → 回到登录页(取消登录则退出程序) |
| 网页请求唤起登录(`POST /api/activate-login`) | 未登录:登录窗弹到最前;已登录:主界面弹到最前(不影响本机服务) |
| 托盘右键「退出」 | 真正退出(dispose 托盘与本机服务) |
> 主界面**没有「停止服务 / 启动服务」**:本机服务跟随程序生命周期(启动即开、退出即停)。
> 留个停止按钮只会让用户误点后网页再也叫不醒软件(显示内容与「未安装」一模一样)。
> 也**没有「复制唤醒地址」**:唤醒地址由插件生成,不需要在界面上手测。
>
> 主界面顶部菜单:
> - **工具**:测试查询(聚焦输入框)、打开日志目录、清理日志、清理更新缓存(`%TEMP%\YuncangTraceUpdate`)
> - **服务**:服务状态(只读)、重启软件
> - **帮助**:检查更新、关于(版本 / 环境 / 运行状态)
>
> **日志不在界面上显示**,只写文件(按天一个,方便直接发给别人排查):
> `<软件目录>\logs\log_2026-09-22.txt`,行格式 `[2026-09-22 14:03:11] 内容`。
> 软件目录不可写时(如装到 Program Files)自动退回 `%LOCALAPPDATA%\YuncangTrace\logs`。
> 「工具 → 打开日志目录」用资源管理器打开它,「清理日志」删掉全部 `log_*.txt`(当天文件也能删,之后会重建)。
## 环境配置(开发 / 生产)
和前端 `VITE_BACKEND` 一个思路:**由构建决定,不靠用户手填**。
| 构建 | `env` | 默认后端 |
| --- | --- | --- |
| `dotnet build`(Debug) | `Development` | `http://127.0.0.1:7300`(= 前端 dev 代理的后端) |
| `dotnet build -c Release` | `Production` | `https://packs.example.com`(占位,打包时必须覆盖) |
打包正式版时指定真实域名:
```powershell
dotnet publish -c Release -r win-x64 -p:ServerBaseUrl=https://trace.example.com -o publish
```
优先级(从高到低):
1. 启动参数 `--server=http://192.168.1.10:7300`(临时,不落盘);
2. 环境变量 `YUNCANG_SERVER`;
3. `-p:ServerBaseUrl=` 注入的构建默认值;
4. 用户在登录页手改并保存的地址(`settings.json`)。
几个细节:
- 地址等于**内置默认值**时,`settings.json` 里存空串 —— 所以换 Debug/Release 构建能自动跟随,
不会被上一次构建的默认值钉死;只有用户手改过的地址才会持久化。
- 换地址后**不会复用旧令牌**(`session.json` 里的 `ServerBaseUrl` 对不上就要求重新登录)。
- `GET /api/query/{code}` 会回 `env` 和 `server`(排査环境是否装错时先看这两个字段;没登录时也带)。
## 环境要求
- 编译:**.NET 8 SDK**(`dotnet --list-sdks` 能看到 `8.x`)
- 只运行已发布的 exe:**.NET 8 Desktop Runtime**(不需要 SDK)
- 打安装包:`desktop\native\ffmpeg\ffmpeg.exe` 必须存在(见 [native/ffmpeg/README.md](native/ffmpeg/README.md))
- **默认普通权限运行**:`app.manifest` 是 `asInvoker`(不是 `requireAdministrator`)。
双击、开始菜单、网页 `yuncang://` 协议唤起都**不弹 UAC**。
- **只有改系统时间才提权**:NTP 窗口点「立即校时 / 同步 NVR 时间」时,才会用 `runas` 拉起
一个只做校时的临时进程(弹一次 UAC,见 `Services/ElevatedNtp.cs`)。
非管理员启动时,启动/定时自动校时会跳过(日志有 `[ntp] 当前不是管理员权限`)。
> **ffmpeg 已打进安装包**(`native\ffmpeg\ffmpeg.exe`)。客户机(尤其是非设备服务器的查件电脑)
> 不需要自己装 ffmpeg 就能做回放校验、多路合并。bin 里的 exe **不再**去 PATH 里找 ffmpeg 时才可用 ——
> 开发时仍可用环境变量 `YUNCANG_FFMPEG` 覆盖版本。
> 本机 SDK 装在用户目录(免管理员):`%LOCALAPPDATA%\Microsoft\dotnet`,
> 已加入用户 `PATH` 和 `DOTNET_ROOT`。**新开的终端**才能直接用 `dotnet`;
> 老终端里临时用:`$env:DOTNET_ROOT="$env:LOCALAPPDATA\Microsoft\dotnet"; $env:Path="$env:DOTNET_ROOT;$env:Path"`。
> 直接双击 `bin\...\*.exe` 也需要 `DOTNET_ROOT` 已生效(否则报 “You must install .NET”)。
> 官方安装包:`winget install --id Microsoft.DotNet.SDK.8 -e`(要 UAC)。
## NTP 校时(2026-10-19)
扫码时间取**本机时钟**,回放按**录像机本地时间**定位;本机时间不准会让录像整体错位
(现场实测 Windows 时间服务没启动,本机慢了近 10 秒,30 秒的回放窗口直接把面单截到窗口外)。
- **入口在「服务 → NTP 校时…」**,只有**设备服务开启**(服务模式)时才显示;关闭设备服务后菜单隐藏。
- **服务模式强制项**:NTP 校时必须启用、启动时必须校时、定时校时不能停(间隔至少 5 分钟),
窗口里的两个开关会置灰,保存时后端(桌面端)也会再强制一次。
- 设置项:NTP 服务器、自动校时间隔(分钟,0 = 仅启动时)、「立即校时」。
- **「同步 NVR 时间」**:拉取当前主体全部录像机(`GET /api/web/nvrs`,后端已有,无需新增接口),
逐台静默执行:
1. 用 8000 私有协议写 NTP(`NET_DVR_SET_NTPCFG`,与桌面端**同一个 NTP 地址**);
2. 立即生效:`NET_DVR_SET_TIMECFG` 把设备时间直接校准到 NTP 时间;
3. **顺带把该录像机下的摄像头逐个校时**(`GET /api/web/nvrs/:id/channels` 拿通道号 →
`NET_DVR_SET_TIMECFG` 带通道号,录像机转发给 IPC),逐个通道报成功/失败;
4. 回读 NTP 配置与设备时间,在窗口里逐台返回结果(✔/✘ + 偏差 + 摄像头 n/m)。
- **为什么必须单独校摄像头**:画面里烧的 OSD 时间是**摄像头自己**的时钟,录像机录像用的是
录像机时钟 —— 两者互不相干。只校录像机时,有的 IPC 会自己跟随,有的不会(现场实测
通道 34 的 OSD 比录像机快 13 小时、通道 45 差约 2 年),回放再对齐也改不了这两行字。
个别第三方 IPC 会拒绝校时,窗口里会列出具体通道和错误(不影响其它通道)。
- 启动时校一次 + 运行期间默认每 **30 分钟**校一次;偏差小于 **0.2 秒**不调整。
- 实现:`Services/NtpClient.cs`(UDP 123 SNTP)+ `Services/ClockSyncService.cs`
(打开 `SeSystemtimePrivilege` 后调用 `SetSystemTime`);NVR 侧在 `HikDeviceService.GetNtpConfig/SetNtpConfig/SetDeviceTime`。
- 改系统时间需要管理员,但**不再要求整个软件以管理员启动**:
非管理员时点「立即校时 / 同步 NVR 时间」会通过 `runas` 起一个只做校时的临时进程
(`--ntp-sync-elevated`,见 `Services/ElevatedNtp.cs`),结果写到临时 JSON 供主进程读回;
用户点「否」只提示「已取消」,不会报错。
- 日志:`[ntp] 启动校时完成:ntp.aliyun.com 偏差 +9.60 秒,往返 30 ms`;
`[ntp] 同步 NVR 完成:1/1 台(…)`;失败只记日志,不影响登录/查询。
- 回放侧仍会按录像机时钟做二次对齐(`HikPlaybackService.ClockOffset`),
即使本机时间临时不准也不会截掉面单。
- **「同步 NVR 时间」直接写时间**:`NET_DVR_SET_TIMECFG` 写的是**设备本地时间**,我们写本机本地时间
(NTP 校准后的值)。前提是**录像机时区必须是东八区**——现场曾把录像机时区设成伦敦(GMT+0),
设备把本地时间当 UTC 推给摄像头,导致录像 OSD 整体跑偏 8~14 小时,而且**烧进视频后改不回来**。
软件走 8000 协议读不到时区,所以这一项由现场保证(时区改好后再同步)。
- **通道名走 8000 私有协议**:`NET_DVR_GET_IPPARACFG_V40`(IP 接入配置)里没有名字,
所以拉通道时对每个 `enabled` 通道再读一次 `NET_DVR_GET_PICCFG_V30`,结构体头部的
`sChanName`(偏移 4,32 字节,**GBK** 编码)就是通道名 —— 实测 32 路约 250ms,中文正常。
**不需要设备的 Web/ISAPI 端口**(很多现场只开 8000)。
- ISAPI 只是兜底:只有当 PICCFG 一个名字都没拿到(极老固件)才去读
`/ISAPI/ContentMgmt/InputProxy/channels`(先 500ms TCP 探测,依次试 80 / 443 / 8443,
设备自签证书不校验,按 IP 匹配、IP 对不上再按 ISAPI 的 `id` 推);
仍然失败就把名字留空,前端拼「NVR名-通道号」,不影响其他字段。
云台探测 / 时区读写**仍然完全不依赖 ISAPI**(`/api/hik/channels` 的 `webPort` 参数已删除,旧前端传了会被忽略)。
## 构建 / 运行 / 发布
## 构建 / 运行 / 发布
```powershell
cd desktop
dotnet build # 编译(Debug = 开发环境,连本地 7300)
dotnet build -c Release # 编译(Release = 生产环境,默认地址见上一节)
dotnet run # 直接跑(调试)
# ★ 发给用户、以及要用「网页叫醒」的话,必须用自包含发布
dotnet publish -c Release -r win-x64 --self-contained true `
-p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true `
-p:ServerBaseUrl=https://正式域名 -o publish
```
**为什么要自包含**:`dotnet build` 出来的 exe 是 *framework-dependent* 的,
它自己会去找 `C:\Program Files\dotnet` 或 `DOTNET_ROOT`。从**浏览器/资源管理器/协议**拉起的进程
拿不到我们临时设的环境变量,于是弹「You must install .NET Desktop Runtime」——
网页上表现就是「唤起没反应 / 弹安装提示」。
自包含单文件(约 154 MB)把运行时打进去了,双击和协议唤起都能直接跑,用户什么都不用装。
> `desktop/nuget.config` 指向华为云 NuGet 镜像(本机访问不了 api.nuget.org)——
> 自包含发布要下载 `Microsoft.*.App.Runtime.win-x64` 运行时包,没有镜像会 restore 失败。
开发阶段想让 `bin\Debug` 的 exe 也能直接双击,两个办法:装官方 SDK/Desktop Runtime 到标准位置,
或者每次用发布产物验证唤起。
## 打安装包(MSI / EXE)+ 自动更新
`desktop/installer/` 下有两套安装包定义,产物一样(perUser、装到同一个目录、注册同一个 `yuncang://` 协议):
- **MSI**(`Product.wxs`,**WiX 5**,免费;WiX v6+ 需要 OSMF 付费协议,别装最新版);
- **EXE**(`YuncangTrace.iss`,**Inno Setup 6**)——**完全不依赖 Windows Installer**。
> 为什么要 EXE:现场有电脑装不了 MSI(Windows Installer 服务被禁用 / 安全软件拦 MSI / 组策略禁止)。
> 这类机器用 EXE 版;装过旧 MSI 的机器再装 EXE 时,EXE 会先静默卸载旧 MSI,不会在「应用和功能」里留两个条目
> (旧 MSI 的卸载会把文件删掉,必须清掉)。MSI 卸载失败(正是 MSI 坏掉的现场)时,EXE 会尽量移除它的卸载项
> (HKLM 下的条目要管理员权限,删不掉只记日志)—— 避免以后误点「卸载」把新装的文件删了。
```powershell
# 工具只需装一次
dotnet tool install --global wix --version 5.0.2 # MSI
winget install --id JRSoftware.InnoSetup # EXE(提供 ISCC.exe)
cd desktop\installer
.\build.ps1 # 开发环境(默认),版本取 csproj,MSI + EXE 都打
.\build.ps1 -Target Exe # 只打 EXE
.\build.ps1 -Target Msi # 只打 MSI(老流程)
.\build.ps1 -Version 1.0.1 # 指定版本
.\build.ps1 -Environment Production -Version 1.0.1 -ReleaseNotes "修复若干问题"
.\build.ps1 -Target Exe -SkipDeploy # 只在 out\ 出包,不复制到后端(调打包用)
```
### 环境与域名(`package.config.json`)
| 环境 | 默认后端 | 用途 |
| --- | --- | --- |
| `Development` | `http://127.0.0.1:7300` | 本机联调;打完会自动把包+版本信息复制到后端,本机就能测更新 |
| `Production` | `https://packs.example.com`(**占位,发布前必须改成正式域名**) | 正式安装包 |
`build.ps1 -Environment Production` 自动用生产域名打 exe(`ServerBaseUrl`)和下载地址;
也可以用 `-ServerBaseUrl` 临时覆盖。
### 脚本做了什么
1. `dotnet publish`(自包含单文件,不依赖 .NET 运行时;版本号一起注入程序集);
**同时把 `native\HCNetSDK\**`、`native\ffmpeg\**`、`..\extension\**` 作为独立文件输出**(不走单文件自解压);
缺 `publish\native\ffmpeg\ffmpeg.exe` 会直接报错中止;
2. `wix build` 生成 MSI(`Product.wxs` 用 `<Files Include="..\publish\native\**" />`、`<Files Include="..\publish\extension\**" />`
递归收集,保持目录结构;`extension\test` / `extension\tools` 这类调试文件不打进包);
`ISCC` 生成 EXE(`YuncangTrace.iss` 把 `publish\` 下的 exe / `native\**` / `extension\**` 打进单个安装包);
3. 算 MD5 → 写 `version.json`(MSI 一份、EXE 一份);
4. 复制到后端:安装包 → `backend/app/public/download/desktop/`,`version.json` → `backend/app/public/version/desktop/`;
5. 本地 `out/` 与后端目录**各只保留最近 5 个**安装包(`.msi` / `.exe` 分别算,`keepVersions` 可配)。
> 安装包与版本信息都归到后端 `desktop` 子目录:下载地址 `<域名>/download/desktop/YuncangTraceSetup-x.y.z.exe`(新客户端)
> 和 `.msi`(老客户端),版本信息仍是 `<域名>/download/version.json`(老客户端写死了这个地址,不能改)。
### 谷歌浏览器插件
仓库根目录的 `extension/dist`(压缩产物)会一起打进 MSI / EXE,安装后固定在 **`<安装目录>\extension`**
(perUser 安装即 `%LOCALAPPDATA%\Programs\YuncangTrace\extension`)。
**首选:Edge 加载项商店(非受管电脑也能装)** ——
- 菜单「工具 → **安装浏览器插件(Edge 应用商店)**」:装了 Edge 就用 `msedge.exe` 打开
`https://microsoftedge.microsoft.com/addons/detail/mgdonmkicojkabgalgekobaoohaohfcj`,
用户点「获取」即可;**不需要开发者模式,也不需要管理员权限**;
- 这个链接**审核通过后**才有效(审核中打开是 404);商店版扩展 ID 是 `mgdonmkicojkabgalgekobaoohaohfcj`;
- 只对 Edge 有效:Chrome 装不了 Edge 商店的扩展,请走下面的企业策略或开发者模式。
**受管设备:企业策略安装(零开发者模式)** —— `Services/ExtensionInstaller.cs`:
- 菜单「工具 → **安装浏览器插件(企业策略:Chrome / Edge)**」:先拉后端 `/download/extension/updates.xml`
读出扩展 ID,再生成 `.reg` 文件、**runas 执行 `reg import`** 写 HKLM 策略(Chrome + Edge),
最后**读注册表**确认结果(不依赖子进程回传,早期用「提权起自己 + 临时文件回传」现场踩过
「退出码 0 但结果文件没写」的坑):
- `ExtensionInstallForcelist = <ID>;https://<域名>/download/extension/updates.xml`
- `ExtensionInstallSources = https://<域名>/download/extension/*`
- 重启浏览器后自动装好,之后由 `updates.xml` 自己升级;`chrome://extensions` 里显示「由你的组织管理」;
- 菜单「工具 → **卸载浏览器插件(企业策略)**」:只删值里带 `/download/extension/` 的那几条,不影响别人写的策略;
- 前提:发布端已执行过 `cd backend && npm run extension:publish`(产出 `.crx` + `updates.xml`);
扩展 ID 由 `extension/keys/key.pem` 决定,**换私钥 = 换 ID = 已下发策略失效**,私钥务必备份;
- 提权失败 / 设备未纳管时,弹窗会直接引导到「Edge 商店」或「开发者模式」两条路。
> ⚠️ 商店版(`mgdon…`)与自建 CRX(`lkei…`)是**两个不同 ID 的扩展**:同一浏览器都装会同时注入、
> 页面被标记两遍。从自建 CRX 切到商店版前,先点「卸载浏览器插件(企业策略)」。
**兜底:开发者模式** ——
- 菜单「工具 → 复制插件路径(开发者模式)」直接把该目录的 **Windows 路径**(如 `C:\Users\xxx\AppData\Local\Programs\YuncangTrace\extension`)复制到剪贴板;
写剪贴板全程在后台 STA 线程、带截止时间退避重试(WPF → WinForms → 补 `OleFlushClipboard`),
被远程桌面(实测 BilldDesk)/ 输入法 / 剪贴板工具占用时不会卡住界面、也不会误报;
**复制前先核对内容**:剪贴板里已经是这个路径就直接算成功;确实写不进去才提示,并告知是哪个进程占着,可选「打开记事本」手动抄写;
- 用户打开 `chrome://extensions` → 打开「开发者模式」→「加载已解压的扩展程序」→ 粘贴路径即可;
- 卸载时该目录随安装包一起删除;
### 自动更新怎么工作
```
软件启动(登录后)→ GET {后端}/download/version.json?t=时间戳
→ version.json 的 version 比当前程序集版本新
→ 软件内弹窗:新版本号 / 更新说明 / 安装包大小
→ 点「立即更新」→ **软件内下载(进度条)**→ MD5 校验
→ 自动静默安装(EXE 走 /VERYSILENT /SUPPRESSMSGBOXES /NORESTART;MSI 走 msiexec /passive)
→ 软件退出 → 装完自动重新打开
```
- **不跳浏览器**:下载、进度、校验、安装都在软件里完成。
- 下载落在 `%TEMP%\YuncangTraceUpdate\`,文件名取下载地址里的真实文件名。
- 安装前会等 3 秒(让本进程先退出,否则 exe 被占用换不掉);perUser 安装不需要管理员。
- **优先 EXE 包**:`version.json` 有 `downloadUrlExe` 就下 EXE(不依赖 Windows Installer,现场装不了 MSI 的机器也能升);
- **校验值必须成对取**:下 EXE 用 `md5Exe` / `sizeExe`,下 MSI 用 `md5` / `size`。
(`≤1.0.151` 的旧客户端两个都取 `md5`,于是下 EXE 拿 MSI 的哈希去比 → 必然「MD5 不一致」;
给这些机器的第一个修复版要只发 MSI,见 backend/README 的 `--target=Msi`);
没有该字段才退回 `downloadUrl`(MSI)。老客户端只认 `downloadUrl`,所以打包脚本**默认两个包都出**。
- **版本一致性防护**:若下载地址里的包版本(`YuncangTraceSetup-x.y.z.msi` / `.exe`)不比当前版本新,
直接忽略 —— 防止 version.json 配错/漏传包导致「装完还是旧版 → 无限弹窗」。
- 回归测试可用环境变量 `YUNCANG_AUTO_UPDATE=1` 让弹窗出现后自动开始下载(无需手点)。
`version.json` 长这样(脚本生成,**不用手写**):
```json
{
"version": "1.0.1",
"downloadUrl": "https://正式域名/download/desktop/YuncangTraceSetup-1.0.1.msi",
"md5": "7a93b4…",
"size": 141578240,
"downloadUrlExe": "https://正式域名/download/desktop/YuncangTraceSetup-1.0.1.exe",
"md5Exe": "d5c75e…",
"sizeExe": 118886550,
"publishedAt": "2026-10-17T12:00:58+08:00",
"buildId": "20261017120058",
"environment": "Production",
"releaseNotes": "修复若干问题"
}
```
> `downloadUrl`(MSI)是给老客户端的,**不能删**;`downloadUrlExe` 是新增字段,新客户端优先用它。
### ⚠️ 缓存(这里最容易踩坑)
Egg 的 `static` 在生产默认**强缓存一年**。如果 `version.json` 也被缓存,软件永远检测不到更新。
处理方式(都已实现):
| 层 | 做法 |
| --- | --- |
| 文件位置 | `version.json` 放在 `app/public/version/desktop/`,**不在静态目录里** |
| 后端路由 | `GET /download/version.json` 由 `controller/download.js` 返回,显式 `Cache-Control: no-store`、去掉 `ETag`/`Last-Modified`(连 304 都不走) |
| 前端中间件 | `middleware/frontend.js` 放行 `/download/*`,否则会被 SPA 入口接管 |
| 客户端 | 请求带 `?t=毫秒时间戳` + `Cache-Control: no-cache` |
| 安装包本体 | 文件名带版本号 → `Cache-Control: public, max-age=31536000, immutable` |
> 生产前面如果还有 **nginx / CDN**,也要对 `/download/version.json` 关缓存,否则只在应用层关没用:
> ```nginx
> location = /download/version.json {
> add_header Cache-Control "no-store, no-cache, must-revalidate" always;
> proxy_no_cache 1;
> proxy_cache_bypass 1;
> proxy_pass http://127.0.0.1:7300;
> }
> ```
安装包行为:
| 项 | 说明 |
| --- | --- |
| 安装范围 | **perUser**(免管理员、无 UAC),装到 `%LOCALAPPDATA%\Programs\YuncangTrace` |
| 启动协议 | **安装即注册** `yuncang://`(HKCU),不需要先启动软件 |
| 卸载 | MSI 由 Windows Installer 删除;EXE 由安装目录下的 `unins000.exe` 删除。两者都会清掉 exe、协议注册、开始菜单 —— 即「取消注册」 |
| 升级 | MSI:`MajorUpgrade`(装新版替换旧版、拦降级);EXE:同一个 `AppId` 覆盖安装;**EXE ↔ MSI 可互相顶替**(装 EXE 时会先静默卸载旧 MSI) |
| 用户数据 | `%LOCALAPPDATA%\YuncangTrace\{settings,session}.json` 卸载**不删**(重装后仍保持设置/登录) |
```powershell
msiexec /i out\YuncangTraceSetup-1.0.1.msi # MSI 安装
msiexec /x out\YuncangTraceSetup-1.0.1.msi # MSI 卸载
.\out\YuncangTraceSetup-1.0.1.exe # EXE 安装(双击即可,免管理员)
.\out\YuncangTraceSetup-1.0.1.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /SP- # EXE 静默安装
```
> 需要「本机所有用户都能用」时:`Product.wxs` 里 `Scope` 改 `perMachine`、注册表根改 `HKLM`,
> 安装时会要管理员权限(UAC)。默认的 perUser 更省事,也够用(软件数据本来就是按用户存的)。
> ⚠️ `build.ps1` 必须保存为 **UTF-8 with BOM**:PowerShell 5.1 读无 BOM 的脚本会按 GBK 解析,
> 中文注释直接把语法搞崩。
### 验证自动更新(不卸载重装)
```powershell
cd desktop\installer
.\build.ps1 -Environment Development -Version 1.0.7 # 先发布一个更高版本(包+version.json 落到后端)
.\test-update.ps1 # 启动旧版本 → 等它自己升级上去
```
`test-update.ps1` 做的事:
1. 读后端 `/download/version.json` 的目标版本,和当前安装版本比较(已是最新就直接退出);
2. 关掉正在运行的软件(单文件自解压出来的真实进程);
3. 带 `YUNCANG_AUTO_UPDATE=1` 启动**旧版本**(更新窗口出现后自动下载,不用手点);
4. 轮询 `%LOCALAPPDATA%\Programs\YuncangTrace\*.exe` 的 `ProductVersion`,直到变成目标版本;
5. 检查本机服务 17300 是否有响应、进程是否已恢复。
输出形如:
```
当前安装版本:1.0.6
后端目标版本:1.0.7
启动旧版本 1.0.6(自动更新已开启)…
[3s] 安装版本 = 1.0.6+af3f8ab…
[6.1s] 安装版本 =
[10.4s] 安装版本 = 1.0.7+d32656a…
✔ 自动更新完成:1.0.6 → 1.0.7(耗时 10.4s)
✔ 本机服务 17300 有响应(HTTP 401)
✔ 软件进程已恢复(PID 12024)
```
> 每次测更新都要打一个**比当前安装版本高**的包(脚本会拒绝在"已是最新"时白跑)。
## 本机接口
本机软件开**两个**端口,职责分开:
| 端口 | 协议 | 用途 |
| --- | --- | --- |
| **17300** | HTTP | 运单查询 / 唤起登录 / 按运单下载录像(低频、无状态) |
| **17301** | WebSocket | 拉通道 / 实时预览(推 JPEG 帧)/ 云台 / 满帧率窗口(预览相关全在这里) |
### HTTP 17300(前端 `/local` 页用的就是这两个)
服务固定监听 `http://localhost:17300`(端口写在前端页面与插件里)。
`LoopbackHttpServer` 直接监听 **127.0.0.1 和 ::1**,所以 `localhost` / `127.0.0.1` 两种写法都能连
(前端改 `VITE_LOCAL_SERVICE` 时不会碰到「回 400」)。请求的 `Host` 不是回环地址会被直接断开。
> ⚠️ **别改回 `HttpListener`**:它依赖 HTTP.sys。现场机器上 HTTP 服务被安全软件/系统优化禁用,
> 或者卡在 STOP_PENDING 时,`HttpListener.Start()` 会抛 `句柄无效(6)`,HTTP 与 WS 会**同时**起不来
> (2026-10-23 升级 1.0.113 后的现场故障就是它)。自建 TcpListener 不需要 HTTP.sys / urlacl / 管理员权限。
浏览器直接打开 <http://localhost:17300/> 会看到一个说明页(列了接口,方便排查)。
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/query/{code}` | 查信息,**同时把服务/登录状态一起返回**(见下)。没登录 → 401 `state:need-login` |
| POST | `/api/activate-login` | 把本机软件的**登录窗叫到前台**(已登录时把主界面叫到前台)。网页收到 `need-login` 时自动调它 |
| POST | `/api/playback/download` | 按运单下载录像(存到本机设置目录) |
> ⚠️ 以前的海康接口(`/api/hik/channels`、`/api/hik/preview*`、`/api/hik/ptz*`)**已全部迁移到 WS 17301**,
> HTTP 侧不再提供(访问会得到 404「接口不存在」)。前端 `api/localWs.ts` 是唯一调用入口。
### WebSocket 17301(预览 / 云台 / 拉通道)
一条连接可同时推多路画面(一条工作台合成画面 4 路没问题)。文本请求 `{id, action, ...}`,
回复 `{id, ok, data | message}`;二进制帧 = `[1 字节 sid 长度][sid ASCII][JPEG]`。
| action | 参数 | 说明 |
| --- | --- | --- |
| `hello` | — | 服务名/版本/端口/登录状态 |
| `ping` | — | 探活 |
| `get_channels` | `host, port, user, password` | 走 8000 私有协议登录 NVR,返回通道列表(与原来 HTTP 返回同构) |
| `start_preview` | + `channel, fps?, streamType?, mode?, logicalChannel?, name?` | 建预览会话,之后持续推该 `sid` 的 JPEG 帧 |
| `stop_preview` | `sid` | 停一路、释放设备码流 |
| `open_window` | 同 `start_preview` | 在本机软件里开**满帧率原生窗口**(PlayM4 直渲染,25fps) |
| `close_window` | `wid` | 关原生窗口(网页断开时也会自动关) |
| `ptz` | + `command, stop?, speed?` | 云台连续动作(`stop=true` 停) |
| `ptz_preset` | + `presetAction`(set/goto/clear), `preset` | 预置点 |
> `start_preview` / `get_channels` / `open_window` / `ptz*` 在服务端**并发执行**,不会把
> 「停止预览 / 云台停转」堵在消息循环后面;云台命令之间按连接串行化,保证「开始转 → 停」不乱序。
>
> 端口可用 `YUNCANG_LOCAL_WS_PORT` 覆盖;前端用 `VITE_LOCAL_WS` 覆盖默认 `ws://127.0.0.1:17301/`。
#### 预览延迟(子码流 / 主码流是两条完全不同的链路)
| 码流 | 链路 | 典型延迟 |
| --- | --- | --- |
| 子码流(`mode=stream`) | 8000 私有协议 → PlayM4 解码 → 取 JPEG | 低,稳定 |
| 主码流(`mode=ffmpeg`) | RTSP → ffmpeg 解码/缩放 → 编码 JPEG | 取决于传输方式 |
主码流**不能走 TCP**:RTP over TCP 一旦有排队(设备发送缓冲、交换队列),延迟只会越堆越高、
而且永远不会自己追回来(TCP 不丢帧)。所以实时预览的 ffmpeg 参数固定为:
- 传输 `-rtsp_transport udp`(丢包宁可丢帧,不排队;4 秒还收不到帧会**自动回退 TCP**,
因为部分网络禁 UDP,不能让用户看不了画面);
- `-analyzeduration 0 -max_delay 0 -reorder_queue_size 0 -avioflags direct -fflags nobuffer -flags low_delay -fps_mode passthrough`
(不分析流、不攒包、输出侧不补帧);
- 回放(`OpenUrl` 的 `lowLatency=false`)**保持 TCP**:回放靠时间戳对齐,丢包会算错延迟。
排查用日志(`logs\log_日期.txt`):
- `ffmpeg 已启动:... UDP` / `TCP` —— 实际用的传输方式;
- `[ffmpeg] 首帧到达:... 用时 320ms(UDP)` —— 首帧耗时;
- `[ffmpeg] UDP 收不到帧,回退 TCP` —— 该网络不通 UDP。
### 为什么没有单独的「探活 / health」接口
探活通过 ≠ 真正查询时软件还在(用户可能中途退出了),两次请求之间状态会变。
把状态合进查询接口后,页面**只发一次请求**就能决定「展示结果」还是「提示可以唤起」:
| HTTP | `state` | 含义 |
| --- | --- | --- |
| 200 | `ok` | 查到了,`data` 是数据 |
| 401 | `need-login` | 软件在跑但**未登录**,页面去调 `activate-login` 并轮询本接口等登录 |
| 400 | `bad-request` | 参数不对(例:码为空) |
| 404 | `not-found` | 没这条记录 |
| 500 | `error` | 内部错误 |
**只有网络层失败(连不上 / 超时 / 被 CORS 拦)才代表「软件没启动」**,
这时页面提示「服务暂不可用 + 下载安装 / 启动本机软件」。
无论成败都带这些字段:`loggedIn`、`user`、`env`(`Development`/`Production`)、`server`(当前后端地址):
```jsonc
// 200
{ "ok": true, "state": "ok", "code": "ABC123", "loggedIn": true, "user": "管理员",
"env": "Development", "server": "http://127.0.0.1:7300",
"data": { "code": "ABC123", "orderNo": "SO-20261017-001", "videoPath": "D:\\video\\demo.mp4" } }
// 401
{ "ok": false, "state": "need-login", "code": "ABC123", "loggedIn": false, "user": null,
"env": "Development", "server": "http://127.0.0.1:7300", "message": "本机软件未登录,请先在软件里登录" }
```
示例:
```powershell
curl http://localhost:17300/api/query/321408064481776
curl http://localhost:17300/api/query/ # 400 bad-request,但带着登录状态
curl -X POST http://localhost:17300/api/activate-login
```
为什么唤起登录用 **POST**:GET 会被浏览器/聊天工具的链接预取误触发,POST 不会。
浏览器跨域(页面在站点域名上,请求的是 localhost)必须回这些响应头,代码里已经处理:
- `Access-Control-Allow-Origin`(回显 Origin)、`Allow-Methods`(`GET, POST, OPTIONS`)、`Allow-Headers`、`Max-Age`
- `Access-Control-Allow-Private-Network: true` —— 公网 https 页面访问 localhost 时 Chrome 会发
私有网络预检(PNA),不回这个头预检就失败
> ⚠️ 千万别只回 `200` 不带 CORS 头:浏览器会直接拦掉,前端看起来和「软件没启动」一模一样。
## 启动协议(网页叫醒本软件)
`yuncang://open?code=xxx`。注册写在 **HKCU**(免管理员):
```
HKEY_CURRENT_USER\Software\Classes\yuncang
(默认) = "URL:云仓视频溯源软件"
"URL Protocol" = ""
\shell\open\command
(默认) = "C:\...\YuncangTrace.LocalService.exe" "%1"
```
- **每次启动都会自动把注册项校正到「当前这个 exe」**(幂等)。这一点很关键:
换目录安装、从 `bin\Debug` 换成发布版、重新装一遍之后,注册表里残留的旧路径会让网页
唤起一个不存在 / 缺运行时的 exe(典型现象就是弹「You must install .NET」或干脆没反应)。
- **界面上完全不展示协议**:注册由安装包完成、卸载时自动删除,启动时自动校正到当前 exe;
用户不需要知道 `yuncang://` 这回事(排障看日志或注册表即可)。
- 手工注册/排查:
```powershell
reg add "HKCU\Software\Classes\yuncang" /ve /d "URL:云仓视频溯源软件" /f
reg add "HKCU\Software\Classes\yuncang" /v "URL Protocol" /d "" /f
reg add "HKCU\Software\Classes\yuncang\shell\open\command" /ve /d '"C:\Path\YuncangTrace.LocalService.exe" "%1"' /f
reg query "HKCU\Software\Classes\yuncang\shell\open\command"
```
- 打包工具里对应:Inno Setup 的 `[Registry]` 段、NSIS 的 `WriteRegStr HKCU ...`、Electron 的
`app.setAsDefaultProtocolClient('yuncang')`;
- 协议名改了要同步前端 `VITE_APP_PROTOCOL`(默认 `yuncang`)。
## 和前端 / 插件怎么配合
1. WMS 页面上点运单号旁的按钮 → 插件按「打开方式」处理:默认**直接用 `yuncang://open?code=<运单号>` 唤起本机软件**并定位到该单号
(浏览器会先问一次「要打开吗」);把打开方式改成「独立小窗 / 新标签页」则改为打开网页;
2. `/local` 页只发一个请求 `GET /api/query/{code}`:
- **连不上** → 提示「服务暂不可用 / 本地打印服务未启动,请下载安装后再试」+ 下载按钮;
点「已安装,启动本机软件」会走 `yuncang://open?code=...`,然后每秒重试同一个查询接口;
- **`need-login`**(软件没登录)→ 页面自动 `POST /api/activate-login`
把本机登录窗叫到前台,然后每秒重试**同一个查询接口**等登录完成(最长 30s),登录好**自动拿到结果**;
- **`ok`** → 直接展示(页面顶部会显示「本机软件已登录:xxx」)。
3. 本软件被协议拉起时,会拿到 `yuncang://open?code=xxx` 参数:已经开着就转给原窗口(单实例),
没开就启动 → 先登录 → 登录完自动查询这个码(登录前收到的 code 会先存着)。
单实例的命名管道监听**在登录之前就起来了**,所以用户卡在登录窗时被网页唤起也不会丢参数。
### 插件「直接唤起」与唤不起时的提示(重要)
浏览器**不会告诉网页**协议到底有没有打开成功 —— 没安装、协议没注册、用户在 Chrome 的
「要打开吗」上点了取消,这三种情况在页面侧**完全一样**。所以必须做超时兜底:
1. 点击 → 隐藏 iframe 触发 `yuncang://open?code=xxx`(不能导航当前页,否则协议没注册会变成错误页);
2. **判断到底成没成,不看页面焦点,看本机服务在不在**:协议触发后每 0.7s 探测一次
`http://localhost:17300/api/query/`(任何 HTTP 响应都算成功,扩展带 host 权限,不受页面 CSP 影响);
- 探测到 → 什么也不做(软件本来就在跑时也能正确判定,不会误报);
- 8 秒都探测不到 → 认为没起来,右下角弹出兜底卡片:
- **在网页中查看** → 打开插件设置里的「唤不起时的兜底页」(默认 `http://localhost:7301/local?code={code}`,
该页面里有完整的下载安装引导);
- **下载安装** → 打开插件设置里的「软件下载地址」(留空则不显示这个按钮)。
3. 插件设置页的相关配置:
- **打开方式**:`直接唤起本机软件(协议)`(默认)/ `独立小窗(网页)` / `新标签页(网页)`;
- **协议模板**(仅「直接唤起」时生效):默认 `yuncang://open?code={code}`;
- **网页地址模板**(仅小窗/标签页时生效):默认 `http://localhost:7301/local?code={code}`;
- **唤不起时的兜底页**、**软件下载地址**(留空则不显示「下载安装」按钮)。
老配置升级时会自动迁移(v3 把协议写在网页模板里的,会改成「打开方式 = 直接唤起 + 网页模板还原」),行为不变。
> 判定依据是「本机服务在不在」,所以**软件已经在跑时不会误报**(这是最常见的场景:
> 协议只是把参数转给已有实例,窗口不一定抢焦点)。真正的误报只剩一种:软件还没完全启动就超时 ——
> 那种情况提示一下也算合理。页面失焦只作为「快速判定成功」的辅助信号。
## ★ 接真实数据
运单查询已经接后端了:`Services/OrderQueryService.cs` 的 `QueryAsync(code)` 调
`GET /api/web/pack-query?code=`(用户令牌 + `X-Subject-Id`),**范围限定当前主体**。
后端用**扫码当时的工作台快照**(`scan_records.workstation_snapshot`)算好回放计划,
本机只负责把返回拍成「项目 / 值」两列:
| 字段 | 含义 |
| --- | --- |
| `扫码记录数` | 同一运单被扫了几次(不同中控/通道/重复扫) |
| `记录 N · 扫码时间` | 已转成本机本地时间 |
| `记录 N · 中控 / 通道` | 哪台中控的哪个通道 |
| `记录 N · 工作台` | 当时的工作台 + 类型(团购 / 散单) |
| `记录 N · 回放区间` | `开始 ~ 结束(秒)`,散单被最大录制时长截断时会标注 |
| `记录 N · 录像机` | 涉及的录像机(名称 + `IP:端口`) |
| `记录 N · 摄像头` | 通道号 + 名称 + 在画布上的位置/尺寸(多路合并要按这个摆) |
> **自动校验回放**:查询命中(后端返回了 `streams`)后,桌面端会**立刻**逐路去录像机试拉
> (每路 2 秒,面板里显示进度),**任意一路拉到录像就停止校验**并显示「预览回放 / 下载录像」按钮 ——
> 不需要把每一路都验完,也不需要用户手动点「校验」。
> 预览和下载仍按**全部**流处理:没录像的那几路在下载时自己跳过,保证多路合并不会退化成单路。
>
> **跨网(查询机和录像机不在同一张网里)**:局域网找不到「设备管理服务」时改问云端,由**能访问
> 录像机的仓库扫码服务**校验;这种查询只给「下载录像」,而且下载**走云端中转**(云端建任务 →
> 仓库设备拉流合并并上传 → 本机把成片取回),不再让本机直连录像机 —— 查询机到仓库 NVR 的
> 8000/554 本来就不通,直连只会让 ffmpeg 报 `退出码 -138`(RTSP 连接超时,`AVERROR(ETIMEDOUT)`)。
>
> **回放时间按录像机时钟对齐**:扫码时间来自本机时钟,回放是按录像机本地时间定位的。
> 每次校验/预览/下载前会读一次录像机时间(8000 私有协议),把请求窗口整体平移,
> 日志里能看到 `[playback] 录像机 … 与本机时钟相差 X 秒`。本机时间不准(比如 Windows
> 时间服务没开、慢了几秒)时,短回放窗口会把面单截到窗口外 —— 这一步就是防这个。
### 多路对齐(预览 / 合并下载)
几路回放是**各自独立连录像机**的,天然会有两处时间差,都要单独处理:
1. **开播时间差(预览)**:各路 RTSP 建链快慢不同,先出帧的那路会一直“跑在前面”。
`PlaybackPreviewWindow` 的做法是**先一起等、再按帧一起放**:
- ffmpeg **每出一帧回调一次**(`HikFfmpegService.Subscribe`)按顺序进各自队列。
⚠️ 不能定时去取“最新一帧”:ffmpeg 定位到关键帧后会把「关键帧→请求时间」整段一次吐出来,
只留最新帧会把这串前面全丢掉,那一路的“第一帧”其实是 1~2 秒后的画面(现象:小窗一出现就超前);
- 每一路都出过第一帧(最多等 12 秒,超时当这路没录像)后才开始播,每 40ms 从**每路队列各取一帧**,
先上线的那路放的就是等同步时攒下的积压 → 几路自然停在同一内容位置;
- 队列超过 220 帧(≈9 秒)就丢到 50 帧(≈2 秒),设备推得比实时快也不会越播越晚。
日志里出现 `[playback] 多路回放开始同步播放(各路基线帧数:…)` 就说明生效了。
**收尾以最长的那一路为准**:各路是从自己的关键帧起推的,同样 8 秒的请求,20fps 那路只有 8.0 秒、
25fps 那路有 9.0 秒;所以不看请求窗口,而是看「队列空了 + 1.5 秒没再收到新帧」判定这一路播完,
**先播完的那路定格在最后一帧**,等最长的那路播完再统一释放设备会话(另有
`Window + 15 秒` 的硬上限,防止设备一直推)。标题变成「回放结束(Xs)」,X 就是最长那路的时长。
2. **录制起点差(下载 / 合并 / 预览)**:回放是从“请求时间所在**关键帧**”开始推的,
各通道 GOP 位置不同 → 同一时间点开始拉的两段录像,第一帧能差好几秒;
不处理就会两格画面错开。
**用 `NET_DVR_GetPlayBackOsdTime` 读第一帧的真实内容时间**(8000 协议,实测可用):
- 下载:`PullPlaybackToFile` 在第一包数据到达时读一次,`偏移 = 首帧 OSD − 请求时间`,
合并时提前的路用 `trim` 切头、晚开始的路用 `setpts` 后移
(日志 `[playback] 通道N 首帧 OSD=hh:mm:ss,比请求时间早/晚 X 秒`);
- 合并:**总时长取最长的那一段**(合并前读各段的真实时长),短的那格在 `overlay` 里定格最后一帧,
按请求窗口截会把从关键帧提前起推的那段尾巴切掉(日志 `[playback] 合并时长按最长的一段算:…`);
- 预览:RTSP 侧拿不到内容时间,所以开窗前先用 `ProbePlaybackOsdStart` 每路探一次,
按 OSD 差值推迟出图(日志 `[playback] 预览按 OSD 起点对齐:…`)。
- 拿不到 OSD(固件不支持/无数据)才退回「时长反推」(`提前量 = 文件时长 − 请求窗口`);
偏差超过 60 秒视为通道时钟异常,不做对齐,绝不把画面推歪。
⚠️ 曾经只用「时长反推」,实测同一个窗口拉两次会得到 36.1s / 42.1s 两种结果
(关键帧起止 + 流在哪断都不固定),头和尾分不开 → 会随机差 2~4 秒,已弃用为首选。
3. **摄像头自身的时钟**:画面里烧的 OSD 时间是**摄像头自己**打的,和录像机的录像时间轴无关。
两个摄像头时钟不一致时,即便回放已经对齐,两格 OSD 也会差几小时甚至几年 ——
这不是回放错位,要在录像机里开「摄像机校时(IPC 校时)」或给 IPC 配 NTP 才能一致。
查询日志只记结论(`[pack-query] 运单号 → found=… records=… streams=…`),不再写完整 JSON;
要排查原始数据看后端日志或页面。
要换成别的数据源,只改 `OrderQueryService.QueryAsync` 一个方法就行(返回 `QueryResult`,
`Data` 是扁平字典即可,前端 `/local` 页也吃这份数据)。
### 扫码 → 查询(不跳页)
- 手动输入 / 回车 / 点查询 / 协议唤起:`RunQueryAsync()`,**切到「打包查询」页**展示;
- 通道扫码:`OnChannelBarcode` 后台算一次结果,**绝不切页签**
(用户还在「扫码通道 / 扫码记录」页时,只在「打包查询」页签上加 `●`,
切过去时才把结果显示出来);
- 扫码数据本身仍由 `ScanService` 落记录 + 上报,跟查询是两条独立的路。
## 常见问题
| 现象 | 处理 |
| --- | --- |
| 启动报「句柄无效」/ `句柄无效 (6)` | 老版本用 `HttpListener`(HTTP.sys)才会这样:系统的 HTTP 服务被禁用或卡在 STOP_PENDING。本次修复起本机服务改成自建 TcpListener,不再依赖 HTTP.sys;老版本临时处理可 `net start http` 或重启电脑 |
| 启动报「没有绑定端口的权限」/ `Access is denied (5)` | 端口被安全软件拦了;换端口(`YUNCANG_LOCAL_PORT`)或加白名单 |
| 报端口被占用(`AddressAlreadyInUse`) | 已经开了一个实例(单实例会把参数转过去);检查任务管理器里的残留进程 |
| 双击图标没反应 / 主界面打不开,托盘图标还在 | 1.0.134 起:再次启动会把已运行实例的主界面叫到前面(托盘双击也行)。更老的版本点了没反应是正常的(第二个实例直接退出),从托盘打开即可 |
| 升级后主界面仍然出不来 | 看日志最后几行:停在 `准备显示更新窗口…` 之后就是老版本的「更新窗盖在登录窗上」死锁,装新版本即可;有 `[app] 主窗口没建:server=… session=… api=…` 说明登录态没建立 |
| 网页提示服务不可用,但软件在跑 | 先用浏览器直接打开 `http://localhost:17300/api/query/`(会回 400 但带登录状态):打不开→防火墙/端口;打得开→多半是 CORS 头没回。预览类问题则看 `ws://127.0.0.1:17301/` 能不能打开(直接浏览器访问应该返回一小段 JSON) |
| 点网页「启动本机软件」没反应 | 协议没注册(界面看「启动协议」状态);或浏览器拦了自动跳转(必须用户点击) |
| 唤起时弹「You must install .NET Desktop Runtime」 | 唤起的是 `bin\Debug` 这类 framework-dependent 的 exe(拿不到 `DOTNET_ROOT`)。用自包含发布产物,并让它启动一次以校正注册表 |
| 改了协议名 | 注册表重注册 + 前端 `VITE_APP_PROTOCOL` 同步 + 插件目标地址同步 |
## 主体切换 / 微信扫码登录 / 设备服务(2026-10-18)
### 登录窗
- **微信扫码登录**(2026-10-28 起走微信登录网关):点「微信扫码登录」→
`POST /api/web/auth/wechat-gateway/qrcode` 申请二维码 → 显示二维码
(`GET /api/wechat-gateway/qrcode.gif?state=`,WPF 不能渲染 SVG 所以后端额外给了 GIF 版)→ 长轮询
`GET /api/web/auth/wechat-gateway/login?state=&wait=25`,手机微信确认后直接拿令牌进主界面;
二维码过期(`expired`)会自动重新申请一张,绑定状态不对(`failed`)直接把服务端给的原因显示在二维码下面。
⚠️ 只有**已经绑定过微信**的账号才能扫码登录(绑定入口在网页版「个人中心 → 微信绑定」)。
- 账号密码登录与微信登录**都会带回主体列表**(`subjects`),主界面右上角显示当前主体。
### 主界面
- 左上状态行:`主体:xxx · 设备服务:未开启 / 已开启(SN)`。
- 菜单 **服务**:
- `当前主体:xxx` → 弹窗切换主体(`GET /api/web/subjects`;切换后设备服务若开着会提示在新主体下重新开启)
- `开启设备服务`(**只有主体管理员可见**;默认关闭)
- `关闭设备服务`(开启后才出现)
- `服务状态:运行中/未启动`
- **开启流程**:先 `GET /api/web/devices/active` 看该主体是否已有设备 → 有就弹确认
「一个主体只允许一台设备在线,开启后它会被踢下线」→ `POST /api/web/devices/activate`
(服务端踢人 + 发长期设备 JWT)→ 上报本机通道 `DESKTOP / 本机中控`。
- **上报**:开启后,本机每处理一个运单号(协议唤起 / 测试查询)都会 `POST /api/scan/records`
(通道 `DESKTOP`,服务端按 设备+通道+条码+秒 去重)。关闭/退出登录时会 `POST /api/web/devices/:id/logout` 让令牌立即失效。
- 状态都落在 `%LOCALAPPDATA%\YuncangTrace\settings.json`(`SubjectId/SubjectName/SubjectRole`、
`DeviceServiceEnabled/DeviceId/DeviceSn/DeviceToken`),其中 `DeviceServiceEnabled` **默认 false**。
### 相关文件
`Services/ApiClient.cs`(登录/微信/主体/设备/上报)、`Services/DeviceService.cs`(开启/关闭/上报)、
`Services/AppSettings.cs`(新增主体与设备字段)、`LoginWindow.*`(微信面板)、`MainWindow.*`(服务菜单 + 状态行)、
`SubjectPickerWindow.*`(切换主体弹窗)。
### 后台扫码服务(Windows 服务,2026-10-19)
「开启设备服务」不再依赖桌面端常驻:会安装系统服务 **`YuncangTraceAgent`**(LocalSystem、自动启动),
**退出软件 / 注销用户 / 重启电脑后继续收码上报**。
| 项 | 位置 / 说明 |
|---|---|
| 服务程序 | `%ProgramData%\YuncangTrace\agent\YuncangTraceAgent.exe`(从安装目录复制;**MSI 升级不会撞「文件被占用」**) |
| 服务配置 | `%ProgramData%\YuncangTrace\agent.json`:服务器地址 + **长期设备令牌**(默认 365 天)+ NTP 设置 |
| 服务令牌 | `%ProgramData%\YuncangTrace\agent-token.json`:访问令牌 + **刷新令牌**(服务自动续期后更新;单独一份避免和 agent.json 互相覆盖) |
| 共享数据 | `channels.json` / `scan-records.json` 在 `%ProgramData%\YuncangTrace\`(普通模式仍在 `%LOCALAPPDATA%`) |
| 运行状态 | `agent-status.json`:是否运行 / 通道在线 / 待上传条数 / NTP 结果,桌面端只读展示 |
| 命令 | `agent-command.json`:立即上传 / 清空记录 / 重新加载通道 / 立即校时 / 立即续期令牌(服务每秒轮询) |
| 发现列表 | `agent-discovered.json`(桌面端「扫码通道」页展示用) |
| NTP | 服务以 LocalSystem 定时校时,**不再需要 UAC**;NTP 窗口的「立即校时」只写命令文件 |
| 安装 / 卸载 | 开启 / 关闭设备服务时用 `runas` 提权(**各弹一次 UAC**),之后日常使用无 UAC |
| 升级 | 新版本启动后检测服务副本版本,提示更新(一次 UAC) |
| 日志 | `%ProgramData%\YuncangTrace\agent\logs\log_*.txt` |
| 日志策略 | 按天一个文件,**自动保留 14 天**;状态文件改为「内容变化才写 + 30 秒保活」(不再每 2 秒重写);面单压着扫码器时同一个码每 5 分钟才记一行 |
| 手动排障 | `sc query YuncangTraceAgent` / `sc start|stop YuncangTraceAgent` |
| 调试 | `YuncangTrace.LocalService.exe --agent-run`(不经 SCM,直接跑后台循环) |
> **退出登录不会关闭设备服务**:服务模式下只清登录态,设备令牌和 `agent.json` 保留,扫码继续上报。
> 要停止必须走「服务 → 关闭设备服务」。
>
> **换账号登录(不属于后台服务主体)**:后台服务是独立进程,继续按原主体扫码/上报;
> 桌面端会把**界面主体**自动切到当前账号可用的主体(查询用),并在状态行标注「服务主体 id=xxx」。
> 此时:
> - **不弹窗**,正常进主界面;页签上方常驻一条提示:「当前账号不属于后台扫码服务绑定的主体(id=xxx)…」;
> - **管理员**:扫码通道 / 扫码记录页照常显示,按提示先「服务 → 关闭设备服务」,再「开启设备服务」即可在当前主体重新绑定;
> - **普通成员**:扫码通道 / 扫码记录页**直接隐藏**(本地文件是那台服务的数据,与当前账号的主体无关),只保留打包查询;
> - 查询接口用的是当前账号的主体;「关闭设备服务」仍可执行:先停/卸载本地服务,再尝试通知服务器注销(不是该主体成员时服务端注销会失败,日志有记录);
> - 账号下**一个主体都没有**:弹窗提醒后**直接退回登录页**(后台服务保持运行,换有主体的账号登录即可)。
>
> 只有当前界面主体就是服务主体时,切换主体才必须先关闭设备服务(避免扫码写到旧主体)。
>
> **令牌自动续期**:激活时后端同时下发访问令牌(365 天)和刷新令牌(默认 730 天)。
> 后台服务在访问令牌剩余不足 7 天时自动调 `POST /api/device/refresh` 换新(两者都轮换),
> 结果写到 `agent-token.json`;只要服务在跑就不需要人工重新激活。
> 关闭设备服务 / 被同主体其它设备踢下线时,刷新令牌一并作废。
> 需要验证续期流程时:菜单 **服务 → 立即续期设备令牌**(写 `RefreshTokenAt` 命令),服务会立即换一次并记日志。
>
> **设备心跳**:后台服务每 **60 秒**调 `POST /api/scanner/heartbeat` 刷新后端 `last_seen_at`,
> 所以即使长时间没扫码,网页设备列表也能看出服务在线;心跳 401 会触发令牌续期。
>
> 服务模式下桌面端只做界面/配置:不启动本进程的 `ScanService`(避免和后台服务抢设备连接),
> 通道在线状态、扫码记录都从服务写的文件里读。
## 扫码服务(从 AndroidScanCenter 移植,2026-10-18)
扫码中控不再由 Android 盒子承担,**TCP/UDP 通讯全部搬到桌面端**:
| 能力 | 实现 | 说明 |
|---|---|---|
| 设备发现 | `Services/Scan/DiscoveryMonitor.cs` | **常驻 UDP**:一个 socket 一直开着,每 3s 向 `255.255.255.255` + 各网段定向广播发一次探测,期间**持续收**、按 MAC 合并,12s 没见到就摘掉。⚠️ 设备**不会主动广播**(实测绑 48899 静听 40s 只能收到自己的探测包),回复只发回**发送方源端口**,所以不能在 48899 上被动监听 |
| 设备配置 / 重启 | 同上(JCMD) | `CID 10003` 读 SYS、`10005` 写 SYS(增量)、`20003` 重启;**不要发 `DO_RELOAD`**(会抹掉改动) |
| 写设备名 / 确保 TCP 服务 | `Services/Scan/DeviceConfig.cs` | 条目 **`packcenter` / TCP-SERVER / 8087**(**不用 Android 的 `scancenter:8086`**),缺失/不对则整条写入 → `10017` **落 flash** → 回读校验;**设备最多放 3 条 SOCK**,满了就复用一条非保留条目(`scancenter`、`netp` 是别人的,绝不动),实际用的名字记在通道的 `SockName` 上;写前备份全部条目原始字段,写完发现别人的条目丢了会**原样写回** |
| 自愈 | `ScanService.HealAsync` | 通道连续 3 次连不上 → 回查设备 SOCK 条目,被删/被改就重建(每台设备 60s 最多一次) |
| 收条码 | `Services/Scan/ChannelConnection.cs` | 每条通道一条 **TCP 出向连接**到设备 `:8087`(设备当服务端),按 CR/LF 切行,断线 5s 重连;设备每 ~0.7s 推的 6 字节二进制帧(`04 D0 00 00 FF 2C`)会被忽略,不污染条码行 || 扫码枪设置 | `Services/Scan/ScannerCommands.cs` | 连上后一次写 28 字节:**连续扫描 + 识别间隔 0s + 静音状态**(9+9+10,静音那两条是 10 字节,校验位照抄)。写失败不影响收码。扫码枪自己重启会丢设置,靠“每次重连都下发”自动兜住 |
| 静音 | `ScanService.SetMuted` | **只存本地 + 让连接重走一遍**(关 socket → 立即重连 → 整条设置重下发)。不在现有 socket 上补写指令:Android 侧实测“字节发出去了但枪没执行”时无法判断 |
| 改名 | `ScanService.RenameChannelAsync`(通道页「重命名」) | 已添加的通道**直接改名**,不用删了再添加(删除会让服务器软删该通道并解绑工作台、通道号还可能变)。名字落本机 `channels.json` + 普通推送同步服务器(`POST /api/scan/channels` 按 `channelId` 更新 `channelName`),可选同时写设备 `SYS.HostName`(写失败不回滚本机改名)。服务模式下本机只落文件,后台服务发现文件变了会自己重载 |
| 串口指令调试 | `Views/ScannerCommandWindow`(通道页「串口指令…」) | 发任意 **HEX 字节**透传给扫码枪,预填四条常用指令(静音/恢复蜂鸣/连续扫描/间隔 0s)。换批枪后指令集不同时现场自己试,不用发版 |
| 假死看门狗 | `ScanService.WatchdogLoopAsync` | 每 30s:连接看着在线但 **60s 没字节** → 回查设备侧 `SOCK.ClientIP`(CID 10001 才有)→ 本机 IP 不在里面就强制重连(设备断电重启时 TCP 不发 FIN,`ReadAsync` 会永久挂住) |
| IP 变化 | `ScanService.ApplyDiscoveredIps` | 每次发现结果回来就刷新各通道 `LastIp`,变了立即用新地址重连(DHCP 续租后不会卡在旧 IP) || 通道配置 | `Services/Scan/ChannelStore.cs` | `%LOCALAPPDATA%\YuncangTrace\channels.json`(服务模式:`%ProgramData%\YuncangTrace\channels.json`),通道号取最小空号、删除后不复用;**不再有团购/散单字段**(团散在「工作台」区分) |
| 编排 | `Services/Scan/ScanService.cs` | 启动→连接**全部**通道(没有启用/停用开关,加了就连);**通道一旦变动(增/删/改名)自动同步到服务器**:`POST /api/scan/channels`(增删带 `replace: true`,全量对账;改名只是更新名称)→ `GET /api/scan/channels` 回查确认 → 缺了就退避重试(1s→30s)直到服务器真的有;**删除通道会让服务器软删该通道并解绑工作台**(`removed` / `unbound`),删到 0 个也会推空列表 |
| 扫码记录 | `Services/Scan/ScanRecordStore.cs` | `%LOCALAPPDATA%\YuncangTrace\scan-records.json`(服务模式:`%ProgramData%\YuncangTrace\scan-records.json`),每个通道最多 5000 条;**先落本地、服务器确认后才标「已上传」**,没确认的一直重试,断网不丢;连续扫描只刷新「最近一次扫到的时间」;**扫到后 5 秒没再扫到同一个码才上报**,上报的就是最后一次扫描时间;同一运单 24 小时内再次扫到会**重新激活同一条本地记录**(不新增行),下一轮上报覆盖服务器记录 |
| 上报队列 | `Services/DeviceService.cs` | 条码静默满 5 秒后后台攒批(50 条/批)推 `POST /api/scan/records`(有积压时上报循环每秒醒一次,空闲 30 秒),失败不标记、指数退避重发(服务端按 设备+通道+条码+秒 精确去重;**同一运单 24 小时内只保留一条,后上报的新时间会覆盖旧记录的时间与工作台快照**)。**主体过期/停用或令牌失效 → 暂停推送**(保留本地积压、不做无意义重试),暂停期间每 60 秒只发一次心跳;心跳返回 `subject.expired=false`(续费)后自动恢复并补传 |
### 添加通道(设备名 + 通道号)
`扫描设备 → 选中 → 添加为通道` 会弹窗让用户定**通道号**与**设备名**(与 AndroidScanCenter 一致):
- **通道号**:`1..50` 的下拉框,已占用的号照样列出来并标注「已被 xx 占用」,选中就提示、不关框;
默认勾在最小空号上。没有「通道号」设备字段 —— 它是**本地概念**(现场认工位),上报时就是 `channelId`。
- **设备名**:默认填设备自报的 `HostName`,会**写进设备**(`SYS.HostName`,UTF-8 支持中文)并落 flash;
留空则用设备自报名。写失败**不阻断**添加(只影响设备面板/其他上位机看到的叫法)。
添加顺序是「**先配设备、后落本地**」(回滚本地行不通:设备名可能已经写上去了):
1. 确保设备有给中控用的 TCP 服务(`SOCK` 段 `packcenter / TCP-SERVER / 8087`):
已就绪则不写;缺失/不对则整条写入 → **回读确认**(设备 `RC=0` 只代表报文收到了,端口冲突它不报错);
这一步失败就**整个添加失败**,本地什么都不写(否则会得到一条永远连不上的死通道)。
2. 设备名与自报的不同 → `10005` 写 `SYS.HostName` → `10017` 落 flash(不落盘一次重载就丢)。
3. 才把通道写进本地配置、开始连 TCP,并同步通道列表到服务器。
真机验证(`192.168.9.204`,E10C 1.41.1):`写设备配置 SYS:0` → `保存到 flash:0` →
广播里的 `HostName` 立即变成新名字 → `通道 1(工位 9)已连接 192.168.9.204:8087`。
### 重命名通道
`扫码通道 → 选中一行 → 重命名`:只改**名字**,通道号不动(通道号是现场认工位的号)。
- 名字先落本机 `channels.json`,再用**普通推送**同步服务器(`channelId` 不变,服务器按 id 更新
`channel_name`);不走 `replace` 全量对账,所以不会误删别的通道、也不会解绑工作台;
- 「同时把名称写入设备(`SYS.HostName`)」默认勾选(与添加通道一致),设备 IP 未知时该选项不可用;
写失败**只提示**,本机改名照样生效(设备名只影响设备面板/其他上位机看到的叫法,不影响收码);
- 名字没变就只按需补写设备名,不白刷一次服务器;
- 服务模式:桌面端只写通道文件,后台服务发现文件时间变了会重新加载并重连
(日志 `[agent] channels.json 已变更,重新加载通道`)。
### 面单摄像头(独立页签:配置 + 拉流识别)
「面单摄像头」是**单独的页签**(与「扫码通道/扫码记录」一起显示),每路一行:
`工作台 | 摄像头 | 上报通道 | 状态(识别中/启动中/异常/已停止) | 最近识别到的条码 | 首次识别时间 | 最近命中 | 码流 | 解码耗时 | 次数 | 备注`。
- **首次识别时间**:这条记录真正拿去上报/落库的时间,面单一直摆在拍摄区**不会刷新**(重复命中不改时间);
- **最近命中**:摄像头最近一次解码成功的时刻,每秒都在跳,只用来判断「摄像头有没有在看/对着条码」;
- **码流**:当前实际用的是主码流还是子码流、分辨率多少;
- **解码耗时**:最近一帧「OpenCV 检测 + 透视矫正 + ZXing 解码」花了多少毫秒,用来判断机器吃不吃得消;
- 行是按 `工作台|摄像头|通道` 原地更新的(不整体重画),只有值真变了才会重绘。
顶部状态行显示 `已拉取 N 路 · 时间`,底部的黄字是服务端提示(例如「摄像头找不到录像机」「录像机没有保存密码」)。
数据来源:服务模式下由**后台服务**拉配置 + 识别,界面读 `agent-status.json` 的 `LabelScan`
(后台服务每 **400ms** 写一轮、界面每 **300ms** 轮询一次,识别到就是几百毫秒内能看到);
普通模式下直接读本进程 `ScanService.LabelScan`。
#### 配置拉取(`LabelScanMonitor`)
- 服务启动拉一次 + **每 1 分钟**兜底(推送可能丢:设备正好离线、edge 任务 TTL 过期、推送失败);
以前是 5 分钟,现场在网页上改完面单摄像头要等好几分钟才生效,看起来就是「取消的那路还在跑、新增的不启动」;
- 收到 `labelScan.refresh`(**服务端**在 Web 端改了面单摄像头/工作台/上报通道后主动推的 edge 任务)立即重拉;
- 记住 `revision`:内容变了才写一条「配置变更」日志;
- 拉完就**对账**:新增的启动识别、配置变了的重建、消失的停掉;没变的不打断(轮询很密,不能断流);
- 对账单路失败(构造/启动异常)只记日志并清掉半成品,**不影响其它路**,下一轮会重试。
#### 识别(`LabelScanWorker`)
```
ffmpeg(RTSP, tcp) → 灰度 rawvideo 帧 → 读帧线程只留最新一帧(按 DecodeFps 限速)
→ OpenCV BarcodeDetector 整图检测(cv::barcode,输出条码四角点,带旋转/透视)
→ 无候选 = 画面里没面单,直接丢掉
→ 有候选:逐个透视矫正成轴对齐小图 → ZXing 解 CODE_128 → CleanBarcode 校验
→ 命中入队(扫描线程不等) → 上报线程:写记录 + 立即上报 + 通知安卓播报
```
- **为什么用 OpenCV 检测而不是自己找 ROI**:现场面单是**竖放或斜着**摆的(实测四角点
`(433,602)(450,514)(1371,685)(1354,774)`,倾斜约 5°)。1D 码要求扫描线完整穿过整条,
按「行梯度能量」找横带再轴对齐裁剪,会把条码截断 → **必然解不出**(实测 0 命中)。
OpenCV 给的是四角点,透视矫正后条码完整,实测 1920×1080 整图 **检测约 10~15ms + 解码约 1ms**,
3/3 帧命中、无面单画面 3/3 帧 0 候选(无假阳性)。
- **退避(隔帧检测)**:① 同一个码连续命中 3 次(面单没动)② 连续 3 帧没结果(画面里没面单)→ 之后隔帧检测;
一旦**画面变化**(面单拿走/换新/有人手伸进来,靠 32×18 缩略图平均灰度差 > 6 判定)立刻恢复全帧率。
实测面单摆着不动时 CPU 直接减半,新面单放上去不额外延迟。
- **选流**:先试子码流,**宽度够 1080 才用**(拉流解码开销只有主码流的 1/7,更省 CPU);
太小就退回主码流并在日志里说明。实测这台录像机子码流 800×448,条码只有 1.8px/模块,
同样设置**读不出来**;把子码流调到 1280×720 即可自动启用;
- **延迟**:`ffmpeg -threads 2`。HEVC 默认帧级多线程会把输出往后压好几帧 ——
用画面里的时间水印实测「OSD 时间 → 本机收到帧」:默认线程 **2.6s**、`-threads 1/2` **0.5s**、
加 `-fflags nobuffer -flags low_delay` 反而更慢(2.9s)。输入 20fps、我们只取 8fps,2 线程完全够;
- **不积压**:读帧线程始终把管道读空、只保留最新一帧,旧帧直接丢(`FrameLag` 恒为 0~个位数);
上报走独立线程 + 8 条缓冲队列,写记录/上报/通知安卓再慢也不会拖住识别;
- **RTSP 通道序号**:库里存的是设备通道号(数字通道从 33 起),RTSP 要 1 起序号,
所以按 `channelNo-32 → channelNo` 依次探测,成功后**记住**(日志 `码流就绪:主码流 2304x1296(序号 3201)`);
- 条码过滤:4~64 位、只含常见条码字符、**至少 6 位数字**(压掉摄像头误识别噪声);
- 同一张面单连续命中节流到 500ms 一次:足够维持「在场」状态,又不会刷上报;
- 断流自动重连(3 秒),连续失败按 3/10 次节流打日志;不影响扫码枪链路。
排障字段(`agent-status.json` 的 `LabelScan.Items[]`):
| 字段 | 含义 |
|---|---|
| `LastPath` | `OpenCV解码` / `无候选` / `候选未解出` / `稳态退避` / `失败退避` |
| `LastCvMs` | OpenCV 整图检测耗时 |
| `LastDecodeMs` | 透视矫正 + ZXing 解码耗时 |
| `RoiText` | 矫正后的条码尺寸(如 `条码 937x90`),或 `无候选` |
| `RoiRatio` | 矫正+解码耗时(毫秒) |
| `FrameLag` / `FrameDropped` | 取帧时的积压帧数 / 累计丢弃旧帧数(正常应接近 0) |
| `FramesRead` / `FrameThrottled` / `FramesDecoded` | 管道读到 / 限速丢弃 / 实际处理 的帧数 |
| `LastWaitMs` / `LastLoopMs` | 等新帧耗时 / 两次取帧的完整周期(看瓶颈在「帧不够」还是「处理慢」) |
| `RoiFailStreak` / `SteadyHits` | 连续无结果次数 / 连续命中次数(≥3 触发隔帧退避) |
日志样例:
```
[label-scan] 已拉取面单识别配置(启动):1 路,revision=sha1:df244c17781de5ba
[label-scan] 散单1号 → 测试散单面单(241 通道 64,主码流)→ 上报通道 2「测试安卓」
[label-scan] 散单1号 → 测试散单面单… 子码流只有 800x448(条码像素不够,读不出来),改用主码流
[label-scan] 散单1号 → 测试散单面单… 码流就绪:主码流 2304x1296(序号 3201)
[label-scan] 识别到条码:SF1164748936737(通道 2,首次 10-24 16:19:26,倾角 -12°,解码 38ms,新记录=True,播报=True)
```
页签里的「码流」「解码耗时」两列就是上面这些信息,现场调机位时能直接看出问题在哪一层。
⚠️ 配置快照里含录像机密码:只放内存,不落盘、不写日志、界面文案也不显示。
### 工作台 OSD 字幕(摄像头名 + 运单号)
「设备服务」开启后(后台服务模式 / 界面模式都会跑),会按**工作台**维护录像机的 OSD 通道名:
| 时机 | 写什么 |
| --- | --- |
| 扫到运单号(扫码枪 / 面单识别,连续重复命中都算「在扫」) | 该工作台**所有摄像头**:`摄像头名 + 空格 + 运单号`(如 `2号线面单 SF1164748936737`) |
| **运单号没变** | **不重写**(连续扫描只续在场计时) |
| 连续 **60 秒**没有任何命中 | 全部还原成**摄像头自己的名字**(摄像头没名字才退回工作台名) |
- 配置来源:`GET /api/scanner/workstations`(设备令牌)——只下发**绑了本机扫码通道**的工作台,
每项带本机通道、全部绑定摄像头(名称 / 录像机通道号 / 录像机凭据);
启动拉一次 + 每 1 分钟兜底,服务端推 `labelScan.refresh`(改工作台/摄像头绑定时会推)立即重拉;
- 写的是**录像机通道名**(`NET_DVR_SET_PICCFG_V30` 读-改-写整包 + 回读校验),
所以实时流、回放、下载的录像里都带这段字;摄像头本身不改;
- 字段只有 **31 字节(GBK)**:超长时先压摄像头名、保住完整运单号(见 `OsdText`);
- 每次写设备配置要 0.3~3 秒,写入在**后台批量队列**里执行(不阻塞扫码/识别):
一个工作台绑了多路摄像头时是**同时下发**的(一批最多 4 路;不同通道并发安全 ——
录像机只是把配置分别转给各摄像头,实测两路并发读改写 20 次全部成功、其余字段零差异),
但**同一通道**必须串行(「读整包 → 改 → 写回」会互相覆盖,批内已按通道去重);
写完一批还有待写的会立刻接着来,不会空等;失败按 5s→10s→20s→40s→60s 退避;
配置里被移除的摄像机会先还原一次摄像头名再忘掉;
- 状态在 `agent-status.json` 的 `Osd`(每路摄像头的当前文本 / 最近写入时间 / 错误,**不含密码**)。
> ⚠️ 改通道名 = 改录像机上的通道名:NVR 本机界面、其他客户端、以及我们「拉取通道」读到的名字都会变。
> 服务停止时**不主动清 OSD**(下次启动会按配置还原成摄像头名);要动态的长文本字幕只能本地 `ffmpeg drawtext`。
### 摄像头识别结果 → 记录 + 安卓播报通知
在「工作台 → 绑定管理」里把某路摄像头设为**面单摄像头**(每个工作台只保留一路,散单/团购都能设)后,识别到的条码
统一走 `ScanService.ReportCameraScanAsync(channelId, channelName, code, wsType)`。
**与扫码枪的差别(现场场景:面单放进拍摄区 → 开始打包 → 打包完才取走)**:
| | 扫码枪(团购) | 面单摄像头(散单) |
|---|---|---|
| 时间 | **最后一次**扫描(包裹离开扫码器) | **第一次**识别(面单进入拍摄区);面单没离开画面就**永不前移** |
| 上报时机 | 静默 5 秒后 | **写入即上报**(`ScanRecordItem.Immediate`) |
| 视野内重复命中 | 刷新时间 | **什么都不做**(不改时间、不重复上报、不重复播报) |
| 中途被手挡/移位/反光(面单还在画面里) | 刷新成新时间 | **仍算同一轮,时间不前移** |
| 面单真的被拿走(画面里连续 45 秒没有任何条码)后再放回 | 刷新成新时间 | 当作**新一轮打包**,用**这次**的时间(装错了重新打包、20 分钟后重新称重再包一遍都属于这种) |
**工作台类型决定规则**(后端下发的 `wsType`,见 `LabelScanMonitor.ModeOf`):
| | 散单(wsType=1) | 团购(wsType=2) |
|---|---|---|
| 面单摄像头识别 | 取**第一次** + 立即上报 | 和扫码枪一样:静默 5 秒、取**最后一次** |
| 扫码枪 | 同样取**第一次** + 立即上报(`DeviceService.ReportFirstSeen`,5 秒内重复算一次) | 静默 5 秒、取**最后一次**(不变) |
**工作台没接扫码枪也能用**(摄像头完全替代扫码枪):服务端会给这种工作台一条**虚拟通道**
`CAM-<工作台id>`(名字 `面单摄像头·<摄像头名>`),下发的 `items[].virtualChannel = true`。
设备端照常上报即可,差别只有:
- 通道名从配置里取(`LabelScanMonitor.ChannelNameOf`),因为 `CAM-` 不在本机 `channels.json` 里;
- `channels[]` 里也会带这条虚拟通道,所以记录规则照旧按 `wsType` 走;
- 虚拟通道没有对应的扫码工位,`NotifyScanSuccessAsync` 找不到安卓通道 → **不播报**(正常现象);
- 这类工作台在 Web 端「绑定管理」里看不到「没绑扫码通道」的警告,虚拟通道带「虚拟」标记、不给解绑。
- **「离开」只有一个判据**:画面里**连续 45 秒没有任何条码**(`LabelScanWorker.RepackAbsence`)。
识别线程和上报层共用这个值(`ScanService.CameraPresenceGap` = 它),避免出现
「算重新进去了、但时间没更新」的漏洞。在场状态是**按「通道|条码」**记的,
所以换一张新面单永远是新建记录、不受这个值影响。
- **为什么用「画面里有没有条码」而不是「有没有解出码」**:接入 OpenCV 后 `无候选` 是可信的
(面单在视野里就一定有候选);而「解不出」还会发生在面单明明在场的时候(反光、遮住一角)。
- **时间绝不因为识别空档前移**(这是修过的现场问题):面单一直摆着、中途被手挡一会儿,
以前会被当成「离开又回来」,加上这中间通道上又扫过别的包裹,打包时间直接被改成
「开始打包 30 秒之后」,录像定位整体偏移。**「中间扫过别的包裹」不是重新打包的信号**
—— 两张面单轮流进入视野就会命中,但那两张都没离开过。
- **真正的新一轮打包会被识别**:面单被拿走(画面里连续 45 秒没有条码)后再放回,
记录时间更新成这一次(`ScanService.ResolveCameraScanTime` 的 `afterAbsence`)。
例如 20 分钟后发现称重不对、开箱重装再包一遍 —— 只要换货期间面单离开了画面就成立。
- **时间只认记录**:上报/界面显示的时间都取本地记录里那条的 `ScannedAt`,
在场判定只决定「要不要重新上报一次 + 时间要不要更新」,服务重启、丢帧都不会把时间推后;
- **记录永远写**:与通道类型、安卓是否在线、设备服务是否开启无关。断网/离线只是留在本地队列等重试;
- **通知要回执**:只对 `AndroidStation` 通道发 `0x1E{"cmd":"scan","id":…,"code":…}\n`,
等设备回 `0x1E{"cmd":"ack","id":…}\n`(1.2 秒超时,最多重发 2 次)。
`CameraScanResult.Notified=false` 只代表「没确认到播报」,**不代表没记上**;
网口扫码枪没有语音能力,不发(避免被透传到枪的串口)。
**设备端要求 AndroidStation ≥ 1.0.3**:1.0.1 还不认识 0x1E 控制帧(表现为「安卓端没回执」),
1.0.2 起会把 ack 里的 id 过滤掉非字母数字字符导致桌面端永远比对不上,1.0.3 已改成原样回显。
### 界面
- 主窗口改成页签:**打包查询** / **扫码通道**(后者仅在「设备服务」开启后出现)。
查到条码(协议唤起或通道扫码)时**默认切回「打包查询」页签**并自动查询。
- 扫码通道页:**每个区块的状态与按钮都在各自标题行上**。
- 「扫码通道」标题行:状态(`扫码服务运行中 · 通道 N 个(在线 M)` + 通道同步状态 + 待上传条数)+ `重连全部` / `静音`(选中行切换,已静音时叫「恢复蜂鸣」)/ `读取设备配置` / `重命名` / `删除通道`(后三个都要先选中一行);
通道列表有「类型」「状态」「静音」三列(类型 = `安卓扫描通道` / `扫码枪`,来自 UDP 发现应答的设备型号,
`AndroidStation` 才标成安卓扫描通道。**只有安卓扫描通道需要「扫码成功」通知**:摄像头识别到条码时
通知它播报语音;扫码枪通道没有语音能力,不发。**记录一直在写,与通道类型/在线状态无关**);
**没有「同步通道」按钮** —— 通道增删/启停都会自动上传并回查确认;
- 「发现到的设备」标题行:`开始扫描`(**开关**,打开后常驻发现:每 3s 探测、socket 一直收,直到手工停止)+ `添加为通道` + 状态(`正在扫描… 未添加 N 台` / `发现 N 台未添加的设备(另有 M 台已添加)`);
发现列表和「添加通道」弹窗都会标注 **安卓扫描通道**(型号 `AndroidStation`),添加时把型号一起落进 `channels.json`。
- **已经添加为通道的设备不会再出现在发现列表里**:显示集合与「发现到的全集」分开存(`_allDevices` / `_devices`),
按通道 MAC 过滤;删掉通道后那台设备会自己回到列表里,不用重新扫。每轮结果按 MAC 合并,不整表覆盖(UDP 丢包时设备不会闪没)。
- 扫码记录页(对应 AndroidScanCenter 的「通道回放」,`Views/ScanRecordsView`):
通道筛选 / `立即上传` / `清空`,列表显示 时间 / 通道 / 号 / 条码 / **已上传或待上传** / 确认时间,
状态行是 `全部通道:显示 N 条 · 本地共 M 条 · 待上传 K 条`。
数据源是本地记录库,所以**服务器挂了也能看到刚才扫了什么、还有多少没传出去**。
- 菜单 **工具 → 打开配置页(后台)**:用系统浏览器打开 `{服务器}/?token=<用户JWT>`,
前端启动时读 `?token=` 存进 localStorage 并把参数从地址栏去掉(免登录,见 `frontend/src/router/index.ts`)。
### 联调验证(本机)
用 `node` 起一个假设备(`127.0.0.1:8087` 推两行条码)→ 开启设备服务 → 日志:
```
[scan] 扫码服务已启动,通道 1 个
[scan] 通道已同步到服务器并确认:1 个
[scan] 通道 1(模拟扫码枪)已连接 127.0.0.1:8087
[scan] 通道 1 扫码:TESTCH-BARCODE-9001(5 秒未再扫到后上报)
(5 秒后)
[scan] 已上报扫码 1 条
```
数据库 `scan_records` 里 `channel_id=1`、`device_sn=MINGREN`;工作台可绑定通道 `1/模拟扫码枪`。