Distributed-Prometheus/central-server/CONFIGURATION.md

# 中央服务器配置说明

本文档说明如何配置中央服务器的各项参数。

## 配置文件结构

中央服务器使用 `.env` 文件管理所有可配置参数，主要配置文件包括：

- **`.env`** - 环境变量配置文件（从 `env.example` 复制并修改）
- **`docker-compose.yml`** - Docker Compose 服务定义（使用环境变量）
- **`prometheus.yml.template`** - Prometheus 配置模板（部署时自动生成 `prometheus.yml`）
- **`prometheus.yml`** - Prometheus 实际配置文件（由模板自动生成，不要手动编辑）
- **`alert_rules.yml`** - Prometheus 告警规则配置
- **`alertmanager/alertmanager.yml`** - Alertmanager 告警管理配置

## 快速开始

1. **复制环境变量模板**：
   ```bash
   cd central-server
   cp env.example .env
   ```

2. **编辑 `.env` 文件**，根据实际情况修改配置参数

3. **运行部署脚本**：
   ```bash
   ./deploy.sh
   ```

部署脚本会自动：
- 加载 `.env` 文件中的环境变量
- 从 `prometheus.yml.template` 生成 `prometheus.yml`
- 创建数据目录并设置权限
- 启动所有服务

## 配置参数说明

### 端口配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `PROMETHEUS_PORT` | 9091 | Prometheus Web UI 端口（避免与 cockpit 冲突） |
| `GRAFANA_PORT` | 3000 | Grafana Web UI 端口 |
| `ALERTMANAGER_PORT` | 9093 | Alertmanager Web UI 端口 |
| `VICTORIAMETRICS_PORT` | 8428 | VictoriaMetrics 端口（边缘节点推送数据到此端口） |

**注意**：
- 如果端口被占用，修改 `.env` 文件中对应的端口号
- 修改端口后需要重新运行 `./deploy.sh`
- 确保防火墙已开放相应端口

### Grafana 配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `GRAFANA_ADMIN_PASSWORD` | admin123 | Grafana 管理员密码（**首次部署后请立即修改**） |
| `GRAFANA_DEFAULT_LANGUAGE` | zh-Hans | Grafana 默认语言（zh-Hans=简体中文，en=英文） |
| `GRAFANA_DEFAULT_THEME` | light | Grafana 默认主题（light=浅色，dark=深色） |

**安全建议**：
- 生产环境必须修改 `GRAFANA_ADMIN_PASSWORD`
- 建议使用强密码（至少12位，包含大小写字母、数字和特殊字符）

**Geomap 使用天地图缓存**：若在 Grafana 的 Geomap 面板中要用天地图底图且走缓存（不暴露 key），可将 Base layer 设为 XYZ Tile layer，底图 URL：`http://<本机或 central>:4090/tiles/vec/{z}/{x}/{y}`，再添加一层：`http://<本机或 central>:4090/tiles/cva/{z}/{x}/{y}`。需在 central 配置 `TIANDITU_TK` 与 tile-cache。详见 [../doc/TIANDITU_CONFIG.md](../doc/TIANDITU_CONFIG.md)。

### Prometheus 配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `PROMETHEUS_RETENTION_TIME` | 30d | Prometheus 数据保留时间（30d=30天，7d=7天） |
| `PROMETHEUS_SCRAPE_INTERVAL` | 15 | Prometheus 抓取间隔（秒） |
| `PROMETHEUS_EVALUATION_INTERVAL` | 15 | Prometheus 告警评估间隔（秒） |
| `PROMETHEUS_CLUSTER_NAME` | central-monitoring | Prometheus 集群标识（用于区分不同集群） |

**性能调优**：
- `PROMETHEUS_SCRAPE_INTERVAL` 越小，数据越实时，但会增加系统负载
- 建议值：15-30秒（一般监控），60秒（低频监控）
- `PROMETHEUS_RETENTION_TIME` 越大，历史数据保留越久，但占用更多存储空间

### 远程写入配置

这些参数控制边缘节点向中央服务器推送数据的性能：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `PROMETHEUS_REMOTE_WRITE_MAX_SAMPLES` | 10000 | 每次发送的最大样本数 |
| `PROMETHEUS_REMOTE_WRITE_CAPACITY` | 20000 | 队列容量（样本数） |
| `PROMETHEUS_REMOTE_WRITE_MAX_SHARDS` | 10 | 最大分片数（并发写入数） |

**调优建议**：
- 边缘节点较多时，可以增加 `MAX_SHARDS` 提高并发处理能力
- 网络不稳定时，可以增加 `CAPACITY` 提高缓冲能力
- 一般情况使用默认值即可

### VictoriaMetrics 配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `VICTORIAMETRICS_RETENTION_PERIOD` | 30d | VictoriaMetrics 数据保留时间 |

**注意**：
- VictoriaMetrics 是边缘节点数据的长期存储
- 保留时间越长，占用存储空间越大
- 建议根据实际存储容量和需求设置

