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

52
doc/ALERTING.md Normal file
View File

@@ -0,0 +1,52 @@
# 告警与通知
本文说明告警规则、如何激活，以及 Alertmanager 的配置与通知渠道。
---
## 告警规则（alert_rules.yml）
中央已内置 `central-server/alert_rules.yml`，主要包含：
| 规则 | 条件 | 说明 |
|------|------|------|
| ONVIFDeviceDown | `up{job="onvif-devices"} == 0` 持续 1m | ONVIF 设备离线 |
| NetworkDeviceDown | `probe_success{job="network-ping"} == 0` 持续 2m | 网络设备 Ping 不通 |
| HighNetworkLatency | `probe_duration_seconds{job="network-ping"} > 1` 持续 5m | Ping 延迟过高 |
**为何显示 Inactive**：规则依赖边缘推送的指标。需先部署边缘、配置 Ping/ONVIF 目标，数据经 remote_write 到 VictoriaMetrics 后，规则才会评估；无数据时保持 inactive。
**激活步骤**：完成 [README.md#第二步](README.md) 边缘部署 → 在 Grafana 选 VictoriaMetrics 数据源确认有 `probe_success{job="network-ping"}` 等 → Prometheus 会从 VictoriaMetrics 取数并评估规则。
---
## Alertmanager 配置（alertmanager.yml）
路径：`central-server/alertmanager/alertmanager.yml`。
- **route**：分组（group_by）、等待时间（group_wait）、重复间隔（repeat_interval）、默认接收器（receiver）。
- **receivers**：当前示例为 webhook `http://127.0.0.1:5001/`。
**注意**：容器内 127.0.0.1 指向自身，若 webhook 在宿主机，应改为 `http://host.docker.internal:5001/` 或宿主机 IP。
- **inhibit_rules**：critical 抑制同实例的 warning，减少告警风暴。
**常用接收器类型**：`email_configs`、`wechat_configs`、`dingtalk_configs`、`webhook_configs`。按需替换为邮件、企业微信、钉钉或自建 webhook。
**验证**：`docker exec alertmanager amtool check-config /etc/alertmanager/alertmanager.yml`；Web UI：http://localhost:9093。
---
## 自定义告警规则
在 `alert_rules.yml` 中追加或修改规则，例如：
```yaml
- alert: ExampleAlert
expr: your_metric > threshold
for: 5m
labels:
severity: warning
annotations:
summary: "示例告警"
```
修改后若 Prometheus 启用了 `--web.enable-lifecycle`，可 `curl -X POST http://localhost:9091/-/reload` 重载。

300
doc/ALERTMANAGER_CONFIG.md
View File

@@ -1,300 +0,0 @@
# Alertmanager 配置说明
## 配置文件概述
`alertmanager.yml` 是 Alertmanager 的核心配置文件，用于定义告警路由、通知方式和告警抑制规则。
## 配置详解
### 1. Global（全局配置）
```yaml
global:
smtp_smarthost: 'localhost:587'
smtp_from: 'alertmanager@example.com'
```
**作用**：定义全局的 SMTP 邮件服务器配置
**字段说明**：
- `smtp_smarthost`: SMTP 服务器地址和端口
- 当前配置：`localhost:587`（本地邮件服务器）
- 如果使用外部邮件服务，例如：
- Gmail: `smtp.gmail.com:587`
- 163邮箱: `smtp.163.com:465`
- 企业邮箱: `smtp.company.com:587`
- `smtp_from`: 发送告警邮件的发件人地址
- 当前配置：`alertmanager@example.com`（示例地址，需要修改）
**注意**：当前配置使用的是 webhook，所以 SMTP 配置暂时未使用。
---
### 2. Route（路由配置）
```yaml
route:
group_by: ['alertname']
group_wait: 10s
group_interval: 10s
repeat_interval: 1h
receiver: 'web.hook'
```
**作用**：定义告警的路由规则，决定告警如何分组和发送
**字段说明**：
| 字段 | 说明 | 当前值 | 含义 |
|------|------|--------|------|
| `group_by` | 告警分组字段 | `['alertname']` | 按告警名称分组，相同名称的告警会被合并 |
| `group_wait` | 分组等待时间 | `10s` | 收到第一个告警后，等待10秒再发送（用于合并同类告警） |
| `group_interval` | 分组间隔 | `10s` | 同一分组内新告警的发送间隔 |
| `repeat_interval` | 重复间隔 | `1h` | 如果告警持续存在，每1小时重复发送一次通知 |
| `receiver` | 默认接收器 | `'web.hook'` | 所有告警默认发送到 `web.hook` 接收器 |
**示例场景**：
- 如果 3 个设备同时离线，会在 10 秒内合并为一条告警发送
- 如果告警持续存在，每小时会重复通知一次
---
### 3. Receivers（接收器配置）
```yaml
receivers:
- name: 'web.hook'
webhook_configs:
- url: 'http://127.0.0.1:5001/'
```
**作用**：定义告警通知的接收方式
**当前配置**：
- **接收器名称**：`web.hook`
- **通知方式**：Webhook（HTTP POST）
- **目标地址**：`http://127.0.0.1:5001/`
**说明**：
- 告警会以 JSON 格式 POST 到指定的 URL
- 需要有一个服务监听 `127.0.0.1:5001` 来处理告警
- 如果没有这个服务，告警通知会失败
**其他可用的接收器类型**：
- `email_configs` - 邮件通知
- `wechat_configs` - 企业微信通知
- `dingtalk_configs` - 钉钉通知
- `slack_configs` - Slack 通知
- `webhook_configs` - 自定义 Webhook
---
### 4. Inhibit Rules（抑制规则）
```yaml
inhibit_rules:
- source_match:
severity: 'critical'
target_match:
severity: 'warning'
equal: ['alertname', 'dev', 'instance']
```
**作用**：定义告警抑制规则，避免重复告警
**当前规则说明**：
- **源匹配**：如果存在 `severity: critical` 的告警
- **目标匹配**：则抑制 `severity: warning` 的告警
- **匹配条件**：当 `alertname`、`dev`、`instance` 标签相同时
**示例场景**：
- 如果设备离线（critical），则不再发送该设备的温度过高（warning）告警
- 避免告警风暴，只关注最严重的问题
**注意**：当前配置中的 `dev` 标签可能不存在，建议修改为实际使用的标签。
---
## 配置流程图
```
Prometheus 触发告警
│
▼
Alertmanager 接收告警
│
├─> 按 alertname 分组
├─> 等待 10s（group_wait）
├─> 应用抑制规则
│
▼
发送到接收器 (web.hook)
│
▼
POST 到 http://127.0.0.1:5001/
```
---
## 常见配置场景
### 场景 1：邮件通知
```yaml
receivers:
- name: 'email'
email_configs:
- to: 'admin@example.com'
from: 'alertmanager@example.com'
smarthost: 'smtp.gmail.com:587'
auth_username: 'your-email@gmail.com'
auth_password: 'your-password'
```
### 场景 2：企业微信通知
```yaml
receivers:
- name: 'wechat'
wechat_configs:
- api_url: 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send'
corp_id: 'your-corp-id'
to_user: '@all'
```
### 场景 3：多接收器（根据严重程度）
```yaml
route:
routes:
- match:
severity: critical
receiver: 'critical-alerts'
- match:
severity: warning
receiver: 'warning-alerts'
receiver: 'default'
receivers:
- name: 'critical-alerts'
email_configs:
- to: 'oncall@example.com'
- name: 'warning-alerts'
webhook_configs:
- url: 'http://127.0.0.1:5001/'
```
---
## 当前配置的问题和建议
### 问题 1：Webhook 服务不存在
**当前配置**：`http://127.0.0.1:5001/`
**问题**：如果没有服务监听这个端口，告警通知会失败
**解决方案**：
1. **部署 Webhook 接收服务**（推荐用于开发测试）
2. **配置邮件通知**（推荐用于生产环境）
3. **配置企业微信/钉钉**（推荐用于团队协作）
### 问题 2：抑制规则标签不匹配
**当前配置**：`equal: ['alertname', 'dev', 'instance']`
**问题**：`dev` 标签可能不存在于告警中
**建议修改**：
```yaml
equal: ['alertname', 'instance']
```
### 问题 3：SMTP 配置未使用
**当前配置**：SMTP 配置存在但未使用
**建议**：
- 如果使用邮件通知，需要配置正确的 SMTP 服务器
- 如果只使用 Webhook，可以删除 SMTP 配置
---
## 验证配置
### 1. 检查配置语法
```bash
docker exec alertmanager amtool check-config /etc/alertmanager/alertmanager.yml
```
### 2. 查看告警状态
访问 Alertmanager Web UI：
```
http://localhost:9093
```
### 3. 测试告警
在 Prometheus 中手动触发告警，查看是否收到通知。
---
## 配置示例（推荐）
### 最小化 Webhook 配置
```yaml
route:
group_by: ['alertname', 'instance']
group_wait: 10s
group_interval: 10s
repeat_interval: 1h
receiver: 'web.hook'
receivers:
- name: 'web.hook'
webhook_configs:
- url: 'http://127.0.0.1:5001/'
send_resolved: true # 发送恢复通知
inhibit_rules:
- source_match:
severity: 'critical'
target_match:
severity: 'warning'
equal: ['alertname', 'instance']
```
### 邮件通知配置
```yaml
global:
smtp_smarthost: 'smtp.gmail.com:587'
smtp_from: 'alertmanager@example.com'
smtp_auth_username: 'your-email@gmail.com'
smtp_auth_password: 'your-app-password'
route:
group_by: ['alertname']
group_wait: 10s
group_interval: 10s
repeat_interval: 1h
receiver: 'email'
receivers:
- name: 'email'
email_configs:
- to: 'admin@example.com'
send_resolved: true
```
---
## 下一步
1. **配置通知渠道**：根据实际需求配置邮件、企业微信、钉钉等
2. **测试告警**：确保告警能够正常发送
3. **优化路由规则**：根据业务需求调整告警分组和路由
4. **设置告警抑制**：避免告警风暴

130
doc/ALERT_RULES_EXPLANATION.md
View File

@@ -1,130 +0,0 @@
# 告警规则说明
## 告警规则概述
当前配置了两组告警规则，用于监控 ONVIF 设备和网络设备的状态。
## 告警规则详解
### 1. ONVIF 设备告警组 (onvif_alerts)
#### ONVIFDeviceDown - ONVIF设备离线
- **触发条件**：`up{job="onvif-devices"} == 0`
- **持续时间**：1分钟
- **严重程度**：critical（严重）
- **说明**：当 ONVIF 设备（如摄像头）无法访问或离线超过1分钟时触发
- **告警信息**：显示哪个设备实例离线
#### ONVIFDeviceHighTemperature - ONVIF设备温度过高
- **触发条件**：`onvif_device_temperature > 70`
- **持续时间**：2分钟
- **严重程度**：warning（警告）
- **说明**：当设备温度超过70°C时触发，防止设备过热损坏
- **告警信息**：显示设备实例和当前温度值
#### ONVIFDeviceLowStorage - ONVIF设备存储空间不足
- **触发条件**：`onvif_storage_usage_percent > 90`
- **持续时间**：5分钟
- **严重程度**：warning（警告）
- **说明**：当设备存储使用率超过90%时触发，提醒需要清理存储空间
- **告警信息**：显示设备实例和存储使用率
### 2. 网络设备告警组 (network_alerts)
#### NetworkDeviceDown - 网络设备离线
- **触发条件**：`probe_success{job="network-ping"} == 0`
- **持续时间**：2分钟
- **严重程度**：critical（严重）
- **说明**：当网络设备无法通过 ping 连通时触发
- **告警信息**：显示哪个网络设备实例无法访问
#### HighNetworkLatency - 网络延迟过高
- **触发条件**：`probe_duration_seconds{job="network-ping"} > 1`
- **持续时间**：5分钟
- **严重程度**：warning（警告）
- **说明**：当网络延迟超过1秒时触发，表示网络质量下降
- **告警信息**：显示设备实例和延迟时间
## 为什么告警规则是 Inactive（非活跃）状态？
告警规则显示为 **inactive** 的原因：
1. **缺少数据源**：
- 这些告警依赖于边缘节点推送的数据
- 需要配置 `edge-agent` 并部署到边缘节点
- 边缘节点需要配置 ONVIF 设备和网络探测目标
2. **指标不存在**：
- `up{job="onvif-devices"}` - 需要边缘节点运行 ONVIF Exporter
- `probe_success{job="network-ping"}` - 需要边缘节点运行 Blackbox Exporter
- 如果这些指标不存在，告警规则无法评估，所以是 inactive
3. **数据未推送**：
- 边缘节点的数据需要通过 `remote_write` 推送到中央服务器
- 检查边缘节点是否正常连接并推送数据
## 如何激活告警规则？
### 步骤 1：部署边缘节点代理
```bash
cd ../edge-agent
bash deploy.sh
```
### 步骤 2：配置监控目标
1. **配置 ONVIF 设备**：
- 编辑 `edge-agent/config/devices.csv`
- 添加要监控的 ONVIF 设备信息
2. **配置网络探测目标**：
- 编辑 `edge-agent/config/ping-targets.csv`
- 添加要监控的网络设备 IP 地址
### 步骤 3：更新配置
```bash
cd edge-agent/config
./update-configs.sh
```
### 步骤 4：验证数据推送
1. 在 Prometheus 中查询指标：
```promql
up{job="onvif-devices"}
probe_success{job="network-ping"}
```
2. 如果能看到数据，告警规则会自动变为 **active** 状态
## 告警状态说明
- **Inactive（非活跃）**：告警规则已加载，但没有匹配的数据或条件未满足
- **Pending（待触发）**：条件满足，但未达到持续时间阈值
- **Firing（触发中）**：条件满足且持续时间达到阈值，告警已触发
- **Resolved（已解决）**：告警条件不再满足，告警已恢复
## 告警通知
当告警触发时，会发送到 Alertmanager，然后根据配置发送通知：
- 当前配置：发送到 webhook `http://127.0.0.1:5001/`
- 可以修改 `alertmanager/alertmanager.yml` 配置邮件、钉钉、企业微信等通知方式
## 自定义告警规则
可以在 `alert_rules.yml` 中添加更多告警规则，例如：
```yaml
- alert: CustomAlert
expr: your_metric > threshold
for: 5m
labels:
severity: warning
annotations:
summary: "自定义告警"
description: "描述信息"
```
修改后，Prometheus 会自动重新加载配置（如果启用了 `--web.enable-lifecycle`）。

24
doc/ARCHITECTURE.md
View File

@@ -130,24 +130,8 @@ Alertmanager 处理告警
### 3. 查询流程
```
用户访问 Grafana
│
▼
Grafana 发送 PromQL 查询
│
▼
Prometheus 处理查询
│
├─> 从 VictoriaMetrics 读取数据
└─> 返回查询结果
│
▼
Grafana 渲染图表
│
▼
用户查看监控数据
```
- **中央自抓指标**：Grafana → Prometheus 数据源 → Prometheus 返回结果。
- **边缘数据**：Grafana → **VictoriaMetrics** 数据源 → VictoriaMetrics 返回结果（不经过 Prometheus 查询 VM）。
## 容器详细说明
@@ -160,7 +144,7 @@ Grafana 渲染图表
### 2. Prometheus Central (9091)
- **作用**：指标收集、查询和告警评估
- **数据源**：
- 从 VictoriaMetrics 读取边缘节点数据
- 从 VictoriaMetrics 读取边缘节点数据（用于告警规则评估与部分查询）
- 抓取本地服务（自身、Grafana、Alertmanager、VictoriaMetrics）
- **功能**：
- 评估告警规则 (`alert_rules.yml`)
@@ -178,7 +162,7 @@ Grafana 渲染图表
### 4. Grafana (3000)
- **作用**：数据可视化和仪表板
- **数据源**：从 Prometheus 查询数据
- **数据源**：**Prometheus**（中央自抓指标）、**VictoriaMetrics**（边缘推送数据；查边缘 Ping/ONVIF 等请选此数据源）
- **功能**：
- 创建图表和仪表板
- 多用户管理（组织隔离）

331
doc/CENTRAL_SERVER_CONFIG.md
View File

@@ -4,323 +4,40 @@
```
central-server/
├── docker-compose.yml # Docker Compose 服务编排配置
├── docker-compose.yml # 服务编排
├── deploy.sh # 部署脚本
├── prometheus.yml # Prometheus 主配置文件
├── alert_rules.yml # 告警规则定义
├── alertmanager/
│ └── alertmanager.yml # Alertmanager 告警管理配置
├── prometheus.yml # Prometheus 主配置
├── alert_rules.yml # 告警规则
├── alertmanager/alertmanager.yml
└── grafana/
├── setup-users.sh # 多用户配置脚本
├── provisioning/
│ ├── datasources/ # 数据源自动配置
│ │ ├── prometheus.yml # Prometheus 数据源
│ │ └── prometheus-admin.yml # 管理员全局数据源
│ └── dashboards/ # 仪表板自动配置
│ └── dashboard.yml # 仪表板配置
├── setup-users.sh
├── provisioning/datasources/ # prometheus.yml, victoriametrics.yml
└── dashboards/
└── onvif-monitoring.json # ONVIF 监控仪表板
```
## 配置文件详解
## 主要服务与端口
### 1. docker-compose.yml
| 服务 | 端口 | 说明 |
|------|------|------|
| prometheus-central | 9091 | 自抓 + 告警评估；边缘数据由 Grafana 从 VictoriaMetrics 查询 |
| grafana | 3000 | 数据源：Prometheus（中央自抓）、VictoriaMetrics（边缘数据） |
| victoria-metrics | 8428 | 接收边缘 remote_write |
| alertmanager | 9093 | 告警路由与通知 |
**作用**：定义所有 Docker 容器的配置和编排
## 关键配置摘要
**包含的服务**：
- `prometheus-central` - Prometheus 中央服务器（端口 9091）
- `grafana` - Grafana 可视化仪表板（端口 3000，中文界面）
- `alertmanager` - 告警管理器（端口 9093）
- `victoria-metrics` - 远程写入接收器（端口 8428）
- **prometheus.yml**：`remote_write` 指向 VictoriaMetrics；`rule_files: alert_rules.yml`；抓取自身、VM、Alertmanager、Grafana。
- **告警规则与通知**：见 [ALERTING.md](ALERTING.md)。
- **Grafana 数据源**：Provisioning 下配置 Prometheus、VictoriaMetrics；查边缘指标请选 **VictoriaMetrics**。
- **Grafana Geomap 使用天地图缓存**：在 Geomap 面板中将 Base layer 选为 **XYZ Tile layer**，底图 URL 填 `http://<central>:4080/tiles/vec/{z}/{x}/{y}`，再添加一层 XYZ 填 `http://<central>:4080/tiles/cva/{z}/{x}/{y}`（中文注记）。key 仅需在 central 配置 `TIANDITU_TK`，无需在 Grafana 中填写。详见 [TIANDITU_CONFIG.md](TIANDITU_CONFIG.md)。
- **多用户**：`grafana/setup-users.sh`，见 [USER_MANAGEMENT.md](USER_MANAGEMENT.md)。
**关键配置**：
- 数据存储：所有数据存储在 `/storage` 分区
- 网络：所有容器在 `monitoring_net` 网络中
- 卷挂载：配置文件、数据目录、仪表板等
## 修改与重载
**使用**：
```bash
docker compose up -d # 启动所有服务
docker compose down # 停止所有服务
```
---
### 2. deploy.sh
**作用**：自动化部署脚本，一键部署中央服务器
**功能**：
1. ✅ 检查 Docker 和 Docker Compose 环境
2. ✅ 检查磁盘空间（根分区和 /storage 分区）
3. ✅ 验证配置文件存在性
4. ✅ 创建数据目录并设置权限
5. ✅ 拉取 Docker 镜像
6. ✅ 启动所有服务
7. ✅ 检查服务状态
**使用**：
```bash
bash deploy.sh
```
**输出信息**：
- 服务访问地址
- 管理命令
- 防火墙提示
- 下一步操作建议
---
### 3. prometheus.yml
**作用**：Prometheus 主配置文件，定义数据收集和查询规则
**主要配置**：
#### Global（全局配置）
```yaml
scrape_interval: 15s # 抓取间隔
evaluation_interval: 15s # 告警规则评估间隔
external_labels:
cluster: 'central-monitoring' # 集群标识
```
#### Remote Write（远程写入）
```yaml
remote_write:
- url: http://victoria-metrics:8428/api/v1/write
```
- **作用**：将 Prometheus 收集的数据写入 VictoriaMetrics
- **目的**：接收边缘节点推送的数据
#### Scrape Configs（抓取配置）
定义了 4 个抓取任务：
1. **prometheus-central** - 抓取自身指标
2. **victoria-metrics** - 抓取 VictoriaMetrics 指标
3. **alertmanager** - 抓取 Alertmanager 指标
4. **grafana** - 抓取 Grafana 指标
#### Rule Files（告警规则文件）
```yaml
rule_files:
- "alert_rules.yml"
```
- 引用 `alert_rules.yml` 文件中的告警规则
#### Alerting（告警配置）
```yaml
alerting:
alertmanagers:
- static_configs:
- targets:
- alertmanager:9093
```
- 配置 Alertmanager 地址，用于发送告警
---
### 4. alert_rules.yml
**作用**：定义告警规则，当监控指标满足条件时触发告警
**告警组**：
#### onvif_alerts（ONVIF 设备告警组）
- **ONVIFDeviceDown** - 设备离线告警（critical）
- **ONVIFDeviceHighTemperature** - 设备温度过高告警（warning）
- **ONVIFDeviceLowStorage** - 设备存储空间不足告警（warning）
#### network_alerts（网络设备告警组）
- **NetworkDeviceDown** - 网络设备离线告警（critical）
- **HighNetworkLatency** - 网络延迟过高告警（warning）
**告警规则格式**：
```yaml
- alert: AlertName
expr: promql_query # PromQL 查询表达式
for: 1m # 持续时间
labels:
severity: critical # 严重程度
annotations:
summary: "告警摘要"
description: "详细描述"
```
**详细说明**：参考 `doc/ALERT_RULES_EXPLANATION.md`
---
### 5. alertmanager/alertmanager.yml
**作用**：Alertmanager 配置，定义告警路由和通知方式
**主要配置**：
#### Global（全局配置）
- SMTP 邮件服务器配置（当前未使用）
#### Route（路由配置）
- 告警分组规则
- 告警发送间隔
- 默认接收器
#### Receivers（接收器）
- 当前配置：Webhook `http://127.0.0.1:5001/`
- 可配置：邮件、企业微信、钉钉等
#### Inhibit Rules（抑制规则）
- 避免重复告警
- 当 critical 告警存在时，抑制 warning 告警
**详细说明**：参考 `doc/ALERTMANAGER_CONFIG.md`
---
### 6. grafana/provisioning/
**作用**：Grafana 自动配置目录，容器启动时自动加载
#### datasources/prometheus.yml
**作用**：自动配置 Prometheus 数据源
**配置内容**：
- 数据源名称：Prometheus
- 数据源类型：prometheus
- 访问方式：proxy（通过 Grafana 代理）
- URL：`http://prometheus-central:9090`
- 默认数据源：是
#### datasources/prometheus-admin.yml
**作用**：管理员全局数据源（可选）
**特点**：
- 允许管理员查看所有数据（不受标签过滤限制）
- 用于管理员查看全局监控数据
#### dashboards/dashboard.yml
**作用**：自动加载仪表板配置
**配置内容**：
- 从 `/var/lib/grafana/dashboards` 目录自动加载仪表板
- 更新间隔：10 秒
- 允许 UI 更新：是
---
### 7. grafana/dashboards/onvif-monitoring.json
**作用**：ONVIF 设备监控仪表板
**内容**：
- ONVIF 设备状态面板
- 设备在线率仪表
- 其他监控图表
**自动加载**：通过 `dashboard.yml` 配置自动加载
---
### 8. grafana/setup-users.sh
**作用**：自动化配置 Grafana 多用户和组织
**功能**：
- 创建 Grafana 组织
- 创建用户并分配到组织
- 通过 Grafana API 批量配置
**使用**：
```bash
cd central-server/grafana
bash setup-users.sh
```
**详细说明**：参考 `doc/USER_MANAGEMENT.md`
---
## 配置文件关系图
```
docker-compose.yml
│
├─> prometheus.yml ──┐
│ │
├─> alert_rules.yml ──┤──> Prometheus 容器
│ │
└─> alertmanager.yml ─┘──> Alertmanager 容器
│
└─> grafana/
├─> provisioning/ ──> Grafana 自动配置
└─> dashboards/ ────> 仪表板文件
```
---
## 数据流向
```
边缘节点数据
│
▼
VictoriaMetrics (8428) ──> 存储数据
│
▼
Prometheus (9091) ──┬──> 查询数据 ──> Grafana (3000)
│ │
└──> 评估告警规则 (alert_rules.yml)
│
▼
Alertmanager (9093) ──> 发送通知
```
---
## 配置文件修改指南
### 修改 Prometheus 配置
1. 编辑 `prometheus.yml`
2. 重启容器：`docker compose restart prometheus-central`
3. 或使用热重载：`curl -X POST http://localhost:9091/-/reload`
### 修改告警规则
1. 编辑 `alert_rules.yml`
2. 重启容器：`docker compose restart prometheus-central`
3. 或使用热重载：`curl -X POST http://localhost:9091/-/reload`
### 修改 Alertmanager 配置
1. 编辑 `alertmanager/alertmanager.yml`
2. 重启容器：`docker compose restart alertmanager`
### 修改 Grafana 配置
1. 编辑 `grafana/provisioning/` 下的配置文件
2. 重启容器：`docker compose restart grafana`
3. 或通过 Grafana Web UI 修改（会持久化到数据库）
---
## 重要提示
1. **数据存储**：所有数据存储在 `/storage` 分区，避免根分区空间不足
2. **端口映射**：Prometheus 使用 9091（避免与 cockpit 冲突）
3. **配置文件权限**：确保配置文件有正确的读取权限
4. **网络连通性**：确保边缘节点可以访问 8428 端口（VictoriaMetrics）
5. **告警通知**：当前配置使用 webhook，需要部署接收服务或修改为其他通知方式
---
- Prometheus：改 `prometheus.yml` 或 `alert_rules.yml` 后 `docker compose restart prometheus-central`，或 `curl -X POST http://localhost:9091/-/reload`（若启用 lifecycle）。
- Alertmanager：改 `alertmanager/alertmanager.yml` 后 `docker compose restart alertmanager`。
- Grafana：改 provisioning 后重启；或通过 Web UI 修改（持久化到库）。
## 相关文档
- **系统架构**：`doc/ARCHITECTURE.md`
- **告警规则**：`doc/ALERT_RULES_EXPLANATION.md`
- **Alertmanager 配置**：`doc/ALERTMANAGER_CONFIG.md`
- **用户管理**：`doc/USER_MANAGEMENT.md`
- [ARCHITECTURE.md](ARCHITECTURE.md) | [ALERTING.md](ALERTING.md) | [USER_MANAGEMENT.md](USER_MANAGEMENT.md) | [central-server/CONFIGURATION.md](../central-server/CONFIGURATION.md)

158
doc/DEPLOYMENT_GUIDE.md
View File

@@ -1,161 +1,61 @@
# 部署指南
部署顺序见 **[doc/README.md](README.md)#部署顺序**：**第一步 中央服务器 → 第二步 边缘节点 → 第三步（可选）多用户与告警**。本文为各步的详细说明、检查清单与常见问题。
部署顺序见 **[doc/README.md](README.md)#部署顺序**：中央 → 边缘 → 多用户/告警（可选）→ 拓扑标注（可选）。本文为各步操作与验证要点。
---
## 第一步：部署中央服务器
### 前置要求
**前置**：Docker、Docker Compose；端口 3000、9091、8428、9093、4080 未被占用；磁盘充足。
- Docker 与 Docker Compose 已安装
- 根分区至少约 1GB 可用；数据目录所在分区至少约 2GB
- 端口未被占用：3000（Grafana）、9091（Prometheus）、8428（VictoriaMetrics）、9093（Alertmanager）
- 若需外网访问：防火墙开放上述端口
```bash
cd central-server
cp env.example .env # 可选
bash deploy.sh
```
### 操作步骤
1. 进入目录并准备环境（可选）：
```bash
cd central-server
cp env.example .env # 可选：修改端口、Traefik、网络等
```
2. 执行部署：
```bash
bash deploy.sh
```
3. 等待约 15 秒后检查：
```bash
docker compose ps
```
4. 验证访问：
- Grafana: http://localhost:3000（默认 admin / admin123）
- Prometheus: http://localhost:9091
- VictoriaMetrics: http://localhost:8428
- Alertmanager: http://localhost:9093
### 中央服务器检查清单
- [ ] Docker、Docker Compose 已安装
- [ ] 磁盘空间充足（根分区约 1GB+，数据分区约 2GB+）
- [ ] 端口 3000、9091、8428、9093 未被占用
- [ ] 需要时已开放防火墙
- [ ] 部署后能打开 Grafana、Prometheus
**验证**：Grafana http://localhost:3000（admin/admin123）、Prometheus http://localhost:9091、VictoriaMetrics http://localhost:8428、拓扑标注助手 http://localhost:4080。
---
## 第二步：部署边缘节点
**前提**：第一步中央服务器已部署并正常运行（尤其 VictoriaMetrics 8428 可访问）。
**前提**：中央已运行，VictoriaMetrics 8428 可访问。
### 前置要求
- **本机同机**：`cd edge-agent && bash run-edge-local.sh`（中央地址设为 host.docker.internal:8428）。
- **边缘在另一台机器**：
- 在 edge-agent 下 `cp env.example .env`，编辑 `CENTRAL_SERVER_HOST`、`CENTRAL_SERVER_PORT=8428`。
- `cd config && ./update-configs.sh && cd .. && bash deploy.sh`。
- Docker、Docker Compose 已安装
- `jq` 已安装（用于生成 JSON 配置）
- 边缘节点能访问中央服务器（能访问中央 IP:8428）
- 如需监控 ONVIF/网络设备：网络可达这些设备
**验证**：边缘 Prometheus http://localhost:9092（或边缘机 IP:9092）；中央 Grafana 选数据源 **VictoriaMetrics**，查询 `probe_success{job="network-ping"}` 可见边缘数据。
### 情形 A：本机同机部署（中央与边缘在同一台机器）
```bash
cd edge-agent
bash run-edge-local.sh
```
脚本会自动将中央地址设为 `host.docker.internal:8428` 并执行部署。边缘 Prometheus UI：http://localhost:9092。
### 情形 B：边缘在另一台机器
1. 进入目录并配置中央地址：
```bash
cd edge-agent
cp env.example .env
```
编辑 `.env`：
- `CENTRAL_SERVER_HOST=` 中央服务器 IP 或域名
- `CENTRAL_SERVER_PORT=8428`
2. 配置监控目标并生成配置：
```bash
# 编辑 config/targets.csv（Ping / ONVIF），详见 TARGETS_CSV_GUIDE.md
cd config && chmod +x *.sh && ./update-configs.sh && cd ..
```
3. 部署：
```bash
bash deploy.sh
```
4. 验证：
- 边缘 Prometheus: http://localhost:9092（或边缘机器 IP:9092）
- 在中央 Grafana 中**选择数据源「VictoriaMetrics」**，查询如 `up{job="network-ping"}` 或 `up{region="workernode_1"}` 应能看到边缘数据
### 边缘节点检查清单
- [ ] 中央服务器已部署且 VictoriaMetrics 可访问（端口 8428）
- [ ] `.env` 中 `CENTRAL_SERVER_HOST`、`CENTRAL_SERVER_PORT` 正确
- [ ] `config/targets.csv` 已配置（或已生成 `onvif-targets.json`、`ping-targets.json`）
- [ ] 已执行 `config/update-configs.sh`
- [ ] 边缘能访问中央 8428 端口
- [ ] 部署后在 Grafana 的 VictoriaMetrics 数据源中能看到边缘指标
**常见问题**：
- 看不到边缘数据：确认 `.env` 中为中央 IP（非 host.docker.internal，除非本机同机）；从边缘 `curl -s -o /dev/null -w "%{http_code}" http://<中央IP>:8428/health` 应为 200。
- 端口冲突：边缘 Prometheus 已映射 9092，避免与中央 9091 冲突。
---
## 第三步（可选）：多用户与告警
- **Grafana 多用户**：在中央服务器上执行 `cd central-server/grafana && bash setup-users.sh`，然后按 [USER_MANAGEMENT.md](USER_MANAGEMENT.md) 配置组织、用户与数据源。
- **告警规则**：中央已内置 `alert_rules.yml`；如需调整见 [ALERT_RULES_EXPLANATION.md](ALERT_RULES_EXPLANATION.md)。
- **告警通知**：编辑 `central-server/alertmanager/alertmanager.yml` 配置接收端，见 [ALERTMANAGER_CONFIG.md](ALERTMANAGER_CONFIG.md)。
- **Grafana 多用户**：`cd central-server/grafana && bash setup-users.sh`，详见 [USER_MANAGEMENT.md](USER_MANAGEMENT.md)。
- **告警**：规则见 [ALERTING.md](ALERTING.md)；通知渠道编辑 `central-server/alertmanager/alertmanager.yml`。
---
## 部署后验证
## 第四步（可选）：拓扑标注助手
### 中央
与中央同机运行，访问 http://localhost:4080。上传本机 `targets.csv` → 选择设备、GPS 或地图点击补坐标 → 保存 → 下载 CSV → 将下载文件部署到各边缘 `edge-agent/config/targets.csv`，在边缘执行：
- `docker compose ps` 中 prometheus-central、grafana、victoria-metrics、alertmanager 为 Up
- 能打开 Grafana、Prometheus、Alertmanager、VictoriaMetrics 的 Web 界面
- Grafana 中「Prometheus」数据源可查询到中央自身指标（如 `up`）
### 边缘
- `docker compose ps` 中 prometheus-edge、onvif-exporter、blackbox-exporter 为 Up
- 边缘 Prometheus http://localhost:9092/targets 中目标状态正常
- 中央 Grafana 中**选择数据源「VictoriaMetrics」**，能查到边缘相关指标（如 `up{job="network-ping"}`）
```bash
cd edge-agent/config && ./update-configs.sh && ./csv-to-topology-geojson.sh targets.csv topology.geojson
```
---
## 常见部署问题
## 部署后检查清单
### 端口冲突
- **中央**：`docker compose ps` 中相关服务 Up；Grafana 中 Prometheus 数据源可查 `up`。
- **边缘**：prometheus-edge、blackbox-exporter Up；Grafana 选 VictoriaMetrics 可查 `probe_success{job="network-ping"}` 等。
- **磁盘/端口**：端口冲突用 `ss -tulpn` 排查；空间不足时清理或扩容数据目录。
- 现象：容器启动失败，提示端口已被占用。
- 处理：`netstat -tulpn | grep <端口>` 或 `ss -tulpn` 查看占用；修改对应 `docker-compose.yml` 端口映射或关闭占用进程。
### 磁盘空间不足
- 现象：拉镜像或启动失败。
- 处理：`df -h` 检查空间；`docker system prune -a --volumes` 清理（注意会删未用卷）；保证数据目录所在分区空间充足。
### 边缘无法连接中央
- 现象：边缘数据未出现在中央 Grafana 的 VictoriaMetrics 中。
- 处理：从边缘节点 `telnet <中央IP> 8428` 或 `curl -s -o /dev/null -w "%{http_code}" http://<中央IP>:8428/health`；检查防火墙与 `.env` 中 `CENTRAL_SERVER_HOST`、`CENTRAL_SERVER_PORT`。
### Grafana 中看不到边缘数据
- 确认在 Grafana 里选择的是**数据源「VictoriaMetrics」**，不是「Prometheus」（中央自抓数据在 Prometheus）。
- 确认边缘已部署且 remote_write 指向中央 8428；边缘 Prometheus 日志无推送错误。
---
## 相关文档
- 部署顺序总览：[README.md#部署顺序](README.md)
- 中央配置：[CENTRAL_SERVER_CONFIG.md](CENTRAL_SERVER_CONFIG.md)、[central-server/CONFIGURATION.md](../central-server/CONFIGURATION.md)
- 边缘配置与目标：[EDGE_NODE_SETUP.md](EDGE_NODE_SETUP.md)、[EDGE_AGENT_CONFIG.md](EDGE_AGENT_CONFIG.md)、[TARGETS_CSV_GUIDE.md](TARGETS_CSV_GUIDE.md)
- 架构：[ARCHITECTURE.md](ARCHITECTURE.md)
- 故障排查：[TROUBLESHOOTING.md](TROUBLESHOOTING.md)
详见 [TROUBLESHOOTING.md](TROUBLESHOOTING.md)、[README.md](README.md)。

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)

183
doc/EDGE_NODE_SETUP.md
View File

@@ -1,183 +0,0 @@
# 边缘节点配置指南
## 在本机模拟边缘节点
### 前置条件
1. ✅ Docker 和 Docker Compose 已安装
2. ✅ 中央服务器已部署并运行
3. ✅ 网络连通性正常
### 配置步骤
#### 1. 配置中央服务器地址
编辑 `.env` 文件（如果不存在，从 `env.example` 复制）：
```bash
cd edge-agent
cp env.example .env
nano .env
```
**重要配置**：
```bash
# 如果中央服务器在本机，使用本机IP或localhost
CENTRAL_SERVER_HOST=192.168.2.21 # 或使用 localhost
CENTRAL_SERVER_PORT=8428
# 边缘节点标识（每个节点唯一）
EDGE_NODE_ID=workernode_1
```
#### 2. 配置监控目标（统一配置）
**推荐使用统一的 `targets.csv` 配置文件**，可以在一个文件中同时配置 ONVIF 设备和网络 Ping 目标。
编辑 `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,,,,,,
ping,1.1.1.1,cloudflare_dns,external,external,,,,,,
# ONVIF 设备示例（取消注释并填写实际信息）
# onvif,192.168.1.100,,,front_door,camera,HIKVISION_DS-2CD2342WD-I,front_door,admin,password1,80
```
**说明**：
- `type` 字段：`ping` 表示网络探测，`onvif` 表示 ONVIF 设备
- 如果没有 ONVIF 设备，可以只配置 `ping` 类型的目标
- 详细配置说明请参考：`doc/TARGETS_CSV_GUIDE.md`
**旧格式兼容**：
如果使用旧的 `devices.csv` 和 `ping-targets.csv` 格式，脚本会自动识别并转换。
#### 3. 生成配置文件
```bash
cd config
chmod +x *.sh
./update-configs.sh
cd ..
```
这会生成：
- `config/onvif-targets.json` - ONVIF 设备配置
- `config/ping-targets.json` - 网络探测配置
#### 4. 修改端口映射（避免冲突）
**重要**：本机已有中央服务器运行，需要修改端口避免冲突。
编辑 `docker-compose.yml`，修改 Prometheus Edge 的端口：
**解决**：修改 `docker-compose.yml` 中的端口映射为 9092
#### 2. 无法连接到中央服务器
**问题**：`CENTRAL_SERVER_HOST` 配置错误
**解决**：
- 如果中央服务器在本机：使用 `localhost` 或本机 IP `192.168.2.21`
- 如果中央服务器在其他机器：使用正确的 IP 地址
- 确保防火墙开放 8428 端口
#### 3. ONVIF Exporter 报错
**问题**：没有真实的 ONVIF 设备或设备不可访问
**解决**：
- 暂时可以忽略（不影响网络探测功能）
- 或配置正确的设备信息
#### 4. 数据未推送到中央服务器
**检查**：
1. 查看边缘节点日志：`docker compose logs prometheus-edge`
2. 检查网络连通性：`curl http://192.168.2.21:8428/api/v1/write`
3. 检查中央服务器 VictoriaMetrics 是否运行：`docker ps | grep victoria`
### 测试配置
#### 最小化测试配置
如果只想测试数据推送功能，可以使用最小配置：
1. **清空 ONVIF 设备**（`config/devices.csv` 留空）
2. **只配置网络探测**（`config/ping-targets.csv` 添加几个公共 DNS）
3. **部署并验证数据推送**
### 下一步
1. ✅ 边缘节点部署完成
2. ✅ 数据成功推送到中央服务器
3. 📊 在 Grafana 中创建仪表板查看数据
4. 🔔 配置告警规则（告警规则会自动激活）
```yaml
ports:
- "9092:9090" # 改为 9092，避免与中央服务器冲突
```
#### 5. 修改 Prometheus Edge 配置
编辑 `prometheus-edge/prometheus.yml`：
```yaml
global:
scrape_interval: 120s
evaluation_interval: 120s
external_labels:
region: workernode_1 # 边缘节点标识
user_group: "user-group-a" # 可选：添加用户组标签
```
#### 6. 部署边缘节点
```bash
bash deploy.sh
```
### 验证配置
#### 1. 检查服务状态
```bash
docker compose ps
```
应该看到：
- `prometheus-edge` - 运行中
- `onvif-exporter` - 运行中（如果没有设备可能报错，但不影响）
- `blackbox-exporter` - 运行中
#### 2. 检查数据推送
访问边缘节点 Prometheus：
```bash
http://localhost:9092
```
查询指标：
```promql
up{job="network-ping"}
```
#### 3. 检查中央服务器接收数据
访问中央服务器 Grafana：
```bash
http://localhost:3000
```
在 Prometheus 数据源中查询：
```promql
up{region="workernode_1"}
```
如果能看到数据，说明边缘节点已成功推送数据到中央服务器！
### 常见问题
#### 1. 端口冲突
**问题**：边缘节点 Prometheus 端口 9090 与中央服务器冲突

246
doc/MONITORING_TARGETS.md
View File

@@ -1,246 +0,0 @@
# 边缘节点监控目标说明
## 监控目标类型
边缘节点主要监控三类目标：
### 1. ONVIF 设备 (通过 ONVIF Exporter)
**监控对象**：
- 📹 **摄像头 (Camera)** - IP 摄像头
- 📼 **NVR (Network Video Recorder)** - 网络视频录像机
- 其他支持 ONVIF 协议的设备
**监控指标**：
- `up{job="onvif-devices"}` - 设备在线状态
- `onvif_device_temperature` - 设备温度
- `onvif_storage_usage_percent` - 存储使用率
- 其他 ONVIF 设备指标
**配置位置**：
- CSV 配置：`config/devices.csv`
- JSON 配置：`config/onvif-targets.json`
**配置示例**：
```csv
ip,device_type,model,location,username,password,onvif_port
192.168.1.100,camera,HIKVISION_DS-2CD2342WD-I,front_door,admin,password1,80
192.168.1.50,nvr,HIKVISION_DS-7608NI-I2,server_rack,admin,password4,80
```
**告警规则**：
- `ONVIFDeviceDown` - 设备离线告警
- `ONVIFDeviceHighTemperature` - 温度过高告警
- `ONVIFDeviceLowStorage` - 存储空间不足告警
---
### 2. 网络设备 (通过 Blackbox Exporter)
**监控对象**：
- 🌐 **路由器** - 网络网关设备
- 🔌 **交换机** - 网络交换设备
- 💻 **服务器** - 各种服务器设备
- 🌍 **外部服务** - DNS、网站等外部服务
- 📡 **网络设备** - 任何可通过 ICMP ping 的设备
**监控方式**：
- **ICMP Ping** - 网络连通性探测
- **TCP 连接** - TCP 端口连通性
- **HTTP 探测** - HTTP 服务可用性
**监控指标**：
- `probe_success{job="network-ping"}` - Ping 成功状态 (0/1)
- `probe_duration_seconds{job="network-ping"}` - Ping 延迟时间
- `probe_http_status_code` - HTTP 状态码
- `probe_tcp_connect_success` - TCP 连接成功状态
**配置位置**：
- CSV 配置：`config/ping-targets.csv`
- JSON 配置：`config/ping-targets.json`
**配置示例**：
```csv
ip,device,group,network
192.168.1.1,main_router,network,internal
8.8.8.8,google_dns,external,external
1.1.1.1,cloudflare_dns,external,external
```
**告警规则**：
- `NetworkDeviceDown` - 网络设备离线告警
- `HighNetworkLatency` - 网络延迟过高告警
---
### 3. 边缘节点自身 (Prometheus Edge)
**监控对象**：
- 边缘 Prometheus 服务自身
**监控指标**：
- `up{job="prometheus-edge"}` - Prometheus 服务状态
- `prometheus_tsdb_*` - 时序数据库指标
- `prometheus_config_*` - 配置相关指标
**配置位置**：
- `prometheus-edge/prometheus.yml` (自动配置)
---
## 监控目标汇总表
| 监控类型 | Job名称 | Exporter | 配置文件 | 监控间隔 | 告警规则 |
|---------|---------|----------|----------|----------|----------|
| ONVIF设备 | `onvif-devices` | ONVIF Exporter | `config/onvif-targets.json` | 120秒 | ONVIFDeviceDown<br>ONVIFDeviceHighTemperature<br>ONVIFDeviceLowStorage |
| 网络设备 | `network-ping` | Blackbox Exporter | `config/ping-targets.json` | 300秒 | NetworkDeviceDown<br>HighNetworkLatency |
| 边缘节点自身 | `prometheus-edge` | Prometheus自身 | 自动配置 | 60秒 | - |
---
## 典型监控场景
### 场景 1：家庭/办公室监控
**ONVIF 设备**：
- 前门摄像头
- 后院摄像头
- 客厅摄像头
- NVR 录像机
**网络设备**：
- 主路由器 (192.168.1.1)
- 交换机
- 内部服务器
### 场景 2：企业监控
**ONVIF 设备**：
- 多个区域的摄像头
- 多个 NVR 设备
- 不同品牌的摄像头
**网络设备**：
- 核心路由器
- 汇聚交换机
- 接入交换机
- 关键服务器
- 外部 DNS 服务
### 场景 3：最小化测试
**ONVIF 设备**：
- 无（留空用于测试）
**网络设备**：
- 公共 DNS (8.8.8.8, 1.1.1.1)
- 本地路由器（如果可访问）
---
## 配置建议
### ONVIF 设备配置
1. **设备信息**：
- IP 地址
- 设备类型 (camera/nvr)
- 型号
- 位置标签
- 用户名和密码
- ONVIF 端口（通常 80 或 8080）
2. **安全建议**：
- 使用强密码
- 定期更换密码
- 限制网络访问
### 网络设备配置
1. **内部设备**：
- 路由器、交换机等关键网络设备
- 重要服务器
- 网络打印机等
2. **外部服务**：
- 公共 DNS (8.8.8.8, 1.1.1.1)
- 关键外部服务
- 用于测试网络连通性
3. **标签使用**：
- `group` - 设备分组
- `network` - 网络类型 (internal/external)
- `device` - 设备名称
---
## 数据流向
```
监控目标
│
├─ ONVIF 设备 ──> ONVIF Exporter ──┐
│ │
├─ 网络设备 ──> Blackbox Exporter ──┤
│ │
└─ 边缘节点自身 ──────────────────────┤
│
▼
Prometheus Edge
│
│ remote_write
▼
VictoriaMetrics (中央服务器)
```
---
## 验证监控目标
### 1. 检查 ONVIF 设备
在边缘节点 Prometheus 查询：
```promql
up{job="onvif-devices"}
```
### 2. 检查网络设备
在边缘节点 Prometheus 查询：
```promql
probe_success{job="network-ping"}
```
### 3. 检查数据推送
在中央服务器 Grafana 查询：
```promql
up{region="workernode_1"}
probe_success{region="workernode_1"}
```
---
## 常见问题
### Q: 没有 ONVIF 设备怎么办？
A: 可以留空 ONVIF 设备配置，只使用网络探测功能进行测试。
### Q: 如何添加新的监控目标？
A:
1. 编辑对应的 CSV 文件 (`devices.csv` 或 `ping-targets.csv`)
2. 运行 `cd config && ./update-configs.sh`
3. 等待 5 分钟自动重载，或重启 `prometheus-edge` 容器
### Q: 监控目标太多会影响性能吗？
A:
- ONVIF 设备：每个设备约 1-2 秒查询时间
- 网络 Ping：每个目标约 0.1-0.5 秒
- 建议：单节点不超过 100 个目标
### Q: 如何监控 HTTPS 服务？
A: 修改 `blackbox/config.yml`，添加 HTTPS 探测模块，然后在 `ping-targets.json` 中配置。

2
doc/ONVIF_ALTERNATIVES.md
View File

@@ -78,4 +78,4 @@
- **若需要 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`。
具体边缘配置与 compose 变更见 **[EDGE_AGENT_CONFIG.md](EDGE_AGENT_CONFIG.md)** 及 `edge-agent/docker-compose.yml`。

140
doc/PROJECT_DEFECTS.md
View File

@@ -1,140 +0,0 @@
# 项目缺陷分析
基于 README、central-server 及相关文档的审查结果。
---
## 一、严重缺陷
### 1. Grafana 无法展示边缘节点数据（数据源缺失）【已修复】
**现象**：边缘节点通过 remote_write 将指标推送到 **VictoriaMetrics**，此前 Grafana 仅配置了 **Prometheus** 数据源。
**数据流与配置顺序**：
- **边缘主动上报**：边缘节点上的 Prometheus/Agent 配置了 `remote_write` 指向中央服务器的 VictoriaMetrics（`http://中央IP:8428/api/v1/write`），会主动推送指标到中央。
- **必须先配置边缘**：只有在边缘节点里配置好“中央服务器地址 + 8428 端口”并启动后，数据才会出现在 VictoriaMetrics 中；中央仅提供接收端，不会去拉边缘。
- **Grafana 看到边缘数据**：中央已增加 **VictoriaMetrics** 数据源（`grafana/provisioning/datasources/victoriametrics.yml`）后，在 Grafana 中选用 “VictoriaMetrics” 数据源即可查询这些上报上来的边缘数据；无需再配“边缘数据”本身，只需边缘按文档配置上报。
**已做修改**：
- 在 `grafana/provisioning/datasources/` 中新增 **victoriametrics.yml**，数据源 URL 为 `http://victoria-metrics:8428`。
- 边缘数据可见的前提：边缘已配置并运行，且 remote_write 指向本中央 VM（参见 `doc/EDGE_NODE_SETUP.md`、`doc/EDGE_AGENT_CONFIG.md`）。
---
### 2. docker-compose 网络名未设置默认值导致部署失败
**现象**：`docker-compose.yml` 中默认网络名为 `${NETWORK_NAME}`，未提供默认值。
```yaml
networks:
default:
name: ${NETWORK_NAME}
```
**依据**：`deploy.sh` 只 export 了部分变量，**未 export `NETWORK_NAME`**。若用户“使用默认配置”且没有 `.env`（脚本提示“未找到 .env 和 env.example”时），`NETWORK_NAME` 为空，Compose 会使用空字符串作为网络名，可能导致创建失败或行为异常。
**建议**：
- 在 `deploy.sh` 中为 `NETWORK_NAME` 设置默认值并 export，例如：
`NETWORK_NAME=${NETWORK_NAME:-central_default}` 或与 Traefik 一致时 `NETWORK_NAME=${NETWORK_NAME:-traefik}`
- 或在 `docker-compose.yml` 中写为：`name: ${NETWORK_NAME:-central_default}`
---
### 3. VictoriaMetrics 容器内监听端口与映射不一致
**现象**：容器内通过环境变量改变监听端口，与端口映射不一致。
**依据**（`docker-compose.yml`）：
```yaml
ports:
- "${VICTORIAMETRICS_PORT:-8428}:8428"
command:
- "--httpListenAddr=:${VICTORIAMETRICS_PORT:-8428}"
```
- 端口映射为「主机 `${VICTORIAMETRICS_PORT}` → 容器 **8428**」
- 若用户设置 `VICTORIAMETRICS_PORT=8430`，容器会监听 **8430**，而映射期望容器监听 **8428**，导致主机 8430 无法正确访问服务。
**建议**：容器内应固定监听 8428，仅用环境变量控制主机端口。例如：
```yaml
command:
- "--httpListenAddr=:8428"
```
---
## 二、中等问题
### 4. Alertmanager Webhook 在容器内不可达
**现象**：`alertmanager/alertmanager.yml` 中 webhook 为 `http://127.0.0.1:5001/`。
在容器内 `127.0.0.1` 指向 Alertmanager 自身，无法访问宿主机上的 webhook 服务，告警无法送达。
**建议**：
- Linux 下可使用 `http://host.docker.internal:5001/`（若 Docker 支持）
- 或使用宿主机在 Docker 网桥上的 IP，并在文档中说明需替换为实际地址
---
### 5. 默认启用 Traefik 且为示例域名，不利于“快速开始”
**现象**：`env.example` 中 `TRAEFIK_ENABLED=true`，且域名为 `grafana.example.com` 等。README 的“快速开始”是 `http://localhost:3000`。
**结果**：新用户若直接 `cp env.example .env` 并部署，会默认走 Traefik + 示例域名，本地浏览器无法用 localhost 访问，与文档体验不一致。
**建议**：
- `env.example` 中默认设为 `TRAEFIK_ENABLED=false`，便于本地快速开始
- 或在 README/CONFIGURATION 中明确写：本地试用请将 `TRAEFIK_ENABLED=false`，并说明 Traefik 为可选
---
### 6. 部署脚本未导出 NETWORK_NAME
**现象**：`deploy.sh` 中通过 `set -a; source .env` 可导出 .env 中的变量，但若没有 .env，或 .env 中未写 `NETWORK_NAME`，则 Compose 收到的 `NETWORK_NAME` 可能为空。
**建议**：在 deploy.sh 的“设置默认值”或 export 段落中显式设置并 export：
```bash
NETWORK_NAME=${NETWORK_NAME:-traefik}
export NETWORK_NAME
```
与第 2 点一起修复，可避免无 .env 或漏配时的部署问题。
---
## 三、文档/一致性问题
### 7. 架构文档与实现不一致
**现象**：`doc/ARCHITECTURE.md` 描述“Prometheus 从 VictoriaMetrics 读取数据”，但当前 `prometheus.yml` 仅有 **remote_write** 到 VictoriaMetrics，没有 **remote_read**。
**建议**：修改文档为“Prometheus 将本地抓取数据 remote_write 到 VictoriaMetrics；边缘数据仅存在于 VictoriaMetrics”，并说明 Grafana 如需查边缘数据应使用 VictoriaMetrics 数据源（与第 1 点修复一致）。
---
### 8. 示例密码与安全建议不一致
**现象**：README 和配置中默认管理员密码为 `admin123`，CONFIGURATION.md 建议“首次部署后请立即修改”“生产环境必须修改”。
**建议**：在 README 快速开始处增加一句：“默认密码仅用于首次登录，生产环境请立即修改”，并在部署成功输出中再次提醒。
---
## 四、小结
| 优先级 | 缺陷 | 建议 |
|--------|------|------|
| ~~高~~ | ~~Grafana 缺少 VictoriaMetrics 数据源~~ | ✅ 已增加 `victoriametrics.yml`；边缘需先配置 remote_write 指向中央 VM |
| 高 | Compose 网络名无默认值 | 为 NETWORK_NAME 设默认并 export |
| 高 | VictoriaMetrics 容器监听端口与端口映射不一致 | 容器内固定监听 8428 |
| 中 | Alertmanager webhook 127.0.0.1 在容器内无效 | 改为 host.docker.internal 或宿主机 IP并文档说明 |
| 中 | 默认启用 Traefik + 示例域名 | 默认关闭 Traefik 或文档明确本地试用步骤 |
| 中 | deploy 未导出 NETWORK_NAME | 在 deploy.sh 中设置并 export |
| 低 | 架构文档与实现不符 | 更新 ARCHITECTURE.md |
| 低 | 默认密码与安全建议 | 在 README 和部署输出中强调修改密码 |
以上为当前发现的主要缺陷与改进建议，优先修复前三条可显著提升部署成功率和“边缘+中央”统一监控的可用性。

61
doc/README.md
View File

@@ -6,13 +6,14 @@
## 部署顺序（必读）
整体顺序：**先中央，后边缘**。边缘向中央主动上报数据，中央必须先就绪。
整体顺序：**先中央，后边缘，再按需标注拓扑**。边缘向中央主动上报数据，中央必须先就绪。
| 步骤 | 部署什么 | 做什么 | 验证 |
|------|----------|--------|------|
| 步骤 | 部署 / 操作对象 | 做什么 | 验证 |
|------|------------------|--------|------|
| **第一步** | 中央服务器 | 部署 Prometheus、Grafana、VictoriaMetrics、Alertmanager | Grafana http://localhost:3000、Prometheus http://localhost:9091 |
| **第二步** | 边缘节点（可选，可多台） | 配置中央地址与监控目标，部署边缘 Prometheus + Exporter | 边缘 UI http://localhost:9092，Grafana 选 VictoriaMetrics 数据源可见边缘数据 |
| **第三步** | 多用户 / 告警（可选） | 配置 Grafana 组织与用户、Alertmanager 通知 | 按 [USER_MANAGEMENT.md](USER_MANAGEMENT.md)、[ALERTMANAGER_CONFIG.md](ALERTMANAGER_CONFIG.md) 验证 |
| **第三步** | 多用户 / 告警（可选） | 配置 Grafana 组织与用户、Alertmanager 通知 | 按 [USER_MANAGEMENT.md](USER_MANAGEMENT.md)、[ALERTING.md](ALERTING.md) 验证 |
| **第四步** | 拓扑标注助手 topology-editor（可选） | 上传/编辑/下载 `targets.csv`，用 GPS 与天地图给设备打点并维护拓扑关系 | 在 Grafana Geomap 中按经纬度与 parent/uplink_type 展示网络拓扑 |
---
@@ -55,15 +56,42 @@ bash deploy.sh
- **验证**：边缘 Prometheus UI http://localhost:9092（端口 9092 避免与中央 9091 冲突）。在中央 Grafana 中**选择数据源「VictoriaMetrics」**，查询如 `up{job="network-ping"}` 可见边缘数据；中央自身指标在数据源「Prometheus」。
- **摄像头/ONVIF**：默认不拉取 ONVIF 镜像（公共镜像不存在）。监控摄像头可选：**SNMP Exporter**、**Frigate**、**Blackbox 探测** 或自建 ONVIF 镜像，见 **[ONVIF_ALTERNATIVES.md](ONVIF_ALTERNATIVES.md)**。
- **监控目标**：编辑 `edge-agent/config/targets.csv`（Ping / ONVIF），详见 [TARGETS_CSV_GUIDE.md](TARGETS_CSV_GUIDE.md)。
- **详细**：[EDGE_NODE_SETUP.md](EDGE_NODE_SETUP.md)、[EDGE_AGENT_CONFIG.md](EDGE_AGENT_CONFIG.md)、[DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md)。
- **监控目标**：编辑 `edge-agent/config/targets.csv`（Ping / ONVIF / 拓扑），详见 [TARGETS_AND_MONITORING.md](TARGETS_AND_MONITORING.md)。
- **详细**：[EDGE_AGENT_CONFIG.md](EDGE_AGENT_CONFIG.md)、[DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md)。
---
### 第三步（可选）：多用户与告警
- **Grafana 多用户**：`cd central-server/grafana && bash setup-users.sh`，然后按 [USER_MANAGEMENT.md](USER_MANAGEMENT.md) 配置组织与数据源。
- **告警通知**：编辑 `central-server/alertmanager/alertmanager.yml` 配置接收端；告警规则见 [ALERT_RULES_EXPLANATION.md](ALERT_RULES_EXPLANATION.md)、[ALERTMANAGER_CONFIG.md](ALERTMANAGER_CONFIG.md)。
- **告警通知**：编辑 `central-server/alertmanager/alertmanager.yml` 配置接收端；告警规则与说明见 [ALERTING.md](ALERTING.md)。
---
### 第四步（可选）：拓扑标注助手 / targets.csv 标注
拓扑标注助手是一个与 central 同机运行的小型 Web 服务（在 `topology-editor/` 目录下），用来：
- 上传 / 下载 `targets.csv`；
- 在手机或浏览器中选择设备、**获取 GPS 定位**；浏览器要求页面为**安全来源**（HTTPS 或 http://localhost / 127.0.0.1），否则会报「only secure origins are allowed」无法定位，需通过 HTTPS 访问或在本机用 localhost 打开。
- 叠加天地图底图，点击地图修正坐标；天地图需填写 **TK**（[申请密钥](https://console.tianditu.gov.cn/)），底图与标识图说明见 [TIANDITU_CONFIG.md](TIANDITU_CONFIG.md)。可选：在 central 配置 **TIANDITU_TK** 启用瓦片缓存，节省 key 免费量，缓存按 TTL 自动老化。
- 维护 `name` / `role` / `parent` / `uplink_type` 等拓扑字段。
典型用法：
1. **上传 CSV**：在本机更新 `targets.csv` 后，访问 `http://<central>:4080`，在顶部区域上传。
2. **选择设备补点**：在下拉框中选择已有设备，用「获取 GPS」或点地图修正经纬度，必要时调整 `parent` / `uplink_type`。
3. **保存标注**：点击「保存到 targets.csv」仅更新标注助手中的当前副本。
4. **下载 CSV**：点击「下载 targets.csv」得到新的 CSV，将其下发到各边缘节点的 `edge-agent/config/targets.csv`。
5. **在边缘生成配置与拓扑**：在边缘执行：
```bash
cd edge-agent/config
./update-configs.sh
./csv-to-topology-geojson.sh targets.csv topology.geojson
```
之后 Grafana Geomap 可以同时展示：设备点位（lat/lon）、上下级连线（parent）、链路类型（uplink_type）。
---
@@ -82,8 +110,8 @@ bash deploy.sh
| [CENTRAL_SERVER_CONFIG.md](CENTRAL_SERVER_CONFIG.md) | 中央服务器配置文件说明 |
| [../central-server/CONFIGURATION.md](../central-server/CONFIGURATION.md) | 中央服务器环境变量（.env）说明 |
| [EDGE_AGENT_CONFIG.md](EDGE_AGENT_CONFIG.md) | 边缘节点配置文件说明 |
| [TARGETS_CSV_GUIDE.md](TARGETS_CSV_GUIDE.md) | 边缘监控目标 targets.csv 格式与示例 |
| [MONITORING_TARGETS.md](MONITORING_TARGETS.md) | ONVIF / 网络探测等监控目标说明 |
| [TARGETS_AND_MONITORING.md](TARGETS_AND_MONITORING.md) | 监控目标与 targets.csv（格式、脚本、数据流） |
| [TIANDITU_CONFIG.md](TIANDITU_CONFIG.md) | 天地图配置（底图 vec_w、标识图 cva_w、WMTS 地址） |
| [ONVIF_ALTERNATIVES.md](ONVIF_ALTERNATIVES.md) | **摄像头/ONVIF 监控替代方案**（SNMP、Frigate、Blackbox、自建） |
### 用户与告警
@@ -91,30 +119,23 @@ bash deploy.sh
| 文档 | 说明 |
|------|------|
| [USER_MANAGEMENT.md](USER_MANAGEMENT.md) | Grafana 多用户、组织与数据隔离 |
| [ALERT_RULES_EXPLANATION.md](ALERT_RULES_EXPLANATION.md) | 告警规则说明 |
| [ALERTMANAGER_CONFIG.md](ALERTMANAGER_CONFIG.md) | Alertmanager 配置与通知渠道 |
| [ALERTING.md](ALERTING.md) | 告警规则、Alertmanager 配置与通知渠道 |
### 部署与运维
| 文档 | 说明 |
|------|------|
| [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) | 完整部署步骤、检查清单、验证与常见问题 |
| [EDGE_NODE_SETUP.md](EDGE_NODE_SETUP.md) | 边缘节点配置与验证（含本机同机） |
| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | 故障排查 |
| [BEST_PRACTICES.md](BEST_PRACTICES.md) | 最佳实践与生产环境建议 |
### 参考
| 文档 | 说明 |
|------|------|
| [PROJECT_DEFECTS.md](PROJECT_DEFECTS.md) | 项目缺陷与修复建议 |
---
## 快速导航
- **第一次部署**：按上面「部署顺序」先做第一步，再做第二步。
- **只改中央配置**：看 [CENTRAL_SERVER_CONFIG.md](CENTRAL_SERVER_CONFIG.md)、[CONFIGURATION.md](../central-server/CONFIGURATION.md)。
- **只改边缘 / 监控目标**：看 [EDGE_NODE_SETUP.md](EDGE_NODE_SETUP.md)、[TARGETS_CSV_GUIDE.md](TARGETS_CSV_GUIDE.md)。
- **多用户 / 告警**：看 [USER_MANAGEMENT.md](USER_MANAGEMENT.md)、[ALERTMANAGER_CONFIG.md](ALERTMANAGER_CONFIG.md)。
- **只改边缘 / 监控目标**：看 [EDGE_AGENT_CONFIG.md](EDGE_AGENT_CONFIG.md)、[TARGETS_AND_MONITORING.md](TARGETS_AND_MONITORING.md)。
- **拓扑标注助手**：第四步；上传/编辑/下载 targets.csv；天地图底图与标识图见 [TIANDITU_CONFIG.md](TIANDITU_CONFIG.md)。
- **多用户 / 告警**：看 [USER_MANAGEMENT.md](USER_MANAGEMENT.md)、[ALERTING.md](ALERTING.md)。
- **出问题**：看 [TROUBLESHOOTING.md](TROUBLESHOOTING.md)、[DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md)。

75
doc/TARGETS_AND_MONITORING.md Normal file
View File

@@ -0,0 +1,75 @@
# 监控目标与 targets.csv
边缘监控目标统一由 `edge-agent/config/targets.csv` 配置，经 `update-configs.sh` 生成 `onvif-targets.json`、`ping-targets.json`，并可生成拓扑 GeoJSON 供 Grafana Geomap 使用。
---
## targets.csv 格式
表头（列顺序固定）：
```text
type,ip,name,role,parent,uplink_type,network,device_type,model,location,username,password,onvif_port,lat,lon
```
| 字段 | 说明 | 适用类型 |
|------|------|----------|
| type | `ping` / `onvif` / `topology` | 必填 |
| ip | IP（topology 哑设备可空） | ping, onvif |
| name | 节点唯一名，用于拓扑 parent 引用 | 必填 |
| role | 如 core_switch, access_switch, camera, wireless_bridge, media_converter | 可选 |
| parent | 上联设备 name，用于画拓扑连线 | 可选 |
| uplink_type | 与上联链路类型：fiber / copper / wireless | 可选 |
| network | 如 internal / external | 可选 |
| device_type, model, location | 设备描述；onvif 必填 location、账号等 | onvif |
| username, password, onvif_port | ONVIF 认证与端口（默认 80） | onvif |
| lat, lon | 经纬度（十进制度），Geomap 打点与拓扑 | 可选 |
- **ping**：有 IP，由 Blackbox Exporter 探测，生成 `ping-targets.json`。
- **onvif**：有 IP，由 ONVIF Exporter 探测，生成 `onvif-targets.json`；需填 device_type, model, location, username, password。
- **topology**：仅拓扑节点（可无 IP），不参与抓取；用于生成 `topology.geojson` 画点与连线。
---
## 示例
```csv
type,ip,name,role,parent,uplink_type,network,device_type,model,location,username,password,onvif_port,lat,lon
ping,192.168.2.1,core_sw_1,core_switch,,,internal,,,,,,,22.54,113.98
ping,8.8.8.8,google_dns,dns,core_sw_1,fiber,external,,,,,,,22.55,113.99
topology,,dumb_sw_1,access_switch,core_sw_1,copper,internal,switch,,building_A,,,,22.543,113.988
onvif,192.168.1.100,camera_front,camera,dumb_sw_1,copper,internal,camera,HIKVISION,front_door,admin,pass,80,22.123,113.567
```
---
## 生成配置与拓扑
```bash
cd edge-agent/config
chmod +x *.sh
./update-configs.sh
./csv-to-topology-geojson.sh targets.csv topology.geojson
```
- `update-configs.sh`：根据 targets.csv 生成 `onvif-targets.json`、`ping-targets.json`。
- `csv-to-topology-geojson.sh`：生成 `topology.geojson`，供 Grafana Geomap 加载（设备点 + parent 连线，uplink_type 可区分线型）。
---
## 监控类型与数据流
| 类型 | Job | Exporter | 配置文件 |
|------|-----|----------|----------|
| 网络 Ping | network-ping | Blackbox | ping-targets.json |
| ONVIF | onvif-devices | ONVIF Exporter | onvif-targets.json |
| 边缘自身 | prometheus-edge | Prometheus | 内置 |
数据流：目标 → Exporter → prometheus-edge 抓取 → remote_write → 中央 VictoriaMetrics。Grafana 查边缘数据需选 **VictoriaMetrics** 数据源。
---
## 验证
- 边缘 Prometheus（http://localhost:9092）：`probe_success{job="network-ping"}`、`onvif_device_up`。
- 中央 Grafana（VictoriaMetrics 数据源）：`probe_success{region="workernode_1"}` 等。

131
doc/TARGETS_CSV_GUIDE.md
View File

@@ -1,131 +0,0 @@
# targets.csv 配置指南
## 概述
`targets.csv` 是统一的监控目标配置文件，可以在一个文件中同时配置 ONVIF 设备和网络 Ping 目标。
## 文件格式
```csv
type,ip,device,group,network,device_type,model,location,username,password,onvif_port
```
### 字段说明
| 字段 | 说明 | 必需 | 适用类型 |
|------|------|------|----------|
| `type` | 目标类型：`ping` 或 `onvif` | ✅ | 所有 |
| `ip` | IP 地址 | ✅ | 所有 |
| `device` | 设备名称 | ❌ | ping |
| `group` | 设备分组 | ❌ | ping |
| `network` | 网络类型（internal/external） | ❌ | ping |
| `device_type` | 设备类型（camera/nvr） | ✅ | onvif |
| `model` | 设备型号 | ✅ | onvif |
| `location` | 设备位置 | ✅ | onvif |
| `username` | 用户名 | ✅ | onvif |
| `password` | 密码 | ✅ | onvif |
| `onvif_port` | ONVIF 端口（默认80） | ❌ | onvif |
## 配置示例
### Ping 目标配置
```csv
type,ip,device,group,network,device_type,model,location,username,password,onvif_port
ping,192.168.1.1,main_router,network,internal,,,,,,
ping,8.8.8.8,google_dns,external,external,,,,,,
ping,1.1.1.1,cloudflare_dns,external,external,,,,,,
```
**说明**：
- `type` 设置为 `ping`
- 填写 `ip`, `device`, `group`, `network`
- ONVIF 相关字段留空
### ONVIF 设备配置
```csv
type,ip,device,group,network,device_type,model,location,username,password,onvif_port
onvif,192.168.1.100,,,front_door,camera,HIKVISION_DS-2CD2342WD-I,front_door,admin,password1,80
onvif,192.168.1.101,,,back_yard,camera,DAHUA_IPC-HFW1230S,back_yard,admin,password2,80
onvif,192.168.1.50,,,server_rack,nvr,HIKVISION_DS-7608NI-I2,server_rack,admin,password4,80
```
**说明**：
- `type` 设置为 `onvif`
- 填写 `ip`, `device_type`, `model`, `location`, `username`, `password`
- `onvif_port` 默认为 80，如果不是 80 需要填写
- Ping 相关字段（device, group, network）可以留空
### 混合配置示例
```csv
type,ip,device,group,network,device_type,model,location,username,password,onvif_port
ping,192.168.1.1,main_router,network,internal,,,,,,
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
onvif,192.168.1.101,,,back_yard,camera,DAHUA_IPC-HFW1230S,back_yard,admin,password2,80
```
## 使用注释
可以在 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
```
## 生成配置文件
编辑 `targets.csv` 后，运行：
```bash
cd config
./update-configs.sh
```
这会生成：
- `onvif-targets.json` - ONVIF 设备配置
- `ping-targets.json` - Ping 目标配置
## 向后兼容
如果存在旧的配置文件：
- `devices.csv` - 仍会被识别并转换
- `ping-targets.csv` - 仍会被识别并转换
但建议统一使用 `targets.csv` 进行配置。
## 注意事项
1. **字段顺序**：必须按照 CSV 头部定义的顺序填写
2. **空字段**：不需要的字段可以留空，但逗号不能省略
3. **特殊字符**：如果字段值包含逗号，需要用引号包裹
4. **密码安全**：密码以明文存储，请确保文件权限安全
## 迁移指南
### 从旧格式迁移
**旧格式**（`devices.csv` + `ping-targets.csv`）：
```csv
# devices.csv
ip,device_type,model,location,username,password,onvif_port
192.168.1.100,camera,HIKVISION_DS-2CD2342WD-I,front_door,admin,password1,80
# ping-targets.csv
ip,device,group,network
8.8.8.8,google_dns,external,external
```
**新格式**（`targets.csv`）：
```csv
type,ip,device,group,network,device_type,model,location,username,password,onvif_port
onvif,192.168.1.100,,,front_door,camera,HIKVISION_DS-2CD2342WD-I,front_door,admin,password1,80
ping,8.8.8.8,google_dns,external,external,,,,,,
```
只需将两个文件的内容合并到 `targets.csv`，并添加 `type` 列即可。

129
doc/TIANDITU_CONFIG.md Normal file
View File

@@ -0,0 +1,129 @@
# 天地图配置说明
拓扑标注助手使用**天地图**作为地图校验底图，便于在浏览器中点击修正设备经纬度。天地图提供**底图**与**标识图（中文注记）**两个图层，可单独或叠加使用。
**天地图密钥**：使用瓦片缓存或 Grafana Geomap 时，密钥统一配置在 **central-server/.env** 的 **TIANDITU_TK** 变量中，由 tile-cache 服务读取，不在浏览器或 Grafana 中填写。
---
## 1. 在拓扑标注助手中使用
- 打开拓扑标注助手：`http://<中央服务器>:4080`
- 在「地图校验」区域填写 **天地图 TK**（密钥），点击「加载天地图」即可加载底图并点击地图修正坐标。
- TK 会保存在浏览器本地（localStorage），同一设备填一次即可。
- **申请密钥**：登录 [天地图开放平台](https://console.tianditu.gov.cn/) 注册并创建应用，获取 **tk** 参数。
当前前端通过天地图 JavaScript API 加载地图；若需在其它系统（如 Grafana Geomap）中复用天地图，可使用下方 WMTS 地址。
---
## 2. 两个图层说明
| 图层 | 用途 | 说明 |
|------|------|------|
| **底图 (vec_w)** | 矢量底图 | 道路、建筑、水系等底图，WGS84 经纬度 |
| **标识图 (cva_w)** | 中文注记 | 地名、道路名等文字标注，叠加在底图之上 |
二者叠加后即「带中文注记的天地图」；仅做点位校验时只用底图即可，需要地名时可叠加标识图。
---
## 3. WMTS 地址（底图 + 标识图）
若在 Grafana、其它 GIS 或自研前端中通过 WMTS 接入天地图，可使用以下地址。请将 `tk=您的密钥` 替换为在 [天地图开放平台](https://console.tianditu.gov.cn/) 申请得到的 **tk**。
**底图（矢量）：**
```text
https://t0.tianditu.gov.cn/vec_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=vec&STYLE=default&TILEMATRIXSET=w&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&FORMAT=tiles&tk=您的密钥
```
**标识图（中文注记）：**
```text
https://t0.tianditu.gov.cn/cva_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=cva&STYLE=default&TILEMATRIXSET=w&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&FORMAT=tiles&tk=您的密钥
```
- **瓦片参数**：`{z}` 为层级（zoom），`{y}` 为行号，`{x}` 为列号；由地图引擎在请求时替换。
- **同一密钥**：底图与标识图使用同一个 **tk** 即可。
- **坐标系**：上述为 WGS84（经纬度），与 topology-editor、targets.csv 中 lat/lon 一致。
---
## 4. 瓦片缓存与手动更新（节省 key 免费量）
天地图 key 有免费调用量限制。本项目提供 **tile-cache** 服务：瓦片首次请求时向天地图拉取并落盘，后续同一瓦片在**老化时间**内直接读缓存；超过老化时间的瓦片在下次请求时会自动重新拉取。
### 4.1 启用缓存服务
- **天地图密钥**：在 **central-server/.env** 中配置 **TIANDITU_TK**（必填，否则缓存服务无法回源）。例如：`TIANDITU_TK=您的天地图密钥`。密钥在 [天地图开放平台](https://console.tianditu.gov.cn/) 申请。
- **服务器端 403**：瓦片由 tile-cache 容器向天地图发起请求，出口 IP 为服务器公网 IP。若控制台中为该 key 设置了 **IP 白名单**，必须将服务器公网 IP 加入白名单；若只设置了 **Referer 白名单**，服务器请求无 Referer 易被拒，可暂时关闭 Referer 校验或按平台说明配置后再试。
- **缓存老化时间**（可选）：`TILE_CACHE_TTL_DAYS=7`（默认 7 天）。单个瓦片超过该天数后，下次被请求时会重新向天地图拉取并覆盖缓存。可改为 15 等更大值以延长复用时间。
- **上游超时**（可选）：向天地图请求单瓦片超时时间，默认 15 秒；若日志中频繁出现 `upstream timeout`，可在 `.env` 中设置 `TILE_CACHE_UPSTREAM_TIMEOUT_MS=25000`（单位毫秒）等更大值后重启 tile-cache。
- 与 central 一起启动时，**tile-cache** 容器会自动启动（端口默认 4090），拓扑标注助手通过内部代理使用 `/tiles` 路径，无需在浏览器暴露 key。
### 4.2 拓扑标注助手中使用缓存
- 当 central 已配置 `TILE_CACHE_URL`（默认已指向 tile-cache）时，页面会显示 **「加载天地图（使用服务器缓存）」**：从服务器缓存加载底图 + 标识图，不消耗浏览器端 key。超过 TTL 的瓦片会在下次浏览时自动更新。
### 4.3 主机直连 tile-cache 测试（排查用）
- 从**主机**上 curl 测试 tile-cache 时，若使用 `http://localhost:4090` 出现**无响应、无日志**（请求未进容器），多半是系统把 `localhost` 解析到 IPv6 (`::1`)，而 Docker 只把端口映射到 IPv4。请改用 **`http://127.0.0.1:4090`** 再试，例如：
`curl -s http://127.0.0.1:4090/health`、`curl -s http://127.0.0.1:4090/api/cache/status`。
标注助手通过 topology-editor 代理访问 tile-cache，走内网 `tile-cache:4090`，不受此影响。
### 4.4 Grafana Geomap 使用缓存（可选）
将 Geomap 的 XYZ 底图/标识图 URL 改为：
`http://<central>:4080/tiles/vec/{z}/{x}/{y}` 与 `http://<central>:4080/tiles/cva/{z}/{x}/{y}`（经拓扑助手代理）。天地图密钥已在 **.env** 的 **TIANDITU_TK** 中配置，Grafana 中无需填写。
### 4.5 更新方式
超过 `TILE_CACHE_TTL_DAYS` 天的瓦片，在下次被请求时会自动重新向天地图拉取并写回缓存，无需手动操作。
---
## 5. 在 Grafana Geomap 中配置天地图（直连或走缓存）
Grafana 的 Geomap 支持 **XYZ Tile layer**。可直连天地图 WMTS（URL 中填 tk），或使用瓦片缓存地址（见第 4 节）。
### 5.1 配置底图（vec_w）
1. 新建或编辑一个 **Geomap** 面板。
2. 在右侧 **Layer** / **Base layer** 区域，将底图类型选为 **XYZ Tile layer**（或「自定义」/「Generic XYZ」等，视 Grafana 版本而定）。
3. **URL template** 中填入天地图矢量底图地址（将 `您的密钥` 换成实际 tk）：
```text
https://t0.tianditu.gov.cn/vec_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=vec&STYLE=default&TILEMATRIXSET=w&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&FORMAT=tiles&tk=您的密钥
```
4. **Attribution** 可填：`© 天地图`。
5. 保存面板后即可看到天地图矢量底图。
### 5.2 叠加标识图（cva_w，中文注记）
若需要地名、道路名等中文注记，可在同一 Geomap 上再添加一层 XYZ 瓦片，叠在底图之上：
1. 在 Geomap 面板的 **Map layers** 中点击 **Add layer**。
2. 选择 **XYZ Tile layer**。
3. **URL template** 填入标识图地址（同一 tk）：
```text
https://t0.tianditu.gov.cn/cva_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=cva&STYLE=default&TILEMATRIXSET=w&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&FORMAT=tiles&tk=您的密钥
```
4. 可将该层的 **Opacity** 设为 1（不透明），这样注记清晰可见。
5. 图层顺序：底图在下，标识图在上；若顺序反了，可在面板里拖拽调整。
### 5.3 说明
- Grafana 会在请求瓦片时把 URL 中的 `{z}`、`{x}`、`{y}` 替换为当前层级与行列号，与天地图 WMTS 的 `TILEMATRIX` / `TILEROW` / `TILECOL` 一一对应。
- 底图与标识图使用**同一个 tk** 即可；tk 在 [天地图开放平台](https://console.tianditu.gov.cn/) 申请。
- 若希望所有 Geomap 默认使用天地图，可在 Grafana 的 provisioning 或 `default_baselayer_config` 中配置 type 为 `xyz`、url 为上述 vec_w 地址（详见 [Grafana 文档 - Configure the default base layer](https://grafana.com/docs/grafana/latest/panels-visualizations/visualizations/geomap/#configure-the-default-base-layer-with-provisioning)）。
---
## 6. 参考
- [天地图开放平台](https://www.tianditu.gov.cn/)
- [开发文档 / 服务资源](https://lbs.tianditu.gov.cn/server/MapService.html)