refactor: 边缘节点与配置精简

- 边缘: Prometheus 改为 vmagent，统一 docker-compose.yml，内存+磁盘缓存 - 边缘脚本: 合并为 deploy.sh [--local]，删除 run-edge-local、quick-setup、run-edge-with-cache - 配置: 合并为 update-configs.sh，统一 targets.csv，生成 target-onvif/target-ping/target-topology - 删除 topology-editor、旧格式 devices.csv/ping-targets.csv、setup-remote-write、test-connection - 文档: 更新 EDGE_CACHE、TIANDITU（瓦片改 4090 直连 tile-cache） Made-with: Cursor
2026-02-28 19:44:46 -05:00
parent 72a5bf30b4
commit 650e5145f1
35 changed files with 319 additions and 2774 deletions
--- a/doc/CENTRAL_SERVER_CONFIG.md
+++ b/doc/CENTRAL_SERVER_CONFIG.md
@@ -29,7 +29,7 @@ central-server/
 - **prometheus.yml**：`remote_write` 指向 VictoriaMetrics；`rule_files: alert_rules.yml`；抓取自身、VM、Alertmanager、Grafana。
 - **告警规则与通知**：见 [ALERTING.md](ALERTING.md)。
 - **Grafana 数据源**：Provisioning 下配置 Prometheus、VictoriaMetrics；查边缘指标请选 **VictoriaMetrics**。
- **Grafana Geomap 使用天地图缓存**：在 Geomap 面板中将 Base layer 选为 **XYZ Tile layer**，底图 URL 填 `http://<central>:4080/tiles/vec/{z}/{x}/{y}`，再添加一层 XYZ 填 `http://<central>:4080/tiles/cva/{z}/{x}/{y}`（中文注记）。key 仅需在 central 配置 `TIANDITU_TK`，无需在 Grafana 中填写。详见 [TIANDITU_CONFIG.md](TIANDITU_CONFIG.md)。
+- **Grafana Geomap 使用天地图缓存**：在 Geomap 面板中将 Base layer 选为 **XYZ Tile layer**，底图 URL 填 `http://<central>:4090/tiles/vec/{z}/{x}/{y}`，再添加一层 XYZ 填 `http://<central>:4090/tiles/cva/{z}/{x}/{y}`（中文注记）。key 仅需在 central 配置 `TIANDITU_TK`，无需在 Grafana 中填写。详见 [TIANDITU_CONFIG.md](TIANDITU_CONFIG.md)。
 - **多用户**：`grafana/setup-users.sh`，见 [USER_MANAGEMENT.md](USER_MANAGEMENT.md)。

 ## 修改与重载
--- a/doc/DEPLOYMENT_GUIDE.md
+++ b/doc/DEPLOYMENT_GUIDE.md
@@ -1,12 +1,12 @@
 # 部署指南

-部署顺序见 **[doc/README.md](README.md)#部署顺序**：中央 → 边缘 → 多用户/告警（可选）→ 拓扑标注（可选）。本文为各步操作与验证要点。
+部署顺序见 **[doc/README.md](README.md)#部署顺序**：中央 → 边缘 → 多用户/告警（可选）。本文为各步操作与验证要点。

 ---

 ## 第一步：部署中央服务器

-**前置**：Docker、Docker Compose；端口 3000、9091、8428、9093、4080 未被占用；磁盘充足。
+**前置**：Docker、Docker Compose；端口 3000、9091、8428、9093、4090 未被占用；磁盘充足。

 ```bash
 cd central-server
@@ -14,7 +14,7 @@ cp env.example .env   # 可选
 bash deploy.sh
 ```

-**验证**：Grafana http://localhost:3000（admin/admin123）、Prometheus http://localhost:9091、VictoriaMetrics http://localhost:8428、拓扑标注助手 http://localhost:4080。
+**验证**：Grafana http://localhost:3000（admin/admin123）、Prometheus http://localhost:9091、VictoriaMetrics http://localhost:8428。

 ---

@@ -22,10 +22,10 @@ bash deploy.sh

 **前提**：中央已运行，VictoriaMetrics 8428 可访问。

