API · Cloudflare Containers 文档

Containers 提供两种 API，用于从 Durable Object 管理容器。这两种 API 面向同一容器运行时。

对于新应用，我们建议使用 Durable Object Container API。它可以将容器工作负载与 Durable Object 的持久存储、警报（alarms）和请求处理结合使用。使用 ctx.container 控制容器生命周期，同时由 Durable Object 协调应用状态。Container 类仍会继续记录，供现有应用使用。

Durable Object Container API

通过 ctx.container 启动、停止、监控容器并与其连接。

Container 类

查阅该类及其路由、就绪检查、生命周期钩子和调度，供现有应用参考。

选择 API

在 Durable Object 内部，使用 ctx.container 直接控制容器运行时。你可以管理启动、关闭、网络和资源使用，同时使用 Durable Object 存储和警报（alarms）进行状态与协调。需要时再添加就绪检查、自定义请求路由或生命周期策略。

Container 类扩展 DurableObject，并用便捷方法封装容器运行时 API。现有应用可以使用这些方法完成请求代理、就绪检查、生命周期钩子和调度。需要时仍可使用 Durable Object 存储和警报（alarms）。

以下示例比较两种 API 的起始结构：

src/index.tsts

import { DurableObject } from "cloudflare:workers";

interface Env {}

export class MyContainer extends DurableObject<Env> {
	fetch(): Response {
		const container = this.ctx.container;
		if (!container) {
			return new Response("No container is configured", { status: 500 });
		}
		if (container.running) {
			return new Response("Container is running");
		}
		container.start();
		return new Response("Container is starting", { status: 202 });
	}
}

src/index.tsts

import { Container } from "@cloudflare/containers";

export class MyContainer extends Container {
	defaultPort = 8080;
	sleepAfter = "10m";
}

通过 Durable Object Container API 启动容器，并不意味着其端口已经就绪。对于请求路由，请在确认端口就绪后使用 getTcpPort()。所有直接方法请参阅 Durable Object Container API。便捷方法请参阅 Container 类 API。

下表比较两种选项：

需求	Durable Object Container API	`Container` 类
启动和停止容器	`start()`、`signal()` 和 `destroy()`	`start()`、`stop()` 和 `destroy()`
发送和代理流量	`getTcpPort(port).fetch()` 和 `getTcpPort(port).connect()`	`fetch()` 和 `containerFetch()`
执行另一个进程	`exec()`	`ctx.container.exec()`
检查端口就绪	在应用代码中使用 `getTcpPort()`	`startAndWaitForPorts()` 和 `waitForPort()`
处理并发启动	需要时协调对 `start()` 的调用	由 `start()` 和 `startAndWaitForPorts()` 处理
运行生命周期钩子	`monitor()` 和应用代码	`onStart()`、`onStop()`、`onError()` 和 `onActivityExpired()`
停止空闲容器	`setInactivityTimeout()`	`sleepAfter` 和 `onActivityExpired()`
调度回调	`ctx.storage.setAlarm()`（Durable Object API）	`schedule()`

对于新应用，使用 Durable Object Container API，将直接的容器控制与 Durable Object 存储和协调结合起来。它也适合对延迟敏感的工作负载，以及需要更小存储占用的应用。

如果你的应用使用 Container 类，请参阅迁移到 Durable Object Container API。