frigate-configurator

Frigate NVR 配置专家

全面的 Frigate NVR 配置支持，包含优化的 YAML 生成、检测器设置和故障排查。

开始之前

这项技能可避免 12 多种常见错误，并节省约 60% 的 Frigate 配置令牌用量。

指标	不使用技能	使用技能
设置时间	2-4 小时	30-45 分钟
常见错误	12+	0
令牌用量	~15,000	~6,000

这项技能可避免的已知问题

1. 共享内存分配不足导致总线错误
2. 分辨率配置错误导致画面发绿或失真
3. 使用网络存储存放 SQLite 数据库时出现数据库锁定错误
4. 默认会剥离音频，导致录制内容缺少音频
5. 在 Docker 中使用 localhost 导致 MQTT 连接失败
6. 缺少设备透传导致无法检测到 Coral TPU
7. 缺少硬件加速导致 CPU 使用率过高
8. 时间戳上未设置运动遮罩导致误报
9. required_zones 配置错误导致未触发警报
10. h265 视频流未经转码导致录制内容损坏
11. 缺少 STUN 配置导致 go2rtc WebRTC 连接失败
12. detect 视频流分辨率错误导致漏检

快速开始

第 1 步：创建最简配置

mqtt:
  enabled: false

cameras:
  front_door:
    ffmpeg:
      inputs:
        - path: rtsp://user:[email protected]:554/stream1
          roles:
            - detect
    detect:
      width: 1280
      height: 720
      fps: 5

原因： 先从绝对精简的配置开始，在增加复杂内容之前验证摄像头连接。Frigate 要求显式指定 detect 视频流角色。

第 2 步：添加硬件加速检测器

detectors:
  coral:
    type: edgetpu
    device: usb

# OR for Intel with OpenVINO:
detectors:
  ov:
    type: openvino
    device: GPU

原因： 不建议在生产环境中使用 CPU 检测。即使只有一个 USB Coral TPU，也能显著降低 CPU 使用率并缩短检测延迟。

第 3 步：启用录制并设置保留策略

record:
  enabled: true
  retain:
    days: 1
    mode: motion
  alerts:
    retain:
      days: 14
  detections:
    retain:
      days: 7

cameras:
  front_door:
    ffmpeg:
      inputs:
        - path: rtsp://user:[email protected]:554/stream1
          roles:
            - detect
        - path: rtsp://user:[email protected]:554/stream2
          roles:
            - record

原因： 使用不同的视频流进行 detect（低分辨率）和 record（高分辨率），以优化性能。保留模式可防止存储空间耗尽。

关键规则

务必做到

• 使用与摄像头实际分辨率一致的 width 和 height（通过 VLC 确认）
• 将 detect fps 设为 5-10（更高会浪费资源，更低则会漏掉事件）
• 使用不同的视频流进行 detect（子码流）和 record（主码流）
• 在 Docker 中分配足够的 shm-size（每个摄像头至少 64MB）
• 为时间戳叠加层和持续运动的区域创建运动遮罩
• 使用环境变量存储凭据：{FRIGATE_RTSP_PASSWORD}
• 先在 VLC 中测试 RTSP URL，再添加到 Frigate 配置中

绝不要这样做

• 绝不要在 Docker 容器中将 MQTT 地址设为 localhost 或 127.0.0.1
• 绝不要将 detect 分辨率设为高于 1280x720（这会浪费检测器算力）
• 绝不要在未指定保留策略的情况下启用录制
• 绝不要在不迁移数据库的情况下将 /media/frigate 挂载到网络存储
• 绝不要混用多种用于目标检测的检测器类型（例如 Coral + OpenVINO）
• 绝不要在未显式配置的情况下使用 UDP RTSP 传输（默认使用 TCP）

常见错误

错误：

cameras:
  cam1:
    ffmpeg:
      inputs:
        - path: rtsp://192.168.1.100/stream
          roles:
            - detect
            - record
    detect:
      width: 1920
      height: 1080
      fps: 30

正确：

cameras:
  cam1:
    ffmpeg:
      inputs:
        - path: rtsp://192.168.1.100/substream
          roles:
            - detect
        - path: rtsp://192.168.1.100/mainstream
          roles:
            - record
    detect:
      width: 1280
      height: 720
      fps: 5

原因： 使用 1080p@30fps 进行检测会浪费资源。检测在 720p 或更低分辨率、5fps 下效果最佳。检测始终使用摄像头的子码流，录制则使用主码流。

已知问题预防

