# 天地图配置说明

**天地图** 提供**底图**与**标识图（中文注记）**两个图层。**tile-cache** 服务缓存瓦片，供 Grafana Geomap 使用，节省 key 免费量。

**天地图密钥**：统一配置在 **central-server/.env** 的 **TIANDITU_TK** 变量中，由 tile-cache 服务读取。

---

## 1. 两个图层说明

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

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

---

## 2. 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（经纬度），与 targets.csv 中 lat/lon 一致。

---

## 3. 瓦片缓存（节省 key 免费量）

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

### 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。
### 3.2 Grafana Geomap 使用缓存

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

### 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` 天的瓦片，在下次被请求时会自动重新向天地图拉取并写回缓存，无需手动操作。

---

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

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

### 4.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. 保存面板后即可看到天地图矢量底图。

### 4.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. 图层顺序：底图在下，标识图在上；若顺序反了，可在面板里拖拽调整。

### 4.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)）。

---

## 5. 参考

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