【TileServer GL】TileServer GL官方文档翻译

官方文档：
maptiler-tileserver: https://maptiler-tileserver.readthedocs.io/en/latest/index.html
TileServer GL: https://tileserver.readthedocs.io/en/latest/index.html

TileServer GL 说明

1 安装
- Docker
- npm
- - 使用npm.js全局安装
  - 从源代码本地安装
  - 本机依赖项
- `tileserver-gl-light on npm`
2 用法
3 配置文件
- `options`
- - `paths`
  - `domains`
  - `frontPage`
  - `formatQuality`
  - `maxScaleFactor`
  - `maxSize`
  - `tileMargin`
  - `minRendererPoolSizes`
  - `maxRendererPoolSizes`
  - `serveAllStyles`
  - `watermark`
- `styles`
- `data`
- 从 JSON 样式引用本地文件
- - MBTiles
  - PMTiles
  - `Sprites`
  - `Fonts (glyphs)`
4 部署
- 缓存
- - Cloudflare 缓存规则
  - Nginx 缓存
- 安全
- 在代理或负载均衡器后面运行
5 可用端点
- Styles
- 渲染瓦片
- WMTS 功能
- 静态图像
- 源数据
- TileJSON 数组
- 可用字体列表
- 健康检查

1 安装

Docker

运行 docker 镜像时，无需特殊安装 - 如果镜像不存在，docker 会自动下载。
docker run --rm -it -v $(pwd):/data -p 8080:80 maptiler/tileserver-gl
其他选项（请参阅用法）可以通过将其附加到此命令的末尾来传递到 TileServer GL。例如，您可以执行以下操作：

docker run ... maptiler/tileserver-gl --mbtiles my-tiles.mbtiles– 明确指定要使用的 mbtiles（如果文件夹中有更多）
docker run ... maptiler/tileserver-gl --verbose– 查看自动创建的默认配置

npm

安装了本机依赖项的以下平台支持 npm 。

操作系统：
- Ubuntu 22.04（x64/arm64）
- macOS 12 (x64/arm64)
- Windows (x64)
Node.js 18,20

使用npm.js全局安装

npm install -g tileserver-gl

从源代码本地安装

git clone https://github.com/maptiler/tileserver-gl.git
cd tileserver-gl
npm install
node

本机依赖项

如果您计划在不使用 Docker 的情况下本机运行 TileServer GL，则需要确保安装一些本机依赖项。您需要安装的确切包名称在不同平台上可能有所不同。
Debian 11 需要这些：

libgles2-mesa
libegl1
xvfb
xauth
libopengl0
libcurl4
curl
libuv1-dev
libc6-dev
http://archive.ubuntu.com/ubuntu/pool/main/libj/libjpeg-turbo/libjpeg-turbo8_2.0.3-0ubuntu1_amd64.deb
http://archive.ubuntu.com/ubuntu/pool/main/i/icu/libicu66_66.1-2ubuntu2_amd64.deb

Ubuntu 20.04 需要这些：

libcairo2-dev
libjpeg8-dev
libpango1.0-dev
libgif-dev
build-essential
g++
xvfb
libgles2-mesa-dev
libgbm-dev
libxxf86vm-dev

MacOS 12 (x64/arm64)¶

brew install pkg-config cairo libpng jpeg giflib

Windows (x64)

Microsoft Visual C++ 2015-2022 Redistributable

`tileserver-gl-light on npm`

或者，您可以使用tileserver-gl-light包，它是纯 JavaScript（没有任何本机依赖项）并且可以在任何地方运行，但不包含栅格化要素切片。

2 用法

Usage: main.js tileserver-gl [file] [options]

Options:
  --file <file>             MBTiles or PMTiles file
                              ignored if the configuration file is also specified
  --mbtiles <file>          (DEPRECIATED) MBTiles file
                              ignored if file is also specified
                              ignored if the configuration file is also specified
  -c, --config <file>       Configuration file [config.json] (default: "config.json")
  -b, --bind <address>      Bind address
  -p, --port <port>         Port [8080] (default: 8080)
  -C|--no-cors              Disable Cross-origin resource sharing headers
  -u|--public_url <url>     Enable exposing the server on subpaths, not necessarily the root of the domain
  -V, --verbose             More verbose output
  -s, --silent              Less verbose output
  -l|--log_file <file>      output log file (defaults to standard out)
  -f|--log_format <format>  define the log format:  https://github.com/expressjs/morgan#morganformat-options
  -v, --version             output the version number
  -h, --help                display help for command

