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

feat: 更新文档并添加 OneDrive 支持

Browse Source 
- 在 overview.md 中添加 OneDrive 到存储后端对比
- 更新导航栏和 plume.config 以包含 OneDrive 链接
- 创建详细的 OneDrive 配置指南
- 从 GitHub 和 S3 文档中删除冗余章节
- 将 .env 和缓存目录添加到 .gitignore
This commit is contained in:
RhenCloud
2025-11-15 19:37:35 +08:00
parent 641a729592
commit 22b2339d3c
8 changed files with 415 additions and 723 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@@ -7,3 +7,7 @@ docs/.vuepress/dist
.DS_Store
*.log
.vercel
.env
__pycache__/
.VSCodeCounter/

1
docs/.vuepress/navbar.ts
View File

@@ -24,6 +24,7 @@ export default defineNavbarConfig([
{ text: "Cloudflare R2", link: "/storage/r2" },
{ text: "Amazon S3", link: "/storage/s3" },
{ text: "GitHub", link: "/storage/github" },
{ text: "OneDrive", link: "/storage/onedrive" },
],
},
]);

1
docs/.vuepress/plume.config.ts
View File

@@ -102,6 +102,7 @@ export default defineThemeConfig({
{ text: "Cloudflare R2", link: "/storage/r2" },
{ text: "Amazon S3", link: "/storage/s3" },
{ text: "GitHub", link: "/storage/github" },
{ text: "OneDrive", link: "/storage/onedrive" },
],
},
],

200
docs/storage/github.md
View File

