SNMP 告警端点 v0.37.0+ 监听 UDP 162 端口，被动接收网络/设施设备（交换机/路由器/UPS/传感器等）主动推送的 SNMP Trap/Inform 告警，转成消息流入规则链处理。无需轮询，适合设备告警场景（如链路故障、UPS 低电、温度超限等），与主动采集组件 x/snmpRead 互补。

提示

1. 该组件是扩展组件，需要引入额外的扩展库：rulego-components-iot (opens new window)

Type

endpoint/snmp

配置

字段	类型	说明	默认值
server	string	监听地址（含端口），例如 0.0.0.0:162	0.0.0.0:162
version	string	SNMP 版本（Trap 解码用），可选值：v1/v2c/v3	v2c
community	string	community 字符串（v1/v2c Trap 校验使用）	public

注意

端口 162 是特权端口（<1024）。

• Linux：需以 root 运行，或为进程授予绑定特权端口的能力：sudo setcap cap_net_bind_service=+ep ./your_app。
• Windows：通常需以管理员身份运行。 如不便授权，可监听非特权端口（如 0.0.0.0:1162），但需相应调整设备发送 Trap 的目的端口。

接收消息格式

每收到一个 Trap，组件将其转为 RuleMsg 流入规则链，msg.type 为 SNMP_TRAP，dataType 为 JSON，msg.Data 为如下格式的 JSON 字符串：

{
  "from": "192.168.1.10:54321",
  "version": "v2c",
  "community": "public",
  "timestamp": 12345,
  "variables": [
    { "oid": "1.3.6.1.6.3.1.1.4.1.0", "value": "1.3.6.1.6.3.1.1.5.1", "type": "ObjectIdentifier" },
    { "oid": "1.3.6.1.2.1.2.2.1.1.1", "value": 1, "type": "Integer" }
  ]
}

字段	类型	说明
from	string	发送 Trap 的设备地址（host:port）
version	string	SNMP 版本字符串：v1/v2c/v3
community	string	community 字符串
timestamp	number	Trap 时间戳（来自 gosnmp SnmpPacket.Timestamp，单位由协议定义，通常为百分之一秒）
variables	array	Trap 携带的 PDU 变量绑定列表，每个元素包含 oid/value/type

variables 中每个元素：

字段	类型	说明
oid	string	变量 OID
value	any	变量值
type	string	SNMP 类型字符串：Integer/OctetString/ObjectIdentifier/IPAddress/Counter32/Gauge32/TimeTicks/Counter64/Null/Unknown

其中 1.3.6.1.6.3.1.1.4.1.0（snmpTrapOID）标识 Trap 的具体告警类型，可据此在规则链中路由分发。

元数据(metadata)

每收到一个 Trap，组件还会把以下关键字段写入 msg.Metadata，方便下游节点用 ${metadata.xx} 直接取值（尤其适合 filter/switch 节点按这些字段分流）：

key	说明
from	发送 Trap 的设备地址（host:port）
community	community 字符串
version	SNMP 版本：v1/v2c/v3
trapOID	Trap 告警类型 OID（variables 中 snmpTrapOID 1.3.6.1.6.3.1.1.4.1.0 的值，仅 v2c/v3 有）

示例：用 filter 节点按告警类型分流——条件 metadata.trapOID == '1.3.6.1.6.3.1.1.5.1' 走"链路 down"分支。

完整 Trap 数据（含全部 variables）仍在 msg.Data，metadata 仅提取常用关键字段便于路由分流。

特性

• 被动监听：不主动请求设备，仅接收设备在异常/状态变化时主动上报的 Trap，实时性高、流量开销小。
• 与主动采集互补：告警事件用本端点接收；周期性指标采集用 x/snmpRead 搭配 endpoint/schedule 定时触发。
• 优雅停机：支持 graceful shutdown，停机时等待处理中的 Trap 完成。

示例

以下规则链在 metadata.endpoints 中定义一个 endpoint/snmp，监听 0.0.0.0:162，把收到的 Trap 路由到 log 节点打印：

{
  "ruleChain": {
    "name": "snmp trap demo",
    "root": true
  },
  "metadata": {
    "endpoints": [
      {
        "id": "node_1",
        "type": "endpoint/snmp",
        "name": "SNMP Trap 监听",
        "configuration": {
          "server": "0.0.0.0:162",
          "version": "v2c",
          "community": "public"
        },
        "routers": [
          {
            "id": "router_1",
            "from": {
              "path": "/"
            },
            "to": {
              "path": "node_2"
            }
          }
        ]
      }
    ],
    "nodes": [
      {
        "id": "node_2",
        "type": "log",
        "name": "打印 Trap",
        "configuration": {
          "jsScript": "return 'SNMP Trap received:\\n' + JSON.stringify(msg);"
        }
      }
    ]
  }
}