默认预览样式和配置:

如果未指定配置文件，则使用默认预览样式（与 openmaptiles 兼容）。
如果未指定数据文件（并且在当前工作目录中未找到），则下载示例文件（显示苏黎世区域 Zurich area）

重新加载配置:

通过向节点进程发送 SIGHUP 信号，可以重新加载配置文件，而无需重新启动整个进程。

运行tileserver-gl docker容器时，可以使用docker kill -s HUP tileserver-gl命令。
当tileserver -gl作为docker-compose服务运行时，可以使用docker-compose Kill -s HUPtileserver-gl-service-name 。

Docker 和–port
在 Docker 容器中运行tileserver-gl 时，使用–port选项会使容器错误地显得不健康。相反，建议使用 Docker 的端口映射并将默认端口 8080 映射到所需的外部端口。

3 配置文件

配置文件定义应用程序的行为。这是一个常规的 JSON 文件。
例子：

{
  "options": {
    "paths": {
      "root": "",
      "fonts": "fonts",
      "sprites": "sprites",
      "styles": "styles",
      "mbtiles": ""
    },
    "domains": [
      "localhost:8080",
      "127.0.0.1:8080"
    ],
    "formatQuality": {
      "jpeg": 80,
      "webp": 90
    },
    "maxScaleFactor": 3,
    "maxSize": 2048,
    "pbfAlias": "pbf",
    "serveAllFonts": false,
    "serveAllStyles": false,
    "serveStaticMaps": true,
    "tileMargin": 0
  },
  "styles": {
    "basic": {
      "style": "basic.json",
      "tilejson": {
        "type": "overlay",
        "bounds": [8.44806, 47.32023, 8.62537, 47.43468]
      }
    },
    "hybrid": {
      "style": "satellite-hybrid.json",
      "serve_rendered": false,
      "tilejson": {
        "format": "webp"
      }
    }
  },
  "data": {
    "zurich-vector": {
      "mbtiles": "zurich.mbtiles"
    }
  }
}

`options`

`paths`

定义在哪里查找不同类型的输入数据。

root的值用作所有数据类型的前缀。

`domains`

您可以使用它来选择指定在哪些域上可以访问渲染的图块。这可用于基本负载平衡或绕过浏览器对每个域的连接数的限制。

`frontPage`

root用作首页的html 路径（相对于路径）。

