# 设备状态监控与异常告警系统

**Repository Path**: qrss_t/DSG

## Basic Information

- **Project Name**: 设备状态监控与异常告警系统
- **Description**: DeviceStatusGuardian 是一款面向工业环境的设备状态监控与异常告警系统。系统通过 OPC UA 协议实时采集工业设备数据，基于预设的业务规则进行异常判定，并通过多级告警提级机制确保关键异常能及时触达相关负责人。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-26
- **Last Updated**: 2026-01-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 设备报警系统

## README

## 1. 项目概述

### 1.1 项目背景
**DeviceStatusGuardian** 是面向工业现场的设备状态监控与异常告警系统。系统通过 OPC UA 协议实时采集设备数据，基于规则引擎识别异常，并借助多级通知与联动控制保障关键异常可被及时处理。

### 1.2 项目目标
- **多设备管理**: 支持多台 OPC UA 设备接入、分组与权限隔离。
- **实时监控**: 订阅式采集实现低延迟数据更新。
- **智能告警**: 防抖与告警抑制降低误报与告警风暴。
- **多级推送**: 规则化提级策略保障关键告警触达关键角色。
- **历史追溯**: 指标数据 CSV 持久化，告警日志与记录可查询追溯。

---

## 2. 项目结构与模块清单

### 2.1 目录结构概览
- **Common**: 通用工具与系统信息。
- **Controllers**: MVC 控制器与页面入口。
- **Data**: DbContext 与数据库初始化。
- **Hubs**: SignalR 实时通讯。
- **Interfaces**: 业务接口定义。
- **Models**: 领域模型与配置模型。
- **Services**: 业务服务与后台任务。
- **Views**: 前端 Razor 视图。
- **Properties**: 启动配置。
- **根目录文件**: Program.cs、appsettings.json、service-manager.bat、README-Service.md。

### 2.2 主要模块职责
#### 2.2.1 设备与采集模块
- **Services/Device**: OPC UA 客户端、会话与订阅管理、设备生命周期管理。
- **Controllers/OpcUaDeviceController**: 设备配置与节点浏览入口。
- **Models/Device/OpcUa**: 连接、订阅、节点与状态模型。

#### 2.2.2 告警模块
- **Services/Alarm**: 告警规则评估、状态流转与归档。
- **Controllers/AlarmController**、**AlarmRuleController**: 告警监控与规则配置。
- **Models/Alarm**: 告警规则、告警记录与级别枚举。

#### 2.2.3 通知与模板模块
- **Services/Notification**: 通道管理、模板渲染与发送。
- **Services/Notification/Channels**: 内置通道（SignalR）。
- **Services/Notification/Plugins**: 通道插件加载与注册。
- **Controllers/ChannelController**: 通道配置、模板管理与测试发送。
- **Models/Notification**: 通道配置、模板与接收人模型。

#### 2.2.4 联动控制模块
- **Services/Background/LinkageControlBackgroundService**: 联动任务执行。
- **Controllers/LinkageRuleController**: 联动规则配置与维护。
- **Models/Linkage**: 联动条件与规则模型。

#### 2.2.5 身份与权限模块
- **Services/Identity**: 登录认证、RBAC 权限管理。
- **Controllers/AuthController**、**UserController**: 登录、注册与用户管理。
- **Models/Identity**: 用户、角色、权限与联系方式模型。

#### 2.2.6 系统配置与运维模块
- **Services/System**: 系统健康指标采集。
- **Services/Upgrade**: 升级包校验与清理。
- **Controllers/SystemConfigController**: 系统配置与维护入口。
- **Models/System**: 系统设置、健康指标与许可证模型。

#### 2.2.7 数据存储模块
- **Services/Storage**: CSV 与 JSONL 存储实现。
- **Models/Storage**: 存储选项与查询模型。
- **Data/DeviceStatusDbContext**: 数据表与迁移管理。

#### 2.2.8 后台任务模块
- **Services/Background**: 告警恢复、提级、归档、防抖与状态轮询。

---

## 3. 工作流程

### 3.1 采集与告警流程
1. 设备接入后创建 OPC UA 会话与订阅。
2. 数据变化通过订阅回调进入缓存与规则评估。
3. 告警引擎应用防抖规则，生成告警记录。
4. 告警进入活动状态并推送通知。

### 3.2 告警提级与恢复流程
1. 告警进入活动状态后按配置周期推送。
2. 达到提级阈值后升级为 Escalated 通知高级用户。
3. 数据恢复满足恢复防抖条件后自动恢复告警。
4. 用户可进行确认操作，停止后续提级推送。

### 3.3 通知流程
1. 通道配置与模板在系统设置中维护。
2. 通知管理器渲染模板并选择通道发送。
3. 通道日志记录到 JSONL 存储，便于追溯。

### 3.4 联动控制流程
1. 告警触发后匹配联动规则。
2. 联动后台服务执行 OPC UA 写入操作。

### 3.5 身份与权限流程
1. 登录通过 Cookie 认证。
2. RBAC 权限控制控制器访问与设备范围。

---

## 4. 系统架构

