Frigate 与 Home Assistant 集成完全指南：安装、配置、实体与 API 详解-编程实验室

Frigate 与 Home Assistant 集成完全指南：安装、配置、实体与 API 详解

【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate

Frigate 是一款面向 IP 摄像头的本地实时目标检测 NVR，官方推荐的 Home Assistant 集成方式是通过 frigate-hass-integration（可经 HACS 直接安装）。本文以官方集成文档为主体，结合仓库源码，系统讲解集成前的 MQTT 准备、HACS 安装流程、不同部署形态下的 URL 配置、集成选项、实体清单、媒体浏览器、投屏、Camera/Notification API、RTSP 流模板以及多 Frigate 实例支持，帮助你在一台或多台 Frigate 服务器上完整打通 Home Assistant 生态。

一、前置准备：Frigate 与 MQTT

1.1 先安装并运行 Frigate

在配置任何集成之前，Frigate 本身必须已经安装并正常运行。Frigate 的完整安装方式（Docker、HA Add-on、裸机等）请参见安装文档。集成能否正常工作，很大程度上取决于 Frigate 是否能够稳定提供 HTTP API 与 MQTT 消息。

1.2 MQTT：Home 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的完整参数模型，除上述四项外还包括：

参数	默认值	说明
`port`	`1883`	MQTT Broker 端口（明文 MQTT 通常为 1883）
`topic_prefix`	`frigate`	所有 Frigate MQTT 主题的前缀；运行多实例时必须唯一
`client_id`	`frigate`	连接 Broker 时的客户端标识；每个实例应唯一
`stats_interval`	`60`	系统与摄像机统计信息发布到 MQTT 的间隔（秒）
`qos`	`0`	MQTT 发布/订阅的 QoS 级别（0、1、2）
`tls_ca_certs`/`tls_client_cert`/`tls_client_key`/`tls_insecure`	`None`	TLS 连接相关配置，用于加密或双向认证场景

源码中还通过 pydantic 校验器强制了user与password必须成对出现（user_requires_pass），单独配置其一会被拒绝。

1.3 Frigate 的 MQTT 客户端行为（源码视角）

在 frigate/comms/mqtt.py 的MqttClient中可以看到 MQTT 与集成联动的几个关键实现细节：

Client ID 绑定：_start()中创建 paho 客户端时传入client_id=self.mqtt_config.client_id，多实例部署时正是依靠它区分不同 Frigate；
遗嘱消息：will_set在{topic_prefix}/available上发布offline（QoS 1、retain），Broker 在 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默认5000，external默认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:8971（172.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:8971（compose 服务名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 App（HA 官方 App 内嵌的 Frigate Add-on 变体），URL 应按下表选择。使用 Proxy App 时切勿把集成指向代理 URL，直接填从本网络直接访问 Frigate 所用的地址即可：

App 变体	URL
Frigate	`http://ccab4aaf-frigate:5000`
Frigate (Full Access)	`http://ccab4aaf-frigate-fa:5000`
Frigate Beta	`http://ccab4aaf-frigate-beta:5000`
Frigate Beta (Full Access)	`http://ccab4aaf-frigate-fa-beta:5000`

3.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作为集成 URL：

services: 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/OFF，Frigate 的MqttClient在 frigate/comms/mqtt.py 中订阅并处理这些命令；同时_set_initial_topics()发布的 retain 状态（如detect/state）又反过来驱动开关实体的当前状态，形成闭环。

六、媒体浏览器（Media Browser）

集成提供以下媒体浏览能力：

带缩略图浏览被追踪对象的录像片段
浏览快照
按月份、日期、摄像机、时间浏览录像

入口在 Home Assistant 左侧菜单栏的Media Browser中。此功能需要 HA 侧启用media_source集成（见 2.1 节注意事项）。

七、投屏到媒体设备（Casting）

集成支持把录像片段和摄像机实时画面投放到受支持的媒体设备上。

:::tip

录像片段要能成功投屏，必须包含音频，可能需要为录像启用音频。

注意：即使你的摄像机不支持音频，要接受投屏请求，也必须在录像中启用音频通道。

:::

八、摄像机 API（Camera API）

以下操作可以关闭摄像机（暂停 Frigate 对该流的处理；不会在 Frigate 重启后保持，详见 Camera state）：

action: 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。

:::

九、通知 API（Notification 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.jpg

Android 设备加载录像片段（mp4）：

https://HA_URL/api/frigate/notifications/<event-id>/clip.mp4

iOS 设备加载录像片段（HLS）：

https://HA_URL/api/frigate/notifications/<event-id>/master.m3u8

加载被追踪对象的预览 GIF：

https://HA_URL/api/frigate/notifications/<event-id>/event_preview.gif

加载审核项（review item）的预览 GIF：

https://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.jpg

https://HA_URL/api/frigate/<client-id>/clips/front_door-1624599978.427826-976jaa.mp4

11.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），仅供参考