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

第16章 R2对象存储集成指南

文档 R2 是对象存储。Worker 通过 r2_buckets binding 访问一个 bucket。celld 把对象存入节点用 --bucket 打开的 fleet bucket,因此 R2 具备该对象存储的持久性。在没有 fleet bucket 的节点上,所有 R2 方法都会失败。API 详情请阅读 Workers API 参考。

示例 R2 示例演示了在 R2 bucket 中读取、写入和删除对象。

index.js export default { async fetch(request, env) { const key = new URL(request.url).pathname.slice(1); if (!key) return new Response("Use /KEY.", { status: 400 });

if (request.method === "PUT") { await env.FILES.put(key, request.body, { httpMetadata: { contentType: request.headers.get("content-type") ?? "application/octet-stream", }, }); return new Response(null, { status: 204 }); }

if (request.method === "DELETE") { await env.FILES.delete(key); return new Response(null, { status: 204 }); }

if (request.method === "GET") { const object = await env.FILES.get(key); if (object === null) return new Response("Not found.", { status: 404 });

const headers = new Headers(); object.writeHttpMetadata(headers); headers.set("etag", object.httpEtag); return new Response(object.body, { headers }); }

return new Response("Method not allowed.", { status: 405 }); }, };

wrangler.jsonc { "name": "r2", "main": "index.js", "compatibility_date": "2026-01-01", "r2_buckets": [ { "binding": "FILES", "bucket_name": "example-files" } ] }

API

get(key, { range, onlyIf }) 返回一个带流式 body 的 R2ObjectBody,或 null。range 可以是 offset、length、suffix 或 Range header。 head(key) 返回对象记录,但不包含 body。 put(key, value, { httpMetadata, customMetadata, onlyIf }) 接受 string、ArrayBuffer、typed array、Blob 或 ReadableStream。条件被拒绝时返回 null。 delete(keys) 删除一个 key 或一组 key。 list({ prefix, delimiter, cursor, startAfter }) 返回一页对象。 createMultipartUpload(key) 返回一个 handle。uploadPart(number, value) 上传一个 part,complete(parts) 组装对象。

Key 与存储 每个 binding 有自己的 bucket_name,celld 将 key 存为对象 r2//。key 长度为 1 到 1024 字节。流式 put() 的 body 超过 8 MiB 时会自动转为 multipart upload。delete() 单次最多删除 1000 个 key。celld 没有公开的 bucket URL、presigned URL 或 S3 endpoint,要发布对象内容就得在前面放一个 Worker。

对象存储会把部分 key 以百分号编码形式保存:包含非 ASCII 字符、控制字符,或 % \ { } ^ ` [ ] " < > ~ # | * ? 之一的 key。例如 přehled.html 会变成 r2//p%C5%99ehled.html。每个空 segment 会变成 %,因此 photos/ 变成 r2//photos/%,而 a/b、/a/b、a//b 和 a/b/ 是四个不同的对象,这一点与 Cloudflare R2 一致。list() 返回解码后的 key,但排序按编码形式进行,startAfter 也与编码形式比较。Cloudflare R2 按 UTF-8 字节排序。例如 Cloudflare R2 会返回 a~ after startAfter: "aa",而 celld 比较 a%7E 与 aa,会跳过该 key。来自 celld 列表的 cursor 没有这个问题。当 list() 遇到其他工具写入的、百分号编码后不是有效 UTF-8 的 key(如 a%FF)时会失败。

celld 0.5.1 及更早版本会从 key 中去掉空 segment。这类版本写入 photos/ 下的对象会留在 photos 下,list() 也把它作为 photos 返回。

Multipart upload 一个 multipart upload 存在于开启它的那个节点上。part 规则请阅读 Multipart upload。在 predecessor 之前到达的 part 会先驻留内存,上限 256 MiB,超过后 celld 会拒绝后续 part。等待中的 part 可以被替换;已写入对象存储的 part 则不行,celld 会拒绝这类写入。

与 Cloudflare 的差异

R2 binding 使用 fleet bucket 中 r2// 下的空间。 五个 content header 以 headers 形式存储。customMetadata、cacheExpiry、checksum 和 storage class 合并为一个 JSON 值,存放在 celld-r2 这个 user-metadata 名称下(Azure Blob Storage 不允许 metadata 名称含连字符,故为 celld_r2)。 其他工具写入的对象仍可通过 binding 读取。其 user metadata 会成为 customMetadata,headers 会成为 httpMetadata。要写入完整记录请使用 celld r2 put。 celld r2 get|head|put|delete|list 替代了 wrangler r2 object。该命令直接读取 fleet bucket,因此不需要运行中的节点。 对象版本等同于其内容 ETag,因此相同内容产生相同版本。 ssecKey 和 jurisdiction 不可用。 条件写入不能使用大于 8 MiB 的流式 body。 createMultipartUpload() 不接受 checksum。 multipart upload 无法在其他节点上恢复,也无法在重启后恢复。celld 也无法替换对象存储已持有的 part。 乱序 part 最多占用 256 MiB 内存,且 completion 无法改变已存储的 part 顺序。

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

本篇用到的工具

评论 (0)