Image Management

在 `wrangler deploy` 期间推送镜像

在运行 wrangler deploy 时，如果你在Wrangler 配置中将 image 属性设置为 Dockerfile 的路径，Wrangler 将使用 Docker 在本地构建你的容器镜像，然后将其推送到 Cloudflare 运行的 registry 中。这个 registry 与你的 Cloudflare 账户集成，由 R2 提供支持。所有身份验证在推送和提取镜像时由 Cloudflare 自动处理。

只需提供指向 Dockerfile 的路径：

{
	"containers": [
		{
			"image": "./Dockerfile"
		}
	]
}

[[containers]]
image = "./Dockerfile"

然后通过 wrangler deploy 部署你的 Worker。不需要进行其他镜像管理。

在后续部署中，Wrangler 只会推送已更改的镜像层，这节省了空间和时间。

使用预构建的容器镜像

容器支持来自由 Cloudflare 管理的 registry.cloudflare.com registry、Docker Hub ↗、Amazon ECR ↗ 和 Google Artifact Registry ↗ 的镜像。

使用公开的 Docker Hub 镜像

要使用公开的 Docker Hub 镜像，请在你的 Wrangler 配置中将 image 设置为一个完全限定的 Docker Hub 镜像引用。

例如：

{
	"containers": [
		{
			"image": "docker.io/<NAMESPACE>/<REPOSITORY>:<TAG>"
		}
	]
}

[[containers]]
image = "docker.io/<NAMESPACE>/<REPOSITORY>:<TAG>"

公开的 Docker Hub 镜像不需要配置 registry。

私有的 Docker Hub 镜像使用接下来介绍的私有 registry 配置流程。

如果已配置了 Docker Hub 凭证，这些凭证用于提取公开和私有镜像。

配置私有 registry 凭证

要使用 Docker Hub、Amazon ECR 或 Google Artifact Registry 的私有镜像，请针对 registry 域运行 wrangler containers registries configure。

Wrangler 会提示你输入 secret 并将其存储在 Secrets Store 中。如果你还没有 Secrets Store 存储，Wrangler 将首先提示你创建一个。

使用 --secret-name 来命名或重用一个 secret，--secret-store-id 以定位特定的 Secrets Store 存储，以及 --skip-confirmation 以进行非交互式运行。在 CI 或脚本中，通过 stdin 传递 secret。

使用私有的 Docker Hub 镜像

使用以下值在 Wrangler 中配置 Docker Hub：

registry 域：docker.io
用户名标志：--dockerhub-username=<YOUR_DOCKERHUB_USERNAME>
secret：具有只读权限的 Docker Hub 个人访问令牌（PAT）

要创建 Docker Hub 个人访问令牌：

登录到 Docker 主页 ↗。
前往 Account settings（账户设置） > Personal access tokens（个人访问令牌）。
选择 Generate new token（生成新令牌）。
赋予该令牌 Read（读取） 权限，然后复制令牌值。

交互式：

npx wrangler containers registries configure docker.io --dockerhub-username=<YOUR_DOCKERHUB_USERNAME>

yarn wrangler containers registries configure docker.io --dockerhub-username=<YOUR_DOCKERHUB_USERNAME>

pnpm wrangler containers registries configure docker.io --dockerhub-username=<YOUR_DOCKERHUB_USERNAME>

CI 或脚本：

printf '%s' "$DOCKERHUB_PAT" | npx wrangler containers registries configure docker.io --dockerhub-username=<YOUR_DOCKERHUB_USERNAME> --secret-name=<SECRET_NAME> --skip-confirmation

配置完 registry 后，使用上述展示的相同的完全限定的 Docker Hub 镜像引用。

使用私有 Amazon ECR 镜像

使用以下值在 Wrangler 中配置 Amazon ECR：

registry 域：<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com
访问密钥标志：--aws-access-key-id=<AWS_ACCESS_KEY_ID>
secret：匹配的 AWS 秘密访问密钥

不支持公开 ECR 镜像。要生成所需凭证，创建一个带有只读策略的 IAM 用户。以下示例允许访问 us-east-1 中 AWS 账户 123456789012 内的所有镜像存储库。

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Action": ["ecr:GetAuthorizationToken"],
			"Effect": "Allow",
			"Resource": "*"
		},
		{
			"Effect": "Allow",
			"Action": [
				"ecr:BatchCheckLayerAvailability",
				"ecr:GetDownloadUrlForLayer",
				"ecr:BatchGetImage"
			],
			// arn:${Partition}:ecr:${Region}:${Account}:repository/${Repository-name}
			"Resource": [
				"arn:aws:ecr:us-east-1:123456789012:repository/*"
				// "arn:aws:ecr:us-east-1:123456789012:repository/example-repo"
			]
		}
	]
}

创建 IAM 用户后，使用其凭证在 Wrangler 中配置 registry。如果尚不存在，Wrangler 会提示你创建一个 Secrets Store 存储，然后将 secret 存储在那里。

交互式：

npx wrangler containers registries configure <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com --aws-access-key-id=<AWS_ACCESS_KEY_ID>

yarn wrangler containers registries configure <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com --aws-access-key-id=<AWS_ACCESS_KEY_ID>

pnpm wrangler containers registries configure <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com --aws-access-key-id=<AWS_ACCESS_KEY_ID>

CI 或脚本：

