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

第3章 第 3 章:celld 安全机制与网络边界详解

文档安全

celld v0.6.2 为 Beta 版本。严禁在互不信任的多租户环境中使用。

仅最新发布的版本会提供安全修复。

安全边界

一个 Fleet 运行一个应用程序。celld 信任应用代码、Fleet 节点以及操作员。应用代码可以使用其配置的绑定(bindings),并消耗共享的节点资源。切勿在一个 Fleet 中运行来自互不信任租户的代码。

应用代码无法访问引擎的主机函数(host functions)。内部脚本将这些函数作为参数接收,且 globalThis 上不存在任何以 __ 为前缀的属性。因此,设置了 globalOutbound: null 的 Worker Loader worker 只能通过其 env 中的能力(capabilities)访问主机。

celld 依赖两个外部边界:受信任的私有网络保护内部监听器,对象存储凭证控制 Fleet。

分离监听器

celld 开启两个 HTTP 监听器,且均不终止 TLS。

监听器 服务对象 所需保护
--listen(公共) 已部署的 Worker 在代理或应用层面终止 TLS 并对用户进行认证。
--internal-listen(默认 127.0.0.1:0,一个空闲的环回端口) 对等协议(peer protocol)和操作员 API 限制访问权限,仅允许受信任的操作员和 Fleet 节点访问。切勿向公网暴露。若网络不提供机密性,请使用 WireGuard 或 Tailscale 等加密覆盖网络。

--advertise 将内部地址提供给对等节点。如果没有显式指定 --internal-listen,celld 会拒绝显式的 --advertise 或非环回的 --listen。由于 celld 无法验证主机名或翻译后的端口,你必须将通告的地址路由到内部监听器。

公共监听器仅保留 /.well-known/celld/health:健康时返回 200 和 {"ok":true},否则返回 503。Worker 拥有其他所有公共路径的控制权,包括 /health。内部监听器对未知路径返回 404,因此操作员请求不会变成应用请求。

内部监听器包含三组请求,这三组请求均要求处于受信任的私有网络中:

  • 大多数操作员路由没有请求认证。
  • /peer/tunnel 为 cell 获取、RPC 和 WebSocket 调用开启隧道。建立请求携带 Fleet HMAC、时钟限制和重放保护。隧道内部的调用是未经签名的普通 HTTP。
  • Peer-control 和保留 cell 路由使用 Fleet HMAC、时钟限制和重放保护对每个请求进行签名。

因此,通往运行时类的每条路径都需要 Fleet 密钥。HMAC 不对建立后的隧道字节进行认证,也不加密流量,因此它不能替代私有网络。

使用内部操作员 API

操作员 API 是 Alpha 接口。版本发布可能会更改其路径或响应格式。这些路由不对调用者进行认证:

  • /state 报告节点状态。
  • /cell/<SCOPE> 解析或激活一个 cell。
  • /evict/<SCOPE> 尝试驱逐驻留的 cell 并报告结果。
  • /do/<ID> 向普通 Durable Object 发送直接请求。
  • POST /shutdown 开始优雅的所有权交接。handoff=preserve 为同节点重载做准备。

/do/<ID> 拒绝所有保留的运行时类,例如 D1、Workflows、KV 和 Queues,因为其协议可以访问应用数据。对于这些类,请使用经过 HMAC 认证的 /runtime/<SCOPE> 路由。

/peer/probe 返回签名的诊断响应。不要直接调用其他保留的 peer 路径。

读取驱逐结果

被接受的驱逐操作会等待操作完成,而被拒绝的则立即返回。并发调用者可以加入同一次驱逐,因此成功计数不等于停止计数。

Rust 方法 AppHandle::evict 返回 Result<EvictSuccess, EvictError>。Evicted 确认运行时已停止,AlreadyAbsent 确认本地已不存在。需要确认驱逐完成的调用者必须检查是否为 Evicted。通过 HTTP,两者都返回 200 和 {"ok":true}。错误上的 kind() 和 reason() 与 HTTP 错误响应体匹配。在响应到达之前,后续请求可能会重新激活该 cell。

缺失的 cell 或已处于 Inactive、Dormant 或 Remote 状态的 cell 在本地视为不存在。待处理的激活、停止或所有权转移会阻止该结果。该请求不会驱逐远程运行时。休眠的 cell 保留其所有权及休眠的主机套接字。节点在保存、重载或本地清单确认期间,或缺乏权限时会拒绝请求。

错误响应体格式如下:

{"ok":false,"error":{"kind":"refused","reason":"cell_active"}}
状态码 类型 原因 起因
409 refused cell_active Cell 有活跃的工作或需要运行时的套接字。
409 refused cell_transitioning Cell 有另一个生命周期转换。
409 refused alarm_imminent 警报驻留策略保留该 cell。
409 refused alarm_uncovered 警报覆盖未确认,或在压力丢弃期间,触发的警报阻止了驱逐。
503 refused node_unavailable 节点无法接受驱逐。
503 refused eviction_limit 节点已达到其驱逐并发限制。
409 cancelled new_activity 新请求取消了已接受的驱逐。
409 cancelled alarm_activity 警报观察或触发取消了已接受的驱逐。
409 cancelled node_fenced 节点在驱逐过程中失去了权限。
503 failed actor_unavailable 请求无法到达 Actor。
500 failed reply_lost 已送达的请求丢失了回复,因此结果未知。
500 failed durability_failed 持久性验证失败。
500 failed durability_timeout 持久性验证超出了操作截止时间。
500 failed runtime_stop_failed 运行时停止报告了失败。

格式错误的范围返回 400。错误并不证明运行时仍然驻留。运行时停止没有整体超时,因此一个永远不返回的停止操作会使请求保持挂起状态。

设置转发头策略

celld 默认忽略 X-Forwarded-Host 和 X-Forwarded-Proto。仅当受信任的代理替换这两个头时,才设置 --trust-forwarded-headers 或 CELLD_TRUST_FORWARDED_HEADERS=1。celld 使用每个头中的最后一个值,因此较早的客户端值无法覆盖代理值。

celld 从请求目标中获取路径和查询,并忽略绝对形式目标的 scheme 和 authority。如果没有受信任的代理,Host 头将设置 request.url 中的主机名。celld 接受主机名、IPv4 地址或带括号的 IPv6 地址,端口可选。它会拒绝格式错误和非规范的值,并回退到 celld.local。

主机名仍然由客户端控制。不要将未检查的主机名用于授权决策。请使用受信任的代理,或在 Worker 中将主机名与列表进行比对。

限制请求体

公共监听器和 /do/<ID> 默认将请求体限制为 1 GiB。设置 CELLD_MAX_REQUEST_BODY_BYTES 为较小的正整数以降低此限制。对于声明的超大请求体,以及当 Worker 读取超出限制时,celld 返回 413。

对于除 GET 或 HEAD 以外的方法,/do/<ID> 会对未知长度或至少 1 MiB 的请求体进行流式处理。它会在分发前收集较小的请求体。

保护 Fleet 存储桶

Fleet 存储桶是权限的根源。它存储部署、cell 状态、所有权和节点租约,以及共享的对等认证密钥。持有存储桶凭证的人控制着整个 Fleet。每个凭证仅应允许访问一个 Fleet 存储桶,并在怀疑泄露后轮换凭证。

Cell 所有权

每个 cell 是一个具有单个写者的 SQLite 数据库。所有权纪元(ownership epoch)对每个 cell 进行围栏控制(fencing),因此失去租约的节点无法修改当前状态。这种围栏保护存储一致性。它并不隔离恶意应用。参见 celld 的保证和局限性。

本篇用到的工具

评论 (0)