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

refactor: config/apps 目录重组、文档重构、架构图收窄

Browse Source 
- 中央：config/(prometheus,alertmanager,grafana)、apps/(tile-cache,topology-editor)
- 边缘：config/(vmagent,blackbox,targets)、apps/(onvif-exporter)
- env: TRAEFIK_PROVIDER、prometheus/env.example 详细说明
- 文档：README/doc 重构，EDGE_CACHE 合并到 EDGE_AGENT_CONFIG
- targets.csv 更新流程说明，ARCHITECTURE 图收窄

Made-with: Cursor
This commit is contained in:
jack
2026-02-28 22:05:43 -05:00
parent 650e5145f1
commit ab1515dffb
48 changed files with 2071 additions and 509 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
doc/ALERTING.md
View File

@@ -6,7 +6,7 @@
## 告警规则（alert_rules.yml）
中央已内置 `central-server/alert_rules.yml`，主要包含：
中央已内置 `central-server/config/prometheus/alert_rules.yml`，主要包含：
| 规则 | 条件 | 说明 |
|------|------|------|
@@ -16,13 +16,13 @@
**为何显示 Inactive**：规则依赖边缘推送的指标。需先部署边缘、配置 Ping/ONVIF 目标，数据经 remote_write 到 VictoriaMetrics 后，规则才会评估；无数据时保持 inactive。
**激活步骤**：完成 [README.md#第二步](README.md) 边缘部署 → 在 Grafana 选 VictoriaMetrics 数据源确认有 `probe_success{job="network-ping"}` 等 → Prometheus 会从 VictoriaMetrics 取数并评估规则。
**激活步骤**：完成边缘部署（见 [README](README.md)、[DEPLOYMENT_GUIDE](DEPLOYMENT_GUIDE.md)）→ 在 Grafana 选 VictoriaMetrics 数据源确认有 `probe_success{job="network-ping"}` 等 → Prometheus 会从 VictoriaMetrics 取数并评估规则。
---
## Alertmanager 配置（alertmanager.yml）
路径：`central-server/alertmanager/alertmanager.yml`。
路径：`central-server/config/alertmanager/alertmanager.yml`。
- **route**：分组（group_by）、等待时间（group_wait）、重复间隔（repeat_interval）、默认接收器（receiver）。
- **receivers**：当前示例为 webhook `http://127.0.0.1:5001/`。
@@ -37,7 +37,7 @@
## 自定义告警规则
在 `alert_rules.yml` 中追加或修改规则，例如：
在 `config/prometheus/alert_rules.yml` 中追加或修改规则，例如：
```yaml
- alert: ExampleAlert

124
doc/ARCHITECTURE.md
View File

@@ -3,78 +3,22 @@
## 容器关系图
```
┌─────────────────────────────────────────────────────────────────┐
│ 边缘节点 (Edge Agents) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Edge Node 1 │ │ Edge Node 2 │ │ Edge Node N │ │
│ │ │ │ │ │ │ │
│ │ Prometheus │ │ Prometheus │ │ Prometheus │ │
│ │ Edge │ │ Edge │ │ Edge │ │
│ │ │ │ │ │ │ │
│ │ ONVIF │ │ ONVIF │ │ ONVIF │ │
│ │ Exporter │ │ Exporter │ │ Exporter │ │
│ │ │ │ │ │ │ │
│ │ Blackbox │ │ Blackbox │ │ Blackbox │ │
│ │ Exporter │ │ Exporter │ │ Exporter │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────┘ │
│ │ │
│ remote_write │
│ (HTTP POST) │
└────────────────────────────┼────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 中央服务器 (Central Server) │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ VictoriaMetrics (8428) │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ 远程写入接收器 │ │ │
│ │ │ - 接收边缘节点推送的指标数据 │ │ │
│ │ │ - 存储时序数据 │ │ │
│ │ │ - 提供查询接口 │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └────────────────────┬───────────────────────────────────────┘ │
│ │ │
│ │ 数据查询 │
│ │ │
│ ┌────────────────────▼───────────────────────────────────────┐ │
│ │ Prometheus Central (9091) │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ 指标收集和查询引擎 │ │ │
│ │ │ - 从 VictoriaMetrics 读取数据 │ │ │
│ │ │ - 抓取本地服务指标 (自身、Grafana、Alertmanager) │ │ │
│ │ │ - 评估告警规则 │ │ │
│ │ │ - 提供 PromQL 查询接口 │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └────────────┬───────────────────────────┬───────────────────┘ │
│ │ │ │
│ │ 告警触发 │ 数据查询 │
│ │ │ │
│ ┌────────────▼──────────┐ ┌─────────────▼──────────────┐ │
│ │ Alertmanager (9093) │ │ Grafana (3000) │ │
│ │ ┌──────────────────┐ │ │ ┌──────────────────────┐ │ │
│ │ │ 告警管理 │ │ │ │ 可视化仪表板 │ │ │
│ │ │ - 接收告警 │ │ │ │ - 从 Prometheus 查询 │ │ │
│ │ │ - 告警分组 │ │ │ │ - 创建图表和仪表板 │ │ │
│ │ │ - 发送通知 │ │ │ │ - 多用户管理 │ │ │
│ │ │ - 告警抑制 │ │ │ │ - 中文界面 │ │ │
│ │ └──────────────────┘ │ │ └──────────────────────┘ │ │
│ └───────────────────────┘ │ └──────────────────────────┘ │
│ │ │
└──────────────────────────────┼──────────────────────────────────┘
│
│ HTTP 访问
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 管理员 │ │ 用户组A │ │ 用户组B │
│ (Admin) │ │ (Org A) │ │ (Org B) │
└─────────────┘ └─────────────┘ └─────────────┘
┌─ 边缘节点 (Edge Node 1/2/…/N) ─────────────────┐
│ vmagent | ONVIF Exporter | Blackbox Exporter │
└──────────────────┬────────────────────────────┘
│ remote_write (HTTP POST)
▼
┌─ 中央服务器 ───────────────────────────────────┐
│ VictoriaMetrics (8428) 接收边缘推送、存储 │
│ │ 数据查询 │
│ ▼ │
│ Prometheus (9091) 抓取本地、告警评估 │
│ ├── 告警 ──> Alertmanager (9093) │
│ └── 查询 ──> Grafana (3000) │
└──────────────────┬─────────────────────────────┘
│ HTTP 访问
▼
管理员 / 用户组A / 用户组B
```
## 数据流向
@@ -173,19 +117,11 @@ Alertmanager 处理告警
## 网络关系
```
monitoring_net (Docker Bridge Network)
│
├─ prometheus-central:9090 (内部)
│ └─> 映射到宿主机:9091
│
├─ grafana:3000 (内部)
│ └─> 映射到宿主机:3000
│
├─ alertmanager:9093 (内部)
│ └─> 映射到宿主机:9093
│
└─ victoria-metrics:8428 (内部)
└─> 映射到宿主机:8428
monitoring_net (Docker Bridge)
├─ prometheus-central:9090 -> 宿主机 9091
├─ grafana:3000 -> 宿主机 3000
├─ alertmanager:9093 -> 宿主机 9093
└─ victoria-metrics:8428 -> 宿主机 8428
```
## 端口映射
@@ -199,25 +135,19 @@ monitoring_net (Docker Bridge Network)
## 数据存储
所有数据存储在 `/storage` 分区：
```
/storage/
central-server/data/
├── prometheus-data/ # Prometheus 时序数据
├── grafana-data/ # Grafana 配置和仪表板
├── victoria-metrics-data/ # VictoriaMetrics 时序数据
└── docker/ # Docker 数据
├── grafana-data/ # Grafana 配置与仪表板
└── victoria-metrics-data/ # VictoriaMetrics 时序数据
```
## 依赖关系
```
VictoriaMetrics
↑ (数据查询)
│
Prometheus
├─> (告警触发) ──> Alertmanager
└─> (数据查询) ──> Grafana
VictoriaMetrics <── Prometheus
├─ 告警 ──> Alertmanager
└─ 查询 ──> Grafana
```
**启动顺序**：

7
doc/BEST_PRACTICES.md
View File

@@ -164,11 +164,8 @@ firewall-cmd --reload
```bash
# 备份所有配置文件
tar -czf config-backup-$(date +%Y%m%d).tar.gz \
central-server/*.yml \
central-server/alertmanager/*.yml \
central-server/grafana/provisioning/ \
edge-agent/*.yml \
edge-agent/prometheus-edge/*.yml
central-server/config/ \
edge-agent/config/
```
#### 数据备份

23
doc/CENTRAL_SERVER_CONFIG.md
View File

@@ -6,13 +6,14 @@
central-server/
├── docker-compose.yml # 服务编排
├── deploy.sh # 部署脚本
├── prometheus.yml # Prometheus 主配置
├── alert_rules.yml # 告警规则
├── alertmanager/alertmanager.yml
└── grafana/
├── setup-users.sh
├── provisioning/datasources/ # prometheus.yml, victoriametrics.yml
└── dashboards/
├── config/ # 配置目录
│ ├── prometheus/ # Prometheus 配置（prometheus.yml、alert_rules.yml）
│ ├── alertmanager/ # Alertmanager 配置
│ └── grafana/ # Grafana 配置（provisioning、dashboards）
├── apps/ # 自建应用源码
│ ├── tile-cache/ # 天地图瓦片缓存
│ └── topology-editor/ # GPS 标注助手
└── data/ # 运行时数据（gitignore）
```
## 主要服务与端口
@@ -26,16 +27,16 @@ central-server/
## 关键配置摘要
- **prometheus.yml**：`remote_write` 指向 VictoriaMetrics；`rule_files: alert_rules.yml`；抓取自身、VM、Alertmanager、Grafana。
- **config/prometheus/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>:4090/tiles/vec/{z}/{x}/{y}`，再添加一层 XYZ 填 `http://<central>:4090/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)。
- **多用户**：`config/grafana/setup-users.sh`，见 [USER_MANAGEMENT.md](USER_MANAGEMENT.md)。
## 修改与重载
- 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`。
- Prometheus：改 `config/prometheus/prometheus.yml` 或 `config/prometheus/alert_rules.yml` 后 `docker compose restart prometheus-central`，或 `curl -X POST http://localhost:9091/-/reload`（若启用 lifecycle）。
- Alertmanager：改 `config/alertmanager/alertmanager.yml` 后 `docker compose restart alertmanager`。
- Grafana：改 provisioning 后重启；或通过 Web UI 修改（持久化到库）。
## 相关文档

34
doc/DEPLOYMENT_GUIDE.md
View File

@@ -1,21 +1,23 @@
# 部署指南
部署顺序见 **[doc/README.md](README.md)#部署顺序**：中央 → 边缘 → 多用户/告警（可选）。本文为各步操作与验证要点。
部署顺序：中央 → 边缘 → 多用户/告警（可选）。详见 [README](README.md)。
---
## 第一步：部署中央服务器
**前置**：Docker、Docker Compose；端口 3000、9091、8428、9093、4090 未被占用；磁盘充足。
**前置**：Docker、Docker Compose；端口 3000、9091、8428、9093 未被占用；磁盘充足。
```bash
cd central-server
cp env.example .env # 可选
cp env.example .env # 可选，按需改端口、Traefik 等
bash deploy.sh
```
**验证**：Grafana http://localhost:3000（admin/admin123）、Prometheus http://localhost:9091、VictoriaMetrics http://localhost:8428。
**详细**：[CENTRAL_SERVER_CONFIG](CENTRAL_SERVER_CONFIG.md)、[central-server/CONFIGURATION.md](../central-server/CONFIGURATION.md)。
---
## 第二步：部署边缘节点
@@ -23,29 +25,31 @@ bash deploy.sh
**前提**：中央已运行，VictoriaMetrics 8428 可访问。
- **本机同机**：`cd edge-agent && bash deploy.sh --local`（中央地址设为 host.docker.internal:8428）。
- **边缘在另一台机器**：
- 在 edge-agent 下 `cp env.example .env`，编辑 `CENTRAL_SERVER_HOST`、`CENTRAL_SERVER_PORT=8428`。
- `bash deploy.sh`（会自动调用 update-configs）。
- **边缘跨机**：`cd edge-agent` → 编辑 `.env` 中 `CENTRAL_SERVER_HOST=中央IP` → `bash deploy.sh`。
**验证**：边缘 Prometheus http://localhost:9092（或边缘机 IP:9092）；中央 Grafana 选数据源 **VictoriaMetrics**，查询 `probe_success{job="network-ping"}` 可见边缘数据。
**验证**：边缘 http://localhost:9092；中央 Grafana 选数据源 **VictoriaMetrics**，查询 `probe_success{job="network-ping"}` 可见边缘数据。
**targets.csv**：部署时自动生成 target-*.json；修改 targets.csv 后需手动 `cd config && ./update-configs.sh`，vmagent 每 5 分钟自动重载。
**常见问题**：
- 看不到边缘数据：确认 `.env` 中为中央 IP（非 host.docker.internal，除非本机同机）；从边缘 `curl -s -o /dev/null -w "%{http_code}" http://<中央IP>:8428/health` 应为 200。
- 端口冲突：边缘 Prometheus 已映射 9092，避免与中央 9091 冲突。
- 看不到边缘数据：确认 `.env` 中为中央 IP（跨机不能用 host.docker.internal）；`curl -s -o /dev/null -w "%{http_code}" http://<中央IP>:8428/health` 应为 200。
- 端口冲突：边缘已映射 9092，与中央 9091 区分。
**详细**：[EDGE_AGENT_CONFIG](EDGE_AGENT_CONFIG.md)、[TARGETS_AND_MONITORING](TARGETS_AND_MONITORING.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`。
- **Grafana 多用户**：`cd central-server/config/grafana && bash setup-users.sh`，见 [USER_MANAGEMENT](USER_MANAGEMENT.md)。
- **告警**：规则见 [ALERTING](ALERTING.md)；通知渠道编辑 `central-server/config/alertmanager/alertmanager.yml`。
---
## 部署后检查清单
- **中央**：`docker compose ps` 中相关服务 Up；Grafana 中 Prometheus 数据源可查 `up`。
- **边缘**：prometheus-edge、blackbox-exporter Up；Grafana 选 VictoriaMetrics 可查 `probe_success{job="network-ping"}` 等。
- **磁盘/端口**：端口冲突用 `ss -tulpn` 排查；空间不足时清理或扩容数据目录。
- **中央**：`docker compose ps` 中相关服务 Up；Grafana Prometheus 数据源可查 `up`。
- **边缘**：prometheus-edge、blackbox-exporter Up；Grafana 选 VictoriaMetrics 可查 `probe_success{job="network-ping"}`。
- **磁盘/端口**：`ss -tulpn` 查端口；空间不足时清理或扩容。
详见 [TROUBLESHOOTING.md](TROUBLESHOOTING.md)、[README.md](README.md)。
详见 [TROUBLESHOOTING](TROUBLESHOOTING.md)。

18
doc/EDGE_AGENT_CONFIG.md
View File

@@ -26,25 +26,27 @@
- **config/targets.csv**：统一监控目标（ping/onvif/topology），格式与脚本见 [TARGETS_AND_MONITORING.md](TARGETS_AND_MONITORING.md)。
- **config/update-configs.sh**：从 targets.csv 生成 `target-onvif.json`、`target-ping.json`、`target-topology.geojson`。
- **prometheus-edge (vmagent)**：使用 `vmagent-scrape.yml.template` 抓取；`CENTRAL_SERVER_HOST`/`PORT` 来自 `.env`；磁盘缓存卷 `vmagent-cache-data`。
- **prometheus-edge (vmagent)**：使用 `config/vmagent/vmagent-scrape.yml.template` 抓取；`CENTRAL_SERVER_HOST`/`PORT` 来自 `.env`；磁盘缓存卷 `vmagent-cache-data`。
- **.env**：`CENTRAL_SERVER_HOST`、`CENTRAL_SERVER_PORT=8428`、`EDGE_NODE_ID`。本机同机用 `./deploy.sh --local`；跨机配 `.env` 后 `./deploy.sh`。
## 常用操作
- 改监控目标：编辑 `config/targets.csv` → `cd config && ./update-configs.sh`，必要时重启 prometheus-edge。
- 改监控目标：编辑 `config/targets.csv` → `cd config && ./update-configs.sh`；vmagent 每 5 分钟自动重载 JSON，无需重启。
- 改中央地址：编辑 `.env` → `docker compose restart prometheus-edge`。
## 中心宕机 / 断网时的缓存
`docker-compose.yaml` 使用 vmagent 统一实现：
`docker-compose.yaml` 使用 vmagent 实现：
- **短时内存缓存**：中心短暂不可达时在内存中缓冲
- **长时磁盘缓存**：长时间离线时写入磁盘队列（默认 512MB），恢复后自动补传
- **冗余重试**：失败自动重试，边缘重启后从磁盘恢复未上传数据
| 层级 | 机制 | 说明 |
|------|------|------|
| **短时内存缓存** | 内存队列 | 中心短暂不可达时在内存中缓冲（约 30 分钟量级） |
| **长时磁盘缓存** | 持久化队列 | 长时间离线写入磁盘（默认 512MB），恢复后自动补传 |
| **冗余重试** | 失败重试 | 边缘重启后从磁盘恢复未上传数据 |
详见 [EDGE_CACHE.md](EDGE_CACHE.md)。
**参数**（修改 prometheus-edge 的 `command` 可调）：`-remoteWrite.maxDiskUsagePerURL=512MB`、`-remoteWrite.tmpDataPath=/cache/remotewrite`、`-memory.allowedPercent=80`。监控指标：`vmagent_remotewrite_pending_bytes`、`vmagent_remotewrite_packets_dropped_total`。
## 相关文档
- [EDGE_CACHE.md](EDGE_CACHE.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)
- [DEPLOYMENT_GUIDE](DEPLOYMENT_GUIDE.md) | [TARGETS_AND_MONITORING](TARGETS_AND_MONITORING.md) | [ONVIF_ALTERNATIVES](ONVIF_ALTERNATIVES.md) | [ARCHITECTURE](ARCHITECTURE.md)

34
doc/EDGE_CACHE.md
View File

@@ -1,34 +0,0 @@
# 边缘节点缓存
## 架构
`docker-compose.yaml` 使用 **vmagent** 统一实现：
| 层级 | 机制 | 说明 |
|------|------|------|
| **短时内存缓存** | 内存队列 | 中心短暂不可达时在内存中缓冲（~30 分钟量级） |
| **长时磁盘缓存** | 持久化队列 | 长时间离线时写入磁盘（默认 512MB），恢复后自动补传 |
| **冗余重试** | 失败重试 | 自动重试，边缘重启后从磁盘恢复未上传数据 |
## 部署
```bash
cd edge-agent
bash deploy.sh
# 本机同机: bash deploy.sh --local
```
## 配置
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `-remoteWrite.maxDiskUsagePerURL` | 512MB | 每 URL 最大磁盘缓存 |
| `-remoteWrite.tmpDataPath` | /cache/remotewrite | 磁盘队列路径 |
| `-memory.allowedPercent` | 80 | 内存队列可用比例 |
修改 `docker-compose.yaml` 中 `prometheus-edge` 的 `command` 可调整上述参数。
## 监控
- `vmagent_remotewrite_pending_bytes`：待发送字节数
- `vmagent_remotewrite_packets_dropped_total`：丢包数

8
doc/ONVIF_ALTERNATIVES.md
View File

@@ -11,7 +11,7 @@
| **SNMP Exporter** | 摄像头/设备支持 SNMP | 用官方 `prom/snmp_exporter`，按设备 MIB 配置 OID，无 ONVIF 协议 |
| **Frigate** | 已用或可部署 Frigate NVR | Frigate 暴露 `/api/metrics`，Prometheus 直接抓取或通过 frigate-exporter |
| **UniFi Protect Exporter** | UniFi 摄像头/Protect | 使用专有 exporter，非 ONVIF 通用方案 |
| **ONVIF 自建** | 必须用 ONVIF 协议 | **本项目已提供**：见 **edge-agent/onvif-exporter/**，Go + use-go/onvif，读取 `onvif-targets.json`，GetDeviceInformation 探测，暴露 `onvif_device_up`、`onvif_probe_duration_seconds`。`docker compose --profile onvif up -d --build` 即可。 |
| **ONVIF 自建** | 必须用 ONVIF 协议 | **本项目已提供**：见 **edge-agent/apps/onvif-exporter/**，Go + use-go/onvif，读取 `target-onvif.json`，GetDeviceInformation 探测，暴露 `onvif_device_up`、`onvif_probe_duration_seconds`。`docker compose --profile onvif up -d --build` 即可。 |
| **仅 Ping/HTTP 探测** | 只关心在线与可达性 | 用 Blackbox Exporter 对摄像头 IP 做 ICMP/HTTP 探测，不解析 ONVIF |
---
@@ -63,19 +63,19 @@
## 4. ONVIF 自建 Exporter（必须走 ONVIF 时）
**本项目已在 edge-agent/onvif-exporter/ 提供自建容器**，无需再找第三方镜像。
**本项目已在 edge-agent/apps/onvif-exporter/ 提供自建容器**，无需再找第三方镜像。
- **实现**：Go + [use-go/onvif](https://github.com/use-go/onvif)，读取 `config/target-onvif.json`（与 `targets.csv` 中 onvif 行一致），轮询 ONVIF `GetDeviceInformation`，暴露 Prometheus 指标 `onvif_device_up`、`onvif_probe_duration_seconds`。
- **启用**：在边缘节点执行 `docker compose --profile onvif up -d --build`，会构建并启动 ONVIF exporter，无需设置 `ONVIF_EXPORTER_IMAGE`。
- **配置**：在 `config/targets.csv` 中增加 onvif 行（ip、device_type、model、location、username、password、onvif_port），运行 `config/update-configs.sh` 生成 `target-onvif.json`。
- 若需自行修改或扩展，见 **edge-agent/onvif-exporter/README.md**。
- 若需自行修改或扩展，见 **edge-agent/apps/onvif-exporter/README.md**。
---
## 在本项目中的建议
- **边缘默认部署**：不依赖不存在的 ONVIF 镜像；默认只跑 **prometheus-edge** + **blackbox-exporter**（Ping/探测），可选用 **snmp-exporter** 或 Frigate 抓取。
- **若需要 ONVIF**：使用本项目自建的 **edge-agent/onvif-exporter**，执行 `docker compose --profile onvif up -d --build` 即可构建并启动；无需再设 `ONVIF_EXPORTER_IMAGE`。
- **若需要 ONVIF**：使用本项目自建的 **edge-agent/apps/onvif-exporter**，执行 `docker compose --profile onvif up -d --build` 即可构建并启动；无需再设 `ONVIF_EXPORTER_IMAGE`。
- **摄像头支持 SNMP 时**：优先考虑 **SNMP Exporter** 作为“Prometheus 监控摄像头”的替代方案，再根据需要补充 Frigate 或 Blackbox。
具体边缘配置与 compose 变更见 **[EDGE_AGENT_CONFIG.md](EDGE_AGENT_CONFIG.md)** 及 `edge-agent/docker-compose.yaml`。

117
doc/README.md
View File

@@ -1,112 +1,63 @@
# Distributed-Prometheus 文档
# 文档索引
本目录为项目文档入口。**先按部署顺序做完第一步、第二步，再按需查阅其他文档。**
本目录为项目文档入口。**首次部署**按「部署顺序」先中央、后边缘；**修改配置**按需查阅对应文档。
---
## 部署顺序（必读）
## 部署顺序
整体顺序：**先中央，后边缘**。边缘向中央主动上报数据，中央必须先就绪。
| 步骤 | 操作 | 验证 |
|------|------|------|
| **1. 中央** | `cd central-server && cp env.example .env && bash deploy.sh` | Grafana http://localhost:3000、Prometheus http://localhost:9091 |
| **2. 边缘** | `cd edge-agent && bash deploy.sh`（本机同机加 `--local`） | 边缘 http://localhost:9092；Grafana 选 VictoriaMetrics 可见 `probe_success{job="network-ping"}` |
| **3. 可选** | 多用户、告警通知 | [USER_MANAGEMENT](USER_MANAGEMENT.md)、[ALERTING](ALERTING.md) |
| 步骤 | 部署 / 操作对象 | 做什么 | 验证 |
|------|------------------|--------|------|
| **第一步** | 中央服务器 | 部署 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)、[ALERTING.md](ALERTING.md) 验证 |
**边缘跨机**：编辑 `edge-agent/.env` 中 `CENTRAL_SERVER_HOST` 为中央 IP，再 `bash deploy.sh`。
**targets.csv**：部署时自动从 targets.csv 生成 target-onvif.json、target-ping.json；修改 targets.csv 后需手动 `cd config && ./update-configs.sh`，vmagent 每 5 分钟自动重载。
---
### 第一步：部署中央服务器
**必须先做**。中央提供 VictoriaMetrics（接收边缘数据）、Prometheus、Grafana、Alertmanager。
```bash
cd central-server
cp env.example .env # 可选：按需改端口、Traefik、网络等
bash deploy.sh
```
- **前置**：已安装 Docker、Docker Compose；端口 3000、9091、8428、9093 未被占用。
- **验证**：访问 http://localhost:3000（Grafana，admin/admin123）、http://localhost:9091（Prometheus）。
- **详细**：[DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md)、[CENTRAL_SERVER_CONFIG.md](CENTRAL_SERVER_CONFIG.md)、[central-server/CONFIGURATION.md](../central-server/CONFIGURATION.md)。
---
### 第二步：部署边缘节点
**在中央已运行后**进行。边缘将指标推送到中央 VictoriaMetrics（端口 8428）。
边缘必选：**remote_write**（prometheus-edge）、**Blackbox** 容器；可选：ONVIF/SNMP 等容器（见 [EDGE_AGENT_CONFIG.md](EDGE_AGENT_CONFIG.md)）。
- **本机同机**（中央与边缘在同一台机器）：
```bash
cd edge-agent
bash deploy.sh --local
```
脚本会设置中央地址为 `host.docker.internal:8428` 并执行部署。
- **边缘在另一台机器**：
```bash
cd edge-agent
cp env.example .env
# 编辑 .env：CENTRAL_SERVER_HOST=中央服务器IP，CENTRAL_SERVER_PORT=8428
cd config && ./update-configs.sh && cd .. # 从 targets.csv 生成 JSON
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_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` 配置接收端；告警规则与说明见 [ALERTING.md](ALERTING.md)。
---
## 文档列表（按用途）
## 文档列表
### 架构与数据流
| 文档 | 说明 |
|------|------|
| [ARCHITECTURE.md](ARCHITECTURE.md) | 系统架构、容器关系、数据流向、端口与依赖 |
| [ARCHITECTURE](ARCHITECTURE.md) | 容器关系图、数据流向、端口与依赖 |
### 配置说明
### 中央节点
| 文档 | 说明 |
|------|------|
| [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_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、自建） |
| [CENTRAL_SERVER_CONFIG](CENTRAL_SERVER_CONFIG.md) | 中央目录结构、服务端口、关键配置 |
| [../central-server/CONFIGURATION.md](../central-server/CONFIGURATION.md) | 中央环境变量（.env）说明 |
### 用户与告警
### 边缘节点
| 文档 | 说明 |
|------|------|
| [USER_MANAGEMENT.md](USER_MANAGEMENT.md) | Grafana 多用户、组织与数据隔离 |
| [ALERTING.md](ALERTING.md) | 告警规则、Alertmanager 配置与通知渠道 |
| [EDGE_AGENT_CONFIG](EDGE_AGENT_CONFIG.md) | 边缘目录结构、vmagent、blackbox、缓存机制 |
| [TARGETS_AND_MONITORING](TARGETS_AND_MONITORING.md) | targets.csv 格式、update-configs.sh、监控类型 |
### 部署与运维
### 告警与多用户
| 文档 | 说明 |
|------|------|
| [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) | 完整部署步骤、检查清单、验证与常见问题 |
| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | 故障排查 |
| [BEST_PRACTICES.md](BEST_PRACTICES.md) | 最佳实践与生产环境建议 |
| [ALERTING](ALERTING.md) | 告警规则、Alertmanager 配置、通知渠道 |
| [USER_MANAGEMENT](USER_MANAGEMENT.md) | Grafana 多用户、组织与数据隔离 |
---
### 扩展功能
## 快速导航
| 文档 | 说明 |
|------|------|
| [ONVIF_ALTERNATIVES](ONVIF_ALTERNATIVES.md) | ONVIF 摄像头监控方案（SNMP、Frigate、Blackbox、自建） |
| [TIANDITU_CONFIG](TIANDITU_CONFIG.md) | 天地图底图、Grafana Geomap、tile-cache |
- **第一次部署**：按上面「部署顺序」先做第一步，再做第二步。
- **只改中央配置**：看 [CENTRAL_SERVER_CONFIG.md](CENTRAL_SERVER_CONFIG.md)、[CONFIGURATION.md](../central-server/CONFIGURATION.md)。
- **只改边缘 / 监控目标**：看 [EDGE_AGENT_CONFIG.md](EDGE_AGENT_CONFIG.md)、[TARGETS_AND_MONITORING.md](TARGETS_AND_MONITORING.md)。
- **多用户 / 告警**：看 [USER_MANAGEMENT.md](USER_MANAGEMENT.md)、[ALERTING.md](ALERTING.md)。
- **出问题**：看 [TROUBLESHOOTING.md](TROUBLESHOOTING.md)、[DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md)。
### 运维
| 文档 | 说明 |
|------|------|
| [DEPLOYMENT_GUIDE](DEPLOYMENT_GUIDE.md) | 完整部署步骤、检查清单、常见问题 |
| [TROUBLESHOOTING](TROUBLESHOOTING.md) | 故障排查 |
| [BEST_PRACTICES](BEST_PRACTICES.md) | 最佳实践与生产建议 |

2
doc/TARGETS_AND_MONITORING.md
View File

@@ -2,6 +2,8 @@
边缘监控目标统一由 `edge-agent/config/targets.csv` 配置，经 `update-configs.sh` 生成 `target-onvif.json`、`target-ping.json`、`target-topology.geojson`。
**更新流程**：部署时 deploy.sh 自动从 targets.csv 生成 target-*.json；修改 targets.csv 后需手动执行 `cd edge-agent/config && ./update-configs.sh`，vmagent 每 5 分钟自动重载 JSON，无需重启。
---
## targets.csv 格式

8
doc/TROUBLESHOOTING.md
View File

@@ -116,10 +116,10 @@ docker compose logs prometheus-edge
# 查询: probe_success{job="network-ping"}
# 2. 检查告警规则文件
cat central-server/alert_rules.yml
cat central-server/config/prometheus/alert_rules.yml
# 3. 检查 Prometheus 配置
cat central-server/prometheus.yml
cat central-server/config/prometheus/prometheus.yml
```
**常见原因**：
@@ -130,7 +130,7 @@ cat central-server/prometheus.yml
**解决方案**：
- 部署边缘节点并配置监控目标
- 检查告警规则表达式
- 确认 `prometheus.yml` 中引用了 `alert_rules.yml`
- 确认 `config/prometheus/prometheus.yml` 中引用了 `alert_rules.yml`
- 重启 Prometheus 容器
---
@@ -374,7 +374,7 @@ ls -lh /storage/prometheus-data
ls -lh /storage/victoria-metrics-data
# 检查数据保留配置
grep retention prometheus.yml
grep retention config/prometheus/prometheus.yml
```
**解决**：