使用true(或不使用）为默认的 TileServer GL 首页提供样式和数据列表。用于false完全禁用首页 (404)。

`formatQuality`

各个图像格式的压缩质量。[0-100]

`maxScaleFactor`

允许栅格图块和静态地图请求的最大比例因子（例如@3x后缀）。另请参阅maxSize下文。默认值为3最大值9。

`maxSize`

允许渲染的最大图像边长（包括比例因子）。更改此值时要小心，因为需要考虑硬件限制。默认为2048 。

`tileMargin`

在图块渲染期间添加的附加图像边长是从提供的图块中裁剪出来的。这对于解决裁剪标签的问题很有用，但它确实会降低性能，因为需要加载额外的相邻矢量切片来生成单个切片。默认是0禁用此处理。

`minRendererPoolSizes`

每个比例因子的栅格图块渲染器的最小数量。该值是一个数组：第一个元素是比例因子一的最小渲染器数量，第二个元素是比例因子二的渲染器的最小数量，依此类推。如果数组的元素少于maxScaleFactor，则最后一个元素也用于所有剩余的比例因子。选择渲染器池大小是内存使用和速度之间的权衡。合理的值取决于您的硬件以及样式数量和比例因子。如果您有足够的内存，您需要将其设置为等于maxRendererPoolSizes以避免由于渲染器破坏和重新创建而增加延迟。如果您需要节省内存，则需要低于的值maxRendererPoolSizes，可能会为更常见的比例因子分配更多渲染器。默认为[8, 4, 2]

`maxRendererPoolSizes`

每个比例因子的栅格切片渲染器的最大数量。价值和考虑因素与上面类似minRendererPoolSizes。如果您有足够的内存，请尝试将这些值设置为等于或略高于您的处理器数量，例如，如果您有四个处理器，请尝试将值设置为[6]。如果需要节省内存，请尝试使用较低的不太常见的比例因子值。默认为.[16, 8, 4]

`serveAllStyles`

paths.styles如果启用此选项，将提供所有样式。（没有递归，仅.json使用文件。）该过程还将监视此目录中的更改并动态删除/添加更多样式。建议serveAllFonts在使用该选项时也使用该选项。

`watermark`

要作为水印（左下角）渲染到栅格图块（和静态地图）中的可选字符串。可用于硬编码属性等（也可以按样式指定）。默认情况下不使用。

`styles`

该对象中的每一项都定义一种样式（地图）。它可以有以下选项：

style– 样式 json 文件的名称 [必需]
serve_rendered– 是否渲染此样式的栅格瓦片
serve_data– 是否允许访问原始图块、精灵和所需的字形
tilejson– 添加到为栅格数据创建的 TileJSON 的属性
- format和bounds有特别用处

`data`

每一项指定一个应由服务器访问的数据源。它必须具有以下选项之一：：

mbtiles– mbtiles 文件的名称
pmtiles– pmtiles 文件或 url 的名称。

除非您明确想要提供原始数据，否则不需要在此处指定 mbtiles 文件。

例如：

"data": {
  "source1": {
    "mbtiles": "source1.mbtiles"
  },
  "source2": {
    "pmtiles": "source2.pmtiles"
  },
  "source3": {
    "pmtiles": "https://foo.lan/source3.pmtiles"
  }
}

从 JSON 样式引用本地文件

您可以从 JSON 样式链接各种数据源（例如甚至远程 TileJSON）。

MBTiles

要指定您要使用本地 mbtile，请使用以下语法：mbtiles://switzerland.mbtiles。switzerland.mbtilesTileServer-GL 将尝试在root+路径中查找文件mbtiles。

例如：

"sources": {
  "source1": {
    "url": "mbtiles://switzerland.mbtiles",
    "type": "vector"
  }
}

或者，您可以使用mbtiles://{zurich-vector}从配置引用现有数据对象。在这种情况下，服务器将查看config.json以确定使用哪个 mbtiles 文件。对于上面的配置，这相当于mbtiles://zurich.mbtiles.

PMTiles

要指定您要使用本地 pmtile，请使用以下语法：pmtiles://source2.pmtiles。source2.pmtilesTileServer-GL 将尝试在root+路径中查找文件pmtiles。

要指定您要使用基于 url 的 pmtile，请使用以下语法：pmtiles://https://foo.lan/source3.pmtiles。

例如：

"sources": {
  "source2": {
    "url": "pmtiles://source2.pmtiles",
    "type": "vector"
  },
  "source3": {
    "url": "pmtiles://https://foo.lan/source3.pmtiles",
    "type": "vector"
  },
}

或者，您可以使用pmtiles://{source2}从配置引用现有数据对象。在这种情况下，服务器将config.json通过数据 ID 来查看以确定要使用哪个文件。对于上面的配置，这相当于pmtiles://source2.mbtiles.

`Sprites`

如果您的样式需要任何精灵图，请确保样式 JSON 在属性中包含正确的路径sprite。

它可以是本地路径（例如my-style/sprite）或远程 http(s) 位置（例如https://mycdn.com/my-style/sprite）。此路径中添加了几个可能的扩展名，因此应存在以下文件：

sprite.json
sprite.png
sprite@2x.json
sprite@2x.png

您还可以在精灵图路径中使用以下占位符以方便使用：

{style}– 替换为样式文件的名称 ( xxx.json)
{styleJsonFolder}– 替换为样式文件的路径

`Fonts (glyphs)`

与精灵图类似，样式 JSON 也需要包含字体字形的正确路径（在属性中glyphs），并且可以是本地的和远程的。
它应包含以下占位符：

{fontstack}– 字体和变体的名称
{range}– 字形的范围

例如，"glyphs": "{fontstack}/{range}.pbf" 将指示TileServer GL查找字体 fonts/Open Sans/0-255.pbf等文件（fonts 来自上面config.json示例的path属性）。

4 部署

通常 - 您应该在前端使用 nginx/lighttpd/apache - 并且tileserver-gl 服务器在生产部署中隐藏在其后面。

缓存

您可以使用很多选项来创建适当的缓存基础设施：Varnish、CloudFlare……

Cloudflare 缓存规则

Cloudflare 支持用于配置缓存的自定义规则： https://developers.cloudflare.com/cache/about/cache-rules/
tileserver-gl 以多种格式渲染图块 - 渲染栅格数据的格式有.png、.jpg (jpeg)、.webp，对于矢量数据有.pbf格式。另外，生成.json格式的样式信息。

端点数据可以由 Cloudflare 配置生成缓存。例如，要缓存矢量端点，您需要为数据配置 Cloudflare.pbf规则和.json数据。

创建匹配hostname (equal)和URI Path (ends with)的.pbf和.json字段的规则。将缓存状态设置为可缓存以启用缓存，并将Edge TTL 覆盖为 Browser TTL7天（取决于您的应用程序使用情况）。

这将确保您的瓦片在客户端和 Cloudflare 缓存 7 天。如果瓦片服务器关闭或用户无法访问互联网，它将尝试使用缓存的瓦片。

请注意，Browser TTL将覆盖客户端设备上的过期日期。如果您重建地图，旧的瓦片将一直呈现，直到其过期或被客户端设备上的缓存清除。

Nginx 缓存

如果您在tileserver前面设置了反向代理，您可能需要启用缓存，因为它将大大减轻应用程序的请求。
配置代理缓存路径指令来初始化缓存存储：

proxy_cache_path /var/cache/nginx/tileserver
                 keys_zone=TileserverCache:50m
                 levels=1:2
                 inactive=2w
                 max_size=10g;

确保为 /var/cache/nginx/tileserver 文件夹授予适当的权限。通常 nginx 使用 www-data 用户运行。在特定代理通道上启用缓存：

location / {
  include proxy_params;
  proxy_pass http://127.0.0.1:8080/;

  proxy_cache TileserverCache;
  proxy_cache_valid 200 1w;

  # add_header X-Cache-Status $upstream_cache_status;
}

如果您需要确认缓存是否有效，请取消注释 X-Cache-Status 标头。这将返回带有HIT或MISS标头值的响应标头，该标头值指示 nginx 是否缓存了响应。
更改样式或图块信息后，请确保通过删除配置目录中的文件来清理缓存。您可以尝试使用缓存值来满足您的需求。
有关 Nginx 缓存的更多信息：https://docs.nginx.com/nginx/admin-guide/content-cache/content-caching/

安全

Nginx 可用于通过 https、密码、引用者、IP 地址限制、访问密钥等添加保护。

在代理或负载均衡器后面运行

如果您需要在代理后面运行 TileServer GL，请确保代理将X-Forwarded-*标头发送到服务器（最重要的是X-Forwarded-Host和X-Forwarded-Proto），以确保 TileJSON 等内部生成的 URL 使用所需的域和协议。

5 可用端点

如果您通过配置的端口（默认 8080）访问服务器，您可以看到您的地图出现在浏览器中。

Styles

样式位于/styles/{id}/style.json(+ array at /styles.json)
- 精灵图位于/styles/{id}/sprite[@2x].{format}
- 字体样式位于/fonts/{fontstack}/{start}-{end}.pbf

渲染瓦片

渲染后的瓦片供应于/styles/{id}/{z}/{x}/{y}[@2x].{format}
- 可选@2x（或@3x, @4x）部分可用于渲染 HiDPI（视网膜）瓦片
- 可用格式：png, jpg( jpeg),webp
- TileJSON 位于/styles/{id}.json
渲染的图块在该tileserver-gl-light版本中不可用。

WMTS 功能

WMTS 功能的服务地点为/styles/{id}/wmts.xml

静态图像

几个端点：
- /styles/{id}/static/{lon},{lat},{zoom}[@{bearing}[,{pitch}]]/{width}x{height}[@2x].{format}（以中心为基础）
- /styles/{id}/static/{minx},{miny},{maxx},{maxy}/{width}x{height}[@2x].{format}（基于区域）
- /styles/{id}/static/auto/{width}x{height}[@2x].{format}（自动调整路径 - 见下文）
所有静态图像端点还支持以下查询参数：
- path - 逗号分隔lng,lat管道分隔对
  - 例如5.9,45.8|5.9,47.8|10.5,47.8|10.5,45.8|5.9,45.8
- latlng- 表示path坐标是lat,lng有序的，而不是通常的lng,lat
- fill- 用作填充的颜色（例如red, rgba(255,255,255,0.5), #0000ff）
- stroke- 路径描边的颜色
- width- 笔画的宽度
- padding- 拟合端点的“百分比”填充（基于区域和路径自动拟合）
  - 值0.1意味着“向每边添加 10% 的大小，以确保感兴趣的区域清晰可见”
您还可以使用/styles/{id}/static/raw/...具有原始球面墨卡托坐标 (EPSG:3857) 的（实验）端点，而不是 WGS84。
该tileserver-gl-light版本不提供静态图像。