mirror of
https://github.com/RhenCloud/Cloud-Index.git
synced 2025-12-06 15:26:10 +08:00
450 lines
12 KiB
Markdown
450 lines
12 KiB
Markdown
# Cloud-Index
|
||
|
||
一个支持多种云存储后端的文件管理、索引和浏览服务。
|
||
|
||
更多详细信息请访问 [项目文档](https://docs.cloud-index.rhen.cloud)
|
||
|
||
我在这个项目上至少花费了：
|
||
|
||
[](https://wakapi.rhen.cloud)
|
||
|
||
## 特性
|
||
|
||
- 📁 浏览和预览云存储中的文件
|
||
- 🖼️ 图片缩略图生成
|
||
- 🌐 公共访问 URL 支持
|
||
- 🔄 多存储后端支持（可扩展）
|
||
- ⬆️ 文件上传功能
|
||
- 🗑️ 文件删除功能
|
||
- ✏️ 文件/文件夹重命名
|
||
- 📂 创建文件夹
|
||
- 📋 文件/文件夹复制
|
||
- 🔄 文件/文件夹移动
|
||
- 📱 响应式界面，多种设备尺寸支持
|
||
- 🌙 深色模式支持
|
||
|
||
## 在线演示
|
||
|
||
你可以在在线演示中体验 Cloud Index 的主要功能（浏览、预览、上传、下载等）。
|
||
|
||
- Demo 地址：[https://demo.cloud-index.rhen.cloud](https://demo.cloud-index.rhen.cloud)
|
||
- 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作为存储后端）
|
||
|
||
## TODO
|
||
|
||
- [x] Github Repo 储存支持
|
||
- [ ] Github Release 储存支持
|
||
- [ ] Microsoft Onedrive 储存支持
|
||
- [ ] 基于数据库的用户/权限管理
|
||
- [ ] 操作日志记录
|
||
- [ ] Office Documents 预览支持
|
||
- [ ] 视频预览支持
|
||
- [ ] 文件夹打包下载支持
|
||
|
||
## 支持的存储后端
|
||
|
||
- **Cloudflare R2** - Cloudflare 的对象存储服务（S3 兼容）
|
||
- **Amazon S3** - Amazon S3 对象存储服务
|
||
- **GitHub Repository** - 基于 GitHub Repository 的存储服务
|
||
<!-- - **Github Release** - 基于 GitHub Release 的存储服务 -->
|
||
|
||
## 快速开始
|
||
|
||
### 1. 克隆项目
|
||
|
||
```bash
|
||
git clone https://github.com/RhenCloud/Cloud-Index.git
|
||
cd Cloud-Index
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 3. 配置环境变量
|
||
|
||
复制 `.env.example` 到 `.env` 并填写配置：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
### 4. 运行应用
|
||
|
||
```bash
|
||
python app.py
|
||
```
|
||
|
||
## 部署
|
||
|
||
### Vercel 部署
|
||
|
||
项目包含 `vercel.json` 配置文件，可直接部署到 Vercel：
|
||
|
||
1. 在 Vercel 中导入项目
|
||
2. 在 Vercel 项目设置中配置环境变量
|
||
3. 部署
|
||
|
||
## 配置说明
|
||
|
||
### Cloudflare R2 配置
|
||
|
||
```env
|
||
STORAGE_TYPE=r2
|
||
|
||
# R2 账户 ID
|
||
R2_ACCOUNT_ID=your-account-id
|
||
|
||
# R2 访问凭证
|
||
R2_ACCESS_KEY_ID=your_access_key_id
|
||
R2_SECRET_ACCESS_KEY=your_secret_access_key
|
||
|
||
# R2 存储桶配置
|
||
R2_BUCKET_NAME=your_bucket_name
|
||
|
||
# 可选：公共访问域名
|
||
R2_PUBLIC_DOMAIN=https://pub-your-bucket.r2.dev
|
||
```
|
||
|
||
### GitHub Repository 配置
|
||
|
||
```env
|
||
STORAGE_TYPE=github
|
||
|
||
# GitHub 仓库 (格式: owner/repo)
|
||
GITHUB_REPO=your-username/your-repo
|
||
|
||
# GitHub 个人访问令牌（需要 repo 权限）
|
||
# 获取方式：https://github.com/settings/tokens
|
||
GITHUB_TOKEN=ghp_your_token_here
|
||
|
||
# GitHub 分支名称（可选，默认: main）
|
||
GITHUB_BRANCH=main
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```bash
|
||
cloud-index/
|
||
├── app.py # Flask 应用主入口
|
||
├── config.py # 统一配置管理
|
||
├── utils.py # 工具函数模块
|
||
├── handlers/
|
||
│ └── routes.py # 路由处理器
|
||
├── storages/ # 存储后端实现
|
||
│ ├── __init__.py
|
||
│ ├── base.py # 基础存储类（抽象类）
|
||
│ ├── factory.py # 存储工厂类
|
||
│ ├── r2.py # Cloudflare R2 实现
|
||
│ └── github.py # GitHub Repository 实现
|
||
├── templates/ # HTML 模板
|
||
│ ├── base.html
|
||
│ ├── index.html
|
||
│ └── footer.html
|
||
├── static/ # 静态资源
|
||
│ ├── css/
|
||
│ │ └── main.css
|
||
│ └── js/
|
||
│ └── main.js
|
||
├── .env.example # 环境变量示例
|
||
├── pyproject.toml # 项目配置和依赖
|
||
└── requirements.txt # Python 依赖
|
||
```
|
||
|
||
## API 路由
|
||
|
||
- `GET /` - 浏览根目录
|
||
- `GET /<path:prefix_path>` - 浏览指定目录
|
||
- `GET /file/<path:file_path>` - 获取文件内容
|
||
- `GET /thumb/<path:file_path>` - 获取图片缩略图
|
||
- `POST /upload` - 上传文件
|
||
- `DELETE /delete/<path:file_path>` - 删除文件
|
||
- `POST /rename/<path:old_key>` - 重命名文件
|
||
- `DELETE /delete_folder/<path:prefix>` - 删除文件夹
|
||
- `POST /rename_folder/<path:old_prefix>` - 重命名文件夹
|
||
- `POST /copy` - 复制文件或文件夹
|
||
- `POST /move` - 移动文件或文件夹
|
||
- `POST /create_folder` - 创建文件夹
|
||
|
||
详细 API 文档：[API 文档](docs/api.md)
|
||
|
||
### 本地开发
|
||
|
||
```bash
|
||
# 1. 克隆项目
|
||
git clone https://github.com/RhenCloud/Cloud-Index.git
|
||
cd Cloud-Index
|
||
|
||
# 2. 创建虚拟环境
|
||
python -m venv venv
|
||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||
|
||
# 3. 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 4. 配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env 文件，填入你的存储配置
|
||
|
||
# 5. 运行应用
|
||
python app.py
|
||
```
|
||
|
||
应用将在 `http://localhost:5000` 启动。
|
||
|
||
## 技术栈
|
||
|
||
- **Flask** - Web 框架
|
||
- **Boto3** - AWS SDK（用于 S3 兼容存储）
|
||
- **Pillow** - 图片处理
|
||
- **Python-dotenv** - 环境变量管理
|
||
|
||
## 常见问题
|
||
|
||
### Q: 如何限制上传文件大小？
|
||
|
||
A: 在 `handlers/routes.py` 中的 `upload()` 函数中添加文件大小检查：
|
||
|
||
```python
|
||
@main_route.route("/upload", methods=["POST"])
|
||
def upload():
|
||
file = request.files["file"]
|
||
|
||
# 限制文件大小为 100MB
|
||
MAX_FILE_SIZE = 100 * 1024 * 1024
|
||
if len(file.read()) > MAX_FILE_SIZE:
|
||
return jsonify({"success": False, "error": "File too large"}), 413
|
||
|
||
file.seek(0) # 重置文件指针
|
||
# ... 继续上传逻辑
|
||
```
|
||
|
||
### Q: 如何添加访问认证？
|
||
|
||
A: 参考 [API 文档](docs/api.md) 的"安全建议"部分，可以添加基于 Token 的简单认证。
|
||
|
||
### Q: 支持哪些图片格式的缩略图生成？
|
||
|
||
A: 支持 `jpg`, `jpeg`, `png`, `gif`, `bmp`, `webp`, `svg`, `ico` 等常见格式。
|
||
|
||
### Q: 如何在深色模式和浅色模式间切换？
|
||
|
||
A: 点击页面顶部的月亮/太阳图标即可切换。设置将保存在本地存储中。
|
||
|
||
### Q: 支持哪些存储后端？
|
||
|
||
A: 当前支持：
|
||
|
||
- Cloudflare R2（推荐）
|
||
- Amazon S3
|
||
- GitHub Repository
|
||
|
||
### Q: 如何添加新的存储后端？
|
||
|
||
A: 参考项目结构中的"添加新的存储后端"部分，继承 `BaseStorage` 并实现所有抽象方法即可。
|
||
|
||
## 贡献指南
|
||
|
||
欢迎为 Cloud-Index 做出贡献！无论是报告 Bug、提出新功能建议，还是直接提交代码，我们都非常感谢。
|
||
|
||
### 如何贡献
|
||
|
||
#### 1. 报告问题
|
||
|
||
如果你发现了 Bug 或有功能建议：
|
||
|
||
1. 在 [Issues](https://github.com/RhenCloud/Cloud-Index/issues) 页面搜索是否已有相关问题
|
||
2. 如果没有，创建新的 Issue，并提供：
|
||
- **Bug 报告**：详细的复现步骤、预期行为、实际行为、环境信息（操作系统、Python 版本等）
|
||
- **功能建议**：清晰的需求描述、使用场景、预期效果
|
||
|
||
#### 2. 提交代码
|
||
|
||
**基本流程**：
|
||
|
||
1. **Fork 项目**
|
||
点击 GitHub 页面右上角的 "Fork" 按钮
|
||
|
||
2. **克隆到本地**
|
||
|
||
```bash
|
||
git clone https://github.com/your-username/Cloud-Index.git
|
||
cd Cloud-Index
|
||
```
|
||
|
||
3. **进行开发**
|
||
- 遵循现有的代码风格
|
||
- 添加必要的注释
|
||
- 确保代码能正常运行
|
||
|
||
4. **提交更改**
|
||
|
||
```bash
|
||
git add .
|
||
git commit -m "feat: 添加某某功能"
|
||
# 或 "fix: 修复某某问题"
|
||
```
|
||
|
||
5. **推送到 GitHub**
|
||
|
||
```bash
|
||
git push origin main
|
||
```
|
||
|
||
6. **创建 Pull Request**
|
||
- 在 GitHub 上打开你的 Fork
|
||
- 点击 "New Pull Request"
|
||
- 填写 PR 描述，说明你的更改内容和原因
|
||
|
||
**Commit 信息规范**（建议）：
|
||
|
||
- `feat:` 新功能
|
||
- `fix:` 修复 Bug
|
||
- `docs:` 文档更新
|
||
- `style:` 代码格式调整（不影响功能）
|
||
- `refactor:` 重构代码
|
||
- `test:` 添加或修改测试
|
||
- `chore:` 构建工具或辅助工具的变动
|
||
|
||
### 开发指南
|
||
|
||
#### 项目架构
|
||
|
||
项目采用 **策略模式** 和 **工厂模式**，使得添加新的存储后端非常简单：
|
||
|
||
```bash
|
||
存储抽象层 (BaseStorage)
|
||
↓
|
||
具体实现 (R2Storage, GitHubStorage, ...)
|
||
↓
|
||
工厂创建 (StorageFactory)
|
||
```
|
||
|
||
**核心组件**：
|
||
|
||
- **BaseStorage** (`storages/base.py`) - 定义存储后端的统一接口（抽象基类）
|
||
- **具体存储实现** (`storages/r2.py`, `storages/github.py`) - 实现特定存储的业务逻辑
|
||
- **StorageFactory** (`storages/factory.py`) - 根据环境变量创建对应的存储实例
|
||
|
||
#### 添加新的存储后端
|
||
|
||
如果你想支持新的存储服务（如 Google Cloud Storage、Azure Blob 等），按以下步骤操作：
|
||
|
||
##### **步骤 1：创建存储实现文件**
|
||
|
||
在 `storages/` 目录下创建新文件，例如 `gcs.py`：
|
||
|
||
```python
|
||
from storages.base import BaseStorage
|
||
|
||
class GCSStorage(BaseStorage):
|
||
"""Google Cloud Storage 实现"""
|
||
|
||
def __init__(self):
|
||
# 初始化 GCS 客户端
|
||
pass
|
||
|
||
# 实现所有抽象方法
|
||
def list_objects(self, prefix=""):
|
||
pass
|
||
|
||
def get_object(self, key):
|
||
pass
|
||
|
||
# ... 其他方法
|
||
```
|
||
|
||
##### **步骤 2：实现所有抽象方法**
|
||
|
||
参考 `BaseStorage` 中定义的方法签名，实现以下方法：
|
||
|
||
- `list_objects()` - 列出文件和目录
|
||
- `get_object()` - 获取文件内容
|
||
- `get_object_info()` - 获取文件元数据
|
||
- `upload_file()` - 上传文件
|
||
- `delete_file()` - 删除文件
|
||
- `rename_file()` - 重命名文件
|
||
- `generate_presigned_url()` - 生成预签名 URL
|
||
- `get_public_url()` - 获取公共访问 URL
|
||
- 其他文件夹操作方法...
|
||
|
||
##### **步骤 3：在工厂中注册**
|
||
|
||
编辑 `storages/factory.py`，添加新的存储类型：
|
||
|
||
```python
|
||
from storages.gcs import GCSStorage
|
||
|
||
class StorageFactory:
|
||
@staticmethod
|
||
def get_storage():
|
||
storage_type = os.getenv("STORAGE_TYPE", "r2")
|
||
|
||
if storage_type == "gcs":
|
||
return GCSStorage()
|
||
# ... 其他类型
|
||
```
|
||
|
||
##### **步骤 4：添加配置示例**
|
||
|
||
在 `.env.example` 中添加新存储的配置说明：
|
||
|
||
```env
|
||
# Google Cloud Storage 配置
|
||
STORAGE_TYPE=gcs
|
||
GCS_PROJECT_ID=your-project-id
|
||
GCS_BUCKET_NAME=your-bucket
|
||
GCS_CREDENTIALS_PATH=/path/to/credentials.json
|
||
```
|
||
|
||
##### **步骤 5：更新文档**
|
||
|
||
- 在 README.md 的"支持的存储后端"部分添加新存储
|
||
- 在"配置说明"部分添加详细的配置步骤
|
||
|
||
#### 本地测试
|
||
|
||
开发完成后，请在本地测试：
|
||
|
||
```bash
|
||
# 1. 配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env，设置你的存储配置
|
||
|
||
# 2. 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 3. 运行应用
|
||
python app.py
|
||
|
||
# 4. 测试功能
|
||
# 访问 http://localhost:5000
|
||
# 测试文件浏览、上传、下载、删除等功能
|
||
```
|
||
|
||
### 代码规范
|
||
|
||
- 使用 **4 个空格** 缩进（Python PEP 8 标准）
|
||
- 函数和方法添加 **docstring** 说明
|
||
- 变量和函数使用 **有意义的命名**
|
||
- 复杂逻辑添加 **注释说明**
|
||
- 保持代码简洁，遵循 **单一职责原则**
|
||
|
||
### 需要帮助？
|
||
|
||
如果在贡献过程中遇到问题：
|
||
|
||
- 查看 [项目文档](https://docs.cloud-index.rhen.cloud)
|
||
- 在 [Discussions](https://github.com/RhenCloud/Cloud-Index/discussions) 提问
|
||
- 通过 Issue 联系维护者
|
||
|
||
感谢你对 Cloud-Index 的贡献！🎉
|
||
|
||
## 许可证
|
||
|
||
MIT License
|