滚动发布

滚动发布（rollout） 会在你部署使用 Containers 的 Worker 后，应用目标容器应用配置。目标可以更改镜像、实例类型、限制、放置或其他容器设置。

容器实例 是你的容器镜像在 Cloudflare 网络上的一份正在运行的副本。它运行镜像启动的进程（Dockerfile 中的 ENTRYPOINT/CMD，或基础镜像默认值）。当目标更改镜像时，滚动发布会用运行目标镜像的副本替换容器实例。滚动发布不会更改 Durable Object 存储。

当现有容器应用的有效配置发生变化时，wrangler deploy 会：

1. 上传并激活新的 Worker 版本，包括 Durable Object 类代码。
2. 需要时构建并推送 Dockerfile 镜像，或使用已配置的 registry 镜像引用。
3. 启动滚动发布以应用目标容器配置。

Worker 会在镜像和滚动发布步骤开始前处于活动状态。这些步骤不是事务性的，因此如果后续镜像或滚动发布步骤失败，Worker 仍可保持活动。部署成功表示滚动发布已开始，而不是每个容器实例都已完成替换。首次部署会直接创建容器应用，没有有效容器变更的部署不会启动滚动发布。

当镜像变更时，新的 Worker 代码在滚动发布完成前仍可到达使用先前镜像的容器实例。请优先让 Worker 和镜像变更在该窗口期内可以协同工作，或者在需要平台允许的最短混合窗口时选择立即。

字段名称和允许值列在 Containers 配置下。

默认情况下，Wrangler 使用 rollout_step_percentage 启动滚动发布。如果省略 max_instances 或小于 2，Wrangler 使用一个 100 步骤。否则，Wrangler 请求 [10, 100]：

1. 请求约 10% 的容器实例使用新配置。平台会在必要时提高该百分比，使该步骤在配置的 max_instances 下至少代表一个实例。
2. 将 100% 的容器实例设为目标，使用新配置。

在 Wrangler 中用 rollout_step_percentage 配置步骤。用 --containers-rollout 覆盖一次部署的默认计划。

当滚动发布选择要更新的容器实例时：

1. 宽限期（如果已配置）。 如果 rollout_active_grace_period 大于 0，最近才连接到其 Durable Object 的容器实例会被跳过，直到它们通过该窗口。默认 0 表示没有额外等待。请参阅滚动发布活动宽限期。
2. 发送停止信号。 平台向容器中的主进程发送 SIGTERM，以便它可以停止接受新工作并完成进行中的工作。如果该进程需要在退出前清理，请在镜像中处理 SIGTERM。
3. 排空。 进程在 SIGTERM 后最多有 15 分钟退出。
4. 必要时强制停止。 如果进程在 15 分钟后仍在运行，平台发送 SIGKILL。
5. 退出后。 容器进程退出后，Worker 中可以运行 Container 类的 onStop 钩子。
6. 使用目标镜像启动新的容器实例。 除非你将数据存储在容器文件系统之外，否则磁盘是临时的。

每个被选中的容器实例都按自己的时间表执行此序列。整个实例群不会在同一时刻重启。

新容器实例必须启动其进程。启动通常需要数秒量级的时间，取决于镜像大小以及启动时运行的内容。请参阅冷启动。

需要该容器实例的请求可能等到容器就绪，或者在客户端或 Worker 超时短于启动时间时失败。请保持启动工作快速，如果配置了端口就绪检查请使用它们，并在设置超时时考虑启动时间。

rollout_active_grace_period 仅在滚动发布期间应用，此时平台选择要替换哪些容器实例。

Containers 由 Durable Objects 提供支持。每个正在运行的容器实例都与启动它并向其发送流量的 Durable Object 实例关联。宽限期是该连接必须已经存在多久，滚动发布才可以关闭容器。它不是从部署完成开始计算的。

当短会话应在滚动发布替换容器前完成时，使用非零值。连接时间更长的容器实例在通过窗口后仍可被替换。

rollout_active_grace_period 适用于每种滚动发布模式，包括立即。

--containers-rollout 仅适用于 wrangler deploy。它不适用于 wrangler versions upload。

在完整部署中，Wrangler 在处理容器镜像和滚动发布之前激活 Worker。滚动发布模式控制如何应用目标容器配置。

立即将滚动发布计划设为单一步骤，目标为 100% 的容器实例。没有中间百分比停留。

npx wrangler deploy --containers-rollout=immediate

yarn wrangler deploy --containers-rollout=immediate

pnpm wrangler deploy --containers-rollout=immediate

当 Worker 代码和容器镜像需要保持兼容，并且你希望混合窗口尽量短到平台允许的程度时使用立即模式（例如 Worker 与镜像中进程通信方式发生破坏性变更）。

行为：

• 新的 Worker 版本会在处理容器镜像和滚动发布之前被激活。
• 然后滚动发布使用与渐进模式相同的替换序列将容器实例替换到 100%，如果已配置则包括宽限期。
• 替换会在实际时钟时间内完成。耗时取决于正在运行的容器实例数量、每个实例停止和启动所需时间，以及任何宽限期。
• 当镜像变更时，立即模式会尽量缩短但不能消除新 Worker 到达先前镜像实例的时段。
• 部署成功表示滚动发布已开始，而不是替换已完成。

无模式保持镜像和正在运行的容器实例不变，仅部署 Worker 代码。

当部署不应发布新镜像或启动容器实例滚动发布时使用无模式。如果 image 是 Dockerfile 路径且 Docker 不可用，Wrangler 可能需要此标志或可用的 Docker 环境，以便部署跳过容器步骤。

rollout_active_grace_period 为 300 秒（五分钟），步骤为 [10, 100]：

{
	"containers": [
		{
			"max_instances": 10,
			"class_name": "MyContainer",
			"image": "./Dockerfile",
			"rollout_active_grace_period": 300,
			"rollout_step_percentage": [10, 100],
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"name": "MY_CONTAINER",
				"class_name": "MyContainer",
			},
		],
	},
	"exports": {
		"MyContainer": {
			"type": "durable-object",
			"storage": "sqlite",
		},
	},
}

[[containers]]
max_instances = 10
class_name = "MyContainer"
image = "./Dockerfile"
rollout_active_grace_period = 300
rollout_step_percentage = [ 10, 100 ]

[[durable_objects.bindings]]
name = "MY_CONTAINER"
class_name = "MyContainer"

[exports.MyContainer]
type = "durable-object"
storage = "sqlite"

• 部署 Containers
• Container 生命周期
• 镜像管理
• Wrangler 配置