# 使用指南

按**任务**走的操作手册。接口字段速查见 [API.md](./API.md)。

本指南以本机部署为例：

- 服务地址：`http://192.168.1.62:8910`（静态 IP，局域网可达）
- 运维台：`http://127.0.0.1:8910/admin/`（**仅本机**）
- 数据目录：`D:\Code\tile-server\data`（切片在 `tiles\`，矢量在 `geojson\`）

---

## 一、五分钟跑通：拿到第一张图

### 1. 在运维台签发一个令牌

浏览器打开 `http://127.0.0.1:8910/admin/` → **访问令牌** → 签发。

- **底图编码**：填已入库的 code，例如 `gaode-image`
- **有效时长**：留空走默认 30 天
- 勾不勾"允许提交切片任务"，决定这个令牌能不能调切片接口

签完页面顶部会显示**明文令牌**，形如 `bmp_xxxxxxxx`。**只显示这一次**，立刻复制存好。

### 2. 确认底图已入库

运维台 **底图** 页能看到 `gaode-image` / `gaode-shp` / `google-image`，并显示级别范围和格式。

取图模板长这样：

```text
http://192.168.1.62:8910/tiles/gaode-image/current/{z}/{x}/{y}.webp
```

### 3. 取一张验证

```powershell
curl.exe -o 0.webp -w "%{http_code} %{content_type}`n" `
  "http://192.168.1.62:8910/tiles/gaode-image/current/0/0/0.webp?token=<令牌>"
```

返回 `200 image/webp` 就通了。

### 4. 放进地图前端

取图模板本身就是前端要的格式，两种用法：

**Leaflet**

```javascript
const token = 'bmp_xxxxxxxx';
const urlTemplate = 'http://192.168.1.62:8910/tiles/gaode-image/current/{z}/{x}/{y}.webp';

L.tileLayer(urlTemplate + '?token=' + token, {
  tileSize: 256,
  minZoom: 0,
  maxZoom: 13,          // 用底图详情里的 maxZoom
  attribution: '内部底图'
}).addTo(map);
```

**OpenLayers**

```javascript
new ol.layer.Tile({
  source: new ol.source.XYZ({
    url: 'http://192.168.1.62:8910/tiles/gaode-image/current/{z}/{x}/{y}.webp?token=bmp_xxxxxxxx',
    crossOrigin: 'anonymous'
  })
});
```

> 令牌走查询参数（`?token=`）是给地图客户端设计的——`<img>` 和瓦片库没法设请求头。
> 代价是令牌会出现在 URL 里，所以**给前端用的令牌要单独签发、单独设短有效期**，别和管理令牌混用。

### 5. 也可以让程序自己去问目录

不要让前端写死 code，让它先查目录：

```powershell
curl.exe -H "Authorization: Bearer <令牌>" http://192.168.1.62:8910/api/v1/catalog/basemaps
```

返回里每个底图带 `url_template`、`min_zoom`、`max_zoom`、`tile_format`，
前端照着渲染即可。目录会**按令牌授权自动过滤**——没有权限的底图不会出现。

---

## 二、无人机影像：一次次的累加

目标：一个图层 `uav-2026`，飞一次加一次，最终是一张完整的图。

### 准备

1. 运维台 **访问令牌** 签发一个勾了 **"允许提交切片任务"** 的令牌
2. 这个令牌不需要任何底图授权——它只用来提交切片，读不到图

### 第一次飞行

```powershell
$TOKEN = "bmp_xxxxxxxx"

curl.exe -X POST http://127.0.0.1:8910/api/v1/slice/jobs `
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" `
  -d '{"target_code":"uav-2026","source_paths":["D:\\uav\\flight-a.tif"],"zoom_min":0,"zoom_max":18}'
```

返回 `202` 和任务对象，`status` 是 `pending`。

### 几天后又飞了

**同一个 `target_code`，只提交新影像**，就是累加：

```powershell
curl.exe -X POST http://127.0.0.1:8910/api/v1/slice/jobs `
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" `
  -d '{"target_code":"uav-2026","source_paths":["D:\\uav\\flight-b.tif"],"zoom_min":0,"zoom_max":18}'
