consbio/mbtileserver

mbtileserver

基于Go的轻量级服务器，用于提供https://github.com/mapbox/mbtiles-spec%E6%A0%BC%E5%BC%8F%E5%AD%98%E5%82%A8%E7%9A%84%E5%9C%B0%E5%9B%BE%E7%93%A6%E7%89%87%E6%9C%8D%E5%8A%A1%E3%80%82

!https://github.com/consbio/mbtileserver/actions/workflows/test.yml/badge.svg  https://goreportcard.com/badge/github.com/consbio/mbtileserver](https://goreportcard.com/report/github.com/consbio/mbtileserver)

当前支持mbtiles规范1.0版本定义的png、jpg、webp和pbf（矢量瓦片）格式瓦片集。瓦片遵循基于Web Mercator坐标系统的XYZ瓦片方案提供服务。不再支持UTF8 Grids。

除瓦片级访问外，还提供：

• 每个瓦片集的TileJSON 2.1.0端点，包含mbtiles文件的完整元数据
• 用于浏览每个瓦片集的预览地图
• 最小化的ArcGIS瓦片地图服务API

我们已在AWS t2.nano虚拟机上成功托管多个瓦片集，无性能问题。

目标

• 为mbtiles格式存储的地图瓦片提供Web瓦片API
• 高性能
• 可在资源有限的云托管机器（内存和CPU受限）上运行
• 易于安装和操作

支持的Go版本

需要Go 1.16+。

mbtileserver使用Go模块，遵循Go 1.16及以上的标准实践。

安装

可通过以下命令安装：

sh
$ go get github.com/consbio/mbtileserver

这将创建并安装名为mbtileserver的可执行文件。

使用方法

命令行参数

从仓库根目录运行（需确保$GOPATH/bin在$PATH中）：

$ mbtileserver --help
Serve tiles from mbtiles files.

Usage:
  mbtileserver [flags]

Flags:
  -c, --cert string            X.509 TLS证书文件名。如果提供，将用于启用服务器SSL
  -d, --dir string             包含mbtiles文件的目录。可使用逗号分隔的多个目录列表（默认"./tilesets"）
      --disable-preview        禁用每个瓦片集的地图预览（默认启用）
      --disable-svc-list       禁用服务列表端点（默认启用）
      --disable-tilejson       禁用每个瓦片集的TileJSON端点（默认启用）
      --domain string          服务器域名。仅用于AutoTLS
      --dsn string             Sentry DSN
      --enable-arcgis          启用ArcGIS Mapserver端点
      --enable-fs-watch        启用通过监控文件系统重新加载瓦片集
      --enable-reload-signal   启用通过HUP信号优雅重启服务器进程
      --generate-ids           自动生成瓦片集ID，而非使用相对路径
  -h, --help                   帮助信息
  -k, --key string             TLS私钥
  -p, --port int               服务器端口。如果使用--cert或--tls选项，默认443，否则默认8000（默认-1）
  -r, --redirect               将HTTP重定向到HTTPS
      --root-url string        服务端点的根URL（默认"/services"）
  -s, --secret-key string      用于HMAC请求认证的共享密钥
      --tiles-only             仅启用瓦片端点（等同于--disable-svc-list --disable-tilejson --disable-preview）
  -t, --tls                    通过Let's Encrypt自动获取TLS证书
  -v, --verbose                详细日志

托管瓦片只需将mbtiles文件放入tilesets目录并启动服务器即可。

瓦片集目录可包含子目录，这些将转换为相应的URL：
<tile_dir>/foo/bar/baz.mbtiles将可通过/services/foo/bar/baz访问。

如果提供--generate-ids，瓦片集ID将使用每个瓦片集路径的SHA1哈希自动生成。默认情况下，瓦片集ID基于使用--dir提供的基础目录的相对路径。

需要移除、修改或添加新瓦片集时，只需重启服务器进程或使用以下重新加载方法。

如果提供有效的Sentry DSN，警告、错误、致命错误和恐慌将报告给Sentry。

如果提供redirect选项，服务器还会监听80端口并将请求重定向到443端口。

如果提供--tls选项，将自动代表您接受Let's Encrypt服务条款。请在此查看条款。证书缓存在执行mbtileserver的目录下创建的.certs文件夹中。请确保该文件夹可由mbtileserver进程写入，否则会出错。证书在服务器收到第一个请求时才会请求。建议启动后通过访问https://<hostname>/services并观察服务器日志确保证书正确处理。常见错误包括Let's Encrypt无法访问您提供的域名。localhost或仅限内部的域名无效。

如果提供--cert或--tls，默认端口为443。

环境变量

也可使用环境变量代替命令行参数，这在Docker部署中更有用。以下变量可用：

• PORT（对应--port）
• TILE_DIR（对应--dir）
• GENERATE_IDS（对应--generate-ids）
• ROOT_URL（对应--root-url）
• DOMAIN（对应--domain）
• TLS_CERT（对应--cert）
• TLS_PRIVATE_KEY（对应--key）
• HMAC_SECRET_KEY（对应--secret-key）
• AUTO_TLS（对应--tls）
• REDIRECT（对应--redirect）
• DSN（对应--dsn）
• VERBOSE（对应--verbose）

