第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 的保证和局限性。