feat: 天地图瓦片缓存(tile-cache)、拓扑标注助手与文档更新

- 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>

central-server/CONFIGURATION.md

@@ -62,6 +62,8 @@
 - 生产环境必须修改 `GRAFANA_ADMIN_PASSWORD`
 - 建议使用强密码（至少12位，包含大小写字母、数字和特殊字符）
 
+**Geomap 使用天地图缓存**：若在 Grafana 的 Geomap 面板中要用天地图底图且走缓存（不暴露 key），可将 Base layer 设为 XYZ Tile layer，底图 URL：`http://<本机或 central>:4080/tiles/vec/{z}/{x}/{y}`，再添加一层：`http://<本机或 central>:4080/tiles/cva/{z}/{x}/{y}`。需在 central 配置 `TIANDITU_TK` 与 tile-cache。详见 [../doc/TIANDITU_CONFIG.md](../doc/TIANDITU_CONFIG.md)。
+
 ### Prometheus 配置
 
 | 参数 | 默认值 | 说明 |
@@ -102,6 +104,17 @@
 - 保留时间越长，占用存储空间越大
 - 建议根据实际存储容量和需求设置
 
+### 天地图 / 瓦片缓存配置
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `TIANDITU_TK` | （空） | **天地图密钥**，配置到 `.env` 中。启用后 tile-cache、拓扑助手「使用服务器缓存」及 Grafana Geomap 使用天地图底图时均使用此密钥，无需在浏览器或 Grafana 中填写。在 [天地图开放平台](https://console.tianditu.gov.cn/) 申请。 |
+| `TILE_CACHE_PORT` | 4090 | 瓦片缓存服务端口 |
+| `TILE_CACHE_DATA_DIR` | ./data/tile-cache | 瓦片缓存数据目录 |
+| `TILE_CACHE_TTL_DAYS` | 7 | 缓存老化时间（天），超过后该瓦片下次请求时重新向天地图拉取；可改为 15 等 |
+
+**说明**：以上参数均在 **central-server/.env** 中配置；部署时由 docker-compose 传入 tile-cache 容器。
+
 ### 数据存储路径配置
 
 | 参数 | 默认值 | 说明 |
@@ -368,5 +381,4 @@ cp env.example .env
 
 - [中央服务器架构说明](../doc/ARCHITECTURE.md)
 - [部署指南](../doc/DEPLOYMENT_GUIDE.md)
-- [告警规则说明](../doc/ALERT_RULES_EXPLANATION.md)
-- [Alertmanager 配置说明](../doc/ALERTMANAGER_CONFIG.md)
+- [告警与通知](../doc/ALERTING.md)

central-server/docker-compose.yml

@@ -82,6 +82,41 @@ services:
       - "--retentionPeriod=${VICTORIAMETRICS_RETENTION_PERIOD:-30d}"
       - "--httpListenAddr=:${VICTORIAMETRICS_PORT:-8428}"
 
+  # 拓扑标注助手（上传/下载 targets.csv，H5 采集 GPS + 天地图校验）
+  topology-editor:
+    build:
+      context: ..
+      dockerfile: topology-editor/Dockerfile
+    image: topology-editor:local
+    container_name: topology-editor
+    restart: unless-stopped
+    environment:
+      - PORT=4080
+      - TILE_CACHE_URL=http://tile-cache:4090
+    ports:
+      - "${TOPOLOGY_EDITOR_PORT:-4080}:4080"
+    mem_limit: "128m"
+
+  # 天地图瓦片缓存（节省 key 免费量；可手动清空缓存后重新拉取）
+  tile-cache:
+    build:
+      context: ..
+      dockerfile: tile-cache/Dockerfile
+    image: tile-cache:local
+    container_name: tile-cache
+    restart: unless-stopped
+    environment:
+      - PORT=4090
+      - TIANDITU_TK=${TIANDITU_TK:-}
+      - CACHE_DIR=/cache
+      - CACHE_TTL_DAYS=${TILE_CACHE_TTL_DAYS:-7}
+      - UPSTREAM_TIMEOUT_MS=${TILE_CACHE_UPSTREAM_TIMEOUT_MS:-15000}
+    volumes:
+      - ${TILE_CACHE_DATA_DIR:-./data/tile-cache}:/cache
+    ports:
+      - "${TILE_CACHE_PORT:-4090}:4090"
+    mem_limit: "128m"
+
 
 # 定义网络配置（默认使用已存在的 traefik 网络）
 networks:

central-server/env.example

@@ -78,6 +78,16 @@ GRAFANA_DATA_DIR=./data/grafana-data
 # VictoriaMetrics 数据目录
 VICTORIAMETRICS_DATA_DIR=./data/victoria-metrics-data
 
+# 天地图瓦片缓存（密钥与缓存参数均在 .env 中配置）
+# 在 .env 中设置 TIANDITU_TK 后，tile-cache 与拓扑助手「使用服务器缓存」、Grafana Geomap 方可使用天地图
+# 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 反向代理配置
 # ============================================