# 天地图配置说明

拓扑标注助手使用**天地图**作为地图校验底图，便于在浏览器中点击修正设备经纬度。天地图提供**底图**与**标识图（中文注记）**两个图层，可单独或叠加使用。

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

---

## 1. 在拓扑标注助手中使用

- 打开拓扑标注助手：`http://<中央服务器>:4080`
- 在「地图校验」区域填写 **天地图 TK**（密钥），点击「加载天地图」即可加载底图并点击地图修正坐标。
- TK 会保存在浏览器本地（localStorage），同一设备填一次即可。
- **申请密钥**：登录 [天地图开放平台](https://console.tianditu.gov.cn/) 注册并创建应用，获取 **tk** 参数。

当前前端通过天地图 JavaScript API 加载地图；若需在其它系统（如 Grafana Geomap）中复用天地图，可使用下方 WMTS 地址。

---

## 2. 两个图层说明

| 图层 | 用途 | 说明 |
|------|------|------|
| **底图 (vec_w)** | 矢量底图 | 道路、建筑、水系等底图，WGS84 经纬度 |
| **标识图 (cva_w)** | 中文注记 | 地名、道路名等文字标注，叠加在底图之上 |

二者叠加后即「带中文注记的天地图」；仅做点位校验时只用底图即可，需要地名时可叠加标识图。

---

## 3. WMTS 地址（底图 + 标识图）

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

**底图（矢量）：**

```text
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=您的密钥
```

**标识图（中文注记）：**

```text
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=您的天地图密钥`。密钥在 [天地图开放平台](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 使用缓存（可选）

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

1. 新建或编辑一个 **Geomap** 面板。
2. 在右侧 **Layer** / **Base layer** 区域，将底图类型选为 **XYZ Tile layer**（或「自定义」/「Generic XYZ」等，视 Grafana 版本而定）。
3. **URL template** 中填入天地图矢量底图地址（将 `您的密钥` 换成实际 tk）：

```text
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=您的密钥
```

4. **Attribution** 可填：`© 天地图`。
5. 保存面板后即可看到天地图矢量底图。

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

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

1. 在 Geomap 面板的 **Map layers** 中点击 **Add layer**。
2. 选择 **XYZ Tile layer**。
3. **URL template** 填入标识图地址（同一 tk）：

```text
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=您的密钥
```

4. 可将该层的 **Opacity** 设为 1（不透明），这样注记清晰可见。
5. 图层顺序：底图在下，标识图在上；若顺序反了，可在面板里拖拽调整。

### 5.3 说明

- Grafana 会在请求瓦片时把 URL 中的 `{z}`、`{x}`、`{y}` 替换为当前层级与行列号，与天地图 WMTS 的 `TILEMATRIX` / `TILEROW` / `TILECOL` 一一对应。
- 底图与标识图使用**同一个 tk** 即可；tk 在 [天地图开放平台](https://console.tianditu.gov.cn/) 申请。
- 若希望所有 Geomap 默认使用天地图，可在 Grafana 的 provisioning 或 `default_baselayer_config` 中配置 type 为 `xyz`、url 为上述 vec_w 地址（详见 [Grafana 文档 - Configure the default base layer](https://grafana.com/docs/grafana/latest/panels-visualizations/visualizations/geomap/#configure-the-default-base-layer-with-provisioning)）。

---

## 6. 参考

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