go-pmtiles 瓦片代理服务如何工作:LRU 缓存、ETag 失效与多段 HTTP 请求深度解析
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 类型实现。它的职责可以概括为三步:
- 解析路径:匹配
/{archive}/{z}/{x}/{y}.{ext}、/{archive}/metadata、/{archive}.json(TileJSON)三类路由 - 查目录:通过多级目录结构定位瓦片在归档文件中的字节偏移
- 取数据:对底层存储发起带 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 瓦片代理的三个支柱:
- 只缓存目录、不缓存瓦片:目录小而热,LRU 按字节预算淘汰,缓存内存占用可精确控制
- ETag 条件请求 + 自动重试:
If-Match让"缓存是否过期"由存储端裁决,412/416 触发整档清除,归档热更新零配置 - 单协程事件循环 + 请求合并:天然无锁,并发同 key 请求共享一次网络拉取
- 多段 Range 批量下载(sync 场景):一个请求头携带数十段区间,把带宽和连接数都压到最低
如果你正在自托管矢量瓦片服务,这套纯 Go 实现的架构值得仔细研读——核心逻辑集中在 pmtiles/server.go 一个文件里,配合 pmtiles/bucket.go 就能读懂全部缓存与请求逻辑。🚀