bushrangers/ha-monitor-api

Home Assistant监控API

欢迎使用轻量级"ha-monitor-api"项目！

这是一个快速开发的轻量级API（仅用一个晚上完成），旨在将系统实时指标（如磁盘、网络、CPU/温度等）以简单JSON端点形式暴露，供Home Assistant实例查询。它设计为在Docker容器中运行，适合部署在网络中的其他主机（如外部树莓派摄像头盒、自制气象站或DIY BLE/Zigbee网关等），以便快速将指标反馈给Home Assistant。

该工具不旨在存储磁盘指标或创建复杂图表（已有Zabbix、Prometheus+Grafana等工具），核心目标是提供一个轻量级API，在Docker容器中运行并暴露实时监控数据，供其他系统使用。

Docker Hub: https://hub.docker.com/r/bushrangers/ha-monitor-api/

!https://img.shields.io/github/license/ned-kelly/ha-monitor-api.svg !https://img.shields.io/docker/pulls/bushrangers/ha-monitor-api.png

注意： 当前支持以下系统架构：arm、arm64、amd64。若运行在其他架构上，进程将无法启动或需自行构建镜像。

前提条件

• Docker
• Docker-compose
• 待监控的Linux系统（如树莓派等）

部署步骤

操作简单，克隆源码并启动容器：

bash
# 在待监控主机上克隆源码
git clone https://github.com/ned-kelly/ha-monitor-api /opt/ha-monitor-api
cd /opt/ha-monitor-api

# 启动容器
docker-compose up -d

配置变量

默认服务监听所有接口的TCP:9999端口。如需修改端口，可在compose文件中设置LISTEN_PORT环境变量。

集成到Home Assistant

可通过https://www.home-assistant.io/components/sensor.rest/%E5%B0%86%E5%85%B6%E9%9B%86%E6%88%90%E5%88%B0Home Assistant。以下是OrangePI的示例配置：

sensors/configuration.yaml文件：

yaml
# 监控前门PI的系统资源
- platform: rest
  name: 前门PI
  resource: http://10.16.10.144:9999/
  timeout: 30
  json_attributes:
    - cpu_current
    - cpu_free
    - cpu_average
    - cpu_temperature
    - drive
    - memory
    - network
  value_template: '{{ value_json.value}}'
  headers:
    Content-Type: application/json
    User-Agent: Home Assistant Agent

# 提取传感器数据为独立传感器
- platform: template
  sensors:
    front_door_cputemp:
      value_template: '{{ states.sensor.前门PI.attributes["cpu_temperature"] }}'
      unit_of_measurement: '°'
      entity_id: sensor.前门PI
    front_door_cpuused:
      value_template: '{{ states.sensor.前门PI.attributes["cpu_current"] }}'
      unit_of_measurement: '%'
      entity_id: sensor.前门PI
    front_door_freegb:
      value_template: '{{ states.sensor.前门PI.attributes["drive"]["freeGb"] }}'
      unit_of_measurement: 'GB'
      entity_id: sensor.前门PI
    front_door_driveused:
      value_template: '{{ states.sensor.前门PI.attributes["drive"]["usedPercentage"] }}'
      unit_of_measurement: '%'
      entity_id: sensor.前门PI
    front_door_freemem:
      value_template: '{{ states.sensor.前门PI.attributes["memory"]["freeMemPercentage"] }}'
      unit_of_measurement: '%'
      entity_id: sensor.前门PI
    front_door_networklevel:
      value_template: '{{ states.sensor.前门PI.attributes["network"]["wlan0"]["wireless"]["qualityLevel"] }}'
      entity_id: sensor.前门PI
    front_door_networklink:
      value_template: '{{ states.sensor.前门PI.attributes["network"]["wlan0"]["wireless"]["qualityLink"] }}'
      entity_id: sensor.前门PI
    front_door_networkin:
      value_template: '{{ states.sensor.前门PI.attributes["network"]["wlan0"]["inputBytes"] | multiply(0.000000001024) | round(2) }}'
      entity_id: sensor.前门PI
      unit_of_measurement: 'GB'
    front_door_networkout:
      value_template: '{{ states.sensor.前门PI.attributes["network"]["wlan0"]["outputBytes"] | multiply(0.000000001024) | round(2) }}'
      entity_id: sensor.前门PI
      unit_of_measurement: 'GB'

Lovelace UI配置示例： 使用"vertical-stack-in-card"插件组合多个卡片：

yaml
show_header_toggle: false
title: 前门PI监控
type: 'custom:vertical-stack-in-card'
cards:
  - type: glance
    columns: 4
    entities:
      - entity: sensor.front_door_networkin
        icon: 'mdi:download'
        name: 下载(GB)
      - entity: sensor.front_door_networkout
        icon: 'mdi:upload'
        name: 上传(GB)
      - entity: sensor.front_door_networklevel
        icon: 'mdi:radio-tower'
        name: 信号强度
      - entity: sensor.front_door_networklink
        icon: 'mdi:speedometer'
        name: 链路质量
  - type: history-graph
    entities:
      - entity: sensor.front_door_cpuused
        name: CPU使用率(%)
  - type: glance
    columns: 3
    entities:
      - entity: sensor.front_door_cputemp
        icon: 'mdi:thermometer-lines'
        name: CPU温度(°C)
      - entity: sensor.front_door_freegb
        icon: 'mdi:harddisk'
        name: 磁盘剩余(GB)
      - entity: sensor.front_door_freemem
        icon: 'mdi:memory'
        name: 内存剩余(%)

备注

这仍是一个正在开发的项目，是为Home Assistant快速实现的临时解决方案。欢迎提交PR改进，该项目也可用于Home Assistant之外的场景，尤其适合低资源嵌入式设备。