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

本文最后更新于:5 个月前

原文地址
本文内容已尽可能与原格式相同,如有遗漏,请多海涵。
本文于此Commit下翻译

R2入门指南

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

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

购买R2

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

购买R2:

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

1. 安装Wrangler

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

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

1
npm install -D wrangler

或用Yarn安装:

1
yarn add wrangler

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

2. 认证Wrangler

安装完成后,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

3. 创建您的存储桶

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

1
wrangler r2 bucket create <YOUR_BUCKET_NAME>

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

1
wrangler r2 bucket list

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

4. 将您的R2存储桶绑定在Worker上

你需要存储桶绑定在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的更多详细信息。

5. 通过worker访问您的R2存储桶

在您的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) {
casePUT”:
await MY_BUCKET.put(key, request.body);
return new Response(`Put ${key} successfully!`);
caseGET”:
const object = await MY_BUCKET.get(key);

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

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

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

6. 存储桶访问和隐私

将上述代码添加到您的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) {
casePUT’:
caseDELETE’:
return hasValidHeader(request);
caseGET’:
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可用。

7. 部署你的存储桶

一切准备就绪,设置完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的原英文内容
  2. 译者注:这个提示框的原文为:
    “A binding is a how your Worker interacts with external resources such as KV Namespaces , Durable Objects , or R2 Buckets . A binding is a runtime variable that the Workers runtime provides to your code. You can declare a variable name in your wrangler.toml file that will be bound to these resources at runtime, and interact with them through this variable. Every binding’s variable name and behavior is determined by you when deploying the Worker. Refer to the Environment VariablesOpen external link documentation for more information.
    A binding is defined in the wrangler.toml file of your Worker project’s directory.” 水平有限,若翻译有误,欢迎批评指正

Cloudflare R2 快速开始使用指南教程 | 中文翻译
https://www.morax-xyc.com/post/fbc493de/
作者
Morax-xyc
发布于
2022年5月11日
更新于
2022年5月12日
许可协议