完善中央与边缘部署、远程写入与监控文档
- 增加中央与边缘完整配置和部署脚本 - 引入 VictoriaMetrics 数据源与 remote_write 故障排查说明 - 新增 edge-agent 配置脚本、ONVIF 自建 exporter 与 ping 监控示例 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Super User
323
doc/EDGE_AGENT_CONFIG.md
Normal file
323
doc/EDGE_AGENT_CONFIG.md
Normal file
@@ -0,0 +1,323 @@
|
||||
# 边缘节点配置文件说明
|
||||
|
||||
## 边缘节点需要什么
|
||||
|
||||
| 类型 | 说明 | 对应组件 |
|
||||
|------|------|----------|
|
||||
| **必选** | **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](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_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
|
||||
|
||||
**作用**：自动化部署脚本，一键部署边缘节点
|
||||
|
||||
**功能**：
|
||||
1. ✅ 检查 Docker 和 Docker Compose 环境
|
||||
2. ✅ 检查 jq 工具（用于配置转换）
|
||||
3. ✅ 生成配置文件（从 CSV 到 JSON）
|
||||
4. ✅ 验证配置文件存在性
|
||||
5. ✅ 创建环境变量文件
|
||||
6. ✅ 创建数据目录
|
||||
7. ✅ 拉取 Docker 镜像
|
||||
8. ✅ 启动所有服务
|
||||
|
||||
**使用**：
|
||||
```bash
|
||||
bash deploy.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. quick-setup.sh
|
||||
|
||||
**作用**：快速配置脚本，自动配置边缘节点
|
||||
|
||||
**功能**：
|
||||
- 自动检测本机 IP
|
||||
- 创建 `.env` 文件
|
||||
- 配置统一监控目标（`targets.csv`）
|
||||
- 生成配置文件
|
||||
- 可选择立即部署
|
||||
|
||||
**使用**：
|
||||
```bash
|
||||
bash quick-setup.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. env.example / .env
|
||||
|
||||
**作用**：环境变量配置
|
||||
|
||||
**配置项**：
|
||||
```bash
|
||||
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（全局配置）
|
||||
```yaml
|
||||
scrape_interval: 120s # 抓取间隔（2分钟）
|
||||
evaluation_interval: 120s # 告警评估间隔
|
||||
external_labels:
|
||||
region: workernode_1 # 边缘节点标识
|
||||
```
|
||||
|
||||
#### Remote Write（远程写入）
|
||||
```yaml
|
||||
remote_write:
|
||||
- url: http://${CENTRAL_SERVER_HOST}:${CENTRAL_SERVER_PORT}/api/v1/write
|
||||
```
|
||||
- **作用**：将收集的数据推送到中央服务器 VictoriaMetrics
|
||||
- **目的**：边缘节点不存储长期数据，只做数据收集和转发
|
||||
|
||||
#### Scrape Configs（抓取配置）
|
||||
定义了 3 个抓取任务：
|
||||
1. **onvif-devices** - 抓取 ONVIF 设备指标（通过 ONVIF Exporter）
|
||||
2. **network-ping** - 抓取网络探测指标（通过 Blackbox Exporter）
|
||||
3. **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
|
||||
|
||||
**作用**：统一监控目标配置文件（推荐使用）
|
||||
|
||||
**格式**：
|
||||
```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`
|
||||
|
||||
**使用**：
|
||||
```bash
|
||||
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 (中央服务器)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 配置文件修改指南
|
||||
|
||||
### 修改监控目标
|
||||
|
||||
1. 编辑 `config/targets.csv`
|
||||
2. 运行 `cd config && ./update-configs.sh`
|
||||
3. 等待 5 分钟自动重载，或重启容器
|
||||
|
||||
### 修改中央服务器地址
|
||||
|
||||
1. 编辑 `.env` 文件
|
||||
2. 重启容器：`docker compose restart prometheus-edge`
|
||||
|
||||
### 修改 Prometheus 配置
|
||||
|
||||
1. 编辑 `prometheus-edge/prometheus.yml`
|
||||
2. 重启容器：`docker compose restart prometheus-edge`
|
||||
|
||||
---
|
||||
|
||||
## 重要提示
|
||||
|
||||
1. **数据保留**：边缘节点只保留 1 小时数据，长期数据存储在中央服务器
|
||||
2. **资源限制**：配置了内存和 CPU 限制，适合边缘设备
|
||||
3. **端口冲突**：Prometheus Edge 使用 9092（避免与中央服务器冲突）
|
||||
4. **网络连通性**：确保可以访问中央服务器的 8428 端口
|
||||
5. **配置更新**：修改 CSV 后需要运行 `update-configs.sh` 生成 JSON
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- **边缘节点配置**：`doc/EDGE_NODE_SETUP.md`
|
||||
- **监控目标说明**：`doc/MONITORING_TARGETS.md`
|
||||
- **统一配置指南**：`doc/TARGETS_CSV_GUIDE.md`
|
||||
- **系统架构**：`doc/ARCHITECTURE.md`
|
||||
Reference in New Issue
Block a user