- **本机同机**：`cd edge-agent && bash run-edge-local.sh`（中央地址设为 host.docker.internal:8428）。
+- **本机同机**：`cd edge-agent && bash deploy.sh --local`（中央地址设为 host.docker.internal:8428）。
 - **边缘在另一台机器**：  
  - 在 edge-agent 下 `cp env.example .env`，编辑 `CENTRAL_SERVER_HOST`、`CENTRAL_SERVER_PORT=8428`。  
-  - `cd config && ./update-configs.sh && cd .. && bash deploy.sh`。
+  - `bash deploy.sh`（会自动调用 update-configs）。

 **验证**：边缘 Prometheus http://localhost:9092（或边缘机 IP:9092）；中央 Grafana 选数据源 **VictoriaMetrics**，查询 `probe_success{job="network-ping"}` 可见边缘数据。

@@ -42,16 +42,6 @@ bash deploy.sh

 ---

-## 第四步（可选）：拓扑标注助手
-
-与中央同机运行，访问 http://localhost:4080。上传本机 `targets.csv` → 选择设备、GPS 或地图点击补坐标 → 保存 → 下载 CSV → 将下载文件部署到各边缘 `edge-agent/config/targets.csv`，在边缘执行：
-
-```bash
-cd edge-agent/config && ./update-configs.sh && ./csv-to-topology-geojson.sh targets.csv topology.geojson
-```
-
---
-
 ## 部署后检查清单

 - **中央**：`docker compose ps` 中相关服务 Up；Grafana 中 Prometheus 数据源可查 `up`。  
--- a/doc/EDGE_AGENT_CONFIG.md
+++ b/doc/EDGE_AGENT_CONFIG.md
@@ -2,34 +2,49 @@

 ## 需要什么

-| 类型 | 说明 | 对应组件 |
-|------|------|----------|
-| **必选** | remote_write 推送到中央 | prometheus-edge |
-| **必选** | Ping/网络探测 | blackbox-exporter |
-| **可选** | ONVIF 等 | onvif-exporter（`--profile onvif`），见 [ONVIF_ALTERNATIVES.md](ONVIF_ALTERNATIVES.md) |
+
+| 类型     | 说明                 | 对应组件                                                                               |
+| ------ | ------------------ | ---------------------------------------------------------------------------------- |
+| **必选** | remote_write 推送到中央 | prometheus-edge                                                                    |
+| **必选** | Ping/网络探测          | blackbox-exporter                                                                  |
+| **可选** | ONVIF 等            | onvif-exporter（`--profile onvif`），见 [ONVIF_ALTERNATIVES.md](ONVIF_ALTERNATIVES.md) |
+

 ## 容器与数据流

-| 容器 | 作用 | 端口 |
-|------|------|------|
-| prometheus-edge | 抓取 Blackbox（及可选 ONVIF），remote_write → 中央 VictoriaMetrics | 9092 |
-| blackbox-exporter | Ping/HTTP/TCP 探测 | 9115（内部） |
-| onvif-exporter | 可选，ONVIF 探测 | 9600（内部） |
+
+| 容器                | 作用                                                       | 端口       |
+| ----------------- | -------------------------------------------------------- | -------- |
+| prometheus-edge (vmagent) | 抓取 Blackbox（及可选 ONVIF），remote_write → 中央 VictoriaMetrics，含内存+磁盘缓存 | 9092 |
+| blackbox-exporter | Ping/HTTP/TCP 探测                                         | 9115（内部） |
+| onvif-exporter    | 可选，ONVIF 探测                                              | 9600（内部） |
+

 数据流：目标 → Exporter → prometheus-edge → remote_write → 中央 VictoriaMetrics。

 ## 目录与配置

 - **config/targets.csv**：统一监控目标（ping/onvif/topology），格式与脚本见 [TARGETS_AND_MONITORING.md](TARGETS_AND_MONITORING.md)。
