Frigate 全局配置与摄像头级覆盖Override机制完全指南继承、合并规则与 Profiles 进阶用法【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigateFrigate 允许把绝大部分配置只写一次作为「全局默认值」再针对个别摄像头单独覆盖override从而实现一套默认配置 少量摄像头差异的声明式管理。本文围绕 Frigate 官方文档 Global and Camera-Level Configuration 展开结合仓库内配置解析源码与 Web UI 实现系统讲解继承的判定逻辑、覆盖的生效粒度、列表与映射两类数据的合并差异以及lpr/face_recognition等必须在全局先启用才能逐摄像头使用的能力。读完后你将能精确预测某条摄像头配置写下去之后实际运行时各摄像头究竟拿到什么值避免最常见的配置误判。继承机制的基本规则全局是默认值摄像头可覆盖Frigate 绝大多数配置既可以放在顶层作用于所有摄像头也可以放在某个摄像头下仅作用于该摄像头。顶层值会被当作该摄像头未显式声明时的默认值顶层声明了某值→ 所有摄像头默认使用它摄像头下声明了同名的值→ 该摄像头改用自己的值其余摄像头不受影响摄像头下没有声明→ 继续跟随全局值。UI 操作示例以文档中的 Detect FPS 为例进入Settings Global configuration Object detection把Detect FPS设为5此时所有摄像头都以 5 fps 执行检测进入Settings Camera configuration Object detection选中driveway摄像头把Detect FPS设为10。结果是driveway以 10 fps 检测其余摄像头仍继承全局的 5 fps。YAML 配置示例detect: fps: 5 # 所有摄像头默认以 5 fps 检测 cameras: front_door: ffmpeg: ... driveway: ffmpeg: ... detect: fps: 10 # 仅此摄像头使用 10 fpsfront_door未写detect因而继承全局fps: 5driveway显式写出fps: 10该值只对它生效。关于 Settings UI 各页面的整体导览可参考 Frigate Configuration。覆盖按单个值生效而不是按配置区块整体替换这是最容易误用的规则在某个区块里只覆盖一个字段并不会让该摄像头的整个区块脱离全局。区块内其余未写的字段依然来自全局配置而且全局配置后续修改时仍会影响这些摄像头。UI 行为如果只设置了某摄像头的Motion threshold而Contour area保持默认那么被覆盖的只有 thresholdcontour_area 仍跟随Settings Global configuration Motion detection中的值之后在全局修改它依然会传导到该摄像头。展开一个配置区块时区块标题处会显示该区块中有多少字段与全局配置不同方便你快速定位已被覆盖的字段。YAML 行为motion: threshold: 30 contour_area: 10 cameras: driveway: motion: threshold: 40最终driveway的有效配置是threshold: 40摄像头值与contour_area: 10继承全局值。你只覆盖了显式写出的那个字段。让摄像头重新回到跟随全局的状态在 YAML 中Frigate 判定是否覆盖的依据是该键是否写进了摄像头配置而不是它的值与全局是否相同。即使把全局值原样重复写在摄像头下也会被当作一次覆盖snapshots: enabled: true cameras: driveway: snapshots: enabled: true # 即使与全局一致这也是一次覆盖设想后续你为了整站关闭快照把全局snapshots.enabled改为false由于driveway拥有自己的值它仍然会继续保存快照。要让driveway重新跟随全局正确做法是从摄像头配置中删除该键而不是把它改成与全局一致的值。UI 中的对应操作在 Settings 的摄像头配置页里凡是自己写了值的区块会显示Overridden徽标点击区块底部的Reset to Global按钮即可移除该区块的覆盖、恢复为全局继承。这一交互在 Web 前端由web/src/components/config-form/sections/BaseSection.tsx中的 Reset to Global 逻辑以及web/src/hooks/use-config-override.ts中的isOverridden比较与resetToGlobal实现共同支撑前端会把摄像头当前值与全局值逐字段比较标记出存在差异覆盖的字段重置时再回退为全局值。列表是整体替换映射是按键合并这是覆盖机制里最出乎意料、也最容易引发线上误配置的区别。列表List整体替换摄像头下的列表不会与全局列表相加而是完全取代全局列表。objects: track: - person - car cameras: backyard: objects: track: - dog # backyard 只追踪 dogperson 与 car 都不再追踪backyard的追踪目标最终只有dog。若希望dog是在全局person、car之外的追加项就必须在摄像头上把想要的所有对象全部列出。UI 上的对应语义是摄像头页面展示的正在追踪的对象选择列表以全局列表为起点但你在Settings Camera configuration Objects下改动该选择时会替换该摄像头的整个列表而不是往全局列表里追加。因此请确保选中的是最终想要追踪的全部对象而不仅是新增的那几个。空列表也是合法覆盖空列表同样是一次有效覆盖并且是让某摄像头退出某项能力的标准做法review: alerts: labels: - person cameras: street: review: alerts: labels: [] # 此摄像头永远不产生 alerts注意空列表意味着显式声明什么也没有与未写这个键继续继承全局在语义上完全不同。映射Map逐键合并摄像头下的映射可以只新增一个键无需重新声明全局映射中的其余键。objects: filters: person: min_area: 5000 cameras: driveway: objects: filters: car: min_area: 10000最终driveway同时拥有自己声明的car过滤器与全局继承下来的person过滤器。在 UI 中为某一对象新增过滤器并不会移除该摄像头从全局继承下来的其它对象过滤器。源码层面的依据这种标量/映射合并、列表替换的规则在配置解析中被严格执行。Frigate 加载配置时会在frigate/config/config.py的FrigateConfig.post_validation中把若干全局区块audio、audio_transcription、birdseye、face_recognition、lpr、record、snapshots、live、objects、review、motion、notifications、detect、ffmpeg、timestamp_style等向下传播再逐摄像头调用deep_merge(camera.model_dump(exclude_unsetTrue), modified_global_config)合成最终配置见 frigate/config/config.py。deep_merge定义在 frigate/util/builtin.py两个 dict 都有的键如果同为 dict则递归合并即映射按键合并如果同为 list则在默认参数merge_listsFalse、override语义下用摄像头一方整体替换即列表整体替换摄像头已经显式声明的标量值不会被全局值改写。这正是写了就覆盖、不写才继承和列表替换、映射合并两条规则的底层实现。仓库中的配置解析测试也对这一行为做了覆盖例如 frigate/test/test_config.py 中的test_inherit_tracked_objects、test_deep_merge_override_replaces_list_values、test_global_snapshots_merge、test_inherit_object_filters等用例分别验证了追踪对象列表的继承与整体替换、快照配置的全局合并等场景。哪些设置可以覆盖全局唯一、摄像头专属与部分可覆盖大多数设置都遵循全局写默认值、摄像头可覆盖但并非全部。权威依据是完整参考配置Full Reference Config凡是支持摄像头级覆盖的配置区块都会标注注释# NOTE: Can be overridden at the camera level。在 UI 中判断依据同样直观某设置若同时出现在Settings Global configuration与Settings Camera configuration下就可以覆盖。在此基础上还有几类特殊情况值得记住仅全局global only没有对应的摄像头级配置包括go2rtc、genaiproviders、classification、telemetry、camera_groups、ui等区块仅摄像头级camera only这类区块天然不存在全局默认值例如zones与onvif部分可覆盖partially overridable摄像头只能接收全局区块中的少数几个键face_recognition、lpr与audio_transcription均属此类参考配置中会注明哪些键在摄像头级有效。部分可覆盖在源码中的具体形态同样清晰post_validation中用allowed_fields_map限制了向下传播的字段白名单例如face_recognition只下传enabled、min_arealpr只下传enabled、expire_time、min_area、enhancementaudio_transcription只下传enabled、live_enabled见 frigate/config/config.py。也就是说这些区块的摄像头级配置在模型层只开放了白名单内的键。必须先全局启用、才能逐摄像头使用的功能lpr 与 face_recognition车牌识别LPR与人脸识别face recognition有一个特殊约定全局设置在这里不只是默认值而是一个总开关——只有全局开启后任意摄像头才允许使用该功能。若在全局关闭的状态下直接在某摄像头开启Frigate 会判定为配置错误并拒绝启动报错形如Camera driveway has lpr enabled but lpr is disabled at the global level of the config. You must enable lpr at the global level.这一校验实现在verify_lpr_and_face中见 frigate/config/config.py只要camera_config.lpr.enabled为真而frigate_config.lpr.enabled为假就抛出ValueErrorface_recognition同理。正确做法是先全局开启功能再在不需要的摄像头上一一关闭UI 操作进入Settings Global configuration License plate recognition打开LPR进入Settings Camera configuration License plate recognition逐个选中不运行 LPR 的摄像头关闭Enable LPR开关。YAML 配置lpr: enabled: true cameras: driveway: ffmpeg: ... # 继承全局LPR 开启 backyard: ffmpeg: ... lpr: enabled: false # 主动退出 LPR:::note 此约定仅适用于lpr与face_recognition因为它们的全局开关决定支撑后台进程是否启动。其它功能不遵循该约束——例如音频转写audio transcription可以直接在单个摄像头启用无需先全局开启。 :::Profiles叠加在摄像头配置之上的一层Profiles 在以上所有规则之上再叠加一层Profile 是一组具名的摄像头级覆盖集合可在 Frigate 运行期间随时切换启停例如离家时批量改变检测与录像行为。关键语义是Profile 应用在摄像头已经解析完成的配置之上因此当某个 Profile 处于激活状态时Profile 中的值会同时压过摄像头值与全局值。Profile 只覆盖摄像头配置的子集并且不会修改你的配置文件本身配置解析与启停切换的实现集中在 frigate/config/profile_manager.py其运行时切换、还原行为由 frigate/test/test_profiles.py 中的大量用例验证。快速自查清单摄像头会继承你未在它名下声明的所有值覆盖只作用于你写出的那个值不会让整个区块脱离全局只要把某个值写在摄像头上就会形成覆盖即便它与全局值相同要恢复继承请删除该键列表整体替换全局列表映射按键合并进全局映射空列表是一次数值明确的覆盖等价于退出该项能力lpr与face_recognition必须先全局启用摄像头才允许单独开启判断某设置能否被摄像头覆盖以 Full Reference Config 中# NOTE: Can be overridden at the camera level注释或 UI 中该设置是否同时出现在全局与摄像头两级配置为准。【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Frigate 全局配置与摄像头级覆盖（Override）机制完全指南：继承、合并规则与 Profiles 进阶用法
Frigate 全局配置与摄像头级覆盖Override机制完全指南继承、合并规则与 Profiles 进阶用法【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigateFrigate 允许把绝大部分配置只写一次作为「全局默认值」再针对个别摄像头单独覆盖override从而实现一套默认配置 少量摄像头差异的声明式管理。本文围绕 Frigate 官方文档 Global and Camera-Level Configuration 展开结合仓库内配置解析源码与 Web UI 实现系统讲解继承的判定逻辑、覆盖的生效粒度、列表与映射两类数据的合并差异以及lpr/face_recognition等必须在全局先启用才能逐摄像头使用的能力。读完后你将能精确预测某条摄像头配置写下去之后实际运行时各摄像头究竟拿到什么值避免最常见的配置误判。继承机制的基本规则全局是默认值摄像头可覆盖Frigate 绝大多数配置既可以放在顶层作用于所有摄像头也可以放在某个摄像头下仅作用于该摄像头。顶层值会被当作该摄像头未显式声明时的默认值顶层声明了某值→ 所有摄像头默认使用它摄像头下声明了同名的值→ 该摄像头改用自己的值其余摄像头不受影响摄像头下没有声明→ 继续跟随全局值。UI 操作示例以文档中的 Detect FPS 为例进入Settings Global configuration Object detection把Detect FPS设为5此时所有摄像头都以 5 fps 执行检测进入Settings Camera configuration Object detection选中driveway摄像头把Detect FPS设为10。结果是driveway以 10 fps 检测其余摄像头仍继承全局的 5 fps。YAML 配置示例detect: fps: 5 # 所有摄像头默认以 5 fps 检测 cameras: front_door: ffmpeg: ... driveway: ffmpeg: ... detect: fps: 10 # 仅此摄像头使用 10 fpsfront_door未写detect因而继承全局fps: 5driveway显式写出fps: 10该值只对它生效。关于 Settings UI 各页面的整体导览可参考 Frigate Configuration。覆盖按单个值生效而不是按配置区块整体替换这是最容易误用的规则在某个区块里只覆盖一个字段并不会让该摄像头的整个区块脱离全局。区块内其余未写的字段依然来自全局配置而且全局配置后续修改时仍会影响这些摄像头。UI 行为如果只设置了某摄像头的Motion threshold而Contour area保持默认那么被覆盖的只有 thresholdcontour_area 仍跟随Settings Global configuration Motion detection中的值之后在全局修改它依然会传导到该摄像头。展开一个配置区块时区块标题处会显示该区块中有多少字段与全局配置不同方便你快速定位已被覆盖的字段。YAML 行为motion: threshold: 30 contour_area: 10 cameras: driveway: motion: threshold: 40最终driveway的有效配置是threshold: 40摄像头值与contour_area: 10继承全局值。你只覆盖了显式写出的那个字段。让摄像头重新回到跟随全局的状态在 YAML 中Frigate 判定是否覆盖的依据是该键是否写进了摄像头配置而不是它的值与全局是否相同。即使把全局值原样重复写在摄像头下也会被当作一次覆盖snapshots: enabled: true cameras: driveway: snapshots: enabled: true # 即使与全局一致这也是一次覆盖设想后续你为了整站关闭快照把全局snapshots.enabled改为false由于driveway拥有自己的值它仍然会继续保存快照。要让driveway重新跟随全局正确做法是从摄像头配置中删除该键而不是把它改成与全局一致的值。UI 中的对应操作在 Settings 的摄像头配置页里凡是自己写了值的区块会显示Overridden徽标点击区块底部的Reset to Global按钮即可移除该区块的覆盖、恢复为全局继承。这一交互在 Web 前端由web/src/components/config-form/sections/BaseSection.tsx中的 Reset to Global 逻辑以及web/src/hooks/use-config-override.ts中的isOverridden比较与resetToGlobal实现共同支撑前端会把摄像头当前值与全局值逐字段比较标记出存在差异覆盖的字段重置时再回退为全局值。列表是整体替换映射是按键合并这是覆盖机制里最出乎意料、也最容易引发线上误配置的区别。列表List整体替换摄像头下的列表不会与全局列表相加而是完全取代全局列表。objects: track: - person - car cameras: backyard: objects: track: - dog # backyard 只追踪 dogperson 与 car 都不再追踪backyard的追踪目标最终只有dog。若希望dog是在全局person、car之外的追加项就必须在摄像头上把想要的所有对象全部列出。UI 上的对应语义是摄像头页面展示的正在追踪的对象选择列表以全局列表为起点但你在Settings Camera configuration Objects下改动该选择时会替换该摄像头的整个列表而不是往全局列表里追加。因此请确保选中的是最终想要追踪的全部对象而不仅是新增的那几个。空列表也是合法覆盖空列表同样是一次有效覆盖并且是让某摄像头退出某项能力的标准做法review: alerts: labels: - person cameras: street: review: alerts: labels: [] # 此摄像头永远不产生 alerts注意空列表意味着显式声明什么也没有与未写这个键继续继承全局在语义上完全不同。映射Map逐键合并摄像头下的映射可以只新增一个键无需重新声明全局映射中的其余键。objects: filters: person: min_area: 5000 cameras: driveway: objects: filters: car: min_area: 10000最终driveway同时拥有自己声明的car过滤器与全局继承下来的person过滤器。在 UI 中为某一对象新增过滤器并不会移除该摄像头从全局继承下来的其它对象过滤器。源码层面的依据这种标量/映射合并、列表替换的规则在配置解析中被严格执行。Frigate 加载配置时会在frigate/config/config.py的FrigateConfig.post_validation中把若干全局区块audio、audio_transcription、birdseye、face_recognition、lpr、record、snapshots、live、objects、review、motion、notifications、detect、ffmpeg、timestamp_style等向下传播再逐摄像头调用deep_merge(camera.model_dump(exclude_unsetTrue), modified_global_config)合成最终配置见 frigate/config/config.py。deep_merge定义在 frigate/util/builtin.py两个 dict 都有的键如果同为 dict则递归合并即映射按键合并如果同为 list则在默认参数merge_listsFalse、override语义下用摄像头一方整体替换即列表整体替换摄像头已经显式声明的标量值不会被全局值改写。这正是写了就覆盖、不写才继承和列表替换、映射合并两条规则的底层实现。仓库中的配置解析测试也对这一行为做了覆盖例如 frigate/test/test_config.py 中的test_inherit_tracked_objects、test_deep_merge_override_replaces_list_values、test_global_snapshots_merge、test_inherit_object_filters等用例分别验证了追踪对象列表的继承与整体替换、快照配置的全局合并等场景。哪些设置可以覆盖全局唯一、摄像头专属与部分可覆盖大多数设置都遵循全局写默认值、摄像头可覆盖但并非全部。权威依据是完整参考配置Full Reference Config凡是支持摄像头级覆盖的配置区块都会标注注释# NOTE: Can be overridden at the camera level。在 UI 中判断依据同样直观某设置若同时出现在Settings Global configuration与Settings Camera configuration下就可以覆盖。在此基础上还有几类特殊情况值得记住仅全局global only没有对应的摄像头级配置包括go2rtc、genaiproviders、classification、telemetry、camera_groups、ui等区块仅摄像头级camera only这类区块天然不存在全局默认值例如zones与onvif部分可覆盖partially overridable摄像头只能接收全局区块中的少数几个键face_recognition、lpr与audio_transcription均属此类参考配置中会注明哪些键在摄像头级有效。部分可覆盖在源码中的具体形态同样清晰post_validation中用allowed_fields_map限制了向下传播的字段白名单例如face_recognition只下传enabled、min_arealpr只下传enabled、expire_time、min_area、enhancementaudio_transcription只下传enabled、live_enabled见 frigate/config/config.py。也就是说这些区块的摄像头级配置在模型层只开放了白名单内的键。必须先全局启用、才能逐摄像头使用的功能lpr 与 face_recognition车牌识别LPR与人脸识别face recognition有一个特殊约定全局设置在这里不只是默认值而是一个总开关——只有全局开启后任意摄像头才允许使用该功能。若在全局关闭的状态下直接在某摄像头开启Frigate 会判定为配置错误并拒绝启动报错形如Camera driveway has lpr enabled but lpr is disabled at the global level of the config. You must enable lpr at the global level.这一校验实现在verify_lpr_and_face中见 frigate/config/config.py只要camera_config.lpr.enabled为真而frigate_config.lpr.enabled为假就抛出ValueErrorface_recognition同理。正确做法是先全局开启功能再在不需要的摄像头上一一关闭UI 操作进入Settings Global configuration License plate recognition打开LPR进入Settings Camera configuration License plate recognition逐个选中不运行 LPR 的摄像头关闭Enable LPR开关。YAML 配置lpr: enabled: true cameras: driveway: ffmpeg: ... # 继承全局LPR 开启 backyard: ffmpeg: ... lpr: enabled: false # 主动退出 LPR:::note 此约定仅适用于lpr与face_recognition因为它们的全局开关决定支撑后台进程是否启动。其它功能不遵循该约束——例如音频转写audio transcription可以直接在单个摄像头启用无需先全局开启。 :::Profiles叠加在摄像头配置之上的一层Profiles 在以上所有规则之上再叠加一层Profile 是一组具名的摄像头级覆盖集合可在 Frigate 运行期间随时切换启停例如离家时批量改变检测与录像行为。关键语义是Profile 应用在摄像头已经解析完成的配置之上因此当某个 Profile 处于激活状态时Profile 中的值会同时压过摄像头值与全局值。Profile 只覆盖摄像头配置的子集并且不会修改你的配置文件本身配置解析与启停切换的实现集中在 frigate/config/profile_manager.py其运行时切换、还原行为由 frigate/test/test_profiles.py 中的大量用例验证。快速自查清单摄像头会继承你未在它名下声明的所有值覆盖只作用于你写出的那个值不会让整个区块脱离全局只要把某个值写在摄像头上就会形成覆盖即便它与全局值相同要恢复继承请删除该键列表整体替换全局列表映射按键合并进全局映射空列表是一次数值明确的覆盖等价于退出该项能力lpr与face_recognition必须先全局启用摄像头才允许单独开启判断某设置能否被摄像头覆盖以 Full Reference Config 中# NOTE: Can be overridden at the camera level注释或 UI 中该设置是否同时出现在全局与摄像头两级配置为准。【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考