Distributed-Prometheus/doc/CENTRAL_SERVER_CONFIG.md

# 中央服务器配置文件说明

## 目录结构

```
central-server/
├── docker-compose.yml          # Docker Compose 服务编排配置
├── deploy.sh                   # 部署脚本
├── prometheus.yml              # Prometheus 主配置文件
├── alert_rules.yml             # 告警规则定义
├── alertmanager/
│   └── alertmanager.yml        # Alertmanager 告警管理配置
└── grafana/
    ├── setup-users.sh          # 多用户配置脚本
    ├── provisioning/
    │   ├── datasources/        # 数据源自动配置
    │   │   ├── prometheus.yml  # Prometheus 数据源
    │   │   └── prometheus-admin.yml  # 管理员全局数据源
    │   └── dashboards/         # 仪表板自动配置
    │       └── dashboard.yml   # 仪表板配置
    └── dashboards/
        └── onvif-monitoring.json  # ONVIF 监控仪表板
```

## 配置文件详解

### 1. docker-compose.yml

**作用**：定义所有 Docker 容器的配置和编排

**包含的服务**：
- `prometheus-central` - Prometheus 中央服务器（端口 9091）
- `grafana` - Grafana 可视化仪表板（端口 3000，中文界面）
- `alertmanager` - 告警管理器（端口 9093）
- `victoria-metrics` - 远程写入接收器（端口 8428）

**关键配置**：
- 数据存储：所有数据存储在 `/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，需要部署接收服务或修改为其他通知方式

---

## 相关文档

- **系统架构**：`doc/ARCHITECTURE.md`
- **告警规则**：`doc/ALERT_RULES_EXPLANATION.md`
- **Alertmanager 配置**：`doc/ALERTMANAGER_CONFIG.md`
- **用户管理**：`doc/USER_MANAGEMENT.md`