- **config/update-configs.sh**：从 targets.csv 生成 `onvif-targets.json`、`ping-targets.json`。
- **prometheus-edge**：使用 `prometheus.yml.template` + deploy.sh 中 envsubst，注入 `CENTRAL_SERVER_HOST`/`PORT`；数据目录使用 Docker 卷 `prometheus-edge-data`。
- **.env**：`CENTRAL_SERVER_HOST`、`CENTRAL_SERVER_PORT=8428`、`EDGE_NODE_ID`。本机同机可用 `run-edge-local.sh`（host.docker.internal）；跨机填中央 IP。
+- **config/update-configs.sh**：从 targets.csv 生成 `target-onvif.json`、`target-ping.json`、`target-topology.geojson`。
+- **prometheus-edge (vmagent)**：使用 `vmagent-scrape.yml.template` 抓取；`CENTRAL_SERVER_HOST`/`PORT` 来自 `.env`；磁盘缓存卷 `vmagent-cache-data`。
+- **.env**：`CENTRAL_SERVER_HOST`、`CENTRAL_SERVER_PORT=8428`、`EDGE_NODE_ID`。本机同机用 `./deploy.sh --local`；跨机配 `.env` 后 `./deploy.sh`。

 ## 常用操作

 - 改监控目标：编辑 `config/targets.csv` → `cd config && ./update-configs.sh`，必要时重启 prometheus-edge。
 - 改中央地址：编辑 `.env` → `docker compose restart prometheus-edge`。

+## 中心宕机 / 断网时的缓存
+
+`docker-compose.yaml` 使用 vmagent 统一实现：
+
+- **短时内存缓存**：中心短暂不可达时在内存中缓冲
+- **长时磁盘缓存**：长时间离线时写入磁盘队列（默认 512MB），恢复后自动补传
+- **冗余重试**：失败自动重试，边缘重启后从磁盘恢复未上传数据
+
+详见 [EDGE_CACHE.md](EDGE_CACHE.md)。
+
 ## 相关文档

- [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) | [TARGETS_AND_MONITORING.md](TARGETS_AND_MONITORING.md) | [ONVIF_ALTERNATIVES.md](ONVIF_ALTERNATIVES.md) | [ARCHITECTURE.md](ARCHITECTURE.md)
+- [EDGE_CACHE.md](EDGE_CACHE.md) | [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) | [TARGETS_AND_MONITORING.md](TARGETS_AND_MONITORING.md) | [ONVIF_ALTERNATIVES.md](ONVIF_ALTERNATIVES.md) | [ARCHITECTURE.md](ARCHITECTURE.md)
+
--- a/doc/EDGE_CACHE.md
+++ b/doc/EDGE_CACHE.md
@@ -0,0 +1,34 @@
+# 边缘节点缓存
+
+## 架构
+
+`docker-compose.yaml` 使用 **vmagent** 统一实现：
+
+| 层级 | 机制 | 说明 |
+|------|------|------|
+| **短时内存缓存** | 内存队列 | 中心短暂不可达时在内存中缓冲（~30 分钟量级） |
+| **长时磁盘缓存** | 持久化队列 | 长时间离线时写入磁盘（默认 512MB），恢复后自动补传 |
+| **冗余重试** | 失败重试 | 自动重试，边缘重启后从磁盘恢复未上传数据 |
+
+## 部署
+
+```bash
+cd edge-agent
+bash deploy.sh
+# 本机同机: bash deploy.sh --local
+```
+
+## 配置
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `-remoteWrite.maxDiskUsagePerURL` | 512MB | 每 URL 最大磁盘缓存 |
+| `-remoteWrite.tmpDataPath` | /cache/remotewrite | 磁盘队列路径 |
+| `-memory.allowedPercent` | 80 | 内存队列可用比例 |
+
+修改 `docker-compose.yaml` 中 `prometheus-edge` 的 `command` 可调整上述参数。
+
+## 监控
+
+- `vmagent_remotewrite_pending_bytes`：待发送字节数
+- `vmagent_remotewrite_packets_dropped_total`：丢包数
--- a/doc/ONVIF_ALTERNATIVES.md
+++ b/doc/ONVIF_ALTERNATIVES.md
@@ -55,7 +55,7 @@
 不解析 ONVIF，只监控“摄像头/NVR 是否在线、端口是否可达”。

 - **已有组件**：边缘节点已包含 **Blackbox Exporter**（如 `prom/blackbox-exporter`）。