示例：

$ PORT=7777 TILE_DIR=./path/to/your/tiles VERBOSE=true mbtileserver

在docker-compose.yml中：

yaml
mbtileserver:
  ...
  environment:
    PORT: 7777
    TILE_DIR: "./path/to/your/tiles"
    VERBOSE: true
  entrypoint: mbtileserver
  ...

重新加载

使用信号重新加载

mbtileserver可选择支持优雅重新加载（不中断任何进行中的请求）。此功能需通过--enable-reload-signal标志启用。启用后，可通过向服务器进程发送HUP信号触发重新加载：

$ kill -HUP <pid>

重新加载服务器将使其检测瓦片目录的变化，添加新瓦片集并移除不再存在的瓦片集。

使用文件系统监控重新加载

mbtileserver可选择通过监控文件系统变化支持单个瓦片集的重新加载。此功能需通过--enable-fs-watch标志启用。

服务器启动时，-d/--dir指定的所有目录及其当时存在的子目录将被监控瓦片集变化。

正在更新的现有瓦片集在磁盘文件更新时会被锁定。这将导致对该瓦片集的传入请求最多停滞30秒，一旦瓦片集完全更新并解锁就会返回。如果瓦片集更新超过30秒，将返回HTTP 503错误，直到瓦片集完全更新并解锁。

在极高请求量下，文件首次修改到检测到修改（并锁定瓦片集）之间的请求可能会遇到错误。

警告：不要在服务器运行时移除顶级监控目录。
警告：不要在服务器运行时在监控目录内创建或删除子目录。
警告：不要直接在监控目录中生成瓦片。应在单独目录中创建，完成后复制到监控目录。

与反向代理一起使用

可在mbtileserver前使用反向代理拦截传入请求、提供TLS等。

我们在各种项目的生产环境中使用过Caddy和NGINX，通常在需要代理到其他后端服务时使用。

为确保正确的请求URL传递给mbtileserver，使TileJSON和地图预览端点正常工作，请确保反向代理发送以下头：

• 协议（HTTP/HTTPS）：X-Forwarded-Proto、X-Forwarded-Protocol或X-Url-Scheme以设置请求协议；或X-Forwarded-Ssl自动设置为HTTPS
• 主机：设置Host和X-Forwarded-Host

Caddy v2示例

对于本地运行在8000端口的mbtileserver，在域名配置块中添加：

<domain_name> {
  route /services* {
    reverse_proxy localhost:8000
  }
}

根据瓦片集内容变化频率，可在route块中添加缓存控制头。例如，防止客户端缓存瓦片超过1小时：

  route /services* {
    header Cache-Control "public, max-age=3600, must-revalidate"
    reverse_proxy localhost:8000
  }

NGINX示例

对于本地运行在8000端口的mbtileserver，在server块中添加：

nginx
server {
   <其他配置选项>

    location /services {
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $server_name;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_pass http://localhost:8000;
    }
}

Docker部署

拉取镜像

从GitHub Packages拉取最新镜像：

$ docker pull ghcr.io/consbio/mbtileserver:latest

本地构建镜像

构建本地Docker镜像（命名为mbtileserver）：

$ docker build -t mbtileserver -f Dockerfile .

运行容器

在8080端口运行容器，瓦片集位于<host tile dir>。默认情况下，容器内mbtileserver运行在8000端口。

$ docker run --rm -p 8080:8000 -v <host tile dir>:/tilesets ghcr.io/consbio/mbtileserver

可传递额外命令行参数，例如使用证书使服务器支持HTTPS。以下示例使用https://github.com/FiloSottile/mkcert%E7%94%9F%E6%88%90%E7%9A%84%E8%87%AA%E7%AD%BE%E5%90%8D%E8%AF%81%E4%B9%A6%EF%BC%8C%E5%B9%B6%E5%90%AF%E7%94%A8%E8%87%AA%E5%8A%A8%E9%87%8D%E5%AE%9A%E5%90%91%EF%BC%88%E4%BD%BF%60mbtileserver%60%E5%90%8C%E6%97%B6%E7%9B%91%E5%90%AC80%E7%AB%AF%E5%8F%A3%E5%B9%B6%E8%87%AA%E5%8A%A8%E9%87%8D%E5%AE%9A%E5%90%91%E5%88%B0443%EF%BC%89%EF%BC%9A

$ docker run --rm -p 80:80 -p 443:443 -v <host tile dir>:/tilesets -v <host cert dir>:/certs/ ghcr.io/consbio/mbtileserver -c /certs/localhost.pem -k /certs/localhost-key.pem -p 443 --redirect

使用docker-compose

通过docker-compose运行：

$ docker-compose up -d