问题	根本原因	解决方案
总线错误	共享内存不足	在 docker-compose 中设置 shm-size: 256mb
数据库已锁定	SQLite 位于网络存储上	使用 database.path: /config/frigate.db
视频偏绿／失真	配置中的分辨率错误	使分辨率与摄像头的实际输出分辨率一致
录像无音频	默认移除音频	使用 preset-record-generic-audio-aac
MQTT 连接失败	Docker 中使用了 localhost	改用主机 IP 地址
未检测到 Coral	缺少设备直通配置	将 /dev/bus/usb 添加到 Docker 设备列表
CPU 使用率高	未配置硬件加速	添加合适的预设（vaapi/qsv/nvidia）
缺少提醒	未设置 required_zones	使用 review.alerts.required_zones 配置区域
UDP 流失败	Frigate 默认使用 TCP	将 preset-rtsp-udp 添加到输入参数

配置参考

config.yml 结构

# MQTT Configuration (optional but recommended)
mqtt:
  enabled: true
  host: 192.168.1.50
  port: 1883
  user: "{FRIGATE_MQTT_USER}"
  password: "{FRIGATE_MQTT_PASSWORD}"

# Detector Configuration
detectors:
  coral:
    type: edgetpu
    device: usb  # or pci for M.2/PCIe

# Global Object Settings
objects:
  track:
    - person
    - car
    - dog
    - cat
  filters:
    person:
      min_area: 5000
      max_area: 100000
      threshold: 0.7

# Recording Settings
record:
  enabled: true
  retain:
    days: 1
    mode: motion
  alerts:
    retain:
      days: 14
  detections:
    retain:
      days: 7

# Snapshot Settings
snapshots:
  enabled: true
  retain:
    default: 7

# Camera Configuration
cameras:
  front_door:
    enabled: true
    ffmpeg:
      inputs:
        - path: "rtsp://{FRIGATE_RTSP_USER}:{FRIGATE_RTSP_PASSWORD}@192.168.1.100:554/stream1"
          input_args: preset-rtsp-restream
          roles:
            - detect
        - path: "rtsp://{FRIGATE_RTSP_USER}:{FRIGATE_RTSP_PASSWORD}@192.168.1.100:554/stream0"
          input_args: preset-rtsp-restream
          roles:
            - record
      output_args:
        record: preset-record-generic-audio-aac
    detect:
      width: 1280
      height: 720
      fps: 5
    motion:
      mask:
        - 0,0,200,0,200,100,0,100  # Timestamp area
    zones:
      front_yard:
        coordinates: 100,500,400,500,400,720,100,720
        objects:
          - person
          - car
    review:
      alerts:
        required_zones:
          - front_yard

关键设置：

• detect.fps：对于大多数摄像头，5 是最佳值（可降低检测器负载）
• detect.width/height：必须与摄像头子码流的实际分辨率一致
• record.retain.mode：使用 motion 或 active_objects 以节省存储空间
• motion.mask：将多边形定义为逗号分隔的坐标
• zones.coordinates：由边界框底部中心位置决定是否位于区域内

硬件加速预设

Intel（第 6 代及更新型号）

# For Intel gen8+ (prefer QSV)
ffmpeg:
  hwaccel_args: preset-intel-qsv-h264  # or preset-intel-qsv-h265

# For Intel gen1-gen7 (use VAAPI)
ffmpeg:
  hwaccel_args: preset-vaapi

NVIDIA GPU

ffmpeg:
  hwaccel_args: preset-nvidia

需要 NVIDIA Container Toolkit：

# docker-compose.yml
services:
  frigate:
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all

AMD GPU

ffmpeg:
  hwaccel_args: preset-vaapi

# docker-compose.yml
environment:
  - LIBVA_DRIVER_NAME=radeonsi

Raspberry Pi

# Raspberry Pi 4/5
ffmpeg:
  hwaccel_args: preset-rpi-64-h264  # or preset-rpi-64-h265

需要：在 /boot/config.txt 中设置 gpu_mem=128，并在 Docker 中映射设备。

对象检测器类型

USB Coral TPU

detectors:
  coral:
    type: edgetpu
    device: usb  # Single USB Coral
    # device: usb:0  # First of multiple USB Corals

Docker 设备映射：

devices:
  - /dev/bus/usb:/dev/bus/usb

M.2/PCIe Coral TPU

detectors:
  coral:
    type: edgetpu
    device: pci
    # device: pci:0  # First of multiple PCIe Corals

OpenVINO（Intel）

detectors:
  ov:
    type: openvino
    device: GPU  # or CPU

model:
  path: /openvino-model/ssdlite_mobilenet_v2.xml
  width: 300
  height: 300

ONNX（多 GPU）

detectors:
  onnx:
    type: onnx
    # Automatically uses: ROCm (AMD), OpenVINO (Intel), TensorRT (NVIDIA)

高级功能

基于区域的速度估算

zones:
  driveway:
    coordinates: 100,500,400,500,400,720,100,720
    distances:
      - "100,500|400,500|20ft"  # 20 feet between points
    speed:
      threshold: 15  # Minimum mph to register

