← 文章 / 开源项目
Simon Willison 4天前 · 2026-11-18 01:16:16 · 12 阅读

用 service workers 和 Pyodide 在浏览器中运行完整的 Datasette Python 服务端应用

用 service workers 和 Pyodide 在浏览器中运行完整的 Datasette Python 服务端应用

2026年11月17日

Datasette Lite 是我把 Datasette Python 应用移植到浏览器里直接运行的成果,基于 WebAssembly 和 Pyodide。现在我用 service workers 对 Datasette Lite 做了彻底重写,新版几乎和真正的服务端应用别无二致。

现在通过精心构造的 lite.datasette.io URL,你可以实现以下所有操作:

  • 加载客户端版 Datasette,浏览任意 SQLite 数据库、JSON 文件、CSV 文件或 SQL 脚本
  • 从 PyPI 选择指定发布版本的 Datasette 来加载
  • 从 Datasette 的 GitHub 仓库加载指定的 commit、tag 或分支
  • 从 100 多个 SQLite 版本中任选一个配合 Datasette 使用
  • 从 PyPI 或 wheel 文件 URL 安装额外的 Datasette 插件,包括 JavaScript 可视化工具

能够加载指定的 Datasette 版本、插件和 SQLite 版本,让它成为链接演示的绝佳工具——无论是展示开发中的新功能还是复现 bug,都不再需要为此专门搭一个 web 服务器。

举个例子,看看下面这个 URL:

https://lite.datasette.io/?install=datasette-maplibre&url=https://gist.githubusercontent.com/simonw/39fa5d399465766039549912e2b3d291/raw/f6dfba99a75cbb8b5d9386223220eb52272767ee/demo.db&metadata=https://gist.githubusercontent.com/simonw/39fa5d399465766039549912e2b3d291/raw/f6dfba99a75cbb8b5d9386223220eb52272767ee/metadata.yml#/demo/capitals_and_countries%23map=0/4.2/180&color=continent

点开这个链接,经过短暂加载后,你会看到一个这样的页面:

网页地图界面截图。工具栏:“View” 设置为 “Clusters”,“Colour by” 设置为 “continent”,另有 “Filter to this area” 和 “Download GeoJSON” 按钮。世界地图展示国家轮廓并按大洲着色,带有彩色圆点和数字集群圆圈。南美洲某点弹出框显示:首府加拉加斯,国家委内瑞拉,大洲南美洲,首都人口 2985000,纬度 10.502944,经度 -66.918983。图例:非洲(52),亚洲(45),欧洲(39),北美洲(16),南美洲(13),大洋洲(6)。文字:“所有 171 行数据均已在地图上显示”。下方为表格,列包括 country、continent、capital_population、latitude、longitude、boundary。首行:阿富汗,亚洲,3277000,34.518636,69.181314,boundary 列中包含一张小地图,显示阿富汗轮廓并以蓝色填充。

这是 Datasette 正在运行新的 datasette-maplibre 插件,加载包含国家 GeoJSON 形状数据的数据库,并在表格中同时展示合并地图和单个边界地图。

让我们来拆解一下这个 URL,看看它在做什么:

https://lite.datasette.io/
  ?install=datasette-maplibre
  &url=https://.../demo.db
  &metadata=https://.../metadata.yml
  #/demo/capitals_and_countries%23map=0/4.2/180&color=continent

?install=datasette-maplibre 会从 PyPI 安装该额外插件。你可以多次传入 &install=... 以加载更多插件。

&url=https://.../demo.db 会从提供的 URL 加载该 SQLite 数据库。这些 URL 需要具备开放的 CORS 头——我会将此类文件托管在 Gists 上,因为它们为网页托管的文件提供了一种获取开放 CORS 头的简便方式。

&metadata=https://.../metadata.yml 会加载这个 metadata.yml 文件。元数据文件为多个数据表和 Datasette 首页添加了 HTML 描述。访问这个首页,可以看到该插件的其他功能导览,全部通过元数据文件定义。

#/demo/capitals_and_countries%23map=0/4.2/180&color=continent 是一个片段哈希,它会被转换为 Datasette 内部的路径——这里加载的是 /demo/capitals_and_countries SQL 视图,然后在其后附加另一个片段哈希(%23 是 URL 编码后的 #),告诉地图插件缩放到指定位置,并根据数据中的 continent 列设置地图上图形的颜色。

这个 URL 承载了相当多的功能!关于这种构建可通过 URL 寻址的软件的技巧,我去年在URL-addressable Pyodide Python environments 一文中有更详细的介绍。

Datasette Lite 支持的全部 URL 参数说明见 Datasette Lite README。

