Frigate Web Push 推送通知从配置、设备注册到端到端排障【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate本篇指南围绕 Frigate NVR 内置的浏览器推送Web Push通知功能展开详细讲解其底层协议与整体链路、启用前置条件、全局与单摄像头两级的 YAML/UI 配置、设备注册流程以及常见故障的逐层排查方法。读完你既能基于 notifications 参考文档 快速上线推送告警也能结合本仓库中frigate/comms/webpush.py与frigate/api/notification.py的源码理解通知为什么没发出去。通知机制与技术背景Frigate 的原生通知基于 Web Push 协议与 VAPID 规范实现服务端通过一套公钥/私钥体系VAPID对推送请求签名把加密后的消息交给浏览器厂商的推送服务如 Google FCM、Mozilla autopush再由其投递到已注册的浏览器/设备上最后由注册于页面中的 Service Worker即 web/public/notifications-worker.js唤醒并弹出通知。因此一条通知的完整链路是Frigate → 浏览器厂商推送服务 → 设备上的浏览器 → Service Worker 弹窗。这也决定了两个隐含前提Frigate 服务器必须能出站访问互联网中的浏览器厂商推送服务端点。相关约束在 network_requirements 文档 的 Push Notifications 小节有专门说明如果你的部署网络需要白名单请将上述推送服务域名放行。浏览器侧的注册与投递是否成功取决于设备上使用的浏览器与系统通知权限详见后文排障章节。在代码层面推送能力由frigate/comms/webpush.py中的WebPushClient类承载。该类在启动时通过py_vapid的Vapid01.from_file读取/生成配置文件目录下的notifications.pemVAPID 密钥对并为数据库中的每个用户从其notification_tokens字段构建WebPusher订阅对象随后通过一个独立的通知线程和 FIFO 队列逐条消费、发送推送。测试用例 test_webpush_registration.py 中对真实推送服务端点fcm.googleapis.com、push.services.mozilla.com、web.push.apple.com 等做了接受性校验可作为理解服务端要能连到哪些域名的参考。启用推送的前置条件在配置界面打开开关之前需要先满足以下条件文档原文要求逐条核对安全连接与账号登录Frigate 必须通过受信任的https连接访问且当前已登录为 Frigate 用户认证相关说明见 authentication 文档。受支持的浏览器目前已知 Chrome、Firefox 与 Safari 均受支持。外部可达通知要能在离开家庭/办公网络后继续送达Frigate 必须能从外部访问。iOS 额外开关部分用户反馈还需在 iOS 的Settings → Apps → Safari → Advanced → Features中开启 Notifications 开关此外 iOS 上只有添加到主屏幕后从主屏图标启动的 Frigate 才能收到 Web Push详见下方 FAQ。需要特别强调注册端口问题每个设备注册时都绑定到当前登录的 Frigate 用户账号因此注册必须在经过认证的 8971 端口的安全连接上进行——反向代理与隧道也应指向 8971否则注册会失败或绑定到错误上下文。配置全局通知全局配置决定整个实例是否启用推送、用哪个邮箱签名 VAPID 请求、跨摄像头的最小发送间隔。UI 方式导航到Settings Notifications Notifications在Email中填入你的邮箱地址为需要告警的摄像头打开通知开关。YAML 方式notifications: enabled: True email: johndoegmail.com cooldown: 10 # wait 10 seconds before sending another notification from any camera对应字段的含义与默认值可以直接在配置模型中查到见 frigate/config/camera/notification.py 与全局配置 frigate/config/config.py字段类型默认值说明enabledboolFalse是否全局启用通知可被单摄像头覆盖emailstrNone推送通知使用的邮箱用于 VAPID 签名声明sub: mailto:...不填则不会发送任何推送cooldownint0必须 ≥0冷却秒数用于防止频繁打扰从源码看email是硬性前提webpush.py 在启动时就会记录Email must be provided for push notifications to be sent警告而send_alert、send_trigger、send_notification_test等方法在 email 为空时会直接提前返回因此没有邮箱配置整条通知链路都不会工作。配置单摄像头通知如果只想让个别摄像头发通知可以只针对该摄像头开启而全局notifications块保持关闭或仅保留 email。摄像头配置中也内嵌了一份NotificationConfig见 frigate/config/camera/camera.py。UI 方式进入Settings Camera configuration Notifications并选择目标摄像头打开Enable notifications设置Cooldown period为该摄像头两次通知之间的最小等待秒数例如30。YAML 方式cameras: doorbell: ... notifications: enabled: True cooldown: 30 # wait 30 seconds before sending another notification from the doorbell camera两级冷却的判定逻辑通知会被拦截不发送当满足以下任一条件全局冷却未结束自任意摄像头上次发送通知以来尚未经过全局notifications.cooldown秒单摄像头冷却未结束自该摄像头上次发送通知以来尚未经过其自身的cooldown秒。这段逻辑在 webpush.py 的_within_cooldown中实现last_notification_time记录全局最近一次发送时间last_camera_notification_time[camera]记录每个摄像头各自的最近发送时间。实际触发告警时会同时用当前时间减去这两个时间点、与对应冷却值比较命中即跳过并输出对应 debug 日志。一个由此派生的实际坑全局冷却适用于所有摄像头忙碌摄像头的通知会吃掉全局冷却窗口从而抑制较安静摄像头的通知。如果希望各摄像头互不影响应把全局cooldown保持为0默认值只在需要的摄像头上单独设置冷却。注册设备与测试注册设备配置完成后在所有希望接收通知的设备上以 Frigate 用户身份通过 https8971 端口登录点击Register This Device按钮注册该设备会同步注册后台 Service Worker重启 Frigate之后通知才会真正开始发送。注册动作的底层由 frigate/api/notification.py 中的POST /api/notifications/register接口完成浏览器把PushManager订阅对象endpointp256dh/auth密钥POST 上来服务端校验后写入对应用户的notification_tokens字段。该接口对订阅端点的校验相当严格——必须是https默认端口、公网可路由的完整主机名并携带订阅路径localhost、内网 IP、.local/.internal等内网后缀、带凭据或非默认端口的端点都会被拒绝这部分行为也有对应的单元测试覆盖test_webpush_registration.py。前端注册所需的 VAPID 公钥则由GET /api/notifications/pubkey提供api/notification.py当全局与所有摄像头通知都未启用时该接口会直接返回错误这也是界面上看不到注册入口的常见原因。发送测试通知在Settings Notifications中使用Send a test notification按钮。源码中send_notification_testwebpush.py会给所有已注册用户各推送一条标题为 Test Notification 的消息如果 debug 日志中出现了Sending test notification但设备收不到说明消息已离开 Frigate问题出在推送服务与设备之间见排障章节。当前支持的通知类型与平台差异目前 Frigate 的推送通知只覆盖 review 告警alert后续会支持更多类型。理解这一点对排障非常关键通知只针对告警级别事件。源码中send_alertwebpush.py只在事件的severity alert时才继续处理如果摄像头只产生了 detection 而没有升级为 alert就不会有通知。要让关心的事件进入 alert需调整该摄像头的review alerts labels配置。事件仍在进行时通知的直达链接指向实时视图/#camera且 TTL 为 0事件结束后发送的通知会附带事件缩略图TTL 设为 3600 秒直达链接指向review?idid。通知标题由检测到的目标物与所在区域拼装如Person detected in Front Yard开启 GenAI 后则可能带有 Needs Review/Security Concern 等前缀并使用语义摘要作为消息体实现见send_alert中的元数据处理分支。平台差异方面有一个已知限制原文档明确说明仅 Chrome 支持在通知中显示图片Safari 与 Firefox 的通知只会显示标题和消息正文。此外启用用户角色roles后用户只会收到其角色被授权摄像头上的通知——源码中_refresh_user_cameras会依据auth.roles与User.get_allowed_cameras重建用户→摄像头访问缓存发送时逐用户做_user_has_camera_access校验webpush.py。降低通知延迟Android 端设置各平台对通知的处理方式不同Android 上最典型的问题是厂商的电池优化策略会杀死后台 Service Worker导致通知延迟甚至丢失在 Android 的电池优化设置中为浏览器Chrome、Firefox关闭电池优化如果 Frigate 是以 PWA 方式运行的也请为 Frigate 这个应用关闭电池优化。通知排障 FAQ推送链路跨越 Frigate、浏览器与浏览器厂商推送服务三端原文档建议按从服务端向外排查的顺序进行。如何调试通知问题第一步开启推送客户端 debug 日志在logger配置中加入frigate.comms.webpush: debug并重启 Frigatelogger: default: info logs: frigate.comms.webpush: debug这些日志会精确显示通知在哪一环被截停各条日志含义对照如下均可在 webpush.py 源码中逐条定位日志内容含义Email must be provided for push notifications to be sent全局email为空任何通知都不会发送对应 webpush.py 启动警告与各发送方法的提前返回Sending test notification、Sending push notification for camera, review ID id消息已由 Frigate 成功移交给推送服务Skipping notification for camera - in global cooldown period/... camera-specific cooldown period被冷却机制抑制请回查上一节的冷却配置Notifications for camera are currently suspended通知正处在暂停期内暂停来源是Settings Notifications界面或 MQTTNotification endpoint expired for user, received 410该设备的订阅已失效需要重新注册404/410都代表推送服务拒收Failed to send notification to user :: status推送服务拒绝了消息401/403通常指向 VAPID 或email配置问题5xx属于推送服务侧故障如果告警发生时完全没有日志输出说明通知从未被排队请确认确实产生了 alert注意 detection 不会触发通知并且全局与对应摄像头都开启了通知。服务端对失效订阅的处理是自动的_process_notifications收到404/410响应后会将该端点记入expired_subs随后由cleanup_registrationswebpush.py从数据库与运行时的web_pushers中清理掉过期订阅。第二步核对最常出问题的基础项Frigate 必须通过设备信任证书的 https访问否则浏览器会静默拒绝注册 Service Worker自签名证书若未在设备上安装为受信任证书同样会失败。iOS 上通知只在 Frigate 被添加到主屏幕并从该图标打开时生效Safari/Chrome 的普通标签页在 iOS 上收不到 Web Push。每台设备都要单独注册且注册后必须重启 Frigate否则包括测试通知在内的一切推送都不会发送。Frigate 服务器需要有到浏览器厂商推送服务的出站互联网访问见 network_requirements 文档。第三步从 UI 侧做发送测试在Settings Notifications点击Send a test notification。若日志显示Sending test notification但设备上什么都没收到问题出在推送服务到设备这一段而不是 Frigate。第四步检查收不到通知的设备浏览器侧确认站点通知权限在浏览器/系统设置中为Allow且勿开启专注模式、勿扰模式将其屏蔽桌面浏览器打开开发者工具 → Application → Service Workers确认notifications-worker.js已注册并激活若异常取消注册后重新注册设备可重建损坏的订阅查看浏览器控制台与反向代理日志排查/notifications-worker.js加载失败或/api/notifications/register报错。通知运行一段时间后停止到达怎么办推送订阅由浏览器厂商签发可能被吊销最常见于浏览器升级后、清除站点数据后、或设备长时间离线。此时设备在 Frigate 中仍显示已注册但推送服务已拒收消息debug 日志会显示带404/410状态的Notification endpoint expired。解决办法是在Settings Notifications中取消注册并重新注册该设备然后重启 Frigate。某个摄像头一直收不到通知怎么办按顺序排查通知只针对 alert。如果该摄像头产生的是 detection请调整其review alerts labels把关心的目标物归类为 alert相关配置见 review 文档确认在Settings Camera configuration Notifications中为该摄像头开启了通知检查该摄像头的cooldown值——同时记住全局冷却作用于所有摄像头一个繁忙的摄像头可能消耗全局冷却窗口从而压制较安静的摄像头若启用了带角色的 authentication用户只会收到其角色被授权访问摄像头的通知。通知暂停Suspend功能除冷却外Frigate 还支持按摄像头暂停通知一段指定的时间suspend_notifications/unsuspend_notifications见 webpush.py。暂停期间触发的通知会输出Notifications for camera are currently suspended并直接跳过暂停窗口到期后由后台线程自动恢复并可经由 MQTT 把状态变更广播出去。文档中提示的Notifications for camera are currently suspended日志即来自该机制若发现通知被抑制可先到Settings Notifications确认是否存在遗留的暂停。小结Frigate 的推送通知是一套完整的 Web Push 实现配置上区分全局邮箱 全局冷却与摄像头级启用 摄像头级冷却两个层级运行时由 WebPushClient 负责 VAPID 签名、队列发送、过期订阅清理与告警过滤API 侧由 notification.py 提供公钥下发与订阅注册。排查时始终记住四件事email 必须配置、事件必须达到 alert 级别、设备必须注册且服务需重启、Frigate 必须能出站连接浏览器厂商推送服务——大多数收不到通知的报告最终都可归因于这四点。【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考