# Prometheus 监控 ONVIF/摄像头的替代方案

当前项目原计划使用 **ghcr.io/atiek/onvif-exporter**，该镜像在公共 registry **不存在**，且未见可直接替代的“ONVIF → Prometheus /metrics”公开镜像。以下为可行替代思路。

---

## 方案概览

| 方案 | 适用场景 | 说明 |
|------|----------|------|
| **SNMP Exporter** | 摄像头/设备支持 SNMP | 用官方 `prom/snmp_exporter`，按设备 MIB 配置 OID，无 ONVIF 协议 |
| **Frigate** | 已用或可部署 Frigate NVR | Frigate 暴露 `/api/metrics`，Prometheus 直接抓取或通过 frigate-exporter |
| **UniFi Protect Exporter** | UniFi 摄像头/Protect | 使用专有 exporter，非 ONVIF 通用方案 |
| **ONVIF 自建** | 必须用 ONVIF 协议 | **本项目已提供**：见 **edge-agent/onvif-exporter/**，Go + use-go/onvif，读取 `onvif-targets.json`，GetDeviceInformation 探测，暴露 `onvif_device_up`、`onvif_probe_duration_seconds`。`docker compose --profile onvif up -d --build` 即可。 |
| **仅 Ping/HTTP 探测** | 只关心在线与可达性 | 用 Blackbox Exporter 对摄像头 IP 做 ICMP/HTTP 探测，不解析 ONVIF |

---

## 1. SNMP Exporter（摄像头支持 SNMP 时推荐）

很多 IP 摄像头和 NVR 支持 SNMP，可用 Prometheus 官方 **snmp_exporter** 统一监控。

- **镜像**：`prom/snmp-exporter:latest`（Docker Hub 公开）
- **原理**：snmp_exporter 按配置的 OID 向设备发 SNMP 请求，将结果转为 Prometheus 指标。
- **步骤概要**：
  1. 确认摄像头/NVR 开启 SNMP（v2c 或 v3），并拿到 community 或 v3 认证信息。
  2. 在边缘节点部署 `prom/snmp-exporter`，配置 `snmp.yml`（可参考 [snmp_exporter 官方](https://github.com/prometheus/snmp_exporter) 的 generator 与现成 MIB）。
  3. 在边缘 Prometheus 的 `scrape_configs` 中增加对 snmp_exporter 的抓取（按 target 区分设备）。
- **优点**：镜像现成、方案成熟，可与现有边缘 Prometheus + remote_write 无缝配合。
- **缺点**：不是 ONVIF，依赖设备支持 SNMP。

---

## 2. Frigate NVR 暴露的 Prometheus 指标

若已使用或可部署 [Frigate](https://frigate.video/) 作为 NVR，可直接用其内置 Prometheus 接口。

- **端点**：Frigate 提供 `http://<frigate-host>:5000/api/metrics`（或你配置的端口）。
- **在边缘 Prometheus 中增加**：
  ```yaml
  - job_name: 'frigate'
    metrics_path: '/api/metrics'
    static_configs:
      - targets: ['frigate-host:5000']   # 或容器名/服务名
    scrape_interval: 15s
  ```
- **指标内容**：摄像头 FPS、检测状态、事件计数、系统/GPU/存储等（见 [Frigate 文档](https://docs.frigate.video/configuration/metrics/)）。
- **优点**：无需额外 ONVIF exporter，Frigate 已聚合摄像头与检测指标。
- **缺点**：依赖 Frigate 部署，非“纯 ONVIF”方案。

---

## 3. 仅用 Blackbox 做在线与可达性监控

不解析 ONVIF，只监控“摄像头/NVR 是否在线、端口是否可达”。

- **已有组件**：边缘节点已包含 **Blackbox Exporter**（如 `prom/blackbox-exporter`）。
- **做法**：在 `config/target-ping.json`（或等价目标列表）中加入摄像头/NVR 的 IP，用 ICMP 或 TCP/HTTP 探测（例如对 80/8000 等端口做 `tcp_connect` 或 `http_2xx`）。
- **优点**：无需任何 ONVIF 镜像，部署即可用，与现有 Ping 监控一致。
- **缺点**：无设备级 ONVIF 状态、无摄像头特有指标。

---

## 4. ONVIF 自建 Exporter（必须走 ONVIF 时）

**本项目已在 edge-agent/onvif-exporter/ 提供自建容器**，无需再找第三方镜像。

- **实现**：Go + [use-go/onvif](https://github.com/use-go/onvif)，读取 `config/target-onvif.json`（与 `targets.csv` 中 onvif 行一致），轮询 ONVIF `GetDeviceInformation`，暴露 Prometheus 指标 `onvif_device_up`、`onvif_probe_duration_seconds`。
- **启用**：在边缘节点执行 `docker compose --profile onvif up -d --build`，会构建并启动 ONVIF exporter，无需设置 `ONVIF_EXPORTER_IMAGE`。
- **配置**：在 `config/targets.csv` 中增加 onvif 行（ip、device_type、model、location、username、password、onvif_port），运行 `config/update-configs.sh` 生成 `target-onvif.json`。
- 若需自行修改或扩展，见 **edge-agent/onvif-exporter/README.md**。

---

## 在本项目中的建议

- **边缘默认部署**：不依赖不存在的 ONVIF 镜像；默认只跑 **prometheus-edge** + **blackbox-exporter**（Ping/探测），可选用 **snmp-exporter** 或 Frigate 抓取。
- **若需要 ONVIF**：使用本项目自建的 **edge-agent/onvif-exporter**，执行 `docker compose --profile onvif up -d --build` 即可构建并启动；无需再设 `ONVIF_EXPORTER_IMAGE`。
- **摄像头支持 SNMP 时**：优先考虑 **SNMP Exporter** 作为“Prometheus 监控摄像头”的替代方案，再根据需要补充 Frigate 或 Blackbox。

具体边缘配置与 compose 变更见 **[EDGE_AGENT_CONFIG.md](EDGE_AGENT_CONFIG.md)** 及 `edge-agent/docker-compose.yaml`。