go-pmtiles 瓦片代理服务如何工作:LRU 缓存、ETag 失效与多段 HTTP 请求深度解析

原创2026-11-13 13:48:471,748 阅读

go-pmtiles 瓦片代理服务如何工作:LRU 缓存、ETag 失效与多段 HTTP 请求深度解析

go-pmtiles 是一个单文件可执行工具,用于创建和托管 PMTiles 瓦片归档。它的 serve 瓦片代理命令内置了一套精巧的高性能架构:基于 LRU 策略的目录缓存、基于 ETag 的缓存自动失效、以及批量多段 HTTP Range 请求。这篇文章带你从瓦片请求的生命周期入手,深入拆解这三项核心技术是如何协作的。

瓦片代理的整体架构

当你运行 go-pmtiles serve 时,它会启动一个 HTTP 服务,把本地目录或 S3、GCS、Azure Blob 等远程存储中的 .pmtiles 归档暴露为标准的 z/x/y 瓦片接口:

./go-pmtiles serve ./archives --port 8080 --cache-size 64

📦 请求处理的核心由 server.go 中的 Server 类型实现。它的职责可以概括为三步:

  1. 解析路径:匹配 /{archive}/{z}/{x}/{y}.{ext}、/{archive}/metadata、/{archive}.json(TileJSON)三类路由
  2. 查目录:通过多级目录结构定位瓦片在归档文件中的字节偏移
  3. 取数据:对底层存储发起带 ETag 校验的 Range 请求,取出那一小段瓦片字节

关键设计在于:服务端从不缓存瓦片本身,只缓存"目录"。目录是归档文件的"索引表",体积小、命中率极高,把它缓存下来后,绝大多数瓦片请求都只需一次精确的 Range 下载。

PMTiles 的三级目录查找

PMTiles 归档内部按区块组织:

区块 作用 大小
文件头 记录各区块偏移量、缩放级别、瓦片格式 固定 127 字节
根目录(Root) 一级索引,指向若干叶目录 通常几 KB
叶目录(Leaf) 二级索引,直接给出瓦片偏移 按需加载
瓦片数据区 实际的 MVT/PNG/WebP 等瓦片字节 归档主体

在 server.go 的 getTileAttempt 函数 中,查找瓦片的过程最多循环 3 层:先读 16KB 的文件头拿到根目录位置,在根目录中用二分查找定位瓦片;如果条目指向叶目录,则加载叶目录再查一次;命中后按 TileDataOffset + entry.Offset 发起 Range 请求取回瓦片字节。

🎯 注意一个细节:头文件首次获取时,代码会一次性把根目录也缓存进去,让后续请求少跑一趟网络往返。

LRU 缓存:单协程事件循环 + 大小预算

缓存键与淘汰策略

LRU 缓存在 server.go 的 Start 方法 中实现,数据结构非常经典:

  • 一个 map[cacheKey]*list.Element 哈希表,cacheKey 由归档名、ETag、偏移量和长度组成
  • 一条双向链表 evictList 维护访问顺序:命中时 MoveToFront,新增时 PushFront,淘汰时从链表尾部 Back() 移除

与常见的"按条目数"淘汰不同,这里的预算是字节数:

while totalSize > cacheSize * 1000 * 1000 {
    evictList.Back() // 淘汰最久未访问的条目
}

--cache-size 64 表示 64MB 的目录缓存总量。每个缓存条目的大小按 24 * len(entries) 估算(每个目录条目 24 字节)。

请求合并(In-flight Deduplication)

这套缓存还有一个隐藏的高阶技巧:并发请求合并。整个缓存由单一协程的事件循环驱动,HTTP 请求通过 reqs channel 投递进来,等待结果从各自的 channel 中取出。

当事件循环收到一个未命中的 key 时,会检查 inflight 映射:

  • 如果同一 key 已有下载在途,新请求只是被 append 进等待队列,不会发起第二次网络请求,统计上记为一次缓存命中
  • 下载完成后,事件循环把结果广播给所有等待者,再一并写入 LRU 链表

这意味着即使 1000 个用户同时请求同一张热门瓦片,对远端存储也只产生 1 次真实拉取。这是代理服务抗压能力的核心来源。🔥

ETag 失效:文件更新后缓存如何自动作废

瓦片归档是会被重建上传的。如果缓存里的目录还指着旧文件的偏移量,就会取出错乱的字节。go-pmtiles 用 ETag 条件请求解决了这个问题,实现分散在 bucket.go 与 server.go 中。

If-Match 条件读取

所有对底层的读操作都走 NewRangeReaderEtag 接口。在 HTTPBucket 的实现 中,每个请求同时携带两个请求头:

  • Range: bytes=offset-end:只取需要的字节段
  • If-Match: <etag>:告诉服务端"只有文件没变我才要数据"

对 S3、Azure Blob、GCS,BucketAdapter 会把 ETag 翻译成各云厂商的条件参数(IfMatch / GenerationMatch);对本地 file:// 存储,则用"修改时间 + 文件大小"哈希出一个伪 ETag。

412/416 触发整档清除 + 重试

