WindowsServicePlugin:选包、本机安装与恢复
本主题负责客户端如何选取 CVWindowsService 包,以及本机安装、数据库切换、配置和恢复;Backend 发布、版本/包选择与下载响应由 CVWindowsService 发布与下载维护。服务端成功返回不代表客户端校验、安装或启动成功。
必须区分三个制品:WindowsServicePlugin.dll / .cvxp 是插件;CVWindowsService[版本]...zip 是业务服务包;ColorVisionServiceHost 是许多安装/启停操作调用的后台权限代理。发布插件不等于发布服务ZIP,也不等于授权安装或变更数据库。
入口、依赖与权限
项目和 Plugins/Directory.Build.props 定义 Windows WPF、x64、net10.0-windows 及 Engine/UI 依赖。manifest身份为 WindowsServicePlugin,入口 WindowsServicePlugin.dll;插件发布版本取编译DLL的FileVersion。插件产物与交付负责HostCopy、manifest和.cvxp规则。
MenuServiceManager在“帮助 > 服务管理器”提供常用快捷入口,ServiceManagerAppProvider在“应用与工具 > 内部工具”提供另一入口;两者打开同一非模态窗口,不限制应用内角色。打开窗口不代表已具备Windows提权、目录ACL或后台代理授权。Menus中的服务日志菜单提供 localhost REST 日志导出入口,不属于 Backend CVWS API。InstallServiceManager是向导步骤,点击“安装”直接打开模态ServiceInstallWindow,确认安装目录及 MySQL、MQTT、服务组件后再执行安装。关闭窗口后刷新描述与配置状态;ConfigurationStatus仅检查 BaseLocation 非空且目录存在,不检查数据库、服务安装或健康。ServiceHostWindowsServiceController将安装/卸载/启停交给ColorVisionServiceHostClient,返回bool并记录代理缺失、旧版本或失败。执行仍需兼容的代理及服务、文件、数据库权限。- “终止”通过权限代理按服务进程白名单结束进程树,随后核对服务状态。常规启停使用服务控制器。 通用进程终止
- 项目虽为WinExe,当前
App.Application_Startup初始化配置/日志/主题、加载Engine后即Shutdown,不是另一套独立服务管理器交付入口。
安装、SQL、备份恢复和服务启停均须明确目标与授权。查看主题或下载元数据不授权这些动作;配置和日志可能含敏感内容,不为排障打印实际密码或完整配置。
窗口与操作分层
- “管理设置”提供目录、更新配置与状态刷新入口。服务行提供启停和重启,单项安装、卸载、终止和日志清理位于“更多操作”。窗口与样式由
ServiceManagerWindow.xaml、ServiceInstallWindow.xaml和ServiceManagerStyles.xaml定义。 - 安装窗口选择目录、服务包、组件和数据库选项。安装期间禁用表单,成功后自动关闭,失败时保留日志。
ServiceOperationLog随窗口开始和结束采集,切换标签时保留记录。 - “服务日志”页的“清空当前记录”只清窗口内存。“一键清空服务日志”清理三个受管理服务的磁盘日志,服务行可单独清理。磁盘清理需确认,并通过 ServiceHost 停止后恢复原本运行的服务。注册中心先停后启,避免提前拉起主服务。
ServiceLogCleanup仅清理目标log目录内的普通文件,保留目录并跳过重解析点。由安装根目录推导出的路径必须位于根目录内。单文件删除失败会汇总,恢复启动失败时需核对服务状态。
在线选包、回退与缓存
当前安装窗口有 DownloadServicePackageCommand / OnlineDownloadCommand,不是只有本地选ZIP。ServiceManagerConfig.UpdateServerUrl 默认取Marketplace默认地址;DownloadLocation 默认位于 Environments.DirToolPackageCache/CVWindowsService。
GetLatestCvWindowsServicePackageAsync 的客户端顺序是:
- 依次尝试配置源与
MarketplaceConfig.DefaultServiceBaseUrl,按authority去重;BuildServerRoot只保留authority,丢弃配置URL的路径、query和fragment,不是任意子路径API前缀配置。 - 每源先请求
/api/tool/cvwindowsservice/releases,读取latestVersion,在同版本packages中按数值suffix降序选择;没有可用downloadUrl仍可构造该版本download路径。 - releases获取/解析未成功才读
/latest-version,接受版本文本或含version/latestVersion的JSON,构造/download/<version>;该源两路失败才转下一源。 - 绝对downloadUrl原样使用,相对URL按源authority解析;这一解析层没有同源或强制HTTPS门禁。服务包和工具列表的元数据请求统一使用
UpdateHttpClientProvider,遵循“更新时禁用系统代理”设置;每次请求超时15秒,暂态失败最多尝试3次,服务包元数据仍失败后转下一分支,不在这里发送下载凭据。
取得候选即结束元数据源遍历,后面的实际下载或包校验失败不会重新尝试另一个源。FindCachedCvWindowsServicePackage 在下载目录顶层查 CVWindowsService[版本]*.zip,只取本地修改时间最新的一个,再通过下述目录识别;无效时进入下载,不逐个尝试更旧缓存。不与远端suffix、大小或摘要比对。下载委托 IDownloadService 的显式文件名重载,该调用authorization参数为null,并等待回调路径。CvwsPackageInfo 保留Version/DownloadUrl/FileName,优先使用发布元数据的fileName,缺失时使用URL中的ZIP文件名,否则生成 CVWindowsService[版本].zip,避免版本接口被保存为纯版本号;工具包同样传递列表中的真实文件名。仍未消费服务端hash/size,不能宣称此消费者已做发布签名或SHA-256核验。
单独下载成功仅设置 ServicePackagePath 并勾选服务安装,不自动安装。在线下载并行取得服务包与当前可见的MySQL/MQTT/VC++ 2013组件,每项成功即回填路径和勾选状态;等待全部任务后汇总失败组件名称与底层错误,保留其它成功结果。安装是独立命令;关闭安装窗口只释放日志绑定,没有取消这些后台下载/安装任务的逻辑。
“完整包”识别不是完整性认证
IsFullServicePackageZip 只打开ZIP并检查顶层名称包含RegWindowsService,以及CVMainWindowsService_x64 / CVMainWindowsService_dev至少一个;不要求目录内exe、cfg、SQL或CommonDll齐全,不验证签名/摘要。名称符合不等于包可信、可运行;该工作流仍以完整包而非增量包为交付契约。
ServicePackageVersionResolver 优先读取包中服务exe的FileVersion,失败回退文件名中的 CVWindowsService[版本];读取版本会临时提取文件,但不执行它。无法得到版本则终止安装。解压后若能读版本就比较一致性,读不到时只记日志并继续使用包版本,不是每个成功路径都完成二次版本核验。
安装清理枚举包内实际顶层名称,经名称和路径范围检查后删除BaseLocation下对应文件/目录,再解压覆盖;不限于三个服务目录。因此要确认包来源及每个实际顶层目标,“仅包内顶层”不是业务文件白名单。
安装、数据库与配置顺序
ExecuteInstallAsync 先检查所选MySQL版本与运行库、解析现有/目标服务版本和数据库,再安装所需运行库,依选择安装组件、替换文件、注册服务、执行数据库步骤、同步配置、启动服务;不是跨文件、服务注册和数据库的原子事务。
MySQL页的“ZIP全安装”和“注册服务”会在调用后台前检查运行库;完整安装窗口也使用同一版本规则。版本读取实际 mysqld.exe 文件信息,ZIP只临时提取其中的程序读取版本,不执行它、不依赖ZIP文件名判断。无法读取版本时提示并停止。MySQL 5.7.37及之前的5.7版本需要VC++ 2013 x64,5.7.38/39仍需要2013;5.7.40及之后和MySQL 8不会被这项检查拦截。这只是2013运行库检查,不代表已验证这些版本的全部依赖。
运行库检测沿用x64系统目录中的 msvcr120.dll 与 msvcp120.dll,两者都存在才通过;仅安装x86运行库不足以通过。MySQL页缺少运行库时会弹窗提示到“服务安装管理”下载或选择VC++ 2013 x64并安装,本次操作停止。完整安装窗口已选择有效运行库安装程序时先安装并复查;未提供安装程序时在停服务或替换目录之前提示并停止。显式勾选VC++ 2013仍按用户选择安装,不因MySQL 8跳过该选择。
| 阶段 | 当前约束与失败边界 |
|---|---|
| 版本与数据库 | ServiceDatabaseVersionMap 以主版本4为分界:低于4使用color_vision,4及以上使用color_vision_4xx;版本已知时优先于配置库名,未知时才沿用配置或默认4xx库 |
| 数据库升级选择 | AutoUpdateDatabase初始为true。已有MySQL且跨库名边界时,关闭该选项会在替换文件前拒绝 |
| 停止与替换 | 尝试停止受管理服务;普通停止失败不一定阻止清理,归档服务卸载失败则阻止包更新 |
| CommonDll与注册 | CommonDll存在时复制到已存在的三个服务目录再删源目录;不存在或复制异常只记日志。选中服务安装时,三个服务目录对应的exe均为必需项:缺exe、后台安装返回false或抛异常都会汇总,全部尝试结束后统一使安装失败 |
| SQL与业务账号 | 新装MySQL走初始化;其它勾选升级时由插件MySqlServiceManager委托Engine的MySqlDatabaseMaintenanceService.ResetDatabaseFromSqlFileAsync。同名源库和目标库都尚未创建时按新安装直接初始化,不尝试备份不存在的库;跨库更新缺少源库时仍停止,避免跳过旧数据。安装先要求找到color_vision_all.sql,数据库步骤成功后更新业务账号授权;明确失败中止后续配置/启动 |
| 配置与启动 | 数据库步骤后才ApplyDatabaseName、ApplyConfigAndRefreshAfterInstall。桌面端当前连接直接更新为业务账号并持久化,安装维护的root凭据由MySqlServiceConfig独立保存。有服务/MySQL/MQTT安装工作便自动调用启动,不存在独立可选启动开关;MySQL、MQTT和已安装的三个业务服务会分别尝试启动,返回false或抛异常均汇总,任一必需服务失败都使安装失败 |
MySQL ZIP安装位置与服务根同级,默认业务用户cv。MySqlServiceHelper 将带UTF-8 BOM的SQL按UTF-8读取,其余先严格UTF-8解码、失败回退GB18030,再向mysql.exe传UTF-8。Engine重置与资源保留负责保留表、字典依赖和SQL失败语义,不是整库或全部结果无损迁移。安装器要求SQL存在,而直接调用部分MySQL helper找不到SQL时会记录跳过并返回true,二者成功判据不同。
重置 MySQL root 密码前会等待 mysqld 进程退出。若进程退出超时,安装日志会列出仍运行的进程 ID,供操作员确认应停止的实例。
服务管理器将数据库配置写入服务目录的 cfg/MySql.config,将与桌面端共用的 MQTT 和注册中心默认参数写入现有的 cfg/MQTT.config 和 cfg/WinService.config。注册中心启动时以数据库监控列表为准并回写本地文件,因此常规配置同步将 MySQL,CVMainService_x64,CVMainService_dev 同步到默认注册中心 RC_local 对应的 t_scgd_sys_config_monitor 记录和本地 Monitor.Services,缺少本地键时补齐。数据库缺少记录或匹配多条记录会使同步失败。其它已存在的受管理配置写异常也可传播到安装编排、阻止后续启动,缺少配置文件时跳过该文件。
服务管理器的 CVWindowsService 页在“注册中心服务”的“更多操作”菜单中提供“移除归档服务检测”,用于旧部署仍按 Monitor.Services 反复尝试启动 CVArchService 的情况。ServiceManagerViewModel.Monitoring.cs 优先从已注册的注册中心程序路径定位 cfg/WinService.config,未注册时回退到安装根目录。RegistrationCenterMonitorConfiguration 从默认注册中心对应的数据库列表中移除归档项并同步到本地文件,保留其它监控服务及检测周期。文件中的非空 NodeName 必须与默认注册中心名称一致。缺文件、缺监控记录或匹配多个记录均报错。
从仍使用可编辑 RC 配置的版本升级时,需同步更新已安装的 Windows 服务管理插件。旧插件依赖主程序原有的 RC 配置类型。
点击后先确认运行状态变化:原来运行的注册中心通过 ServiceHost 停止,保存后恢复;原来停止的保持停止。停止失败不会写配置。数据库更新使用事务,本地文件先以临时文件替换,数据库提交失败时尝试恢复原文件;普通写入失败不报告成功。这不是跨数据库和文件的崩溃原子事务,双重恢复失败会明确提示核对两处配置。保存失败仍尝试恢复原先运行的注册中心;保存成功但恢复启动失败会明确提示“配置已保存”和服务状态待处理。此操作不卸载归档服务、不删除归档库或数据,也不要求重装服务包;执行仍须具备数据库、目录写权限和兼容的后台代理。
ServiceManagerConfig.BaseLocation 是安装根,MySqlPort 默认3306;安装窗口的 InstallServiceChecked/InstallMySqlChecked/InstallMqttChecked 直接代理同名配置字段,初始缺省分别true/false/false。AutoUpdateDatabase 和所选包路径则是安装ViewModel自己的状态,不能把勾选项一律当作已保存配置或已完成动作。
窗口只有在所选安装阶段及必需服务安装/启动汇总均通过后才将进度设为“安装完成”,刷新组件状态后自动关闭安装窗口;任一必需服务失败会显示安装失败及失败服务列表,并保留窗口供查看日志和重试。该结果仍只覆盖编排收到的返回值,还须分别核对服务状态、版本、配置及数据库结果;日志、progress=100、窗口关闭或某次ServiceHost成功均不替代整条安装验收。
插件MySQL页另有独立入口,由 ServiceManagerViewModel.MySql.cs 编排:RunSqlScriptAsync 调用 ExecuteSqlFile,遇到 color_vision_all.sql 会进入同源/目标库的Engine资源保留更新,之后只记录结果并刷新状态,不同步服务配置;专用“重置数据库”要求root密码、找到非空安装SQL并确认主机与目标库,再清除目标库、导入安装SQL,确认目标库已创建关键资源表后才报告重建成功。它不备份或回写旧流程、模板和资源;若导入或验证失败,数据库可能已清除或部分写入,日志会说明阶段。成功后同步受管理配置;该同步失败会单独提示,不把数据库重建当作整条操作完成。同步成功后先询问是否通过ServiceHost重启注册中心服务,等待结果后再独立询问是否重启ColorVision;服务重启失败会提示实际状态待核对,软件重启仅在用户选择后启动新进程 -r,创建成功才关闭当前应用。RunSqlScriptAsync 不会触发这两个提示。插件 RestoreDatabase 使用业务账号导入SQL,再调用Engine的流程节点标识更新;后一步失败时日志明确SQL已导入。节点更新规则及保留资源回写后的处理见MySQL恢复。
备份和恢复不等于自动回滚
安装窗口提供数据库“立即备份”和“恢复备份”手动操作。数据库备份默认写入“我的文档/ColorVision/Backup”,使用当前配置的数据库;MySQL 未运行时只记录日志并跳过。文件存在或完成日志不是恢复演练证明。数据库更新时的资源保留与回写由Engine重置与资源保留定义。
服务包更新前检测到已有 CVArchService 时,通过 ServiceHost 停止并卸载,卸载失败或仍被系统占用时停止更新。它仅作为旧部署退役清理保留;安装成功及失败路径均不重新注册或恢复该服务,启动时的缺失服务补装也只处理注册中心与 x64/dev 主服务。ServiceHost 对 CVArchService 仅开放卸载,不开放安装、启动或重启。卸载服务不会删除历史归档数据库或归档数据。
构建、发布与验证
插件构建、.cvxp上传和CVWindowsService服务ZIP发布是不同动作。以下从仓库根目录运行。本地构建写构建/HostCopy产物,不执行安装器:
dotnet build .\Plugins\WindowsServicePlugin\WindowsServicePlugin.csproj -c Release -p:Platform=x64仅在明确授权发布插件时执行下面的wrapper;它会构建、上传并清理本地.cvxp,不是普通验证命令:
.\Scripts\package_plugin.bat WindowsServicePlugin在获授权的隔离 Windows 环境核对源回退、包识别与下载中断、服务安装及失败汇总、真实 SQL 迁移和备份恢复。