### 4.1 技术栈
- **框架**: .NET 10.0, ASP.NET Core MVC。
- **协议**: OPC UA（OPCFoundation.NetStandard.Opc.Ua）。
- **数据库**: EF Core + SQLite（默认）。
- **实时通信**: SignalR。
- **后台任务**: BackgroundService。

### 4.2 架构图
```mermaid
graph TD
    User[用户/管理员] -->|HTTP/SignalR| Web[ASP.NET Core MVC]
    Web --> Controllers
    Controllers --> Services[业务服务层]

    subgraph Services
        DeviceSvc[设备与连接管理]
        AlarmSvc[告警引擎]
        NotifySvc[通知中心]
        StorageSvc[数据存储]
        RbacSvc[权限管理]
    end

    subgraph BackgroundTasks
        StatusPoller[连接状态轮询]
        EscalationWorker[告警提级]
        RecoveryWorker[告警恢复]
        LinkageWorker[联动控制]
        ArchiveWorker[告警归档]
        DebounceWorker[防抖处理]
    end

    Services --> DB[(SQLite/SQL Server)]
    Services --> CSV[(CSV Metrics Store)]
    Services --> LOG[(JSONL Logs)]
    Services --> OPCUA[OPC UA Servers]
```

---

## 5. 核心模块详解

### 5.1 设备与 OPC UA 采集
- 每台设备独立会话与订阅，隔离故障影响。
- 按顺序释放订阅与会话，避免服务端句柄泄露。
- 断线自动重连，保障采集稳定性。

### 5.2 告警引擎
- 规则支持比较运算符与阈值判断。
- 防抖机制避免抖动误报。
- 状态流转：Normal → Active → Acknowledged → Resolved。

### 5.3 通知系统
- 通道注册表统一管理内置与插件通道。
- 模板服务渲染变量与格式。
- 发送日志落地到 JSONL 文件，支持查询。

### 5.4 数据持久化
- **关系数据**: 设备、规则、用户与告警记录。
- **指标数据**: CsvDataStore 按天分片保存。
- **日志数据**: JSONL 文件存储告警与通知日志。

### 5.5 升级与维护
- 更新包签名校验支持单文件上传验证。
- 启动时清理遗留临时文件。

---

## 6. 配置说明

### 6.1 基础配置
- `appsettings.json` 主要配置项：
  - `ConnectionStrings.DefaultConnection`: SQLite 数据库路径或 SQL Server 连接字符串。
  - `SignalR.ClientAccessKey`: SignalR 客户端访问密钥。
  - `Logging`: 日志等级与格式。

### 6.2 端口与运行环境
- 开发环境默认地址来自 `Properties/launchSettings.json`。
- 发布环境可通过 `Kestrel` 配置调整监听地址与端口。

---

## 7. 安装与部署

### 7.1 环境准备
- 安装 .NET 10.0 Runtime 或 SDK。
- Windows 场景建议以管理员权限操作服务脚本。

### 7.2 本地运行
```bash
cd DeviceStatusGuardian
dotnet run
```

### 7.3 发布部署
```bash
dotnet publish -c Release -o publish
```

### 7.4 Windows 服务部署
- 使用 `service-manager.bat` 管理服务。
- 典型命令：
```cmd
service-manager.bat install
service-manager.bat start
service-manager.bat stop
service-manager.bat status
service-manager.bat uninstall
```

### 7.5 启动初始化
- 数据库文件不存在时自动创建。
- 首次运行自动创建管理员账号：
  - 账号：999
  - 密码：999
  - 角色：Administrator

---

## 8. 操作指导

### 8.1 登录与用户
1. 使用默认账号登录后修改密码。
2. 在个人资料中配置联系方式用于接收通知。

### 8.2 设备与订阅管理
1. 添加设备并配置 OPC UA 连接信息。
2. 浏览节点并选择订阅点位。
3. 在订阅管理中启停采集任务。

### 8.3 告警规则与监控
1. 创建告警规则并设定阈值与防抖。
2. 在告警监控页查看活动告警。
3. 处理并确认告警，查看历史记录。

### 8.4 通知通道配置
1. 在系统设置配置通道参数。
2. 配置模板并执行测试发送。
3. 查看通道日志与发送记录。

### 8.5 联动控制
1. 配置联动规则与触发条件。
2. 触发告警后自动写入目标节点。

### 8.6 系统配置
1. 设置告警推送周期与提级阈值。
2. 查看系统健康指标与运行状态。

---

## 9. 运维与排障

### 9.1 日志与数据目录
- 业务日志：`Logs/`
- 通知通道日志：`Logs/NotificationChannel/`
- 告警归档日志：`Logs/AlarmArchive/`
- 告警通知日志：`Logs/AlarmNotification/`

### 9.2 常见问题
- 设备已连接但数据不更新：检查订阅是否启用与采样间隔设置。
- 高级告警未提级：检查告警推送阈值与用户角色。
- 端口冲突：在 `appsettings.json` 的 `Kestrel` 节点配置端口。

---

## 10. 相关工具与扩展

### 10.1 插件打包工具
- **PluginPackTool**: 生成通知通道插件包并计算完整性清单。

### 10.2 示例插件
- **SamplePlugins/NotificationChannels.WxPusherPlugin**
- **SamplePlugins/NotificationChannels.NapCatPlugin**