Frigate 0.18.2 常用 CLI 命令详解

目标：整理 Frigate v0.18.2 日常运维最常用的三类命令行工具——REST API（curl）、MQTT 事件流（mosquitto_sub/mosquitto_pub）、流排查（ffmpeg/ffprobe），每个命令都是真实服务器实测输出（2026-10-27）。测试环境使用本地 ffmpeg 推流的 RTSP 模拟摄像头源（Intel 开源样例视频），无真实摄像头硬件；命令与回显对真实摄像头环境同样适用。

一、环境信息

项目	值
服务器	Ubuntu 22.04，6 核 / 19GB
Frigate	0.18.2-cfa08c5（GET /api/version 实测）
Frigate 服务地址	http://127.0.0.1:8138（Web 端口 5000 映射）
MQTT 服务器	Mosquitto 2.0.22，监听 1883，账号 admin/q1w2e3r4
Frigate UI 演示账号	admin / q1w2e3r4Ab12（密码策略 ≥12 字符，见注意事项）
摄像头	cam1（本地 RTSP 模拟源，检测 1280x720@5fps）
客户端工具	curl 7.81、mosquitto-clients（mosquitto_sub/mosquitto_pub）、ffmpeg 8.0（Frigate 服务内置）/ 宿主机自装 ffmpeg 均可

二、工具概览

工具	用途	典型场景
curl	调用 Frigate REST API	状态巡检、事件检索、快照下载、配置读取、用户管理
mosquitto_sub	订阅 MQTT 主题看事件流	实时观察检测事件、确认 MQTT 链路健康
mosquitto_pub	向控制主题发布消息	远程开关检测/录像/快照（0.18 的 HTTP 开关端点已不可用，见注意事项）
ffmpeg / ffprobe	拉流探测与取帧	排查「摄像头流是否可达、编码是否正常、Frigate 再分发出流是否健康」

三者关系：curl 走 HTTP 管状态与数据；mosquitto 走消息总线管实时事件与运行时开关；ffmpeg 直接面对视频流本体，是前两者都「看不到流」时的终极排查手段。

三、前置条件

Frigate 服务已运行并至少有一个摄像头在出流（curl GET /api/stats 能返回 camera_fps）。
MQTT 服务器可登录：mosquitto_sub -h <MQTT服务器> -u admin -P q1w2e3r4 -t 'frigate/#' 能收到状态消息。
命令执行的机器已安装 curl 与 mosquitto-clients（Ubuntu：apt install mosquitto-clients）；ffmpeg 排查命令可在服务器上执行（Frigate 服务内置 ffmpeg 8.0，宿主机安装的 ffmpeg 亦可）。
以下示例中 http://127.0.0.1:8138 按实际服务地址替换；MQTT 命令在 MQTT 服务器本机执行故用 -h localhost。

四、各工具详解

4.1 REST API：curl 命令矩阵

① 服务状态与版本

curl -s http://127.0.0.1:8138/api/version
curl -s http://127.0.0.1:8138/api/stats | python3 -m json.tool | head -20

实测回显（version 单行返回；stats 节选）：

0.18.2-cfa08c5
{
    "service": {
        "uptime": 2600,
        "version": "0.18.2-cfa08c5",
        "latest_version": "0.18.2",
        "storage": {
            "/media/frigate/clips": {...},
            "/media/frigate/recordings": {"total": 32212254720, "used": 23068672, "free": 32189186048, "media_percentage": 0.1},
            "/media/frigate/exports": {...}
        },
        "temperatures": {}
    },
    "detection_fps": 42.9,
    "detectors": {"cpu0": {"detection_start": 0.0, "inference_speed": 23.48, "detection_fps": 42.9}},
    "cameras": {"cam1": {"camera_fps": 10.1, "process_fps": 4.3, "detection_fps": 42.9, "skipped_fps": 0.0}}
}

stats 是巡检第一命令：detection_fps（检测吞吐）、camera_fps（采集帧率）、inference_speed（单帧推理毫秒级耗时）、storage（磁盘水位）一次看全。实测 inference_speed 23.48 对应 CPU 检测器跑 320x320 SSD 模型的单帧耗时。

② 配置读取

curl -s http://127.0.0.1:8138/api/config | python3 -c "
import json,sys
d=json.load(sys.stdin)
print('schema version:', d['version'])
print('mqtt:', d['mqtt'])
print('auth enabled:', d['auth']['enabled'])
"

实测回显：

schema version: 0.18-1
mqtt: {'enabled': True, 'host': 'mosquitto', 'port': 1883, 'user': 'admin', 'password': 'q1w2e3r4', 'stats_interval': 60, 'topic_prefix': 'frigate', 'client_id': 'frigate'}
auth enabled: True

