完善中央与边缘部署、远程写入与监控文档
- 增加中央与边缘完整配置和部署脚本 - 引入 VictoriaMetrics 数据源与 remote_write 故障排查说明 - 新增 edge-agent 配置脚本、ONVIF 自建 exporter 与 ping 监控示例 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Super User
372
central-server/CONFIGURATION.md
Normal file
372
central-server/CONFIGURATION.md
Normal file
@@ -0,0 +1,372 @@
|
||||
# 中央服务器配置说明
|
||||
|
||||
本文档说明如何配置中央服务器的各项参数。
|
||||
|
||||
## 配置文件结构
|
||||
|
||||
中央服务器使用 `.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位，包含大小写字母、数字和特殊字符）
|
||||
|
||||
### 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 是边缘节点数据的长期存储
|
||||
- 保留时间越长，占用存储空间越大
|
||||
- 建议根据实际存储容量和需求设置
|
||||
|
||||
### 数据存储路径配置
|
||||
|
||||
| 参数 | 默认值 | 说明 |
|
||||
|------|--------|------|
|
||||
| `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/ALERT_RULES_EXPLANATION.md)
|
||||
- [Alertmanager 配置说明](../doc/ALERTMANAGER_CONFIG.md)
|
||||
Reference in New Issue
Block a user