初始化文档

2025-12-06 15:26:10 +08:00 · 2025-11-09 14:21:55 +08:00
commit e97717dfe7
26 changed files with 8747 additions and 0 deletions
--- a/docs/storage/r2.md
+++ b/docs/storage/r2.md
@@ -0,0 +1,390 @@
+---
+title: Cloudflare R2
+createTime: 2025/11/09 00:26:55
+permalink: /storage/r2
+---
+# Cloudflare R2 配置指南
+
+详细的 Cloudflare R2 配置步骤和最佳实践。
+
+## 概述
+
+Cloudflare R2 是一个 S3 兼容的对象存储服务，具有以下优势：
+
+- 💚 存储流量完全免费
+- 🌍 全球 CDN 加速
+- 💰 请求费用低（每 100 万次 $0.36）
+- ⚡ 高性能和高可靠性
+- 🔄 S3 API 完全兼容
+
+## 账户设置
+
+### 1. 创建 Cloudflare 账户
+
+访问 [Cloudflare 官网](https://dash.cloudflare.com/sign-up) 创建免费账户。
+
+### 2. 激活 R2
+
+1. 登录 Cloudflare 控制面板
+2. 左侧菜单选择 "R2"
+3. 点击 "开始使用 R2"
+4. 阅读条款并确认
+
+## 创建存储桶
+
+### 1. 创建新桶
+
+1. 进入 R2 → "存储桶"
+2. 点击 "创建存储桶"
+3. 输入存储桶名称（例如 `my-storage`）
+   - 名称必须全局唯一
+   - 只能包含小写字母、数字和连字符
+4. 选择区域（通常选择 "自动" APAC）
+5. 点击 "创建存储桶"
+
+### 2. 存储桶设置
+
+进入存储桶 → "设置"：
+
+- **CORS**: 启用 CORS 以支持跨域请求
+- **生命周期规则**: 可选，用于自动删除过期文件
+- **版本控制**: 保持禁用（不需要版本历史）
+
+## 获取 API 凭证
+
+### 1. 创建 API Token
+
+1. 进入 R2 → "API 令牌"
+2. 点击 "创建 API 令牌"
+3. 选择 "Edit" 权限（允许读写）
+4. 配置 TTL（可选，默认无限期）
+5. 复制 **Token ID** 和 **Token Secret**
+6. 点击 "创建 API 令牌"
+
+**权限说明：**
+
+- **读取**: 仅允许列表和下载
+- **编辑**: 允许读、写和删除（推荐）
+- **删除**: 包含删除和管理员操作
+
+### 2. 记录账户 ID
+
+在 R2 仪表盘的任何存储桶页面可以看到 **Account ID**（例如 `a1b2c3d4e5f6g7h8i`）
+
+保存以下信息：
+
+```env
+ACCESS_KEY_ID = your_token_id
+SECRET_ACCESS_KEY = your_token_secret
+R2_ACCOUNT_ID = your_account_id
+R2_BUCKET_NAME = your-bucket-name
+```
+
+## 配置环境变量
+
+编辑 `.env` 文件：
+
+```env
+# 存储类型
+STORAGE_TYPE=r2
+
+# API 凭证
+ACCESS_KEY_ID=your_token_id
+SECRET_ACCESS_KEY=your_token_secret
+
+# R2 配置
+R2_ENDPOINT_URL=https://your_account_id.r2.cloudflarestorage.com
+R2_BUCKET_NAME=your-bucket-name
+R2_REGION=auto
+
+# 可选：公开访问配置
+R2_PUBLIC_URL=https://pub-your-bucket-name.r2.dev
+
+# 可选：预签名 URL 过期时间（秒，默认 3600）
+R2_PRESIGN_EXPIRES=3600
+```
+
+## 配置公开访问（可选）
+
+若要生成可分享的公开链接，需要配置公开 URL。
+
+### 1. 启用公开访问
+
+1. 进入存储桶 → "设置"
+2. 找到 "Public access" 部分
+3. 点击 "Allow public access"
+
+### 2. 配置自定义域（推荐）
+
+#### 方式 A：使用 R2 默认 URL
+
+```env
+R2_PUBLIC_URL=https://pub-your-bucket-name.r2.dev
+```
+
+#### 方式 B：使用自定义域
+
+1. 进入存储桶 → "设置" → "Custom domains"
+2. 点击 "Connect domain"
+3. 输入你的域名（例如 `assets.example.com`）
+4. 在域名 DNS 设置中添加 CNAME 记录：
+
+   ```
+   assets.example.com CNAME your-bucket-name.r2.dev
+   ```
+
+5. 点击 "Continue"
+
+配置环境变量：
+
+```env
+R2_PUBLIC_URL=https://assets.example.com
+```
+
+## 与 CDN 集成
+
+### 方式 A：Cloudflare CDN（推荐）
+
+R2 已与 Cloudflare CDN 整合：
+
+1. 进入存储桶设置
+2. CDN 部分会自动显示 CDN 可用性
+3. 公开访问的文件会自动通过 CDN 加速
+
+### 方式 B：其他 CDN 供应商
+
+若使用其他 CDN（如 Akamai、AWS CloudFront）：
+
+1. 配置 CDN 源指向 R2
+2. CDN 会自动缓存文件
+3. 在应用中使用 CDN URL
+
+```env
+# 使用 CDN 加速
+R2_PUBLIC_URL=https://your-cdn-url.com
+```
+
+## 测试连接
+
+### 方式一：启动应用测试
+
+```bash
+python app.py
+```
+
+访问 `http://localhost:5000`，查看是否能正常显示文件列表。
+
+### 方式二：使用 CLI 测试
+
+```bash
+# 安装 aws cli
+pip install awscli
+
+# 配置凭证
+aws configure --profile r2
+
+# 输入以下信息：
+# AWS Access Key ID: your_token_id
+# AWS Secret Access Key: your_token_secret
+# Default region: auto
+
+# 测试连接
+aws s3 ls s3://your-bucket-name --profile r2 --endpoint-url https://your_account_id.r2.cloudflarestorage.com
+```
+
+### 方式三：Python 测试
+
+```python
+import boto3
+
+s3 = boto3.client(
+    's3',
+    endpoint_url='https://your_account_id.r2.cloudflarestorage.com',
+    aws_access_key_id='your_token_id',
+    aws_secret_access_key='your_token_secret',
+    region_name='auto'
+)
+
+# 列出所有对象
+response = s3.list_objects_v2(Bucket='your-bucket-name')
+for obj in response.get('Contents', []):
+    print(obj['Key'])
+```
+
+## 常见配置
+
+### 启用 CORS
+
+如果需要从浏览器直接上传文件到 R2：
+
+1. 进入存储桶 → "设置"
+2. 找到 CORS 部分
+3. 添加以下规则：
+
+```json
+[
+  {
+    "AllowedOrigins": ["*"],
+    "AllowedMethods": ["GET", "HEAD", "PUT", "POST", "DELETE"],
+    "AllowedHeaders": ["*"],
+    "ExposeHeaders": ["ETag"]
+  }
+]
+```
+
+### 生命周期规则（可选）
+
+自动删除旧文件以节省成本：
+
+1. 进入存储桶 → "设置" → "生命周期规则"
+2. 点击 "添加规则"
+3. 配置规则：
+   - **前缀**: 可选（如 `cache/`）
+   - **在上传后删除**: 指定天数（如 30 天）
+4. 点击 "添加"
+
+## 监控和管理
+
+### 查看使用情况
+
+1. 进入 R2 仪表盘
+2. 查看 "存储使用" 和 "请求统计"
+3. 可以看到：
+   - 存储桶大小（GB）
+   - 月度请求数
+   - 估计费用
+
+### 管理文件
+
+通过 Cloudflare 控制面板：
+
+1. 进入存储桶 → "对象"
+2. 可以：
+   - 📁 浏览文件夹
+   - 📥 上传文件
+   - 📤 下载文件
+   - 🗑️ 删除文件
+   - 📋 查看详情
+
+也可以通过 Cloud Index 应用管理：
+
+访问应用 UI 进行所有文件操作。
+
+## 最佳实践
+
+### 1. 安全性
+
+- ✅ 使用编辑权限 Token（最小权限原则）
+- ✅ 定期轮换凭证
+- ✅ 不要在版本控制中提交凭证
+- ✅ 使用 `.env` 文件管理凭证
+
+### 2. 性能优化
+
+- ✅ 启用 R2 CDN 加速
+- ✅ 设置合理的缓存 TTL
+- ✅ 定期清理过期文件
+- ✅ 使用生命周期规则自动清理
+
+### 3. 成本控制
+
+- ✅ 设置存储使用警告
+- ✅ 定期检查费用
+- ✅ 删除不需要的文件
+- ✅ 使用生命周期规则
+
+### 4. 监控
+
+- ✅ 定期检查使用统计
+- ✅ 设置告警
+- ✅ 记录访问日志
+- ✅ 备份重要数据
+
+## 常见问题
+
+### Q: 如何获取文件的公开 URL？
+
+**A:** 在 Cloud Index 应用中：
+
+1. 点击文件菜单
+2. 选择 "复制链接"
+3. 分享链接
+
+### Q: 如何上传大文件？
+
+**A:** R2 支持多部分上传（通过应用自动处理）：
+
+- 单个文件最大 5GB
+- 应用会自动分块上传
+
+### Q: 费用会很高吗？
+
+**A:** R2 价格极低：
+
+- 存储：每月每 GB $0.015
+- 请求：每 100 万次 $0.36
+- 流量：完全免费 ✅
+
+典型用户月费 < $1
+
+### Q: 可以删除 API Token 吗？
+
+**A:** 可以，但需要谨慎：
+
+1. 进入 R2 → "API 令牌"
+2. 找到 Token 点击删除
+3. 需要配置新 Token 后才能继续使用应用
+
+## 故障排除
+
+### 连接失败
+
+检查：
+
+1. 凭证是否正确
+2. 端点 URL 是否正确（包含 Account ID）
+3. 存储桶名称是否正确
+4. 网络连接是否正常
+
+### 上传失败
+
+检查：
+
+1. Token 权限是否为 "编辑" 或更高
+2. 存储桶是否存在
+3. 文件名是否有效
+4. 磁盘空间是否充足
+
+### 文件无法访问
+
+检查：
+
+1. 是否启用了公开访问
+2. R2_PUBLIC_URL 配置是否正确
+3. CDN 是否正常工作
+4. 文件权限设置
+
+## 成本示例
+
+假设月均使用情况：
+
+| 指标 | 数值 | 费用 |
+|-----|------|------|
+| 存储 | 10GB | $0.15 |
+| 请求 | 100K | $0.036 |
+| 流量 | 1TB | $0 |
+| **总计** | - | **$0.186** |
+
+极低成本！✅
+
+## 获取帮助
+
+- 📖 [Cloudflare R2 官方文档](https://developers.cloudflare.com/r2/)
+- 🐛 [提交 Issue](https://github.com/RhenCloud/Cloud-Index/issues)
+- 💬 [讨论区](https://github.com/RhenCloud/Cloud-Index/discussions)
+
+## 下一步
+
+- 🚀 [快速开始](../guide/quickstart.md) - 开始使用应用
+- 📖 [其他存储后端](./overview.md) - 对比其他服务
+- 💾 [S3 配置](./s3.md) - AWS S3 配置