denoland/celld

来源：https://github.com/denoland/celld

celld

自托管、分布式的 Durable Objects。

celld 是一个开源的守护进程，可以在你自己的机器上运行 Cloudflare Workers 和 Durable Objects。每个对象都是一个独立的 SQLite 数据库，按名称寻址，并复制到你拥有的兼容 S3 的存储桶；节点仅通过该存储桶协调，不需要控制平面或共识机制。由于每个对象都是自己的小型数据库，应用天然分片——单个共享数据库的争用和故障影响半径被设计掉，而不是被管理。空闲的单元会休眠到几乎不占资源。了解更多请访问 celld.dev（https://celld.dev）或阅读文档（https://celld.dev/docs）。

工作原理

每个 celld 节点都内嵌 V8 并执行 Wrangler bundle。整个集群共享一个兼容 S3 的存储桶，其中包含部署、单元状态和小型所有权记录。对象存储的比较并交换（compare-and-swap）确保同一时间只有一个节点拥有某个单元，而无需成员协议、故障检测器或共识服务。

celld 会持续将每个单元的 SQLite 数据库复制到存储桶。当单元迁移或唤醒时，其新所有者会恢复该数据库并继续执行。存储桶是持久化的唯一事实来源；节点是可替换的。

安装

安装程序会下载 celld 二进制文件（可通过 gh attestation verify 验证来源）：

sh curl -fsSL https://celld.dev/install.sh | sh

如果安装程序提示，请将 ~/.local/bin 加入 PATH。

使用 celld deploy 部署的 Worker 项目需要 PATH 中包含 esbuild（https://esbuild.github.io）；仅含静态资源的项目则不需要。

安装程序将已验证的发布版本保存在 ~/.local/lib/celld/releases 下，并原子地切换一个 current 指针。要卸载 celld，请使用带保护措施的卸载程序：

sh curl -fsSL https://celld.dev/uninstall.sh | sh

容器

发布镜像包含 celld 二进制文件，并发布适用于 Linux x86-64 和 ARM64 的版本：

sh docker run --rm ghcr.io/denoland/celld --version

持久化运行时的本地状态，并传入标准 AWS 凭证环境变量：

sh docker volume create celld-state docker run --rm --network host \ -e AWS_ACCESS_KEY_ID \ -e AWS_SECRET_ACCESS_KEY \ -e AWS_SESSION_TOKEN \ -e CELLD_WATCH=/var/lib/celld/state \ -v celld-state:/var/lib/celld \ ghcr.io/denoland/celld \ --bucket s3://my-cells-bucket \ --endpoint https://ACCOUNT.r2.cloudflarestorage.com \ --region auto \ --listen 0.0.0.0:8080 \ --advertise node-a.internal:8080

使用真正的 AWS S3 时，去掉 --endpoint/--region。在负载均衡器后面，为每个节点指定一个其同级节点可以访问的独立 --advertise 地址。

运行

celld 使用标准的 AWS 凭证链。先部署到兼容 S3 的存储桶，然后针对同一存储桶启动 celld：

``sh celld deploy .
–bucket s3://my-cells-bucket

celld
–bucket s3://my-cells-bucket
–listen 0.0.0.0:8080
–advertise 10.0.0.12:8080 ``

对于其他兼容 S3 的服务，请使用 --endpoint；当无法推断时，请使用 --region。一个集群运行同一个应用，每个节点从 deploy/current.json 加载其最近一次成功提交的部署。运行 celld --help 查看完整的命令行。 部署对象使用 crates/celld/protocol.rs 中记录的文档化类型。celld deploy 会从 PATH 调用 esbuild 来处理 Worker 代码，接受受支持的 Wrangler 配置子集——包括协同部署或纯静态资源——并直接写入这些对象。每个节点都通过存储桶租约发现所有者和同级节点；没有账户或加入服务。

对等 HTTP 不终止 TLS。请将所有通告地址放在受信任的私有网络或加密覆盖网络（如 WireGuard 或 Tailscale）上；不要直接公开对等端口。直接使用公网 IP 会被拒绝，除非显式提供 --unsafe-public-advertise。第一个当前节点会在存储桶中创建 fleet/peer-auth.json。所有对等请求都带有协议版本、绑定请求体、使用 HMAC 认证、受时钟限制，并通过集群密钥进行重放保护。请将对存储桶及其凭据的访问视为集群管理员访问。

操作集群

celld diagnose 默认枚举所有节点租约，然后对每个在线同级节点执行带签名的直接探测：

sh celld diagnose --bucket s3://my-cells-bucket

报告会在单个失败后继续检查，并区分过期记录、格式错误或不安全的通告地址、不可达的同级节点以及不兼容的协议。它还会打印每个节点的粗略驻留单元、WebSocket、RSS、CPU、文件描述符、压力和卸载（shedding）采样。传入一个或多个 --peer NODE_ID 选项可限制检查范围。

在首个版本的安全默认值仍在测量期间，压力卸载是可选加入的。请在负载较高的节点上设置驻留单元的高、低水位线：

sh CELLD_MAX_RESIDENT_CELLS=1000 \ CELLD_RESIDENT_LOW_WATER=800 \ celld --bucket s3://my-cells-bucket --listen 0.0.0.0:8080 \ --advertise node-a.internal:8080

在 Linux 上，CELLD_MAX_RSS_MB 和 CELLD_MAX_CPU_PERCENT 会增加进程内存和 CPU 触发条件；驻留单元水位线是可移植的。在压力下，celld 会持久化复制并隔离（fence）最近最少使用的空闲单元，将它们发布为无主状态而不重置其 epoch，并拒绝重新获取新的无主单元，直到达到低水位线。备用节点不会收到分配：当正常流量到达时，它通过相同的存储桶协议获取已释放的单元。有活跃工作或存在在线主机 WebSocket 的单元不会被卸载。

从源码构建

sh cargo build --locked cargo test --locked cargo clippy --all-targets --locked -- -D warnings

工作区会构建 celld 运行时。其版本化的对象存储协议位于 crates/celld/protocol.rs。examples/ 下的小型 Wrangler 项目用于测试受支持的 Worker 和 Durable Object 接口。

运行时和兼容性接口仍在演进中。公共测试覆盖独立引擎冒烟路径；每次发布前都会针对 Workers 和 Durable Objects 参考行为进行一致性测试，并在故障注入下对分布式协议进行确定性模拟。

贡献

禁用拉取请求。编码代理让发送大型、缺少上下文的变更变得过于容易，而这种变更给维护者带来的时间成本远大于其节省的时间。欢迎深思熟虑的贡献；请理解代码，保持补丁聚焦，并尊重你所请求的审查时间。

将 git format-patch 附件发送至 [email protected]。

贡献者许可协议：通过电子邮件发送补丁，即表示你证明你有权提交该补丁，并将你所能转让的所有权利转让给 Deno Land Inc.。对于无法转让的权利，你授予 Deno Land Inc. 一项永久、不可撤销、全球范围、免版税、可转让、可再许可的许可，以使用、修改、合并、再许可、再分发或发布补丁的全部或部分，无论是否署名。

许可证

Apache-2.0

在运行公共集群之前，请阅读限制和安全页面。