新增 MSI 安装包:安装即注册 yuncang:// 协议,卸载自动取消注册

需求:打包安装包;协议在**安装时**注册(不依赖先启动软件一次);卸载能清掉注册。

实现(desktop/installer/):
- Product.wxs(WiX 5):
  - Scope=perUser(免管理员、无 UAC),安装到 %LOCALAPPDATA%\Programs\YuncangTrace;
  - Component 里写 HKCU\Software\Classes\yuncang(默认值 / URL Protocol / shell\open\command),
    注册表项属于 MSI 组件 → **卸载时自动删除**,即「取消注册」;
  - 开始菜单快捷方式(RemoveFolder On=uninstall);
  - MajorUpgrade(升级替换、拒绝降级);用户数据 settings/session.json 不在安装目录,卸载保留。
  - 版本号用 $(var.Version) 由构建命令注入,避免和 csproj 两处维护。
- build.ps1:读取 csproj 的 <Version> → dotnet publish(自包含单文件)→ wix build
  → out\YuncangTraceSetup-<版本>.msi。
  ⚠️ 脚本保存为 UTF-8 with BOM:PowerShell 5.1 读无 BOM 脚本会按 GBK 解析,中文注释会让语法报错。
- 工具链:`dotnet tool install --global wix --version 5.0.2`
  (WiX v7 会要求接受 OSMF 付费维护费协议,改用 v5)。

实测(perUser 静默安装 → 协议 → 唤起 → 卸载):
- 安装:文件落到 %LOCALAPPDATA%\Programs\YuncangTrace,HKCU 协议立即指向安装目录
  (安装前指向 desktop\publish,安装后被正确覆盖),开始菜单快捷方式已创建;
- **不启动软件**,直接 Start-Process "yuncang://open?code=INSTALLTEST":
  进程路径 = 安装目录 exe,日志显示 "已恢复登录:管理员 → 收到启动协议 → 查询:INSTALLTEST";
- 卸载:安装目录删除、HKCU 协议删除、开始菜单删除,均无残留;
- build.ps1 完整跑通,产物 54.1 MB(cab 压缩)。

.gitignore:忽略 desktop/installer/out/ 与 *.wixpdb。
desktop/README.md:新增「打安装包(MSI)」章节(构建命令、安装范围、协议注册/卸载行为、
perMachine 改法、BOM 提醒)。
This commit is contained in:
liufumingren 2026-10-17 11:49:26 +08:00
parent 65a4fd86f1
commit 77b5713d02
4 changed files with 216 additions and 0 deletions

4
.gitignore vendored
View File

@ -25,6 +25,10 @@ artifacts/
*.user
*.suo
# 安装包产物(installer/build.ps1 生成)
desktop/installer/out/
*.wixpdb
# ---------- 运行期 / 日志 ----------
# backend 的 logs/、多实例自测时的 logs-test/、脚本产出的 run/
logs/

View File

@ -113,6 +113,43 @@ dotnet publish -c Release -r win-x64 --self-contained true `
开发阶段想让 `bin\Debug` 的 exe 也能直接双击,两个办法:装官方 SDK/Desktop Runtime 到标准位置,
或者每次用发布产物验证唤起。
## 打安装包(MSI)
`desktop/installer/` 下是安装包定义(**WiX 5**,免费;WiX v6+ 需要 OSMF 付费协议,别装最新版)。
```powershell
# 工具只需装一次
dotnet tool install --global wix --version 5.0.2
cd desktop\installer
.\build.ps1 -ServerBaseUrl https://正式域名
# → out\YuncangTraceSetup-<版本>.msi(约 54 MB,cab 压缩)
```
`build.ps1` 做两件事:先 `dotnet publish`(自包含单文件,不依赖运行时)→ 再 `wix build`。
版本号取自 csproj 的 `<Version>`,改版本只改那一处。
安装包行为:
| 项 | 说明 |
| --- | --- |
| 安装范围 | **perUser**(免管理员、无 UAC),装到 `%LOCALAPPDATA%\Programs\YuncangTrace` |
| 启动协议 | **安装即注册** `yuncang://`(HKCU),不需要先启动软件 |
| 卸载 | MSI 自动删除 exe、协议注册、开始菜单 —— 即「取消注册」 |
| 升级 | `MajorUpgrade`:装新版会替换旧版;降级被拦 |
| 用户数据 | `%LOCALAPPDATA%\YuncangTrace\{settings,session}.json` 卸载**不删**(重装后仍保持设置/登录) |
```powershell
msiexec /i out\YuncangTraceSetup-1.0.0.msi # 安装
msiexec /x out\YuncangTraceSetup-1.0.0.msi # 卸载
```
> 需要「本机所有用户都能用」时:`Product.wxs` 里 `Scope` 改 `perMachine`、注册表根改 `HKLM`,
> 安装时会要管理员权限(UAC)。默认的 perUser 更省事,也够用(软件数据本来就是按用户存的)。
> ⚠️ `build.ps1` 必须保存为 **UTF-8 with BOM**:PowerShell 5.1 读无 BOM 的脚本会按 GBK 解析,
> 中文注释直接把语法搞崩。
## 本机接口(前端 `/local` 页用的就是这两个)
服务固定监听 `http://localhost:17300`(端口写在前端页面与插件里)。

