本指南将带您完成创建 K2 流、向其写入记录,以及通过订阅消费的过程。
完成本指南后,您将:
- 使用 Cloudflare API 创建了流。
- 通过 HTTP 向流生产了一批记录。
- 创建了跟踪读取位置的订阅。
- 消费了一批记录并确认了该批次。
- 注册 Cloudflare 账户 ↗ 并订阅 Workers Paid 计划。K2 在 Workers Free 计划上不可用。
- 查找您的 账户 ID。
- 安装
curl↗ 和jq↗。
K2 stream(流)是持久、仅追加的记录日志。每条 record(记录)
包含二进制 content 负载和可选的字符串 headers。
生产者按批次向流追加记录。每个批次原子写入: 批次中的每条记录都会被存储,或者一条也不存储。
消费者通过 subscription(订阅)从流读取。订阅跟踪 流中的位置。同一流上的多个订阅彼此独立读取。
当消费者从订阅读取时,K2 会向该消费者租出一批记录。 消费者处理完记录后确认该批次。 如果消费者未在租约到期前确认批次,K2 会再次投递这些记录。这为您提供至少一次投递。
您需要 API token 来创建流并从中读取。
-
在 Cloudflare 仪表板中,转到 Account API tokens(账户 API 令牌) 页面。
前往 Account API tokens(账户 API 令牌) ↗ -
选择 Create Token(创建令牌) > Create Custom Token(创建自定义令牌)。
-
为令牌输入名称,例如
k2-get-started。 -
在 Permissions(权限) 下,为您的账户添加 K2 Config Write、K2 Produce 和 K2 Consume 权限。K2 Config Write 允许您创建和删除流。
-
选择 Continue to summary(继续查看摘要) > Create Token(创建令牌)。
-
复制令牌值。离开该页面后将无法再次查看。
将账户 ID 和 API token 导出为 shell 变量。本指南中的命令使用这些变量。
export ACCOUNT_ID=<YOUR_ACCOUNT_ID>
export CLOUDFLARE_API_TOKEN=<YOUR_API_TOKEN>创建名为 orders 的流。此请求启用 HTTP 端点,并要求使用 API token 向其生产记录。
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/k2/streams" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"name": "orders",
"http": {
"enabled": true,
"authentication": true
}
}'{
"success": true,
"errors": [],
"messages": [],
"result": {
"id": "241fa65b438a4d539a19371f58bfdae0",
"name": "orders",
"retention_seconds": 604800,
"endpoint": "https://241fa65b438a4d539a19371f58bfdae0.k2.cloudflarestorage.com",
"http": {
"enabled": true,
"authentication": true
},
"worker_binding": {
"enabled": true
},
"created_at": "2026-09-24T21:19:19.246Z",
"modified_at": "2026-09-24T21:19:19.246Z"
}
}响应包括:
id:流 ID。用于构建流端点。endpoint:生产和消费记录的基础 URL。retention_seconds:K2 保留记录的时长。默认为七天(604800秒)。
将流 ID 和端点导出为 shell 变量:
export STREAM_ID=<STREAM_ID>
export K2_ENDPOINT=https://$STREAM_ID.k2.cloudflarestorage.com流配置选项
| 字段 | 必填 | 说明 |
|---|---|---|
name |
是 | 1 到 128 个字母、数字或下划线。在账户内必须唯一。名称不区分大小写。 |
http.enabled |
是 | 启用 HTTP /produce 端点。 |
http.authentication |
否 | 通过 HTTP 生产时需要 API token。如果省略此字段,任何拥有端点 URL 的人都可以生产。 |
http.cors.origins |
否 | 最多五个允许从浏览器生产的源,或 ["*"] 以允许任意源。 |
worker_binding.enabled |
否 | 允许 Worker 通过绑定生产。默认为 true。 |
retention_seconds |
否 | 记录保留期,从 3600(一小时)到 2592000(30 天)。默认为 604800(七天)。 |
http 或 worker_binding 至少必须启用一个。
向流的 /produce 端点发送包含两条记录的批次。记录
content 必须是标准 base64。在此示例中,每条记录包含
base64 编码的 JSON 订单事件。
curl "$K2_ENDPOINT/produce" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"records": [
{
"content": "eyJvcmRlcl9pZCI6MTAwMSwic3RhdHVzIjoiY3JlYXRlZCJ9",
"headers": { "event-type": "order.created" }
},
{
"content": "eyJvcmRlcl9pZCI6MTAwMiwic3RhdHVzIjoiY3JlYXRlZCJ9",
"headers": { "event-type": "order.created" }
}
]
}'{ "success": true }success: true 响应表示 K2 存储了批次中的每条记录。
要编码自己的负载,请将其通过 base64 管道处理:
printf '%s' '{"order_id":1001,"status":"created"}' | base64订阅跟踪消费者已处理的记录。创建名为 orders-processor 的订阅,从流中最早的记录开始。
curl "$K2_ENDPOINT/subscriptions" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"name": "orders-processor",
"start_at": { "type": "earliest" }
}'{
"result": { "id": "e2f747f8bccf453eb2767496779cd135" },
"success": true,
"errors": [],
"messages": []
}请求体包含:
name:1 到 128 个字母、数字、下划线或连字符。在流内必须唯一。start_at.type:earliest从最旧的仍保留记录读取。latest跳过创建订阅时已存在的记录。
使用相同名称和设置创建订阅会返回现有订阅 ID,因此该请求可以安全重试。
将订阅 ID 导出为 shell 变量:
export SUBSCRIPTION_ID=<SUBSCRIPTION_ID>请求最多 100 条记录的批次。worker_id 标识您的消费者。每个 worker 一次只能持有一个租约。
curl "$K2_ENDPOINT/subscriptions/$SUBSCRIPTION_ID/consume" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"worker_id": "worker-1",
"max_records": 100
}'{
"result": {
"batch_id": "4f1c2a9e8b7d4c6f9a0e1d2c3b4a5968",
"leased_until_ms": 1790165100000,
"records": [
{
"timestamp_ms": 1790164800000,
"content": "eyJvcmRlcl9pZCI6MTAwMSwic3RhdHVzIjoiY3JlYXRlZCJ9",
"headers": { "event-type": "order.created" }
},
{
"timestamp_ms": 1790164800000,
"content": "eyJvcmRlcl9pZCI6MTAwMiwic3RhdHVzIjoiY3JlYXRlZCJ9",
"headers": { "event-type": "order.created" }
}
]
},
"success": true,
"errors": [],
"messages": []
}响应包含:
batch_id:已租出批次的 ID。确认批次时需要它。leased_until_ms:租约到期时间,为自 Unix 纪元以来的毫秒数。租约持续五分钟。records:批次中的记录。timestamp_ms是 K2 收到记录的时间,为自 Unix 纪元以来的毫秒数。content为 base64。
要解码记录内容,请将响应通过 jq 管道处理:
curl --silent "$K2_ENDPOINT/subscriptions/$SUBSCRIPTION_ID/consume" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{"worker_id": "worker-1", "max_records": 100}' \
| jq -r '.result.records[].content | @base64d'{"order_id":1001,"status":"created"}
{"order_id":1002,"status":"created"}由于 worker-1 仍持有其租约,第二次请求会返回同一批次并刷新租约。如果消费者丢失响应,可使用此行为恢复批次。
如果没有可读取的记录,响应会包含空的 records 数组,且 batch_id 为 null。请等待后再轮询。
将响应中的批次 ID 导出为 shell 变量:
export BATCH_ID=<BATCH_ID>处理完记录后,确认该批次。这会将订阅推进到这些记录之后,并释放租约,以便 worker 可以读取下一批次。
curl "$K2_ENDPOINT/subscriptions/$SUBSCRIPTION_ID/batches/$BATCH_ID/ack" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{ "worker_id": "worker-1" }'{ "result": {}, "success": true, "errors": [], "messages": [] }如果处理失败,请改为向 /nack 而不是 /ack 发送相同请求。K2 会在不推进订阅的情况下释放租约,并再次投递这些记录。
再次运行第 5 步的 consume 请求。由于您已确认第一批,响应将不包含记录。
删除订阅:
curl "$K2_ENDPOINT/subscriptions/$SUBSCRIPTION_ID" \
--request DELETE \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"{
"result": { "id": "e2f747f8bccf453eb2767496779cd135" },
"success": true,
"errors": [],
"messages": []
}删除流及其所有记录:
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/k2/streams/$STREAM_ID" \
--request DELETE \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"{ "success": true, "errors": [], "messages": [], "result": {} }