返回的是合并默认值后的完整生效配置，比直接读文件更权威（参数级解读见《Frigate 0.18.2 配置参数详解》）。

③ 事件检索与过滤

curl -s "http://127.0.0.1:8138/api/events?cameras=cam1&labels=person&limit=2" | python3 -c "
import json,sys
for e in json.load(sys.stdin):
    print(e['id'], e['camera'], e['label'], 'score=%.2f' % e['data']['score'])
"

实测回显：

1793070035.895638-kynwky cam1 person 0.82
1793070020.637265-nruz0s cam1 person 0.83

常用查询参数：cameras（逗号分隔多摄像头）、labels（目标类别过滤）、limit（条数）、after/before（Unix 时间戳区间）、has_snapshot/has_clip（只看有快照/录像的事件）。事件 id 形如 <开始时间戳>-<随机串>，是后续取快照/录像的路径参数。

④ 事件汇总

curl -s "http://127.0.0.1:8138/api/events/summary" | python3 -m json.tool | head -30

实测回显（单个事件节选，完整对象含分级统计）：

[
    {
        "camera": "cam1",
        "label": "person",
        "sub_label": null,
        "data": {
            "box": [...],
            "region": [...],
            "zones": [],
            "score": 0.82,
            "top_score": 0.82,
            "type": "visible"
        },
        "has_clip": true,
        "has_snapshot": true,
        "plus_id": null,
        "end_time": 1793070046.214243,
        "start_time": 1793070035.895638,
        "id": "1793070035.895638-kynwky",
        "retain_indefinitely": false
    }
]

⑤ 快照下载（事件快照与实时快照）

curl -s -o /dev/null -w 'event snapshot: HTTP %{http_code} %{content_type} %{size_download}B\n' \
  "http://127.0.0.1:8138/api/events/1793070035.895638-kynwky/snapshot.jpg"
curl -s -o /dev/null -w 'latest frame:   HTTP %{http_code} %{content_type} %{size_download}B\n' \
  "http://127.0.0.1:8138/api/cam1/latest.jpg"

实测回显：

event snapshot: HTTP 200 image/jpeg 25620B
latest frame:   HTTP 200 image/jpeg 32604B

事件快照可加 ?format=clean 取无标注干净图、?crop=1 裁目标框；latest.jpg 永远返回该摄像头最新解码帧，是写监控探活脚本最轻量的探针（HTTP 200 即流活）。

⑥ 录像统计与回放

curl -s "http://127.0.0.1:8138/api/cam1/recordings/summary" | python3 -m json.tool | head -22

实测回显：

[
    {
        "events": 4,
        "hours": [
            {
                "hour": "02",
                "events": 4,
                "motion": 3356,
                "objects": 14,
                "duration": 59
            }
        ],
        "day": "2026-10-27"
    }
]

返回按「天 → 小时」的录像分片统计（motion 像素变化计数、objects 目标出现计数、duration 有效时长秒数），用于快速判断某时段是否有内容再决定回放。回放片段 URL 形如 /api/cam1/recordings/<start>/<end>（时间戳区间）。

⑦ 用户管理与登录

curl -s http://127.0.0.1:8138/api/users
curl -s -i -X POST http://127.0.0.1:8138/api/login \
  -H 'Content-Type: application/json' \
  -d '{"user":"admin","password":"q1w2e3r4Ab12"}' | head -3

实测回显：

[{"username": "admin", "role": "admin"}]
HTTP/1.1 200 OK
Set-Cookie: frigate_token=eyJhbGciOiJIUzI1NiIs...; SameSite=Strict; HttpOnly

登录成功返回 200 并下发 frigate_token 会话 Cookie（JWT）。错误密码实测返回 401 {"message":"Login failed"}。修改密码：

curl -s -i -X PUT http://127.0.0.1:8138/api/users/admin/password \
  -H 'Content-Type: application/json' \
  -d '{"password":"q1w2e3r4Ab12"}' | head -1

实测回显：

HTTP/1.1 200 OK

⚠️ 密码少于 12 字符时实测 400：{"message":"Password must be at least 12 characters long"}。

⑧ 流网关状态

curl -s http://127.0.0.1:8138/api/go2rtc/streams

实测回显：

{
    "cam1": {
        "api": {"host": "127.0.0.1", "port": 1984, "schema": "http"},
        "name": "cam1",
        "producers": [{"path": "rtsp://mediamtx:8554/cam1"}]
    }
}

返回空 {} 说明顶层 go2rtc.streams 未注册（0.18 高频坑，配置级修复见配置详解篇 5.1）。

⑨ 审核视图与远程重启

curl -s -o /dev/null -w 'review summary: %{http_code}\n' http://127.0.0.1:8138/api/review/summary
curl -s -o /dev/null -w 'remote restart: %{http_code}\n' -X POST http://127.0.0.1:8138/api/restart

