Cloudflare Queues 绑定规范

Cloudflare Queues 组件的详细文档

组件格式

用于 Dapr 的此输出绑定允许与 Cloudflare Queues 交互以发布新消息。目前无法使用 Dapr 从队列消费消息。

要设置 Cloudflare Queues 绑定，请创建类型为 bindings.cloudflare.queues 的组件。请参阅此指南了解如何创建和应用绑定配置。

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: bindings.cloudflare.queues
  version: v1
  # 如果 Dapr 正在为您管理 Worker，请增加 initTimeout
  initTimeout: "120s"
  metadata:
    # 现有 Cloudflare Queue 的名称（必需）
    - name: queueName
      value: ""
    # Worker 的名称（必需）
    - name: workerName
      value: ""
    # PEM 编码的 Ed25519 私钥（必需）
    - name: key
      value: |
        -----BEGIN PRIVATE KEY-----
        MC4CAQ...
        -----END PRIVATE KEY-----
    # Cloudflare 账户 ID（让 Dapr 管理 Worker 所需）
    - name: cfAccountID
      value: ""
    # Cloudflare 的 API 令牌（让 Dapr 管理 Worker 所需）
    - name: cfAPIToken
      value: ""
    # Worker 的 URL（如果在 Dapr 之外预创建 Worker 则必需）
    - name: workerUrl
      value: ""

警告

上面的示例将密钥作为纯字符串使用。建议按照此处的描述使用密钥存储来管理密钥。

规范元数据字段

字段	必填	绑定支持	详细信息	示例
`queueName`	Y	输出	现有 Cloudflare Queue 的名称	`"mydaprqueue"`
`key`	Y	输出	Ed25519 私钥，PEM 编码	见上方示例
`cfAccountID`	Y/N	输出	Cloudflare 账户 ID。让 Dapr 管理 Worker 时必需。	`"456789abcdef8b5588f3d134f74ac"def`
`cfAPIToken`	Y/N	输出	Cloudflare 的 API 令牌。让 Dapr 管理 Worker 时必需。	`"secret-key"`
`workerUrl`	Y/N	输出	Worker 的 URL。如果在 Dapr 之外预配置 Worker 则必需。	`"https://mydaprqueue.mydomain.workers.dev`

当您配置 Dapr 为您创建 Worker 时，您可能需要为组件的 initTimeout 属性设置更长的值，以便为部署 Worker 脚本预留足够的时间。例如：initTimeout: "120s"

绑定支持

此组件支持具有以下操作的输出绑定：

publish（别名：create）：向队列发布消息。
传递给绑定的数据将按原样用作发布到队列的消息正文。
此操作不接受任何元数据属性。

创建 Cloudflare Queue

要使用此组件，您必须在 Cloudflare 账户中创建一个 Cloudflare Queue。

您可以通过以下两种方式之一创建新队列：

使用 Cloudflare 控制面板

使用 Wrangler CLI：

# 如需身份验证，请先执行 `npx wrangler login`
npx wrangler queues create <NAME>
# 例如：`npx wrangler queues create myqueue`

配置 Worker

由于 Cloudflare Queues 只能由在 Workers 上运行的脚本访问，Dapr 需要维护一个 Worker 来与队列通信。

Dapr 可以自动为您管理 Worker，或者您可以自己预先配置 Worker。在 workerd 上运行时，预先配置 Worker 是唯一支持的选项。

重要

为每个 Dapr 组件使用单独的 Worker。不要为不同的 Cloudflare Queues 绑定使用相同的 Worker 脚本，也不要为 Dapr 中不同的 Cloudflare 组件（例如，Workers KV 状态存储和 Queues 绑定）使用相同的 Worker 脚本。

如果您想让 Dapr 为您管理 Worker，您需要提供这 3 个元数据选项：

workerName：Worker 脚本的名称。这将是您的 Worker URL 的第一部分。例如，如果为您的 Cloudflare 账户配置的 “workers.dev” 域是 mydomain.workers.dev 并且您将 workerName 设置为 mydaprqueue，Dapr 部署的 Worker 将在 https://mydaprqueue.mydomain.workers.dev 上可用。
cfAccountID：您的 Cloudflare 账户的 ID。登录到 Cloudflare 控制面板后，您可以在浏览器的 URL 栏中找到它，ID 紧跟在 dash.cloudflare.com 之后。例如，如果 URL 是 https://dash.cloudflare.com/456789abcdef8b5588f3d134f74acdef，则 cfAccountID 的值是 456789abcdef8b5588f3d134f74acdef。
cfAPIToken：具有创建和编辑 Workers 权限的 API 令牌。您可以在 Cloudflare 控制面板的 “My Profile” 部分的 “API Tokens” 页面中创建它：
1. 点击 “Create token”。
2. 选择 “Edit Cloudflare Workers” 模板。
3. 按照屏幕上的说明生成新的 API 令牌。

当 Dapr 配置为为您管理 Worker 时，当 Dapr 运行时启动时，它会检查 Worker 是否存在且是最新的。如果 Worker 不存在，或者它使用的是过时的版本，Dapr 会自动为您创建或升级它。

