进阶 celld.dev 2026-10-11 10:08:47 · 49 阅读

第15章 Queues 消息队列

文档:Queues

Queues 是一个消息代理。生产者 Worker 发送消息,消费者 Worker 随后以批次形式接收。每个队列占用一个 cell(单元格)。查阅 Cloudflare Queues 文档 了解 API 详情。

示例

Queues 示例通过请求发送一个任务,并在队列处理程序中处理该任务。如果任务路径以 /fail 结尾,系统将重试两次,随后示例从死信队列中读取该任务。

index.js

export default {
  async fetch(request, env) {
    const job = {
      path: new URL(request.url).pathname,
      createdAt: new Date().toISOString(),
    };
    await env.JOBS.send(job);
    return Response.json({ queued: job });
  },

  async queue(batch) {
    for (const message of batch.messages) {
      if (batch.queue === "example-jobs-dead-letter") {
        console.log("dead job", message.body);
        message.ack();
        continue;
      }

      if (message.body.path.endsWith("/fail")) {
        console.log("retrying job", message.body, message.attempts);
        message.retry({ delaySeconds: 1 });
        continue;
      }

      console.log("processing job", message.body);
      message.ack();
    }
  },
};

wrangler.jsonc

{
  "name": "queues",
  "main": "index.js",
  "compatibility_date": "2026-01-01",
  "queues": {
    "producers": [{ "binding": "JOBS", "queue": "example-jobs" }],
    "consumers": [
      {
        "queue": "example-jobs",
        "max_batch_size": 10,
        "max_batch_timeout": 5,
        "max_retries": 2,
        "dead_letter_queue": "example-jobs-dead-letter"
      },
      { "queue": "example-jobs-dead-letter" }
    ]
  }
}

API

  • env.JOBS.send(body, { contentType, delaySeconds }) 发送单条消息。contentType 支持 "v8"、"json"、"text" 或 "bytes"。
  • env.JOBS.sendBatch(messages) 一次调用最多发送 100 条消息。
  • 消费者脚本导出 queue(batch, env, ctx) 函数。batch.queue 指定队列名称,batch.messages 中的每一项包含 id、时间戳、body(主体内容)和 attempts(尝试次数)。
  • message.ack() 和 message.retry({ delaySeconds }) 用于结算单条消息。batch.ackAll() 和 batch.retryAll() 用于结算整个批次。对于同一条消息,以首次调用为准。
  • 如果处理程序直接返回,则自动确认所有未结算的消息。如果处理程序抛出异常,则自动重试所有未确认的消息。

生产者

queues.producers 条目指定绑定名称和队列名称。整个 fleet(机队/集群)中所有指向同一队列的生产者都写入该队列。celld 强制执行 Cloudflare 的以下限制:

  • 单条消息最大 128,000 字节
  • 单次 sendBatch() 调用最多 100 条消息,总计不超过 256,000 字节
  • delaySeconds 最大值为 86,400 秒

生产者条目可设置 delivery_delay 作为默认延迟。当队列 cell 提交消息后,send() 才会解析完成。单个 cell 同时最多接受 256 个生产者调用,超出后会产生 cell 过载错误,生产者需自行重试。

消费者

queues.consumers 条目指定队列名称。仅允许一个脚本消费特定队列,因此若部署中包含两个脚本消费同一队列,部署将失败。该条目可配置以下参数:

  • max_batch_size:默认 10,最大 100
  • max_batch_timeout:以秒为单位,默认 5,最大 60
  • max_retries:默认 3
  • max_concurrency:最大 250
  • retry_delay
  • dead_letter_queue

celld 在部署时验证每个参数。查阅 批量处理、重试与延迟 了解各参数含义。

celld 不保证投递顺序,且至少投递一次。重新投递时 message.id 保持不变,应用可将其作为幂等键使用。如果处理程序始终未结算批次,它将持有租约直到过期,celld 将此视为一次投递失败。celld 不对重试添加指数退避,需根据 message.attempts 自行计算延迟。超过 max_retries 的消息会被移至 dead_letter_queue;若消费者未配置死信队列,则直接删除该消息。

与 Cloudflare 的差异

  • 一个队列仅限一个写入者。需增加队列数量以提升写入容量。
  • 队列拥有者(owner)同时最多接受 256 个并发生产者调用,额外调用将被拒绝,生产者需重试。
  • celld 保留消息 4 天,该期限不可配置。
  • 拉取消费者(Pull consumers)、Queues HTTP API、控制台操作、手动附加消费者、R2 事件通知及队列事件订阅均不可用。

Cloudflare 兼容性页面列出了 运行时 API 和不支持的服务。

本篇用到的工具

评论 (0)