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

- 中央：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

central-server/env.example

@@ -1,55 +1,85 @@
-# 中央服务器环境变量配置
-# 复制此文件为 .env 并根据实际情况修改
+# =============================================================================
+# 中央服务器环境变量配置模板
+# =============================================================================
+#
+# 【用途】
+#   本文件为 central-server 所有可配置参数的模板，供 deploy.sh 和 docker-compose 使用。
+#   部署脚本 deploy.sh 会读取 .env，并将部分变量代入 prometheus.yml.template 生成 prometheus.yml。
+#
+# 【使用方式】
+#   1. 复制为 .env：  cp env.example .env
+#   2. 编辑 .env，按实际环境修改参数
+#   3. 运行部署脚本： ./deploy.sh
+#
+# 若不存在 .env，deploy.sh 会自动从 env.example 创建，并提示修改后重试。
+#
+# 【变量去向】
+#   - deploy.sh：加载 .env，生成 prometheus.yml，创建数据目录，启动 docker-compose
+#   - docker-compose：端口、数据目录、容器环境变量、Traefik 标签等
+#   - prometheus.yml.template：PROMETHEUS_*、VICTORIAMETRICS_PORT 等（见模板头部）
+#
+# 【修改生效】
+#   修改 .env 后需重新运行 ./deploy.sh。不要直接编辑 prometheus.yml，其由模板生成。
+#
+# =============================================================================
 
 # ============================================
 # 端口配置
 # ============================================
+# 宿主机映射端口，对应各服务容器内端口。端口冲突时修改此处。
 
-# Prometheus 端口（避免与 cockpit 冲突）
+# Prometheus Web UI 端口（避免与 cockpit 9090 冲突，故默认 9091）
+# 访问：http://localhost:${PROMETHEUS_PORT}
 PROMETHEUS_PORT=9091
 
-# Grafana 端口
+# Grafana Web UI 端口
+# 访问：http://localhost:${GRAFANA_PORT}
 GRAFANA_PORT=3000
 
-# Alertmanager 端口
+# Alertmanager Web UI 端口
 ALERTMANAGER_PORT=9093
 
-# VictoriaMetrics 端口（边缘节点推送数据到此端口）
+# VictoriaMetrics 端口（边缘 vmagent 通过 remote_write 推送到此端口）
+# 必须与边缘侧 CENTRAL_VM_URL 中的端口一致；通常不通过 Traefik，边缘直连
 VICTORIAMETRICS_PORT=8428
 
 # ============================================
 # Grafana 配置
 # ============================================
 
-# Grafana 管理员密码
+# Grafana 管理员密码（生产环境必须修改，建议 12 位以上强密码）
 GRAFANA_ADMIN_PASSWORD=admin123
 
-# Grafana 默认语言
+# Grafana 默认语言：zh-Hans 简体中文，en 英文
 GRAFANA_DEFAULT_LANGUAGE=zh-Hans
 
-# Grafana 默认主题
+# Grafana 默认主题：light 浅色，dark 深色
 GRAFANA_DEFAULT_THEME=light
 
-# Grafana 根 URL（用于 Traefik 反向代理，如果使用 Traefik，设置为 https://grafana.example.com）
+# Grafana 根 URL（使用 Traefik 时设为对外访问地址，如 https://grafana.example.com）
+# 影响登录跳转、OAuth 回调等
 GRAFANA_ROOT_URL=http://localhost:3000
 
 # ============================================
 # Prometheus 配置
 # ============================================
+# 部分变量会代入 prometheus.yml.template 生成 prometheus.yml
 
-# Prometheus 数据保留时间
+# Prometheus 本地 TSDB 数据保留时间（如 30d、7d、1y）
 PROMETHEUS_RETENTION_TIME=30d
 
-# Prometheus 抓取间隔（秒）
+# 抓取间隔（秒），影响中央 Prometheus 抓取本机服务的频率
+# 建议 15–60；越小越实时，负载越高
 PROMETHEUS_SCRAPE_INTERVAL=15
 
-# Prometheus 告警评估间隔（秒）
+# 告警规则评估间隔（秒）
 PROMETHEUS_EVALUATION_INTERVAL=15
 
-# Prometheus 集群标识
+# 集群标识，作为 external_labels 中的 cluster 标签，用于区分多集群
 PROMETHEUS_CLUSTER_NAME=central-monitoring
 
-# 远程写入队列配置
+# remote_write 到 VictoriaMetrics 的队列参数（中央 Prometheus 将抓取数据推送到 VM）
+# 边缘写入量大时可适当调大；一般保持默认即可
 PROMETHEUS_REMOTE_WRITE_MAX_SAMPLES=10000
 PROMETHEUS_REMOTE_WRITE_CAPACITY=20000
 PROMETHEUS_REMOTE_WRITE_MAX_SHARDS=10
@@ -57,81 +87,83 @@ PROMETHEUS_REMOTE_WRITE_MAX_SHARDS=10
 # ============================================
 # VictoriaMetrics 配置
 # ============================================
+# VM 接收边缘 remote_write 并存储；Grafana 数据源通常指向 VM
 
-# VictoriaMetrics 数据保留时间
+# VM 数据保留时间（如 30d、90d）
 VICTORIAMETRICS_RETENTION_PERIOD=30d
 
 # ============================================
 # 数据存储路径
 # ============================================
