进阶 celld.dev 2026-10-11 10:08:47 · 40 阅读

第18章 第 18 章:Workers 部署原理与请求处理机制

第 18 章 Workers

文档:Workers

Worker 是一种无状态请求处理器,使用 Cloudflare Workers API。 celld 在集群的每个节点上的 V8 isolate 中运行部署。

示例

hello 示例通过 fetch 处理器返回文本响应。

index.js ```javascript export default { async fetch(request, env) { return new Response("Hello from cells! url=" + request.url, { status: 200, }); }, }; ```

wrangler.jsonc ```json { "name": "hello", "main": "index.js", "compatibility_date": "2026-01-01" } ```

API

* `fetch(request, env, ctx)` 是默认导出。它接收传入的 Request 并返回 Response。 * `scheduled` 处理 Cron Trigger,`queue` 处理 Queues 消费者。 * `env` 持有由 Wrangler 配置声明的 bindings。 * `ctx.waitUntil(promise)` 在响应发送给客户端后,让 isolate 保持存活直到该 promise 完成。

查阅 [handlers 文档](#) 获取完整列表。

请求路径

celld 提供纯 HTTP 服务,因此入口代理必须终止 TLS。由于每个节点都持有当前部署,负载均衡器可以将请求发送给任何节点。该节点运行处理器,并将 binding 调用转发给拥有该 cell 的节点。R2 binding 直接读写集群共享存储桶。

Worker 请求在 celld 集群中的运行位置 入口终止 TLS,并将请求发送给集群中的任意节点。接收请求的节点在 V8 isolate 中运行 Worker 部署,并调用 `fetch(request, env, ctx)`。处理器返回 Response。env 对象持有 bindings,binding 调用会离开 isolate:KV 命名空间、D1 数据库、队列和 Durable Object 各自是一个由单个节点拥有的 cell;而 R2 binding 则直接读写共享的集群存储桶。

[图示:HTTP 客户端 -> 入口/负载均衡器 (终止 TLS) -> 任意 celld 节点 (V8 isolate 中运行 Worker, 调用 fetch) -> 返回 Response。Binding 调用指向拥有者节点 (KV, D1, Queues, Durable Objects) 或集群存储桶 (R2)]

主模块的每个导出必须是处理器对象或类,如同 workerd 中那样,因此导出字符串或数字的主模块会启动失败。 celld 在一个 isolate 中并发运行许多请求,并随时废弃 isolate,因此 Worker 必须将状态保存在 binding 中,而不是模块作用域内。

与 Cloudflare 的区别

* celld 不管理自定义域名或终止 TLS。 * `ctx.passThroughOnException()` 无效,因为 celld 没有 CDN。 * celld 不提供 Workers AI binding。进程会拒绝 `CELLD_AI_BINDING` 和 `CELLD_AI_URL`,部署也会拒绝 `ai` 声明。

Cloudflare 兼容性页面列出了 [运行时 API](#) 和 [不支持的服务](#)。

Python Workers

主文件为 `.py` 的 Worker 使用 Cloudflare Python Workers API。相同的项目无需修改即可在 Cloudflare 上运行。celld 支持该平台的一部分,本节列出了这些支持项。

Python 示例使用 SDK 和 vendored 包来处理请求。

pyproject.toml ```toml [project] name = "python-example" version = "0.1.0" requires-python = ">=3.13" dependencies = ["beautifulsoup4"]

[dependency-groups] dev = ["workers-py", "workers-runtime-sdk"] ```

src/entry.py ```python # POST 一个 HTML 页面到 /summarize 以获取其标题和链接。摘要保存在 KV 中, # 键为页面的 SHA-256,GET /summary/ 读取该摘要。 import hashlib import json from urllib.parse import urlparse

from bs4 import BeautifulSoup from workers import Response, WorkerEntrypoint

def summarize(html): soup = BeautifulSoup(html, "html.parser") return { "title": soup.title.get_text(strip=True) if soup.title else None, "headings": [h.get_text(strip=True) for h in soup.select("h1, h2")], "links": [a["href"] for a in soup.select("a[href]")], }

class Default(WorkerEntrypoint): async def fetch(self, request): path = urlparse(request.url).path if request.method == "POST" and path == "/summarize": html = await request.text() digest = hashlib.sha256(html.encode()).hexdigest() summary = summarize(html) await self.env.PAGES.put(digest, json.dumps(summary)) return Response.json({"sha256": digest, summary}) if request.method == "GET" and path.startswith("/summary/"): stored = await self.env.PAGES.get(path.removeprefix("/summary/")) if stored is None: return Response("not found", status=404) return Response(stored, headers={"content-type": "application/json"}) return Response("POST HTML to /summarize\n", status=404) ```

wrangler.jsonc ```json { "name": "python", "main": "src/entry.py", "compatibility_date": "2026-09-01", "compatibility_flags": ["python_workers"], "kv_namespaces": [ { "binding": "PAGES", "id": "example-pages" } ] } ```

构建项目

运行 `uv run pywrangler sync` 将包 vendored 到 `python_modules/`,然后运行 `celld dev .`。构建会拒绝不完整的 Workers SDK (`workers-runtime-sdk`)。 `celld deploy` 会捆绑 Pyodide 运行时、`python_modules/` 以及匹配默认 Wrangler 模块规则的文件(位于 main 目录之下):`.py`、`.txt`、`.html`、`.sql`、`.bin` 和 `.wasm`。Worker 可以在 `/session/metadata` 下打开每个文件,如在 Cloudflare 上那样。运行时不会下载任何内容。

首次构建会从 Pyodide CDN 下载 Pyodide 运行时,并检查每个文件的大小和 SHA-256。后续构建会复用 `$XDG_CACHE_HOME/celld/pyodide-0.28.3`,或 `~/.cache/celld/pyodide-0.28.3`。设置 `CELLD_PYTHON_RUNTIME_DIR` 以使用其他目录;已填充的目录允许构建离线运行。下载在 60 秒无数据时失败。构建需要在 PATH 中有 esbuild,或将 `CELLD_ESBUILD` 设置为其路径。

Python 部署需要 `python-workers-v1` 特性,而 `celld deploy` 不检查节点是否具备该特性。若节点正在运行且缺少该特性,会记录错误并保持当前部署,导致集群同时服务两个版本。若在 Python 部署当前有效时启动一个缺少该特性的节点,该节点会出错退出。在首次 Python 部署之前升级所有节点,并在 Python 部署有效期间不要降级。

运行时版本

celld 运行带有 CPython 3.13.2 和 pyodide_2025_0 wheel ABI 的 Pyodide 0.28.3。Cloudflare 使用 `python_workers_20250116` 选择此系列(它运行带有自身补丁的 Pyodide 0.28.2)。配置必须满足:

* `compatibility_flags` 包含 `python_workers`。 * `compatibility_date` 格式为 YYYY-MM-DD。 * `compatibility_date` 晚于 2026-04-21。若日期更早,必须通过 flag 开启该日期未默认开启的行为: * 2025-08-11 之前需要 `python_workers_force_new_vendor_path` * 2025-08-14 之前需要 `python_no_global_handlers` * 2025-09-29 之前需要 `python_workers_20250116` * 2026-04-21 之前需要 `enable_python_external_sdk` * `compatibility_date` 早于 2026-09-08,或者 flags 包含 `no_python_workers_314`。从 2026-09-08 起,Cloudflare 运行 Pyodide 314 (Python 3.14),这需要针对不同 ABI 的 wheel。

celld 在部署时拒绝其他设置。`python_process_pth_files` 遵循其兼容性日期 (2026-05-26)。

支持情况

| API | 备注 | | :--- | :--- | | `Default(WorkerEntrypoint).fetch` | 每个请求一个实例,与 Cloudflare 一致 | | `workers.Response`, `Response.json`, request 正文、文本和头部 | 在测试中与 workerd 进行比较 | | `workers.fetch` | 出站 HTTP | | `self.env` bindings | 使用 KV 测试。其他 bindings 是 JavaScript Worker 获得的对象,未在 Python 中测试 | | `self.ctx.waitUntil` | Python awaitables 保持存活直到完成 | | `python_modules/` 中的纯 Python 包 | 使用 beautifulsoup4 测试 | | `from js import ...` | isolate 的 JavaScript 全局变量 |

不支持

* 用 Python 编写的 Durable Objects、Workflows、Cron Triggers 和 Queue 消费者。`celld deploy` 会拒绝声明这些项的 Python 项目。 * 命名入口点类和到 Python 方法的 RPC。 * 带编译扩展(.so 文件)的包,以及 Pyodide 作为单独分发包提供的标准库模块:`ssl`、`sqlite3`、`lzma` 和基于 OpenSSL 的 `hashlib` 算法。 * 除 `cloudflare:workers` 和 `cloudflare:sockets` 外的模块使用 `pyodide.ffi.run_sync` 和 `workers.import_from_javascript`。celld 隐藏 WebAssembly 堆栈切换 (JSPI),因为在 JSPI 下每个异步入口都会泄漏 C 堆栈,直到解释器停止。 * 在 Python Worker 中调用 `process.exit()` 会抛出错误。 * 内存快照和 `_cloudflare` 包的导入补丁。需要这些补丁的包补丁(如同步 FastAPI 处理器)不会应用。

故障行为

解释器在针对 isolate 的第一个请求时启动,并发的首个请求共享该启动过程。如果主模块引发错误,发往该 isolate 的所有请求都会因相同的 traceback 而失败。 致命的解释器错误(如 C 堆栈溢出)会导致该 isolate 正在运行的所有请求失败。随后 celld 会替换 isolate,如同 Cloudflare 所做,使下一个请求可以等待新的解释器。

本篇用到的工具

评论 (0)