接入 Home Assistant

适用于 MiBee NVR v0.13.0+（内置 RTSP 输出、MQTT 触发与状态发布）；仓库内附带的 custom integration 自 v0.13.0 起提供

MiBee NVR 自带一个可选的 Home Assistant 自定义集成（方案 0：自动发现、按相机生成实体与开关）；不装它也完全可行——通过 RTSP 输出、REST API、MQTT 触发与状态发布四个能力，可以拼出完整的接入方案。本文按用途拆分路径，全部可独立启用。

方案总览

用途	路径	依赖
一体化（发现 + 实体 + 开关）	自定义集成（方案 0）	手动复制安装
看画面（H.264/H.265 相机）	RTSP 输出 + Generic Camera	无（HA 原生）
看画面（MJPEG/JPEG 相机）	stream.mjpeg + MJPEG Camera	无（HA 原生）
触发联动（HA → NVR）	MQTT 触发	MQTT 代理
状态回传（NVR → HA）	MQTT 状态发布（推荐）或 REST 轮询	无 / MQTT 代理
低延迟看画面	HACS WebRTC 卡片	HACS

最省事的组合是「RTSP 看画面 + MQTT 触发 + MQTT 状态回传」，全程只用 HA 原生集成。

前置准备

• NVR 的 REST 接口使用 Web 登录凭据做 Basic Auth（/api/health、/api/events、/api/metrics 除外，它们是公开的）。
• 摄像头 ID 用 NVR 中配置的 id（kebab-case，如 front-door）。
• 密码不要硬编码进版本库管理的 YAML，使用 HA 的 secrets。

方案 0：自定义集成（推荐）

仓库内置一个 Home Assistant 自定义集成（源码与实体清单）。安装后自动发现局域网内的 NVR，并为每台相机创建：

• 摄像头实体 — H.264/H.265 走 NVR 内置 RTSP 输出（HA stream，延迟 1–3 秒）；MJPEG/JPEG 相机走 stream.mjpeg 直通（HA 原生 MJPEG 摄像头）。
• 二进制传感器 ×2 — Connected（连接状态）与 Recording（正在写录像段）。
• 开关 — 切换相机的 recording_enabled 录制开关。

安装（手动复制，约 1 分钟；集成位于主仓子目录，HACS 无法从主仓直接安装）：

git clone https://github.com/Mi-Bee-Studio/MiBeeNvr.git /tmp/mibee-nvr
mkdir -p <HA配置目录>/custom_components
cp -r /tmp/mibee-nvr/deploy/home-assistant/custom_components/mibee_nvr \
      <HA配置目录>/custom_components/

重启 Home Assistant 后：设置 → 设备与服务 → 添加集成 → MiBee NVR。局域网内的 NVR 会被 _mibee-nvr._tcp mDNS 自动发现，输入 Web 登录凭据即可；凭据、RTSP 端口（默认 8554）与轮询间隔（默认 30 秒）都可在集成选项里修改。

方案 A：RTSP 输出 + Generic Camera（H.264/H.265 相机）

NVR 内置 RTSP 输出服务器（默认开启），每个摄像头一个拉流地址：

rtsp://<NVR-IP>:8554/<camera_id>

• 仅 H.264/H.265 原生分发，不转码、只有视频（无音频）；MJPEG/JPEG 相机不供流，请改用方案 A'。
• 默认无鉴权（局域网开放）；可在配置中启用用户名密码：

# mibee-nvr.yaml
server:
  rtsp:
    enabled: true
    port: 8554
    username: ""     # 可选；设置后地址写 rtsp://user:pass@<NVR-IP>:8554/<camera_id>
    password: ""

Docker 部署需要发布 8554 端口（官方 compose 文件已包含）。

在 HA 的 configuration.yaml 中为每个摄像头加一段 Generic Camera：

camera:
  - platform: generic
    name: "前门"
    still_image_url: "http://192.0.2.30:9090/api/cameras/front-door/snapshot"
    stream_source: "rtsp://192.0.2.30:8554/front-door"
    username: admin
    password: "!secret nvr_password"

关于 still_image_url：

• GET /api/cameras/{id}/latest-frame 对 JPEG 系相机（HTTP-JPEG/MJPEG）直接返回最新帧；H.264/H.265 相机在 NVR 所在主机装有可选 FFmpeg 时也能返回解码后的 JPEG（约 10 秒缓存），无 FFmpeg 则返回 404。
• 无 FFmpeg 的 H.264/H.265 相机可用 GET /api/cameras/{id}/snapshot（转发相机自身的快照 URL，仅 ONVIF 快照能力的设备可用），或直接填相机厂商的快照地址。

方案 A'：MJPEG/JPEG 相机（如 ESP32 摄像头）

MJPEG/JPEG 相机不走 RTSP 输出，改用 HA 原生的 MJPEG Camera 直接拉 NVR 的 MJPEG 流：

