跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

从 Workers 使用 R2

最后更新 查看 MarkdownAgent 设置

1. 使用 C3 创建新应用

C3 (create-cloudflare-cli) 是命令行工具，旨在帮助您尽快设置并将 Workers 和 Pages 应用部署到 Cloudflare。

开始之前，打开终端窗口并运行：

npm create cloudflare@latest -- r2-worker

进行设置时，请选择以下选项：

  • 对于 What would you like to start with?，选择 Hello World example。
  • 对于 Which template would you like to use?，选择 Worker only。
  • 对于 Which language do you want to use?，选择 JavaScript。
  • 对于 Do you want to use git for version control?，选择 Yes。
  • 对于 Do you want to deploy your application?，选择 No（部署前我们还会做一些修改）。

然后，进入新创建的目录：

cd r2-worker

2. 创建存储桶

运行以下命令创建存储桶：

npx wrangler r2 bucket create <YOUR_BUCKET_NAME>

要检查存储桶是否已创建，请运行：

npx wrangler r2 bucket list

运行 list 命令后，您将看到所有存储桶名称，包括刚创建的存储桶。

3. 将存储桶绑定到 Worker

您需要将存储桶绑定到 Worker。

要将 R2 存储桶绑定到 Worker，请在 Wrangler 文件中添加以下内容。将 binding 属性更新为有效的 JavaScript 变量标识符，将 bucket_name 更新为 步骤 2 中创建存储桶时使用的 <YOUR_BUCKET_NAME>：

{
	"r2_buckets": [
		{
			"binding": "MY_BUCKET", // <~ valid JavaScript variable name
			"bucket_name": "<YOUR_BUCKET_NAME>"
		}
	]
}
[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "<YOUR_BUCKET_NAME>"

有关配置 Worker 的更多详细信息（例如，若使用司法管辖区），请参阅 Wrangler 配置文档。

4. 从 Worker 访问 R2 存储桶

在 Worker 代码中，存储桶现可通过 MY_BUCKET 变量访问，您可以开始与之交互。

R2 存储桶可以 READ、LIST、WRITE 和 DELETE 对象。以下示例使用 Module Worker 语法展示所有操作。将以下代码片段添加到项目的 index.js 文件：

import { WorkerEntrypoint } from "cloudflare:workers";

export default class extends WorkerEntrypoint<Env> {
  async fetch(request: Request) {
    const url = new URL(request.url);
    const key = url.pathname.slice(1);

    switch (request.method) {
      case "PUT": {
        await this.env.MY_BUCKET.put(key, request.body, {
          onlyIf: request.headers,
          httpMetadata: request.headers,
        });
        return new Response(`Put ${key} successfully!`);
      }
      case "GET": {
        const object = await this.env.MY_BUCKET.get(key, {
          onlyIf: request.headers,
          range: request.headers,
        });

        if (object === null) {
          return new Response("Object Not Found", { status: 404 });
        }

        const headers = new Headers();
        object.writeHttpMetadata(headers);
        headers.set("etag", object.httpEtag);

        // When no body is present, preconditions have failed
        return new Response("body" in object ? object.body : undefined, {
          status: "body" in object ? 200 : 412,
          headers,
        });
      }
      case "DELETE": {
        await this.env.MY_BUCKET.delete(key);
        return new Response("Deleted!");
      }
      default:
        return new Response("Method Not Allowed", {
          status: 405,
          headers: {
            Allow: "PUT, GET, DELETE",
          },
        });
    }
  }
};
export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const key = url.pathname.slice(1);

    switch (request.method) {
      case "PUT": {
        await env.MY_BUCKET.put(key, request.body, {
          onlyIf: request.headers,
          httpMetadata: request.headers,
        });
        return new Response(`Put ${key} successfully!`);
      }
      case "GET": {
        const object = await env.MY_BUCKET.get(key, {
          onlyIf: request.headers,
          range: request.headers,
        });

        if (object === null) {
          return new Response("Object Not Found", { status: 404 });
        }

        const headers = new Headers();
        object.writeHttpMetadata(headers);
        headers.set("etag", object.httpEtag);

        // When no body is present, preconditions have failed
        return new Response("body" in object ? object.body : undefined, {
          status: "body" in object ? 200 : 412,
          headers,
        });
      }
      case "DELETE": {
        await env.MY_BUCKET.delete(key);
        return new Response("Deleted!");
      }
      default:
        return new Response("Method Not Allowed", {
          status: 405,
          headers: {
            Allow: "PUT, GET, DELETE",
          },
        });
    }
  }
}
from workers import WorkerEntrypoint, Response
from urllib.parse import urlparse


class Default(WorkerEntrypoint):
	async def fetch(self, request):
		url = urlparse(request.url)
		key = url.path[1:]

		if request.method == "PUT":
			await self.env.MY_BUCKET.put(
				key,
				request.body,
				onlyIf=request.headers,
				httpMetadata=request.headers,
			)
			return Response(f"Put {key} successfully!")
		elif request.method == "GET":
			obj = await self.env.MY_BUCKET.get(
				key,
				onlyIf=request.headers,
				range=request.headers,
			)

			if obj is None:
				return Response("Object Not Found", status=404)

			# When no body is present, preconditions have failed
			body = obj.body if hasattr(obj, "body") else None
			status = 200 if hasattr(obj, "body") else 412

			headers = {"etag": obj.httpEtag}
			return Response(body, status=status, headers=headers)
		elif request.method == "DELETE":
			await self.env.MY_BUCKET.delete(key)
			return Response("Deleted!")
		else:
			return Response(
				"Method Not Allowed",
				status=405,
				headers={"Allow": "PUT, GET, DELETE"},
			)

