Cloud-Index

一个支持多种云存储后端的文件管理、索引和浏览服务。

更多详细信息请访问 项目文档

我在这个项目上至少花费了：

特性

• 📁 浏览和预览云存储中的文件
• 🖼️ 图片缩略图生成
• 🌐 公共访问 URL 支持
• 🔄 多存储后端支持（可扩展）
• ⬆️ 文件上传功能
• 🗑️ 文件删除功能
• ✏️ 文件/文件夹重命名
• 📂 创建文件夹
• 📋 文件/文件夹复制
• 🔄 文件/文件夹移动
• 📱 响应式界面，多种设备尺寸支持
• 🌙 深色模式支持

在线演示

你可以在在线演示中体验 Cloud Index 的主要功能（浏览、预览、上传、下载等）。

• Demo 地址：https://r2.demo.cloud-index.rhen.cloud（使用Cloudflare R2作为存储后端）
• Demo 地址：https://github.demo.cloud-index.rhen.cloud（使用Github Repository作为存储后端）

TODO

• Github Repo 储存支持
• Github Release 储存支持
• 基于数据库的用户/权限管理
• 操作日志记录
• Office Documents 预览支持
• 视频预览支持
• 文件夹打包下载支持

支持的存储后端

• Cloudflare R2 - Cloudflare 的对象存储服务（S3 兼容）
• Amazon S3 - Amazon S3 对象存储服务
• GitHub Repository - 基于 GitHub Repository 的存储服务

快速开始

1. 克隆项目

git clone https://github.com/RhenCloud/Cloud-Index.git
cd Cloud-Index

2. 安装依赖

pip install -r requirements.txt

3. 配置环境变量

复制 .env.example 到 .env 并填写配置：

cp .env.example .env

4. 运行应用

python app.py

部署

Vercel 部署

项目包含 vercel.json 配置文件，可直接部署到 Vercel：

1. 在 Vercel 中导入项目
2. 在 Vercel 项目设置中配置环境变量
3. 部署

配置说明

Cloudflare R2 配置

STORAGE_TYPE=r2

# R2 访问凭证
ACCESS_KEY_ID=your_access_key_id
SECRET_ACCESS_KEY=your_secret_access_key

# R2 存储桶配置
R2_BUCKET_NAME=your_bucket_name
R2_ENDPOINT_URL=https://your-account-id.r2.cloudflarestorage.com
R2_REGION=auto

# 可选：公共访问 URL
R2_PUBLIC_URL=https://pub-your-bucket.r2.dev

# 可选：预签名 URL 过期时间（秒）
R2_PRESIGN_EXPIRES=3600

GitHub Repository 配置

STORAGE_TYPE=github

# GitHub 仓库所有者（用户名或组织）
GITHUB_REPO_OWNER=your-username

# GitHub 仓库名称
GITHUB_REPO_NAME=your-repo

# GitHub 个人访问令牌（需要 repo 权限）
# 获取方式：https://github.com/settings/tokens
GITHUB_ACCESS_TOKEN=ghp_your_token_here

# GitHub 分支名称（可选，默认: main）
GITHUB_BRANCH=main

# GitHub Raw 文件反向代理 URL（可选，用于加速访问）
# 常用反向代理：
# - https://raw.fastgit.org （推荐，速度快）
# - https://ghproxy.com
# - https://raw.kgithub.com
# 留空则使用官方 raw.githubusercontent.com（国内可能较慢）
GITHUB_RAW_PROXY_URL=https://raw.fastgit.org

项目结构

cloud-index/
├── app.py                 # Flask 应用主入口
├── handlers/
│   └── routes.py         # 路由处理器
├── storages/             # 存储后端实现
│   ├── __init__.py
│   ├── base.py          # 基础存储类（抽象类）
│   ├── factory.py       # 存储工厂类
│   ├── r2.py            # Cloudflare R2 实现
│   └── github.py        # GitHub Repository 实现
├── templates/           # HTML 模板
│   ├── index.html
│   └── footer.html
├── static/             # 静态资源
│   └── thumbs/
├── .env.example        # 环境变量示例
└── 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 文档

本地开发

# 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() 函数中添加文件大小检查：

@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 文档 的"安全建议"部分，可以添加基于 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 页面搜索是否已有相关问题
2. 如果没有，创建新的 Issue，并提供：
   • Bug 报告：详细的复现步骤、预期行为、实际行为、环境信息（操作系统、Python 版本等）
   • 功能建议：清晰的需求描述、使用场景、预期效果

2. 提交代码

基本流程：

1. Fork 项目
   点击 GitHub 页面右上角的 "Fork" 按钮

2. 克隆到本地

   git clone https://github.com/your-username/Cloud-Index.git
   cd Cloud-Index
   

3. 创建功能分支

   git checkout -b feature/your-feature-name
   # 或修复 Bug: git checkout -b fix/bug-description
   

4. 进行开发

   • 遵循现有的代码风格
   • 添加必要的注释
   • 确保代码能正常运行

5. 提交更改

   git add .
   git commit -m "feat: 添加某某功能"
   # 或 "fix: 修复某某问题"
   

6. 推送到 GitHub

   git push origin feature/your-feature-name
   

7. 创建 Pull Request

   • 在 GitHub 上打开你的 Fork
   • 点击 "New Pull Request"
   • 填写 PR 描述，说明你的更改内容和原因

Commit 信息规范（建议）：

• feat: 新功能
• fix: 修复 Bug
• docs: 文档更新
• style: 代码格式调整（不影响功能）
• refactor: 重构代码
• test: 添加或修改测试
• chore: 构建工具或辅助工具的变动

开发指南

项目架构

项目采用 策略模式 和 工厂模式，使得添加新的存储后端非常简单：

存储抽象层 (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：

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，添加新的存储类型：

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 中添加新存储的配置说明：

# 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 的"支持的存储后端"部分添加新存储
• 在"配置说明"部分添加详细的配置步骤

本地测试

开发完成后，请在本地测试：

# 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 说明
• 变量和函数使用 有意义的命名
• 复杂逻辑添加 注释说明
• 保持代码简洁，遵循 单一职责原则

需要帮助？

如果在贡献过程中遇到问题：

• 查看 项目文档
• 在 Discussions 提问
• 通过 Issue 联系维护者

感谢你对 Cloud-Index 的贡献！🎉

许可证

MIT License