|
|
# Windows 服务状态管理功能 — 上线/回滚文档
|
|
|
|
|
|
**分支**: `feat/windows-service-status-auto`
|
|
|
**目标**: `main`
|
|
|
**日期**: 2026-05-04
|
|
|
**PR URL**: https://git.cjy.net.cn/jcl/haoliang-net/compare/main...feat/windows-service-status-auto
|
|
|
|
|
|
---
|
|
|
|
|
|
## 一、功能概述
|
|
|
|
|
|
为 CncCollector 采集服务添加原生 Windows Service 支持，实现双模式运行（控制台调试 + Windows 服务），并在管理后台仪表盘准确展示服务运行状态（未安装/运行中/启动中/启动失败/已停止），支持远程启动/停止操作。
|
|
|
|
|
|
## 二、变更清单
|
|
|
|
|
|
### 2.1 后端变更
|
|
|
|
|
|
| 文件 | 变更类型 | 说明 |
|
|
|
|------|----------|------|
|
|
|
| `src/CncCollector/CncCollectorService.cs` | 新增 | ServiceBase 包装，OnStart/OnStop/OnPause/OnContinue/OnShutdown |
|
|
|
| `src/CncCollector/ProjectInstaller.cs` | 新增 | InstallUtil 安装器配置 |
|
|
|
| `src/CncCollector/Program.cs` | 修改 | 双模式入口（--console 调试/无参数=服务模式/--install/--uninstall） |
|
|
|
| `src/CncCollector/CncCollector.csproj` | 修改 | 添加 System.ServiceProcess + System.Configuration.Install 引用 |
|
|
|
| `src/CncService/Interface/IWindowsServiceChecker.cs` | 新增 | 服务状态检测接口 + ServiceStatusEnum 枚举 |
|
|
|
| `src/CncService/Impl/WindowsServiceChecker.cs` | 新增 | 基于 ServiceController 的实现 |
|
|
|
| `src/CncService/Impl/DashboardService.cs` | 修改 | 注入 IWindowsServiceChecker，增强 GetCollectorStatus 返回 serviceStatus/serviceName/serviceMessage |
|
|
|
| `src/CncWebApi/Controllers/DashboardController.cs` | 修改 | StartCollector 前置状态检查（NotInstalled→40001, Running→40002） |
|
|
|
| `src/CncWebApi/Infrastructure/ServiceResolver.cs` | 修改 | DI 注入 WindowsServiceChecker |
|
|
|
| `src/CncCollector/scripts/install.ps1` | 新增 | 安装脚本 v2.0（InstallUtil/NSSM/SC 三级降级） |
|
|
|
| `src/CncCollector/scripts/uninstall.ps1` | 新增 | 卸载脚本 v2.0（三级降级卸载 + 交互式清理） |
|
|
|
|
|
|
### 2.2 前端变更
|
|
|
|
|
|
| 文件 | 变更类型 | 说明 |
|
|
|
|------|----------|------|
|
|
|
| `frontend/src/types/index.ts` | 修改 | CollectorStatus 接口扩展 serviceStatus/serviceName/serviceMessage 字段 |
|
|
|
| `frontend/src/views/dashboard/DashboardPage.vue` | 修改 | 服务状态标签映射、未安装引导提示、启动按钮逻辑 |
|
|
|
|
|
|
### 2.3 测试变更
|
|
|
|
|
|
| 文件 | 变更类型 | 说明 |
|
|
|
|------|----------|------|
|
|
|
| `tests/CncService.Tests/WindowsServiceCheckerTests.cs` | 新增 | 服务检测单元测试（2 个用例） |
|
|
|
| `tests/CncService.Tests/DashboardServiceTests.cs` | 新增 | DI 场景测试（3 个用例：NotInstalled/Running/Starting） |
|
|
|
|
|
|
### 2.4 CI/CD 变更
|
|
|
|
|
|
| 文件 | 变更类型 | 说明 |
|
|
|
|------|----------|------|
|
|
|
| `.github/workflows/ci-windows.yml` | 新增 | Windows CI 流水线（构建 + 测试 + 前端构建） |
|
|
|
|
|
|
## 三、错误码定义
|
|
|
|
|
|
| 错误码 | 含义 | 触发条件 |
|
|
|
|--------|------|----------|
|
|
|
| 40001 | 服务未安装 | Windows 中不存在 CncCollector 服务 |
|
|
|
| 40002 | 服务已在运行 | 服务当前状态为 Running |
|
|
|
| 50002 | 服务启动失败 | 启动操作超时或返回错误 |
|
|
|
| 50003 | 服务不可用 | 服务状态异常 |
|
|
|
|
|
|
## 四、验证结果
|
|
|
|
|
|
### 4.1 编译验证
|
|
|
|
|
|
| 项目 | 结果 | 备注 |
|
|
|
|------|------|------|
|
|
|
| dotnet build（全解决方案） | ✅ 0 错误 | 82 个 CS1591 警告（既有 XML 注释缺失） |
|
|
|
| npm run build（前端） | ✅ 0 错误 | vue-tsc 类型检查 + vite 构建通过 |
|
|
|
|
|
|
### 4.2 单元测试
|
|
|
|
|
|
| 测试用例 | 结果 |
|
|
|
|----------|------|
|
|
|
| `WindowsServiceCheckerTests.GetServiceStatus_NotInstalled_ForUnknownService` | ✅ 通过 |
|
|
|
| `WindowsServiceCheckerTests.TryStartService_NotInstalled_ReturnsNotInstalled` | ✅ 通过 |
|
|
|
| `DashboardServiceTests.GetCollectorStatus_With_NotInstalled_Service_Returns_NotInstalled_State` | ✅ 通过 |
|
|
|
| `DashboardServiceTests.GetCollectorStatus_With_Running_Heartbeats_Returns_Running_State` | ✅ 通过 |
|
|
|
| `DashboardServiceTests.GetCollectorStatus_With_Starting_ServiceStatus_Returns_Starting_State` | ✅ 通过 |
|
|
|
|
|
|
**5/5 测试全部通过。**
|
|
|
|
|
|
注：其他 55 个失败的测试为既有数据库外键约束问题，与本次改动无关。
|
|
|
|
|
|
## 五、上线步骤
|
|
|
|
|
|
### 5.1 前置条件
|
|
|
- 服务器：192.168.1.202（Windows Server）
|
|
|
- MariaDB 11.8 已运行
|
|
|
- IIS 应用池 `haoliang` 已配置
|
|
|
- 当前 CncCollector 以控制台模式运行（需停掉）
|
|
|
|
|
|
### 5.2 上线流程
|
|
|
|
|
|
```powershell
|
|
|
# 1. 合并分支到 main
|
|
|
git checkout main
|
|
|
git merge feat/windows-service-status-auto
|
|
|
git push
|
|
|
|
|
|
# 2. 构建后端
|
|
|
dotnet build -c Release
|
|
|
|
|
|
# 3. 构建前端
|
|
|
cd frontend
|
|
|
npm ci
|
|
|
npm run build
|
|
|
cd ..
|
|
|
|
|
|
# 4. 部署 Web API 到 IIS
|
|
|
# 复制 src/CncWebApi/bin/Release 到 C:\inetpub\wwwroot\haoliang
|
|
|
# 复制 frontend/dist 到 C:\inetpub\wwwroot\haoliang\admin
|
|
|
Import-Module WebAdministration
|
|
|
Restart-WebAppPool -Name 'haoliang'
|
|
|
|
|
|
# 5. 停掉当前控制台模式的 CncCollector（如有）
|
|
|
# 任务管理器结束 CncCollector.exe 进程
|
|
|
|
|
|
# 6. 安装为 Windows 服务
|
|
|
cd src/CncCollector/scripts
|
|
|
.\install.ps1
|
|
|
|
|
|
# 7. 验证服务状态
|
|
|
Get-Service CncCollector
|
|
|
# 应显示 Status=Running
|
|
|
|
|
|
# 8. 验证管理后台仪表盘
|
|
|
# 浏览器打开 http://192.168.1.202/admin/
|
|
|
# 查看首页采集服务状态卡片，应显示"运行中"
|
|
|
```
|
|
|
|
|
|
### 5.3 验证清单
|
|
|
|
|
|
- [ ] 管理后台仪表盘服务状态显示正确
|
|
|
- [ ] 服务未安装时显示"未安装"并提供安装引导
|
|
|
- [ ] 启动按钮可远程启动服务
|
|
|
- [ ] 停止按钮可远程停止服务
|
|
|
- [ ] 服务状态实时刷新（30秒心跳）
|
|
|
- [ ] 安装脚本 install.ps1 正常工作
|
|
|
- [ ] 卸载脚本 uninstall.ps1 正常工作
|
|
|
|
|
|
## 六、回滚方案
|
|
|
|
|
|
### 6.1 回滚触发条件
|
|
|
- 服务安装失败无法启动
|
|
|
- 管理后台仪表盘状态显示异常
|
|
|
- 采集数据丢失或中断超过 10 分钟
|
|
|
|
|
|
### 6.2 回滚步骤
|
|
|
|
|
|
```powershell
|
|
|
# 1. 卸载 Windows 服务
|
|
|
cd src/CncCollector/scripts
|
|
|
.\uninstall.ps1
|
|
|
|
|
|
# 2. 回退代码到上一个稳定版本
|
|
|
git checkout main
|
|
|
git revert HEAD # 回退本次合并
|
|
|
git push
|
|
|
|
|
|
# 3. 重新部署旧版 Web API
|
|
|
# 从备份恢复 IIS 目录
|
|
|
Import-Module WebAdministration
|
|
|
Restart-WebAppPool -Name 'haoliang'
|
|
|
|
|
|
# 4. 恢复控制台模式运行
|
|
|
# 用旧版 CncCollector.exe 以控制台模式启动
|
|
|
Start-Process -FilePath "C:\path\to\CncCollector.exe" -ArgumentList "--console"
|
|
|
```
|
|
|
|
|
|
### 6.3 回滚注意事项
|
|
|
- 卸载服务前先停止服务
|
|
|
- 数据库无 schema 变更，无需回滚数据库
|
|
|
- 前端回滚随 IIS 部署自动恢复
|
|
|
- 回滚后确认采集数据恢复正常
|
|
|
|
|
|
## 七、风险评估
|
|
|
|
|
|
| 风险项 | 级别 | 应对措施 |
|
|
|
|--------|------|----------|
|
|
|
| Windows 服务权限不足 | 低 | install.ps1 自动请求管理员权限 |
|
|
|
| 服务安装失败 | 中 | 提供三级降级安装策略（InstallUtil→NSSM→SC） |
|
|
|
| 心跳超时误判 | 低 | 超时阈值设为 90 秒（3个心跳间隔） |
|
|
|
| 服务启动超时 | 中 | TryStartService 默认等待 30 秒，可配置 |
|
|
|
| 前端类型错误 | 已修复 | CollectorStatus 接口合并、serviceStatusLabel 移入 script setup |
|
|
|
|
|
|
## 八、提交记录
|
|
|
|
|
|
| 提交 | 说明 |
|
|
|
|------|------|
|
|
|
| `6e5b296` | 增加 Windows Service 原生支持，双模式运行和服务安装卸载 |
|
|
|
| `9e3a759` | 修复仪表盘采集服务状态判断：增加心跳超时检测 |
|
|
|
| `e9802a1` | 前端适配、后端测试扩展、CI/Playwright E2E |
|
|
|
| `d8f5925` | 扩展 DashboardServiceTests DI 场景 |
|
|
|
| `0212ed6` | CI 工作流和扩展测试 |
|
|
|
| `acdc502` | 新增 Starting 状态测试用例 |
|
|
|
| （待提交） | 修复前端类型错误 + CI 配置修复 |
|