我已经开始把 Datasette Lite 用于 Datasette 的开发流程。比如最近的一个 issue 描述了一个分页 bug——我在评论中用 Datasette Lite 的链接演示了修复前的错误行为和修复后的效果:

Bug 演示:https://lite.datasette.io/?ref=1.0a42&sql=https://gist.github.com/simonw/75ececf61d50e6e8d50f0c150150ee81#/data/scores?_size=2&_sort=score——点击下一页,第二页是空的。

修复该 bug 后的同一页面(运行于 1.0a43 版本):https://lite.datasette.io/?ref=1.0a43&sql=https://gist.github.com/simonw/75ececf61d50e6e8d50f0c150150ee81#/data/scores?_size=2&_sort=score

原理:利用 Service Worker

Datasette Lite 并非全新项目。我早在 2022 年就发布了首个版本,最初只是觉得把服务端应用跑在浏览器里挺有趣,是个玩笑,但很快它便展现出实际价值。

初版的问题在于它只是个临时方案。其实现方式是让 Datasette 在 Pyodide web worker 中运行,模拟请求经过该技术栈处理,再通过 innerHTML 将生成的 HTML 注入顶层页面。

对于基础功能的 Datasette,这套方法可行;但所有依赖 JavaScript 的功能都会失效,因为 innerHTML 中的 script 标签不会执行,且用于 web worker 的变通方法无法加载额外的 JavaScript 或 CSS 文件。

新版本采取了基于 Service Worker 的完全不同思路。它允许 JavaScript 拦截针对新页面和资源的 HTTP 请求,转由客户端代码直接响应。

Datasette Lite 为整个 lite.datasette.io 域名注册了 service worker。父页面随后创建一个 iframe,将针对 Datasette 页面的请求发送至如下形式的 URL:

/app/aa94e6851595/ # 主页(HTML)
/app/aa94e6851595/data/places # 表格页面(HTML)
/app/aa94e6851595/-/static/navigation-search.js #(JavaScript)
/app/aa94e6851595/-/static/app.css #(CSS)

这些是常规的 Datasette URL,但加了 /app/aa94e6851595/ 前缀。这是为了什么?

加入 /app/<session>/ 前缀,主要是为了解决多标签页并存的问题。

以上述 URL 为例,它加载了一个带有 datasette-maplibre 插件的演示实例。该 URL 定义了一个完整的定制 Datasette 实例。你可能在一个标签页中运行这个实例,同时在另一个标签页运行我其他的演示链接。

lite.datasette.io 的 service worker 由所有标签页共享。如果它把请求路由到同一个 Datasette 实例,那么无论各标签页的 URL 想配置什么插件或设置,它们都会共享同一个底层实例。

因此,父页面会生成一个随机的 session ID,作为后续所有隐藏资源加载和页面加载的前缀。service worker 再借助这个 session ID,把请求经父页面转发给一个 web worker——里面运行着该会话专属的 Datasette 实例。

(依然需要 web worker,因为取决于浏览器,Pyodide 在 service worker 里最多只能维持 30 秒左右的状态。这里的环节实在太多了!)

我让 Claude Fable 5.2 生成了几张 SVG 示意图来解释这套机制。下面是我最喜欢的一张,现已嵌入 Datasette Lite 的 README:

架构示意图,标题为“点击 Datasette Lite 中的链接后发生了什么”,图例显示实线箭头代表“请求”,虚线箭头代表“响应”。一个蓝色方框标记为“index.html:你打开的页面 - 每个标签页选择一个随机会话并启动一个 Web Worker。”,其中包含两个白色方框:“iframe Datasette 页面位于 /app/session/…“ 和 “shell.js 页面自身的脚本:中继”。“下方是一个黄色方框,标记为“sw.js:service worker - 拦截 /app/session/…的请求。”。右侧是一个绿色方框,标有数字 4,标记为“webworker.js:Web Worker - Pyodide:WebAssembly 中的 Python”,其中包含三个堆叠的白色方框:“ASGI 桥接 + Cookie 罐”、“Datasette ASGI 应用”和“SQLite 数据库”。带编号的箭头将它们连接起来:从 iframe 向下指向 sw.js 的实线箭头 1,从 sw.js 向上指向 shell.js 的实线箭头 2,从 shell.js 横向指向 Web Worker 的实线箭头 3,从 Web Worker 指回 shell.js 的虚线箭头 5,从 shell.js 向下指向 sw.js 的虚线箭头 6,以及从 sw.js 向上指向 iframe 的虚线箭头 7。底部的编号说明为:1 页面请求 /app/session/fixtures。2 sw.js 拦截它并将其发送给所属标签页。3 shell.js 将其转发给 Web Worker。4 Python 添加 Cookie 并调用 Datasette,后者查询 SQLite。5 状态、标头和正文返回到页面,6 然后通过 MessagePort 返回到 sw.js,7 后者向浏览器返回一个 Response。iframe 渲染它。” src=

