Cloudflare R2 快速开始使用指南教程 | 中文翻译

AI 摘要
Cloudflare R2存储允许开发人员存储大量非结构化数据,而无需支付与典型云存储服务相关的昂贵出口带宽费用。本指南介绍了如何购买R2、安装和认证Wrangler、创建存储桶、将存储桶绑定在Worker上,并访问和保护存储桶的方法。通过完成本指南,您可以成功部署R2存储桶并与之交互。
警告
本文最后更新于 2022-05-12,文中内容可能已过时。
提示
原文地址 本文内容已尽可能与原格式相同,如有遗漏,请多海涵。 本文于此Commit下翻译

Cloudflare R2存储允许开发人员存储大量非结构化数据,而无需支付与典型云存储服务相关的昂贵出口带宽费用。

本指南将指导您设置Wrangler部署第一个R2存储桶。

在创建第一个存储桶之前,您必须在Cloudflare仪表板中购买R2。

购买R2:

  1. 登录Cloudflare仪表板
  2. 帐户主页中,选择R2
  3. 选择购买R2计划
  4. 选择继续查看付款详情以查看您的付款。
  5. 选择返回 R2以前往 R2 面板。

要创建您的R2存储桶,请安装Wrangler,即Workers CLI。

安装wrangler,确保您已安装npm。使用像Volta这样的Node版本管理器或nvm以避免权限问题或轻松更改Node.js版本,然后运行:

1
npm install -D wrangler

或用Yarn安装:

1
yarn add wrangler

有关更多信息,请参阅Wrangler安装/更新页面(英文页面1)。

安装完成后,wrangler将需要访问Cloudflare OAuth令牌来代表您管理Worker资源。

运行wrangler login以自动化处理令牌。

Wrangler将尝试自动打开您的网页浏览器,以完成Cloudflare帐户的登录过程。如果您在完成此步骤时遇到问题,或者您无法访问浏览器GUI,您可以将wrangler login终端生成的URL复制并粘贴到浏览器中并登录。

1
2
3
4
wrangler login
Allow Wrangler to open a page in your browser? [y/n]
y
💁  Opened a link in your default browser: https://dash.cloudflare.com/oauth2/...

打开浏览器,登录您的帐户,然后选择Allow。这将向Wrangler发送OAuth令牌,以便它可以将您的脚本部署到Cloudflare。

版本要求
R2需要Wrangler1.19.8或更高版本。要检查您的Wrangler版本,请运行wrangler --version

通过运行以下操作创建存储桶:

1
wrangler r2 bucket create <YOUR_BUCKET_NAME>

要检查您的存储桶是否已创建,请运行:

1
wrangler r2 bucket list

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

你需要存储桶绑定在worker上使用。

绑定(Bindings)

binding[^2]是您的worker与KV命名空间、耐用对象或R2存储桶等外部资源交互的方式。binding是Workers运行时向您的代码提供的运行时变量。您可以在wrangler.toml文件中声明一个变量名,该变量名将在运行时绑定到这些资源,并通过此变量与它们交互。每个binding的变量名称和行为都由您在部署Worker时决定。请参阅环境变量(英文页面)的文档以了解更多信息。

Binding在Worker项目目录的wrangler.toml文件中定义。

使用官方提供的模板创建Worker。Wrangler模板是git存储库,旨在作为构建新的Cloudflare Workers项目的起点。

1
wrangler init <YOUR_WORKER_NAME>

接下来,在项目目录中找到新生成的wrangler.toml文件,并使用Cloudflare帐户ID更新account_id

通过登录Cloudflare仪表板>概述>向下移动到API>找到您的帐户ID,然后选择单击复制以复制您的帐户ID。或者运行wrangler whoami命令来复制您的帐户ID。

1
2
3
4
5
6
name = ”<YOUR_WORKER_NAME>"
type = ”javascript"
compatibility_date = 2022-04-18"

account_id = ”YOUR_ACCOUNT_ID" # ← Replace with your Account ID.
workers_dev = true

如果您需要使用较旧的兼容日期,则需要启用r2_public_beta_bindings标志(英文页面)。