```

新影像覆盖到哪算哪，之前飞的地方原样保留（命令里带了 `--exclude`，空白瓦片不会落盘，
所以不会把旧影像"挖出洞"）。

### 看进度

```powershell
curl.exe -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8910/api/v1/slice/jobs/<任务id>
```

`status` 走 `pending → running → succeeded / failed`。
失败时 `message` 有原因，完整输出在 `log_path`。

### 什么时候需要"重建"

日常累加是**按瓦片**覆盖的：如果两次飞行在**同一张 256px 瓦片内**有重叠，
整块瓦片会来自较新的那次，可能出现瓦片边界的可见接缝。

**重叠很小的话不用管。** 真觉得有接缝时，做一次镶嵌重建：

运维台 → **影像切片** → 图层源清单 → 点该图层的 **「重建为镶嵌」**。

它会自动读出这个图层记录的全部源影像、沿用当前已发布的级别范围，
先 `gdalbuildvrt` 拼成一张虚拟栅格再切，重叠区**逐像素**合成，没有接缝。

### 图层现在由哪些影像构成

```powershell
curl.exe -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8910/api/v1/slice/layers/uav-2026/sources
```

运维台同一页也有这张清单。

### 两个注意点

- **`target_code` 必须是英文数字**（如 `uav-2026`）。中文会被归一化掉导致报错。
  想显示"2026无人机影像"，由**你的前端自己映射** code → 中文名。
- 切片是**单并发**的，按提交顺序执行。一次提交多个图层要排队，但不会阻塞接口。

---

## 三、给下游系统对接

### 方式一：下游主动拉（推荐）

下游拿一个令牌，调目录 → 拿 `url_template` → 自己取图。

```powershell
curl.exe -H "Authorization: Bearer <令牌>" http://192.168.1.62:8910/api/v1/catalog/basemaps
```

好处：地址由服务方维护，换 IP / 加图层下游不用改代码。

### 方式二：服务方推送描述

在运维台 **推送** 页配好目标系统（回调地址 + 可选请求头），
资源更新时把描述推给下游，下游收到后再自己来拉。

- 推送是**异步**的，提交后先返回 `pending`
- 失败自动重试（30s、60s），状态在推送记录里看
- 失败记录可以点 **重推**

### 切片完成回调

提交切片任务时带上 `callback_url`：

```json
{"target_code":"uav-2026","source_paths":["D:\\uav\\b.tif"],"callback_url":"http://portal-a/api/tile-jobs/done"}
```

任务结束时服务会 POST：

```json
{"event":"tile.job.finished","job":{ ...任务对象... }}
```

失败同样自动退避重试。

---

## 四、常见问题速查

| 现象 | 原因 | 怎么办 |
|---|---|---|
| `401 invalid token` | 令牌错、过期或被停用 | 运维台令牌页看状态；重新签发 |
| `403 token has no access` | 令牌有效但没授权这个底图 | 用有该底图授权的令牌，或重新签发 |
| `403 admin endpoints are loopback-only` | 从别的机器调了管理接口 | 管理接口只能在本机调；远程请用业务令牌走 `/api/v1/catalog`、`/tiles` |
| `403 ... slice scope` | 令牌没勾"允许提交切片任务" | 重新签发并勾上 |
| `404` 取图 | 该 z/x/y 没切出来，或资源已下线 | 运维台 **底图** 页看该版本的"在位/文件缺失"标记 |
| 取图地址里是 `127.0.0.1` | 改过 base URL 但没重扫 | 运维台点 **立即扫描**，模板是扫描时生成的 |
| 切片任务 `failed` | 源影像路径不对、不是栅格、GDAL 报错 | 看任务的 `message` 和 `log_path` |
| 页面打不开 | 在别的机器访问了 `/admin/` | 管理台仅本机；远程只能调业务接口 |
| 别的网段访问不通 | 路由器没有两个网段之间的路由 | 找网络管理员加路由 |

---

## 五、日常运维

运维台各页对应的动作：

| 页面 | 用途 |
|---|---|
| **总览** | 待处理事项（失败的扫描/推送、缺失的资源）+ 实时指标 |
| **底图** | 台账、默认版本、取图模板、**就地验真**（粘贴令牌试拉一张） |
| **矢量** | 矢量资源与下载地址，同样可验真 |
| **令牌** | 签发 / 停用，查看授权范围与最近使用时间 |
| **推送** | 目标系统、推送记录、失败重推 |
| **扫描** | 扫描源、立即扫描、扫描历史 |
| **影像切片** | 提交切片、任务列表、图层源清单与重建 |
| **服务** | 版本、对外地址、探针与指标入口 |

**故障排查第一站是日志**：

```powershell
Get-Content D:\Code\tile-server\bin\logs\basemap-pusher.log -Tail 50
```

访问日志每行形如 `GET /tiles/xxx/... 200 320B 2ms`，令牌已脱敏成 `***`。

**服务管理**（`install/uninstall/start/stop` 需管理员）：

```powershell
scripts\service.bat status
scripts\service.bat restart
```