camera:
  - platform: mjpeg
    name: "院子 ESP32"
    mjpeg_url: "http://192.0.2.30:9090/api/cameras/yard-esp32/stream.mjpeg"
    username: admin
    password: "!secret nvr_password"
    verify_ssl: false

静态缩略图可再配 still_image_url: "http://.../api/cameras/{id}/latest-frame"（JPEG 系相机可用，带 ETag 304）。

方案 B：MQTT 触发联动（HA → NVR）

运动传感器触发时让 NVR 立即录制。先在 NVR 侧配置 MQTT（详见 MQTT 集成）：

# mibee-nvr.yaml
mqtt:
  enabled: true
  broker: "tcp://192.0.2.1:1883"
  client_id: "mibee-nvr"
  topic: "mibee"
  username: "mqtt_user"
  password: "mqtt_password"

NVR 订阅 mibee/trigger/{camera_id}，支持 record（启动摄像头取流；是否写盘由相机「启用录制」开关决定，加 duration 可开限时强制录制窗口、不受开关限制）、stop（停止取流）与 snapshot（快照落盘并发布 camera.snapshot 事件）。HA 自动化示例（对仅直播相机建议带 duration，确保真正落盘，详见 MQTT 集成）：

automation:
  - alias: "检测到运动时触发前门录像"
    trigger:
      - platform: state
        entity_id: binary_sensor.front_door_motion
        to: "on"
    action:
      - service: mqtt.publish
        data:
          topic: "mibee/trigger/front-door"
          payload: '{"action": "record", "duration": "60s"}'

方案 C：状态回传（NVR → HA）

C1：MQTT 状态发布（推荐）

两条发布通道（详见 MQTT 集成 — 状态发布）：

• {prefix}/health/{camera_id}：健康告警（断连/冻结/恢复）。需 mqtt.enabled: true + health.alerts.mqtt: true。
• {prefix}/event/{topic}：录像与摄像头事件（segment.completed、camera.added、camera.quality、storage.health.changed）。需 mqtt.enabled: true + mqtt.status_events: true。

HA 侧示例——每次录像段完成时更新传感器：

mqtt:
  sensor:
    - name: "前门 最近录像"
      state_topic: "mibee/event/segment.completed"
      value_template: "{{ value_json.camera_id }}"
      json_attributes_topic: "mibee/event/segment.completed"

注意：segment.completed 是全 NVR 一个主题（按 camera_id 字段区分相机）。按相机过滤可在自动化中用条件模板判断 trigger.payload_json.camera_id。

C2：REST 轮询（无需 MQTT）

低频数值用 HA 的 RESTful 集成轮询 NVR 接口。单摄像头统计端点返回 recording_count 与 total_size：

restful:
  - resource: "http://192.0.2.30:9090/api/cameras/front-door/stats"
    username: admin
    password: "!secret nvr_password"
    scan_interval: 60
    sensor:
      - name: "前门录像条数"
        value_template: "{{ value_json.recording_count }}"
      - name: "前门录像占用"
        value_template: "{{ value_json.total_size }}"

GET /api/health（公开）可轮询整体状态与 device_id。

C3：SSE 事件流（需要中间件）

NVR 提供 SSE 事件流：GET /api/events（全 NVR，公开、限流 60 次/分钟）与 GET /api/cameras/{id}/events（单相机，需鉴权）。HA 原生不消费 SSE，需要 Node-RED 或自写脚本中转成 MQTT——如果已经启用 C1 的 MQTT 状态发布，通常无需此方案。

方案 D：低延迟画面（HACS WebRTC 卡片）

Generic Camera 走 RTSP 有 1–3 秒延迟。需要亚秒级时可装社区卡片（AlexxIT/WebRTC，经 HACS 安装）：

type: custom:webrtc-camera
url: rtsp://192.0.2.30:8554/front-door
muted: true

该卡片内置 go2rtc 做 RTSP→WebRTC 转换（不直接消费 NVR 的 WHEP 端点），低延迟并支持声音。同样仅适用于 H.264/H.265 相机。

已知限制与安全注意事项

• RTSP 输出默认无鉴权，局域网内任何设备都能拉流。要么配置 server.rtsp.username/password，要么确保 NVR 处于可信网络。
• MQTT 触发的 snapshot 动作会将快照落盘到 {存储根目录}/snapshots/{camera_id}/，并在开启 mqtt.status_events 时发布 camera.snapshot 事件。
• latest-frame 对 JPEG 系相机直接可用；H.264/H.265 相机需 NVR 主机装有可选 FFmpeg（否则用 snapshot 端点或相机自身快照 URL 替代）。
• RTSP 输出与 WebRTC 卡片方案均不覆盖 MJPEG/JPEG 相机（用方案 A'）。
• NVR → HA 没有应用级推送通知闭环，告警通知需在 HA 里自行搭自动化（可订阅健康主题触发）。

下一步

• MQTT 集成 — 触发动作与状态发布的完整参考
• 配置参考 — server.rtsp、mqtt、health.alerts 等全部字段
• API 概览 — REST 接口与鉴权说明