RhenCloud/Cloud-Index
1
0
Fork 0
mirror of https://github.com/RhenCloud/Cloud-Index.git synced 2025-12-06 15:26:10 +08:00
Code Issues Packages Projects Releases Wiki Activity

初始化文档

Browse Source
This commit is contained in:
RhenCloud
2025-11-09 14:21:55 +08:00
commit e97717dfe7
26 changed files with 8747 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

516
docs/storage/github.md Normal file
View File

@@ -0,0 +1,516 @@
---
title: GitHub
createTime: 2025/11/09 00:26:55
permalink: /storage/github
---
# GitHub 存储配置指南
使用 GitHub 仓库作为存储后端的详细配置。
## 概述
GitHub 存储是一个创新的免费存储方案，利用 GitHub 仓库来存储文件：
- 💚 完全免费（通过 GitHub）
- 📝 自动版本控制
- 🔐 私密仓库支持
- 🌍 全球访问
- 📦 便于备份和迁移
## 为什么选择 GitHub 存储？
### 优势
1. **完全免费** - 无需付费，利用 GitHub 存储空间
2. **自动版本控制** - 所有文件自动保存版本历史
3. **内置权限管理** - 利用 GitHub 的访问权限系统
4. **易于备份** - 通过 Git 可以轻松备份和迁移
5. **开发者友好** - 与 Git 工作流完美集成
### 限制
- 仓库大小建议不超过 1GB
- 文件大小建议不超过 100MB
- 不适合大规模二进制文件存储
### 推荐用途
- 📄 文档和文本文件
- 🖼️ 博客和网站图片
- 🔧 配置文件
- 📋 CSV 数据文件
- 🎯 开源项目资源
## 账户设置
### 1. 创建 GitHub 账户
如果还没有 GitHub 账户，访问 [GitHub](https://github.com/signup) 创建一个免费账户。
### 2. 创建仓库
1. 登录 GitHub
2. 点击 "+" 图标 → "New repository"
3. 输入仓库名称（例如 `my-storage`）
4. 选择 "Private"（私密）或 "Public"（公开）
5. **不要** 初始化 README
6. 点击 "Create repository"
## 生成 Personal Access Token
### 1. 创建 Token
1. 登录 GitHub
2. 进入 Settings → Developer settings → Personal access tokens
3. 点击 "Generate new token"（选择 "Tokens (classic)"）
4. 输入 Token 名称（例如 `cloud-index`）
5. 选择过期时间（推荐 "90 days" 或 "No expiration"）
### 2. 设置权限
选择以下权限：
- ✅ **repo** - 完整控制私有仓库（包括所有子权限）
- ✅ **workflow** - 更新 GitHub Action 工作流
- ❌ 其他权限保持未勾选
### 3. 生成并复制 Token
1. 点击 "Generate token"
2. **立即复制 Token**（只显示一次）
3. 保存到安全位置
⚠️ **重要**: 不要分享你的 Token！
## 配置环境变量
编辑 `.env` 文件：
```env
# 存储类型
STORAGE_TYPE=github
# GitHub 账户信息
GITHUB_REPO_OWNER=your-username
GITHUB_REPO_NAME=my-storage
GITHUB_ACCESS_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# 可选：使用的分支
GITHUB_BRANCH=main
# 可选：GitHub Raw 内容代理（用于加速国内访问）
GITHUB_RAW_PROXY_URL=https://raw.ghproxy.com
# 可选：预签名 URL 过期时间（秒）
GITHUB_PRESIGN_EXPIRES=3600
```
**配置说明：**
- `GITHUB_REPO_OWNER`: 你的 GitHub 用户名
- `GITHUB_REPO_NAME`: 创建的仓库名称
- `GITHUB_ACCESS_TOKEN`: 生成的 Personal Access Token
- `GITHUB_BRANCH`: 默认 `main`（仓库主分支）
- `GITHUB_RAW_PROXY_URL`: 可选，用于加速访问
## 国内加速代理配置
由于 GitHub 在国内访问速度较慢，推荐使用代理加速：
### 推荐代理服务
```env
# GitHub 官方（无加速）
GITHUB_RAW_PROXY_URL=
# ghproxy.com - 国内加速（推荐）
GITHUB_RAW_PROXY_URL=https://raw.ghproxy.com
# ghproxy.net - 国内加速
GITHUB_RAW_PROXY_URL=https://ghproxy.net
# 其他代理服务
GITHUB_RAW_PROXY_URL=https://raw.fastgit.org
```
## 初始化仓库
首次使用时，需要初始化仓库（可选但推荐）：
```bash
# 克隆空仓库
git clone https://github.com/your-username/my-storage.git
cd my-storage
# 创建初始文件
echo "# 存储仓库" > README.md
git add README.md
git commit -m "Initial commit"
git push -u origin main
# 返回 Cloud Index 目录
cd ../cloud-index
```
## 测试连接
### 方式一：启动应用测试
```bash
python app.py
```
访问 `http://localhost:5000`，查看是否能正常显示文件列表。
### 方式二：使用 CLI 测试
```bash
# 测试 Token 是否有效
curl -H "Authorization: token ghp_xxx" \
https://api.github.com/repos/your-username/my-storage
# 应该返回仓库信息
```
### 方式三：Python 测试
```python
import requests
token = "ghp_xxx"
repo_owner = "your-username"
repo_name = "my-storage"
headers = {
"Authorization": f"token {token}",
"Accept": "application/vnd.github.v3+json"
}
url = f"https://api.github.com/repos/{repo_owner}/{repo_name}/contents"
response = requests.get(url, headers=headers)
if response.status_code == 200:
print("连接成功！")
print("仓库文件：")
for item in response.json():
print(f" - {item['name']} ({item['type']})")
else:
print(f"连接失败！错误代码：{response.status_code}")
```
## 管理仓库
### 通过 Cloud Index 管理
应用提供完整的文件管理功能：
- 📁 浏览文件和文件夹
- ⬆️ 上传文件
- 🗑️ 删除文件
- ✏️ 重命名文件
- 📂 创建新文件夹
### 通过 GitHub Web 管理
1. 访问你的仓库主页
2. 点击 "Add file" → "Upload files"
3. 选择要上传的文件
4. 点击 "Commit changes"
### 通过 Git 命令行管理
```bash
# 克隆仓库
git clone https://github.com/your-username/my-storage.git
cd my-storage
# 添加文件
cp /path/to/file .
# 提交更改
git add .
git commit -m "Add new files"
git push
# 删除文件
git rm filename
git commit -m "Remove file"
git push
# 查看历史
git log
```
## 启用版本控制特性
### 查看文件历史
1. 在 GitHub Web 上打开文件
2. 点击 "History"
3. 查看所有历史版本
### 恢复旧版本文件
```bash
# 查看文件历史
git log -- filename
# 恢复到特定版本
git checkout <commit-hash> -- filename
# 提交恢复
git commit -m "Restore filename to previous version"
git push
```
### 标记发布版本
```bash
# 创建标签
git tag -a v1.0 -m "Release version 1.0"
git push origin v1.0
# 查看所有标签
git tag -l
```
## 生成公开访问 URL
### Raw 文件 URL
文件会自动通过 Raw GitHub URL 访问：
```
# 官方 URL（国外快）
https://raw.githubusercontent.com/your-username/my-storage/main/path/to/file
# 使用代理加速（国内快）
https://raw.ghproxy.com/https://raw.githubusercontent.com/your-username/my-storage/main/path/to/file
```
### 在应用中生成
在 Cloud Index 应用中：
1. 点击文件
2. 选择 "复制链接"
3. 分享链接给他人
## 最佳实践
### 1. 安全性
- ✅ 使用 Personal Access Token 而非用户密码
- ✅ 定期轮换 Token
- ✅ 为 Token 设置过期时间
- ✅ 不要分享 Token
- ✅ 使用私密仓库存储敏感信息
- ✅ 不要在公开仓库存储个人数据
### 2. 性能优化
- ✅ 使用国内代理加速（如 ghproxy）
- ✅ 定期清理不需要的文件
- ✅ 合理组织文件结构
- ✅ 使用分支管理大型项目
### 3. 仓库管理
- ✅ 保持仓库大小 < 1GB
- ✅ 每个文件 < 100MB
- ✅ 定期清理历史版本
- ✅ 使用 `.gitignore` 排除不需要的文件
### 4. 备份
- ✅ 定期备份重要文件
- ✅ 使用 Git 本地备份
- ✅ 定期推送到其他服务（如 GitLab）
## 高级配置
### 使用 GitHub Actions 自动化
可以创建自动化工作流（可选）：
```yaml
# .github/workflows/backup.yml
name: Daily Backup
on:
schedule:
- cron: '0 0 * * *'
jobs:
backup:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Backup
run: |
# 你的备份脚本
echo "Backup completed"
```
### 使用分支隔离环境
为不同环境使用不同分支：
```bash
# 创建开发分支
git checkout -b develop
git push -u origin develop
# 创建生产分支
git checkout -b production
git push -u origin production
```
## 文件大小限制处理
如果遇到文件过大（> 100MB）：
### 使用 Git LFS
```bash
# 安装 Git LFS
git lfs install
# 追踪大文件
git lfs track "*.psd"
git add .gitattributes
# 提交文件
git add large-file.psd
git commit -m "Add large file"
git push
```
### 分割文件
```bash
# 分割大文件
split -b 50M large-file.zip large-file.zip.part_
# 上传分割后的文件
git add large-file.zip.part_*
git commit -m "Add split files"
git push
# 恢复时合并
cat large-file.zip.part_* > large-file.zip
```
## 常见问题
### Q: 如何更新 Token？
**A:**
1. 生成新 Token
2. 更新 `.env` 文件中的 `GITHUB_ACCESS_TOKEN`
3. 重启应用
### Q: Token 过期了怎么办？
**A:**
1. 进入 GitHub Settings
2. 重新生成 Token
3. 更新应用配置
### Q: 可以在组织中使用吗？
**A:** 可以，配置仓库的所有者为组织名即可：
```env
GITHUB_REPO_OWNER=my-organization
```
### Q: 仓库大小有限制吗？
**A:** GitHub 建议仓库不超过 1GB。如果超过：
1. 清理不需要的历史版本
2. 使用 Git LFS
3. 分割仓库
### Q: 可以在多个应用中使用同一仓库吗？
**A:** 可以，但需要注意并发冲突。建议：
1. 为每个环境创建不同的仓库
2. 使用分支隔离
3. 定期同步
## 故障排除
### 连接失败
检查：
1. Token 是否正确
2. 仓库名称是否正确
3. 用户名是否正确
4. 网络连接是否正常
5. Token 是否过期
### Token 无效
解决方案：
1. 重新生成 Token
2. 确保有 `repo` 权限
3. 检查 Token 是否过期
### 文件无法访问
检查：
1. 仓库是否存在
2. 文件是否已提交
3. 是否使用了正确的分支
4. 代理 URL 是否正确
### 上传缓慢
优化方案：
1. 配置国内代理
2. 分割大文件
3. 检查网络连接
4. 考虑使用其他存储后端
## 与其他存储的对比
| 特性 | GitHub | R2 | S3 |
|-----|--------|-----|-----|
| 成本 | 免费 | $0.36/百万请求 | $2-3/GB |
| 文件大小限制 | 100MB | 无限 | 5TB |
| 仓库大小限制 | 1GB | 无限 | 无限 |
| 版本控制 | ✅ | ❌ | ⚠️ |
| 适合大文件 | ❌ | ✅ | ✅ |
## 成本示例
月均使用情况：
| 指标 | 数值 | 费用 |
|-----|------|------|
| 存储 | 500MB | 免费 |
| 请求 | 10K | 免费 |
| 流量 | 1GB | 免费 |
| **总计** | - | **完全免费** ✅ |
## 获取帮助
- 📖 [GitHub API 文档](https://docs.github.com/en/rest)
- 📖 [GitHub 仓库管理指南](https://docs.github.com/en/repositories)
- 🐛 [提交 Issue](https://github.com/RhenCloud/Cloud-Index/issues)
- 💬 [讨论区](https://github.com/RhenCloud/Cloud-Index/discussions)
## 下一步
- 🚀 [快速开始](../guide/quickstart.md) - 开始使用应用
- 📖 [存储后端对比](./overview.md) - 对比其他服务
- 💾 [Cloudflare R2 配置](./r2.md) - R2 配置指南

239
docs/storage/overview.md Normal file
View File

@@ -0,0 +1,239 @@
---
title: 后端概览
createTime: 2025/11/09 00:26:55
permalink: /storage/overview
---
# 存储后端概览
Cloud Index 支持多个存储后端，可根据需求选择合适的服务。
## 后端对比
| 特性 | Cloudflare R2 | Amazon S3 | GitHub Repository |
|-----|------------|----------|------------------|
| **定价模式** | 流量免费 + 请求费 | 流量费 + 请求费 + 存储费 | 免费（通过 GitHub） |
| **价格水平** | 💚 最低 | 💛 中等 | 💚 免费 |
| **全球覆盖** | ✅ 全球 CDN | ✅ 全球 CDN | ✅ CDN 加速可选 |
| **易用性** | ✅ 简单 | ⚠️ 中等 | ✅ 简单 |
| **可扩展性** | ✅ 无限制 | ✅ 无限制 | ⚠️ 仓库大小限制（1GB） |
| **性能** | 🚀 优秀 | 🚀 优秀 | 🚀 优秀（配合 CDN） |
| **版本控制** | ❌ 无 | ❌ 无 | ✅ 自动 Git 历史 |
| **适用场景** | 个人/小团队 | 企业 | 开源/文档 |
## 快速选择指南
### 选择 Cloudflare R2
**如果你需要：**
- ✅ 最低成本
- ✅ 快速启动
- ✅ 全球加速
- ✅ 简单配置
**推荐用途：**
- 个人云盘
- 小团队文件存储
- 媒体文件托管
- 备份存储
**成本估算（月均）：**
- 1GB 存储 + 1 万请求 = $0.001 左右（极低）
### 选择 Amazon S3
**如果你需要：**
- ✅ 完整功能
- ✅ 企业级服务
- ✅ 高可靠性
- ✅ 专业支持
**推荐用途：**
- 企业级应用
- 生产环境存储
- 大规模数据存储
- 需要合规性的应用
**成本估算（月均）：**
- 1GB 存储 + 1 万请求 = $0.023 左右（按需计费）
### 选择 GitHub Repository
**如果你需要：**
- ✅ 完全免费
- ✅ 版本控制
- ✅ 简单易用
- ✅ 便于备份
**推荐用途：**
- 文档存储
- 配置文件
- 小文件共享
- 开源项目资源
- 博客图片
**成本估算：**
- 完全免费 ✅
## 功能特性对比
### 文件操作
| 操作 | R2 | S3 | GitHub |
|-----|-----|-----|---------|
| 上传 | ✅ | ✅ | ✅ |
| 下载 | ✅ | ✅ | ✅ |
| 删除 | ✅ | ✅ | ✅ |
| 列表 | ✅ | ✅ | ✅ |
| 重命名 | ✅ | ✅ | ✅ |
| 复制 | ✅ | ✅ | ⚠️ (需支持) |
| 移动 | ✅ | ✅ | ⚠️ (需支持) |
### 高级功能
| 功能 | R2 | S3 | GitHub |
|-----|-----|-----|---------|
| 公开访问 URL | ✅ | ✅ | ✅ |
| 预签名 URL | ✅ | ✅ | ✅ |
| CDN 集成 | ✅ | ✅ | ✅ |
| 版本控制 | ❌ | ⚠️ (付费) | ✅ |
| 生命周期策略 | ✅ | ✅ | ❌ |
| 访问控制 | ✅ | ✅ | ✅ (Git 权限) |
## 性能基准
基于 1 千次请求、1GB 文件的测试：
| 操作 | R2 | S3 | GitHub |
|-----|-----|-----|---------|
| **列表** | ~50ms | ~80ms | ~150ms |
| **上传** | ~300ms | ~350ms | ~500ms |
| **下载** | ~100ms | ~120ms | ~200ms |
| **删除** | ~100ms | ~120ms | ~200ms |
*注：实际性能取决于网络距离和文件大小*
## 成本对比（月均）
假设场景：
- 存储：10GB
- 月请求：100,000
- 流量：500GB
| 服务 | 存储费 | 请求费 | 流量费 | 总计 |
|-----|-------|--------|--------|------|
| **R2** | 免费 | $0.36 | 免费 | **$0.36** 💚 |
| **S3** | $2.30 | $0.50 | $4.57 | **$7.37** |
| **GitHub** | 免费 | 免费 | 免费 | **免费** 🎉 |
## 迁移指南
### R2 → S3
```bash
# 使用 aws cli 迁移
aws s3 sync s3://r2-bucket/ s3://s3-bucket/ \
--source-profile r2 \
--profile s3
```
### S3 → R2
```bash
# 使用 aws cli 迁移
aws s3 sync s3://s3-bucket/ s3://r2-bucket/ \
--source-profile s3 \
--profile r2 \
--endpoint-url https://account.r2.cloudflarestorage.com
```
### GitHub → R2
```bash
# 1. 从 GitHub 克隆仓库
git clone https://github.com/user/repo.git
cd repo
# 2. 使用工具上传到 R2
# 使用 rclone、aws cli 等工具
```
## 如何选择
### 决策树
```
是否需要完全免费？
├─ 是 → GitHub Repository ✅
└─ 否
└─ 是否需要企业级功能？
├─ 是 → Amazon S3 ✅
└─ 否 → Cloudflare R2 ✅（最佳平衡）
```
### 快速决策表
| 场景 | 推荐 | 理由 |
|-----|------|------|
| 个人博客 | GitHub | 免费且简单 |
| 小团队文件 | R2 | 成本低，性能好 |
| 企业应用 | S3 | 功能完整，支持好 |
| 大规模存储 | R2 | 流量免费，成本最低 |
| 版本控制重要 | GitHub | 自动 Git 历史 |
## 后续配置
选择好存储后端后，按照相应指南进行配置：
- **[Cloudflare R2 配置](./r2.md)** - 详细配置步骤
- **[Amazon S3 配置](./s3.md)** - AWS S3 设置
- **[GitHub 存储配置](./github.md)** - GitHub 仓库配置
## 常见问题
### Q: 可以中途更换存储后端吗？
**A:** 可以！只需修改 `.env` 文件中的 `STORAGE_TYPE` 环境变量。但需要：
- 手动迁移现有文件
- 重新配置凭证
### Q: 多个后端能同时使用吗？
**A:** 目前不支持，但可以：
- 部署多个应用实例
- 每个实例使用不同后端
- 通过负载均衡器分流
### Q: 有免费额度吗？
**A:**
- **R2**: 每月前 1000 万请求免费 ✅
- **S3**: 新用户 12 个月免费套餐
- **GitHub**: 完全免费（通过 GitHub）✅
### Q: 如何监控使用成本？
**A:**
- **R2**: Cloudflare 控制面板实时显示
- **S3**: AWS 成本管理器
- **GitHub**: 不产生成本
## 获取帮助
- 📖 [R2 详细配置](./r2.md)
- 📖 [S3 详细配置](./s3.md)
- 📖 [GitHub 详细配置](./github.md)
- 🐛 [提交 Issue](https://github.com/RhenCloud/Cloud-Index/issues)

390
docs/storage/r2.md Normal file
View File

@@ -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 配置

478
docs/storage/s3.md Normal file
View File

@@ -0,0 +1,478 @@
---
title: Amazon S3
createTime: 2025/11/09 00:26:55
permalink: /storage/s3
---
# Amazon S3 配置指南
详细的 Amazon S3 配置步骤和最佳实践。
## 概述
Amazon S3（Simple Storage Service）是业界标准的对象存储服务，具有以下优势：
- 🏢 企业级服务
- 🔐 最高的安全性
- 📊 功能最完整
- 🌍 全球可用
- 📈 自动扩展
## 账户设置
### 1. 创建 AWS 账户
访问 [AWS 官网](https://aws.amazon.com/) 创建账户。新用户享受 12 个月免费套餐。
### 2. 访问 S3 控制台
1. 登录 AWS 管理控制台
2. 搜索 "S3"
3. 进入 S3 服务
## 创建存储桶
### 1. 创建新桶
1. 点击 "创建存储桶"
2. 输入存储桶名称（例如 `my-cloud-storage`）
- 名称必须全局唯一
- 只能包含小写字母、数字、连字符和点
3. 选择区域（例如 `ap-northeast-1` 东京）
4. **ACL** - 保持默认（禁用）
5. **阻止公有访问设置** - 根据需求配置（见下一步）
6. 点击 "创建存储桶"
### 2. 配置公开访问（可选）
若要让文件可以公开访问：
1. 进入存储桶 → "权限"
2. 找到 "阻止公有访问" 部分
3. 点击 "编辑"
4. **取消勾选** "阻止所有公有访问"
5. 点击 "保存"
### 3. 启用 ACL（仅在需要时）
1. 进入存储桶 → "权限"
2. 找到 "对象所有权" 部分
3. 点击 "编辑"
4. 选择 "ACL 已启用"
5. 点击 "保存"
## 创建 IAM 用户和凭证
### 1. 创建 IAM 用户
使用 IAM 用户而不是根账户更安全：
1. 进入 IAM 控制台
2. 左侧菜单 → "用户"
3. 点击 "创建用户"
4. 输入用户名（例如 `Cloud Index-user`）
5. 点击 "创建用户"
### 2. 配置权限
#### 方式 A：使用托管策略（推荐）
1. 进入用户详情
2. 点击 "添加权限" → "直接附加现有策略"
3. 搜索 "AmazonS3FullAccess"
4. 勾选并点击 "下一步"
5. 点击 "添加权限"
#### 方式 B：使用自定义策略（更安全）
1. 进入用户详情
2. 点击 "添加权限" → "创建内联策略"
3. 选择 JSON
4. 粘贴以下策略：
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListAllMyBuckets",
"s3:GetBucketLocation"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:GetObjectVersion",
"s3:ListBucketVersions"
],
"Resource": "arn:aws:s3:::my-cloud-storage"
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": "arn:aws:s3:::my-cloud-storage/*"
}
]
}
```
5. 点击 "创建策略"
### 3. 创建访问密钥
1. 进入用户详情
2. 点击 "安全凭证" 选项卡
3. 向下滚动到 "访问密钥"
4. 点击 "创建访问密钥"
5. 选择 "其他"
6. 点击 "下一步"
7. 复制 **Access Key ID** 和 **Secret Access Key**
8. 保存到安全位置
**⚠️ 重要**: 密钥只显示一次，请立即保存！
## 配置环境变量
编辑 `.env` 文件：
```env
# 存储类型
STORAGE_TYPE=s3
# AWS 凭证
ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# S3 配置
S3_BUCKET_NAME=my-cloud-storage
S3_REGION=ap-northeast-1
# 可选：公开访问配置
S3_PUBLIC_URL=https://my-cloud-storage.s3.ap-northeast-1.amazonaws.com
# 可选：预签名 URL 过期时间（秒，默认 3600）
S3_PRESIGN_EXPIRES=3600
```
## 常用 AWS 区域
选择离你最近的区域以获得最佳性能：
| 区域代码 | 位置 | 说明 |
|---------|------|------|
| `us-east-1` | 美国东部（N. Virginia） | 美国 |
| `us-west-2` | 美国西部（Oregon） | 美国西海岸 |
| `eu-west-1` | 欧洲（Ireland） | 欧洲 |
| `ap-northeast-1` | 亚太（Tokyo） | 日本、韩国 |
| `ap-southeast-1` | 亚太（Singapore） | 东南亚 |
| `cn-north-1` | 中国（北京） | 中国 |
## 配置公开访问 URL
### 方式 A：使用 S3 默认 URL
```env
S3_PUBLIC_URL=https://bucket-name.s3.region.amazonaws.com
```
### 方式 B：使用 CloudFront CDN
1. 进入 CloudFront 控制台
2. 点击 "创建分配"
3. 源域名：选择你的 S3 存储桶
4. 其他设置保持默认
5. 点击 "创建分配"
6. 等待部署（约 15-20 分钟）
7. 复制分配域名
配置环境变量：
```env
S3_PUBLIC_URL=https://d123abc456.cloudfront.net
```
### 方式 C：使用自定义域名
1. 使用 Route 53 或其他 DNS 服务
2. 创建 CNAME 记录指向 S3 或 CloudFront
3. 配置 SSL 证书
```env
S3_PUBLIC_URL=https://assets.example.com
```
## 启用 CORS（如需跨域请求）
1. 进入存储桶
2. 点击 "权限"
3. 向下滚动到 "CORS"
4. 点击 "编辑"
5. 粘贴以下配置：
```json
[
{
"AllowedHeaders": ["*"],
"AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
"AllowedOrigins": ["*"],
"ExposeHeaders": ["ETag"]
}
]
```
6. 点击 "保存更改"
## 启用版本控制（可选）
1. 进入存储桶
2. 点击 "属性"
3. 找到 "版本控制"
4. 点击 "编辑"
5. 选择 "启用"
6. 点击 "保存更改"
## 启用生命周期规则（自动清理）
自动删除过期文件以节省成本：
1. 进入存储桶
2. 点击 "管理"
3. 点击 "创建生命周期规则"
4. 输入规则名称（例如 `delete-old-cache`）
5. 配置规则：
- **前缀**：可选（如 `cache/`）
- **对象年龄**：30 天后删除
- **过期对象删除标记**：勾选
6. 点击 "创建规则"
## 测试连接
### 方式一：启动应用测试
```bash
python app.py
```
访问 `http://localhost:5000`，查看是否能正常显示文件列表。
### 方式二：使用 AWS CLI 测试
```bash
# 安装 aws cli
pip install awscli
# 配置凭证
aws configure
# 输入以下信息：
# AWS Access Key ID: AKIAIOSFODNN7EXAMPLE
# AWS Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# Default region: ap-northeast-1
# Default output format: json
# 测试连接
aws s3 ls s3://my-cloud-storage
```
### 方式三：Python 测试
```python
import boto3
s3 = boto3.client(
's3',
aws_access_key_id='AKIAIOSFODNN7EXAMPLE',
aws_secret_access_key='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
region_name='ap-northeast-1'
)
# 列出所有对象
response = s3.list_objects_v2(Bucket='my-cloud-storage')
for obj in response.get('Contents', []):
print(obj['Key'])
```
## 成本优化建议
### 1. 选择合适的存储类型
S3 提供多种存储类别：
| 类别 | 适用场景 | 成本 |
|------|---------|------|
| **S3 标准** | 经常访问的数据 | 💛 中等 |
| **S3 智能分层** | 访问模式不确定 | 自动优化 |
| **S3 标准-IA** | 不经常访问 | 💚 低 |
| **Glacier** | 归档数据 | 🔥 极低 |
默认使用 S3 标准即可。
### 2. 启用生命周期规则
自动将旧文件迁移到更便宜的存储类：
```json
{
"Transitions": [
{
"Days": 90,
"StorageClass": "GLACIER"
}
],
"Expiration": {
"Days": 180
}
}
```
### 3. 定期清理
1. 定期检查存储桶大小
2. 删除不需要的文件
3. 删除过期的版本
### 4. 监控成本
1. 进入 AWS 成本管理器
2. 设置成本告警
3. 定期审查费用
## 监控和管理
### 查看存储使用情况
1. 进入存储桶
2. 点击 "指标"
3. 可以看到：
- 存储桶大小
- 对象数量
- 请求统计
### 启用访问日志
1. 进入存储桶 → "属性"
2. 找到 "服务器访问日志"
3. 点击 "编辑"
4. 启用日志
5. 指定目标存储桶和前缀
6. 点击 "保存更改"
## 最佳实践
### 1. 安全性
- ✅ 使用 IAM 用户而非根账户
- ✅ 使用最小权限原则
- ✅ 定期轮换访问密钥
- ✅ 启用 MFA（多因素认证）
- ✅ 启用 CloudTrail 审计
- ✅ 不要在代码中提交凭证
### 2. 性能
- ✅ 使用 CloudFront CDN
- ✅ 启用传输加速（可选）
- ✅ 选择适当的区域
- ✅ 使用多部分上传（应用自动处理）
### 3. 可靠性
- ✅ 启用版本控制
- ✅ 启用 MFA 删除保护
- ✅ 启用服务器端加密
- ✅ 定期备份
### 4. 成本控制
- ✅ 使用生命周期规则
- ✅ 监控使用成本
- ✅ 定期清理过期数据
- ✅ 使用合适的存储类别
## 常见问题
### Q: 新用户有免费额度吗？
**A:** 是的！AWS 12 个月免费套餐包括：
- 5GB S3 存储
- 20,000 GET 请求
- 2,000 PUT 请求
之后按使用量计费。
### Q: 月费大概多少？
**A:** 取决于使用量。示例：
- 存储 100GB：~$2.30
- 请求 1M：~$0.50
- 流量 100GB：~$0.92
- **总计**：~$3.72/月
### Q: 如何降低成本？
**A:**
1. 使用 S3 标准-IA（便宜 50%）
2. 启用生命周期规则
3. 压缩文件
4. 使用 CloudFront CDN（减少 S3 请求）
### Q: 如何处理大文件上传？
**A:** S3 支持：
- 单个对象最大 5TB
- 应用自动使用多部分上传
- 没有大小限制
## 故障排除
### 连接失败
检查：
1. Access Key 和 Secret Key 是否正确
2. 区域代码是否正确
3. 存储桶名称是否正确
4. IAM 用户是否有 S3 权限
5. 网络连接是否正常
### 上传失败
检查：
1. IAM 用户是否有 `s3:PutObject` 权限
2. 存储桶是否存在
3. 文件名是否有效
4. 磁盘空间是否充足
### 公开文件无法访问
检查：
1. 是否启用了公开访问
2. 是否配置了正确的 URL
3. 是否启用了 CORS
4. CloudFront 是否正常工作
## 获取帮助
- 📖 [AWS S3 官方文档](https://docs.aws.amazon.com/s3/)
- 📖 [AWS SDK for Python 文档](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)
- 🐛 [提交 Issue](https://github.com/RhenCloud/Cloud-Index/issues>)
- 💬 [讨论区](https://github.com/RhenCloud/Cloud-Index/discussions)
## 下一步
- 🚀 [快速开始](../guide/quickstart.md) - 开始使用应用
- 📖 [存储后端对比](./overview.md) - 对比其他服务
- 💾 [Cloudflare R2 配置](./r2.md) - R2 配置指南