跳到正文
Simon Willison·· 5 小时前AI 评分50

Datasette Lite 用 Service Worker 与 Pyodide 在浏览器中运行完整服务端 Datasette 应用

Running the full server-side Datasette Python app in the browser with service workers and Pyodide

AI 导读

Datasette Lite 完成重写,借助 Service Worker 与 Pyodide 在浏览器中运行几乎与真实服务端无异的 Datasette 应用。

正文 · AI 翻译

2026年11月17日

Datasette Lite 是我将 Datasette 这个 Python 应用移植到浏览器中、借助 WebAssembly 和 Pyodide 直接运行的版本。我发布了使用 service worker 完全重写的 Datasette Lite,现在它几乎与真正的服务端应用难以区分。

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

  • 加载客户端 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

点击该链接,经过短暂的加载屏幕后,你会看到一个如下所示的页面:

Screenshot of a web map interface. Toolbar: "View" set to "Clusters", "Colour by" set to "continent", plus "Filter to this area" and "Download GeoJSON" buttons. A world map shows countries outlined and shaded by continent, with coloured dots and numbered cluster circles. A popup for a point in South America reads: capital Caracas, country Venezuela, continent South America, capital_population 2985000, latitude 10.502944, longitude -66.918983. Legend: Africa (52), Asia (45), Europe (39), North America (16), South America (13), Oceania (6). Text: "All 171 rows are on the map". Below, a table with columns country, continent, capital_population, latitude, longitude, boundary. First row: Afghanistan, Asia, 3277000, 34.518636, 69.181314, with a small map in the boundary column showing Afghanistan outlined and shaded in blue.

这就是 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 上,因为它们提供了一种简单的方法,让 Web 托管的文件获得开放的 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 可寻址的 Pyodide Python 环境一文中,更详细地介绍了这种构建 URL 可寻址软件的技巧。

支持的完整 URL 参数集在 Datasette Lite README 中有描述。

我已经开始将 Datasette Lite 作为 Datasette 开发流程的一部分来使用。这里有一个最近的问题,描述了一个分页 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 年发布了第一个版本,最初只是当作一个玩笑(在浏览器中运行服务端应用确实挺有趣),但它很快就证明了自己的价值。

最初版本的问题在于它只是一个临时拼凑的方案。它的工作方式是在 Pyodide web worker 中运行 Datasette,通过该技术栈模拟请求,然后使用 innerHTML 将生成的 HTML 注入回顶层页面。

这对基础版 Datasette 有效,但意味着任何使用 JavaScript 的功能都无法工作,因为 innerHTML 中的 script 标签不会执行,而且它使用的 web worker 技巧也无法加载额外的 JavaScript 或 CSS 文件。

新版本采用了基于 Service Worker 的全新方案。Service Worker 允许 JavaScript 拦截对新页面和资源的 HTTP 请求,并改由客户端代码来提供响应。

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

/app/aa94e6851595/ # the homepage (HTML)
/app/aa94e6851595/data/places # a table page (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 试图配置什么插件或其他设置。

相反,父页面会生成一个随机会话 ID,并将其用作所有后续隐藏资源和页面加载的前缀。然后 service worker 可以使用该会话 ID 将这些请求通过父页面路由回一个 web worker,该 worker 为那个特定会话运行一个专用的 Datasette 实例。

(我们仍然需要一个 web worker,因为 service worker 中的 Pyodide 无法在约 30 秒后维持状态,具体取决于浏览器。这里有很多活动部件!)

我让 Claude Fable 5.2 生成了几张 SVG 图表来帮助解释这一点。这是我最喜欢的一张,现已嵌入 Datasette Lite 的 README 中:

Architecture diagram titled "What happens when you click a link in Datasette Lite", with a legend showing a solid arrow for "request" and a dashed arrow for "response". A blue box labeled "index.html: the page you opened - Each tab picks a random session and starts one Web Worker." contains two white boxes: "iframe Datasette pages at /app/session/…" and "shell.js the page's own script: relays". Below it is a yellow box labeled "sw.js: the service worker - Intercepts requests for /app/session/…." To the right is a green box marked 4 and labeled "webworker.js: a Web Worker - Pyodide: Python in WebAssembly" containing three stacked white boxes: "ASGI bridge + cookie jar", "Datasette ASGI app" and "SQLite databases". Numbered arrows connect them: solid arrow 1 from the iframe down to sw.js, solid arrow 2 from sw.js up to shell.js, solid arrow 3 from shell.js across to the Web Worker, dashed arrow 5 from the Web Worker back to shell.js, dashed arrow 6 from shell.js down to sw.js, and dashed arrow 7 from sw.js up to the iframe. A numbered key at the bottom reads: 1 The page requests /app/session/fixtures. 2 sw.js intercepts it and posts it to the owning tab. 3 shell.js forwards it to the Web Worker. 4 Python adds cookies and calls Datasette, which queries SQLite. 5 The status, headers and body return to the page, 6 then to sw.js over a MessagePort, 7 which hands the browser a Response. The iframe renders it.

这个系统早在 5 月就作为一次AI 研究探索诞生,由 Claude Opus 4.8 生成。直到 11 月(以及 Claude Fable 5.2),我才对它的工作原理足够熟悉,能够自信地将其投入生产环境!

附加功能:选择你的 SQLite 版本

我在昨晚添加了这个功能,它是在调查SQLite 中的一个潜在 bug 时顺带做出来的。

Datasette 旨在兼容自 3.25(2018 年 9 月发布)以来的任何已发布版本的 SQLite。自那以后又发布了 87 个版本。

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

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

WebAssembly 非常适合这个场景。我可以完全在浏览器中加载自定义的 SQLite 构建,在那里测试它,然后在关闭标签页时将其丢弃。

datasette/pysqlite3-wasm-wheels 是我的新仓库,其中包含为 163 个不同 SQLite 版本编译的 pysqlite3 的 WebAssembly Python wheel。每个版本都会得到一个类似这样命名的文件:

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 文件的路径,然后获取该 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 之间有何不同:

Screenshot of a web tool for comparing SQL across SQLite versions. Heading "SQLite versions (163 available)" sits above a filter text input with placeholder "Filter, e.g. 3.4", a "Clear selection" button and a blue "Start REPL with 2 versions" button. Below is a scrollable grid of pill-shaped checkboxes, one per version, running from 3.54.1 down past 3.30.0, with 3.54.1 and 3.54.0 checked. A "REPL" heading follows, with two green status badges reading "3.54.1 ready" and "3.54.0 ready", then a textarea containing "select json_object('a', (select json_array(1)))" beside a blue "Run" button, and a row of clickable example queries labeled "Examples:". The output section shows the prompt "sqlite> select json_object('a', (select json_array(1)))" followed by an orange warning "Versions differ: 2 different results" and two side-by-side yellow result panels, each with the query as its column header. The "SQLite 3.54.1" panel returns a JSON object where key "a" has a string value: the array containing 1, wrapped in double quotes. The "SQLite 3.54.0" panel returns a JSON object where key "a" has an actual array containing 1, with no quotes around it.

这也应该适用于所有其他 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 · simonwillison.net