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.8 KiB
天地图配置说明
拓扑标注助手使用天地图作为地图校验底图，便于在浏览器中点击修正设备经纬度。天地图提供底图与**标识图（中文注记）**两个图层，可单独或叠加使用。
天地图密钥：使用瓦片缓存或 Grafana Geomap 时，密钥统一配置在 central-server/.env 的 TIANDITU_TK 变量中，由 tile-cache 服务读取，不在浏览器或 Grafana 中填写。
1. 在拓扑标注助手中使用
- 打开拓扑标注助手：
http://<中央服务器>:4080 - 在「地图校验」区域填写 天地图 TK（密钥），点击「加载天地图」即可加载底图并点击地图修正坐标。
- TK 会保存在浏览器本地（localStorage），同一设备填一次即可。
- 申请密钥：登录 天地图开放平台 注册并创建应用，获取 tk 参数。
当前前端通过天地图 JavaScript API 加载地图；若需在其它系统（如 Grafana Geomap）中复用天地图，可使用下方 WMTS 地址。
2. 两个图层说明
| 图层 | 用途 | 说明 |
|---|---|---|
| 底图 (vec_w) | 矢量底图 | 道路、建筑、水系等底图，WGS84 经纬度 |
| 标识图 (cva_w) | 中文注记 | 地名、道路名等文字标注，叠加在底图之上 |
二者叠加后即「带中文注记的天地图」；仅做点位校验时只用底图即可，需要地名时可叠加标识图。
3. WMTS 地址（底图 + 标识图）
若在 Grafana、其它 GIS 或自研前端中通过 WMTS 接入天地图，可使用以下地址。请将 tk=您的密钥 替换为在 天地图开放平台 申请得到的 tk。
底图（矢量）：
https://t0.tianditu.gov.cn/vec_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=vec&STYLE=default&TILEMATRIXSET=w&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&FORMAT=tiles&tk=您的密钥
标识图（中文注记）：
https://t0.tianditu.gov.cn/cva_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=cva&STYLE=default&TILEMATRIXSET=w&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&FORMAT=tiles&tk=您的密钥
- 瓦片参数：
{z}为层级（zoom），{y}为行号，{x}为列号；由地图引擎在请求时替换。 - 同一密钥：底图与标识图使用同一个 tk 即可。
- 坐标系：上述为 WGS84（经纬度），与 topology-editor、targets.csv 中 lat/lon 一致。
4. 瓦片缓存与手动更新（节省 key 免费量）
天地图 key 有免费调用量限制。本项目提供 tile-cache 服务：瓦片首次请求时向天地图拉取并落盘，后续同一瓦片在老化时间内直接读缓存；超过老化时间的瓦片在下次请求时会自动重新拉取。
4.1 启用缓存服务
- 天地图密钥：在 central-server/.env 中配置 TIANDITU_TK（必填，否则缓存服务无法回源）。例如：
TIANDITU_TK=您的天地图密钥。密钥在 天地图开放平台 申请。- 服务器端 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。
- 上游超时（可选）：向天地图请求单瓦片超时时间，默认 15 秒；若日志中频繁出现
- 与 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 使用缓存（可选）
将 Geomap 的 XYZ 底图/标识图 URL 改为：
http://<central>:4080/tiles/vec/{z}/{x}/{y} 与 http://<central>:4080/tiles/cva/{z}/{x}/{y}（经拓扑助手代理）。天地图密钥已在 .env 的 TIANDITU_TK 中配置，Grafana 中无需填写。
4.5 更新方式
超过 TILE_CACHE_TTL_DAYS 天的瓦片，在下次被请求时会自动重新向天地图拉取并写回缓存，无需手动操作。
5. 在 Grafana Geomap 中配置天地图（直连或走缓存）
Grafana 的 Geomap 支持 XYZ Tile layer。可直连天地图 WMTS（URL 中填 tk），或使用瓦片缓存地址（见第 4 节）。
5.1 配置底图（vec_w）
- 新建或编辑一个 Geomap 面板。
- 在右侧 Layer / Base layer 区域，将底图类型选为 XYZ Tile layer（或「自定义」/「Generic XYZ」等，视 Grafana 版本而定）。
- URL template 中填入天地图矢量底图地址（将
您的密钥换成实际 tk）：
https://t0.tianditu.gov.cn/vec_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=vec&STYLE=default&TILEMATRIXSET=w&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&FORMAT=tiles&tk=您的密钥
- Attribution 可填：
© 天地图。 - 保存面板后即可看到天地图矢量底图。
5.2 叠加标识图（cva_w，中文注记）
若需要地名、道路名等中文注记，可在同一 Geomap 上再添加一层 XYZ 瓦片，叠在底图之上：
- 在 Geomap 面板的 Map layers 中点击 Add layer。
- 选择 XYZ Tile layer。
- URL template 填入标识图地址（同一 tk）：
https://t0.tianditu.gov.cn/cva_w/wmts?SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&LAYER=cva&STYLE=default&TILEMATRIXSET=w&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&FORMAT=tiles&tk=您的密钥
- 可将该层的 Opacity 设为 1（不透明），这样注记清晰可见。
- 图层顺序：底图在下，标识图在上；若顺序反了，可在面板里拖拽调整。
5.3 说明
- Grafana 会在请求瓦片时把 URL 中的
{z}、{x}、{y}替换为当前层级与行列号，与天地图 WMTS 的TILEMATRIX/TILEROW/TILECOL一一对应。 - 底图与标识图使用同一个 tk 即可；tk 在 天地图开放平台 申请。
- 若希望所有 Geomap 默认使用天地图，可在 Grafana 的 provisioning 或
default_baselayer_config中配置 type 为xyz、url 为上述 vec_w 地址（详见 Grafana 文档 - Configure the default base layer）。