从监控告警到现场处置：用 HTTP API、Modbus TCP 构建声光语音告警系统

在服务器监控、工业自动化和视频安防场景中，“发现异常”通常并不是最难的问题。Zabbix、云监控、SCADA、PLC、NVR 等系统都能产生告警，真正容易被忽略的是：告警能否及时进入值班人员的感知范围。

弹窗可能被其他窗口遮挡，短信可能延迟，邮件也很难保证被立即查看。对于机房、监控室、生产车间等需要快速响应的场所，更有效的做法是把软件告警转换成现场可感知的灯光、提示音和语音信息。

本文以博灵 Q 系列智能监控终端为例，讨论如何利用 HTTP API、Webhook、Modbus TCP、SNMP 和邮件监控，构建一套可落地的智能声光告警方案。

本文侧重系统架构和接口实践。产品能力、参数及接口应以实际设备版本和官方文档为准。

一、先明确需求：我们需要的不是“会响的灯”

传统声光报警器通常只能接收开关量信号，能够表示“发生了异常”，却很难说明异常来自哪台设备、哪个监控项以及严重程度。

一个更完整的语音通知终端，需要解决以下问题：

1. 接收不同来源的告警
   包括 HTTP Webhook、PLC、网络设备、监控平台、邮件和 SNMP Trap。

2. 区分告警等级
   例如严重告警显示红色，警告显示黄色，恢复通知显示绿色。

3. 播报动态内容
   不只是播放固定录音，而是通过 TTS 播报“核心数据库 CPU 使用率超过 90%”之类的完整信息。

4. 控制告警生命周期
   支持单次播报、周期提醒、无限循环、跳过当前告警和清空队列。

5. 降低系统改造成本
   已有平台最好只增加一个 Webhook 或脚本，不修改核心业务逻辑。

这也是网络报警灯逐步从简单执行器，演变为网络化告警终端的原因。

二、推荐的系统架构

一套典型的智能声光告警系统，可以分成四层：

┌─────────────────────────────────────────────┐
│ 告警源                                      │
│ Zabbix / 云监控 / SCADA / PLC / NVR / ERP   │
└───────────────────┬─────────────────────────┘
                    │
        HTTP / Webhook / Modbus TCP
        SNMP Trap / SMTP / 原生 TCP
                    │
                    ▼
┌─────────────────────────────────────────────┐
│ 告警适配层                                  │
│ 字段转换、级别映射、去重、限流、签名、路由  │
└───────────────────┬─────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│ 博灵 Q 系列智能监控终端                     │
│ 告警队列、通知组、LED 效果、TTS、提示音     │
└───────────────────┬─────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│ 现场响应                                    │
│ 声光提醒、语音播报、邮件通知、人工确认处置  │
└─────────────────────────────────────────────┘

其中，告警适配层非常重要。

如果监控平台已经支持自定义 Webhook，可以直接按照设备 API 的数据结构发送请求；如果平台的回调格式不能修改，则可以使用设备的自定义 API 功能，对 host、service、level 等字段进行映射。

例如：

{
  "host": "核心数据库服务器",
  "service": "CPU 使用率",
  "level": "1",
  "time": "2026-08-18 10:30:00"
}

可以配置为：

• level=1：红色灯光，播报“严重告警”；
• level=2：黄色灯光，播报“警告”；
• level=3：绿色灯光，播报“故障已恢复”。

最终合成的语音可以是：

核心数据库服务器，CPU 使用率发生严重告警，请值班人员处理。

这种字段映射方式适合对接云监控、工单系统、ERP、动力环境监测平台和现有运维系统。

三、通过 HTTP API 触发一次声光语音告警

Q 系列文档提供了单次告警接口：

POST http://<设备IP地址>/api/api/send_msg

调用前通常需要完成以下配置：

• 开启声光播报 API；
• 设置 API Key；
• 校准设备时间；
• 配置网络访问权限；
• 生产环境启用 API 签名鉴权；
• 根据现场需求设置通知组、音量和灯光效果。

下面给出一个经过简化的 Python 调用示例：

import hashlib
import json
import time

import requests

DEVICE_IP = "192.168.0.66"
API_KEY = "请替换为已修改的API Key"

def compact_json(value):
    return json.dumps(
        value,
        ensure_ascii=False,
        separators=(",", ":")
    )

def create_sign(payload, api_key):
    sign_params = dict(payload)
    sign_params["token"] = api_key

    sign_text = "".join(
        f"{key}{sign_params[key]}"
        for key in sorted(sign_params)
    )

    return hashlib.md5(sign_text.encode("utf-8")).hexdigest()

payload = {
    "led_style": "15",
    "color": compact_json({"1": ["#FF0000"]}),
    "led_flag": compact_json([0.03, 1]),
    "text": "核心数据库CPU使用率超过百分之九十，请立即检查",
    "tts_speed": "5",
    "repeat_count": "2",
    "time": str(int(time.time()))
}

payload["sign"] = create_sign(payload, API_KEY)

response = requests.post(
    f"http://{DEVICE_IP}/api/api/send_msg",
    data=payload,
    timeout=5
)

response.raise_for_status()
print(response.json())

这段脚本完成了三个动作：

1. 构造 LED、颜色和语音播报参数；
2. 按字段名排序并计算 MD5 签名；
3. 将请求发送到语音通知终端。

需要注意，设备文档要求请求时间与设备时间的误差控制在一定范围内。若频繁出现签名失败，应优先检查：

• 设备和调用端的系统时间；
• JSON 字符串的空格与序列化格式；
• 参与签名的字段是否与实际请求一致；
• API Key 是否正确；
• 参数值是否被框架自动转换。

生产环境中还应增加告警去重和限流。例如，同一主机的同一故障在一分钟内只推送一次，避免监控平台连续重试造成播报队列积压。