### 天地图 / 瓦片缓存配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `TIANDITU_TK` | （空） | **天地图密钥**，配置到 `.env` 中。启用后 tile-cache、拓扑助手「使用服务器缓存」及 Grafana Geomap 使用天地图底图时均使用此密钥，无需在浏览器或 Grafana 中填写。在 [天地图开放平台](https://console.tianditu.gov.cn/) 申请。 |
| `TILE_CACHE_PORT` | 4090 | 瓦片缓存服务端口 |
| `TILE_CACHE_DATA_DIR` | ./data/tile-cache | 瓦片缓存数据目录 |
| `TILE_CACHE_TTL_DAYS` | 7 | 缓存老化时间（天），超过后该瓦片下次请求时重新向天地图拉取；可改为 15 等 |

**说明**：以上参数均在 **central-server/.env** 中配置；部署时由 docker-compose 传入 tile-cache 容器。

### 数据存储路径配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `DATA_STORAGE_ROOT` | ./data | 数据存储根目录（相对于 central-server 目录） |
| `PROMETHEUS_DATA_DIR` | ./data/prometheus-data | Prometheus 数据目录（相对路径） |
| `GRAFANA_DATA_DIR` | ./data/grafana-data | Grafana 数据目录（相对路径） |
| `VICTORIAMETRICS_DATA_DIR` | ./data/victoria-metrics-data | VictoriaMetrics 数据目录（相对路径） |

**存储说明**：
- 默认使用相对路径，数据存储在 `central-server/data/` 目录下
- 部署脚本会自动将相对路径转换为绝对路径（Docker 需要绝对路径）
- 如果需要使用其他路径，可以修改为绝对路径（如 `/data/prometheus-data`）
- 确保目录有足够的写权限

### Traefik 反向代理配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `TRAEFIK_ENABLED` | true | 是否启用 Traefik 反向代理 |
| `TRAEFIK_NETWORK` | traefik | Traefik 网络名称 |
| `GRAFANA_DOMAIN` | grafana.example.com | Grafana 域名 |
| `PROMETHEUS_DOMAIN` | prometheus.example.com | Prometheus 域名 |
| `ALERTMANAGER_DOMAIN` | alertmanager.example.com | Alertmanager 域名 |
| `TRAEFIK_ENTRYPOINT` | web | Traefik EntryPoint 名称 |
| `TRAEFIK_HTTPS_ENABLED` | false | 是否启用 HTTPS |
| `GRAFANA_ROOT_URL` | http://localhost:3000 | Grafana 根 URL（使用 Traefik 时设置为 https://域名） |

**Traefik 配置说明**：
- 启用 Traefik 后，服务将通过域名访问，不再直接暴露端口
- 需要确保 Traefik 网络已创建：`docker network create traefik`（如果不存在）
- 需要配置 DNS 解析，将域名指向 Traefik 服务器
- VictoriaMetrics 通常不通过 Traefik 访问（边缘节点直接连接）
- 如果使用 HTTPS，需要配置 Traefik 的 TLS 证书
- `NETWORK_NAME` 必须与 Traefik 实际网络一致，否则 Traefik 无法转发

### Docker 网络配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `NETWORK_NAME` | traefik | Compose 网络名称（与 Traefik 实际网络一致） |
| `ENABLE_IPV6` | false | 是否启用 IPv6（true/false） |

**网络配置说明**：
- `NETWORK_NAME` 必须与 Traefik 实际网络名称一致，否则 Traefik 无法访问服务
- 如需 IPv6，请设为 `true`，并确保 Docker 已启用 IPv6

## 配置示例

### 示例 1：修改端口避免冲突

如果 9091 端口被占用，修改 `.env`：

```bash
# 将 Prometheus 端口改为 9092
PROMETHEUS_PORT=9092
```

### 示例 2：延长数据保留时间

如果需要保留 90 天的历史数据，修改 `.env`：

```bash
PROMETHEUS_RETENTION_TIME=90d
VICTORIAMETRICS_RETENTION_PERIOD=90d
```

**注意**：保留时间越长，需要的存储空间越大。90天大约需要：
- 每个边缘节点：约 5-10GB（取决于监控目标数量）
- 中央服务器：约 2-5GB

### 示例 3：使用自定义存储路径

如果需要使用其他分区或绝对路径：

```bash
# 使用绝对路径（例如使用 /data 分区）
DATA_STORAGE_ROOT=/data
PROMETHEUS_DATA_DIR=/data/prometheus-data
GRAFANA_DATA_DIR=/data/grafana-data
VICTORIAMETRICS_DATA_DIR=/data/victoria-metrics-data

# 或者使用相对路径（相对于 central-server 目录）
PROMETHEUS_DATA_DIR=./data/prometheus-data
GRAFANA_DATA_DIR=./data/grafana-data
VICTORIAMETRICS_DATA_DIR=./data/victoria-metrics-data
```

### 示例 4：启用 Traefik 反向代理

通过 Traefik 使用域名访问服务：

