From b938c787979b3a8ef7cf4832f9c9544847fe8357 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Sun, 9 Nov 2025 13:42:26 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E8=B4=A1=E7=8C=AE?=
 =?UTF-8?q?=E6=8C=87=E5=8D=97=EF=BC=8C=E6=B7=BB=E5=8A=A0=E6=8A=A5=E5=91=8A?=
 =?UTF-8?q?=E9=97=AE=E9=A2=98=E5=92=8C=E6=8F=90=E4=BA=A4=E4=BB=A3=E7=A0=81?=
 =?UTF-8?q?=E7=9A=84=E8=AF=A6=E7=BB=86=E6=AD=A5=E9=AA=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 212 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 197 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index e5d00cc..972b32a 100644
--- a/README.md
+++ b/README.md
@@ -247,25 +247,207 @@ A: 参考项目结构中的"添加新的存储后端"部分，继承 `BaseStorag
 
 ## 贡献指南
 
-项目采用策略模式和工厂模式，使得添加新的存储后端变得简单：
+欢迎为 Cloud-Index 做出贡献！无论是报告 Bug、提出新功能建议，还是直接提交代码，我们都非常感谢。
 
-1. **BaseStorage** - 定义存储后端的统一接口
-2. **具体实现** (R2Storage, GithubStorage) - 实现具体的存储逻辑
-3. **StorageFactory** - 根据配置创建对应的存储实例
+### 如何贡献
 
-### 添加新的存储后端
+#### 1. 报告问题
 
-1. 在 `storages/` 目录下创建新的存储实现文件
-2. 继承 `BaseStorage` 并实现所有抽象方法
-3. 在 `StorageFactory` 中添加对应的创建逻辑
-4. 更新 `.env.example` 添加新的配置项
-欢迎提交 Issue 和 Pull Request！
+如果你发现了 Bug 或有功能建议：
 
-1. Fork 项目
-2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
-3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
-4. 推送到分支 (`git push origin feature/AmazingFeature`)
-5. 开启 Pull Request
+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. **创建功能分支**  
+
+   ```bash
+   git checkout -b feature/your-feature-name
+   # 或修复 Bug: git checkout -b fix/bug-description
+   ```
+
+4. **进行开发**  
+   - 遵循现有的代码风格
+   - 添加必要的注释
+   - 确保代码能正常运行
+
+5. **提交更改**  
+
+   ```bash
+   git add .
+   git commit -m "feat: 添加某某功能"
+   # 或 "fix: 修复某某问题"
+   ```
+
+6. **推送到 GitHub**  
+
+   ```bash
+   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:` 构建工具或辅助工具的变动
+
+### 开发指南
+
+#### 项目架构
+
+项目采用 **策略模式** 和 **工厂模式**，使得添加新的存储后端非常简单：
+
+```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 的贡献！🎉
 
 ## 许可证