- 端口 17311 → **17300**(桌面端常量、localhost/127.0.0.1 双前缀、前端 LOCAL_BASE、
插件默认目标与说明、两个 README 全部同步)。
- `/api/health` 返回值加上 `loggedIn` / `user`(由 App 提供:IsLoggedInProvider、UserNameProvider),
前端只认 `ok`(探活),再用 `loggedIn` 决定要不要唤起登录。
- 新增 `POST /api/activate-login`:叫本机软件把登录窗(已登录则主界面)带到前台。
用 POST 而不是 GET,避免被浏览器/聊天工具的链接预取误触发;CORS Allow-Methods 加了 POST。
- `/api/query/{code}` 未登录时返回 401(前端会转去唤起登录)。
- 桌面端:App 记住登录窗引用,收到 LoginRequested 时切回 UI 线程激活它(托盘里也能叫出来)。
- 前端 `/local?code=`:
- 路由加 alias `/local/`;
- 新增 need-login 状态:探活到「软件在跑但没登录」→ 自动 POST activate-login →
每秒探活等登录(30s 上限)→ 登录完成后自动查询;期间有「再叫一次登录窗口」按钮与托盘提示;
- api/local.ts 增加 localHealth()(online/loggedIn/user)、requestLocalLogin()、waitForLoggedIn();
waitForHealth() 改为返回状态而非 bool;老版本软件没有 loggedIn 字段时按已登录处理(向后兼容)。
- 实测(7301 + 模拟的 17300):打开 /local/?code=… → 「本机软件未登录 / 正在等待登录…」→
mock 翻成已登录后自动切到查询结果(5 行);杀掉 mock 后显示「服务暂不可用」且探测地址为 17300。
云仓视频溯源软件(本机服务 / WPF)
Windows 桌面端,用前端 /local 公共页和 Chrome 插件做对接:
- 登录页:账号密码登录后端(
POST /api/web/auth/login)拿 user JWT,令牌存本机; 下次启动先用/api/web/me验证,还有效就直接进主界面; - 在
127.0.0.1:17300起一个本机 HTTP 服务,浏览器里的页面直接查询本机数据; - 注册
yuncang://启动协议,网页可以「叫醒」本软件(前提是已安装); - 托盘图标:关窗口只是缩到托盘(本机服务不能因关窗断掉),双击托盘恢复窗口, 右键菜单有「打开主界面 / 服务地址 / 退出」;
- 防多开:全局互斥体 + 命名管道 —— 第二个实例不会抢 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 + CORS + PNA
├── 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 # 全局日志缓冲(窗口没开时的日志也不丢)
└── JsonUtil.cs # JSON 序列化(中文不转义)
登录 / 托盘 / 防多开的行为
| 场景 | 行为 |
|---|---|
| 首次启动 | 先起本机服务(17300)与托盘,再弹登录页 → 登录成功才出主窗口 |
| 已有令牌 | 登录窗一闪而过:/api/web/me 通过就直接进主窗口;失效则清掉令牌留在登录页 |
| 关窗口(X) | 隐藏到托盘,本机服务继续跑(第一次会冒一个气泡提示) |
| 再次双击 exe / 点网页「启动本机软件」 | 不会开第二个:把 yuncang://open?code=… 通过命名管道转给已运行实例 |
| 托盘双击 / 右键「打开主界面」 | 恢复窗口 |
| 「退出登录」 | 清令牌 → 关闭主窗口 → 回到登录页(取消登录则退出程序) |
| 托盘右键「退出」 | 真正退出(dispose 托盘与本机服务) |
服务器地址默认 http://127.0.0.1:7300(后端 dev 默认端口),登录页上可以改,改完会存进 settings.json。
换服务器后不会复用旧令牌(会要求重新登录)。
环境要求
- 编译:.NET 8 SDK(
dotnet --list-sdks能看到8.x) - 只运行已发布的 exe:.NET 8 Desktop Runtime(不需要 SDK)
本仓库当前环境没有装 .NET,所以这份代码没在 CI 里编译过;第一次请自己跑一遍
dotnet build,有报错直接贴出来。
构建 / 运行 / 发布
cd desktop
dotnet build -c Release # 编译
dotnet run # 直接跑(调试)
# 发布给用户装(framework-dependent,体积小、需要装 Desktop Runtime)
dotnet publish -c Release -r win-x64 --self-contained false -o publish
# 或者自带运行时(体积大,但用户什么都不用装)
dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -o publish
本机接口(前端 /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/health |
验活 + 登录状态:2xx 即认为软件已启动。返回 { ok, name, version, port, loggedIn, user, serverTime } |
| GET | /api/query/{code} |
按运单号查信息(需已登录,否则 401 { ok:false, loggedIn:false, message })。成功时字段平铺在顶层({ code, orderNo, ... }) |
| POST | /api/activate-login |
把本机软件的登录窗叫到前台(已登录时把主界面叫到前台)。网页发现 loggedIn:false 时自动调它 |
示例:
curl http://localhost:17300/api/health
curl http://localhost:17300/api/query/321408064481776
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);卸载时点「取消启动协议」或调用
ProtocolHelper.Unregister(); - 手工注册/排查:
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 页面上点运单号旁的按钮 → 插件打开
http://<站点>/local?code=<运单号>(/local/也认); /local页先探活http://localhost:17300/api/health:- 连不上 → 提示「服务暂不可用 / 本地打印服务未启动,请下载安装后再试」+ 下载按钮;
点「已安装,启动本机软件」会走
yuncang://open?code=...,然后每 1s 轮询探活; - 连上了但
loggedIn:false(软件没登录)→ 页面自动POST /api/activate-login把本机登录窗叫到前台,然后每秒探活等登录完成(最长 30s),登录好自动继续查询; - 已登录 → 直接调
/api/query/{code}展示(页面顶部会显示「本机软件已登录:xxx」)。
- 连不上 → 提示「服务暂不可用 / 本地打印服务未启动,请下载安装后再试」+ 下载按钮;
点「已安装,启动本机软件」会走
- 本软件被协议拉起时,会拿到
yuncang://open?code=xxx参数:已经开着就转给原窗口(单实例), 没开就启动 → 先登录 → 登录完自动查询这个码(登录前收到的 code 会先存着)。
★ 接真实数据
只改一处:Services/OrderQueryService.cs 的 Query(string? code)。
public QueryResult Query(string? code)
{
var value = (code ?? "").Trim();
if (value.Length == 0) return QueryResult.BadRequest("缺少运单号");
// 例:查本地 SQLite / 扫本地打包视频目录 / 调内部接口
var row = _db.FindByCode(value);
if (row is null) return QueryResult.NotFound($"没有找到 {value} 的记录");
return QueryResult.Success(new Dictionary<string, object?>
{
["code"] = row.Code,
["orderNo"] = row.OrderNo,
["printStatus"] = row.PrintStatus,
["videoPath"] = row.VideoPath,
});
}
返回对象平铺即可,前端页面会把顶层字段渲染成「项目 / 值」两列(字段随便加)。
常见问题
| 现象 | 处理 |
|---|---|
启动报「没有绑定端口的权限」/ Access is denied (5) |
管理员执行 netsh http add urlacl url=http://localhost:17300/ user=%USERNAME%,或改成以当前用户身份运行 |
| 报端口被占用(错误 32) | 已经开了一个实例(单实例会把参数转过去);检查任务管理器里的残留进程 |
| 网页提示服务不可用,但软件在跑 | 先用浏览器直接打开 http://localhost:17300/api/health:打不开→防火墙/端口;打得开→多半是 CORS 头没回 |
| 点网页「启动本机软件」没反应 | 协议没注册(界面看「启动协议」状态);或浏览器拦了自动跳转(必须用户点击) |
| 改了协议名 | 注册表重注册 + 前端 VITE_APP_PROTOCOL 同步 + 插件目标地址同步 |