printf '%s' "$AWS_SECRET_ACCESS_KEY" | npx wrangler containers registries configure <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com --aws-access-key-id=<AWS_ACCESS_KEY_ID> --secret-name=<SECRET_NAME> --skip-confirmation

配置完 registry 后，在你的 Wrangler 配置中使用完全限定的 Amazon ECR 镜像引用：

{
	"containers": [
		{
			"image": "<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/<REPOSITORY>:<TAG>"
		}
	]
}

[[containers]]
image = "<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/<REPOSITORY>:<TAG>"

使用私有 Google Artifact Registry 镜像

使用以下值在 Wrangler 中配置 Google Artifact Registry：

registry 域：<REGION>-docker.pkg.dev
Google 服务账户电子邮件标志：--gar-email=<SERVICE_ACCOUNT_EMAIL>
secret：服务账户 JSON 密钥

公共凭证是服务账户电子邮件，通过 --gar-email 提供。它必须与服务账户密钥中的 client_email 字段匹配。

私有凭证是服务账户 JSON 密钥。通过 stdin（文件路径、原始 JSON 或 base64）或交互式提示（文件路径或 base64）提供它。 Wrangler 将以 base64 编码形式把密钥存储在 Secrets Store 中。

要生成所需凭证，请创建一个具有 Artifact Registry Reader（Artifact Registry 读取者） 角色的服务账户并下载其 JSON 密钥：

在 Google Cloud 控制台 ↗ 中，转到 IAM & Admin（IAM 和管理） > Service Accounts（服务账号）。
选择 Create service account（创建服务账户），然后输入名称、ID 和可选描述。
授予该服务账户 Artifact Registry Reader（Artifact Registry 读取者） 角色，然后选择 Done（完成）。
选择服务账户，然后打开 Keys（密钥） 选项卡。
选择 Add key（添加密钥） > Create new key（创建新密钥），选择 JSON，然后选择 Create（创建）。该密钥文件会下载到你的机器上。

交互式： Wrangler 将提示输入密钥，你要在其中输入文件路径或经过 base64 编码的 JSON：

npx wrangler containers registries configure <REGION>-docker.pkg.dev --gar-email=<SERVICE_ACCOUNT_EMAIL>

yarn wrangler containers registries configure <REGION>-docker.pkg.dev --gar-email=<SERVICE_ACCOUNT_EMAIL>

pnpm wrangler containers registries configure <REGION>-docker.pkg.dev --gar-email=<SERVICE_ACCOUNT_EMAIL>

CI 或脚本：通过 stdin 传递密钥（将密钥内容作为原始 JSON 或 base64，或通过密钥文件路径）

cat <PATH_TO_KEY> | npx wrangler containers registries configure <REGION>-docker.pkg.dev --gar-email=<SERVICE_ACCOUNT_EMAIL> --secret-name=<SECRET_NAME> --skip-confirmation

如果你已经将密钥存储在 Secrets Store 中，请引用现有 secret 并省略该密钥：

npx wrangler containers registries configure <REGION>-docker.pkg.dev --gar-email=<SERVICE_ACCOUNT_EMAIL> --secret-name=<EXISTING_SECRET_NAME> --skip-confirmation

配置完 registry 后，在你的 Wrangler 配置中使用完全限定的 Google Artifact Registry 镜像引用：

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "containers": [
    {
      "image": "<REGION>-docker.pkg.dev/<PROJECT_ID>/<REPOSITORY>/<IMAGE>:<TAG>"
    }
  ]
}

[[containers]]
image = "<REGION>-docker.pkg.dev/<PROJECT_ID>/<REPOSITORY>/<IMAGE>:<TAG>"

使用来自其他 registry 的镜像

如果你想使用来自另一个 registry 服务商的预构建镜像，请首先确保它在本地存在，然后将其推送到 Cloudflare Registry：

docker pull <PUBLIC_IMAGE>
docker tag <PUBLIC_IMAGE> <IMAGE>:<TAG>

Wrangler 提供了一个向 Cloudflare Registry 推送镜像的命令：

npx wrangler containers push <IMAGE>:<TAG>

yarn wrangler containers push <IMAGE>:<TAG>

pnpm wrangler containers push <IMAGE>:<TAG>

或者，你可以将 -p 标志与 wrangler containers build 一起使用以一步完成镜像的构建和推送：

npx wrangler containers build -p -t <TAG> .

yarn wrangler containers build -p -t <TAG> .

pnpm wrangler containers build -p -t <TAG> .

这将输出一个镜像 registry URI，你可以随后在你的 Wrangler 配置中使用它：

{
	"containers": [
		{
			"image": "registry.cloudflare.com/<YOUR_ACCOUNT_ID>/<IMAGE>:<TAG>"
		}
	]
}

[[containers]]
image = "registry.cloudflare.com/<YOUR_ACCOUNT_ID>/<IMAGE>:<TAG>"

借助 CI 推送镜像

要使用在持续集成环境中构建的镜像，请安装 wrangler，然后使用带有 --push 标志的 wrangler containers build，或者使用 wrangler containers push 命令来构建并推送镜像。

Registry 限制

镜像在大小上受制于为容器配置的实例类型的可用磁盘大小。

通过 wrangler containers images delete 删除镜像来释放空间，但是如果将使用被删除镜像的 Worker 恢复到以前的版本，将会出现错误。