为此,请更新您的wrangler.toml文件以包含以下内容:

1
2
3
# An example date older than ”2022-04-18"
compatibility_date = 2022-02-10"
compatibility_flags = [”r2_public_beta_bindings"]

要将R2存储桶绑定到您的Worker,请将以下内容添加到您的wrangler.toml文件中。将binding属性更新为有效的JavaScript变量标识符,并将bucket_name为您在步骤3中用于创建存储桶的<YOUR_BUCKET_NAME>

1
2
3
[[r2_buckets]]
binding = 'MY_BUCKET' # <~ valid JavaScript variable name
bucket_name = '<YOUR_BUCKET_NAME>'

Wrangler配置文档 (英文页面)中找到有关如何配置Worker的更多详细信息。

在您的Worker代码中,您的存储桶现在可以在MY_BUCKET变量下使用,您可以开始与它交互。

R2存储桶能够读取、列表、写入和删除对象。您可以使用Service Worker语法在下面看到所有操作的示例。将以下片段添加到项目的index.js文件中:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
addEventListener("fetch”, (event) => {
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request) {
  const url = new URL(request.url);
  const key = url.pathname.slice(1);

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

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

      return new Response(object.body);
    case "DELETE”:
      await MY_BUCKET.delete(key);
      return new Response("Deleted!, { status: 200 });

    default:
      return new Response("Route Not Found., { status: 404 });
  }
}

将上述代码添加到您的Worker中后,每个传入的请求都能够与您的存储桶进行交互。这意味着您的存储桶被公开暴露,其内容可以被公开且无需任何许可地访问和修改。

您现在必须定义授权逻辑,以确定谁可以对您的存储桶执行哪些操作。这种逻辑存在于您的Worker代码中,因为确定用户权限是应用程序的工作。以下是与访问和授权实践相关的资源的简单列表:

  1. 基本身份验证:展示如何使用HTTP基本模式限制访问。(英文页面)
  2. 使用自定义标头:允许或拒绝基于标题中已知的预共享密钥的请求。(英文页面)

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

对于PUTDELETE请求,您将使用一个新的AUTH_KEY_SECRET环境变量,稍后您将该变量定义为Wrangler secret。

对于GET请求,您将确保只能请求特定文件。所有这些自定义逻辑都发生在authorizeRequest函数中,hasValidHeader函数处理自定义标头逻辑。如果所有验证都通过了,则允许该操作。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
const ALLOW_LIST = ['cat-pic.webp'];
// Check requests for a pre-shared secret
const hasValidHeader = request => {
  return request.headers.get('X-Custom-Auth-Key') === AUTH_KEY_SECRET;
};

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

async function handleRequest(request) {
  const url = new URL(request.url);
  const key = url.pathname.slice(1);

  if (!authorizeRequest(request, key)) {
    return new Response('Forbidden', { status: 403 });
  }
  // ...

要做到这一点,您需要通过Wrangler创建一个Secret:

1
wrangler secret put AUTH_KEY_SECRET

此命令将提示您在终端中输入Secret:

1
2
3
4
5
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中的全局变量AUTH_KEY_SECRET可用。

一切准备就绪,设置完Worker和存储桶Bucket后,运行wrangler publish命令(英文页面)以部署到Cloudflare的全球网络:

1
wrangler publish

您可以使用已经部署的Worker 路由验证您的授权逻辑是否通过以下命令工作:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# Attempt to write an object without providing the "X-Custom-Auth-Key" header
curl https://your-worker.dev/cat-pic.webp -X PUT —header —data '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.webp -X PUT —header ”X-Custom-Auth-Key: hotdog" —data '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.webp -X PUT —header ”X-Custom-Auth-Key: *********" —data 'test'
#=> Put cat-pic1.webp 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.webp"
curl https://your-worker.dev/cat-pic.webp
#=> test
# Note: This is the value that was successfully PUT above

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

  1. Worker教程
  2. Worker示例

  1. 译者注:"(英文页面)”表示位于括号前方的超链接跳转地址并未被汉化,属于Cloudflare的原英文内容 ↩︎

相关内容