Frigate 录像故障排查完全指南从无录像到无法播放的九类问题定位与修复【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate导读本文是 FrigateNVR with realtime local object detection for IP cameras的录像Recordings故障排查手册源自仓库中 docs/docs/troubleshooting/recordings.md 的完整内容并结合 frigate/record/maintainer.py、frigate/video/ffmpeg.py、frigate/config/camera/record.py 等源码做了底层原理印证。读完本文你将掌握录像段从 RAM 缓存落盘到存储的完整生命周期、导致History 为空/No recordings found的三类根因、PIPELINE_ERROR_DECODE播放错误的六步排查法以及四类缓存警告Unable to keep up / Too many unprocessed / Invalid or missing video stream / Error occurred when attempting to maintain recording cache各自的诊断命令与修复手段。一、先理解录像的完整生命周期缓存 → 校验 → 落盘要高效排查录像问题必须先理解 Frigate 处理录像的方式录像段segment先被写入 RAM 缓存/tmp/cache只有在同时满足两个条件时才会被移动到磁盘上的 recordings 目录该段符合某条保留策略retention policycontinuous/motion/alerts/detections至少之一摄像机的record流正在产出有效、可存储的视频。在 frigate/record/maintainer.py 中RecordingMaintainer.move_files()每 5 秒扫描一次缓存目录列出所有非preview_开头的.mp4段文件随后对每个段调用validate_and_move_segment()frigate/record/maintainer.py进行三段式处理探测校验通过get_video_properties()见 frigate/util/services.py检查段内是否存在有效视频流、时长是否落在(0, MAX_SEGMENT_DURATION)区间内MAX_SEGMENT_DURATION 600秒见 frigate/const.py。校验失败的段被直接删除并记录告警保留策略判定先尝试匹配最高优先级的continuous/motionSegmentInfo.should_discard_segment()见 frigate/record/maintainer.py再检查段是否与 review item警报/检测事件重叠落盘通过move_segment()frigate/record/maintainer.py用 ffmpeg 以-c copy不转码-movflags faststart的方式从缓存拷贝到RECORD_DIR即容器内/media/frigate/recordings见 frigate/const.py并按%Y-%m-%d/%H/camera/MM.SS.mp4UTC 时间组织目录结构。排查起点先为录像维护器开启 debug 日志观察段是否真的落盘了logger: logs: frigate.record.maintainer: debug健康时你会看到类似Copied /media/frigate/recordings/{segment_path} in 0.2 seconds的日志源码中的 debug 日志见 frigate/record/maintainer.py。如果从未出现这类日志说明没有任何段到达磁盘问题大概率出在下面的摄像机/流或存储挂载类别中。二、录像是空的三类根因按优先级排查如果实时画面正常、但 History 视图为空或提示 No recordings found for this time几乎总是下面三类原因之一。请按顺序排查——保留策略配置是最常见的原因。2.1 保留配置问题2.1.1 已开启 recording 但什么都没保存最常见单独设置record.enabled: True不会保留任何录像连续录像continuous recording默认是关闭的缓存中的段只有符合已配置的保留策略时才会被移动到磁盘。你必须配置continuous、motion、alerts、detections中的至少一个。最保守的配置保存所有视频是启用连续保留record: enabled: True continuous: days: 3 # keep all footage for 3 days底层印证在 frigate/config/camera/record.py 中RecordConfig.enabled默认Falsecontinuous是一个RecordRetainConfigdays默认 0即默认不保留而 frigate/record/maintainer.py 中record_config.continuous.days 0才会进入连续保留分支。days: 0表示完全关闭该保留通道。更多常用配置包括省存储方案、仅保留 alerts 等参见 Recording 配置文档。2.1.2 仅按运动/事件保留时保存量低于预期如果只配置了motion、alerts或detections保留没有continuousFrigate 会根据保留mode选择性保存mode: motion默认只保留包含运动的段。如果你的 运动遮罩 覆盖了活动发生区域或运动灵敏度太低即使录像开着也什么都留不下来mode: active_objects只保留存在正在运动的被跟踪对象的段mode: all保留时间窗口内的所有段。对应源码frigate/config/camera/record.py 定义了RetainModeEnumall/motion/active_objectsReviewRetainConfig.mode默认motionfrigate/record/maintainer.py 的should_discard_segment()实现了三种模式的判定逻辑。如果你期望的是连续录像、却只配了运动/事件保留请按上面的方式补一个continuous保留周期。要验证运动是否真的被检测到可在 debug 视图中观察运动框或在 UI 的 Motion Tuner 中调整。2.1.3 alerts / detections 录像依赖对象检测正常运行alerts和detections保留只保存与被跟踪对象重叠的录像段因此它们依赖对象检测正常工作必须开启检测。如果detect: enabled: False永远不会产生 alerts 或 detections相应地这两类保留也保存不到任何东西。continuous和motion保留在检测关闭时仍可正常工作。对象必须被当前模型支持。如果你跟踪的是模型不支持的类别例如在默认模型上跟踪deer或license_plateFrigate 永远不会检测到它、也就永远不会为它录像。请检查日志中形如... is configured to track [deer] objects, which are not supported by the current model的警告该告警的生成见 frigate/config/config.py移除不支持的对象或切换到包含这些类别的模型例如 Frigate。2.1.4 在遵循过时的教程配置键在不同大版本之间会变化。例如旧的clips配置已经很久不存在了。如果你从旧博客或视频复制了配置请对照当前的 参考配置 逐一核对每个键。2.2 摄像机与流问题2.2.1 不兼容的音频编码录像静默保存失败Frigate 把录像存进MP4 容器而某些摄像机音频编码最常见的是pcm_alaw、pcm_mulaw及其他 G.711 变体无法放入 MP4 容器。此时 ffmpeg 写段失败、录像无法保存——即使实时画面完全正常。这在 Tapo、TP-Link VIGI 以及部分 Reolink 摄像机上经常发生。使用合适的 ffmpeg 预设 把音频转码为 AAC或干脆去掉音频cameras: your_camera: ffmpeg: output_args: record: preset-record-generic-audio-aac # transcode audio to AAC # or preset-record-generic to record with no audio底层印证preset-record-generic在 frigate/ffmpeg_presets.py 中输出-an丢弃音频preset-record-generic-audio-aacfrigate/ffmpeg_presets.py输出-c:v copy -c:a aac视频原样拷贝、音频转 AAC。注意默认的 record 输出预设本身就是preset-record-generic-audio-aac见 frigate/config/camera/ffmpeg.py测试用例 frigate/test/test_ffmpeg_presets.py 也验证了该预设最终展开为-c:v copy -c:a aac。如果你的源流本来就是 AAC可改用preset-record-generic-audio-copy避免无谓的转码。2.2.2 record 流没有连上看到No new recording segments were created for camera in the last 120s说明 ffmpeg 无法读取record流。诊断步骤确认摄像机ffmpeg.inputs中确实有一个流被赋予了record角色打开 go2rtc 的 Web 界面端口1984逐个点击流确认能否播放。wrong response on DESCRIBE、start from CONN state等 go2rtc 报错说明与摄像机的连接正在失败在 VLC 或ffplay中用完整的 RTSP URL正确的路径、端口、凭据实测如果你通过 go2rtc 转播restream确保record输入路径指向正确的 go2rtc 流名。在不同摄像机之间复制配置而忘了改流名是常见错误。底层印证该报错由 frigate/video/ffmpeg.py 触发——record_stale_threshold取max(120, 2 * segment_time 30)frigate/video/ffmpeg.py当在阈值窗口内既没有新缓存段、也没有新有效段、或自上次无效段之后一直没有新有效段时Frigate 会重启该摄像机的 record ffmpeg 进程。重启是恢复手段而非原因。2.3 存储与挂载问题2.3.1 存储卷没有正确挂载如果录像卷/media/frigate指向了错误的位置、不可写或网络/加密挂载在启动时失败Frigate 要么无法保存录像要么静默写入启动盘、随后因磁盘看起来比预期小得多而被激进清理。把宿主机真实容量df -h与 Frigate UI 中Storage页面显示的数值对比。若不一致例如 Frigate 显示约 220 GB 而你的存储盘是 4 TB说明 bind mount 解析到了错误的文件系统核对 Dockervolumes映射中的宿主机路径- /your/storage:/media/frigate确实存在且对容器可写对于可能间歇性失败的挂载可在空目录上用chattr i保护挂载点这样挂载缺失时 Frigate 会直接报错而不是静默写入启动盘在录像消失的时间点附近检查dmesg与系统日志寻找文件系统或 I/O 错误。如果录像确实在写、但拷贝速度跟不上参见下文 Unable to keep up with recording segments。三、录像无法播放PIPELINE_ERROR_DECODE 六步排查法3.1 错误来源来自浏览器而非 Frigate当录像在 Frigate UI 中无法播放、并出现Failed to play recordings (error 3): PIPELINE_ERROR_DECODE时这条消息来自你的浏览器。PIPELINE_ERROR_DECODE只由Chromium 系浏览器Chrome、Edge、Brave、Vivaldi、Opera、Arc以及许多 App 内浏览器使用的 Android WebView的媒体管线发出代表浏览器无法解码录像中的某个视频或音频包。WebKit 浏览器Safari对同一底层问题报不同的消息通常是Media failed to decode或DECODER_ERROR_NOT_SUPPORTED。Frigate 把record流不做重编码地拷到磁盘所以浏览器必须解码摄像机原始产出的码流——而 Chromium 的解码器对畸形/非标准媒体的容忍度远低于 VLC 或 ffmpeg。⚠️警告同一段录像在 VLC 中完美播放、用ffprobe/ffmpeg解码干净、甚至 MP4 容器结构合法都不代表浏览器能解码。VLC 和 ffmpeg 对编码器怪癖和损坏包比浏览器媒体管线宽容得多所以合法文件照样可能触发PIPELINE_ERROR_DECODE。这超出了 Frigate 的控制范围——Frigate 从不修改录像流。3.2 Step 1确认是浏览器问题在Firefox或Safari中打开同一段录像。Firefox 和 Safari 使用不同的媒体引擎不可能产生PIPELINE_ERROR_DECODE如果它们能正常播放就确认了这是客户端解码器问题而非坏录像。换浏览器只是临时绕过下面几步才是根治 Chromium 系的方案。3.3 Step 2排除 H.265 / HEVC浏览器对 H.265 (HEVC) 的支持取决于操作系统、GPU、硬件加速和浏览器版本是此错误最常见的原因。按可靠性从高到低改录 H.264。把摄像机record/主码流配置为 H.264——这是浏览器兼容性最好的编码。参见 摄像机设置建议。用 go2rtc 转码为 H.264。如果必须保留 HEVC让 go2rtc 对录像流重编码。这会增加 CPU 占用追加#hardware可在可用时使用 GPUgo2rtc: streams: your_camera: # transcode video to h264 and audio to aac; #hardware uses the GPU if available - ffmpeg:rtsp://user:passwordCAMERA_IP:554/stream#videoh264#audioaac#hardware cameras: your_camera: ffmpeg: inputs: - path: rtsp://127.0.0.1:8554/your_camera input_args: preset-rtsp-restream roles: - record注意#videoh264参数只在ffmpeg:源模块下生效把它加到一个普通rtsp://go2rtc 源上是无效的。保留 HEVC 但提升兼容性。如果你的浏览器和系统支持 HEVC可以给摄像机设置apple_compatibility。某些播放器Safari 及其他客户端要求特定的 HEVC 流格式该选项用于修正这一格式cameras: your_camera: ffmpeg: apple_compatibility: true你可能还需要在浏览器中开启 HEVC 与硬件解码例如 Chrome 的 设置 → 系统 → 使用硬件加速如可用。HEVC 的硬件支持因 GPU、操作系统和浏览器版本差异很大。底层印证apple_compatibility是 frigate/config/camera/ffmpeg.py 中定义的一个布尔配置项属于摄像机 ffmpeg 配置模型。3.4 Step 3清理摄像机发出的损坏包如果错误是间歇性的刷新页面后同一段录像又能播或播放一段时间后才失败很可能是摄像机偶发输出损坏/畸形包——某些机型比别家更容易这样。即使不换编码把流经 go2rtc 的ffmpeg模块转发一次往往就能把流清理到浏览器可解码的程度go2rtc: streams: your_camera: - ffmpeg:rtsp://user:passwordCAMERA_IP:554/stream#videoh264#audioaac3.5 Step 4修复不兼容或损坏的音频音频是最常见的元凶之一——音频轨解码失败会拖垮整段录像。请确保摄像机输出AAC音频用 go2rtc 把音频转码为 AAC#audioaac或干脆去掉音频。参见上文 不兼容的音频编码 中基于预设的做法。3.6 Step 5避开智能/编码检查关键帧间隔关闭摄像机上的任何Smart Codec、H.264或H.265特性。这些非标准模式会在流中动态改变编码参数、丢弃关键帧恰好产生浏览器拒绝解码的那种包。它们也会导致 录像段只有约 1 秒。把摄像机的I 帧关键帧间隔设为与帧率相等例如 20 fps 就设20。过长的关键帧间隔会拖慢起播并更容易引发解码错误。3.7 Step 6考虑码率与客户端硬件浏览器是本地解码的所以对一台设备来说过高的流可能在另一台上正常超高码率或分辨率例如 4K/8MP 的 HEVC 主码流可能压垮低功耗平板、手机或 SBC导致解码器停滞。在台式机上试同一段录像如果台式机正常就调低摄像机码率或录制更低分辨率的子码流。报错里点名了客户端 GPU 解码器例如VaapiVideoDecoder: failed Initialize()ing the frame pool说明是浏览器硬件解码问题。切换浏览器的硬件加速开关开或关通常能解决这类问题。3.8 附带问题录像有声音没画面或完全无法播放Frigate 直接拷贝record流而不重编码所以能否播放取决于浏览器是否支持摄像机的编码。H265/HEVC 录像在某些浏览器里无法播放。如果录像表现为只有音频或黑屏多半是摄像机在发送浏览器无法解码的编码——把摄像机配置为输出H264以获得最大兼容性。如果播放失败伴随明确的PIPELINE_ERROR_DECODE或Media failed to decode请直接走上面的 六步排查法。四、缓存警告与错误4.1 Invalid or missing video stream in segment ... Discarding.每一段录像在离开缓存前都要经过校验。Frigate 会探测/tmp/cache中每个已完成的.mp4见 frigate/record/maintainer.py要求有可读的视频流和合法的时长才会搬入存储校验失败的段会被删除那约 10 秒的画面就丢了。这条校验产生三种消息Invalid or missing video stream in segment path. Discarding.—— 段内没有视频或完全无法读取Failed to probe corrupt segment path后接Discarding a corrupt recording segment: path—— 段能读但时长无法确定duration -1见 frigate/record/maintainer.py单独一条Discarding a corrupt recording segment: path—— 段的时长非法为空或超过十分钟指向摄像机送出的损坏时间戳。对上述每一种情况摄像机 watchdog 还会记录Invalid recording segment detected for camera at timestamp见 frigate/video/ffmpeg.py。⚠️警告这几乎总是摄像机或网络问题而不是 Frigate 的问题。一段录像只有在 ffmpeg 写完它之后才算完整任何在中途打断流的事情都会留下一个无法保存的文件。Frigate 只是在报告这个中断而不是制造它。先从摄像机和网络入手摄像机断开了连接。摄像机重启、切夜视模式时重新初始化流、过载或超出并发连接数时踢掉客户端都很常见。把所有从摄像机拉流的东西数一遍Frigate 的 detect 流和 record 流、go2rtc、手机 App、其他 NVR每一样都占一个连接。把各角色都收敛到单一 RTSP restream 上让摄像机始终只看到一个连接往往单凭这一点就能解决。到摄像机的链路不可靠。WiFi 摄像机、电力猫、饱和的上行链路、故障交换机端口、劣质网线都会产生这种模式而且通常一次只影响一台摄像机。WiFi 摄像机本身就不被推荐。摄像机无法稳定送出被要求的内容。高码率 4K 流可能超过摄像机自身在负载下的编码与推送能力。降低码率或录制更低分辨率的子码流。摄像机启用了 Smart Codec、H.264 或 H.265。这些模式在流中改变编码参数正是损坏段变体背后的坏时间戳来源。关掉该模式并把关键帧间隔设为与帧率相等。参见 录像段只有约 1 秒。围绕第一次出现该错误的位置阅读 Frigate 和/或 go2rtc 日志。当摄像机或网络有故障时其他消息会同时出现例如No frames received from camera in 20 seconds、Non-monotonic DTS、RTP: PTxx: bad cseq、error while decoding MB或连接超时——每一条都在 Common error messages 中有解释。要确认摄像机是源头可以在 go2rtc Web 界面端口1984见 go2rtc 排障打开它的流或在 VLC 中播放同一个 URL并让它运行足够久、直到故障再次出现。摄像机与网络都没问题时录像存不下的音频。有些摄像机发送 G.711 音频无法存入 MP4导致段无法收尾。参见 不兼容的音频编码。Frigate 本身被停止或重启。重启前后每个摄像机出现一条此类警告属正常无需处理。系统空间或内存耗尽。/tmp/cache满了或宿主机因内存占用过高杀掉了 Frigate都会截断正在写入的段。两者都会在日志中留下其他错误。参见 Errno 28No space left on device。4.2 No new recording segments were created ... Restarting the ffmpeg record process...当一台摄像机连续两分钟没有产出可用录像时Frigate 会重启该摄像机的 record 进程以尝试恢复。措辞会告诉你录像卡在哪一步No new recording segments were created缓存里根本没出现新段文件说明 ffmpeg 没有从 record 流拿到视频。摄像机不可达或拒绝连接、流 URL/路径/凭据错误或摄像机接受了连接却什么也不发。参见上文 record 流没有连上。No new valid recording segments were created与No valid segments created since last invalid segment录像在源源不断到达但始终通不过校验——摄像机送出了无法保存的视频。参见上文 Invalid or missing video stream。重启是 Frigate 在从问题中恢复而不是制造问题。摄像机重启或短暂网络中断后出现一次属于正常。如果每两三分钟就重复出现说明摄像机或网络仍在失败而且重启会扩大损失——每次重启都会截断正在写入的段。请从该摄像机日志中最早的那次失败入手排查而不是盯着重启本身。底层印证完整的三种措辞分支见 frigate/video/ffmpeg.py。其中record_stale_threshold至少 120 秒max(120, 2 * segment_time 30)frigate/video/ffmpeg.py与消息中的 in the last 120s 对应。4.3 Unable to keep up with recording segments in cache 警告缓存段搬移速度跟不上这条警告意味着录像维护器把段从 RAM 缓存搬到磁盘的速度不够快。缓存填满后Frigate 会丢弃最旧的段以避免内存耗尽崩溃——你因此丢失已录画面。这几乎总是存储吞吐或系统资源问题。Step 1开启录像 debug 日志第一步是测量每段从 RAM 缓存搬到磁盘耗时多久。为录像维护器开启 debug 日志logger: logs: frigate.record.maintainer: debug这会为每段添加拷贝耗时的日志行DEBUG : Copied /media/frigate/recordings/{segment_path} in 0.2 seconds.让它一直运行到警告开始出现以便确认错误发生的那一刻磁盘是否真的在变慢。Step 2解读拷贝耗时持续超过约 1 秒存储跟不上录像的写入速度。继续 Step 3–5 诊断慢存储。持续远低于 1 秒存储足够快问题更可能是 CPU 或资源争用。跳到 Step 6。Step 3检查 RAM、swap、缓存与磁盘占用如果 CPU、RAM、磁盘吞吐或总线 I/O 不足Frigate 内部做什么都没用。在警告出现期间逐一检查系统资源。Linux 下可用的诊断工具/命令docker statshtopiotop -oiostat -sxy --human 1 1vmstat 1在现代 Linux 内核上只要启用了 swap系统就会用一部分。把vm.swappiness1已不再意味着内核只在避免 OOM 时才 swap。要防止容器内发生任何 swap请把内存与内存swap 分配设为相同值并禁用 swapDocker Compose 示例services: frigate: ... mem_swappiness: 0 memswap_limit: MAXSWAP deploy: resources: limits: memory: MAXRAM运行命令示例--memoryMAXRAM --memory-swapMAXSWAP --memory-swappiness0注意这些是容器的硬上限务必在docker stats显示的用量之上留足余量——一旦触及MAXRAM容器会立即停止。一般而言让所有 cache 和 tmp 文件占用的空间保持在 RAM 中优于在可行时落到磁盘 I/O 上。Step 4检查存储类型把录像存到网络共享是流行做法但可能降低拷贝速度并引发问题。有用户发现改用NFS 替代 SMB后拷贝耗时显著下降、问题消失。同时务必确保运行 Frigate 的设备与网络共享之间的网络连接稳定且快速——饱和或不可靠的链路会让拷贝停滞。Step 5检查挂载选项有用户发现通过fstab以sync选项挂载磁盘会大幅降低性能、导致此问题改用async后拷贝耗时大幅下降。Step 6排除 CPU 负载如果拷贝耗时始终低于 1 秒却仍看到警告说明机器 CPU 负载过高Frigate 拿不到足够资源来跟上。试试临时关停其他服务、以及任何吃资源的 Frigate 功能看问题是否改善。底层印证该警告在 frigate/record/maintainer.py 中产生——当某个摄像机的已处理段数超过MAX_SEGMENTS_IN_CACHE 6见 frigate/const.py时move_files()丢弃最旧的段并保留最近 6 个消息文本与文档中的示例完全一致。4.4 Too many unprocessed recording segments in cache 警告检测流掉队这条警告意味着受影响摄像机的detect 流落后或停止处理帧了。录像缓存中堆着等待检测器分析的段当未处理的段超过 6 个时Frigate 会丢弃最旧的段以防缓存占满。⚠️警告此错误是症状而非根因。真正的根因总是在这些消息开始出现之前就已记录在日志里。你必须从 Frigate 启动开始、通读到该警告第一次出现的完整日志才能找到真正的问题。Step 1拿到完整日志收集从启动到错误首次出现的完整 Frigate 日志。寻找在 Too many unprocessed 消息之前出现的错误或警告——根因就在那里。Step 2检查缓存目录进入 Frigate 容器检查录像缓存docker exec -it frigate ls -la /tmp/cache每台摄像机应该只有少量.mp4段文件。如果某台摄像机的文件数明显多于其他摄像机它就是问题源头。单台摄像机的问题会级联导致所有摄像机都报此错。Step 3验证段时长录像段应当约为 10 秒。用ffprobe检查缓存中的段docker exec -it frigate ffprobe -v error -show_entries formatduration -of defaultnoprint_wrappers1 /tmp/cache/camerasegment.mp4如果段只有约 1 秒而非 10 秒说明摄像机在发送损坏的时间戳导致段被切得过碎、缓存以预期 10 倍的速度被填满。短段的常见原因摄像机开启了 Smart Codec 或 Smart这类功能在流中动态改变编码参数会破坏时间戳。在摄像机设置里关掉它们流中途中改变编码、码率或分辨率活动流期间的任何编码变更都可能造成不可预期的切段摄像机固件缺陷到摄像机厂商官网检查固件更新。提示不必手跑ffprobe也能抓到它。打开某摄像机的Camera Probe Info对话框System → Metrics → Cameras 页面上的信息图标查看Keyframe analysis部分。它会探测 record 流并标记稀疏或变化的关键帧——这正是智能/ 编码H.264/H.265和过长关键帧间隔产生的现象。Step 4检查检测器卡死如果 detect 流不处理帧段就会堆积。常见原因检测分辨率过高用子码流做检测不要用全分辨率主码流检测 FPS 过高检测推荐上限为 5 fps模型过大用更小的模型变体例如 YOLOs或t尺寸而非e或x。除非你有强劲的专用检测器否则用 320x320 输入而非 640x640虚拟化在虚拟机尤其是 Proxmox里跑 Frigate 可能导致检测器挂起或停滞。这是虚拟化环境下 GPU/TPU 直通passthrough的已知问题Frigate 无法修复。推荐在裸金属上以 Docker 运行 Frigate。Step 5检查 GPU 挂起在宿主机上检查dmesg中与 GPU 相关的错误dmesg | grep -i -E gpu|drm|reset|hang类似trying reset from guc_exec_queue_timedout_job的 GPU 重置/挂起消息说明是驱动或硬件问题。确保内核和 GPU 驱动尤其是 Intel是最新的。Step 6验证硬件加速配置错误的hwaccel_args预设可能让 ffmpeg 静默失败或狂吃 CPU把检测器饿死。升级 Frigate 后确认预设与你的硬件匹配例如用preset-intel-qsv-h264而非已废弃的preset-vaapi对 h265 摄像机使用对应的 h265 预设例如preset-intel-qsv-h265注意hwaccel_args只对 detect 流有效。Frigate 不解码 record 流。Step 7验证 go2rtc 流配置确保 go2rtc 配置中的 ffmpeg 源名与正确的摄像机流匹配。流名配错例如从一台摄像机复制配置到另一台却没更新流引用会导致用到错误的流或整条流直接失败。Step 8检查系统资源如果以上都不适用问题可能是整体资源受限。在宿主机上监控CPU 占用CPU 过载会阻止检测器跟上RAM 与 swap过度 swap 会大幅拖慢所有 I/O磁盘 I/O用iotop或iostat检查是否饱和存储空间确认 Frigate 存储卷有可用空间查看 Frigate UI 的 Storage 页面。可以尝试临时禁用genai、face_recognition等吃资源的功能看问题是否缓解——这有助于定位检测器是否被饿死。底层印证该警告在 frigate/record/maintainer.py 中产生——未处理段数缓存段数减去已处理段数超过 6 时触发文本与文档完全一致。4.5 Error occurred when attempting to maintain recording cache这条消息意味着录像维护器在把段从缓存搬到磁盘时出错。它只是一个通用包装真正的根因总是记录在紧挨着的下一行。Frigate 通常会自行恢复并继续运行但受影响的段会丢失所以值得解决。⚠️警告一定要读这条消息紧随其后的一行。单独一条Error occurred when attempting to maintain recording cache什么也说明不了下一行的异常例如[Errno 28] No space left on device或[Errno 17] File exists才是真问题。对应源码frigate/record/maintainer.py 中move_files()的异常被捕获后先打这条 error、再打异常对象本身与文档描述完全一致。因为这些是操作系统级错误必须在宿主机上解决而不是改 Frigate 配置。最常见的底层错误如下。[Errno 28] No space left on deviceFrigate 写入的文件系统满了。需要检查录像卷真的满了。用df -h检查宿主机上映射到/media/frigate的路径的剩余空间并查看 Frigate UI 的Storage页面磁盘显示有剩余空间却仍然满。这通常意味着文件系统用光了inode用df -i检查或因为错误的 bind mount录像落到了一个比预期更小的文件系统上。参见上文 存储卷没有正确挂载/tmp/cache满了。如果你把/tmp/cache挂成了小容量的tmpfs段的积压会填满它。增大 tmpfs 容量或解决段堆积的根源参见上文 Too many unprocessed recording segments宿主机在 Frigate 清理之前就阻止了写入。在某些系统上例如设置了填满阈值的 Unraid宿主机在 Frigate 的紧急清理运行之前就禁止写入。在卷上留出更多余量或降低保留天数让 Frigate 更早清理。[Errno 17] File exists伴随 ffmpeg Error writing trailer 或 unable to re-open output file诸如[Errno 17] File exists: /media/frigate/recordings/.../camera常伴随 ffmpeg 报错Unable to re-open ... output file for shifting data或Error writing trailer: No such file or directory是**不可靠网络共享NFS 或 SMB**的典型特征——挂载在掉线、提供过期的目录条目或对文件锁处理不当。确认到 NAS 的网络连接稳定且快速。间歇性链路会零星产生这些错误录像挂载优先用 NFS 而非 SMB不少用户发现 NFS 更可靠也更快复查fstab/挂载选项中损害一致性或性能的设置参见上文 Unable to keep up 一节 中syncvsasync的说明开启frigate.record.maintainer的 debug 日志确认错误是否与共享变得不可用同步发生。引用了你手动重命名或删除的摄像机的错误如果下一行错误引用了一个配置中已不存在的摄像机名说明重命名或删除操作在持久化的/tmp/cache卷中留下了孤儿数据。按 安装文档 的推荐用tmpfs挂载/tmp/cache可避免旧摄像机名下的残留缓存文件在重启后存活从根本上杜绝此问题如果错误持续存在停止 Frigate 并从/tmp/cache中清除旧摄像机名遗留的段文件。五、其他录像问题5.1 我只配了运动录像为什么没运动时也在录你需要用运动遮罩把摄像机的时间戳遮掉。即使场景中没有运动你的运动设置灵敏度也可能高到把时间戳当成运动如果开启了音频检测请记住高于min_volume的音频会被视为运动对应源码只有 RMS 音量 ≥audio.min_volume才触发音频检测见 frigate/events/audio.py配置项定义于 frigate/config/camera/audio.py调整 运动检测设置——既可以直接改配置文件也可以用 UI 的 Motion Tuner。5.2 重启 Frigate 或重建容器后时间轴预览是黑的拖动 History 时间轴时出现的 scrubbing 预览timelapse 片段、副摄像机预览以及悬停 review 卡片时播放的预览都不是连续录制的。Frigate 在每小时中把低分辨率预览帧缓存在/tmp/cache只在**整点top of the hour**把它们组装成一个完成的预览片段。在推荐配置下/tmp/cache是一个小的内存型tmpfs区域。Frigate 启动时会尝试恢复当前小时的缓存帧所以从 UI 做**软重启soft restart**可以保留它们但如果你重建 Docker 容器或在某小时中途以任何其他方式强制停止 Frigate内存缓存会被丢弃那个不完整小时就不会生成预览片段。这是预期行为不是 bug已完成的整点预览已写入磁盘不受影响重启后的下一个完整小时会正常生成预览这与shm_size无关增大共享内存不会改变这一点。要避免这个空档请尽量使用 UI 设置菜单里的Restart Frigate按钮而不是重建容器。六、总结按日志消息对号入座的排查速查表现象 / 日志消息首选排查方向关键源码位置History 为空 / No recordings found保留策略continuous/motion/alerts/detections至少配一个frigate/config/camera/record.py只配了运动/事件保留但保存量少retain.modemotion/active_objects/all与运动遮罩frigate/record/maintainer.pyalerts/detections 什么都不存检测是否开启、模型是否支持该对象frigate/config/config.py录像静默不保存音频编码G.711 → MP4 不兼容改用preset-record-generic-audio-aacfrigate/ffmpeg_presets.pyNo new recording segments were created...record 流连接、RTSP URL、go2rtc 流名frigate/video/ffmpeg.pyPIPELINE_ERROR_DECODE浏览器解码问题H.265→H.264、音频 AAC、智能编码、关键帧间隔见 三、录像无法播放Invalid or missing video stream in segment摄像机/网络中断、音频、空间/内存frigate/record/maintainer.pyUnable to keep up with recording segments存储吞吐NFS/SMB、sync/async、内存与 swap 限制frigate/record/maintainer.pyToo many unprocessed recording segmentsdetect 流掉队检测配置、GPU 挂起、虚拟化、资源frigate/record/maintainer.pyError occurred when attempting to maintain recording cache读下一行异常Errno 28磁盘满/Errno 17网络共享frigate/record/maintainer.py排查时始终记住两条底层原则Frigate 从不重编码录像流拷贝即-c copy所以浏览器能不能播与ffmpeg 能不能写取决于摄像机码流本身的合规性Frigate 只报告问题、不制造问题——段不完整、时间戳损坏、存储掉线根源几乎都在摄像机、网络或宿主机一侧。从最早的那条日志开始查起通常就能找到答案。【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考