# 诗酷手记（二）：一千万张历史地图瓦片

- URL: https://wuming.si/blog/4110/
- Author: Wuming
- Published: 2026-03-05
- Language: zh-Hans
- Categories: Technology, Poem & Reading

> 上一篇：[搜「东坡」也能找到苏轼](https://wuming.si/blog/4109) ｜ 下一篇：[从 Java 搬到 Go](https://wuming.si/blog/4111)

诗酷有一个[行迹图](https://shi.cool/routes)，把诗人的一生画成一条路线：从籍贯出发，按到任年份经过历任官职所在地，最后到葬地。数据来自 CBDB，一共 828 位诗人、5,108 个站点，平均每人 6 站。

第一版画在 ECharts 的今日中国地图上。能看，但总觉得不对：杜甫走的是唐代的道和州，陆游生活在半壁江山的南宋，画在今天的省界上，味道全没了。

中研院的[中国历史地图](https://gis.sinica.edu.tw/ccts/)（CCTS）有各朝代的历史地图，以标准的 WMTS 瓦片提供。于是有了这个项目：把需要的图层下载下来，自己托管，给每位诗人配上他那个年代的底图。

## 先算清楚有多少

CCTS 的 GetCapabilities 对全部 114 个图层都声明了 z0 到 z21 共 22 级。照这个估，选中的 25 个历史图层是 7.85 万亿张、约 134 PB。

这当然不对。22 级只是网格定义，不是数据。实际探测下来，每个图层的数据在 z7 到 z17 之间就到顶了，再往深处，服务器返回一张 196 字节的空白图，所有图层字节完全相同。按实测上限算，25 个图层合计 **1,056 万张、24 GB**。

所以瓶颈从来不是磁盘，而是时间和礼貌。z12 一层就占了全部瓦片的 73%。

## 下载器：单文件、只用标准库

下载脚本 `ccts_tiles.py` 是一个文件，只用 Python 标准库，可以直接拷到任何一台机器上跑。子命令有 `list`、`probe`、`estimate`、`download`、`status`。

几个决定都是实测出来的：

**存 MBTiles，不存目录树。** 一开始打算把瓦片存到树莓派上的 SMB 共享。实测 SQLite 直写 SMB 只有 0.5 MB/s，顺序拷贝却有 21 MB/s，差 40 倍；目录树更糟，每建一个文件就是一次网络往返，几百万个小文件根本不可行。后来改成写本地磁盘，SQLite 183 MB/s。

**空白瓦片不入库，但要记下来。** 空白瓦片占 10% 到 40%。一开始只是不存，结果每次续传都要把它们重新请求一遍。后来单独建一张 `blanks` 表，续传时一起跳过。

**按层级断点续传。** 某一层全部抓完、零失败，才写一条「该层完成」的记录。重启时完成的层直接跳过，不用把几百万个坐标重新枚举一遍。

## 从 1 张每秒到 36 张每秒

在另一台机器上跑，只有每秒 1 张。一测，单张 1,768 毫秒，其中 TLS 握手 1,073 毫秒：**每张瓦片都新建了一次 HTTPS 连接。**

改成每个线程持有一条长连接之后，单线程从 0.57 张每秒到 1.89 张每秒；16 个线程下，端到端从每秒 1 张到了 36 到 39 张。

另一个优化是**剪掉空白子树**：父瓦片没有数据，它的四个子瓦片必然也没有，因为源图根本不覆盖那块地面。按层级从浅到深下载，父层的结论是已知的，整棵子树可以跳过。东汉图层在 z7 到 z10 分别省掉了 21、134、894、3,395 张。

这个优化第一版差点闯大祸。有的图层（比如西汉）在 z0 就返回空白，因为服务器在低层级根本不出图。剪枝从 z0 开始推，一路把整个金字塔剪光，而且没有任何提示。后来加了两道保险：只有父层真正产出过瓦片，才拿它的空白做推断；动手之前抽查几张要剪的瓦片，只要有一张其实有数据，这个图层就彻底关掉剪枝。

## 卡了四天

有一次下载停在三国图层的 z11。进程还在，CPU 0%，16 条连接全部挂着，日志一个字没有，就这样过了 3 天 23 小时。

一开始以为是源站整个挂了：两台机器都连不上，TCP 能握手，HTTP 永远不返回。后来从另一台 Vultr 机器一试，立刻返回 200。原来是 IP 被封了，而之前的两个观测点恰好在同一个被封的网段。

修了两类问题：

- **不能挂死。** 加了看门狗：某一层 5 分钟内完成数没有增长，就刷盘、退出，下次续传。socket 显式设超时、开 TCP keepalive。启动前先探活，不通就直接说明并退出；加 `--wait` 可以每隔几分钟重试，恢复后自动继续。
- **走代理。** 标准库没有 SOCKS5，为了保持「单文件、只用标准库」，按 RFC 1928 和 1929 手写了握手。目标地址以域名交给代理解析，因为那台机器所在的网络 DNS 也不通。经一条 `ssh -D` 隧道，稳定在每秒 23 到 29 张，零失败。

最后 25 个图层全部下完：1,056 万张，12 GB。

## 塞进一台小服务器

服务器上没有 12 GB 可用。一看数据，线描地图越往深层，空白和纯色瓦片越多，而且逐字节相同。MBTiles 规范本身就支持去重：一张 `images` 表存图片，一张 `map` 表存坐标到图片的映射，`tiles` 是一个视图。标准的阅读器不需要任何改动。

去重并把层级限制在 z11 以内之后，15 个朝代底图从 8.41 GB 变成 0.90 GB，少了 89%。唐代主底图从 807 MB 变成 80 MB。扫描件就没这么好运，唐代驿路图是 JPEG，去重只省了 28%。

瓦片服务也是一个只用标准库的小脚本，把一个目录的 `.mbtiles` 暴露成标准的 XYZ 接口。MBTiles 里的行号是自下而上的（TMS），网页地图按自上而下请求（XYZ），翻转在服务端做。缺失的瓦片返回一张 1×1 透明图，而不是 404，没下完的地方显示空白，而不是一堆碎图标。

它以 systemd 常驻，nginx 反代，缓存头是一年 immutable，Cloudflare 边缘直接命中。图层加到 17 个时，SQLite 的页缓存涨到 107 MB，逼近 120 MB 的内存上限。给每个连接设 2 MB 缓存、关掉 mmap，降到 66 MB，压测下不再上涨。

瓦片用了一个独立域名 `tiles.shi.cool`。主站会下发 session cookie，一屏地图 20 到 60 个瓦片请求都会带着它，换个域名就省了。将来要把瓦片挪到对象存储，改一条 CNAME 即可，页面代码一行不用动。

## 底图按年代选，不按朝代名选

前端从 ECharts 换成 Leaflet，URL 不变。上线后发现一个真错误：原来是「一个朝代取第一个可用图层」，而 327 位有行迹的宋代诗人里，有 119 位生于 1127 年之后。**陆游、辛弃疾一直被画在北宋地图上**，那张图上中原还没有失陷。

现在按诗人的生年或活跃年份选图幅：西汉和东汉以公元 25 年为界，三国、西晋、东晋以 280 年和 317 年为界，北宋和南宋以 1127 年为界，先秦从商到西周、春秋再到秦。年代不详的，退回该朝代最早的一张。

还有几个小问题：

- **「今界」开关没反应。** 想叠一层今天的省界做对比，用的是 ECharts 的 `china.json`。交给 Leaflet 既不报错，也画不出东西。原来它的坐标是压缩编码的：每两个字符是一个点的 zigzag 增量，要累加再除以 1024。解码之后得到 16,173 个点，全部落在中国范围内。
- **路线看不清。** 唐代地图本身是米黄底、朱红注记，路线用的正是网站的主色朱红，糊成一片。换颜色不够，改用制图上常用的双线：底下一条 7 像素的白色衬线，上面一条 3 像素的深蓝虚线，什么底图上都读得出来。虚线再加一个 CSS 动画，路线看起来会「走」。
- **全屏要带上控件。** 全屏的对象是整个地图区，包括底图选择、不透明度、年份滑块和图例。只把地图本身全屏，恰好会把最需要的几个控件挡在外面。

现在线上有 21 个图层，1.39 GB，覆盖语料 11 个朝代中的 10 个。

下一篇：[网站是怎么从 Java 搬到 Go，而搜索引擎一点没察觉的](https://wuming.si/blog/4111)。