四、PLC 场景为什么更适合 Modbus TCP

工业现场中的 PLC、组态软件和部分边缘控制器不一定方便调用 HTTP API，但通常支持 Modbus TCP。

Q 系列文档提供两种 Modbus 对接方式。

1. 模板 ID 触发

先在设备管理界面配置语音模板和通知组，再由 PLC 向指定保持寄存器写入模板 ID。

例如，预先配置：

模板 ID：10
播报内容：二号生产线设备温度超过阈值，请检查
通知组：严重告警

PLC 只需写入模板编号，无须实时传输和编码中文文本。

文档中的逻辑地址 100 对应报文偏移 0x0063，可以使用功能码 0x06 写单个寄存器。这种方式实现简单，适合告警内容相对固定的生产线。

2. 多寄存器自定义播报

如果需要动态指定颜色、LED 效果和语音文本，可以使用功能码 0x10 写多个保持寄存器。

其数据大致包括：

• LED 样式；
• 一到四组颜色；
• 播报时长；
• 提示音编号；
• TTS 语速；
• 灯光样式参数；
• UTF-8 编码的播报文本。

这种方式更加灵活，但需要正确处理寄存器地址、字节序和文本编码。对于首次集成的项目，建议优先使用模板 ID；只有在告警内容必须动态变化时，再采用多寄存器方案。

五、没有监控平台，也能做轻量级主动监控

除了被动接收外部告警，Q 系列还可以主动监测部分基础设施状态。

根据文档，其主机监控能力包括：

• Ping 网络连通性；
• HTTP/HTTPS 可用性与关键词检查；
• TCP 端口探测；
• FTP/SFTP 服务检查；
• SNMP Get 数据采集；
• SNMP Trap 接收；
• 邮件内容监控。

例如，在小型机房中可以通过 SNMP Get 获取服务器 CPU 使用率。Windows和Linux常见的主机资源 OID 包括：

1.3.6.1.2.1.25.3.3.1.2.n  CPU 使用率
1.3.6.1.2.1.25.2.3.1.5.n  存储器总容量
1.3.6.1.2.1.25.2.3.1.6.n  存储器已使用容量

可以先使用 snmpwalk 确认实际索引：

snmpwalk -v 2c -c Public \
  192.168.0.210 \
  1.3.6.1.2.1.25.3.3.1.2

随后在终端中配置正常值范围。例如 CPU 使用率正常范围为 0～80，超过阈值后触发红色声光语音告警。

SNMP v2c 的团体字不应继续使用示例默认值。正式部署时建议采用 SNMP v3，或至少修改团体字并通过 ACL 限制访问来源。

六、三个值得落地的应用场景

场景一：数据中心与运维监控平台联动

监控平台检测到服务器、数据库或网络设备故障后，通过 Webhook 调用单次告警 API。

严重告警使用红色旋转灯效并播报完整故障信息；恢复事件显示绿色，并播报恢复结果。

它解决的不是“没有告警”，而是监控大屏信息过多、值班人员暂时离开座位时，关键告警不容易被及时感知的问题。

场景二：PLC 与生产线异常提醒

PLC 根据温度、压力、物料或设备状态触发业务逻辑，再通过 Modbus TCP 写入预设模板 ID。

与传统蜂鸣器相比，语音告警可以直接说明故障位置和处置要求，例如：

三号工位缺料，请补充物料。

这能减少操作人员判断告警含义的时间。

场景三：NVR 与视频监控室联动

部分 NVR 可以发送异常邮件。Q 系列可通过本地 SMTP 或 IMAP 收取邮件，再按照发件人、主题关键词和正文正则表达式提取内容。

当出现视频信号丢失、硬盘异常或移动侦测事件时，设备可以播报具体摄像头名称，适合已有邮件告警能力、但缺少开放 API 的视频监控系统。

七、生产部署不能忽略的细节

为了让网络报警灯真正成为可靠的告警节点，建议在上线前完成以下检查：

• 修改默认管理密码和 API Key；
• 启用 API 鉴权，限制调用源 IP；
• 将设备部署在独立 VLAN 或受控管理网段；
• 不要把设备 HTTP 管理端口直接暴露到公网；
• 跨网络调用优先使用 VPN、安全网关或受控云服务；
• 配置 NTP，避免时间偏差导致签名失败；
• 设置告警去重、限流和恢复通知；
• 为周期告警保存 cid，确保故障恢复后能够停止循环播报；
• 检查播报队列长度，避免告警风暴；
• 根据现场噪声测试音量、语速、提示音和灯光效果；
• 建立设备离线后的备用通知链路。

结语

智能声光告警的价值，不是简单地增加一种通知方式，而是把监控系统中的抽象事件，转化为现场人员可以立即看见、听见并理解的信息。

从接口设计来看，博灵 Q 系列同时覆盖 HTTP API、Webhook、自定义字段映射、Modbus TCP、原生 TCP、SNMP 和邮件监控，比较适合以下项目进行技术评估：

• 已有监控平台，需要补充现场语音告警；
• PLC 或组态软件需要输出动态声光信息；
• 小型机房希望获得轻量级主动监控；
• 视频监控系统只有邮件通知能力；
• 告警来源较多，需要统一接入一个现场通知终端。

对于新项目，建议优先采用 HTTP API 或 Modbus 模板方式完成最小可行验证，再逐步加入告警分级、去重、队列控制和恢复闭环。这样既能降低对接复杂度，也能让智能声光告警真正参与到故障处置流程中。
 

参考资料：

• 博灵 Q 系列产品介绍
• HTTP API 快速入门
• 单次告警 API
• Modbus TCP 对接说明
• 主机监控说明
• SNMP Get 监控案例