72a5bf30b4
- tile-cache: 瓦片缓存服务(vec/cva)、启动探针、详细日志、上游超时可配置(UPSTREAM_TIMEOUT_MS) - central: docker-compose 集成 tile-cache，env.example 增加 TILE_CACHE_* / TIANDITU_TK - topology-editor: 天地图/缓存加载、GPS 安全来源错误提示、TIANDITU 文档(403/白名单、localhost 测试说明) - doc: README 部署步骤与 GPS 安全来源说明，TIANDITU_CONFIG 完善 Co-authored-by: Cursor <cursoragent@cursor.com>
7.6 KiB
Distributed-Prometheus 文档
本目录为项目文档入口。先按部署顺序做完第一步、第二步，再按需查阅其他文档。
部署顺序（必读）
整体顺序：先中央，后边缘，再按需标注拓扑。边缘向中央主动上报数据，中央必须先就绪。
| 步骤 | 部署 / 操作对象 | 做什么 | 验证 |
|---|---|---|---|
| 第一步 | 中央服务器 | 部署 Prometheus、Grafana、VictoriaMetrics、Alertmanager | Grafana http://localhost:3000、Prometheus http://localhost:9091 |
| 第二步 | 边缘节点（可选，可多台） | 配置中央地址与监控目标，部署边缘 Prometheus + Exporter | 边缘 UI http://localhost:9092，Grafana 选 VictoriaMetrics 数据源可见边缘数据 |
| 第三步 | 多用户 / 告警（可选） | 配置 Grafana 组织与用户、Alertmanager 通知 | 按 USER_MANAGEMENT.md、ALERTING.md 验证 |
| 第四步 | 拓扑标注助手 topology-editor（可选） | 上传/编辑/下载 targets.csv，用 GPS 与天地图给设备打点并维护拓扑关系 |
在 Grafana Geomap 中按经纬度与 parent/uplink_type 展示网络拓扑 |
第一步：部署中央服务器
必须先做。中央提供 VictoriaMetrics（接收边缘数据）、Prometheus、Grafana、Alertmanager。
cd central-server
cp env.example .env # 可选：按需改端口、Traefik、网络等
bash deploy.sh
- 前置：已安装 Docker、Docker Compose；端口 3000、9091、8428、9093 未被占用。
- 验证：访问 http://localhost:3000（Grafana，admin/admin123）、http://localhost:9091（Prometheus）。
- 详细：DEPLOYMENT_GUIDE.md、CENTRAL_SERVER_CONFIG.md、central-server/CONFIGURATION.md。
第二步：部署边缘节点
在中央已运行后进行。边缘将指标推送到中央 VictoriaMetrics（端口 8428）。
边缘必选：remote_write（prometheus-edge）、Blackbox 容器；可选：ONVIF/SNMP 等容器（见 EDGE_AGENT_CONFIG.md）。
-
本机同机（中央与边缘在同一台机器）：
cd edge-agent bash run-edge-local.sh脚本会设置中央地址为
host.docker.internal:8428并执行部署。 -
边缘在另一台机器：
cd edge-agent cp env.example .env # 编辑 .env：CENTRAL_SERVER_HOST=中央服务器IP，CENTRAL_SERVER_PORT=8428 cd config && ./update-configs.sh && cd .. # 从 targets.csv 生成 JSON bash deploy.sh -
验证：边缘 Prometheus UI http://localhost:9092（端口 9092 避免与中央 9091 冲突）。在中央 Grafana 中选择数据源「VictoriaMetrics」，查询如
up{job="network-ping"}可见边缘数据；中央自身指标在数据源「Prometheus」。 -
摄像头/ONVIF：默认不拉取 ONVIF 镜像（公共镜像不存在）。监控摄像头可选：SNMP Exporter、Frigate、Blackbox 探测 或自建 ONVIF 镜像，见 ONVIF_ALTERNATIVES.md。
-
监控目标：编辑
edge-agent/config/targets.csv（Ping / ONVIF / 拓扑），详见 TARGETS_AND_MONITORING.md。
第三步（可选）：多用户与告警
- Grafana 多用户：
cd central-server/grafana && bash setup-users.sh，然后按 USER_MANAGEMENT.md 配置组织与数据源。 - 告警通知：编辑
central-server/alertmanager/alertmanager.yml配置接收端；告警规则与说明见 ALERTING.md。
第四步（可选）：拓扑标注助手 / targets.csv 标注
拓扑标注助手是一个与 central 同机运行的小型 Web 服务（在 topology-editor/ 目录下），用来：
- 上传 / 下载
targets.csv； - 在手机或浏览器中选择设备、获取 GPS 定位；浏览器要求页面为安全来源（HTTPS 或 http://localhost / 127.0.0.1），否则会报「only secure origins are allowed」无法定位，需通过 HTTPS 访问或在本机用 localhost 打开。
- 叠加天地图底图，点击地图修正坐标；天地图需填写 TK（申请密钥），底图与标识图说明见 TIANDITU_CONFIG.md。可选：在 central 配置 TIANDITU_TK 启用瓦片缓存，节省 key 免费量，缓存按 TTL 自动老化。
- 维护
name/role/parent/uplink_type等拓扑字段。
典型用法：
-
上传 CSV：在本机更新
targets.csv后，访问http://<central>:4080，在顶部区域上传。 -
选择设备补点：在下拉框中选择已有设备，用「获取 GPS」或点地图修正经纬度，必要时调整
parent/uplink_type。 -
保存标注：点击「保存到 targets.csv」仅更新标注助手中的当前副本。
-
下载 CSV：点击「下载 targets.csv」得到新的 CSV，将其下发到各边缘节点的
edge-agent/config/targets.csv。 -
在边缘生成配置与拓扑：在边缘执行：
cd edge-agent/config ./update-configs.sh ./csv-to-topology-geojson.sh targets.csv topology.geojson之后 Grafana Geomap 可以同时展示：设备点位（lat/lon）、上下级连线（parent）、链路类型（uplink_type）。
文档列表（按用途）
架构与数据流
| 文档 | 说明 |
|---|---|
| ARCHITECTURE.md | 系统架构、容器关系、数据流向、端口与依赖 |
配置说明
| 文档 | 说明 |
|---|---|
| CENTRAL_SERVER_CONFIG.md | 中央服务器配置文件说明 |
| ../central-server/CONFIGURATION.md | 中央服务器环境变量（.env）说明 |
| EDGE_AGENT_CONFIG.md | 边缘节点配置文件说明 |
| TARGETS_AND_MONITORING.md | 监控目标与 targets.csv（格式、脚本、数据流） |
| TIANDITU_CONFIG.md | 天地图配置（底图 vec_w、标识图 cva_w、WMTS 地址） |
| ONVIF_ALTERNATIVES.md | 摄像头/ONVIF 监控替代方案（SNMP、Frigate、Blackbox、自建） |
用户与告警
| 文档 | 说明 |
|---|---|
| USER_MANAGEMENT.md | Grafana 多用户、组织与数据隔离 |
| ALERTING.md | 告警规则、Alertmanager 配置与通知渠道 |
部署与运维
| 文档 | 说明 |
|---|---|
| DEPLOYMENT_GUIDE.md | 完整部署步骤、检查清单、验证与常见问题 |
| TROUBLESHOOTING.md | 故障排查 |
| BEST_PRACTICES.md | 最佳实践与生产环境建议 |
快速导航
- 第一次部署：按上面「部署顺序」先做第一步，再做第二步。
- 只改中央配置：看 CENTRAL_SERVER_CONFIG.md、CONFIGURATION.md。
- 只改边缘 / 监控目标：看 EDGE_AGENT_CONFIG.md、TARGETS_AND_MONITORING.md。
- 拓扑标注助手：第四步；上传/编辑/下载 targets.csv；天地图底图与标识图见 TIANDITU_CONFIG.md。
- 多用户 / 告警：看 USER_MANAGEMENT.md、ALERTING.md。
- 出问题：看 TROUBLESHOOTING.md、DEPLOYMENT_GUIDE.md。