Files

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

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

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

2026-02-25 04:24:40 -05:00

10 KiB

Raw Blame History

边缘节点配置文件说明

边缘节点需要什么

类型	说明	对应组件
必选	remote_write：把边缘指标推到中央	prometheus-edge（内配 remote_write 到中央 VictoriaMetrics）
必选	Blackbox：Ping/网络探测	blackbox-exporter 容器
可选	ONVIF、SNMP、Frigate 等	onvif-exporter（`--profile onvif`）、或自建/第三方镜像

默认部署只起 prometheus-edge + blackbox-exporter；需要 ONVIF 时再设 ONVIF_EXPORTER_IMAGE 并 docker compose --profile onvif up -d。参见 ONVIF_ALTERNATIVES.md。

边缘节点各容器分别做什么

容器	必选/可选	作用	端口/接口
prometheus-edge	必选	抓取 Blackbox（及可选 ONVIF 等），通过 remote_write 推送到中央 VictoriaMetrics	对外 9092；内部抓取 blackbox:9115、可选 onvif:9600
blackbox-exporter	必选	网络 Ping/HTTP/TCP 探测，暴露 `/probe` 给 prometheus-edge 抓取	容器内 9115
onvif-exporter	可选	本项目自建：读取 `config/onvif-targets.json`，ONVIF GetDeviceInformation 探测，暴露 `onvif_device_up`、`onvif_probe_duration_seconds`。启用：`docker compose --profile onvif up -d --build`。	容器内 9600

数据流：Ping 目标 → blackbox-exporter:9115 → prometheus-edge 抓取 → remote_write → 中央 VictoriaMetrics。
若启用 ONVIF：ONVIF 设备 → onvif-exporter:9600 → prometheus-edge 抓取 → remote_write → 中央。

ONVIF 镜像替代方案

说明：目前没有公开可用的 ONVIF→Prometheus 镜像（如 ghcr.io/atiek/onvif-exporter 已不存在）。可选做法：

方式	说明
用替代方案	摄像头支持 SNMP 时用 prom/snmp-exporter；已用 Frigate 时抓其 `/api/metrics`；仅需在线监控时用 Blackbox 对摄像头 IP 做 Ping/HTTP。详见 ONVIF_ALTERNATIVES.md。
ONVIF 可选	边缘默认不启动 ONVIF 服务（无可用镜像）。需要时自建镜像并在 `.env` 设 `ONVIF_EXPORTER_IMAGE=你的镜像:tag`，再执行 `docker compose --profile onvif up -d`。
自建镜像	基于 Go ONVIF 库编写 exporter 并构建镜像，见 ONVIF_ALTERNATIVES.md 中「ONVIF 自建 Exporter」。

目录结构

edge-agent/
├── docker-compose.yml          # Docker Compose 服务编排配置
├── deploy.sh                   # 部署脚本
├── quick-setup.sh              # 快速配置脚本
├── env.example                 # 环境变量示例
├── prometheus-edge/
│   └── prometheus.yml          # Prometheus Edge 配置
├── blackbox/
│   └── config.yml              # Blackbox Exporter 配置
└── config/
    ├── targets.csv             # 统一监控目标配置（推荐）
    ├── devices.csv             # ONVIF 设备配置（旧格式）
    ├── ping-targets.csv        # Ping 目标配置（旧格式）
    ├── onvif-targets.json      # ONVIF 设备 JSON 配置（自动生成）
    ├── ping-targets.json       # Ping 目标 JSON 配置（自动生成）
    ├── update-configs.sh      # 配置文件更新脚本
    ├── csv-to-targets.sh       # 统一配置转换脚本
    ├── csv-to-json.sh         # ONVIF 配置转换脚本
    ├── csv-to-ping-json.sh    # Ping 配置转换脚本
    ├── setup-remote-write.sh  # 远程写入配置脚本
    └── test-connection.sh     # 连接测试脚本

配置文件详解

1. docker-compose.yml

作用：定义边缘节点的 Docker 容器配置

包含的服务：

必选：prometheus-edge（抓取 + remote_write）、blackbox-exporter（Ping 探测）
可选：onvif-exporter（需 --profile onvif 且设置 ONVIF_EXPORTER_IMAGE）

关键配置：

资源限制：内存和 CPU 限制（适合边缘设备）
环境变量：中央服务器地址和端口
数据保留：1 小时（边缘节点只做临时存储）
远程写入：自动推送到中央服务器

2. deploy.sh

作用：自动化部署脚本，一键部署边缘节点

功能：

✅ 检查 Docker 和 Docker Compose 环境
✅ 检查 jq 工具（用于配置转换）
✅ 生成配置文件（从 CSV 到 JSON）
✅ 验证配置文件存在性
✅ 创建环境变量文件
✅ 创建数据目录
✅ 拉取 Docker 镜像
✅ 启动所有服务

使用：

bash deploy.sh

