Frigate NVR 集成方案

文档状态：原型已接入 — Genapsed 可渲染 Frigate 配置、启动容器，并拉起 NVR-Bridge worker
相关组件：Genapsed、NVR-Bridge、MiniVLM、时间线存储
官方资源：官网 · 文档 · API

1. 组件定位

Frigate NVR 是一个开源的、AI 友好的网络视频监控系统（NVR）。它使用多种机器学习模型检测和标注画面中的人、动物等对象，并提供用于实时查看、回放、审计事件的 Web UI 和 API 接口。

在 Everpast 系统中，Frigate 处于视频底座层，负责与摄像头和录像相关的底层能力。它不直接生成系统时间线——它只告诉系统"画面可能发生了变化"，后续还需要 MiniVLM 判断"具体发生了什么"。

虽然 Frigate 后期也开始支持通过 VLM 识别监控内容，但本系统不使用 Frigate 的 VLM 功能，而是使用 MiniVLM 模块实现画面理解和事件生成。

2. 主要职责

接入摄像头视频流
通过 RTSP/RTMP 等协议拉取摄像头画面，支持主流品牌（海康、大华、TP-Link 等）。
录像和分段存储
持续录制视频并按时间段分段存储，便于回放和检索。
移动检测和目标检测
在视频流上实时运行移动检测算法，并可配置对象检测模型识别人、动物、车辆等。
生成事件元数据
当检测到事件时，生成 event_id、截图、缩略图、视频片段引用等元数据。
事件上报
将检测事件通过 Frigate 原生 MQTT topic 上报给 NVR-Bridge。NVR-Bridge 负责转换成 Everpast 标准消息，再由 Genapsed 显式路由到 MiniVLM。
视频片段精准裁剪
根据时间范围对录像进行精准裁剪，生成指定区间的视频片段。查询引擎和插件只需提供时间范围引用，由 Frigate 利用其成熟的视频处理逻辑完成裁剪并返回片段路径。

3. 数据流集成

Frigate 官方 MQTT 事件 topic 是 <topic_prefix>/events。在 Everpast 中，Genapsed 生成的 Frigate 配置默认使用：

mqtt:
  topic_prefix: everpast/frigate

因此 Frigate 原生事件会发布到：

everpast/frigate/events

NVR-Bridge 读取 Frigate 原生事件后，输出 Everpast 标准消息示例：

{
  "msg_id": "uuid-v4",
  "source": "nvr_bridge.frigate",
  "target": "minivlm",
  "type": "motion_detected",
  "priority": "high",
  "timestamp": 1741000000,
  "payload": {
    "camera_id": "cam01",
    "frigate_event_id": "1741000000.123456-abcd",
    "trigger_type": "frigate_event",
    "frigate_event_type": "end",
    "confidence": 0.93,
    "label": "person",
    "box": [120, 80, 430, 720],
    "media_refs": {
      "image": "http://127.0.0.1:5000/api/events/1741000000.123456-abcd/snapshot.jpg",
      "video": "http://127.0.0.1:5000/api/events/1741000000.123456-abcd/clip.mp4"
    }
  },
  "metadata": {
    "requires_ack": true,
    "trace_id": "trace-uuid"
  }
}

MQTT Topic：everpast/nvr_bridge/event/high（详见 Genapsed-核心组件 的消息网关章节）。

Genapsed 开发模式默认启用 Frigate，会渲染 data/frigate/config/config.yml 和开发 Compose 服务，并启动 Frigate 容器。首次启动允许没有摄像头，后续可通过 WebUI、配置文件或 Frigate UI 补充；如果已有 RTSP 地址，也可以通过 --frigate-camera NAME=RTSP_URL 在启动时写入。NVR-Bridge worker 默认订阅 everpast/frigate/events，只转发 Frigate end 事件，避免 new/update 高频重复触发 MiniVLM。

4. 配置参考

Frigate 的配置文件通常在 /config/config.yml。以下是与 Everpast 集成相关的关键配置：

