更新日志

现在，您可以在 Cloudflare 仪表板中监控 Durable Object 命名空间随时间变化所使用的 SQLite 总存储量。全新的总存储图表显示了每小时报告的最大存储量。这有助于您识别存储增长、验证数据清理并调查异常使用情况。

该图表仅适用于基于 SQLite 的 Durable Object 命名空间。对于使用旧版键值存储后端的命名空间，它不会显示。不支持按 ID 或名称查看单个 Durable Object 的存储量。

欲了解更多信息，请参阅指标和分析。

如果您的账户中尚无基于键值 (KV) 后端的 Durable Object 命名空间，您将无法再创建新的此类命名空间。新的 Durable Object 命名空间必须使用 SQLite 存储后端。自 2024 年该后端正式商用 (GA) ↗ 以来，我们一直推荐所有新的 Durable Objects 使用该后端。

通过 new_sqlite_classes 迁移创建一个新类：

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": [
        "MyDurableObject"
      ]
    }
  ]
}

[[migrations]]
tag = "v1"
new_sqlite_classes = ["MyDurableObject"]

基于 SQLite 的 Durable Objects 与键值后端具有同等的功能特性——包括键值存储 API——并且还支持关系型 SQL 查询以及 时间点恢复 (PITR)，可将对象存储恢复到过去 30 天内的任意时间点。

如果您尝试在受影响的账户上创建新的基于键值的命名空间（使用 new_classes 迁移），部署将失败并显示以下错误：

Creating new key-value backed Durable Object namespaces is no longer supported on this account. Please create a namespace using a `new_sqlite_classes` migration instead.

此更改仅影响尚未开始使用键值存储后端的账户。拥有至少一个现有基于键值命名空间的账户目前仍可创建新的命名空间，而 Workers 免费计划一直以来仅支持基于 SQLite 的 Durable Objects。这是向将 SQLite 作为 Durable Objects 单一存储后端迈出的更广泛一步，为未来现有基于键值对象的迁移路径做准备。

欲了解更多信息，请参阅 Durable Objects 迁移。

Wrangler 配置文件中全新的声明式 exports 字段取代了用于管理 Durable Object 类生命周期的命令式 migrations 数组。您无需再编写带有唯一标签的有序迁移步骤列表，而是声明 Worker 导出的每个 Durable Object 类，Cloudflare 会将其与已部署的内容进行对比，以确定需要创建、重命名还是删除哪些 Durable Object 状态。

在使用旧版迁移时，将 ChatRoom 重命名为 Room 需要保留这两个标记的步骤：

{
	"migrations": [
		{ "tag": "v1", "new_sqlite_classes": ["ChatRoom"] },
		{
			"tag": "v2",
			"renamed_classes": [{ "from": "ChatRoom", "to": "Room" }],
		},
	],
}

而使用 exports，您只需将 Room 声明为当前类，并将 ChatRoom 标记为已重命名：

{
	"exports": {
		"ChatRoom": {
			"type": "durable-object",
			"state": "renamed",
			"renamed_to": "Room",
		},
		"Room": { "type": "durable-object", "storage": "sqlite" },
	},
}

每个条目都以类名作为键。state 字段承载生命周期（默认为 created——活动类——以及墓碑（tombstone）状态 deleted、renamed、transferred，和用于跨 Worker 传输的接收状态 expecting-transfer）。

与旧版 migrations 数组相比的关键改进：

• 无需迁移标签。 当前的 exports 映射是唯一的真实数据源——无需维护 v1、v2、v3 条目的历史链。
• 结构化的部署输出。 Wrangler 会在创建、更新、删除、重命名或传输 Durable Object 类时进行报告。它还会识别可安全删除的陈旧配置条目。没有更改或通知的部署不会打印此输出。
• 零停机重命名和传输模式是一等公民。 墓碑（Tombstones）可以与代码中仍然存在的源类共存，从而实现 三次部署重命名 和 四次部署跨 Worker 传输，在滚动部署期间不会出现运行时错误。
• 跨 Worker 安全性。 当您删除或重命名类时，Cloudflare 会列出您账户中其绑定（binding）仍引用该命名空间的其他所有 Worker，以便您在更改生效前重新部署它们。

