初始化文档

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/guide/introduction.md
+++ b/docs/guide/introduction.md
@@ -0,0 +1,228 @@
+---
+title: 项目介绍
+createTime: 2025/11/09 00:26:55
+permalink: /guide/introduction
+---
+# 项目介绍
+
+## 项目概述
+
+**Cloud Index** 是一个现代化的、功能完整的云存储文件管理系统。它提供了一个统一的文件浏览、管理和共享界面，支持多种云存储后端，使用户能够轻松地在不同的云存储服务之间切换。
+
+## 在线演示
+
+你可以在在线演示中体验 Cloud Index 的主要功能（浏览、预览、上传、下载等）。
+
+- Demo 地址：[https://r2.demo.cloud-index.rhen.cloud](https://r2.demo.cloud-index.rhen.cloud)（使用Cloudflare R2作为存储后端）
+- Demo 地址：[https://github.demo.cloud-index.rhen.cloud](https://github.demo.cloud-index.rhen.cloud)（使用Github Repository作为存储后端）
+
+### 项目特点
+
+#### 1. 多后端支持
+
+通过灵活的架构设计，支持多种云存储服务：
+
+- **Cloudflare R2** - 低成本的S3兼容对象存储
+- **Amazon S3** - 业界标准的对象存储服务
+- **GitHub Repository** - 将GitHub仓库作为存储后端
+- **GitHub Release** - 利用Release API存储文件（开发中）
+
+后端可以通过简单的配置进行切换，无需修改代码。
+
+#### 2. 完整的文件操作功能
+
+提供常见的文件管理功能：
+
+- 📁 目录浏览与导航
+- 📝 文件详情查看（名称、大小、修改时间等）
+- ⬆️ 文件上传
+- 🗑️ 文件删除
+- ✏️ 文件/文件夹重命名
+- 📂 创建新文件夹
+- 📋 复制文件/文件夹
+- 🔄 移动文件/文件夹
+
+#### 3. 智能媒体处理
+
+- 🖼️ 自动生成缩略图，支持缓存
+- 👁️ 图片预览
+- 📊 文件类型识别和对应图标
+- 🎨 美观的预览界面
+
+#### 4. 分享与访问
+
+- 🌐 生成公共访问URL（如果存储支持）
+- 🔗 预签名URL支持，具有过期时间控制
+- 📱 移动设备友好的响应式设计
+- 🌙 深色模式支持
+
+#### 5. 企业级特性
+
+- 🔐 环境变量配置管理
+- 📊 文件大小格式化显示
+- 🌍 国际化支持（中文/英文）
+- ⚡ 高性能缓存机制
+
+## 项目架构
+
+### 核心组件
+
+```
+Cloud-Index/
+├── app.py                    # Flask 应用主入口
+├── handlers/
+│   └── routes.py            # 路由处理
+├── storages/
+│   ├── base.py              # 存储基类
+│   ├── factory.py           # 存储工厂（策略模式）
+│   ├── r2.py                # Cloudflare R2 实现
+│   ├── s3.py                # Amazon S3 实现
+│   └── github.py            # GitHub 存储实现
+├── templates/               # HTML 模板
+│   ├── base.html            # 基础模板
+│   ├── index.html           # 主页面
+│   └── footer.html          # 页脚
+└── static/                  # 静态资源
+    ├── css/                 # 样式表
+    ├── js/                  # JavaScript 文件
+    └── thumbs/              # 缩略图缓存
+```
+
+### 架构模式
+
+1. **工厂模式** - `StorageFactory` 负责根据配置创建相应的存储实现
+2. **策略模式** - 不同的存储后端实现相同的 `BaseStorage` 接口
+3. **MVC模式** - 使用 Flask 框架实现标准的 MVC 架构
+
+## 技术栈
+
+| 组件 | 技术 | 说明 |
+|-----|------|------|
+| **后端框架** | Flask | 轻量级 Python Web 框架 |
+| **前端** | HTML5/CSS3/JS | 原生 Web 技术 |
+| **对象存储** | AWS S3 SDK | boto3 库 |
+| **文件处理** | Pillow | 图片处理库 |
+| **API调用** | requests | HTTP 库 |
+| **部署** | Docker/Vercel | 容器化和Serverless部署 |
+
+## 工作流程
+
+### 文件浏览流程
+
+```
+用户请求
+    ↓
+Flask 路由处理
+    ↓
+存储工厂获取对应后端
+    ↓
+执行存储操作（list/get/delete等）
+    ↓
+模板渲染
+    ↓
+返回给用户
+```
+
+### 文件上传流程
+
+```
+用户上传文件
+    ↓
+Flask 接收请求
+    ↓
+验证文件
+    ↓
+调用存储后端上传
+    ↓
+返回结果
+```
+
+### 缩略图生成流程
+
+```
+请求图片缩略图
+    ↓
+检查缓存
+    ↓
+缓存命中？ → 返回缓存
+    ↓ 否
+获取原始文件
+    ↓
+使用 Pillow 生成缩略图
+    ↓
+保存到本地缓存
+    ↓
+返回缩略图
+```
+
+## 存储后端选择指南
+
+### Cloudflare R2
+
+**最佳用途**: 低成本、小企业、边缘计算优先
+
+- 💰 价格最低（存储费用免费，仅收取请求费）
+- 🚀 全球 CDN 加速
+- 🔄 S3 API 兼容
+- 适合: 静态资源、备份、媒体库
+
+### Amazon S3
+
+**最佳用途**: 大企业、高可用性、完整生态
+
+- 📊 功能最完整
+- 🔒 安全性最高
+- 🌍 全球可用
+- 💼 企业级支持
+- 适合: 生产环境、大规模应用、合规要求高
+
+### GitHub Repository
+
+**最佳用途**: 轻量级、免费、版本控制
+
+- 🆓 完全免费（利用GitHub存储）
+- 📝 自动版本控制
+- 🔐 访问权限管理
+- 易于备份和迁移
+- 适合: 文档、配置文件、小文件、开源项目
+
+## 性能指标
+
+- **文件列表响应** < 100ms（本地缓存）
+- **缩略图生成** 平均 50-200ms（取决于图片大小）
+- **文件上传** 无限制（取决于网络）
+- **并发连接** 支持数百并发请求
+- **缓存有效期** 可配置（默认1小时）
+
+## 与其他解决方案对比
+
+| 特性 | Cloud Index | Nextcloud | MinIO | S3 Web UI |
+|-----|---------|----------|-------|-----------|
+| 多后端支持 | ✅ | ❌ | ❌ | ❌ |
+| 易部署 | ✅ | ❌ | ⚠️ | ❌ |
+| 低成本 | ✅ | ❌ | ⚠️ | ❌ |
+| 功能完整度 | ✅ | ✅✅ | ✅ | ⚠️ |
+| 学习曲线 | 低 | 高 | 中 | 低 |
+
+## 未来规划
+
+- [ ] GitHub Release 存储支持
+- [ ] 基于数据库的用户权限管理
+- [ ] 操作日志记录与审计
+- [ ] Office 文档预览支持
+- [ ] 视频预览支持
+- [ ] 文件夹打包下载
+- [ ] API 文档完善
+- [ ] WebDAV 支持
+- [ ] 搜索功能增强
+- [ ] 分享链接和权限管理
+
+## 许可证
+
+GPLv3 License - 详见项目根目录的 LICENSE 文件
+
+## 相关链接
+
+- 📖 [GitHub 仓库](https://github.com/RhenCloud/Cloud-Index>)
+- 🐛 [问题报告](https://github.com/RhenCloud/Cloud-Index/issues>)
+- 💬 [讨论区](https://github.com/RhenCloud/Cloud-Index/discussions>)