Frigate 与 Home Assistant 集成完全指南安装、配置、实体与 API 详解【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigateFrigate 是一款面向 IP 摄像头的本地实时目标检测 NVR官方推荐的 Home Assistant 集成方式是通过 frigate-hass-integration可经 HACS 直接安装。本文以官方集成文档为主体结合仓库源码系统讲解集成前的 MQTT 准备、HACS 安装流程、不同部署形态下的 URL 配置、集成选项、实体清单、媒体浏览器、投屏、Camera/Notification API、RTSP 流模板以及多 Frigate 实例支持帮助你在一台或多台 Frigate 服务器上完整打通 Home Assistant 生态。一、前置准备Frigate 与 MQTT1.1 先安装并运行 Frigate在配置任何集成之前Frigate 本身必须已经安装并正常运行。Frigate 的完整安装方式Docker、HA Add-on、裸机等请参见 安装文档。集成能否正常工作很大程度上取决于 Frigate 是否能够稳定提供 HTTP API 与 MQTT 消息。1.2 MQTTHome Assistant 侧与 Frigate 侧必须连通Frigate 集成要求 Home Assistant 中先安装并手动配置mqtt集成参见 Home Assistant MQTT 集成文档。同时Frigate 配置文件中也必须启用 MQTT并且 Frigate 与 Home Assistant 必须连接同一个 MQTT Broker——集成创建的许多实体都依赖 MQTT 消息驱动。典型的 Frigate 侧 MQTT 配置如下mqtt: enabled: True host: mqtt.server.com # 运行 MQTT 集成的 HA 服务器地址 user: your_mqtt_broker_username password: your_mqtt_broker_password从仓库源码 frigate/config/mqtt.py 可以看到MqttConfig的完整参数模型除上述四项外还包括参数默认值说明port1883MQTT Broker 端口明文 MQTT 通常为 1883topic_prefixfrigate所有 Frigate MQTT 主题的前缀运行多实例时必须唯一client_idfrigate连接 Broker 时的客户端标识每个实例应唯一stats_interval60系统与摄像机统计信息发布到 MQTT 的间隔秒qos0MQTT 发布/订阅的 QoS 级别0、1、2tls_ca_certs/tls_client_cert/tls_client_key/tls_insecureNoneTLS 连接相关配置用于加密或双向认证场景源码中还通过 pydantic 校验器强制了user与password必须成对出现user_requires_pass单独配置其一会被拒绝。1.3 Frigate 的 MQTT 客户端行为源码视角在 frigate/comms/mqtt.py 的MqttClient中可以看到 MQTT 与集成联动的几个关键实现细节Client ID 绑定_start()中创建 paho 客户端时传入client_idself.mqtt_config.client_id多实例部署时正是依靠它区分不同 Frigate遗嘱消息will_set在{topic_prefix}/available上发布offlineQoS 1、retainBroker 在 Frigate 异常掉线时自动补发Home Assistant 据此感知 Frigate 在线状态全量订阅连接成功后client.subscribe(f{topic_prefix}/#)即订阅前缀下的所有主题状态主题_set_initial_topics()会为每台摄像机发布enabled/state、detect/state、recordings/state、snapshots/state等 retain 状态集成实体因此能即时读到最新状态命令主题所有/set类命令主题如{topic_prefix}/{name}/detect/set都会注册message_callback_add并路由到on_mqtt_command这正是下方开关实体能控制 Frigate 的底层通道。二、集成安装2.1 通过 HACS 安装Frigate 集成在 HACS 中作为默认仓库提供安装步骤如下打开 HACS在搜索栏输入Frigate选择并安装Home Assistant HACS 在搜索栏输入 Frigate Frigate重启 Home Assistant添加/配置集成Home Assistant Settings Devices Services Add Integration Frigate注意若希望媒体浏览器Media Browser在 HA 中出现还需在 Home Assistant 配置中启用 media_source 集成。2.2 可选Lovelace 卡片安装如需在 Lovelace 界面中嵌入 Frigate 实况卡片请按该卡片的独立安装说明操作它是与主集成相互独立的可选组件。三、配置集成URL 的选择配置集成时Home Assistant 会要求填写 Frigate 实例的URL可以指向内部未认证端口5000仅限可信网络/容器内访问无认证认证端口8971需登录认证通常启用了 TLS。URL 形如http://host:5000/。这两个端口在 frigate/config/network.py 中定义internal默认5000external默认8971。认证端口的语义可以进一步在 frigate/api/auth.py 及认证相关测试 frigate/test/http_api/test_http_auth_internal_port.py 中看到内部端口请求被当作匿名 admin 处理外部端口则需要认证。3.1 Docker Compose 示例同机部署场景一Home Assistant 使用 host 网络模式不推荐让 Frigate 也跑在 host 网络模式下。此场景配置集成时应使用http://172.17.0.1:5000或http://172.17.0.1:8971172.17.0.1是 Docker 默认网桥中访问宿主机的地址services: homeassistant: image: ghcr.io/home-assistant/home-assistant:stable network_mode: host ... frigate: image: ghcr.io/blakeblackshear/frigate:stable ... ports: - 172.17.0.1:5000:5000 ...场景二HA 未使用 host 网络或与 Frigate 分属不同 compose 文件此场景推荐连接认证端口例如http://frigate:8971compose 服务名frigate可直接被同网络解析。无需为 Frigate 映射端口services: homeassistant: image: ghcr.io/home-assistant/home-assistant:stable # network_mode: host ... frigate: image: ghcr.io/blakeblackshear/frigate:stable ... ports: # - 172.17.0.1:5000:5000 ...3.2 Home Assistant App 场景如果使用 Home Assistant AppHA 官方 App 内嵌的 Frigate Add-on 变体URL 应按下表选择。使用 Proxy App 时切勿把集成指向代理 URL直接填从本网络直接访问 Frigate 所用的地址即可App 变体URLFrigatehttp://ccab4aaf-frigate:5000Frigate (Full Access)http://ccab4aaf-frigate-fa:5000Frigate Betahttp://ccab4aaf-frigate-beta:5000Frigate Beta (Full Access)http://ccab4aaf-frigate-fa-beta:50003.3 Frigate 运行在独立机器上如果 Frigate 运行在局域网内的另一台设备上Home Assistant 需要能访问其8971端口。局域网直连使用http://frigate_device_ip:8971作为集成 URL以便启用认证:::tip上述 URL 假设你已禁用 TLS。默认情况下 TLS 是开启的Frigate 会使用自签名证书Home Assistant 无法验证自签名证书将无法通过 HTTPS 连接 8971 端口。要么禁用 TLS 改用 HTTP要么为 Frigate 配置有效的正式证书。:::services: frigate: image: ghcr.io/blakeblackshear/frigate:stable ... ports: - 8971:8971 ...Tailscale 或其他私有网络使用http://frigate_device_tailscale_ip:5000作为集成 URLservices: frigate: image: ghcr.io/blakeblackshear/frigate:stable ... ports: - tailscale_ip:5000:5000 ...四、集成选项Options在 Home Assistant 中打开Home Assistant Configuration Integrations Frigate Options选项说明RTSP URL Template用于覆盖标准 RTSP 流 URL 的 jinja2 模板例如配合反向代理使用。该选项仅在启用高级模式的用户中显示。详见下文 RTSP 流五、集成提供的实体平台说明camera摄像机实时画面需要 RTSP 可达image每台摄像机最近一次检测到对象的图片sensor监控 Frigate 性能、各区域/摄像机对象计数的状态实体switch用于开关检测detect、录像recordings与快照snapshots的开关实体binary_sensor每个摄像机/区域/对象的 motion 运动二进制传感器其中switch实体的底层正是通过 Frigate 的 MQTT 命令主题实现集成向frigate/camera/detect/set、recordings/set、snapshots/set等主题发布ON/OFFFrigate 的MqttClient在 frigate/comms/mqtt.py 中订阅并处理这些命令同时_set_initial_topics()发布的 retain 状态如detect/state又反过来驱动开关实体的当前状态形成闭环。六、媒体浏览器Media Browser集成提供以下媒体浏览能力带缩略图浏览被追踪对象的录像片段浏览快照按月份、日期、摄像机、时间浏览录像入口在 Home Assistant 左侧菜单栏的Media Browser中。此功能需要 HA 侧启用media_source集成见 2.1 节注意事项。七、投屏到媒体设备Casting集成支持把录像片段和摄像机实时画面投放到受支持的媒体设备上。:::tip录像片段要能成功投屏必须包含音频可能需要为录像启用音频。注意即使你的摄像机不支持音频要接受投屏请求也必须在录像中启用音频通道。:::八、摄像机 APICamera API以下操作可以关闭摄像机暂停 Frigate 对该流的处理不会在 Frigate 重启后保持详见 Camera stateaction: camera.turn_off data: {} target: entity_id: camera.back_deck_cam # 你的 Frigate 摄像机实体 ID重新打开摄像机action: camera.turn_on data: {} target: entity_id: camera.back_deck_cam # 你的 Frigate 摄像机实体 ID:::note上述动作切换的是 Frigate 的运行时 On/Off 状态。若要永久禁用某台摄像机请在 Frigate UI 的Settings → Camera Management中将其状态设为Disabled。:::九、通知 APINotification API很多人不希望把 Frigate 暴露到公网因此集成创建了一些公开的 API 端点专门用于通知推送场景。所有端点都挂在 Home Assistant 域名之下格式为https://HA_URL/api/frigate/notifications/...。加载被追踪对象的缩略图https://HA_URL/api/frigate/notifications/event-id/thumbnail.jpg加载被追踪对象的快照https://HA_URL/api/frigate/notifications/event-id/snapshot.jpgAndroid 设备加载录像片段mp4https://HA_URL/api/frigate/notifications/event-id/clip.mp4iOS 设备加载录像片段HLShttps://HA_URL/api/frigate/notifications/event-id/master.m3u8加载被追踪对象的预览 GIFhttps://HA_URL/api/frigate/notifications/event-id/event_preview.gif加载审核项review item的预览 GIFhttps://HA_URL/api/frigate/notifications/review-id/review_preview.gif加载审核项的缩略图https://HA_URL/api/frigate/notifications/review-id/camera/review_thumbnail.webp这些端点与 Frigate 内部媒体 API 一一对应例如 frigate/api/media.py 中实现了event_preview、review_preview等端点master.m3u8是 HLS 播放列表格式——文档源码中明确注释iOS 设备应使用 master.m3u8 的 HLS 链接而非 clip.mp4因为 Safari 无法可靠地处理渐进式 mp4 文件。Android 与 iOS 分开使用clip.mp4与master.m3u8正是这一兼容性差异的体现。十、RTSP 流与 RTSP URL 模板10.1 默认行为实时画面要正常工作Frigate 的 RTSP 端口默认8554必须可访问Home Assistant 会在查看实况时直接连接frigatehost:8554。10.2 RTSP URL 模板对于高级用例可以通过集成选项中的RTSP URL Template改变这一行为。设置后该字符串将覆盖上述默认行为推导出的流地址。它支持 jinja2 模板 中提供的camera字典变量。注意模板中拿不到任何 Home Assistant 状态只有来自 Frigate 的 camera 字典。这在 Frigate 位于反向代理之后、或默认流端口对 Home Assistant 不可达如防火墙规则时非常有用。模板示例换用不同端口rtsp://frigate_host:2000/front_door在流 URL 中使用摄像机名称rtsp://frigate_host:2000/{{ name }}使用摄像机名称并先转为小写rtsp://frigate_host:2000/{{ name|lower }}十一、多 Frigate 实例支持Frigate 集成原生支持同时对接多台 Frigate 服务器。11.1 多实例前提要让多个 Frigate 实例协同工作每个服务器的topic_prefix与client_id必须设置为不同值。具体设置方式参见 MQTT 配置。这两个参数在 frigate/config/mqtt.py 中默认均为frigate多实例时必须显式改掉。从源码可以印证其作用client_id在 frigate/comms/mqtt.py 的_start()中作为 paho 客户端 ID 传入Broker 用它区分不同连接也是集成区分实例的标识topic_prefix所有主题状态、命令、available遗嘱消息都以其为前缀保证多实例消息互不串扰。11.2 API URL 的实例标识配置多个 Frigate 实例后通知 API 的 URL 需要带上标识来告诉 Home Assistant 指向哪台 Frigate。该标识就是配置中的 MQTTclient_id参数用法如下https://HA_URL/api/frigate/client-id/notifications/event-id/thumbnail.jpghttps://HA_URL/api/frigate/client-id/clips/front_door-1624599978.427826-976jaa.mp411.3 默认处理规则当只配置了单台Frigate 实例时URL/标识中无需指定client-id——该实例被默认假定当配置了多台Frigate 实例时用户必须显式指明所指的是哪台服务器。十二、常见问题FAQ检测到多个对象时如何把正确的binary_sensor关联给 HomeKit 中的摄像机HomeKit 集成会随机把与该摄像机设备分组的其中一个 binary sensor运动传感器实体关联上去。你可以在 Home Assistant 的 HomeKit 配置中为每台摄像机指定linked_motion_sensor来固定关联关系。我基于 occupancy占用传感器设置了自动化有时自动化因传感器被打开而触发但我去 Frigate 里却找不到触发传感器的对象。这是 Bug 吗不是。占用传感器的检查逻辑较少因为它常用于开灯这类延迟必须尽可能低的场景因此这些传感器偶尔会出现误报。如果你需要误报过滤应改用frigate/events或frigate/reviews主题上的 MQTT 传感器。结语至此你已经完整掌握了 Frigate × Home Assistant 集成的全部关键环节从 MQTT 前置准备、HACS 安装、不同部署形态下的 URL 选择到实体体系、媒体浏览、投屏、Camera/Notification API、RTSP 模板与多实例支持。配合仓库中 frigate/config/mqtt.py、frigate/comms/mqtt.py、frigate/config/network.py 与 frigate/api/media.py 等源码你可以在排查问题时直达底层实现把配置能用提升为原理清楚。【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考