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

第7章 celld 的核心保证与存储要求

文档 celld 提供哪些保证

celld 有两条承诺。任一时刻恰好只有一个节点服务某个 cell,因此不会有两台机器写同一个数据库。celld 在写入经受住故障之前不会确认它,因此被确认的写入永不丢失。这两条承诺都要求 bucket 具备可用的条件写入和范围读取,以及一个能重启进程的 supervisor。

bucket 必须提供什么

  • 条件创建:对象已存在时写入必须失败。
  • 条件覆盖:读取之后对象发生变化时,写入必须失败。
  • 写后读一致性:成功写入之后的读取必须返回该写入。
  • 范围读取:读取必须返回请求的字节范围和该范围内的字节。
  • 仅针对 epoch GC(CELLD_LTX_RETENTION_SECS)需要列后写一致性:成功写入之后的列取必须包含写入的对象。Amazon S3、Cloudflare R2、Google Cloud Storage 和 Azure Blob Storage 提供此特性。Tigris Global 或 Dual-region bucket 仅在写入所在区域提供此特性,因此当 fleet 节点分布在多个区域时,不要在 Tigris 上启用 epoch GC。

合格的存储包括 Amazon S3、Cloudflare R2、Tigris、Google Cloud Storage 和 Azure Blob Storage。发布测试针对 R2 运行;S3 路径使用相同的客户端和请求头。Azure 于 2026-08-18 完成单节点验证,使用账户密钥、VM 托管标识和 AKS 工作负载标识。Azure App Service 或 Azure Container Apps 上的托管标识不可用,参见限制说明。

Backblaze B2、Hetzner Object Storage 和 DigitalOcean Spaces 没有实现所需的条件写入,因此在这些存储上可能有两个节点同时拥有一个 cell。接受条件请求头却忽略条件的存储会延迟且无声地失败,所以请运行存储测试。