View File

@ -0,0 +1,86 @@
<?xml version="1.0" encoding="utf-8"?>
<!--
云仓视频溯源软件(本机服务)—— MSI 安装包定义
设计要点:
- **perUser 安装**(免管理员、无 UAC):装到 %LOCALAPPDATA%\Programs\YuncangTrace;
- **安装即注册启动协议** yuncang://(HKCU\Software\Classes),不用先启动软件;
- 注册表项属于安装包的组件 → **卸载时 MSI 自动删除(= 取消注册)**;
- 升级:MajorUpgrade;同版本重装走「修复/重装」。
构建(wix 是 dotnet 全局工具,推荐 build.ps1 一键完成):
wix build Product.wxs -arch x64 -d Version=1.0.0 -o out\YuncangTraceSetup-1.0.0.msi
发布产物要先有:desktop\publish\YuncangTrace.LocalService.exe
-->
<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs">
<Package Name="云仓视频溯源软件"
Manufacturer="云仓"
Version="$(var.Version)"
UpgradeCode="A1E7CF0F-4FC5-4A88-84B5-13E818F352CC"
Scope="perUser"
Compressed="yes">
<!-- 高版本已装时不允许降级安装 -->
<MajorUpgrade DowngradeErrorMessage="已安装更新版本的云仓视频溯源软件,请先在「应用和功能」里卸载旧版本。" />
<MediaTemplate EmbedCab="yes" />
<!-- 安装目录:%LOCALAPPDATA%\Programs\YuncangTrace -->
<StandardDirectory Id="LocalAppDataFolder">
<Directory Id="ProgramsFolder" Name="Programs">
<Directory Id="INSTALLFOLDER" Name="YuncangTrace" />
</Directory>
</StandardDirectory>
<!-- 开始菜单 -->
<StandardDirectory Id="ProgramMenuFolder">
<Directory Id="AppMenuFolder" Name="云仓视频溯源软件" />
</StandardDirectory>
<Feature Id="Main" Title="云仓视频溯源软件" Level="1">
<ComponentGroupRef Id="AppComponents" />
</Feature>
</Package>
<Fragment>
<ComponentGroup Id="AppComponents" Directory="INSTALLFOLDER">
<!-- 主程序(单文件自包含 exe) -->
<Component Id="MainExe" Guid="C779B513-9C6B-4BEC-A963-3AF1E53FEC30">
<File Id="MainExeFile"
Source="..\publish\YuncangTrace.LocalService.exe"
KeyPath="yes" />
</Component>
<!--
启动协议 yuncang://open?code=xxx
写 HKCU(perUser 安装):安装完成即可被浏览器唤起;
卸载时随组件一起删除,不会留下无效协议。
-->
<Component Id="Protocol" Guid="857877CC-C14C-4F17-A0C6-49D5852E0D2E">
<RegistryKey Root="HKCU" Key="Software\Classes\yuncang">
<RegistryValue Type="string" Value="URL:云仓视频溯源软件" KeyPath="yes" />
<RegistryValue Name="URL Protocol" Type="string" Value="" />
<RegistryKey Key="shell\open\command">
<RegistryValue Type="string"
Value="&quot;[INSTALLFOLDER]YuncangTrace.LocalService.exe&quot; &quot;%1&quot;" />
</RegistryKey>
</RegistryKey>
</Component>
<!-- 开始菜单快捷方式(卸载时连文件夹一起删) -->
<Component Id="StartMenuShortcut" Directory="AppMenuFolder" Guid="6CE6EE8C-98FD-475F-947B-E365EBA41569">
<Shortcut Id="AppShortcut"
Name="云仓视频溯源软件"
Description="本机打印与溯源服务(打开后最小化到托盘)"
Target="[INSTALLFOLDER]YuncangTrace.LocalService.exe"
WorkingDirectory="INSTALLFOLDER" />
<RemoveFolder Id="RemoveAppMenuFolder" On="uninstall" />
<RegistryValue Root="HKCU" Key="Software\YuncangTrace\Install"
Name="StartMenuShortcut" Type="integer" Value="1" KeyPath="yes" />
</Component>
</ComponentGroup>
</Fragment>
</Wix>