一旦远端返回 412 Precondition Failed(文件已变)或 416(偏移越界,文件被缩小了),bucket.go 会将其识别为 RefreshRequiredError。

随后 server.go 的失效流程 接管:事件循环收到带 purgeEtag 的请求,清除该归档所有旧 ETag 对应的缓存条目,并打印日志:

re-fetching directories for changed file mymap

而 getTile 和 getHeaderMetadata 会在外层做一次透明重试:第一次尝试失败且返回了 purgeEtag 时,带着清除指令再查一次,这次读到的就是新文件的头与目录。整个过程对客户端完全无感——最多多等待几十毫秒。

✨ 这套机制让"上传新版瓦片 → 代理自动切到新数据"变成一个零配置的原子操作。

多段 HTTP 请求:一次下载多个不连续区块

前面提到 serve 代理每次只取一小段,但 go-pmtiles 的 sync 增量同步功能则是多段 Range 请求的大玩家,代码位于 sync.go。

场景:新版本归档只改了一部分瓦片

归档重建后,往往 90% 的字节与旧版本完全相同。sync 命令配合 .sync 伴随文件,可以对比新旧版本,只下载发生变化的区块,把带宽降到极致。

Range 头批量打包

makeMultiRanges 函数 展示了多段请求的精髓:HTTP 允许 Range 头里写多个逗号分隔的区间:

Range: bytes=100-199,1500-1599,9000-9199

函数会依次把各区间拼进一个 strings.Builder,当预估的请求头长度超过 1MB 上限(1048576-200)时切分,生成一批 multiRange 任务。这样一次 TCP 连接就能带回几十段不连续的瓦片数据,把请求数量从"每个区块一次"压缩到"每 1MB 头长一次"。

此外还有两个优化细节(见 sync.go):

  • 合并相邻区间:若两段在源文件中首尾相接,直接合并为一段,减少 Range 数量
  • 并发下载:下载任务放进 channel,由多个 goroutine 并行消费

sync 命令的 --ranges-per-request 参数(默认 100)也暴露了这个权衡:单个请求里的区间数越多,连接效率越高,但受限于服务端对多段请求的支持程度。

⚠️ 需要注意,sync 目前仍是实验性功能,代码中明确标注 "Do not rely on this in production!",生产环境建议先用它验证收益。

两种部署方式:独立 serve 与 Caddy 插件

独立进程

最简单的部署就是直接运行 serve 子命令(定义于 main.go):

./go-pmtiles serve ./archives \
  --cache-size 256 \
  --admin-port 9090 \
  --cors https://example.com

常用参数:

  • --cache-size:LRU 目录缓存预算(MB),默认 64
  • --cors:允许的跨域来源,浏览器端地图应用必配
  • --admin-port:额外端口暴露 Prometheus /metrics 端点

嵌入 Caddy 反向代理

go-pmtiles 同时提供 Caddy 中间件插件,可以把瓦片服务直接内嵌到你的站点路由里,源码见 caddy/pmtiles_proxy.go。它的 Caddyfile 配置示例 非常直观:

localhost:2019 {
  handle_path /tiles/* {
    pmtiles_proxy {
      bucket https://example.com
      cache_size 256
      public_url https://localhost:2019/tiles
    }
  }
}

其中 public_url 会被写入 TileJSON 的 tiles 字段,供客户端拼接瓦片 URL;插件还负责把每个响应的状态码与耗时写入 Caddy 日志(见 ServeHTTP 方法)。

用 Prometheus 指标观测缓存效率

想验证前面讲的机制是否按预期工作?serve --admin-port 提供的 metrics 端点 暴露了关键指标:

指标族 含义
pmtiles_dir_cache_requests 目录请求数,按 hit/miss 区分
pmtiles_dir_cache_size_bytes 当前缓存占用
pmtiles_bucket_requests 对底层存储的实际请求数
pmtiles_reloads ETag 失效触发的文件重载次数
pmtiles_request_duration 瓦片请求耗时分布

📊 经验法则:目录请求的 hit 率应稳定在 95% 以上;bucket_requests 的增长速度应远低于 requests 总数。如果 reloads 频繁自增,说明远端归档在反复重建,可以检查上游流水线。

小结:为什么这套设计又快又稳

回顾 go-pmtiles 瓦片代理的三个支柱:

  1. 只缓存目录、不缓存瓦片:目录小而热,LRU 按字节预算淘汰,缓存内存占用可精确控制
  2. ETag 条件请求 + 自动重试:If-Match 让"缓存是否过期"由存储端裁决,412/416 触发整档清除,归档热更新零配置
  3. 单协程事件循环 + 请求合并:天然无锁,并发同 key 请求共享一次网络拉取
  4. 多段 Range 批量下载(sync 场景):一个请求头携带数十段区间,把带宽和连接数都压到最低

如果你正在自托管矢量瓦片服务,这套纯 Go 实现的架构值得仔细研读——核心逻辑集中在 pmtiles/server.go 一个文件里,配合 pmtiles/bucket.go 就能读懂全部缓存与请求逻辑。🚀

登录后查看全文
go-pmtiles