如果您不想授予 Dapr 为您部署 Worker 脚本的权限，您可以手动配置一个 Worker 供 Dapr 使用。请注意，如果您有多个 Dapr 组件通过 Worker 与 Cloudflare 服务交互，您需要为每个组件创建单独的 Worker。

要手动配置 Worker 脚本，您需要在本地计算机上安装 Node.js。

创建一个新文件夹来放置 Worker 的源代码，例如：daprworker。
如果您还没有这样做，请使用以下命令通过 Wrangler（Cloudflare Workers CLI）进行身份验证：npx wrangler login。
在新创建的文件夹中，创建一个新的 wrangler.toml 文件，内容如下，并适当填写缺失的信息：

# Worker 的名称，例如 "mydaprqueue"
name = ""

# 不要更改这些选项
main = "worker.js"
compatibility_date = "2022-12-09"
usage_model = "bundled"

[vars]
# 将此设置为 Ed25519 密钥的**公钥**部分，PEM 编码（换行符替换为 `\n`）。
# 示例：
# PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\nMCowB...=\n-----END PUBLIC KEY-----"
PUBLIC_KEY = ""
# 将此设置为您的 Worker 名称（与上面的 "name" 属性值相同），例如 "mydaprqueue"。
TOKEN_AUDIENCE = ""

# 将接下来的两个值设置为您的 Queue 名称，例如 "myqueue"。
# 注意它们将被设置为相同的值。
[[queues.producers]]
queue = ""
binding = ""

注意：有关如何生成 Ed25519 密钥对，请参阅下一节。在部署 Worker 时，请确保使用密钥的公钥部分！

将 Worker 的（预编译和压缩的）代码复制到 worker.js 文件中。您可以使用以下命令执行此操作：

# 将此设置为您正在使用的 Dapr 版本
DAPR_VERSION="release-1.18"
curl -LfO "https://raw.githubusercontent.com/dapr/components-contrib/${DAPR_VERSION}/internal/component/cloudflare/workers/code/worker.js"

使用 Wrangler 部署 Worker：

npx wrangler publish

部署 Worker 后，您需要使用这两个元数据选项来初始化组件：

workerName：Worker 脚本的名称。这是您在 wrangler.toml 文件中的 name 属性中设置的值。
workerUrl：已部署的 Worker 的 URL。npx wrangler command 命令将向您显示完整的 URL，例如 https://mydaprqueue.mydomain.workers.dev。

生成 Ed25519 密钥对

所有 Cloudflare Workers 都在公共 Internet 上监听，因此 Dapr 需要使用额外的身份验证和数据保护措施，以确保没有其他人员或应用程序可以与您的 Worker 通信（从而与您的 Cloudflare Queue 通信）。这些措施包括行业标准措施，例如：

Dapr 向 Worker 发出的所有请求都通过不记名令牌（技术上讲是 JWT）进行身份验证，该令牌使用 Ed25519 密钥签名。
Dapr 与您的 Worker 之间的所有通信都通过加密连接进行，使用 TLS (HTTPS)。
不记名令牌在每个请求上生成，仅在短时间内有效（目前为一分钟）。

要让 Dapr 颁发不记名令牌并让您的 Worker 验证它们，您需要生成一个新的 Ed25519 密钥对。以下是使用 OpenSSL 或 step CLI 生成密钥对的示例。

自 OpenSSL 1.1.0 起支持生成 Ed25519 密钥，因此如果您使用的是旧版本的 OpenSSL，以下命令将不起作用。

Mac 用户注意：在 macOS 上，Apple 附带的 “openssl” 二进制文件实际上基于 LibreSSL，截至目前它不支持 Ed25519 密钥。如果您使用的是 macOS，请使用 step CLI，或使用 brew install openssl@3 从 Homebrew 安装 OpenSSL 3.0，然后将以下命令中的 openssl 替换为 $(brew --prefix)/opt/openssl@3/bin/openssl。

您可以使用 OpenSSL 生成新的 Ed25519 密钥对：

openssl genpkey -algorithm ed25519 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem

在 macOS 上，使用来自 Homebrew 的 openssl@3：

$(brew --prefix)/opt/openssl@3/bin/openssl genpkey -algorithm ed25519 -out private.pem
$(brew --prefix)/opt/openssl@3/bin/openssl pkey -in private.pem -pubout -out public.pem

如果您还没有 step CLI，请按照官方说明进行安装。

接下来，您可以使用 step CLI 生成新的 Ed25519 密钥对：

step crypto keypair \
  public.pem private.pem \
  --kty OKP --curve Ed25519 \
  --insecure --no-password

无论您如何生成密钥对，按照上述说明，您将拥有两个文件：

private.pem 包含密钥的私钥部分；使用此文件的内容作为组件元数据的**key**属性。
public.pem 包含密钥的公钥部分，仅当您手动部署 Worker 时才需要（按照上一节中的说明）。

警告

请保护密钥的私钥部分并将其视为机密值！