View File

@ -0,0 +1,89 @@
#requires -Version 5.1
<#
.SYNOPSIS
打「云仓视频溯源软件」的 MSI 安装包。
.DESCRIPTION
1. 自包含单文件发布 → desktop\publish\YuncangTrace.LocalService.exe
2. 用 WiX 5 打包 → desktop\installer\out\YuncangTraceSetup-<版本>.msi
安装包特性:
- perUser 安装(免管理员、无 UAC),装到 %LOCALAPPDATA%\Programs\YuncangTrace
- **安装即注册** yuncang:// 协议(HKCU),不需要先启动软件
- 卸载时 MSI 自动删除协议与开始菜单(= 取消注册)
.PARAMETER ServerBaseUrl
打进 exe 的生产后端地址(登录用)。默认是占位地址,正式发布必须传真实域名。
.PARAMETER Configuration
默认 Release。
.EXAMPLE
.\build.ps1 -ServerBaseUrl https://trace.example.com
.NOTES
前置:dotnet tool install --global wix --version 5.0.2
(WiX v6+ 需要 OSMF 付费协议,v5 不需要)
#>
param(
[string]$ServerBaseUrl = 'https://packs.example.com',
[string]$Configuration = 'Release'
)
$ErrorActionPreference = 'Stop'
$desktop = Split-Path -Parent $PSScriptRoot # desktop\
$project = Join-Path $desktop 'YuncangTrace.LocalService.csproj'
$publishDir = Join-Path $desktop 'publish'
$outDir = Join-Path $PSScriptRoot 'out'
# 版本号以 csproj 为准(只读文件,不改它)
$projXml = [xml][System.IO.File]::ReadAllText($project, (New-Object System.Text.UTF8Encoding($false)))
$version = ($projXml.Project.PropertyGroup.Version | Where-Object { $_ } | Select-Object -First 1)
if (-not $version) { throw "csproj 里没找到 <Version>" }
Write-Host "版本:$version"
Write-Host "后端:$ServerBaseUrl"
# 1) 发布(自包含单文件:双击/协议唤起都不依赖 .NET 运行时)
Push-Location $desktop
try {
dotnet publish $project -c $Configuration -r win-x64 `
--self-contained true `
-p:PublishSingleFile=true `
-p:IncludeNativeLibrariesForSelfExtract=true `
-p:ServerBaseUrl=$ServerBaseUrl `
-o $publishDir
if ($LASTEXITCODE -ne 0) { throw "dotnet publish 失败($LASTEXITCODE)" }
}
finally {
Pop-Location
}
$exe = Join-Path $publishDir 'YuncangTrace.LocalService.exe'
if (-not (Test-Path $exe)) { throw "发布产物不存在:$exe" }
# 2) 打 MSI
$wix = (Get-Command wix.exe -ErrorAction SilentlyContinue).Source
if (-not $wix) { $wix = Join-Path $env:USERPROFILE '.dotnet\tools\wix.exe' }
if (-not (Test-Path $wix)) {
throw "找不到 wix.exe。先执行:dotnet tool install --global wix --version 5.0.2"
}
New-Item -ItemType Directory -Force -Path $outDir | Out-Null
$msi = Join-Path $outDir "YuncangTraceSetup-$version.msi"
Push-Location $PSScriptRoot
try {
& $wix build Product.wxs -arch x64 -d "Version=$version" -o $msi
if ($LASTEXITCODE -ne 0) { throw "wix build 失败($LASTEXITCODE)" }
}
finally {
Pop-Location
}
$size = [math]::Round((Get-Item $msi).Length / 1MB, 1)
Write-Host ""
Write-Host "完成:$msi($size MB)" -ForegroundColor Green
Write-Host "安装(免管理员):msiexec /i `"$msi`""
Write-Host "卸载: msiexec /x `"$msi`""