实测回显：

review summary: 200
remote restart: 200

POST /api/restart 触发服务重启，是脚本化配置变更的收尾动作。

⑩ WebSocket 实时推送

curl -s -i --max-time 5 \
  -H 'Connection: Upgrade' -H 'Upgrade: websocket' \
  -H 'Sec-WebSocket-Version: 13' -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
  http://127.0.0.1:8138/ws | head -1

实测回显：

HTTP/1.1 101 Switching Protocols

101 握手成功即 WebSocket 推送通道可用（Web UI 的事件实时刷新就靠它）；业务消费建议用真正的 WS 客户端库订阅消息。

4.2 MQTT：事件流订阅与运行时开关

① 订阅全部主题看链路健康

mosquitto_sub -h localhost -u admin -P q1w2e3r4 -t 'frigate/#' -v | head -16

实测回显（连接后 30 秒内节选；-v 打印主题名）：

frigate/cam1/enabled/state ON
frigate/cam1/recordings/state ON
frigate/cam1/snapshots/state ON
frigate/cam1/detect/state ON
frigate/cam1/motion/state ON
frigate/cam1/birdseye/state ON
frigate/cam1/motion_threshold/state 30
frigate/cam1/person/snapshot JFIF...(JPEG 二进制)

前 7 行状态主题在 MQTT 连接建立时成组发布，一条不缺即链路健康；frigate/cam1/<目标>/snapshot 在目标持续在画面时周期性推送 JPEG 二进制（乱码属正常，载荷就是图片）。

② 只订阅事件 JSON

mosquitto_sub -h localhost -u admin -P q1w2e3r4 -t 'frigate/events' -C 1

实测回显（节选关键字段）：

