- 新增 NET_DVR_GET_PICCFG_V30(1002):结构体头部 DWORD dwSize + char sChanName[32] 即通道名,GBK 编码; 实测 DS-7932N-R4 32 路约 250ms,中文(团购复核区1 / 单号:xxx)正常 - 只查 enabled 通道(空槽位回 err=4 直接跳过),失败只写日志,不影响其他字段 - ISAPI 降级为兜底:PICCFG 一个名字都拿不到时才读 ContentMgmt/InputProxy/channels (先 500ms TCP 探测,依次试 80/443/8443,按 IP 匹配、再按 id 推) - 新增 HikSdk.DecodeGbk:注册 CodePagesEncodingProvider 后按 GBK(936) 解码,注册失败退回 ASCII - 桌面端 README 更新通道名来源说明 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
54 KiB
云仓视频溯源软件(本机服务 / 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 # HttpListener(17300):查询 / 唤起登录 / 下载录像
├── 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,有新版本会把更新窗盖在登录页上(否则老版本用户永远卡在登录页收不到更新) |
| 已有令牌 | 登录窗一闪而过:/api/web/me 通过就直接进主窗口;失效则清掉令牌留在登录页 |
| 关窗口(X) | 隐藏到托盘,本机服务继续跑(第一次会冒一个气泡提示) |
| 再次双击 exe / 点网页「启动本机软件」 | 不会开第二个:把 yuncang://open?code=… 通过命名管道转给已运行实例 |
| 托盘双击 / 右键「打开主界面」 | 恢复窗口 |
| 托盘右键「重启软件」 | 等 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(占位,打包时必须覆盖) |
打包正式版时指定真实域名:
dotnet publish -c Release -r win-x64 -p:ServerBaseUrl=https://trace.example.com -o publish
优先级(从高到低):
- 启动参数
--server=http://192.168.1.10:7300(临时,不落盘); - 环境变量
YUNCANG_SERVER; -p:ServerBaseUrl=注入的构建默认值;- 用户在登录页手改并保存的地址(
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) - 默认普通权限运行:
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,后端已有,无需新增接口), 逐台静默执行:- 用 8000 私有协议写 NTP(
NET_DVR_SET_NTPCFG,与桌面端同一个 NTP 地址); - 立即生效:
NET_DVR_SET_TIMECFG把设备时间直接校准到 NTP 时间; - 顺带把该录像机下的摄像头逐个校时(
GET /api/web/nvrs/:id/channels拿通道号 →NET_DVR_SET_TIMECFG带通道号,录像机转发给 IPC),逐个通道报成功/失败; - 回读 NTP 配置与设备时间,在窗口里逐台返回结果(✔/✘ + 偏差 + 摄像头 n/m)。
- 用 8000 私有协议写 NTP(
- 为什么必须单独校摄像头:画面里烧的 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参数已删除,旧前端传了会被忽略)。
构建 / 运行 / 发布
构建 / 运行 / 发布
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)+ 自动更新
desktop/installer/ 下是安装包定义(WiX 5,免费;WiX v6+ 需要 OSMF 付费协议,别装最新版)。
# 工具只需装一次
dotnet tool install --global wix --version 5.0.2
cd desktop\installer
.\build.ps1 # 开发环境(默认),版本取 csproj(1.0.0)
.\build.ps1 -Version 1.0.1 # 指定版本
.\build.ps1 -Environment Production -Version 1.0.1 -ReleaseNotes "修复若干问题"
环境与域名(package.config.json)
| 环境 | 默认后端 | 用途 |
|---|---|---|
Development |
http://127.0.0.1:7300 |
本机联调;打完会自动把包+版本信息复制到后端,本机就能测更新 |
Production |
https://packs.example.com(占位,发布前必须改成正式域名) |
正式安装包 |
build.ps1 -Environment Production 自动用生产域名打 exe(ServerBaseUrl)和下载地址;
也可以用 -ServerBaseUrl 临时覆盖。
脚本做了什么
dotnet publish(自包含单文件,不依赖 .NET 运行时;版本号一起注入程序集); 同时把native\HCNetSDK\**、native\ffmpeg\**、..\extension\**作为独立文件输出(不走单文件自解压); 缺publish\native\ffmpeg\ffmpeg.exe会直接报错中止;wix build生成 MSI(Product.wxs用<Files Include="..\publish\native\**" />、<Files Include="..\publish\extension\**" />递归收集,保持目录结构;extension\test/extension\tools这类调试文件不打进包);- 算 MD5 → 写
version.json; - 复制到后端:MSI →
backend/app/public/download/desktop/,version.json→backend/app/public/version/desktop/; - 本地
out/与后端目录各只保留最近 5 个安装包(keepVersions可配)。
安装包与版本信息都归到后端
desktop子目录:下载地址<域名>/download/desktop/YuncangTraceSetup-x.y.z.msi, 版本信息仍是<域名>/download/version.json(老客户端写死了这个地址,不能改)。
谷歌浏览器插件随包安装
仓库根目录的 extension/ 会一起打进 MSI,安装后固定在 <安装目录>\extension
(perUser 安装即 %LOCALAPPDATA%\Programs\YuncangTrace\extension):
- 菜单「工具 → 复制谷歌插件地址」直接把该目录的 Windows 路径(如
C:\Users\xxx\AppData\Local\Programs\YuncangTrace\extension)复制到剪贴板; 写剪贴板会重试(WPF → WinForms,各 3 次 ×150ms),被输入法/剪贴板工具/远程桌面占用时不会直接报CLIPBRD_E_CANT_OPEN; 仍然失败会提示原因,并可以选「打开记事本」把路径显示出来手动抄写; - 用户打开
chrome://extensions→ 打开「开发者模式」→「加载已解压的扩展程序」→ 粘贴路径即可; - 卸载时该目录随 MSI 组件一起删除;
自动更新怎么工作
软件启动(登录后)→ GET {后端}/download/version.json?t=时间戳
→ version.json 的 version 比当前程序集版本新
→ 软件内弹窗:新版本号 / 更新说明 / 安装包大小
→ 点「立即更新」→ **软件内下载(进度条)**→ MD5 校验
→ 自动静默安装(msiexec /passive)→ 软件退出 → 装完自动重新打开
- 不跳浏览器:下载、进度、校验、安装都在软件里完成。
- 下载落在
%TEMP%\YuncangTraceUpdate\,文件名取 downloadUrl 里的真实文件名。 - 安装前会等 3 秒(让本进程先退出,否则 exe 被占用换不掉);perUser 安装不需要管理员。
- 版本一致性防护:若
downloadUrl里的包版本(YuncangTraceSetup-x.y.z.msi)不比当前版本新, 直接忽略 —— 防止 version.json 配错/漏传包导致「装完还是旧版 → 无限弹窗」。 - 回归测试可用环境变量
YUNCANG_AUTO_UPDATE=1让弹窗出现后自动开始下载(无需手点)。
version.json 长这样(脚本生成,不用手写):
{
"version": "1.0.1",
"downloadUrl": "https://正式域名/download/desktop/YuncangTraceSetup-1.0.1.msi",
"md5": "7a93b4…",
"size": 56786944,
"publishedAt": "2026-10-17T12:00:58+08:00",
"buildId": "20261017120058",
"environment": "Production",
"releaseNotes": "修复若干问题"
}
⚠️ 缓存(这里最容易踩坑)
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关缓存,否则只在应用层关没用: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 自动删除 exe、协议注册、开始菜单 —— 即「取消注册」 |
| 升级 | MajorUpgrade:装新版会替换旧版;降级被拦 |
| 用户数据 | %LOCALAPPDATA%\YuncangTrace\{settings,session}.json 卸载不删(重装后仍保持设置/登录) |
msiexec /i out\YuncangTraceSetup-1.0.1.msi # 安装
msiexec /x out\YuncangTraceSetup-1.0.1.msi # 卸载
需要「本机所有用户都能用」时:
Product.wxs里Scope改perMachine、注册表根改HKLM, 安装时会要管理员权限(UAC)。默认的 perUser 更省事,也够用(软件数据本来就是按用户存的)。
⚠️
build.ps1必须保存为 UTF-8 with BOM:PowerShell 5.1 读无 BOM 的脚本会按 GBK 解析, 中文注释直接把语法搞崩。
验证自动更新(不卸载重装)
cd desktop\installer
.\build.ps1 -Environment Development -Version 1.0.7 # 先发布一个更高版本(包+version.json 落到后端)
.\test-update.ps1 # 启动旧版本 → 等它自己升级上去
test-update.ps1 做的事:
- 读后端
/download/version.json的目标版本,和当前安装版本比较(已是最新就直接退出); - 关掉正在运行的软件(单文件自解压出来的真实进程);
- 带
YUNCANG_AUTO_UPDATE=1启动旧版本(更新窗口出现后自动下载,不用手点); - 轮询
%LOCALAPPDATA%\Programs\YuncangTrace\*.exe的ProductVersion,直到变成目标版本; - 检查本机服务 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(端口写在前端页面与插件里)。
代码里同时注册了 http://127.0.0.1:17300/ 前缀 —— HttpListener 只接受「注册过的 host」,
不注册的话用 127.0.0.1 访问会直接被回 400(前端改 VITE_LOCAL_SERVICE 时就会碰到)。
浏览器直接打开 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/。
为什么没有单独的「探活 / 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(当前后端地址):
// 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": "本机软件未登录,请先在软件里登录" }
示例:
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-AgeAccess-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」或干脆没反应)。 - 界面上完全不展示协议:注册由安装包完成、卸载时 MSI 自动删除,启动时自动校正到当前 exe;
用户不需要知道
yuncang://这回事(排障看日志或注册表即可)。 - 手工注册/排查:
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)。
和前端 / 插件怎么配合
- WMS 页面上点运单号旁的按钮 → 插件按「打开方式」处理:默认直接用
yuncang://open?code=<运单号>唤起本机软件并定位到该单号 (浏览器会先问一次「要打开吗」);把打开方式改成「独立小窗 / 新标签页」则改为打开网页; /local页只发一个请求GET /api/query/{code}:- 连不上 → 提示「服务暂不可用 / 本地打印服务未启动,请下载安装后再试」+ 下载按钮;
点「已安装,启动本机软件」会走
yuncang://open?code=...,然后每秒重试同一个查询接口; need-login(软件没登录)→ 页面自动POST /api/activate-login把本机登录窗叫到前台,然后每秒重试同一个查询接口等登录完成(最长 30s),登录好自动拿到结果;ok→ 直接展示(页面顶部会显示「本机软件已登录:xxx」)。
- 连不上 → 提示「服务暂不可用 / 本地打印服务未启动,请下载安装后再试」+ 下载按钮;
点「已安装,启动本机软件」会走
- 本软件被协议拉起时,会拿到
yuncang://open?code=xxx参数:已经开着就转给原窗口(单实例), 没开就启动 → 先登录 → 登录完自动查询这个码(登录前收到的 code 会先存着)。 单实例的命名管道监听在登录之前就起来了,所以用户卡在登录窗时被网页唤起也不会丢参数。
插件「直接唤起」与唤不起时的提示(重要)
浏览器不会告诉网页协议到底有没有打开成功 —— 没安装、协议没注册、用户在 Chrome 的 「要打开吗」上点了取消,这三种情况在页面侧完全一样。所以必须做超时兜底:
- 点击 → 隐藏 iframe 触发
yuncang://open?code=xxx(不能导航当前页,否则协议没注册会变成错误页); - 判断到底成没成,不看页面焦点,看本机服务在不在:协议触发后每 0.7s 探测一次
http://localhost:17300/api/query/(任何 HTTP 响应都算成功,扩展带 host 权限,不受页面 CSP 影响);- 探测到 → 什么也不做(软件本来就在跑时也能正确判定,不会误报);
- 8 秒都探测不到 → 认为没起来,右下角弹出兜底卡片:
- 在网页中查看 → 打开插件设置里的「唤不起时的兜底页」(默认
http://localhost:7301/local?code={code}, 该页面里有完整的下载安装引导); - 下载安装 → 打开插件设置里的「软件下载地址」(留空则不显示这个按钮)。
- 插件设置页的相关配置:
- 打开方式:
直接唤起本机软件(协议)(默认)/独立小窗(网页)/新标签页(网页); - 协议模板(仅「直接唤起」时生效):默认
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 秒,面板里显示进度),任意一路拉到录像就停止校验并显示「预览回放 / 下载录像」按钮 —— 不需要把每一路都验完,也不需要用户手动点「校验」。 预览和下载仍按全部流处理:没录像的那几路在下载时自己跳过,保证多路合并不会退化成单路。回放时间按录像机时钟对齐:扫码时间来自本机时钟,回放是按录像机本地时间定位的。 每次校验/预览/下载前会读一次录像机时间(8000 私有协议),把请求窗口整体平移, 日志里能看到
[playback] 录像机 … 与本机时钟相差 X 秒。本机时间不准(比如 Windows 时间服务没开、慢了几秒)时,短回放窗口会把面单截到窗口外 —— 这一步就是防这个。
多路对齐(预览 / 合并下载)
几路回放是各自独立连录像机的,天然会有两处时间差,都要单独处理:
- 开播时间差(预览):各路 RTSP 建链快慢不同,先出帧的那路会一直“跑在前面”。
PlaybackPreviewWindow的做法是先一起等、再按帧一起放:- ffmpeg 每出一帧回调一次(
HikFfmpegService.Subscribe)按顺序进各自队列。 ⚠️ 不能定时去取“最新一帧”:ffmpeg 定位到关键帧后会把「关键帧→请求时间」整段一次吐出来, 只留最新帧会把这串前面全丢掉,那一路的“第一帧”其实是 1~2 秒后的画面(现象:小窗一出现就超前); - 每一路都出过第一帧(最多等 12 秒,超时当这路没录像)后才开始播,每 40ms 从每路队列各取一帧, 先上线的那路放的就是等同步时攒下的积压 → 几路自然停在同一内容位置;
- 队列超过 220 帧(≈9 秒)就丢到 50 帧(≈2 秒),设备推得比实时快也不会越播越晚。
日志里出现
[playback] 多路回放开始同步播放(各路基线帧数:…)就说明生效了。 播到请求窗口就一起停:录像机不会按endtime主动断流,各路停的时机还不一样 (实测一路到点停止、另一路还在往后推,看着就是一个窗先冻住), 所以到EndTime - StartTime时统一收尾、释放设备会话,标题变成「回放结束」。
- ffmpeg 每出一帧回调一次(
- 录制起点差(下载 / 合并 / 预览):回放是从“请求时间所在关键帧”开始推的,
各通道 GOP 位置不同 → 同一时间点开始拉的两段录像,第一帧能差好几秒;
不处理就会两格画面错开。
用
NET_DVR_GetPlayBackOsdTime读第一帧的真实内容时间(8000 协议,实测可用):- 下载:
PullPlaybackToFile在第一包数据到达时读一次,偏移 = 首帧 OSD − 请求时间, 合并时提前的路用trim切头、晚开始的路用setpts后移 (日志[playback] 通道N 首帧 OSD=hh:mm:ss,比请求时间早/晚 X 秒); - 预览:RTSP 侧拿不到内容时间,所以开窗前先用
ProbePlaybackOsdStart每路探一次, 按 OSD 差值推迟出图(日志[playback] 预览按 OSD 起点对齐:…)。 - 拿不到 OSD(固件不支持/无数据)才退回「时长反推」(
提前量 = 文件时长 − 请求窗口); 偏差超过 60 秒视为通道时钟异常,不做对齐,绝不把画面推歪。 ⚠️ 曾经只用「时长反推」,实测同一个窗口拉两次会得到 36.1s / 42.1s 两种结果 (关键帧起止 + 流在哪断都不固定),头和尾分不开 → 会随机差 2~4 秒,已弃用为首选。
- 下载:
- 摄像头自身的时钟:画面里烧的 OSD 时间是摄像头自己打的,和录像机的录像时间轴无关。 两个摄像头时钟不一致时,即便回放已经对齐,两格 OSD 也会差几小时甚至几年 —— 这不是回放错位,要在录像机里开「摄像机校时(IPC 校时)」或给 IPC 配 NTP 才能一致。
查询日志只记结论([pack-query] 运单号 → found=… records=… streams=…),不再写完整 JSON;
要排查原始数据看后端日志或页面。
要换成别的数据源,只改 OrderQueryService.QueryAsync 一个方法就行(返回 QueryResult,
Data 是扁平字典即可,前端 /local 页也吃这份数据)。
扫码 → 查询(不跳页)
- 手动输入 / 回车 / 点查询 / 协议唤起:
RunQueryAsync(),切到「打包查询」页展示; - 通道扫码:
OnChannelBarcode后台算一次结果,绝不切页签 (用户还在「扫码通道 / 扫码记录」页时,只在「打包查询」页签上加●, 切过去时才把结果显示出来); - 扫码数据本身仍由
ScanService落记录 + 上报,跟查询是两条独立的路。
常见问题
| 现象 | 处理 |
|---|---|
启动报「没有绑定端口的权限」/ Access is denied (5) |
管理员执行 netsh http add urlacl url=http://localhost:17300/ user=%USERNAME%,或改成以当前用户身份运行 |
| 报端口被占用(错误 32) | 已经开了一个实例(单实例会把参数转过去);检查任务管理器里的残留进程 |
| 网页提示服务不可用,但软件在跑 | 先用浏览器直接打开 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)
登录窗
- 微信扫码登录:点「微信扫码登录」→
GET /api/wechat/login发码 → 显示二维码 (GET /api/wechat/qrcode.gif?code=,WPF 不能渲染 SVG 所以后端额外给了 GIF 版)→ 长轮询GET /api/wechat/login?code=&wait=25,手机确认后直接拿令牌进主界面;码过期会自动换新。 - 账号密码登录与微信登录都会带回主体列表(
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 |
| 调试 | 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)会被忽略,不污染条码行 |
| 静音 | ScanService.SetMuted |
只存本地 + 让连接重走一遍(关 socket → 立即重连 → 整条设置重下发)。不在现有 socket 上补写指令:Android 侧实测“字节发出去了但枪没执行”时无法判断 |
| 串口指令调试 | Views/ScannerCommandWindow(通道页「串口指令…」) |
发任意 HEX 字节透传给扫码枪,预填四条常用指令(静音/恢复蜂鸣/连续扫描/间隔 0s)。换批枪后指令集不同时现场自己试,不用发版 |
| 假死看门狗 | ScanService.WatchdogLoopAsync |
每 30s:连接看着在线但 60s 没字节 → 回查设备侧 SOCK.ClientIP(CID 10001 才有)→ 本机 IP 不在里面就强制重连(设备断电重启时 TCP 不发 FIN,ReadAsync 会永久挂住) |
| IP 变化 | ScanService.ApplyDiscoveredIps |
每次发现结果回来就刷新各通道 LastIp,变了立即用新地址重连(DHCP 续租后不会卡在旧 IP) |
| 编排 | 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,失败不标记、指数退避重发(服务端按 设备+通道+条码+秒 精确去重;同一运单 24 小时内只保留一条,后上报的新时间会覆盖旧记录的时间与工作台快照)。主体过期/停用或令牌失效 → 暂停推送(保留本地积压、不做无意义重试),暂停期间每 60 秒只发一次心跳;心跳返回 subject.expired=false(续费)后自动恢复并补传 |
添加通道(设备名 + 通道号)
扫描设备 → 选中 → 添加为通道 会弹窗让用户定通道号与设备名(与 AndroidScanCenter 一致):
- 通道号:
1..50的下拉框,已占用的号照样列出来并标注「已被 xx 占用」,选中就提示、不关框; 默认勾在最小空号上。没有「通道号」设备字段 —— 它是本地概念(现场认工位),上报时就是channelId。 - 设备名:默认填设备自报的
HostName,会写进设备(SYS.HostName,UTF-8 支持中文)并落 flash; 留空则用设备自报名。写失败不阻断添加(只影响设备面板/其他上位机看到的叫法)。
添加顺序是「先配设备、后落本地」(回滚本地行不通:设备名可能已经写上去了):
- 确保设备有给中控用的 TCP 服务(
SOCK段packcenter / TCP-SERVER / 8087): 已就绪则不写;缺失/不对则整条写入 → 回读确认(设备RC=0只代表报文收到了,端口冲突它不报错); 这一步失败就整个添加失败,本地什么都不写(否则会得到一条永远连不上的死通道)。 - 设备名与自报的不同 →
10005写SYS.HostName→10017落 flash(不落盘一次重载就丢)。 - 才把通道写进本地配置、开始连 TCP,并同步通道列表到服务器。
真机验证(192.168.9.204,E10C 1.41.1):写设备配置 SYS:0 → 保存到 flash:0 →
广播里的 HostName 立即变成新名字 → 通道 1(工位 9)已连接 192.168.9.204:8087。
界面
- 主窗口改成页签:打包查询 / 扫码通道(后者仅在「设备服务」开启后出现)。 查到条码(协议唤起或通道扫码)时默认切回「打包查询」页签并自动查询。
- 扫码通道页:每个区块的状态与按钮都在各自标题行上。
- 「扫码通道」标题行:状态(
扫码服务运行中 · 通道 N 个(在线 M)+ 通道同步状态 + 待上传条数)+重连全部/静音(选中行切换,已静音时叫「恢复蜂鸣」)/读取设备配置/删除通道; 通道列表有「状态」「静音」两列; 没有「同步通道」按钮 —— 通道增删/启停都会自动上传并回查确认; - 「发现到的设备」标题行:
开始扫描(开关,打开后常驻发现:每 3s 探测、socket 一直收,直到手工停止)+添加为通道+ 状态(正在扫描… 未添加 N 台/发现 N 台未添加的设备(另有 M 台已添加))。 - 已经添加为通道的设备不会再出现在发现列表里:显示集合与「发现到的全集」分开存(
_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/模拟扫码枪。