@@ -152,95 +152,6 @@ git push -u origin main
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
```
## 启用版本控制特性
### 查看文件历史
@@ -296,37 +207,6 @@ https://raw.ghproxy.com/https://raw.githubusercontent.com/your-username/my-stora
2. 选择 "复制链接"
3. 分享链接给他人
## 最佳实践
### 1. 安全性
- ✅ 使用 Personal Access Token 而非用户密码
- ✅ 定期轮换 Token
- ✅ 为 Token 设置过期时间
- ✅ 不要分享 Token
- ✅ 使用私密仓库存储敏感信息
- ✅ 不要在公开仓库存储个人数据
### 2. 性能优化
- ✅ 使用国内代理加速（如 ghproxy）
- ✅ 定期清理不需要的文件
- ✅ 合理组织文件结构
- ✅ 使用分支管理大型项目
### 3. 仓库管理
- ✅ 保持仓库大小 < 1GB
- ✅ 每个文件 < 100MB
- ✅ 定期清理历史版本
- ✅ 使用 `.gitignore` 排除不需要的文件
### 4. 备份
- ✅ 定期备份重要文件
- ✅ 使用 Git 本地备份
- ✅ 定期推送到其他服务（如 GitLab）
## 高级配置
### 使用 GitHub Actions 自动化
@@ -401,86 +281,6 @@ 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 |

337
docs/storage/onedrive.md Normal file
View File

@@ -0,0 +1,337 @@
---
title: OneDrive
createTime: 2025/11/15 00:00:00
permalink: /storage/onedrive
---
使用 Microsoft OneDrive 作为存储后端的详细配置。
## 概述
OneDrive 是微软提供的云存储服务，与 Cloud Index 完美集成：
- 💼 企业级可靠性
- 🔄 自动同步和备份
- 🌐 全球访问
- 🔐 强大的权限管理
- 📊 丰富的文件管理功能
- 🖼️ 图片缩略图和预览
## 为什么选择 OneDrive？
### 优势
1. **免费存储空间** - 个人用户 5GB 免费，Microsoft 365 订阅用户 1TB+
2. **自动同步** - 本地文件自动同步到云端
3. **Office 集成** - 与 Office 套件完美集成，在线编辑
4. **版本历史** - 自动保存文件版本，轻松恢复
5. **跨平台支持** - Windows、Mac、iOS、Android 全平台支持
6. **企业级安全** - 支持企业账户，强大的安全控制
### 限制
- 免费用户存储空间有限（5GB）
- 需要 Microsoft 账户
- 文件大小限制（个人版单文件最大 250GB）
### 推荐用途
- 📄 个人文档和笔记
- 🖼️ 照片和图片库
- 🎥 视频文件
- 📁 项目文件管理
- 👥 团队协作文件
- 🔄 需要跨设备同步的文件
## 账户设置
### 1. 创建 Microsoft 账户
如果还没有 Microsoft 账户，访问 [Microsoft](https://signup.live.com) 创建一个免费账户。
### 2. 注册 Azure 应用
要使用 OneDrive API，需要在 Microsoft Entra（Azure AD）中注册应用：
1. 访问 [Azure Portal](https://portal.azure.com)
2. 搜索 "Microsoft Entra ID"（或 "Azure Active Directory"）
3. 左侧菜单选择 "应用注册"
4. 点击 "新注册"
5. 填写应用信息：
- **名称**：例如 `Cloud Index`
- **支持的账户类型**：选择 "任何组织目录中的账户和个人 Microsoft 账户"
- **重定向 URI**：选择 "Web"，输入 `http://localhost:5000/callback`
6. 点击 "注册"
### 3. 配置应用权限
注册完成后，配置 API 权限：
1. 进入应用详情页
2. 左侧菜单选择 "API 权限"
3. 点击 "添加权限"
4. 选择 "Microsoft Graph"
5. 选择 "委托的权限"
6. 搜索并添加以下权限：
- ✅ **Files.ReadWrite.All** - 读写所有文件（必需）
- ✅ **offline_access** - 获取刷新令牌（必需）
- ❌ openid, profile - 可选，用于获取用户信息
7. 点击 "添加权限"
8. 点击 "代表 XXX 授予管理员同意"（如果是管理员）
### 4. 创建客户端密钥
1. 左侧菜单选择 "证书和密码"
2. 点击 "新客户端密码"
3. 输入描述（例如 `Cloud Index Secret`）
4. 选择过期时间（推荐 "24 个月"）
5. 点击 "添加"
6. **立即复制密钥值**（只显示一次）
保存以下信息：
```env
应用程序(客户端) ID = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
客户端密钥值 = your_client_secret_value
```
⚠️ **重要**: 不要分享你的客户端密钥！
## 获取刷新令牌
### 1. 构造授权 URL
使用以下模板构造授权 URL（替换 `YOUR_CLIENT_ID`）：
```
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=http://localhost:5000/callback&scope=Files.ReadWrite.All offline_access
```
### 2. 获取授权码
1. 在浏览器中打开上述 URL
2. 使用 Microsoft 账户登录
3. 同意应用权限
4. 浏览器会跳转到 `http://localhost:5000/callback?code=xxx`
5. 复制 URL 中的 `code` 参数值
### 3. 交换刷新令牌
使用授权码交换刷新令牌。可以使用以下 PowerShell 命令：
```powershell
$body = @{
client_id = 'YOUR_CLIENT_ID'
client_secret = 'YOUR_CLIENT_SECRET'
code = 'YOUR_AUTHORIZATION_CODE'
redirect_uri = 'http://localhost:5000/callback'
grant_type = 'authorization_code'
}
$response = Invoke-RestMethod -Method Post -Uri 'https://login.microsoftonline.com/common/oauth2/v2.0/token' -Body $body
$response.refresh_token
```
或使用 Python：
```python
import requests
data = {
'client_id': 'YOUR_CLIENT_ID',
'client_secret': 'YOUR_CLIENT_SECRET',
'code': 'YOUR_AUTHORIZATION_CODE',
'redirect_uri': 'http://localhost:5000/callback',
'grant_type': 'authorization_code'
}
response = requests.post(
'https://login.microsoftonline.com/common/oauth2/v2.0/token',
data=data
)
print(response.json()['refresh_token'])
```
保存返回的 `refresh_token`。
## 配置环境变量
编辑 `.env` 文件：
```env
# 存储类型
STORAGE_TYPE=onedrive
# OneDrive 配置
ONEDRIVE_CLIENT_ID=your_client_id
ONEDRIVE_CLIENT_SECRET=your_client_secret
ONEDRIVE_REFRESH_TOKEN=your_refresh_token
# 可选：指定文件夹
# ONEDRIVE_FOLDER_ID=folder_item_id # 留空使用根目录
# 可选：重定向 URI（如果与授权时不同）
# ONEDRIVE_REDIRECT_URI=http://localhost:5000/callback
# 可选：自定义权限范围
# ONEDRIVE_SCOPES="Files.ReadWrite.All offline_access"
```
**配置说明：**
- `ONEDRIVE_CLIENT_ID`: Azure 应用的客户端 ID（必需）
- `ONEDRIVE_CLIENT_SECRET`: Azure 应用的客户端密钥（必需）
- `ONEDRIVE_REFRESH_TOKEN`: OAuth 刷新令牌（必需）
- `ONEDRIVE_FOLDER_ID`: 指定文件夹作为根目录（可选）
- `ONEDRIVE_REDIRECT_URI`: 重定向 URI（可选）
- `ONEDRIVE_SCOPES`: 自定义权限范围（可选）
## 环境变量详细说明
| 变量 | 必需 | 默认值 | 说明 |
|------|------|--------|------|
| `STORAGE_TYPE` | ✅ | - | 必须设置为 `onedrive` |
| `ONEDRIVE_CLIENT_ID` | ✅ | - | Azure 应用的客户端 ID |
| `ONEDRIVE_CLIENT_SECRET` | ✅ | - | Azure 应用的客户端密钥 |
| `ONEDRIVE_REFRESH_TOKEN` | ✅ | - | OAuth 刷新令牌 |
| `ONEDRIVE_FOLDER_ID` | ❌ | `root` | 指定文件夹作为根目录 |
| `ONEDRIVE_REDIRECT_URI` | ❌ | - | 重定向 URI，应与授权时一致 |
| `ONEDRIVE_SCOPES` | ❌ | - | 自定义权限范围 |
## 高级配置
### 使用特定文件夹作为根目录
如果要将 OneDrive 中的某个文件夹作为 Cloud Index 的根目录：
1. 在 OneDrive 中找到目标文件夹
2. 使用 Microsoft Graph Explorer 获取文件夹 ID：
- 访问 [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer)
- 登录并授权
- 执行 GET 请求：`https://graph.microsoft.com/v1.0/me/drive/root:/your/folder/path`
- 从响应中复制 `id` 字段
3. 在 `.env` 中设置：
```env
3. 在 `.env` 中设置：
```env
ONEDRIVE_FOLDER_ID=01BYE5RZ6QN3ZWBTUFOFD3GSPGOHDJD36K
```
### 公共客户端配置
如果应用注册为"公共客户端"（桌面/移动应用）：
- 可以省略 `ONEDRIVE_CLIENT_SECRET`
- 但推荐使用机密客户端以提高安全性
### 企业账户配置
使用企业 OneDrive（OneDrive for Business）：
1. 在 Azure AD 中注册应用
2. 配置相同的权限
3. 使用企业账户登录授权
4. 其他配置步骤相同
## 成本估算
### 个人账户
- **免费存储**: 5GB
- **API 调用**: 无限制（有速率限制）
- **流量**: 无限制
- **总成本**: **免费** ✅
### Microsoft 365 个人版
- **月费**: ¥398/年（约 ¥33/月）
- **存储空间**: 1TB
- **额外功能**: Office 套件、高级安全功能
- **适用场景**: 个人用户、小团队
### Microsoft 365 商业版
- **月费**: ¥75-150/用户/月（根据套餐）
- **存储空间**: 1TB/用户起
- **额外功能**: 企业级管理、合规性工具
- **适用场景**: 中小企业、大型团队
## 与其他存储对比
| 特性 | OneDrive | R2 | S3 | GitHub |
|-----|----------|-----|-----|---------|
| **价格** | 💰 付费/限时免费 | 💚 低成本 | 💛 按需计费 | 💚 免费 |
| **存储空间** | 5GB-1TB+ | 无限 | 无限 | 1GB 限制 |
| **Office 集成** | ✅ 完美 | ❌ 无 | ❌ 无 | ❌ 无 |
| **版本历史** | ✅ 自动 | ❌ 无 | ❌ 无 | ✅ Git |
| **全球 CDN** | ✅ 有 | ✅ 有 | ✅ 有 | ⚠️ 可选 |
| **易用性** | ✅ 简单 | ✅ 简单 | ⚠️ 中等 | ✅ 简单 |
| **适用场景** | 个人/企业 | 个人/小团队 | 企业 | 开源/文档 |
## 迁移指南
### 从其他存储迁移到 OneDrive
1. **备份原有数据**
2. **配置 OneDrive** - 按照本指南完成配置
3. **迁移数据** - 使用批量上传工具
4. **验证数据** - 确保所有文件正确迁移
5. **更新配置** - 修改 Cloud Index 配置
6. **测试功能** - 验证所有功能正常
### 从 OneDrive 迁移到其他存储
1. **选择目标存储** - 确定迁移目标（R2/S3/GitHub）
2. **导出数据** - 批量下载所有文件
3. **配置新存储** - 完成目标存储配置
4. **上传数据** - 使用批量上传工具
5. **更新配置** - 修改环境变量
6. **验证迁移** - 确保数据完整
## 参考资源
### 官方文档
- [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/api/overview)
- [OneDrive API 参考](https://docs.microsoft.com/en-us/graph/api/resources/onedrive)
- [OAuth 2.0 授权](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow)
- [Azure AD 应用注册](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
### 工具和资源
- [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer) - 测试 API
- [Azure Portal](https://portal.azure.com) - 管理应用
- [OneDrive 开发者中心](https://developer.microsoft.com/en-us/onedrive)
### 社区资源
- [Cloud Index GitHub](https://github.com/RhenCloud/Cloud-Index)
- [OneDrive API Stack Overflow](https://stackoverflow.com/questions/tagged/onedrive)
- [Microsoft Graph 社区](https://techcommunity.microsoft.com/t5/microsoft-graph/ct-p/MicrosoftGraph)
## 相关文档
- [GitHub 存储配置](/storage/github)
- [Cloudflare R2 配置](/storage/r2)
- [Amazon S3 配置](/storage/s3)
- [存储概述](/storage/overview)
- [快速开始](/guide/quickstart)
- [环境变量配置](/guide/configuration/environment)
## 获取帮助
遇到问题？
1. 查看 [常见问题](#常见问题) 章节
2. 访问 [GitHub Issues](https://github.com/RhenCloud/Cloud-Index/issues)
3. 查阅 [官方文档](https://docs.microsoft.com/en-us/graph/)
4. 加入社区讨论
---
**更新日期**: 2025-11-15
**适用版本**: Cloud Index 主分支

160
docs/storage/overview.md
View File

@@ -9,16 +9,16 @@ Cloud Index 支持多个存储后端，可根据需求选择合适的服务。
## 后端对比
| 特性 | Cloudflare R2 | Amazon S3 | GitHub Repository |
|-----|------------|----------|------------------|
| **定价模式** | 流量免费 + 请求费 | 流量费 + 请求费 + 存储费 | 免费（通过 GitHub） |
| **价格水平** | 💚 最低 | 💛 中等 | 💚 免费 |
| **全球覆盖** | ✅ 全球 CDN | ✅ 全球 CDN | ✅ CDN 加速可选 |
| **易用性** | ✅ 简单 | ⚠️ 中等 | ✅ 简单 |
| **可扩展性** | ✅ 无限制 | ✅ 无限制 | ⚠️ 仓库大小限制（1GB） |
| **性能** | 🚀 优秀 | 🚀 优秀 | 🚀 优秀（配合 CDN） |
| **版本控制** | ❌ 无 | ❌ 无 | ✅ 自动 Git 历史 |
| **适用场景** | 个人/小团队 | 企业 | 开源/文档 |
| 特性 | Cloudflare R2 | Amazon S3 | OneDrive | GitHub Repository |
|-----|------------|----------|----------|------------------|
| **定价模式** | 流量免费 + 请求费 | 流量费 + 请求费 + 存储费 | 订阅制 | 免费（通过 GitHub） |
| **价格水平** | 💚 最低 | 💛 中等 | 💰 付费/限时免费 | 💚 免费 |
| **全球覆盖** | ✅ 全球 CDN | ✅ 全球 CDN | ✅ 全球覆盖 | ✅ CDN 加速可选 |
| **易用性** | ✅ 简单 | ⚠️ 中等 | ✅ 简单 | ✅ 简单 |
| **可扩展性** | ✅ 无限制 | ✅ 无限制 | ⚠️ 5GB-1TB+ | ⚠️ 仓库大小限制（1GB） |
| **性能** | 🚀 优秀 | 🚀 优秀 | 🚀 优秀 | 🚀 优秀（配合 CDN） |
| **版本控制** | ❌ 无 | ❌ 无 | ✅ 自动版本历史 | ✅ 自动 Git 历史 |
| **适用场景** | 个人/小团队 | 企业 | 个人/企业协作 | 开源/文档 |
## 快速选择指南
@@ -83,43 +83,67 @@ Cloud Index 支持多个存储后端，可根据需求选择合适的服务。
- 完全免费 ✅
### 选择 OneDrive
**如果你需要：**
- ✅ Office 集成
- ✅ 自动同步
- ✅ 版本历史
- ✅ 跨平台支持
**推荐用途：**
- 个人文档管理
- 团队协作文件
- Office 文档编辑
- 照片和视频存储
- 跨设备文件同步
**成本估算：**
- 个人版：免费 5GB，Microsoft 365 订阅 ¥398/年（1TB）
- 企业版：¥75-150/用户/月
## 功能特性对比
### 文件操作
| 操作 | R2 | S3 | GitHub |
|-----|-----|-----|---------|
| 上传 | ✅ | ✅ | ✅ |
| 下载 | ✅ | ✅ | ✅ |
| 删除 | ✅ | ✅ | ✅ |
| 列表 | ✅ | ✅ | ✅ |
| 重命名 | ✅ | ✅ | ✅ |
| 复制 | ✅ | ✅ | ⚠️ (需支持) |
| 移动 | ✅ | ✅ | ⚠️ (需支持) |
| 操作 | R2 | S3 | OneDrive | GitHub |
|-----|-----|-----|----------|---------|
| 上传 | ✅ | ✅ | ✅ | ✅ |
| 下载 | ✅ | ✅ | ✅ | ✅ |
| 删除 | ✅ | ✅ | ✅ | ✅ |
| 列表 | ✅ | ✅ | ✅ | ✅ |
| 重命名 | ✅ | ✅ | ✅ | ✅ |
| 复制 | ✅ | ✅ | ✅ | ⚠️ (需支持) |
| 移动 | ✅ | ✅ | ✅ | ⚠️ (需支持) |
### 高级功能
| 功能 | R2 | S3 | GitHub |
|-----|-----|-----|---------|
| 公开访问 URL | ✅ | ✅ | ✅ |
| 预签名 URL | ✅ | ✅ | ✅ |
| CDN 集成 | ✅ | ✅ | ✅ |
| 版本控制 | ❌ | ⚠️ (付费) | ✅ |
| 生命周期策略 | ✅ | ✅ | ❌ |
| 访问控制 | ✅ | ✅ | ✅ (Git 权限) |
| 功能 | R2 | S3 | OneDrive | GitHub |
|-----|-----|-----|----------|---------|
| 公开访问 URL | ✅ | ✅ | ✅ | ✅ |
| 预签名 URL | ✅ | ✅ | ✅ | ✅ |
| CDN 集成 | ✅ | ✅ | ✅ | ✅ |
| 版本控制 | ❌ | ⚠️ (付费) | ✅ | ✅ |
| 生命周期策略 | ✅ | ✅ | ❌ | ❌ |
| 访问控制 | ✅ | ✅ | ✅ | ✅ (Git 权限) |
| Office 在线编辑 | ❌ | ❌ | ✅ | ❌ |
| 缩略图预览 | ⚠️ | ⚠️ | ✅ | ❌ |
## 性能基准
基于 1 千次请求、1GB 文件的测试：
| 操作 | R2 | S3 | GitHub |
|-----|-----|-----|---------|
| **列表** | ~50ms | ~80ms | ~150ms |
| **上传** | ~300ms | ~350ms | ~500ms |
| **下载** | ~100ms | ~120ms | ~200ms |
| **删除** | ~100ms | ~120ms | ~200ms |
| 操作 | R2 | S3 | OneDrive | GitHub |
|-----|-----|-----|----------|---------|
| **列表** | ~50ms | ~80ms | ~120ms | ~150ms |
| **上传** | ~300ms | ~350ms | ~400ms | ~500ms |
| **下载** | ~100ms | ~120ms | ~150ms | ~200ms |
| **删除** | ~100ms | ~120ms | ~150ms | ~200ms |
*注：实际性能取决于网络距离和文件大小*
> **注意**：实际性能取决于网络距离和文件大小
## 成本对比（月均）
@@ -133,51 +157,25 @@ Cloud Index 支持多个存储后端，可根据需求选择合适的服务。
|-----|-------|--------|--------|------|
| **R2** | 免费 | $0.36 | 免费 | **$0.36** 💚 |
| **S3** | $2.30 | $0.50 | $4.57 | **$7.37** |
| **OneDrive** | ¥33/月 | 免费 | 免费 | **¥33/月** (1TB) |
| **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 等工具
```
> **说明**：OneDrive 个人版 5GB 免费，Microsoft 365 订阅 ¥398/年（约 ¥33/月）提供 1TB 空间
## 如何选择
### 决策树
```
```text
是否需要完全免费？
├─ 是 → GitHub Repository ✅
└─ 否
└─ 是否需要企业级功能？
├─ 是 → Amazon S3 ✅
└─ 否 → Cloudflare R2 ✅（最佳平衡）
└─ 是否需要 Office 集成？
├─ 是 → OneDrive ✅
└─ 否
└─ 是否需要企业级功能？
├─ 是 → Amazon S3 ✅
└─ 否 → Cloudflare R2 ✅（最佳平衡）
```
### 快速决策表
@@ -186,9 +184,11 @@ cd repo
|-----|------|------|
| 个人博客 | GitHub | 免费且简单 |
| 小团队文件 | R2 | 成本低，性能好 |
| Office 文档 | OneDrive | Office 集成，在线编辑 |
| 企业应用 | S3 | 功能完整，支持好 |
| 大规模存储 | R2 | 流量免费，成本最低 |
| 版本控制重要 | GitHub | 自动 Git 历史 |
| 版本控制重要 | GitHub/OneDrive | 自动版本历史 |
| 团队协作 | OneDrive | 实时协作，权限管理 |
## 后续配置
@@ -196,17 +196,11 @@ cd repo
- **[Cloudflare R2 配置](./r2.md)** - 详细配置步骤
- **[Amazon S3 配置](./s3.md)** - AWS S3 设置
- **[OneDrive 配置](./onedrive.md)** - Microsoft OneDrive 配置
- **[GitHub 存储配置](./github.md)** - GitHub 仓库配置
## 常见问题
### Q: 可以中途更换存储后端吗？
**A:** 可以！只需修改 `.env` 文件中的 `STORAGE_TYPE` 环境变量。但需要：
- 手动迁移现有文件
- 重新配置凭证
### Q: 多个后端能同时使用吗？
**A:** 目前不支持，但可以：
@@ -221,19 +215,9 @@ cd repo
- **R2**: 每月前 1000 万请求免费 ✅
- **S3**: 新用户 12 个月免费套餐
- **OneDrive**: 个人用户 5GB 免费 ✅
- **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)

223
docs/storage/r2.md
View File

@@ -141,229 +141,6 @@ R2_PUBLIC_URL=https://pub-your-bucket-name.r2.dev
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. 文件权限设置
## 成本示例
假设月均使用情况：

212
docs/storage/s3.md
View File

@@ -252,218 +252,6 @@ S3_PUBLIC_URL=https://assets.example.com
- **过期对象删除标记**：勾选
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/)