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

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 fileignored if the configuration file is also specified--mbtiles <file>          (DEPRECIATED) MBTiles fileignored if file is also specifiedignored 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/tileserverkeys_zone=TileserverCache:50mlevels=1:2inactive=2wmax_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版本不提供静态图像。

源数据

• 源数据服务路径/data/{mbtiles}/{z}/{x}/{y}.{format}
  • 格式取决于源文件（通常png或pbf）
    • 如果原始格式是pbf，那么也可以获取 geojson 格式（对于检查瓦片很有用）
  • TileJSON 位于/data/{id}.json

TileJSON 数组

所有 TileJSON 的数组位于[/{tileSize}]/index.json ([/{tileSize}]/rendered.json; /data.json)

• 可选瓦片大小/{tileSize｝（例如/256、/512）。如果省略，tileSize默认为256。

可用字体列表

可用字体名称的数组位于/fonts.json

健康检查

报告健康状态的端点/health当前返回：

• 503启动 - 在一切初始化之前的一小段时间
• 200OK - 当服务器运行时