mqtt:
  host: 127.0.0.1
  port: 1883
  topic_prefix: everpast/frigate   # 与系统 MQTT topic 规范对齐
  # 注意：系统 Topic 规范是 everpast/<component>/...，
  # 需在 Frigate 配置中将 topic_prefix 设置为 everpast/frigate

cameras:
  living_room:
    ffmpeg:
      inputs:
        - path: rtsp://192.168.1.100:554/stream1
          roles:
            - record
            - detect
    detect:
      enabled: true
      width: 1280
      height: 720
    objects:
      track:
        - person
        - cat
        - dog
    record:
      enabled: true
      alerts:
        retain:
          days: 7             # 告警录像保留天数
      detections:
        retain:
          days: 7             # 检测录像保留天数
    snapshots:
      enabled: true
      retain:
        default: 30           # 截图保留天数（建议长于录像）

5. 集成注意事项

要点	说明
Topic 前缀	Frigate 的 `mqtt.topic_prefix` 设置为 `everpast/frigate` 后，原生事件 topic 是 `everpast/frigate/events`；它不是 Everpast 标准 topic，需要 NVR-Bridge 转换
	对象检测模型
	事件生命周期
	存储
	多摄像头

6. 摄像头注册表（Camera Registry）

Everpast 使用独立的摄像头注册表（everpast_system.camera_registry 表）来存储摄像头语义化元数据，与 Frigate 自身的配置解耦。这样实现了清晰的所有权边界：

配置所有权划分

管理者	管理内容	存储位置
Frigate WebUI	摄像头输入流、检测区域、遮罩、录制规则	Frigate `config.yml`（`cameras:` 段）
Genapsed	MQTT 地址、detector 后端、容器参数	Frigate `config.yml`（`mqtt:`/`detectors:` 段，YAML 段级合并）
Everpast Camera Registry	友好名称、安装地点、用途备注	MySQL `everpast_system.camera_registry` 表

注册表结构

CREATE TABLE `everpast_system`.`camera_registry` (
    `nvr_id`         VARCHAR(64)  NOT NULL DEFAULT 'frigate', -- NVR 标识，未来可扩展多 NVR
    `camera_id`      VARCHAR(128) NOT NULL,                   -- Frigate 中的摄像头 ID
    `friendly_name`  VARCHAR(128) NOT NULL,                   -- 友好名称，默认等于 camera_id
    `location`       VARCHAR(256) NOT NULL DEFAULT '',        -- 安装地点
    `purpose`        VARCHAR(256) NOT NULL DEFAULT '',        -- 用途
    `notes`          TEXT         NOT NULL,                   -- 备注
    `is_active`      TINYINT(1)   NOT NULL DEFAULT 1,         -- 是否在 Frigate 中活跃
    `created_at`     BIGINT       NOT NULL,
    `updated_at`     BIGINT       NOT NULL,
    PRIMARY KEY (`nvr_id`, `camera_id`),
    INDEX `idx_camera_registry_active` (`nvr_id`, `is_active`)
)

数据流

WebUI API

端点	方法	说明
`/api/cameras`	GET	列出所有摄像头元数据
`/api/cameras/{camera_id}`	GET	查询单个摄像头元数据
`/api/cameras/{camera_id}`	PUT	更新友好名称/地点/用途/备注

组件权限

组件	权限	用途
`nvr_bridge`	READ + WRITE	自动同步摄像头 ID
`www_server`	READ	WebUI 展示和编辑
`minivlm`	READ	事件语义化（camera_id → 友好名称）

实现模块

everpast_share/src/everpast_share/camera_registry.py — CameraRegistry 类（CRUD + 同步）
src/nvr_bridge/src/nvr_bridge/runtime/worker.py — NVR-Bridge 启动和定时同步
src/www_server/src/www_server/server.py — /api/cameras 路由
src/minivlm/src/minivlm/runtime/worker.py — MiniVLM 事件 enrich

1. 组件定位​

2. 主要职责​

3. 数据流集成​

4. 配置参考​

5. 集成注意事项​

6. 摄像头注册表（Camera Registry）​

配置所有权划分​

注册表结构​

数据流​

WebUI API​

组件权限​

实现模块​