完善中央与边缘部署、远程写入与监控文档

- 增加中央与边缘完整配置和部署脚本
- 引入 VictoriaMetrics 数据源与 remote_write 故障排查说明
- 新增 edge-agent 配置脚本、ONVIF 自建 exporter 与 ping 监控示例

Co-authored-by: Cursor <cursoragent@cursor.com>

doc/ONVIF_ALTERNATIVES.md

@@ -0,0 +1,81 @@
+# 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/ping-targets.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/onvif-targets.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` 生成 `onvif-targets.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_NODE_SETUP.md** 及 `edge-agent/docker-compose.yml`。