使用旧版 migrations 数组的现有 Workers 仍可照常工作，无需任何更改。要过渡到 exports，请参阅迁移指南。在单个 Worker 中，exports 和 migrations 是互斥的。

欲了解完整的参考信息，请参阅 Durable Object 类导出。

您现在可以使用 Workers 指标（Metrics）选项卡中新增的 Memory Usage（内存使用情况） 图表，监控您的 Workers 和 Durable Objects 在多次调用中消耗了多少内存，图表按 P50、P90、P99 和 P999 百分位数进行了细分。

内存使用情况测量的是每次调用时的 V8 isolate 内存，受限于 每个 isolate 128 MB 的限制 —— 单个 isolate 可以处理许多并发请求并在它们之间共享内存。

使用内存使用情况图表可以：

• 跟踪内存趋势 —— 在导致 Exceeded Memory（超出内存）错误之前，发现可能表明存在内存泄漏的渐进式内存增加。
• 与部署关联 —— 图表上的部署标记可帮助您确定新版本是否引入了内存回归。
• 合理调整您的 Worker 规模 —— 了解您的基准内存占用量，以及在达到 128 MB 限制之前您还有多少余量。

对于 Durable Objects，内存使用情况反映了对象保存的内存中状态（类属性、缓存、活动的 WebSocket 连接），该状态在多次调用之间保持不变，直到对象被休眠或逐出。在逐出、休眠或崩溃时，此状态不会保留，因此请将任何重要内容持久化保存到存储中。

要查看内存使用情况，请打开您的 Worker ↗ 或 Durable Object 命名空间 ↗ 的 Metrics（指标） 选项卡。对于 Durable Objects，您可以按 DO ID 或名称进行过滤，以深入查看特定对象的内存使用情况。您还可以通过 GraphQL Analytics API 使用 workersInvocationsAdaptive 数据集以编程方式查询内存使用情况 —— 从 quantiles.memoryUsageBytesP50 到 quantiles.memoryUsageBytesP999 的字段以字节为单位返回百分位数。

对于本地内存调试，您还可以使用 DevTools 剖析内存以获取堆快照并识别导致高内存占用的特定对象。

Durable Objects 现在支持 us 管辖区（jurisdiction），允许您创建仅在美国境内运行并存储数据的 Durable Objects。当您需要将 Durable Object 的计算和存储保留在美国境内以满足数据驻留要求时，请使用 us 管辖区。

像使用任何其他管辖区一样，创建一个受限于 us 管辖区的命名空间：

// Worker
export default {
	async fetch(request, env) {
		const usSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("us");
		const stub = usSubnamespace.getByName("general");
		return stub.fetch(request);
	},
};

Workers 仍可从世界任何地方访问受限于 us 管辖区的 Durable Objects。管辖区限制仅控制 Durable Object 本身在何处运行和持久化数据。

如需查看支持的管辖区的完整列表，请参阅数据位置 — 限制 Durable Objects 至特定管辖区。

@cloudflare/vitest-pool-workers 包现在包含了从 cloudflare:test 导出的 evictDurableObject 和 evictAllDurableObjects 测试辅助函数。

这些辅助函数允许您测试 Durable Object 在逐出发生时的行为，模拟闲置 Durable Object 从内存中逐出的实际生产生命周期。

有关更多背景信息，请参阅 Durable Object 的生命周期。

import { evictDurableObject, evictAllDurableObjects } from "cloudflare:test";
import { env } from "cloudflare:workers";

const id = env.COUNTER.idFromName("my-counter");
const stub = env.COUNTER.get(id);

// 逐出特定 stub 所指向的 Durable Object 实例
await evictDurableObject(stub);

// 关闭 WebSockets 而不是将它们休眠
await evictDurableObject(stub, { webSockets: "close" });

// 逐出当前在可逐出命名空间中运行的所有 Durable Objects
await evictAllDurableObjects();

这些辅助函数在 @cloudflare/[email protected] 及更高版本中可用。

请在 测试 API 参考和测试 Durable Objects 指南中了解更多信息。

