# 边缘节点配置文件说明

## 边缘节点需要什么

| 类型 | 说明 | 对应组件 |
|------|------|----------|
| **必选** | **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`