南向通道指标监控

工业边缘网关 / 多协议采集平台（Modbus / BACnet / OPCUA 等） @edge-gateway\ui\src\views\ChannelList.vue 前端 UI 不应该只是“在线/离线”，而应该具备：

通信可观测性（Observability）

质量评分（Quality Index）

实时链路状态

设备健康度

通道级 & 设备级分层监控

运维诊断能力

下面我给你一个专家级设计方案，可直接用于产品规划文档。

一、总体设计原则 1️⃣ 分层展示模型

必须严格分为：

南向通道 (Channel) ↓ 设备 (Device) ↓ 点位 (Point)

不要混淆。

通道质量 ≠ 设备质量

设备异常 ≠ 通道异常

二、通道级（Channel）监控指标设计

这是 Modbus TCP / RTU 的核心。

🔷 1. 基础连接信息 UI显示字段 指标 说明 通道状态 Excellent(优秀) / Good (良好)/ Unstable(一般) / Offline(离线) 物理类型 TCP / RTU 本地 IP 本机地址 本地端口 实际绑定端口 远端 IP 设备 IP 远端端口 设备端口 连接模式 Client / Server 当前连接时长 从最后一次成功建立连接开始 最后断开时间 便于排查 当前 Socket FD 可选（调试模式） 🔷 2. 通信质量指标（实时统计） 必须做滑动窗口统计（例如最近 1 分钟） 指标 含义 成功率 success / total 超时次数 Timeout Count CRC 错误次数 CRC Error 异常响应次数 Exception Code 平均响应时间 Avg RTT 最大响应时间 Max RTT 当前重试次数 当前周期 丢包率 (超时+CRC)/总数 🔷 3. 通道质量评分算法（核心）

推荐你用 100 分制算法：

score = 100 score -= timeoutRate * 40 score -= crcRate * 20 score -= retryRate * 20 score -= rttPenalty

映射为：

分数 等级 ≥ 90 Excellent ≥ 75 Good ≥ 60 Unstable < 60 Poor 连续失败 Offline

这个评分应该：

每 5 秒刷新

作为 Dashboard 主指标

🔷 4. 高级指标（专业模式）

当前并发请求数

请求队列长度

最近 10 次异常详情

最近一次异常码

串口帧间隔统计（RTU 专用）

TCP 重连次数

三、设备级监控指标设计

设备层面必须独立裁决。

1️⃣ 基础信息 指标 说明 设备在线状态 当前调度周期 上次采集时间 连续失败次数 降级状态 是否恢复中 2️⃣ 采集质量 指标 说明 点位成功率 平均采集耗时 异常点位数量 无效值数量 Null值比例 3️⃣ 设备健康度算法

例如：

health = 100 health -= 连续失败 * 10 health -= 异常点位比例 * 30 health -= 超时比例 * 30

映射：

分数 状态 ≥90 Healthy ≥70 Warning ≥50 Risk <50 Critical 四、点位级监控指标

这个层级非常重要。

必须支持：

最近更新时间

质量码（Good / Bad / Uncertain）

原始值

解析值

字节序

原始寄存器数据

例如：

Raw: 00 01 00 64 Parsed: 100 Type: FLOAT32 Endian: CDAB Quality: Good

这在调试 Modbus 字节序问题时极其重要。

五、UI 页面设计方案 1️⃣ 通道详情页（专家视图）

顶部：通道总览卡片

状态灯（颜色）

质量评分（圆形进度条）

当前连接时长

成功率

中部：

左侧：连接信息

本地 IP/端口

远端 IP/端口

物理链路

串口参数

右侧：质量统计图

成功率趋势图（折线图）

RTT 曲线

错误类型饼图

底部：

最近 50 条通信日志（可展开原始报文）

2️⃣ 设备详情页

设备健康度评分

连续失败次数

当前调度周期

降级状态

点位异常统计图

3️⃣ 点位详情页

原始寄存器值

字节序转换演示

数据类型切换预览

解析前后对比

六、必须实现的后台指标接口

建议新增：

GET /api/channels/{id}/metrics GET /api/devices/{id}/metrics GET /api/points/{id}/debug

返回结构必须包含：

{ “qualityScore”: 92, “successRate”: 0.99, “timeoutCount”: 3, “crcError”: 0, “avgRtt”: 12.5, “maxRtt”: 45, “reconnectCount”: 1 } 七、与你当前项目强关联建议

你之前提到：

采集通道质量裁决

双层裁决融合

10ms 节点间隔防串流

通道与设备状态隔离

UI 层必须完全体现：

通道质量不影响设备在线显示

设备异常但通道 Excellent 的情况必须能看到

降级设备但通道正常的情况必须能看到

否则前端就掩盖了你的架构优势。

最终成熟产品的效果

成熟工业平台应该能做到：

