Distributed-Prometheus/central-server/CONFIGURATION.md

中央服务器配置说明

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

配置文件结构

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

• .env - 环境变量配置文件（从 env.example 复制并修改）
• docker-compose.yml - Docker Compose 服务定义（使用环境变量）
• config/ - 配置目录
  • prometheus/ - Prometheus 配置（prometheus.yml.template, prometheus.yml, alert_rules.yml）
  • alertmanager/ - Alertmanager 配置（alertmanager.yml）
  • grafana/ - Grafana 配置（provisioning, dashboards）
• apps/ - 自建应用源码
  • tile-cache/ - 天地图瓦片缓存
  • topology-editor/ - GPS 标注助手

快速开始

1. 复制环境变量模板：

   cd central-server
   cp env.example .env
   

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

3. 运行部署脚本：

   ./deploy.sh
   

部署脚本会自动：

• 加载 .env 文件中的环境变量
• 从 config/prometheus/prometheus.yml.template 生成 config/prometheus/prometheus.yml
• 创建数据目录并设置权限
• 启动所有服务

配置参数说明

端口配置

参数	默认值	说明
PROMETHEUS_PORT	9091	Prometheus Web UI 端口（避免与 cockpit 冲突）
GRAFANA_PORT	3000	Grafana Web UI 端口
ALERTMANAGER_PORT	9093	Alertmanager Web UI 端口
VICTORIAMETRICS_PORT	18428	vmauth 对外端口（边缘节点推送数据/查询都走此端口）

注意：

• 如果端口被占用，修改 .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。

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 中填写。在 天地图开放平台 申请。
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_PROVIDER	external	Traefik 来源：internal=本编排启动 Traefik；external=使用已有外部 Traefik
TRAEFIK_NETWORK	traefik	Traefik 网络名称（external 时通常为 traefik；internal 时 deploy.sh 设为 central_default）
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_PROVIDER=internal：本编排内启动 Traefik，监听 80/443，自动创建网络，无需外部 Traefik
• TRAEFIK_PROVIDER=external：接入已有 Traefik，需 docker network create traefik（若不存在）
• 需要配置 DNS 解析，将域名指向本机
• VictoriaMetrics 通常不通过 Traefik 访问（边缘节点直接连接）
• 如果使用 HTTPS，需要配置 Traefik 的 TLS 证书

Docker 网络配置

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

网络配置说明：

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

配置示例

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

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

# 将 Prometheus 端口改为 9092
PROMETHEUS_PORT=9092

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

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

PROMETHEUS_RETENTION_TIME=90d
VICTORIAMETRICS_RETENTION_PERIOD=90d

注意：保留时间越长，需要的存储空间越大。90天大约需要：

• 每个边缘节点：约 5-10GB（取决于监控目标数量）
• 中央服务器：约 2-5GB

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

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

# 使用绝对路径（例如使用 /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 使用域名访问服务：

# 启用 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：生产环境安全配置

生产环境建议配置：

# 使用强密码
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. 停止服务：

   docker compose down
   # 或
   docker-compose down
   

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

3. 重新运行部署脚本：

   ./deploy.sh
   

部署脚本会自动：

• 重新加载环境变量
• 从模板重新生成 prometheus.yml
• 更新 Docker Compose 配置
• 重启所有服务

配置文件说明

docker-compose.yml

Docker Compose 配置文件，定义了所有服务的：

• 镜像版本
• 端口映射（使用环境变量）
• 数据卷挂载（使用环境变量）
• 环境变量（使用环境变量）
• 启动命令（使用环境变量）

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

config/prometheus/prometheus.yml.template

Prometheus 配置模板文件（位于 config/prometheus/），包含：

• 全局配置（抓取间隔、评估间隔、集群名称）
• 远程写入配置（接收边缘节点数据）
• 抓取配置（抓取本地服务指标）
• 告警规则配置
• Alertmanager 配置

注意：

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

config/prometheus/prometheus.yml

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

注意：

• 此文件由部署脚本自动生成，不要手动编辑
• 如果需要修改，应修改 config/prometheus/prometheus.yml.template 和 .env 文件

config/prometheus/alert_rules.yml

Prometheus 告警规则配置文件，定义了：

• ONVIF 设备告警规则（设备离线、高温、存储不足）
• 网络设备告警规则（设备离线、高延迟）

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

config/alertmanager/alertmanager.yml

Alertmanager 告警管理配置文件，定义了：

• 告警路由规则
• 告警分组规则
• 告警抑制规则
• 告警接收器（通知渠道）

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

常见问题

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

A: 确保：

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

Q2: 如何查看当前配置？

A:

• 查看环境变量：cat .env
• 查看生成的 Prometheus 配置：cat config/prometheus/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:

# 备份所有配置文件
tar -czf central-server-config-backup-$(date +%Y%m%d).tar.gz \
    .env \
    config/ \
    docker-compose.yml

Q5: 如何恢复默认配置？

A:

# 从模板重新创建 .env
cp env.example .env
# 重新部署
./deploy.sh

相关文档

• 中央服务器架构说明
• 部署指南
• 告警与通知