mirror of
https://github.com/RhenCloud/Cloud-Index.git
synced 2025-12-06 15:17:40 +08:00
docs: 更新贡献指南，添加报告问题和提交代码的详细步骤
This commit is contained in:
212
README.md
212
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 的贡献！🎉
|
||||
|
||||
## 许可证
|
||||
|
||||
|
||||
Reference in New Issue
Block a user