5. 存储桶访问与隐私

将上述代码添加到 Worker 后，每个传入请求都能与存储桶交互。这意味着存储桶公开暴露，其内容可能被非预期行为者访问和修改。

您现在必须定义授权逻辑，确定谁可以对存储桶执行哪些操作。此逻辑位于 Worker 代码中，因为确定用户权限是应用的职责。以下是与访问和授权实践相关的资源简短列表：

  1. Basic Authentication：展示如何使用 HTTP Basic 方案限制访问。
  2. Using Custom Headers：基于请求头中已知的预共享密钥允许或拒绝请求。

继续使用新创建的存储桶和 Worker，您需要保护所有存储桶操作。

对于 PUT 和 DELETE 请求，您将使用新的 AUTH_KEY_SECRET 环境变量，稍后将其定义为 Wrangler secret。

对于 GET 请求，您将确保只能请求特定文件。所有这些自定义逻辑在 authorizeRequest 函数内发生，hasValidHeader 函数处理自定义请求头逻辑。若所有验证通过，则允许操作。

const ALLOW_LIST = ["cat-pic.jpg"];

// Check requests for a pre-shared secret
const hasValidHeader = (request, env) => {
	return request.headers.get("X-Custom-Auth-Key") === env.AUTH_KEY_SECRET;
};

function authorizeRequest(request, env, key) {
	switch (request.method) {
		case "PUT":
		case "DELETE":
			return hasValidHeader(request, env);
		case "GET":
			return ALLOW_LIST.includes(key);
		default:
			return false;
	}
}

export default {
	async fetch(request, env, ctx) {
		const url = new URL(request.url);
		const key = url.pathname.slice(1);

		if (!authorizeRequest(request, env, key)) {
			return new Response("Forbidden", { status: 403 });
		}

		// ...
	},
};
from workers import WorkerEntrypoint, Response
from urllib.parse import urlparse

ALLOW_LIST = ["cat-pic.jpg"]

# Check requests for a pre-shared secret
def has_valid_header(request, env):
	return request.headers.get("X-Custom-Auth-Key") == env.AUTH_KEY_SECRET

def authorize_request(request, env, key):
	if request.method in ["PUT", "DELETE"]:
		return has_valid_header(request, env)
	elif request.method == "GET":
		return key in ALLOW_LIST
	else:
		return False

class Default(WorkerEntrypoint):
	async def fetch(self, request):
		url = urlparse(request.url)
		key = url.path[1:]

		if not authorize_request(request, self.env, key):
			return Response("Forbidden", status=403)

		# ...

要使此功能生效，您需要通过 Wrangler 创建 secret：

npx wrangler secret put AUTH_KEY_SECRET

此命令会提示您在终端中输入 secret：

npx wrangler secret put AUTH_KEY_SECRET
Enter the secret text you'd like assigned to the variable AUTH_KEY_SECRET on the script named <YOUR_WORKER_NAME>:
*********
🌀  Creating the secret for script name <YOUR_WORKER_NAME>
✨  Success! Uploaded secret AUTH_KEY_SECRET.

此 secret 现可在 Worker 的 env 参数上作为 AUTH_KEY_SECRET 使用。

6. 部署 Worker

Worker 和存储桶设置完成后，运行 npx wrangler deploy 命令部署到 Cloudflare 全球网络：

npx wrangler deploy

您可以使用已部署的 Worker 端点，通过以下命令验证授权逻辑是否生效：

# Attempt to write an object without providing the "X-Custom-Auth-Key" header
curl https://your-worker.dev/cat-pic.jpg -X PUT --data-binary 'test'
#=> Forbidden
# Expected because header was missing

# Attempt to write an object with the wrong "X-Custom-Auth-Key" header value
curl https://your-worker.dev/cat-pic.jpg -X PUT --header "X-Custom-Auth-Key: hotdog" --data-binary 'test'
#=> Forbidden
# Expected because header value did not match the AUTH_KEY_SECRET value

# Attempt to write an object with the correct "X-Custom-Auth-Key" header value
# Note: Assume that "*********" is the value of your AUTH_KEY_SECRET Wrangler secret
curl https://your-worker.dev/cat-pic.jpg -X PUT --header "X-Custom-Auth-Key: *********" --data-binary 'test'
#=> Put cat-pic.jpg successfully!

# Attempt to read object called "foo"
curl https://your-worker.dev/foo
#=> Forbidden
# Expected because "foo" is not in the ALLOW_LIST

# Attempt to read an object called "cat-pic.jpg"
curl https://your-worker.dev/cat-pic.jpg
#=> test
# Note: This is the value that was successfully PUT above

完成本指南后，您已成功安装 Wrangler 并将 R2 存储桶部署到 Cloudflare。

相关资源

  1. Workers Tutorials
  2. Workers Examples

这篇文档对您有帮助吗？