```bash
# 启用 Traefik
TRAEFIK_ENABLED=true
TRAEFIK_NETWORK=traefik
NETWORK_NAME=traefik
ENABLE_IPV6=false

# 配置域名（需要配置 DNS 解析）
GRAFANA_DOMAIN=grafana.yourdomain.com
PROMETHEUS_DOMAIN=prometheus.yourdomain.com
ALERTMANAGER_DOMAIN=alertmanager.yourdomain.com

# 如果使用 HTTPS
TRAEFIK_HTTPS_ENABLED=true
TRAEFIK_ENTRYPOINT=websecure
GRAFANA_ROOT_URL=https://grafana.yourdomain.com
```

**注意**：
- 确保 Traefik 网络已创建：`docker network create traefik`
- 配置 DNS 解析，将域名指向 Traefik 服务器
- 如果使用 HTTPS，需要在 Traefik 中配置 TLS 证书

### 示例 5：生产环境安全配置

生产环境建议配置：

```bash
# 使用强密码
GRAFANA_ADMIN_PASSWORD=YourStrongPassword123!

# 启用 Traefik 反向代理（推荐）
TRAEFIK_ENABLED=true
TRAEFIK_NETWORK=traefik
NETWORK_NAME=traefik
GRAFANA_DOMAIN=grafana.yourdomain.com
PROMETHEUS_DOMAIN=prometheus.yourdomain.com
ALERTMANAGER_DOMAIN=alertmanager.yourdomain.com

# 或使用非标准端口（如果不用 Traefik）
GRAFANA_PORT=3001
PROMETHEUS_PORT=9092

# 延长数据保留时间
PROMETHEUS_RETENTION_TIME=90d
VICTORIAMETRICS_RETENTION_PERIOD=90d
```

## 配置修改流程

1. **停止服务**：
   ```bash
   docker compose down
   # 或
   docker-compose down
   ```

2. **编辑 `.env` 文件**，修改需要更改的参数

3. **重新运行部署脚本**：
   ```bash
   ./deploy.sh
   ```

部署脚本会自动：
- 重新加载环境变量
- 从模板重新生成 `prometheus.yml`
- 更新 Docker Compose 配置
- 重启所有服务

## 配置文件说明

### docker-compose.yml

Docker Compose 配置文件，定义了所有服务的：
- 镜像版本
- 端口映射（使用环境变量）
- 数据卷挂载（使用环境变量）
- 环境变量（使用环境变量）
- 启动命令（使用环境变量）

**注意**：此文件已配置为使用环境变量，一般不需要手动修改。

### prometheus.yml.template

Prometheus 配置模板文件，包含：
- 全局配置（抓取间隔、评估间隔、集群名称）
- 远程写入配置（接收边缘节点数据）
- 抓取配置（抓取本地服务指标）
- 告警规则配置
- Alertmanager 配置

**注意**：
- 此文件是模板，不要直接使用
- 部署脚本会自动从此模板生成 `prometheus.yml`
- 修改配置应通过 `.env` 文件，而不是直接修改模板

### prometheus.yml

Prometheus 实际配置文件，由 `prometheus.yml.template` 自动生成。

**注意**：
- 此文件由部署脚本自动生成，**不要手动编辑**
- 如果需要修改，应修改 `prometheus.yml.template` 和 `.env` 文件

### alert_rules.yml

Prometheus 告警规则配置文件，定义了：
- ONVIF 设备告警规则（设备离线、高温、存储不足）
- 网络设备告警规则（设备离线、高延迟）

**注意**：此文件需要手动编辑，修改后需要重启 Prometheus 服务。

### alertmanager/alertmanager.yml

Alertmanager 告警管理配置文件，定义了：
- 告警路由规则
- 告警分组规则
- 告警抑制规则
- 告警接收器（通知渠道）

**注意**：此文件需要手动编辑，修改后需要重启 Alertmanager 服务。

## 常见问题

### Q1: 修改配置后服务没有生效？

**A**: 确保：
1. 已重新运行 `./deploy.sh` 脚本
2. 检查服务是否正常启动：`docker compose ps`
3. 查看服务日志：`docker compose logs`

### Q2: 如何查看当前配置？

**A**: 
- 查看环境变量：`cat .env`
- 查看生成的 Prometheus 配置：`cat prometheus.yml`
- 查看 Docker Compose 配置：`cat docker-compose.yml`

### Q3: 配置错误导致服务无法启动？

**A**: 
1. 检查 `.env` 文件语法（确保没有多余的空格或特殊字符）
2. 检查端口是否被占用：`netstat -tuln | grep <端口>`
3. 检查数据目录权限：`ls -ld /storage/*-data`
4. 查看错误日志：`docker compose logs`

### Q4: 如何备份配置？

**A**: 
```bash
# 备份所有配置文件
tar -czf central-server-config-backup-$(date +%Y%m%d).tar.gz \
    .env \
    prometheus.yml.template \
    alert_rules.yml \
    alertmanager/alertmanager.yml \
    docker-compose.yml
```

### Q5: 如何恢复默认配置？

**A**: 
```bash
# 从模板重新创建 .env
cp env.example .env
# 重新部署
./deploy.sh
```

## 相关文档

- [中央服务器架构说明](../doc/ARCHITECTURE.md)
- [部署指南](../doc/DEPLOYMENT_GUIDE.md)
- [告警与通知](../doc/ALERTING.md)