From 22b2339d3c4e0e145cf0ce83088dcdf874620416 Mon Sep 17 00:00:00 2001 From: RhenCloud Date: Sat, 15 Nov 2025 19:37:35 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E5=B9=B6=E6=B7=BB=E5=8A=A0=20OneDrive=20=E6=94=AF=E6=8C=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 在 overview.md 中添加 OneDrive 到存储后端对比 - 更新导航栏和 plume.config 以包含 OneDrive 链接 - 创建详细的 OneDrive 配置指南 - 从 GitHub 和 S3 文档中删除冗余章节 - 将 .env 和缓存目录添加到 .gitignore --- .gitignore | 4 + docs/.vuepress/navbar.ts | 1 + docs/.vuepress/plume.config.ts | 1 + docs/storage/github.md | 200 ------------------- docs/storage/onedrive.md | 337 +++++++++++++++++++++++++++++++++ docs/storage/overview.md | 160 +++++++--------- docs/storage/r2.md | 223 ---------------------- docs/storage/s3.md | 212 --------------------- 8 files changed, 415 insertions(+), 723 deletions(-) create mode 100644 docs/storage/onedrive.md diff --git a/.gitignore b/.gitignore index 3e78964..1b460e9 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,7 @@ docs/.vuepress/dist .DS_Store *.log .vercel + +.env +__pycache__/ +.VSCodeCounter/ \ No newline at end of file diff --git a/docs/.vuepress/navbar.ts b/docs/.vuepress/navbar.ts index 3ad3d5a..71773da 100644 --- a/docs/.vuepress/navbar.ts +++ b/docs/.vuepress/navbar.ts @@ -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" }, ], }, ]); diff --git a/docs/.vuepress/plume.config.ts b/docs/.vuepress/plume.config.ts index 3a5e953..5735967 100644 --- a/docs/.vuepress/plume.config.ts +++ b/docs/.vuepress/plume.config.ts @@ -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" }, ], }, ], diff --git a/docs/storage/github.md b/docs/storage/github.md index 7426702..b66e2ee 100644 --- a/docs/storage/github.md +++ b/docs/storage/github.md @@ -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 | diff --git a/docs/storage/onedrive.md b/docs/storage/onedrive.md new file mode 100644 index 0000000..cacf77c --- /dev/null +++ b/docs/storage/onedrive.md @@ -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 主分支 diff --git a/docs/storage/overview.md b/docs/storage/overview.md index 4eb097e..6dd43dd 100644 --- a/docs/storage/overview.md +++ b/docs/storage/overview.md @@ -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) diff --git a/docs/storage/r2.md b/docs/storage/r2.md index ea7fa90..5a4b423 100644 --- a/docs/storage/r2.md +++ b/docs/storage/r2.md @@ -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. 文件权限设置 - ## 成本示例 假设月均使用情况： diff --git a/docs/storage/s3.md b/docs/storage/s3.md index 4241513..58a1aee 100644 --- a/docs/storage/s3.md +++ b/docs/storage/s3.md @@ -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/)