MinIO(社区版)能通过存储测试,但未在生产环境验证。RELEASE.2025-09-06T17-38-46Z 对不存在对象的条件创建会返回 NoSuchKey,导致首次部署失败(denoland/celld#162)。请使用 RELEASE.2025-09-07T16-13-09Z 或更高版本。

gs:// bucket 使用 Cloud Storage XML API,配合 x-goog-if-generation-match 和 OAuth 凭据,因为 Cloud Storage 不对 PUT 应用 If-Match。对于 az:// bucket,NAME 即容器名。

存储测试

celld diagnose 向 bucket 发送四次条件写入:

ok bucket conditional write(创建、拒绝创建、更新、拒绝过期写入)

四次中必须有两次失败;如果存储接受了任何一次本应失败的操作,命令会报错退出并指明该存储。如果凭据只有只读权限,使用 celld diagnose --read-only。

每个节点在开始服务之前都会执行同样的写入,然后读取第二个对象的某个范围并验证范围和字节。节点无法关闭这个测试。当操作失败且原因不明时,它会用新对象最多重试三次;之后节点带着警告启动,因为临时故障可能会自行恢复。当必需的条件写入或范围读取不受支持、存储忽略条件或 Range 请求头、或返回错误的范围或字节时,节点会立即停止。

测试中途停止的进程可能在 probe/ 下留下小对象;celld 永远不会读取它。

celld 保留 probe/、cells/、nodes/、node-cells/、fleet/、deploy/、deploy-blobs/、log/、wake/ 和 telemetry/ 这些命名空间,并会删除其中一部分下的对象。应用不得在这些命名空间下写入。

supervisor

请在能重启进程的 supervisor 下运行 celld,例如 systemd、带重启策略的 Docker 或 Kubernetes。节点失去租约后会自我隔离并退出,如果没有重启机制,fleet 就会损失这部分容量。supervisor 必须无次数限制地重启,且两次尝试之间至少等待一个租约周期。

机制

所有权记录

每个 cell 在 bucket 中有一条所有权记录,记录所有者节点的会话并携带一个 fencing epoch。当记录不存在时,节点通过条件创建获取 cell;记录已存在时则通过 compare-and-swap 获取,因此两个节点不可能获取同一个 cell。每次激活——无论是接管还是本地唤醒——都会推进 epoch,因此一个 epoch 不会有两个写入者。

epoch 前缀

replicator 用无条件 PUT 把每个 cell 的 SQLite 数据复制到 cells/<cell>/ltx/e<epoch>/。键中的 epoch 就是围栏:失去所有权的节点可以继续写入,但只能写入已被取代的前缀,恢复时会选择当前谱系。分层路径可以先把多个 cell 的 segment 合并成一个节点 bundle,稍后再把每个 segment 排入各自的 per-cell 前缀。只有当 per-cell 前缀覆盖了 bundle 中的每个 segment 时,bundle 才会被删除。失败的 compaction 会在 30 秒后重试,退避上限为 300 秒。

确认规则(RPO=0)

gate 会扣住每个响应,直到持久化证明覆盖它能揭示的所有写入:写入响应;对象存在未被覆盖的已提交写入时的只读响应;错误响应(抛出的消息可能携带 handler 读到的值);R2 变更(避免在源写入持久化之前改变应用 bucket);原生 TCP 的 connect、write、TLS 升级或 shutdown;以及流式 body 的每个 chunk。因此客户端不会基于一个仍可能因崩溃而丢失的值采取行动。

拿到 bucket 证明后,celld 会读取一次所有权记录,仅当记录仍然指向本节点和本 epoch 时才确认。分区的节点可以在本地提交并复制到自己已被取代的前缀,但不会确认。

这个检查读的是记录而不是时钟,因此暂停的进程或走偏的时钟无法绕过它。

fleet 证明不需要这样的读取。所有者把每个写入发给一两个其他节点,即它的 follower(合称 ensemble),每个 follower 都必须 fsync 该写入。接管会在恢复前封存先前的节点日志会话,因此过期的所有者无法完成另一次 fleet 证明。

未完成的 SQL 写入游标可能在 SQLite 提交之前就返回行。在显式事务之外,应用必须在输出或 storage.sync() 之前消费完这些行;写入游标未完成时,celld 会拒绝输出。

ensemble 需要两个节点

节点从不把自己算作 follower,而一个 follower 就够了,因此 fleet 在任何节点完成 fleet 证明之前至少需要两个运行中的 celld 节点。CELLD_DURABILITY=fleet 是默认值,所以单节点 fleet 会请求 fleet 姿态却得不到它。

一个节点最多招募两个 follower,因此三个或更多节点的 fleet 会为每个被确认的写入保留三份副本。只要还剩一个 follower,ensemble 就能继续确认。只有一个 follower 的节点会在其他节点可用时招募第二个。在此之前,尚未写入 bucket 的数据只存在于所有者和那一个 follower 上。

没有 ensemble 的节点仍然是正确的。它改为依靠 bucket 证明来确认每个写入,代价是延迟:对象存储的往返比 follower 的 fsync 慢得多。

接管恢复门

fleet 模式下,celld 可能在 bucket 上传完成之前就确认写入。因此每个进程会话都会在其第一次 fleet 持久化确认之前创建一条条件节点日志记录。

冷激活会在读取 bucket 之前检查先前所有者的日志记录。记录不存在证明该会话从未确认过 bucket 之外的写入;已封存的记录证明恢复已完成。记录处于打开或恢复中状态会强制在恢复之前先做恢复:用 compare-and-swap 封锁该记录、封存可达的 follower、把它们保留的 segment 和 bundle 上传到 per-cell 前缀,然后把记录标记为已封存。

cell 可能在其节点会话仍打开时停止;它的下一次激活会收集 per-cell 前缀之外任何被确认的尾部。一旦日志 epoch 处于活跃状态(在其第一次 fleet 证明之前),至少要有一个当前 follower 返回其完整的保留范围,否则激活失败并保持恢复要求。

恢复有以下限制:

  • follower 的 HTTP 错误不能证明其数据不存在,即使其租约已过期,因此持续错误可能阻塞恢复和启动。
  • 重启后的 follower 在有效数据覆盖损坏的批次或缺口之前,无法认证该范围。
  • 较旧节点的仅条目尾部(CLT1)既不能证明完整也不能证明丢失,因此在混合版本更新期间,恢复或启动可能停滞。
  • 如果没有任何后续批次或持久化的结束记录其范围,被删除的最后一个批次无法被发现。
  • 包含未被确认写入的残缺批次在确认之后看起来像损坏,因此损失记录可能在没有任何被确认写入丢失的情况下报告一个未认证的范围。

重启中的节点会在自己的前代恢复完成之前,服务已认证的 follower 封存和尾部请求,因此一起重启的节点可以从存活的 follower 磁盘恢复被确认的写入。只有启动完成后它才接受应用请求和新的 follower 追加。

恢复一个大型死亡节点可能需要几分钟。它以最多 512 MiB 的窗口读取保留的 bundle,并在进入下一个窗口之前上传并释放当前窗口,因此内存不随会话增长;行分布在多个窗口的 cell 每个窗口收到一个对象。失败或超时的尝试不会让等待中的请求失败:cell 以退避方式重试(CELLD_RECOVERY_RETRY_MS,默认 1000),只有在 CELLD_RECOVERY_RETRIES(默认 240)次尝试之后,请求才以 resolve 错误失败。

epoch 链恢复

恢复会把包含 LTX 数据的 epoch 前缀串成一条链,从最新往下追溯到以整库快照开启的 epoch。通过分页载入的 epoch 会从其分页起点接续前代;没有恰好结束于该起点的前代不属于这条链。遗留的 e<epoch>.seal.json 对象不会限制这条链。

分页 cell 不会预先读取整条链。它在稀疏本地文件上打开,首次使用时从对象中读取每一页,其余部分在后台填充;填充完成的 cell 只读本地文件。小于 CELLD_LTX_PAGED_MIN_MB 的链会整体下载。

epoch GC

当 CELLD_LTX_RETENTION_SECS 为正数时,cell 的所有者会删除不再被任何恢复读取的 epoch 前缀,在两种 CELLD_DURABILITY 模式下均如此:

  • 它先在所有 epoch 前缀上构建链,并且仅当最新 epoch 是自己的才继续。这样它的第一个对象必在列取结果中,因此后续所有者可以从相同或更高 epoch 的 base 恢复。
  • 分页 cell 会等到本地文件完整。
  • 仅当所有权记录指向本节点和本 epoch 时才继续。
  • 它写入包含 base 的 retired.json,然后删除 base 之下的前缀,保留自己的 epoch、前一个 epoch,以及所有在配置时限内的 epoch。

顺序很重要:否则被围栏的所有者可能删掉其继任者的 base。迟到的删除是安全的,因为 base 之下的 epoch 永远不会重新加入链。这依赖列后写一致性。

被围栏的节点可能向更旧的前缀追加未被确认的尾部。在快照继任者之后,后续恢复可能暴露该尾部;这不违反契约,因为缺少确认不能证明写入不存在。在分页继任者之后,链会在分页起点截断更旧的前缀,且接管恢复门会在继任者恢复之前封存先前的节点日志会话,因此分页起点之后的写入不可能被确认。

自我围栏

每个节点在 bucket 中持有一条带过期时间的租约,在生命周期的三分之一后续期(CELLD_TTL_MS,默认 10000 ms)。只要已发布的过期时间未过,续期失败就会重试。

过期时间一过,节点就自我围栏:停止每个活跃的 cell,并使所有未完成的请求失败。当租约记录消失或不再匹配自己发布的内容时,节点也会立即围栏。围栏不写任何东西;对端早已把该租约读作死亡或被替换,并通过所有权记录获取 cell。celld 在每次路由请求时都检查已发布的过期时间,因此即使在围栏运行之前,请求也是安全的。

ingress 会在每个新请求上把缓存的远程路由与观测到的租约截止时间比对,并在截止时刻重新读取所有权,即使旧所有者仍保持连接。恢复仍然需要 bucket 和所需的持久化数据。正在排水的 ingress 可以转发给存活的远程所有者,但拒绝为无主或所有者已过期的 cell 获取新的所有权。ingress 不会重放已发给旧所有者的请求,因为 handler 可能已提交写入;调用方可以取消它。

被围栏的节点会记录一行以 SELF-FENCE: 开头的日志并以退出码 3 退出。其他内部故障也共用这个前缀和退出码;日志行会指明原因:node_lease_watchdog_fence(过期)、node_lease_record_missing_fence,或 node_lease_record_mismatch_fence(不指明作者,因为节点无法证明记录是谁写的)。被围栏的状态是终态:只有重启才能让节点通过正常的冷激活路径回归。测试页面展示了这条路径的 kill 测试。

RUST_LOG=celld=info,store=debug 会对针对节点自身租约记录的每次存储请求记录 node_lease_read 或 node_lease_write 事件,结果为 found、missing、applied、rejected 或 error。error 携带 error 字段中的存储故障;found 携带记录的 generation。其他过滤级别下这个目标没有开销。

alarm 发现与 wake 格式

SQLite 存储 alarm 的截止时间、消费状态、重试状态和安装标识。alarm 提示只会让 celld 去读 SQLite,绝不会授权 handler 运行。

每个已提交的安装都在 wake/entries/ 下有一个对象,由所有权 epoch 和一个持久的 SQLite 序列标识。alarm 响应会等待其发布 PUT 和输出证明;同一分钟内的更新还需要一次新的 PUT。

清理通过条件写入在 wake/retired/ 下发布退役记录。该记录需要持久化证明、当前所有者,以及如果 alarm 仍然处于布防状态,还需一个已确认的替代发布。清理只删除更旧的标识或已证实被消费的标识,因此旧的 DELETE 不可能移除后来的安装,bucket 也不需要条件 DELETE。删除过时发布不会阻塞 alarm 响应。

每轮清理最多列取 128 个对象,最多并发处理八个 cell,在下一轮继续列取并在最后一页之后重新开始。一次失败的 DELETE 或迟到的 PUT 可能需要再来一次完整扫描。间隔默认 60 秒;CELLD_WAKER_TICK_MS 同时设置它和到期扫描间隔。大型清单可能耗费多个间隔,且每个额外节点可能重复同样的读取和删除。

wake/format.json 选择格式 2;wake/waker.json 保存 waker 角色的咨询性租约。新节点会自动初始化空 fleet 或升级已停止的 v0.4.1 fleet。不支持的格式,或旧的 wake-format.json、wake-v2/、wake-retired-v2/ 命名,会阻止启动。保留命名空间之外的应用对象则不受影响。

以此格式启动 fleet

空 fleet 会自动初始化此格式。从 v0.4.1 升级会保留 bucket 和节点数据目录,但需要先停止 fleet,因为 v0.4.1 无法读取新的发现条目。

  • 停止应用流量和部署写入。停掉所有旧节点及其 supervisor,然后等待每个节点租约过期。
  • 备份 bucket 和节点数据。保留节点名、peer 地址和数据目录。follower 磁盘上可能有 bucket 尚未持有的被确认写入。
  • 阻止旧二进制重启或写入 bucket:吊销其凭据或访问权。格式标记无法阻止它们。
  • 在每个节点上用相同的配置、数据和地址启动新二进制。等待 fleet 变为健康,然后恢复流量。

节点可以同时启动。活跃的节点租约会阻塞迁移,运维必须防止旧写入者回来。

迁移会保留数据库、节点日志、所有权记录、部署和应用对象。它为每个已存储的 cell 创建发现种子,每页最多 128 条。种子让恢复从 SQLite 推导安装标识,而不改变截止时间或重试状态;只有在持久化恢复完成后才移除种子,因此中断的迁移不会丢弃 alarm。恢复可以在处理种子时加载带有未来 alarm 的 cell。如果节点在迁移中途停止,另一个启动中的节点会接续它。完整清单成功之前不会有节点提供服务,因此 alarm 可能延迟运行。之后的启动不会再迁移。

要回滚,请恢复停止状态的完整 fleet 备份;绝不要对已升级的 fleet 启动旧二进制。恢复会丢失备份之后的写入,请单独保存这些写入。

重启和所有权转移会保留 alarm 历史。每个恢复的写入者会取得新 epoch,并保留已存储的序列和消费状态,因此旧的变更不可能指向后来的安装。

本篇用到的工具

评论 (0)