Frigate中文文档

主题

2026-07-11
2598
9.9m

常见问题解答 ​

为什么我一些增强功能（如语义搜索、车牌识别、人脸识别）无法使用 ​

这些增强功能 Frigate 需要下载额外的模型文件才能正常使用，默认情况下，将会从 Github 和 huggingface 上进行下载，但这些服务均在海外，国内可能出现访问困难的情况，导致模型文件下载失败。

我们也提供有国内的下载加速服务，需要在 docker compose 文件的 environment 下配置以下环境变量：

yaml
HF_ENDPOINT: "https://huggingface.mirror.frigate-cn.video"
GITHUB_ENDPOINT: "https://github.mirror.frigate-cn.video"
TF_KERAS_MOBILENET_V2_WEIGHTS_URL: "https://cnb.cool/frigate-cn/mirrors/storage.googleapis/-/git/raw/main/tensorflow/keras-applications/mobilenet_v2/mobilenet_v2_weights_tf_dim_ordering_tf_kernels_0.35_224_no_top.h5"

详细可见文档里的Docker容器安装教程

为什么我页面打不开，提示400 Bad Request ​

如果提示为The plain HTTP request was sent to HTTPS port，则说明目前 Frigate 开启了 TLS 验证，但你目前使用http协议进行访问。

你需要修改地址中的http为https协议后进行访问，亦或者关闭 TLS 验证（不推荐）。

提示

注意，双向通话等功能必须要 https 协议才能正常工作。

Fatal Python error: Bus error （Python致命错误： Bus error） ​

此错误是由于共享内存(shm-size)设置过小导致的。请根据此指南调整shm-size大小。

如何在录像中添加音频？ ​

默认情况下，Frigate会移除录像中的音频以减少因无效数据导致失败的概率。如需保留音频，需要设置支持音频的FFmpeg预设：

yaml
ffmpeg:
  output_args: 
    record: preset-record-generic-audio-aac

为什么实时监控中没有声音？ ​

仅当配置了go2rtc时实时监控才能有声音，详见实时监控文档。

无法在Web界面查看录像 ​

请确保摄像头发送的是h264编码视频，或进行转码。

可在Chrome浏览器打开chrome://media-internals/页面尝试播放，该页面会显示播放失败的具体原因。

摄像头子码流质量不佳怎么办？ ​

Frigate通常推荐使用可配置子码流的摄像头。若子码流分辨率不合适，可对主码流进行缩放处理。

高效缩放需要满足以下条件：

  1. 需配备GPU或核显进行缩放处理
  2. 需使用硬件加速的ffmpeg预设
  3. 在配置中设置detect -> width和detect -> height为期望的检测分辨率

正确配置后，GPU将负责解码和缩放，CPU占用仅小幅增加但效果更佳。

MJPEG流或快照显示异常绿色画面 ​

这通常表示摄像头配置的分辨率(width/height)不正确。请使用VLC等播放器确认实际分辨率，并检查宽高值是否颠倒。

分辨率不匹配

日志中出现"[mov,mp4,m4a,3gp,3g2,mj2 @ 0x5639eeb6e140] moov atom not found" ​

某些情况下出现此日志信息是正常的。Frigate会在存储前检查录像文件完整性，偶尔这些缓存文件会无效并自动清理。

日志中重复出现"On connect called" ​

若日志频繁出现"On connect called"信息，请检查是否有多个Frigate实例。当多个容器使用相同client_id连接MQTT时会出现此情况。

错误：Database Is Locked ​

SQLite在网络共享存储上运行不佳。若/media目录映射到网络共享，请按照此指南将数据库移至内部存储。

无法发布到MQTT：客户端未连接 ​

在Docker中使用MQTT时，请使用MQTT服务器的实际IP地址，而非localhost、127.0.0.1或mosquitto.ix-mosquitto.svc.cluster.local。

因为Frigate容器不在host网络模式下运行，localhost指向的是容器自身而非宿主机网络。

如何判断摄像头是否离线 ​

可通过MQTT或/api/stats接口检测，离线摄像头的camera_fps会显示为0。

此外，当摄像头离线时，Home Assistant会将其标记为不可用状态。

如何不通过Web界面查看Frigate日志？ ​

Frigate既会内部管理日志，也会直接输出到Docker标准输出。通过CLI查看日志的步骤如下：

  1. 在运行Frigate容器的主机上打开终端
  2. 执行以下命令：
    docker logs -f frigate
    注意：若容器名称不是"frigate"，请替换为实际名称。"-f"参数表示实时追踪日志更新，按Ctrl+C可退出。

更多日志查看选项可参考Docker官方文档。

另外，创建容器时可绑定主机目录到/dev/shm/logs，既持久化日志又便于使用日志分析工具：