音频检测

audio:
  enabled: true
  listen:
    - bark
    - fire_alarm
    - scream
    - speech

cameras:
  front_door:
    ffmpeg:
      inputs:
        - path: rtsp://camera/stream
          roles:
            - audio

GenAI 事件描述

genai:
  enabled: true
  provider: ollama
  base_url: http://192.168.1.100:11434
  model: llava

人脸识别（Frigate+）

face_recognition:
  enabled: true
  threshold: 0.6

cameras:
  front_door:
    detect:
      width: 1280  # Higher res improves face detection

车牌识别

lpr:
  enabled: true

cameras:
  driveway:
    lpr:
      enabled: true

go2rtc 集成

go2rtc:
  streams:
    front_door:
      - rtsp://user:[email protected]:554/stream1
      - "ffmpeg:front_door#video=copy#audio=opus"
  webrtc:
    candidates:
      - 192.168.1.50:8555
      - stun:8555

Docker Compose 模板

services:
  frigate:
    container_name: frigate
    image: ghcr.io/blakeblackshear/frigate:stable
    restart: unless-stopped
    shm_size: "256mb"
    devices:
      - /dev/bus/usb:/dev/bus/usb  # USB Coral
      - /dev/dri/renderD128:/dev/dri/renderD128  # Intel GPU
    volumes:
      - ./config:/config
      - ./storage:/media/frigate
      - type: tmpfs
        target: /tmp/cache
        tmpfs:
          size: 1000000000
    ports:
      - "8971:8971"  # Web UI
      - "8554:8554"  # RTSP feeds
      - "8555:8555/tcp"  # WebRTC
      - "8555:8555/udp"  # WebRTC
    environment:
      FRIGATE_RTSP_USER: admin
      FRIGATE_RTSP_PASSWORD: ${RTSP_PASSWORD}
      FRIGATE_MQTT_USER: frigate
      FRIGATE_MQTT_PASSWORD: ${MQTT_PASSWORD}

附带资源

模板

位于 templates/：

• docker-compose.yml - 可用于生产环境的 compose 文件
• config-minimal.yml - 最简入门配置
• config-full.yml - 功能完整的配置模板

参考资料

位于 references/：

• detector-comparison.md - 检测器性能对比
• ffmpeg-presets.md - 所有可用的 FFmpeg 预设
• mqtt-topics.md - MQTT 主题参考

脚本

位于 scripts/：

• validate-config.sh - 应用配置前验证配置语法

依赖项

必需

软件包	版本	用途
Docker	20.10+	容器运行时
docker-compose	2.0+	服务编排

可选

软件包	版本	用途
NVIDIA Container Toolkit	Latest	NVIDIA GPU 支持
Coral Edge TPU runtime	Latest	Coral TPU 支持

官方文档

• Frigate 文档
• 配置参考
• 入门指南
• 故障排除常见问题

故障排除

摄像头显示离线

症状： 摄像头 fps 显示为 0，Web UI 显示离线状态

解决方案：

# Test RTSP URL directly
ffprobe -rtsp_transport tcp "rtsp://user:pass@ip:554/stream"

# Check Docker logs
docker logs frigate 2>&1 | grep -i "camera_name"

CPU 使用率高

症状： CPU 使用率持续高于 80%，系统变得无响应

解决方案：

1. 启用硬件加速（参见上方预设）
2. 将 detect fps 从 10 降至 5
3. 将 detect 分辨率降至 720p 或更低
4. 添加 Coral TPU 进行对象检测

未检测到对象

症状： 检测到运动，但未创建对象事件

解决方案：

1. 确认检测器已配置并正在运行：检查 /api/stats
2. 检查对象筛选条件是否过于严格（min_area、threshold）
3. 确保检测流分辨率正确
4. 确认对象列表包含所需类型

录像无法正常工作

症状： 显示事件，但没有可用录像

解决方案：

# Ensure record role is assigned
cameras:
  cam1:
    ffmpeg:
      inputs:
        - path: rtsp://camera/stream
          roles:
            - record  # Must be explicitly set
    record:
      enabled: true  # Must be true

设置清单

部署 Frigate 前，请确认：

• 已安装 Docker 和 docker-compose
• 已在 VLC 中测试 RTSP URL（记下实际分辨率）
• 已准备好用于环境变量的摄像头凭据
• 存储卷空间充足（建议 100GB 以上）
• 已配置共享内存大小（每个摄像头至少 64MB）
• 已映射硬件加速设备（如适用）
• 已映射 Coral TPU 设备（如使用）
• 可访问 MQTT broker（如需与 Home Assistant 集成）
• Web UI 使用的端口 8971 可用
• 防火墙允许所需端口（用于流媒体的 8554、8555）