默认docker-compose.yml配置mbtileserver连接主机8080端口，并使用./mbtiles/testdata文件夹作为瓦片集目录。可使用自定义docker-compose.override.yml或环境特定文件进行配置。

重新加载容器内服务器

$ docker exec -it mbtileserver sh -c "kill -HUP 1"

规格

• 期望mbtiles文件遵循https://github.com/mapbox/mbtiles-spec1.0%E7%89%88%E6%9C%AC%EF%BC%8C%E6%8E%A8%E8%8D%901.1%E7%89%88%E6%9C%AC
• 实现https://github.com/mapbox/tilejson-spec

创建瓦片

可使用多种工具创建mbtiles文件。我们使用以下工具创建与mbtileserver兼容的瓦片：

• TileMill（图像瓦片）
• https://github.com/mapbox/tippecanoe%EF%BC%88%E7%9F%A2%E9%87%8F%E7%93%A6%E7%89%87%EF%BC%89
• https://github.com/consbio/pymbtiles%EF%BC%88Python%E5%88%9B%E5%BB%BA%E7%9A%84%E7%93%A6%E7%89%87%EF%BC%89
• https://github.com/consbio/tpkutils%EF%BC%88%E4%BB%8EArcGIS%E7%93%A6%E7%89%87%E5%8C%85%E8%BD%AC%E6%8D%A2%E7%9A%84%E5%9B%BE%E5%83%8F%E7%93%A6%E7%89%87%EF%BC%89

每个mbtiles文件的根名称成为下文使用的"tileset_id"。

XYZ瓦片API

mbtileserver的主要用途是作为XYZ瓦片主机。

瓦片通过以下URL提供：
/services/<tileset_id>/tiles/{z}/{x}/{y}.<format>

其中<format>根据瓦片集数据类型为png、jpg、webp或pbf。

TileJSON API

mbtileserver自动为每个服务创建TileJSON端点，位于/services/<tileset_id>。TileJSON使用与传入请求相同的协议和域名；--domain设置不影响自动生成的URL。

此API提供mbtiles文件中metadata表的大部分元素，以及从瓦片数据自动推断的其他元素。

例如，http://localhost/services/states_outline返回：

json
{
  "bounds": [
    -179.23108,
    -14.601813,
    179.85968,
    71.441055
  ],
  "center": [
    0.314297,
    28.419622,
    1
  ],
  "credits": "US Census Bureau",
  "description": "States",
  "format": "png",
  "id": "states_outline",
  "legend": "[{\"elements\": [{\"label\": \"\", \"imageData\": \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAYAAACNiR0NAAAAAXNSR0IB2cksfwAAAAlwSFlzAAAOxAAADsQBlSsOGwAAAGFJREFUOI3tlDEOgEAIBClI5kF+w0fxwXvQdjZywcZEtDI31YaQgWrdPsYzAPFGJCmmEAhJGzCash0wSVE/HHnlKcDMfrPXYgmXcAl/JswK6lCrz89BdGVm1+qrH0bbWDgA3WwmgzD8ueEAAAAASUVORK5CYII=\"}], \"name\": \"tl_2015_us_state\"}]",
  "map": "http://localhost/services/states_outline/map",
  "maxzoom": 4,
  "minzoom": 0,
  "name": "states_outline",
  "scheme": "xyz",
  "tags": "states",
  "tilejson": "2.1.0",
  "tiles": [
    "http://localhost/services/states_outline/tiles/{z}/{x}/{y}.png"
  ],
  "type": "overlay",
  "version": "1.0.0"
}

地图预览

mbtileserver自动为每个瓦片集创建地图预览页面，位于/services/<tileset_id>/map。

当前图像瓦片使用Leaflet，矢量瓦片使用Mapbox GL JS。

ArcGIS API

项目提供mbtiles文件中瓦片的最小化ArcGIS瓦片地图服务API。

通过--enable-arcgis标志启用。

这应足以用于在线平台如Data Basin。由于ArcGIS API依赖mbtiles文件中不常见的属性，某些方面使用最小信息填充。

此API不旨在用于更全功能的ArcGIS应用（如ArcGIS Desktop）。

可用端点：

• 服务信息：http://localhost:8000/arcgis/rest/services/<tileset_id>/MapServer
• 图层信息：http://localhost:8000/arcgis/rest/services/<tileset_id>/MapServer/layers
• 瓦片：http://localhost:8000/arcgis/rest/services/<tileset_id>/MapServer/tile/0/0/0

请求授权

通过-s/--secret-key或设置HMAC_SECRET_KEY环境变量提供密钥，将限制所有服务器端点和瓦片请求的访问。只有提供使用相同密钥创建的加密签名的请求才会被处理。例如，应用服务器可向授权客户端提供短期令牌，客户端使用该令牌访问特定服务的瓦片。

签名自创建日期起15分钟内有效，防止暴露或泄露的签名在长时间内有用。

创建签名

签名是使用SHA1算法的URL安全base64编码HMAC哈希。哈希密钥是从随机生成的盐和密钥字符串创建的SHA1密钥。哈希负载是哈希创建