跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

Durable Object 的生命周期

最后更新 查看 MarkdownAgent 设置

本节描述 Durable Object 的生命周期。

要使用 Durable Object,您需要创建一个 Durable Object Stub。 仅创建 Durable Object Stub 并不会向 Durable Object 发送请求,因此 Durable Object 尚未实例化。 只有在 Durable Object Stub 上调用方法后,请求才会发送到 Durable Object,其生命周期才开始。

const stub = env.MY_DURABLE_OBJECT.getByName("foo");
// Now the request is sent to the remote Durable Object.
const rpcResponse = await stub.sayHello();

Durable Object 生命周期状态转换

Durable Object 在任意时刻可处于以下状态之一:

状态 描述
活动状态,位于内存中 Durable Object 在内存中运行并处理传入请求。
空闲状态,位于内存中且不可休眠 Durable Object 等待下一个传入请求/事件,但不满足休眠条件。
空闲状态,位于内存中且可休眠 Durable Object 等待下一个传入请求/事件且满足休眠条件。何时让 Durable Object 休眠由运行时决定。目前在此状态下不活跃 10 秒后会休眠。
已休眠 Durable Object 从内存中移除。已休眠的 WebSocket 连接保持连接。
非活动状态 Durable Object 完全从宿主进程中移除,可能需要冷启动。这是所有 Durable Objects 的初始状态。

以下是 Durable Object 在这些状态之间的转换方式(每个状态以圆角矩形表示)。

Durable Object 生命周期

假设 Durable Object 未在运行,第一个传入请求或事件(如 alarm)将执行 Durable Object 类的 constructor(),然后运行被调用的相应函数。

此时 Durable Object 处于 active in-memory 状态。

所有传入请求或事件处理完毕后,Durable Object 会在内存中空闲数秒,处于可休眠或不可休眠状态。

仅当所有 以下条件均满足时,才能发生休眠:

  • 未设置 setTimeout/setInterval 计划回调,因为休眠后无法重建回调。
  • 没有未完成的 I/O 操作或传给 this.ctx.waitUntil() 的 Promise,也没有保持打开的出站连接。
  • 未使用 WebSocket 标准 API。
  • 没有仍在处理的请求/事件,因为休眠意味着丢失本应最终向该请求返回响应的 async 函数。

在无传入请求或事件 10 秒且满足上述所有条件后,Durable Object 将转换到 hibernated 状态。

如果上述任一条件不满足,Durable Object 仍保留在内存中,处于 idle, in-memory, non-hibernateable 状态。

如果在 hibernated 状态下有传入请求或事件,constructor() 将再次运行,Durable Object 将转换到 active, in-memory 状态并执行被调用的函数。

在 idle, in-memory, non-hibernateable 状态下,不活跃 70-140 秒(无传入请求或事件)后,Durable Object 将完全从内存中驱逐,可能从 Cloudflare 宿主中移除,并转换到 inactive 状态。

hibernated 状态的对象保持 WebSocket 客户端连接,运行时决定是否以及何时将对象转换到 inactive 状态(例如决定将对象迁移到不同宿主),从而重启生命周期。

下一个传入请求或事件再次启动循环。

关闭行为

Durable Objects 偶尔会关闭并重启对象,这将运行您的 Durable Object 类构造函数。这可能由多种原因引起,包括:

  • 使用 immediate 代码更新策略的 Worker 代码更新,或达到 max_delay 的 deferred 策略
  • 根据上述状态转换,对象长时间无请求
  • Cloudflare 对 Workers 运行时系统的更新
  • Workers 运行时关于对象托管位置的决策

Durable Object 关闭时,对象实例会自动重启,新请求会路由到新实例。进行中的请求处理方式如下:

  • HTTP 和 RPC 请求:如果进行中的请求不访问 Durable Object 的存储,则允许完成。如果请求尝试访问 Durable Object 的存储,将立即停止并返回错误,以维护 Durable Objects 的全局唯一性属性。Workers 运行时系统更新时,进行中的请求最多有 30 秒完成时间。
  • WebSocket 连接:Durable Object 关闭时,WebSocket 连接会自动终止。这可让新实例尽快接管连接。
  • 其他调用(email、cron):其他调用与 HTTP 请求类似处理。

务必确保使用 Durable Objects 的任何服务都设计为能够处理 Durable Object 可能被关闭的情况。

代码更新

部署新的 Worker 版本不会因代码更新策略而延迟,部署本身会立即完成。代码更新策略控制的是每个已活跃的 Durable Object 何时采用新版本。

deferred 代码更新策略会给活跃的 Durable Object 留出时间,使其在采用新代码前进入休眠。对象可以继续使用当前代码处理请求、存储操作和 Hibernation API WebSocket。如果达到 max_delay 时对象仍处于活跃状态,它就会重置并采用新代码。延迟更新只是尽力而为:它不保证所有操作都能完成,也不能保证对象不会提前重置。

要配置代码更新策略并了解它与渐进式部署的交互方式,请参阅 Durable Objects 代码更新。

无关闭钩子时的处理

Durable Object 会在变为非活动状态、代码更新策略应用新代码,或 Cloudflare 部署新版 Workers runtime 时关闭。immediate 策略会立即应用更新。deferred 策略会为对象提供最长为 max_delay 的休眠时间,但这只是尽力而为,对象可能更早重置。这与其他计算环境类似:计算实例不会永久运行,应用必须将状态持久化到数据库或存储系统。不要依赖并不存在的关闭钩子,而应让应用以增量方式写入状态。

Cloudflare 不提供在关闭前运行的关闭钩子或生命周期回调,因为无法保证这些钩子在所有情况下都会执行,而且外部软件可能会过度依赖这些不可靠的钩子。

不要依赖关闭钩子。你可以定期写入存储,以便在关闭后正常恢复。

例如,处理数据流并需要保存进度时,应在处理过程中将当前位置写入存储,而不是等到最后再持久化:

// Good: Write progress as you go
async processData(data) {
  data.forEach(async (item, index) => {
    await this.processItem(item);
    // Save progress frequently
    await this.ctx.storage.put("lastProcessedIndex", index);
  });
}

这种做法可能不够直观,但 Durable Object 存储写入速度快且同步,因此持久化状态对性能的影响很小。

这种方法可确保 Durable Object 即使意外关闭,也能安全地从任意位置恢复。

这篇文档对您有帮助吗?