如何申请 Cloudflare R2 S3 访问令牌
如何申请 Cloudflare R2 S3 访问令牌
TG-FF 通过 S3 兼容 API 读写 Cloudflare R2 存储桶时，需要你在 R2 控制台创建 Account API 令牌，并获取以下凭据：
- Access Key ID（访问密钥 ID）
- Secret Access Key（机密访问密钥）
- S3 Endpoint（S3 终结点）
本教程会带你完成从进入 R2 到复制凭据的全过程。
!!! warning "安全提示" S3 访问令牌相当于存储桶密钥，不要发给他人，也不要提交到公开仓库。Secret Access Key 只在创建时完整显示一次，关闭页面后无法再次查看。
!!! info "与 Cloudflare API Token 的区别"
本文创建的是 R2 S3 访问令牌（Access Key / Secret Key），用于 S3 客户端读写对象。
若需配置 Workers、D1 等 Cloudflare 服务，请参考 如何为 Cloudflare 账号申请 API Token。
开始之前，请先准备好
| 准备项 | 说明 |
|---|---|
| Cloudflare 账号 | 已注册并可以登录 控制台 |
| 已开通 R2 | 若尚未开通，请先阅读 如何注册 Cloudflare 账号并开通 R2 存储 |
| 电脑浏览器 | 建议使用 Chrome、Edge 或 Safari，界面以中文为例 |
| 记事本或密码管理器 | 用于保存 Access Key、Secret Key 和 Endpoint |
第一步：进入 R2 并打开 API 令牌管理
- 登录 Cloudflare 控制台
- 左侧菜单找到 「存储和数据库」 → 「R2 对象存储」
- 在右侧 「账户详情」 区域，找到 「API 令牌」 一行
- 点击右侧 「管理」 按钮
!!! tip "同页还可复制" 在 账户详情 中，你还可以直接复制 账户 ID 和 S3 API 终结点地址，后续配置 S3 客户端时会用到。
第二步：创建 Account API 令牌
进入 R2 对象存储 的 API 令牌页面后，你会看到两类令牌：
| 类型 | 说明 | 推荐场景 |
|---|---|---|
| 账户 API 令牌 | 与整个账户关联，即使用户离开组织也仍然有效 | 生产环境（推荐） |
| 用户 API 令牌 | 与用户账号绑定，用户离开组织后失效 | 个人开发、临时测试 |
TG-FF 对接 R2 建议使用 账户 API 令牌：
- 在 「账户 API 令牌」 区域，点击 「创建 Account API 令牌」
第三步：配置权限并创建
在创建页面按以下方式配置：
3.1 选择权限
选择 「管理员读和写」：
- 允许创建、列出和删除存储桶
- 允许编辑存储桶配置
- 允许对对象及其元数据进行读取、写入和列出
这是 TG-FF 正常读写 R2 对象所需的权限。
3.2 设置 TTL
将 TTL 设置为 「永久」，避免令牌过期导致服务中断。
若你希望定期轮换密钥，也可以改为固定天数，到期前需重新创建并更新 TG-FF 配置。
3.3 客户端 IP 地址筛选（可选）
默认留空即可，表示 允许所有 IP 使用该令牌。
若你的服务器 IP 固定，可在 「包括」 中填入 IP 或 CIDR 段，进一步限制访问来源。
3.4 点击创建
核对无误后，点击页面底部 「创建 Account API 令牌」。
第四步：复制 S3 凭据
创建成功后，页面会显示 「为 S3 客户端使用以下凭据」。请 立即 复制并保存：
| 凭据 | 说明 |
|---|---|
| 访问密钥 ID | 即 Access Key ID，S3 客户端的用户名 |
| 机密访问密钥 | 即 Secret Access Key，S3 客户端的密码 |
| S3 终结点 | 选择 「默认」 标签页下的 Endpoint URL |
操作步骤：
- 点击 「访问密钥 ID」 下方字段，复制 Access Key ID
- 点击 「机密访问密钥」 下方字段，复制 Secret Access Key
- 在 「默认」 标签下，复制 S3 终结点 URL
- 将三项凭据保存到安全位置
- 确认已保存后，点击 「完成」 关闭页面
!!! warning "凭据只显示一次" 页面底部蓝色提示：出于安全原因，这些令牌值不会再次显示。 若当时没有复制 Secret Access Key，只能删除旧令牌并重新创建。
在 TG-FF 中填写
将第四步复制的信息填入 TG-FF 的 R2 / S3 配置项：
| 配置项 | 对应凭据 |
|---|---|
| Access Key ID | 访问密钥 ID |
| Secret Access Key | 机密访问密钥 |
| Endpoint / S3 API | 默认标签下的 S3 终结点 |
若 TG-FF 还需要 存储桶名称，请在 R2 控制台的存储桶列表中查看（例如 tg-ff-stream）。
常见问题
应该选 Account 还是 User API 令牌？
TG-FF 长期运行建议使用 Account API 令牌。User 令牌绑定个人账号，人员变动时可能失效，更适合临时调试。
权限可以选「仅读」吗？
若 TG-FF 只需要下载、不需要上传，可以选 「管理员只读」。需要上传媒体或写入对象时，请使用 「管理员读和写」。
与 Cloudflare API Token 有什么关系？
两者独立、用途不同：
| 项目 | R2 S3 访问令牌 | Cloudflare API Token |
|---|---|---|
| 格式 | Access Key ID + Secret Access Key | 单一 Token 字符串 |
| 协议 | S3 兼容 API | Cloudflare REST API |
| 典型用途 | 读写 R2 对象 | Workers、D1、KV 等管理 |
TG-FF 若同时用到 R2 对象存储和 Workers，两项可能 都需要 分别配置。
Secret Access Key 丢失了怎么办？
- 回到 R2 API 令牌 管理页
- 删除（撤销） 旧令牌
- 按本教程重新创建
- 在 TG-FF 中更新为新凭据
界面是英文的怎么办？
Cloudflare 控制台可在账户设置中将语言切换为 简体中文，菜单名称与本文截图一致。
流程回顾
flowchart LR
A[R2 账户详情] --> B[管理 API 令牌]
B --> C[创建 Account API 令牌]
C --> D[配置权限与 TTL]
D --> E[复制 Access Key 与 Secret]
E --> F[填入 TG-FF 配置]按以上步骤操作，你就能为 TG-FF 创建 R2 S3 访问令牌。若尚未开通 R2，请先阅读 R2 开通教程。遇到问题可加入 TG-FF 用户交流群 交流。