Frigate 录像功能完全指南：从保留策略配置到源码级存储原理

Frigate 录像功能完全指南从保留策略配置到源码级存储原理【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigateoutput文章Frigate 录像配置与存储原理完全指南保留策略、预录/后录、导出与磁盘空间管理Frigate 是一款面向 IP 摄像头的本地实时目标检测 NVR。录像Recording是它的核心能力之一你可以为每台摄像头独立配置连续录像 事件录像的组合保留策略所有片段直接从摄像头码流写入而不经过重新编码并按 UTC 时间的目录结构落地到磁盘。读完本文你将掌握 Frigate 录像的完整配置骨架连续/运动/告警/检测四类保留、三种保留模式、pre/post capture 预录后录、录像的写入与校验链路cache → 校验 → 落地以及存储统计、媒体同步与紧急清理的底层原理。本文以 record.md 为核心骨架结合 frigate/config/camera/record.py、frigate/record/maintainer.py、frigate/record/cleanup.py 等源码展开纵深讲解。录像存储基础目录结构、时间基准与写入流程录像默认存储于容器内的/media/frigate/recordings目录结构为YYYY-MM-DD/HH/camera_name/MM.SS.mp4全部采用 UTC 时间。也就是说一天的录像按天/小时分目录每小时目录下按摄像头分子目录片段文件以分.秒.mp4命名。两个关键设计决定了这套存储体系的形态零重编码录像片段直接取自摄像头流record 流不做转码因此存储占用与码流质量直接相关也与硬件编码器无关。先写 cache 再落地新的录像片段先写入/tmp/cache推荐配置为小型内存盘tmpfs只有通过校验且符合保留策略的片段才会被移动到/media/frigate/recordings。校验与移动由RecordingMaintainer见 frigate/record/maintainer.py周期执行它会用 ffprobe 探测每个片段的视频流与时长validate_and_move_segmentmaintainer.py无效或损坏片段直接丢弃通过校验的片段用ffmpeg -c copy -movflags faststart快速复制到目标目录并写入数据库move_segment。片段以 10 秒为单位切分写入这与下文 pre/post capture 的时间精度直接相关。:::tip 需要把某段录像永久保留时请使用导出功能而不是为整台摄像头调大保留天数。导出文件单独保存永远不会被保留策略删除。 :::播放兼容性注意H.265 录像只能在 Chrome 108、Edge 与 Safari 中播放其余浏览器要求录像为 H.264 编码。Apple 设备的 Safari 播放 H.265 录像失败时应使用 apple compatibility 选项apple_compatibility来保证流畅播放。三种常见录像配置模板所有录像配置都写在record:根键下可全局配置并在摄像头级别覆盖。以下三套配置覆盖了从全量保存到只留告警的典型需求。最保守确保所有视频都被保存适合对连续性有强要求的场景最近 3 天保存全部视频3 天后只保留含运动事件的视频 7 天7 天后仅保留与告警/检测重叠的视频直到第 30 天。record: enabled: True continuous: days: 3 motion: days: 7 alerts: retain: days: 30 mode: all detections: retain: days: 30 mode: all对应 UI 路径为Settings Global configuration Recording开启Enable recording设置Continuous retention Retention days为 3、Motion retention Retention days为 7并将告警与检测的Event retention Retention days均设为 30、Retention mode均设为all。节省存储只在检测到运动时保存只保留有运动或活动发生的视频适合存储紧张的环境record: enabled: True motion: days: 3 alerts: retain: days: 30 mode: motion detections: retain: days: 30 mode: motionUI 对应操作开启Enable recordingMotion retention Retention days设 3告警与检测的Event retention Retention days均设 30、Retention mode均设motion。最少配置仅保留告警若只想保留有跟踪目标活动期间的录像将连续录像天数设为 0 即可丢弃一切非告警时段record: enabled: True continuous: days: 0 alerts: retain: days: 30 mode: motionUI 对应操作Continuous retention Retention days设 0Alert retention Event retention Retention days设 30、Retention mode设motion。预录与后录Pre-capture / Post-capturepre_capture与post_capture控制告警/检测前后各纳入多少秒的视频。二者可分别针对告警alerts与检测detections独立配置可全局设置、也可按摄像头覆盖。record: enabled: True alerts: pre_capture: 5 # 告警开始前包含的秒数 post_capture: 5 # 告警结束后包含的秒数 detections: pre_capture: 5 # 检测开始前包含的秒数 post_capture: 5 # 检测结束后包含的秒数默认值pre/post capture 均为 5 秒见 record.py 中EventsConfig的默认值。pre_capture 上限60 秒MAX_PRE_CAPTURE 60见 const.py。这些设置按审查类别alerts / detections生效不按对象类型细分。源码层面RecordConfig通过get_review_pre_capture(severity)/get_review_post_capture(severity)按严重级别取对应值并定义了event_pre_capture取 alerts 与 detections 中较大的 pre_capture用于判定缓存片段是否可提前丢弃record.py。pre/post capture 与保留模式的相互作用pre_capture/post_capture定义的是审查项review item周围的时间窗口但真正决定哪些片段落盘的是保留模式retention modemode: all保留捕获窗口内的每一个片段无论是否有运动。mode: motion默认只保留窗口内含有运动的片段。由于对象在动本身就意味着运动含活动跟踪对象的片段会被保留无运动片段即使落在 pre/post 范围内也会被丢弃。mode: active_objects只保留窗口内跟踪对象正在活动的片段仅有一般运动而无活动对象的片段会被丢弃。因此默认motion模式下如果捕获窗口的某些时段没有运动你实际看到的录像会比配置的 pre/post 时长更短。若想保证完整保留预录/后录时长可这样配置record: enabled: True alerts: pre_capture: 10 post_capture: 10 retain: days: 30 mode: all # 保留捕获窗口内的所有片段:::note 由于录像片段按 10 秒分块写入pre-capture 的实际时间取决于片段边界实际预录像画可能比配置值略短或略长。 :::源码侧这个决策落在SegmentInfo.should_discard_segment(retain_mode)maintainer.pyall模式永不丢弃motion模式在motion_count 0或平均 dBFS 非 0有音频活动时保留active_objects模式在active_object_count 0时保留。判定保留后片段才会通过move_segment落地。另外注意cleanup 阶段的保留判定还要求片段与未过期的 review 重叠cleanup.py且motion模式删除motion 0 且 objects 0 且 dBFS 0的片段、active_objects模式删除objects 0的片段。在哪里查看预录/后录像像预录/后录片段包含在录像时间线中可在 History 视图查看。注意pre/post capture 只影响哪些片段被保留在磁盘上不会改变 UI 中审查项的起止点。History 视图仍以审查项实际时间范围为中心但你可以在时间线上前后拖动浏览保留的预录/后录片段。Explore 视图展示的是按跟踪对象实际可见时间裁剪的片段不会反映预录/后录时间。录像保留策略详解Frigate 同时支持连续/运动录像与基于跟踪对象的事件录像二者拥有独立的保留天数和保留模式。:::tip 保留天数支持小数例如可以配置为0.5天。 :::连续录像与运动录像continuous与motion分别控制连续录像、运动录像的保留天数。默认连续录像关闭days默认 0。record: enabled: True continuous: days: 1 # - 连续录像保留天数 motion: days: 2 # - 运动录像保留天数对应 UIEnable recording、Continuous retention Retention days、Motion retention Retention days。连续录像同样支持下文介绍的三种保留模式。从源码看continuous 与 motion 的优先级很有意思validate_and_move_segment会先判断若continuous.days 0则按all模式处理否则若motion.days 0则按motion模式处理maintainer.py从而在片段尚未关联任何审查项时也能尽快决定去留。而 cleanup 计算motion_expire_date时使用max(motion.days, continuous.days)因为运动录像不能比连续录像保留得更短cleanup.py。基于对象的事件录像Alerts / Detections针对标记为告警alert的审查项与普通检测detection的审查项可分别指定录像保留天数record: enabled: True alerts: retain: days: 10 # - 告警录像保留天数 detections: retain: days: 10 # - 检测录像保留天数对应 UIAlert retention Event retention Retention days与Detection retention Event retention Retention days均默认 10 天record.py。此配置会保留与告警/检测重叠的录像片段 10 天。由于多个跟踪对象可以引用同一批录像片段系统避免了为重叠对象存储重复录像从而降低整体存储占用——这正是片段级而非事件级存储管理的价值所在。能否只在特定时间段进行连续录像可以。通过 Frigate UI、Home Assistant 或 MQTT可以自动化让摄像头只在特定情境或时间段录像例如下班时段、传感器触发时。Frigate 的录像状态可通过 MQTT 等机制实时启停具体接入方式参见 MQTT 集成。导出录像与自定义 FFmpeg 导出在 Review 面板中右键桌面端或长按移动端审查项即可导出录像也可以在 History 视图点击 Export 按钮。导出内容通过主导航栏的 Export 视图组织与搜索。带自定义 FFmpeg 参数的导出高级场景可使用自定义导出 HTTP APIPOST /export/custom/{camera_name}/start/{start_time}/end/{end_time}请求体接受ffmpeg_input_args与ffmpeg_output_args用于控制编码、帧率、滤镜等 FFmpeg 选项。若二者都未提供Frigate 默认使用延时摄影time-lapse输出设置25 倍速、30 FPS对应源码中的DEFAULT_TIME_LAPSE_FFMPEG_ARGS见 frigate/api/export.py。以下示例导出 60 倍速、25 FPS 的延时视频{ name: Front Door Time-lapse, ffmpeg_output_args: -vf setptsPTS/60 -r 25 }CPU 回退cpu_fallback若已配置硬件加速但导出失败例如 GPU 不可用在请求体中设置cpu_fallback: true可自动改用软件编码重试{ name: My Export, ffmpeg_output_args: -c:v libx264 -crf 23, cpu_fallback: true }导出安全限制与编码细节非管理员用户不允许使用可访问文件系统的 FFmpeg 参数如-filter_complex、文件路径与协议引用管理员拥有 FFmpeg 参数的完整控制权。配置了hwaccel_args时导出使用硬件编码可通过设置摄像头级hwaccel_args按摄像头覆盖例如摄像头分辨率超过硬件编码器上限时。使用无法识别的值或空字符串将回退到软件编码libx264。为减小输出文件体积可在ffmpeg_output_args中加入-qp nn 为量化参数按需调整质量与体积的平衡。将媒体文件与磁盘同步Media Sync当数据库条目被删除但对应文件仍留在磁盘上时媒体文件事件快照、事件缩略图、审查缩略图、预览、导出与录像会成为孤儿文件。正常运行中 Frigate 的定时清理会处理少量孤儿文件但崩溃、配置变更或升级可能导致 Frigate 不会自动清理的更多孤儿文件。Media Sync 会扫描文件系统并删除数据库未引用的媒体文件。触发方式有两种Frigate UI 的 Maintenance 面板API 端点POST /api/media/sync——调用后返回作业 ID操作在服务器后台继续可通过/api/media/sync/status/{job_id}查询状态。设置verbose: true时会将每个孤儿文件与数据库条目的详细报告写入/config/media_sync/job_id.txt实现见 frigate/jobs/media_sync.py。对于录像报告会区分孤儿数据库条目数据库有记录但磁盘文件缺失与孤儿文件磁盘有文件但数据库无对应记录两类。:::warning 该操作会消耗大量 CPU并内置安全阈值若删除的文件超过总量的 50% 将中止。仅在必要时运行。若设置force: true会绕过安全阈值除非你确认删除是有意为之否则不要使用force。 :::理解存储占用为什么与df/du不一致Frigate 报告的存储占用与操作系统df/du的结果不会完全一致——这是设计使然不是 bug。Frigate 如何统计录像占用Storage Metrics 页面System Storage的Recordings数值与每摄像头的Camera Storage明细是 Frigate数据库中记录的、它自己写入的所有录像片段大小之和并非扫描磁盘得出。这是刻意设计反复遍历整个驱动器求和会让硬盘持续运转并带来无谓的 I/O。而页面旁显示的磁盘total以及 Frigate 决定何时删除录像所依据的剩余空间来自操作系统对挂载在/media/frigate的整个文件系统的报告。因此页面的Unused数值是磁盘总容量减去 Frigate 录像而不是磁盘真实可用空间——只要磁盘上还存了别的东西真实可用空间会更低。什么计入占用以及为何与df对不上只有录像片段/media/frigate/recordings计入录像存储总量。以下内容虽然真实占用磁盘空间但不计入该数值快照与缩略图/media/frigate/clips参见 Snapshots其保留独立于录像。预览视频与审查缩略图同样位于/media/frigate/clips下。导出文件/media/frigate/exports导出永不被保留策略删除。数据库、下载的检测模型、人脸/车牌训练图片位于/config下。增强功能的调试图片/media/frigate/clips启用后车牌识别的debug_save_plates与 GenAI 的debug_save_thumbnails会为排障保存车牌裁剪图与请求图片。这些文件通常就是页面上那个other或看似对不上账的存储来源它是真实的、属于 Frigate 的只是不算在recordings总量里。它们也是Recordings数值与df -h始终存在差距的原因df还额外统计了磁盘上任何非 Frigate 数据、文件系统开销与保留块ext4 默认约保留 5% 给 root所以磁盘可能在录像接近总量之前就显示已满以及刚删除但空间尚未回收的录像。:::tip Storage 页面不是系统级磁盘监控器它展示的是Frigate 录像用了多少空间。要查看真实磁盘占用请在宿主机上使用df -h可用空间与du -sh按目录统计占用。 :::剩余空间与/media/frigate挂载Frigate 报告的是容器内实际挂载到/media/frigate的文件系统的容量与可用空间。如果外接硬盘或网络共享并未真正挂载到该路径例如缺少/etc/fstab条目、容器启动时共享离线、或宿主机未透传该路径容器会回退到宿主机系统盘Frigate 会正确报告这块更小的盘而不是你预期的那块驱动器。若报告容量与你的驱动器不符问题出在挂载而非 Frigate。可在容器内核实实际挂载情况docker exec -it frigate df -h /media/frigate docker exec -it frigate mount | grep media存储卷的配置方式参见安装文档中的存储章节。/tmp/cache是独立的存储区域录像片段先写入/tmp/cache——一块小巧的、基于内存tmpfs的区域通过校验后再移动到/media/frigate/recordings。由于它是独立且容量小/tmp/cache可能在录像盘还有很多空间时就被填满并报出No space left on device错误。两者是不同的存储区域。相关排查缓存填满、片段堆积、探测失败等参见 Recordings 故障排查。指标与磁盘不一致时怎么办因为占用是数据库跟踪的直接在磁盘上删除录像文件、或升级后遗留的文件都不会更新上报的占用甚至可能把占用推到 100% 以上。Frigate 不感知它没记录过的文件也不会自动统计或移除它们。请使用上文 将媒体文件与磁盘同步 来让数据库与磁盘实际内容重新对齐。磁盘空间不足时 Frigate 会删除旧录像吗会。Frigate 持续检查持有/media/frigate/recordings的磁盘的剩余空间。这与累加每个录像的大小不同剩余空间是操作系统已经跟踪的单一数字Frigate 可以即时获取无需遍历文件或唤醒磁盘——这正是它依赖此检查而非扫描驱动器原因。当剩余空间不足约1 小时的录像量按当前录像码率估算不是固定百分比时Frigate 会删除最旧的录像以回收空间并记录日志。这种紧急清理无视保留策略始终先删最旧的录像。基于整盘剩余空间做判断带来两个后果因为检查用的是磁盘真实剩余空间任何占满驱动器的内容——包括非 Frigate 文件——都可能触发对你最旧录像的删除。即使磁盘还有相当比例的可用空间清理也可能发生例如码率高或摄像头多时因为阈值是剩余不足约 1 小时录像余量而不是已用 X%。频繁触发紧急清理通常意味着你的保留配置超出了磁盘容量。请调低保留天数让常规保留清理跟上节奏紧急路径就很少触发了。保留清理的工程实现定时器、删除粒度与安全上限最后从工程实现层面串一遍保留清理的完整链路。清理由独立进程frigate.recording_managerfrigate/record/record.py承载内部同时运行RecordingMaintainer缓存管理与落地与RecordingCleanup过期删除。RecordingCleanupfrigate/record/cleanup.py以record.expire_interval分钟为周期运行默认 60 分钟见 record.py每分钟清理过期临时预览每个周期执行过期审查项删除按alerts.retain.days与detections.retain.days分别计算告警/检测审查项的过期时间戳并删除expire_review_segments。过期录像删除按连续/运动/告警/检测四类保留天数与保留模式逐片段判定是否保留删除时以 100,000 条为一批执行数据库删除expire_existing_camera_recordings并清理不再被引用且过期的预览片段。已删除摄像头的遗留录像按max(continuous.days, motion.days)计算过期线清理配置中已不存在的摄像头的历史录像。空目录回收与 WAL 截断删除后回收空目录当 SQLite WAL 超过MAX_WAL_SIZE时执行PRAGMA wal_checkpoint(TRUNCATE)防止 WAL 无限增长truncate_wal。这套先写 cache → 校验 → 按保留模式与审查项重叠度决定落地 → 定时按保留天数与模式清理的流水线配合基于整盘剩余空间的紧急清理兜底构成了 Frigate 录像存储的完整闭环。理解这些机制后你就可以根据摄像头数量、码率与磁盘容量精确设计适合自己的录像保留方案了。/output文章【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考