jack/Distributed-Prometheus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 天地图瓦片缓存(tile-cache)、拓扑标注助手与文档更新

Browse Source 
- tile-cache: 瓦片缓存服务(vec/cva)、启动探针、详细日志、上游超时可配置(UPSTREAM_TIMEOUT_MS)
- central: docker-compose 集成 tile-cache，env.example 增加 TILE_CACHE_* / TIANDITU_TK
- topology-editor: 天地图/缓存加载、GPS 安全来源错误提示、TIANDITU 文档(403/白名单、localhost 测试说明)
- doc: README 部署步骤与 GPS 安全来源说明，TIANDITU_CONFIG 完善

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Super User
2026-02-25 11:11:38 -05:00
parent 84d2bcc2cf
commit 72a5bf30b4
32 changed files with 2496 additions and 1941 deletions
Download Patch File Download Diff File Expand all files Collapse all files

328
doc/EDGE_AGENT_CONFIG.md
View File

@@ -1,323 +1,35 @@
# 边缘节点配置文件说明
## 边缘节点需要什么
## 需要什么
| 类型 | 说明 | 对应组件 |
|------|------|----------|
| **必选** | **remote_write**：把边缘指标推到中央 | **prometheus-edge**（内配 remote_write 到中央 VictoriaMetrics） |
| **必选** | **Blackbox**：Ping/网络探测 | **blackbox-exporter** 容器 |
| **可选** | ONVIF、SNMP、Frigate 等 | **onvif-exporter**（`--profile onvif`）、或自建/第三方镜像 |
| **必选** | remote_write 推送到中央 | prometheus-edge |
| **必选** | Ping/网络探测 | blackbox-exporter |
| **可选** | ONVIF 等 | onvif-exporter（`--profile onvif`），见 [ONVIF_ALTERNATIVES.md](ONVIF_ALTERNATIVES.md) |
默认部署只起 **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-exporter | Ping/HTTP/TCP 探测 | 9115（内部） |
| onvif-exporter | 可选，ONVIF 探测 | 9600（内部） |
## 边缘节点各容器分别做什么
数据流：目标 → Exporter → prometheus-edge → remote_write → 中央 VictoriaMetrics。
| 容器 | 必选/可选 | 作用 | 端口/接口 |
|------|-----------|------|-----------|
| **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 → 中央。
- **config/targets.csv**：统一监控目标（ping/onvif/topology），格式与脚本见 [TARGETS_AND_MONITORING.md](TARGETS_AND_MONITORING.md)。
- **config/update-configs.sh**：从 targets.csv 生成 `onvif-targets.json`、`ping-targets.json`。
- **prometheus-edge**：使用 `prometheus.yml.template` + deploy.sh 中 envsubst，注入 `CENTRAL_SERVER_HOST`/`PORT`；数据目录使用 Docker 卷 `prometheus-edge-data`。
- **.env**：`CENTRAL_SERVER_HOST`、`CENTRAL_SERVER_PORT=8428`、`EDGE_NODE_ID`。本机同机可用 `run-edge-local.sh`（host.docker.internal）；跨机填中央 IP。
---
## 常用操作
## 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
---
- 改监控目标：编辑 `config/targets.csv` → `cd config && ./update-configs.sh`，必要时重启 prometheus-edge。
- 改中央地址：编辑 `.env` → `docker compose restart prometheus-edge`。
## 相关文档
- **边缘节点配置**：`doc/EDGE_NODE_SETUP.md`
- **监控目标说明**：`doc/MONITORING_TARGETS.md`
- **统一配置指南**：`doc/TARGETS_CSV_GUIDE.md`
- **系统架构**：`doc/ARCHITECTURE.md`
- [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) | [TARGETS_AND_MONITORING.md](TARGETS_AND_MONITORING.md) | [ONVIF_ALTERNATIVES.md](ONVIF_ALTERNATIVES.md) | [ARCHITECTURE.md](ARCHITECTURE.md)