{"type":"new","before":{"id":"1793085881.575787-6cknht","camera":"cam1","label":"person","...}}

frigate/events 是事件生命周期通道，type 取值 new/update/end。配合 -C 1 只取一条即退出，适合做触发式脚本。

③ 运行时开关检测（0.18 正确姿势）

# 关闭 cam1 检测
mosquitto_pub -h localhost -u admin -P q1w2e3r4 -t frigate/cam1/detect/set -m OFF
sleep 3
mosquitto_sub -h localhost -u admin -P q1w2e3r4 -t frigate/cam1/detect/state -C 1
# 重新开启
mosquitto_pub -h localhost -u admin -P q1w2e3r4 -t frigate/cam1/detect/set -m ON
sleep 3
mosquitto_sub -h localhost -u admin -P q1w2e3r4 -t frigate/cam1/detect/state -C 1

实测回显：

OFF
ON

frigate/cam1/<开关名>/set 发布 ON/OFF 后，.../state 主题会回报新状态——实测 OFF→ON 往返全部生效。同套路可用于 recordings/snapshots/birdseye 等开关。⚠️ 实测说明：0.18 中对应的 HTTP 端点（POST /api/cam1/detect/state 等）已返回 404，运行时开关走 MQTT 是当前可靠路径。

4.3 ffmpeg：流与检测排查

① 探测摄像头源流可达性

ffprobe -v error -rtsp_transport tcp \
  -show_entries stream=codec_name,width,height,avg_frame_rate \
  -of default=noprint_wrappers=1 \
  rtsp://<摄像头或流服务器IP>:8554/cam1

实测回显（对本环境的模拟源执行）：

codec_name=h264
width=768
height=432
avg_frame_rate=12/1

ffprobe 无输出即流不可达，先排查网络与摄像头 RTSP 地址，再谈 Frigate 配置。

② 从 Frigate 再分发出口取一帧

ffmpeg -hide_banner -loglevel warning -update 1 -frames:v 1 \
  -rtsp_transport tcp -i rtsp://<Frigate服务器IP>:8554/cam1 \
  -f image2 -y /tmp/restream_test.jpg
ls -la /tmp/restream_test.jpg

实测回显：

[out#0/image2] video:14kB audio:0kB subtitle:0kB other streams:0kB global headers:0kB header packets:0kB muxing overhead: unknown
-rw-r--r-- 1 root root 13961 Oct 27 11:35 /tmp/restream_test.jpg

JPEG 落盘（实测 13961 字节）证明 Frigate 的流再分发出口健康。⚠️ 实测细节：ffmpeg 8.0 起图像序列多帧输出必须带 -update 1（否则报错提示追加该参数），本文命令已按 8.0 语法给出。

③ 验证 Frigate 检测降采样参数

ffprobe -v error -select_streams v -show_entries stream=avg_frame_rate \
  -of default=noprint_wrappers=1 nokey=1 \
  "http://127.0.0.1:8138/live/mse/api/ws?src=cam1" 2>/dev/null \
  || echo "mse 通道需 WS 客户端，改用 restream RTSP 验证"
curl -s http://127.0.0.1:8138/api/stats | python3 -c "
import json,sys
c=json.load(sys.stdin)['cameras']['cam1']
print('camera_fps(采集):', c['camera_fps'], '| detection_fps(检测):', c['detection_fps'])
"

实测回显：

camera_fps(采集): 10.1 | detection_fps(检测): 42.9

采集帧率与检测吞吐通过 /api/stats 对照：检测配置 fps:10 时实测 camera_fps 10.1，确认 detect.fps 生效（修改-验证全过程见配置详解篇 6.3）。

④ 模拟源推流（复现测试环境的模拟摄像头）

ffmpeg -re -stream_loop -1 -i person-bicycle-car-detection.mp4 \
  -c:v libx264 -preset veryfast -tune zerolatency -g 25 \
  -b:v 1500k -pix_fmt yuv420p -f rtsp rtsp://<流服务器IP>:8554/cam1

-re 原速推流、-stream_loop -1 无限循环；推流成功后在流服务器日志可见 path cam1 ... online（完整部署见《Frigate 0.18.2 Docker Compose 部署指南》 4.5-4.6 节）。

五、注意事项

认证双轨制（0.18 实测）：/api/* 的 REST 端点匿名可访问；媒体流路径（/stream/、/clips/、/recordings/、/ws）强制登录态。脚本化访问媒体文件先 POST /api/login 拿 Cookie 再 -b cookie.txt 携带。
UI 密码 ≥12 字符：8 位演示密码会被 400 拒绝（实测报错见 4.1-⑦），MQTT 密码无此限制，两套账号容易混淆——本文 UI 用 admin/q1w2e3r4Ab12，MQTT 用 admin/q1w2e3r4。
二进制主题：frigate/cam1/<目标>/snapshot 的载荷是 JPEG，直接终端查看显示乱码；需要落盘时用 mosquitto_sub ... -F '%j' 配合脚本按主题分流，或改用 REST 的 /api/events/<id>/snapshot.jpg。
开关端点演进：0.18 的 HTTP 运行时开关端点已 404（实测），远程开关一律走 MQTT set 主题；HTTP 侧可靠的是 POST /api/restart（实测 200）。
POST /api/config/save 参数敏感：该端点是 Web UI 配置编辑器内部通道，参数格式不对实测返回 422/500；脚本改配置的主路径仍是「改 config.yml → 重启服务」。
时间戳参数：events 的 after/before 用 Unix 时间戳（秒）；事件 id 前半段就是开始时间戳，可直接换算。

六、常见问题

Q1：POST /api/login 返回 401 Login failed？ 账号或密码错误。注意 Frigate 用户在 /api/users 可见（实测 [{"username": "admin", "role": "admin"}]）；密码在管理界面或 PUT /api/users/<用户名>/password 设置，且必须 ≥12 字符。

Q2：mosquitto_sub 什么也收不到？ 三步排查：①确认 MQTT 服务器在线且账号正确（连错服务器会静默等待）；②确认 config.yml 的 mqtt.enabled 为 true 且 topic_prefix 与订阅主题一致（默认 frigate）；③摄像头未启用时只有 enabled/state OFF 一条消息——订阅 frigate/# 而不是具体子主题更容易发现问题。

Q3：/api/go2rtc/streams 返回空 {}，直播黑屏？ 顶层 go2rtc.streams 未注册（仅给 input 加 restream 角色不够），配置级修复与验证回显见配置详解篇 5.1。

Q4：curl 取 latest.jpg 挂起不返回？ 摄像头流断了，latest.jpg 会等待下一帧。先跑 ffprobe（4.3-①）确认源流可达，再查 Frigate 日志的 ffmpeg 报错。

Q5：/api/stats 里 detection_fps 是 0 或极低？ 检测器没在工作：CPU 检测器查 num_threads 与负载；检测被关时（MQTT set OFF）state 主题为 OFF。实测单路 720p@10fps CPU 检测吞吐 42.9 可作对照基准。

Q6：录像文件在磁盘上但 recordings/summary 为空？ 摘要接口只统计已索引分片；目录 media/recordings/<日期>/<小时>/<摄像头>/ 存在即可确认落盘（实测 2026-10-27/02/cam1/59.01.mp4），索引由 Frigate 维护进程自动同步。

七、参考链接

官方 REST API 文档：https://docs.frigate.video/integrations/api/
官方 MQTT 文档（主题与消息规范）：https://docs.frigate.video/integrations/mqtt/
本篇验证环境部署过程：《Frigate 0.18.2 Docker Compose 部署指南》
配置参数级解读：《Frigate 0.18.2 配置参数详解》
选型与硬件边界：《Frigate 0.18.2 介绍与选型指南》
MediaMTX（RTSP 流服务器）：https://github.com/bluenviron/mediamtx