- **做法**：在 `config/ping-targets.json`（或等价目标列表）中加入摄像头/NVR 的 IP，用 ICMP 或 TCP/HTTP 探测（例如对 80/8000 等端口做 `tcp_connect` 或 `http_2xx`）。
+- **做法**：在 `config/target-ping.json`（或等价目标列表）中加入摄像头/NVR 的 IP，用 ICMP 或 TCP/HTTP 探测（例如对 80/8000 等端口做 `tcp_connect` 或 `http_2xx`）。
 - **优点**：无需任何 ONVIF 镜像，部署即可用，与现有 Ping 监控一致。
 - **缺点**：无设备级 ONVIF 状态、无摄像头特有指标。

@@ -65,9 +65,9 @@

 **本项目已在 edge-agent/onvif-exporter/ 提供自建容器**，无需再找第三方镜像。

- **实现**：Go + [use-go/onvif](https://github.com/use-go/onvif)，读取 `config/onvif-targets.json`（与 `targets.csv` 中 onvif 行一致），轮询 ONVIF `GetDeviceInformation`，暴露 Prometheus 指标 `onvif_device_up`、`onvif_probe_duration_seconds`。
+- **实现**：Go + [use-go/onvif](https://github.com/use-go/onvif)，读取 `config/target-onvif.json`（与 `targets.csv` 中 onvif 行一致），轮询 ONVIF `GetDeviceInformation`，暴露 Prometheus 指标 `onvif_device_up`、`onvif_probe_duration_seconds`。
 - **启用**：在边缘节点执行 `docker compose --profile onvif up -d --build`，会构建并启动 ONVIF exporter，无需设置 `ONVIF_EXPORTER_IMAGE`。
- **配置**：在 `config/targets.csv` 中增加 onvif 行（ip、device_type、model、location、username、password、onvif_port），运行 `config/update-configs.sh` 生成 `onvif-targets.json`。
+- **配置**：在 `config/targets.csv` 中增加 onvif 行（ip、device_type、model、location、username、password、onvif_port），运行 `config/update-configs.sh` 生成 `target-onvif.json`。
 - 若需自行修改或扩展，见 **edge-agent/onvif-exporter/README.md**。

 ---
@@ -78,4 +78,4 @@
 - **若需要 ONVIF**：使用本项目自建的 **edge-agent/onvif-exporter**，执行 `docker compose --profile onvif up -d --build` 即可构建并启动；无需再设 `ONVIF_EXPORTER_IMAGE`。
 - **摄像头支持 SNMP 时**：优先考虑 **SNMP Exporter** 作为“Prometheus 监控摄像头”的替代方案，再根据需要补充 Frigate 或 Blackbox。

-具体边缘配置与 compose 变更见 **[EDGE_AGENT_CONFIG.md](EDGE_AGENT_CONFIG.md)** 及 `edge-agent/docker-compose.yml`。
+具体边缘配置与 compose 变更见 **[EDGE_AGENT_CONFIG.md](EDGE_AGENT_CONFIG.md)** 及 `edge-agent/docker-compose.yaml`。
--- a/doc/README.md
+++ b/doc/README.md
@@ -6,14 +6,13 @@

 ## 部署顺序（必读）

-整体顺序：**先中央，后边缘，再按需标注拓扑**。边缘向中央主动上报数据，中央必须先就绪。
+整体顺序：**先中央，后边缘**。边缘向中央主动上报数据，中央必须先就绪。

 | 步骤 | 部署 / 操作对象 | 做什么 | 验证 |
 |------|------------------|--------|------|
 | **第一步** | 中央服务器 | 部署 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](USER_MANAGEMENT.md)、[ALERTING.md](ALERTING.md) 验证 |
-| **第四步** | 拓扑标注助手 topology-editor（可选） | 上传/编辑/下载 `targets.csv`，用 GPS 与天地图给设备打点并维护拓扑关系 | 在 Grafana Geomap 中按经纬度与 parent/uplink_type 展示网络拓扑 |

 ---

@@ -41,7 +40,7 @@ bash deploy.sh
 - **本机同机**（中央与边缘在同一台机器）：
  ```bash
  cd edge-agent
-  bash run-edge-local.sh
+  bash deploy.sh --local
  ```
  脚本会设置中央地址为 `host.docker.internal:8428` 并执行部署。

@@ -68,33 +67,6 @@ bash deploy.sh

 ---

-### 第四步（可选）：拓扑标注助手 / targets.csv 标注
-
-拓扑标注助手是一个与 central 同机运行的小型 Web 服务（在 `topology-editor/` 目录下），用来：
-
- 上传 / 下载 `targets.csv`；
- 在手机或浏览器中选择设备、**获取 GPS 定位**；浏览器要求页面为**安全来源**（HTTPS 或 http://localhost / 127.0.0.1），否则会报「only secure origins are allowed」无法定位，需通过 HTTPS 访问或在本机用 localhost 打开。
- 叠加天地图底图，点击地图修正坐标；天地图需填写 **TK**（[申请密钥](https://console.tianditu.gov.cn/)），底图与标识图说明见 [TIANDITU_CONFIG.md](TIANDITU_CONFIG.md)。可选：在 central 配置 **TIANDITU_TK** 启用瓦片缓存，节省 key 免费量，缓存按 TTL 自动老化。
- 维护 `name` / `role` / `parent` / `uplink_type` 等拓扑字段。
-
-典型用法：
-
-1. **上传 CSV**：在本机更新 `targets.csv` 后，访问 `http://<central>:4080`，在顶部区域上传。  
-2. **选择设备补点**：在下拉框中选择已有设备，用「获取 GPS」或点地图修正经纬度，必要时调整 `parent` / `uplink_type`。  
-3. **保存标注**：点击「保存到 targets.csv」仅更新标注助手中的当前副本。  
-4. **下载 CSV**：点击「下载 targets.csv」得到新的 CSV，将其下发到各边缘节点的 `edge-agent/config/targets.csv`。  
-5. **在边缘生成配置与拓扑**：在边缘执行：
-
-   ```bash
-   cd edge-agent/config
-   ./update-configs.sh
-   ./csv-to-topology-geojson.sh targets.csv topology.geojson
-   ```
-
-   之后 Grafana Geomap 可以同时展示：设备点位（lat/lon）、上下级连线（parent）、链路类型（uplink_type）。
-
---
-
 ## 文档列表（按用途）

 ### 架构与数据流
@@ -136,6 +108,5 @@ bash deploy.sh
 - **第一次部署**：按上面「部署顺序」先做第一步，再做第二步。
 - **只改中央配置**：看 [CENTRAL_SERVER_CONFIG.md](CENTRAL_SERVER_CONFIG.md)、[CONFIGURATION.md](../central-server/CONFIGURATION.md)。
 - **只改边缘 / 监控目标**：看 [EDGE_AGENT_CONFIG.md](EDGE_AGENT_CONFIG.md)、[TARGETS_AND_MONITORING.md](TARGETS_AND_MONITORING.md)。
- **拓扑标注助手**：第四步；上传/编辑/下载 targets.csv；天地图底图与标识图见 [TIANDITU_CONFIG.md](TIANDITU_CONFIG.md)。
 - **多用户 / 告警**：看 [USER_MANAGEMENT.md](USER_MANAGEMENT.md)、[ALERTING.md](ALERTING.md)。
 - **出问题**：看 [TROUBLESHOOTING.md](TROUBLESHOOTING.md)、[DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md)。
--- a/doc/TARGETS_AND_MONITORING.md
+++ b/doc/TARGETS_AND_MONITORING.md
@@ -1,6 +1,6 @@
 # 监控目标与 targets.csv

-边缘监控目标统一由 `edge-agent/config/targets.csv` 配置，经 `update-configs.sh` 生成 `onvif-targets.json`、`ping-targets.json`，并可生成拓扑 GeoJSON 供 Grafana Geomap 使用。
+边缘监控目标统一由 `edge-agent/config/targets.csv` 配置，经 `update-configs.sh` 生成 `target-onvif.json`、`target-ping.json`、`target-topology.geojson`。

 ---

@@ -25,9 +25,9 @@ type,ip,name,role,parent,uplink_type,network,device_type,model,location,username
 | username, password, onvif_port | ONVIF 认证与端口（默认 80） | onvif |
 | lat, lon | 经纬度（十进制度），Geomap 打点与拓扑 | 可选 |

- **ping**：有 IP，由 Blackbox Exporter 探测，生成 `ping-targets.json`。
- **onvif**：有 IP，由 ONVIF Exporter 探测，生成 `onvif-targets.json`；需填 device_type, model, location, username, password。
- **topology**：仅拓扑节点（可无 IP），不参与抓取；用于生成 `topology.geojson` 画点与连线。
+- **ping**：有 IP，由 Blackbox Exporter 探测，生成 `target-ping.json`。
+- **onvif**：有 IP，由 ONVIF Exporter 探测，生成 `target-onvif.json`；需填 device_type, model, location, username, password。
+- **topology**：仅拓扑节点（可无 IP），不参与抓取；用于生成 `target-topology.geojson` 画点与连线。

 ---

@@ -47,13 +47,10 @@ onvif,192.168.1.100,camera_front,camera,dumb_sw_1,copper,internal,camera,HIKVISI

 ```bash
 cd edge-agent/config
-chmod +x *.sh
 ./update-configs.sh
-./csv-to-topology-geojson.sh targets.csv topology.geojson
 ```

- `update-configs.sh`：根据 targets.csv 生成 `onvif-targets.json`、`ping-targets.json`。
- `csv-to-topology-geojson.sh`：生成 `topology.geojson`，供 Grafana Geomap 加载（设备点 + parent 连线，uplink_type 可区分线型）。
+- `update-configs.sh`：根据 targets.csv 生成 `target-onvif.json`、`target-ping.json`、`target-topology.geojson`（含设备点与 parent 连线）。

 ---

@@ -61,8 +58,8 @@ chmod +x *.sh

 | 类型 | Job | Exporter | 配置文件 |
 |------|-----|----------|----------|
-| 网络 Ping | network-ping | Blackbox | ping-targets.json |
-| ONVIF | onvif-devices | ONVIF Exporter | onvif-targets.json |
+| 网络 Ping | network-ping | Blackbox | target-ping.json |
+| ONVIF | onvif-devices | ONVIF Exporter | target-onvif.json |
 | 边缘自身 | prometheus-edge | Prometheus | 内置 |

 数据流：目标 → Exporter → prometheus-edge 抓取 → remote_write → 中央 VictoriaMetrics。Grafana 查边缘数据需选 **VictoriaMetrics** 数据源。
--- a/doc/TIANDITU_CONFIG.md
+++ b/doc/TIANDITU_CONFIG.md
@@ -1,23 +1,12 @@
 # 天地图配置说明

-拓扑标注助手使用**天地图**作为地图校验底图，便于在浏览器中点击修正设备经纬度。天地图提供**底图**与**标识图（中文注记）**两个图层，可单独或叠加使用。
+**天地图** 提供**底图**与**标识图（中文注记）**两个图层。**tile-cache** 服务缓存瓦片，供 Grafana Geomap 使用，节省 key 免费量。

-**天地图密钥**：使用瓦片缓存或 Grafana Geomap 时，密钥统一配置在 **central-server/.env** 的 **TIANDITU_TK** 变量中，由 tile-cache 服务读取，不在浏览器或 Grafana 中填写。
+**天地图密钥**：统一配置在 **central-server/.env** 的 **TIANDITU_TK** 变量中，由 tile-cache 服务读取。

 ---

-## 1. 在拓扑标注助手中使用
-
- 打开拓扑标注助手：`http://<中央服务器>:4080`
- 在「地图校验」区域填写 **天地图 TK**（密钥），点击「加载天地图」即可加载底图并点击地图修正坐标。
- TK 会保存在浏览器本地（localStorage），同一设备填一次即可。
- **申请密钥**：登录 [天地图开放平台](https://console.tianditu.gov.cn/) 注册并创建应用，获取 **tk** 参数。
-
-当前前端通过天地图 JavaScript API 加载地图；若需在其它系统（如 Grafana Geomap）中复用天地图，可使用下方 WMTS 地址。
-
---
-
-## 2. 两个图层说明
+## 1. 两个图层说明

 | 图层 | 用途 | 说明 |
 |------|------|------|
@@ -28,7 +17,7 @@

 ---

-## 3. WMTS 地址（底图 + 标识图）
+## 2. WMTS 地址（直连）（底图 + 标识图）

 若在 Grafana、其它 GIS 或自研前端中通过 WMTS 接入天地图，可使用以下地址。请将 `tk=您的密钥` 替换为在 [天地图开放平台](https://console.tianditu.gov.cn/) 申请得到的 **tk**。

@@ -46,48 +35,42 @@ https://t0.tianditu.gov.cn/cva_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0

 - **瓦片参数**：`{z}` 为层级（zoom），`{y}` 为行号，`{x}` 为列号；由地图引擎在请求时替换。
 - **同一密钥**：底图与标识图使用同一个 **tk** 即可。
- **坐标系**：上述为 WGS84（经纬度），与 topology-editor、targets.csv 中 lat/lon 一致。
+- **坐标系**：上述为 WGS84（经纬度），与 targets.csv 中 lat/lon 一致。

 ---

-## 4. 瓦片缓存与手动更新（节省 key 免费量）
+## 3. 瓦片缓存（节省 key 免费量）

 天地图 key 有免费调用量限制。本项目提供 **tile-cache** 服务：瓦片首次请求时向天地图拉取并落盘，后续同一瓦片在**老化时间**内直接读缓存；超过老化时间的瓦片在下次请求时会自动重新拉取。

-### 4.1 启用缓存服务
+### 3.1 启用缓存服务

 - **天地图密钥**：在 **central-server/.env** 中配置 **TIANDITU_TK**（必填，否则缓存服务无法回源）。例如：`TIANDITU_TK=您的天地图密钥`。密钥在 [天地图开放平台](https://console.tianditu.gov.cn/) 申请。
  - **服务器端 403**：瓦片由 tile-cache 容器向天地图发起请求，出口 IP 为服务器公网 IP。若控制台中为该 key 设置了 **IP 白名单**，必须将服务器公网 IP 加入白名单；若只设置了 **Referer 白名单**，服务器请求无 Referer 易被拒，可暂时关闭 Referer 校验或按平台说明配置后再试。
 - **缓存老化时间**（可选）：`TILE_CACHE_TTL_DAYS=7`（默认 7 天）。单个瓦片超过该天数后，下次被请求时会重新向天地图拉取并覆盖缓存。可改为 15 等更大值以延长复用时间。
  - **上游超时**（可选）：向天地图请求单瓦片超时时间，默认 15 秒；若日志中频繁出现 `upstream timeout`，可在 `.env` 中设置 `TILE_CACHE_UPSTREAM_TIMEOUT_MS=25000`（单位毫秒）等更大值后重启 tile-cache。
- 与 central 一起启动时，**tile-cache** 容器会自动启动（端口默认 4090），拓扑标注助手通过内部代理使用 `/tiles` 路径，无需在浏览器暴露 key。
-
-### 4.2 拓扑标注助手中使用缓存
-
- 当 central 已配置 `TILE_CACHE_URL`（默认已指向 tile-cache）时，页面会显示 **「加载天地图（使用服务器缓存）」**：从服务器缓存加载底图 + 标识图，不消耗浏览器端 key。超过 TTL 的瓦片会在下次浏览时自动更新。
-
-### 4.3 主机直连 tile-cache 测试（排查用）
-
- 从**主机**上 curl 测试 tile-cache 时，若使用 `http://localhost:4090` 出现**无响应、无日志**（请求未进容器），多半是系统把 `localhost` 解析到 IPv6 (`::1`)，而 Docker 只把端口映射到 IPv4。请改用 **`http://127.0.0.1:4090`** 再试，例如：  
-  `curl -s http://127.0.0.1:4090/health`、`curl -s http://127.0.0.1:4090/api/cache/status`。  
-  标注助手通过 topology-editor 代理访问 tile-cache，走内网 `tile-cache:4090`，不受此影响。
-
-### 4.4 Grafana Geomap 使用缓存（可选）
+### 3.2 Grafana Geomap 使用缓存

 将 Geomap 的 XYZ 底图/标识图 URL 改为：  
-`http://<central>:4080/tiles/vec/{z}/{x}/{y}` 与 `http://<central>:4080/tiles/cva/{z}/{x}/{y}`（经拓扑助手代理）。天地图密钥已在 **.env** 的 **TIANDITU_TK** 中配置，Grafana 中无需填写。
+`http://<central>:4090/tiles/vec/{z}/{x}/{y}` 与 `http://<central>:4090/tiles/cva/{z}/{x}/{y}`。  
+天地图密钥已在 **.env** 的 **TIANDITU_TK** 中配置，Grafana 中无需填写。

-### 4.5 更新方式
+### 3.3 主机直连 tile-cache 测试（排查用）
+
+从**主机** curl 测试 tile-cache 时，若 `http://localhost:4090` 无响应，可改用 **`http://127.0.0.1:4090`**：  
+`curl -s http://127.0.0.1:4090/health`
+
+### 3.4 更新方式

 超过 `TILE_CACHE_TTL_DAYS` 天的瓦片，在下次被请求时会自动重新向天地图拉取并写回缓存，无需手动操作。

 ---

-## 5. 在 Grafana Geomap 中配置天地图（直连或走缓存）
+## 4. 在 Grafana Geomap 中配置天地图（直连或走缓存）

-Grafana 的 Geomap 支持 **XYZ Tile layer**。可直连天地图 WMTS（URL 中填 tk），或使用瓦片缓存地址（见第 4 节）。
+Grafana 的 Geomap 支持 **XYZ Tile layer**。可直连天地图 WMTS（URL 中填 tk），或使用瓦片缓存（见第 3 节）。

-### 5.1 配置底图（vec_w）
+### 4.1 配置底图（vec_w）

 1. 新建或编辑一个 **Geomap** 面板。
 2. 在右侧 **Layer** / **Base layer** 区域，将底图类型选为 **XYZ Tile layer**（或「自定义」/「Generic XYZ」等，视 Grafana 版本而定）。
@@ -100,7 +83,7 @@ https://t0.tianditu.gov.cn/vec_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0
 4. **Attribution** 可填：`© 天地图`。
 5. 保存面板后即可看到天地图矢量底图。

-### 5.2 叠加标识图（cva_w，中文注记）
+### 4.2 叠加标识图（cva_w，中文注记）

 若需要地名、道路名等中文注记，可在同一 Geomap 上再添加一层 XYZ 瓦片，叠在底图之上：

@@ -115,7 +98,7 @@ https://t0.tianditu.gov.cn/cva_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0
 4. 可将该层的 **Opacity** 设为 1（不透明），这样注记清晰可见。
 5. 图层顺序：底图在下，标识图在上；若顺序反了，可在面板里拖拽调整。

-### 5.3 说明
+### 4.3 说明

 - Grafana 会在请求瓦片时把 URL 中的 `{z}`、`{x}`、`{y}` 替换为当前层级与行列号，与天地图 WMTS 的 `TILEMATRIX` / `TILEROW` / `TILECOL` 一一对应。
 - 底图与标识图使用**同一个 tk** 即可；tk 在 [天地图开放平台](https://console.tianditu.gov.cn/) 申请。
@@ -123,7 +106,7 @@ https://t0.tianditu.gov.cn/cva_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0

 ---

-## 6. 参考
+## 5. 参考

 - [天地图开放平台](https://www.tianditu.gov.cn/)
 - [开发文档 / 服务资源](https://lbs.tianditu.gov.cn/server/MapService.html)