一眼看到哪个通道抖动

一眼看到哪个设备异常

一键展开看到原始报文

明确看到质量评分变化曲线

明确看到连接时长与重连历史

八、接口实现文档

1. 通道监控指标接口

接口地址： GET /api/channels/{channelId}/metrics

功能描述： 获取通道的详细监控指标

返回结构：

{
  "qualityScore": 92,           // 质量评分
  "protocol": "BACnet",         // 协议类型
  "successRate": 0.99,          // 成功率
  "timeoutCount": 3,            // 超时次数
  "crcError": 0,                // CRC错误次数
  "crcErrorRate": 0.0,          // CRC错误率
  "retryRate": 0.0,             // 重试率
  "exceptionCode": "",          // 异常码
  "avgRtt": 12.5,               // 平均响应时间(ms)
  "maxRtt": 45,                 // 最大响应时间(ms)
  "minRtt": 5,                  // 最小响应时间(ms)
  "totalRequests": 100,          // 总请求数
  "successCount": 99,            // 成功请求数
  "failureCount": 1,             // 失败请求数
  "packetLoss": 0.01,            // 丢包率
  "reconnectCount": 1,           // 重连次数
  "connectionSeconds": 3600,     // 连接时长(秒)
  "localAddr": "192.168.1.100:502",  // 本地地址
  "remoteAddr": "192.168.1.200:502", // 远端地址
  "lastDisconnectTime": "2026-04-02T10:00:00Z", // 最后断开时间
  "trend": [95, 94, 93, 92, 91], // 趋势数据
  "recentErrors": [              // 最近错误
    {
      "time": "2026-04-02T09:59:00Z",
      "type": "timeout",
      "code": "0x00",
      "message": "Connection timeout"
    }
  ],
  "timestamp": "2026-04-02T10:00:00Z" // 时间戳
}

2. 设备监控指标接口

接口地址： GET /api/devices/{channelId}/{deviceId}/metrics

功能描述： 获取设备的详细监控指标

返回结构：

{
  "state": 0,                    // 设备状态(0:在线, 1:离线, 2:禁用)
  "healthScore": 85,             // 健康度评分
  "successRate": 0.85,           // 点位成功率
  "avgCollectionTime": 15.2,     // 平均采集耗时(ms)
  "exceptionCount": 3,           // 异常点位数量
  "invalidValueCount": 2,        // 无效值数量
  "nullValueRate": 0.05,         // Null值比例
  "consecutiveFailures": 0,      // 连续失败次数
  "currentCycle": 5000,          // 当前调度周期(ms)
  "lastCollectionTime": "2026-04-02T10:00:00Z", // 上次采集时间
  "timestamp": "2026-04-02T10:00:00Z" // 时间戳
}

3. 点位调试信息接口

接口地址： GET /api/points/{pointId}/debug

功能描述： 获取点位的原始数据和解析信息

返回结构：

{
  "pointId": "point-001",        // 点位ID
  "lastUpdateTime": "2026-04-02T10:00:00Z", // 最近更新时间
  "quality": "Good",             // 质量码(Good/Bad/Uncertain)
  "rawValue": "00 01 00 64",     // 原始字节数据
  "parsedValue": 100,            // 解析后的值
  "dataType": "FLOAT32",         // 数据类型
  "endian": "CDAB",              // 字节序
  "timestamp": "2026-04-02T10:00:00Z" // 时间戳
}

九、实现细节

1. 指标收集器架构

2. 数据流转

  1. 指标记录：驱动通过 RecordChannelRequest、RecordChannelError 等函数记录指标
  2. 指标获取：API 接口通过 GetChannelMetrics、GetDeviceMetrics 获取指标
  3. 数据补充：从驱动获取实时连接信息和详细指标
  4. 响应返回：将完整指标数据返回给前端

3. 前端集成

4. 技术特点

十、未来规划

  1. 历史数据存储：实现指标历史数据存储，支持趋势分析
  2. 告警机制：基于指标阈值的告警系统
  3. 可视化增强：添加更多图表和趋势分析功能
  4. 多协议支持：扩展对更多工业协议的指标采集
  5. 性能优化：优化指标收集和存储的性能

十一、前端实现要点

  1. 响应式设计：适配不同屏幕尺寸
  2. 实时更新：支持WebSocket实时更新指标
  3. 数据可视化：使用图表展示趋势数据
  4. 错误处理：优雅处理接口错误和数据缺失
  5. 用户体验：提供清晰的视觉反馈和操作指引

十二、后端实现要点

  1. 性能优化：指标收集和计算的性能优化
  2. 内存管理：合理管理指标数据的内存使用
  3. 并发安全：确保多线程环境下的指标收集安全
  4. 可扩展性：支持自定义指标和协议扩展
  5. 监控自身：监控指标收集系统自身的健康状态