dchesterton/snmp2mqtt

snmp2mqtt

镜像概述

snmp2mqtt是一款轻量级工具，用于将SNMP协议的传感器数据转换并暴露到MQTT协议，实现SNMP设备与MQTT生态系统的无缝集成。通过简单配置即可监控网络设备、服务器等SNMP兼容设备的状态数据，并发送至MQTT broker，适用于智能家居、工业监控等场景。

核心功能与特性

• 支持SNMPv1、v2c和v3版本，满足不同设备的认证需求
• 灵活配置MQTT连接参数，包括主机、端口、认证信息及TLS加密
• 集成Home Assistant自动发现功能，可直接在Home Assistant中显示传感器
• 支持传感器数据转换，通过JavaScript函数自定义数据处理逻辑
• 可配置扫描间隔，控制数据采集频率
• 支持设备元数据设置（制造商、型号、区域等），优化Home Assistant显示

使用场景

• 智能家居监控：将路由器、交换机等SNMP设备状态集成到Home Assistant
• 工业设备监控：实时采集工业传感器SNMP数据并通过MQTT传输
• 网络设备管理：监控设备CPU使用率、内存占用、运行时间等关键指标
• 服务器状态监控：获取服务器uptime、系统负载等信息并通过MQTT上报

配置说明

配置文件结构

snmp2mqtt通过config.yml文件进行配置，包含日志、MQTT、Home Assistant和目标设备等设置。完整配置示例如下：

yaml
log: debug # 可选：日志级别(debug/info/warning/error)，默认info

mqtt:
    host: 192.168.1.5 # 可选：MQTT broker地址，默认localhost
    port: 1884 # 可选：端口，默认1883(非TLS)或8883(TLS)
    username: my_user # 可选：用户名，默认无
    password: my_password # 可选：密码，默认无
    client_id: snmp2mqtt # 可选：客户端ID，默认snmp2mqtt
    keepalive: 30 # 可选：保活时间(秒)，默认10
    clean: true # 可选：清除会话，默认true
    retain: true # 可选：保留消息，默认true
    qos: 2 # 可选：服务质量，默认0
    ca: /cert/ca.pem # 可选：TLS CA证书路径，默认无
    cert: /cert/cert.pem # 可选：TLS证书路径，默认无
    key: /cert/key.pem # 可选：TLS私钥路径，默认无
    reject_unauthorized: true # 可选：验证服务器证书，TLS默认true

homeassistant:
    discovery: true # 可选：启用Home Assistant发现，默认false
    prefix: "home-assistant" # 可选：MQTT主题前缀，默认homeassistant

targets:
    - host: 192.168.0.2 # 必填：目标设备IP
      name: Raspberry Pi # 可选：设备名称
      scan_interval: 30 # 可选：扫描间隔(秒)，默认10
      device_manufacturer: Raspberry Pi # 可选：Home Assistant制造商
      device_model: 3 Model B # 可选：Home Assistant型号
      suggested_area: Bedroom # 可选：Home Assistant区域
      auth_key: password # 可选：SNMPv3认证密码
      auth_protocol: sha # 可选：SNMPv3认证协议(sha/md5)
      priv_key: password # 可选：SNMPv3加密密码
      priv_protocol: des # 可选：SNMPv3加密协议(des/aes/aes256b/aes256r)
      version: "3" # 可选：SNMP版本(1/2c/3)，默认1
      sensors:
          - oid: 1.3.6.1.2.1.25.1.1.0 # 必填：SNMP OID
            name: Raspberry Pi Uptime # 必填：传感器名称
            unit_of_measurement: days # 可选：Home Assistant单位
            transform: "value / 6000" # 可选：JavaScript转换函数
            icon: mdi:calendar-clock # 可选：Home Assistant图标
            binary_sensor: false # 可选：是否为二进制传感器，默认false

    - host: 192.168.0.3
      name: Raspberry Pi 2
      version: 2c
      sensors:
          - oid: 1.3.6.1.2.1.25.1.1.0
            name: Raspberry Pi 2 Uptime
            unit_of_measurement: days
            transform: "Math.floor(value / 6000 / 60 / 24)"
            icon: mdi:calendar-clock

          - oid: 1.3.6.1.4.1.2021.11.11.0
            name: Raspberry Pi 2 CPU
            unit_of_measurement: "%"
            transform: "100 - value"
            icon: mdi:cpu-64-bit

关键配置项说明

log

• 日志级别，控制输出详细程度，可选值：debug、info、warning、error，默认info。

mqtt

• host：MQTT broker地址，默认localhost
• port：MQTT端口，默认1883（非TLS）或8883（TLS）
• username/password：MQTT认证信息，可选
• ca/cert/key：TLS加密相关证书路径，启用TLS时需配置
• reject_unauthorized：是否验证服务器证书，TLS连接默认true

homeassistant

• discovery：是否启用Home Assistant自动发现，默认false
• prefix：Home Assistant MQTT主题前缀，默认homeassistant

targets

• host：目标设备IP地址，必填
• version：SNMP版本，默认1，可选1、2c、3
• scan_interval：扫描间隔（秒），默认10
• sensors：传感器列表，每个传感器需配置oid（必填）和name（必填）
  • transform：JavaScript函数，用于数据转换，如"value / 6000"将原始值转换为分钟

使用方法

Docker Compose部署

创建docker-compose.yml文件：

yaml
version: "3"
services:
    snmp2mqtt:
        container_name: snmp2mqtt
        image: dchesterton/snmp2mqtt:latest
        restart: unless-stopped
        volumes:
            - ./config.yml:/app/config.yml # 挂载本地配置文件

启动服务：

bash
docker-compose up -d

Docker Run部署

直接使用docker run命令：

bash
docker run -d \
  --name snmp2mqtt \
  --restart unless-stopped \
  -v ./config.yml:/app/config.yml \
  dchesterton/snmp2mqtt:latest