docker run -d \
  --name frigate \
  --restart=unless-stopped \
  --mount type=tmpfs,target=/tmp/cache,tmpfs-size=1000000000 \
  --device /dev/bus/usb:/dev/bus/usb \
  --device /dev/dri/renderD128 \
  --shm-size=64m \
  -v /path/to/your/storage:/media/frigate \
  -v /path/to/your/config:/config \
  -v /etc/localtime:/etc/localtime:ro \
  -v /path/to/local/log/dir:/dev/shm/logs \
  -e FRIGATE_RTSP_PASSWORD='password' \
  -p 5000:5000 \
  -p 8554:8554 \
  -p 8555:8555/tcp \
  -p 8555:8555/udp \
  docker.cnb.cool/frigate-cn/frigate:stable

RTSP流在VLC中正常播放，但在Frigate配置中使用相同URL却失败，这是bug吗？ ​

不是。Frigate使用TCP协议连接RTSP流，而VLC会根据网络条件自动切换UDP/TCP协议。VLC能播放而Frigate失败，很可能是因为VLC选择了UDP协议。

TCP能确保数据包有序到达，这对视频录制、解码和流处理至关重要，因此Frigate强制使用TCP连接。UDP速度更快但可靠性较低，VLC的要求与Frigate不同。

如需使用UDP协议，可通过ffmpeg输入参数或preset-rtsp-udp预设配置，详见ffmpeg预设文档。

默认登录密码是什么？/我忘记登录后台密码了怎么办？ ​

在首次安装Frigate的时候，会在日志里生成账号密码，请打开容器日志进行查看。

如果已经重启导致日志丢失的话，有两个方法可以重置密码：

  • 方法一：在Frigate的配置文件中配置reset_admin_password，重新生成管理员密码。具体参数详见配置文件文档。

  • 方法二：可使用5000端口进行访问，5000端口没有鉴权。然后可以在端口下进入设置中修改密码。

警告

请不要将5000端口直接映射到公网，这将会有严重的隐私泄露隐患！如果可以，建议在不需要的时候关闭5000端口的映射。 如果你的系统已经占用了5000端口（例如群晖的管理页面），你可以将容器的5000端口映射至其他任意空闲端口。

为什么 Frigate 不断为我的停放汽车创建新的被追踪目标？ ​

静止追踪旨在防止这种情况：一辆停放的汽车应保持为一个单一的被追踪目标，而不是生成新的目标。如果你不断为同一辆车获得新的被追踪目标，那么 Frigate 很可能丢失了该目标并重新将其检测为新目标。

在浏览 → 追踪详情中打开其中一个被追踪目标。如果检测分数较低（< 70% 左右），则模型对停放汽车是汽车没有信心。这在免费的 COCO 训练目标检测模型上很常见，例如陡峭/俯视角度、部分遮挡的汽车、树叶遮挡或低光照画面。当检测结果在太多帧中低于 min_score 时，追踪器会丢失目标，下一个有信心帧会创建一个全新的目标。

以下方法应该能改善：

  • 改善视角：即使是一个小的角度变化，让汽车更多的部分可见，也可能将分数提高到足以稳定追踪的水平。
  • 使用更准确的模型：从 mobiledet 切换到 yolov9，或升级到更大的变体如 yolov9-s 而非 yolov9-t。最大的收益通常来自在你自己的摄像头图像上微调模型，使其学习你的特定场景。Frigate+ 是一个付费选项——模型基于安防摄像头画面训练，并可微调为你提交的图像。
  • 不要为 car 设置 detect -> stationary -> max_frames：这会人为结束追踪并强制重新检测为新目标。参见静止目标。
  • 使用 required_zones 将警报限制在你关心的区域。参见区域。
  • 使用目标过滤遮罩过滤不可能的位置，如果汽车在屋顶/树顶等位置被检测到。

参见目标过滤器了解更多关于调整 min_score 和 threshold 的信息。注意将它们提得太高会使这个问题更严重。

当 Frigate 将某物检测为错误目标时，如何纠正？ ​

Frigate 的目标检测依赖机器学习模型，而随 Frigate 提供的免费 COCO 训练模型可能在其未训练的场境中误识别目标。有两种处理方法：

使用你自己的图像训练或微调模型。 最持久的修复方法是改进模型本身。最大的收益通常来自在你自己的摄像头图像上微调模型，使其学习你的特定场景。Frigate+ 是付费选项。当 Frigate 标记错误时，在浏览中打开被追踪目标，选择快照标签页，使用提交到 Frigate+ 发送带有正确标签的示例（或将其标记为误报）。一旦你提交了示例并请求了模型，重新训练的模型将对你的摄像头更准确。

使用过滤器抑制误识别。 你可以使用过滤器阻止特定误报被追踪：调整 min_score / threshold，或添加 min_area / max_area / min_ratio / max_ratio 过滤器。如果误报始终在相同的固定位置（如被识别为人的雕像或邮箱），在该位置添加目标过滤遮罩。

过滤器和遮罩只能隐藏不正确的结果——它们不会教会 Frigate 目标实际上是什么。要做到这一点，请微调你自己的模型或使用 Frigate+。