这个系统最早可以追溯到今年 5 月,当时它是一个使用 Claude Opus 4.8 生成的AI 研究性验证项目。直到 11 月(配合 Claude Fable 5.2),我才对这套机制足够熟悉,从而有信心将其投入生产环境!

附加功能:选择 SQLite 版本

我昨晚添加了这一功能,这是我在调查SQLite 中一个潜在 Bug过程中产生的延伸成果。

Datasette 设计用于兼容自 3.25 版本(2018 年 9 月发布)以来任何已发布的 SQLite 版本。自那时起,SQLite 又发布了 87 个新版本。

能够针对特定版本的 SQLite 启动 Datasette,对于演示 SQLite 新特性和排查奇怪的问题非常有用。

过去我用过各种技巧在 Mac 上让 Python 运行不同版本的 SQLite,但这个过程并不简单。

WebAssembly 正好适合这个场景。我可以在浏览器里加载一个自定义编译的 SQLite,直接测试,关掉标签页就丢弃。

datasette/pysqlite3-wasm-wheels 是我的新仓库,包含针对 pysqlite3 编译的 WebAssembly Python wheel,覆盖 163 个不同的 SQLite 版本。每个版本对应一个类似这样的文件:

pysqlite3-0.6.2-3.54.1-cp314-cp314-pyemscripten_2026_0_wasm32.whl

这是最新版本 SQLite 3.54.1 的。

Datasette Lite 现在支持一个特殊的 ?sqlite= URL 参数,可以接受 3.54.1 这样的版本号,解析出对应 wheel 文件的路径,然后下载并安装到 Pyodide 环境中,再配置 Datasette 使用它。

构建好这些 wheel 之后,我让 Claude Fable 5.2 帮我做了[这个附加工具](https://datasette.github.io/pysqlite3-wasm-wheels/?versions=3.54.1,3.54.0&sql=select+json_object(%27a%27%2C+(select+json_array(1%29%29%29),可以在任意选定的 SQLite 版本之间对比 SQL 查询结果。下面这个例子展示了 select json_object('a', (select json_array(1))) 在 SQLite 3.54.0 和 3.54.1 之间的差异:

一张 Web 工具截图,用于对比不同 SQLite 版本中的 SQL。标题“SQLite 版本(共 163 个)”位于筛选输入框上方,输入框占位符为“过滤,例如 3.4”,旁边有“清除选择”按钮和蓝色的“以 2 个版本启动 REPL”按钮。下方是一个可滚动的药丸状复选框网格,每个版本对应一个复选框,版本从 3.54.1 向下延伸至 3.30.0 以下,其中 3.54.1 和 3.54.0 被勾选。接着是“REPL”标题,下方有两个绿色状态徽章,分别显示“3.54.1 就绪”和“3.54.0 就绪”。随后是一个文本域,包含“select json_object('a', (select json_array(1)))”,旁边是蓝色的“Run”按钮,以及一行标记为“示例:”的可点击示例查询。输出部分显示提示符“sqlite> select json_object('a', (select json_array(1)))”,接着是一个橙色警告“版本差异:2 个不同结果”,以及两个并排的黄色结果面板,每个面板顶部都列出了该查询。在“SQLite 3.54.1”面板中,返回的 JSON 对象里键“a”对应一个字符串值:包含 1 的数组被双引号包裹。而在“SQLite 3.54.0”面板中,返回的 JSON 对象里键“a”对应一个实际的数组,内容为 1,没有外层的引号。” src=

这对其他 Python 应用也应同样适用

Datasette Lite 的工作机制并非 Datasette 独有。几乎任何 Python 应用都应该能采用同样的技巧——完全在浏览器中通过 WebAssembly 和 Pyodide 运行,以此作为低成本手段来提供预览环境、展示功能以及复现 Bug。

C 语言和 Rust 编写的扩展过去曾是此类方案的阻碍,但现在任何优秀的编程代理都能将它们编译为 Pyodide 兼容的 WebAssembly。根据 2026 年 4 月发布的 PEP 783,你甚至可以将它们发布到 PyPI。

其中一个难点是数据库。SQLite 完全没问题,但要在 WebAssembly 中运行 PostgreSQL 或 MySQL,虽然可行,却仍是一条少有人走的路。

我非常期待这类 WebAssembly 预览环境能在整个 Python 生态中成为一种常见模式。

面向 Hacker News:在浏览器中通过 service workers 运行完整的服务器端 Datasette Python 应用

原始来源: Simon Willison

评论 (0)