+# 相对于 central-server 目录；deploy.sh 会转换为绝对路径供 Docker 使用
 
-# 数据存储根目录（所有数据存储在此目录下，相对于 central-server 目录）
-# 使用相对路径，数据将存储在 central-server 目录下的 data 子目录中
+# 数据存储根目录（可选，部分脚本可能引用）
 DATA_STORAGE_ROOT=./data
 
-# Prometheus 数据目录
+# Prometheus 本地 TSDB 数据目录
 PROMETHEUS_DATA_DIR=./data/prometheus-data
 
-# Grafana 数据目录
+# Grafana 数据库与插件数据目录
 GRAFANA_DATA_DIR=./data/grafana-data
 
-# VictoriaMetrics 数据目录
+# VictoriaMetrics 时序数据目录
 VICTORIAMETRICS_DATA_DIR=./data/victoria-metrics-data
 
-# 天地图瓦片缓存（密钥与缓存参数均在 .env 中配置）
-# 在 .env 中设置 TIANDITU_TK 后，tile-cache 与拓扑助手「使用服务器缓存」、Grafana Geomap 方可使用天地图
+# 天地图瓦片缓存（供 topology-editor、Grafana Geomap 使用）
+# 在 .env 中设置 TIANDITU_TK 后，tile-cache 才可正常工作
 # TIANDITU_TK=您的天地图密钥
 # TILE_CACHE_PORT=4090
 # TILE_CACHE_DATA_DIR=./data/tile-cache
-# 缓存老化时间（天），超过后该瓦片下次请求时会重新向天地图拉取；默认 7，可改为 15 等
 # TILE_CACHE_TTL_DAYS=7
-# 向天地图请求单瓦片超时（毫秒），默认 15000；网络或上游慢时可适当调大
 # TILE_CACHE_UPSTREAM_TIMEOUT_MS=15000
 
 # ============================================
 # Traefik 反向代理配置
 # ============================================
+# 启用后，docker-compose 会为各服务添加 Traefik 标签，通过域名访问
 
-# 是否启用 Traefik 反向代理（true/false）
-# 如果启用，服务将通过 Traefik 访问，不再直接暴露端口
+# 是否启用 Traefik（true/false）。为 false 时通过宿主机端口直接访问
 TRAEFIK_ENABLED=true
 
-# Traefik 网络名称（通常为 traefik）
+# Traefik 来源：internal=本编排启动 Traefik（包含 traefik 服务）；external=使用已有外部 Traefik
+# internal：本 compose 内启动 Traefik，自动创建网络，无需外部 Traefik
+# external：接入已有 Traefik，需 traefik 网络已存在（如单独部署的 Traefik）
+TRAEFIK_PROVIDER=external
+
+# Traefik 所在 Docker 网络名称
+# external 时通常为 traefik；internal 时为 central_default（compose 自动创建）
 TRAEFIK_NETWORK=traefik
 
-# 域名配置（需要配置 DNS 解析到 Traefik 服务器）
-# Grafana 域名
+# 域名（需 DNS 解析到 Traefik 所在机器）
 GRAFANA_DOMAIN=grafana.example.com
-
-# Prometheus 域名
 PROMETHEUS_DOMAIN=prometheus.example.com
-
-# Alertmanager 域名
 ALERTMANAGER_DOMAIN=alertmanager.example.com
-
-# VictoriaMetrics 域名（通常不需要通过 Traefik 访问，边缘节点直接连接）
 VICTORIAMETRICS_DOMAIN=vm.example.com
 
-# Traefik EntryPoint（通常为 web 或 websecure）
+# Traefik EntryPoint（web=80, websecure=443）
 TRAEFIK_ENTRYPOINT=web
 
-# 是否启用 HTTPS（需要配置 Traefik 的 TLS）
+# 是否启用 HTTPS（需 Traefik 配置 TLS）
 TRAEFIK_HTTPS_ENABLED=false
 
+# TRAEFIK_PROVIDER=internal 时，Traefik 监听的宿主机端口
+# TRAEFIK_HTTP_PORT=80
+# TRAEFIK_HTTPS_PORT=443
+
 # ============================================
 # Docker 网络配置
 # ============================================
+# 由 TRAEFIK_PROVIDER 决定；一般无需手动改，deploy.sh 会自动设置
 
-# Compose 项目名称（用于区分同一目录下的多套部署，避免与旧状态冲突）
+# Compose 项目名称，用于区分同一目录多套部署
 COMPOSE_PROJECT_NAME=central
 
-# 使用已存在的 traefik 网络（由 Traefik 创建，不在此项目中创建）
-# 保持以下两项即可接入现有 Traefik
+# TRAEFIK_PROVIDER=external 时：
 NETWORK_NAME=traefik
 EXTERNAL_NETWORK=true
 
-# 仅在不使用 Traefik、仅本地直连时改为：
-# NETWORK_NAME=central-server_default
+# TRAEFIK_PROVIDER=internal 时（deploy.sh 会自动改为）：
+# NETWORK_NAME=central_default
 # EXTERNAL_NETWORK=false
 
 # 是否启用 IPv6（true/false）