Frigate 的实际部署门槛并不算高，真正棘手的往往在于摄像头视频流、解码器、检测器以及事件链路的调试。本文适用场景包括：云上 ECS 接入、边缘小主机本地识别，或在办公环境中通过 Docker Compose 搭建一套完整 NVR。以下这份排查路线，正是针对上述环境的逐层检查方案。
目标环境
部署形式采用 Docker Compose；摄像头通信协议为 RTSP；识别引擎使用 Frigate 内建检测器；联动方式基于 MQTT 或 Home Assistant；存储设备为本地磁盘或挂载目录。
关键目标并非让服务“勉强跑起来”，而是当有人或物体经过时，系统能够稳定生成事件、顺畅联动、并支持录像回放——这才是真正有效的部署。
1. 镜像与版本预检
第一步，拉取 Frigate 镜像并锁定发行版本。容器状态确认稳定后，再进入后续环节。
docker compose pull frigate
docker compose up -d frigate
docker compose ps
docker logs --tail=120 frigate
如果从 GHCR 拉取镜像速度不稳定，可先验证入口连通性：
docker pull ghcr.1ms.run/blakeblackshear/frigate:stable
本层仅负责确认镜像可用、容器正常启动，之后才能顺利进入视频链路检查。
2. RTSP 流检查
使用 ffprobe 直接验证摄像头视频流是否稳定：
ffprobe rtsp://user:pass@camera-host:554/stream1
ffprobe rtsp://user:pass@camera-host:554/stream2
建议将录像流与检测流分开配置：主码流用于录制，低分辨率的子码流专做检测。摄像头网络连通性及账号权限需先单独验证。若 ffprobe 都无法稳定获取流，请优先排查摄像头设备、网络质量及编码设置，无需急于调整 Frigate 配置。
3. 解码设备检查
在小主机或边缘节点上，解码压力直接影响识别稳定性。先确认硬件解码设备是否存在：
ls -lah /dev/dri
docker exec -it frigate ls -lah /dev/dri
对于 Intel iGPU 场景，可在 Docker Compose 中添加设备映射：
services:
frigate:
image: ghcr.io/blakeblackshear/frigate:stable
devices:
- /dev/dri:/dev/dri
若 CPU 长期处于高负载，应优先处理好硬件解码与码流分配，之后再逐步微调检测阈值。
4. 检测器检查
通过日志确认检测器是否正常运行：
docker logs --tail=200 frigate | grep -i detector
docker logs --tail=200 frigate | grep -i model
需重点关注：检测器是否正常启动、模型缓存目录是否具备写入权限、解码设备是否成功挂载到容器、对象配置中是否包含 person、car 等目标、zone 及 mask 设置是否误遮挡了有效区域。
5. 事件、MQTT 与存储
识别成功只是起点，还需确认事件能够发出、录像能够正常保存：
docker logs --tail=160 frigate | grep -i mqtt
ls -lah /path/to/frigate/storage
df -h
若 Home Assistant 无法联动，应优先排查 MQTT 链路；若回放失败，则需检查存储目录的访问权限及磁盘剩余空间。
检查顺序
| 层级 | 命令或动作 | 目的 |
|---|---|---|
| 镜像 | docker compose pull frigate | 确认版本及容器启动正常 |
| RTSP | ffprobe rtsp://... | 验证视频输入流的稳定性 |
| 解码 | 检查/dev/dri或GPU设备 | 降低CPU解码负载 |
| 检测器 | 查看detector日志与模型缓存 | 确保识别链路正常工作 |
| 事件 | 检查MQTT及存储目录 | 确认联动与回放能力 |
小结
Frigate 摄像头检测到有人经过却未生成事件，往往不是单一环节的问题。建议按上述五层顺序逐一排查，再决定是否需要调整检测阈值、更换码流配置或启用硬件解码。镜像入口层解决了部署与版本更新，而 RTSP、FFmpeg、检测器、MQTT 及存储仍需分别验证并确保每层正常。