Durable Objects 现在支持两个针对亚太地区的新位置提示：apac-ne（东北亚）和 apac-se（东南亚）。当您希望在亚太地区内进行更细粒度的托管放置，而不是使用更宽泛的 apac 提示时，请使用 apac-ne 或 apac-se。

像使用任何其他 locationHint 一样使用这些新提示：

// 东北亚（日本、韩国等）
const stubNE = env.MY_DURABLE_OBJECT.get(id, { locationHint: "apac-ne" });

// 东南亚（新加坡、印度尼西亚等）
const stubSE = env.MY_DURABLE_OBJECT.get(id, { locationHint: "apac-se" });

如果您的用户分布在整个亚太地区，现有的 apac 提示仍是正确的选择。只有当您的流量明显集中在某一个子区域，且您希望将该受众的往返时间降至最低时，才使用 apac-ne 或 apac-se。默认行为以及我们通常建议的做法是，除非绝对需要，否则不添加位置提示，这将在尽可能靠近发起请求的地方创建 Durable Object 以减少延迟。

与所有位置提示一样，这些都是尽力而为的建议。Cloudflare 会将 Durable Object 放置在附近的数据中心，而不一定是提示的确切位置。

如需查看支持的提示的完整列表，请参阅数据位置 — 提供位置提示。

现在，通过 connect() 或出站 WebSocket 创建的活动出站连接在持续期间，Durable Objects 将保持存活。此前，即使对象具有打开的出站连接，Durable Object 也会在 70-140 秒无入站流量后被逐出，而这在使用 TCP 或出站 WebSocket 从大型语言模型 (LLM) 流式传输响应时是一种常见模式。

通过此更改，每个活动的出站连接都可以防止被逐出。一旦所有出站连接关闭，在 Durable Object 被逐出之前将适用标准的 70-140 秒空闲窗口。

如果您正在 Cloudflare 上构建智能体（Agent），这一点尤为重要。在调用模型时从 LLM 流式传输 Token 的智能体，或者通过出站连接执行长时间运行的任务的智能体，现在会在该连接持续期间保持存活，而不是在中途被逐出。

限制：

• 每个出站连接最多可使 Durable Object 保持存活 15 分钟。15 分钟后，该连接将不再防止逐出（连接本身将继续运行），并恢复标准逐出规则。
• Durable Object 现有的每个账户实例限制仍然适用。

欲了解更多信息，请参阅 Durable Object 的生命周期。

现在，您可以在 Cloudflare 仪表板中，按单个 Durable Object 的 ID 或 名称 筛选 Durable Objects 命名空间的 指标 选项卡。此前，指标图表仅显示聚合的命名空间级数据，因此很难隔离特定对象的行为。

开始在筛选器中输入 ID 或名称，然后从自动完成下拉列表中选择匹配项。自动完成仅显示在选定时间范围内有调用的对象，因此未出现的对象在该时间窗内未被调用。这并不一定意味着该对象已被删除。页面上的每个图表都会更新，以仅反映所选的对象。这使得在调试高流量对象、错误激增或意外存储使用时，更容易识别和调查单个 Durable Object。清除筛选器可返回命名空间级指标。

指标由 GraphQL Analytics API 提供支持，因此适用标准的分析行为，例如摄取延迟和采样。

欲了解更多信息，请参阅指标和分析。

按需付费（Pay-as-you-go）客户现在可以直接从 Workers & Pages、D1、R2、Workers KV、Queues、Vectorize、Durable Objects 和 Containers 的产品概览页面查看计费使用量并创建预算警报。新的侧边栏小组件显示了当前时期的支出和账单周期日期范围，同时还提供了一个用于创建预算警报的按钮。

该小组件提取与计费使用量仪表板相同的数据，并与您的账单周期（或免费计划中的当前日期）保持一致，因此数据与您的发票相符。目前尚不支持 Enterprise 合约账户。

选择 **Create budget alert（创建预算警报）**会以内联方式打开预算警报流程，以便您在查看使用量的同一位置设置美元阈值。预算警报适用于您在所有产品上的账户级别总支出，而不仅仅是您创建该警报的产品页面。

有关更多信息，请参阅基于使用量的计费文档。