3. quick-setup.sh

作用：快速配置脚本，自动配置边缘节点

功能：

自动检测本机 IP
创建 .env 文件
配置统一监控目标（targets.csv）
生成配置文件
可选择立即部署

使用：

bash quick-setup.sh

4. env.example / .env

作用：环境变量配置

配置项：

CENTRAL_SERVER_HOST=192.168.2.21  # 中央服务器地址
CENTRAL_SERVER_PORT=8428          # 中央服务器端口
EDGE_NODE_ID=workernode_1         # 边缘节点标识

说明：

env.example 是示例文件
部署时会自动创建 .env 文件
需要根据实际情况修改

5. prometheus-edge/prometheus.yml

作用：边缘 Prometheus 主配置文件

主要配置：

Global（全局配置）

scrape_interval: 120s          # 抓取间隔（2分钟）
evaluation_interval: 120s       # 告警评估间隔
external_labels:
  region: workernode_1          # 边缘节点标识

Remote Write（远程写入）

remote_write:
  - url: http://${CENTRAL_SERVER_HOST}:${CENTRAL_SERVER_PORT}/api/v1/write

作用：将收集的数据推送到中央服务器 VictoriaMetrics
目的：边缘节点不存储长期数据，只做数据收集和转发

Scrape Configs（抓取配置）

定义了 3 个抓取任务：

onvif-devices - 抓取 ONVIF 设备指标（通过 ONVIF Exporter）
network-ping - 抓取网络探测指标（通过 Blackbox Exporter）
prometheus-edge - 抓取自身指标

数据保留：1 小时（边缘节点只做临时存储）

6. blackbox/config.yml

作用：Blackbox Exporter 探测模块配置

支持的探测类型：

icmp - ICMP Ping 探测
tcp_connect - TCP 连接探测
http_2xx - HTTP 服务探测
http_post_2xx - HTTP POST 探测
tcp_connect_tls - TLS 连接探测

当前使用：主要使用 icmp 模块进行网络连通性探测

7. config/targets.csv

作用：统一监控目标配置文件（推荐使用）

格式：

type,ip,device,group,network,device_type,model,location,username,password,onvif_port
ping,8.8.8.8,google_dns,external,external,,,,,,
onvif,192.168.1.100,,,front_door,camera,HIKVISION_DS-2CD2342WD-I,front_door,admin,password1,80

说明：

type 字段：ping 或 onvif
可以在一个文件中配置所有监控目标
详细说明参考：doc/TARGETS_CSV_GUIDE.md

8. config/update-configs.sh

作用：从 CSV 文件生成 JSON 配置文件

功能：

优先使用 targets.csv（统一配置）
兼容旧格式（devices.csv + ping-targets.csv）
自动生成 onvif-targets.json 和 ping-targets.json

使用：

cd config
./update-configs.sh

9. config/csv-to-targets.sh

作用：统一配置转换脚本

功能：

从 targets.csv 读取配置
根据 type 字段分离 ONVIF 和 Ping 目标
生成对应的 JSON 配置文件

10. config/setup-remote-write.sh

作用：配置远程写入（已集成到部署脚本中）

11. config/test-connection.sh

作用：测试边缘节点与中央服务器的连接

功能：

测试网络连通性
测试 VictoriaMetrics 写入接口
验证配置是否正确

配置文件关系图

.env (环境变量)
    │
    ▼
prometheus-edge/prometheus.yml ──> 使用环境变量
    │
    ├─> config/onvif-targets.json ──> ONVIF Exporter
    └─> config/ping-targets.json ────> Blackbox Exporter
         │
         └─> 从 targets.csv 生成

数据流向

监控目标
    │
    ├─> ONVIF 设备 ──> ONVIF Exporter ──┐
    │                                    │
    ├─> 网络设备 ──> Blackbox Exporter ──┤
    │                                    │
    └─> 边缘节点自身 ──────────────────────┤
                                          │
                                          ▼
                              Prometheus Edge
                                          │
                                          │ remote_write
                                          ▼
                              VictoriaMetrics (中央服务器)

配置文件修改指南

修改监控目标

编辑 config/targets.csv
运行 cd config && ./update-configs.sh
等待 5 分钟自动重载，或重启容器

修改中央服务器地址

编辑 .env 文件
重启容器：docker compose restart prometheus-edge

修改 Prometheus 配置

编辑 prometheus-edge/prometheus.yml
重启容器：docker compose restart prometheus-edge

重要提示

数据保留：边缘节点只保留 1 小时数据，长期数据存储在中央服务器
资源限制：配置了内存和 CPU 限制，适合边缘设备
端口冲突：Prometheus Edge 使用 9092（避免与中央服务器冲突）
网络连通性：确保可以访问中央服务器的 8428 端口
配置更新：修改 CSV 后需要运行 update-configs.sh 生成 JSON

10 KiB Raw Blame History Unescape Escape