# ComfyUI CustomNode - 对象存储节点

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code Quality](https://img.shields.io/badge/code%20quality-A-green.svg)](https://github.com/psf/black)

ComfyUI自定义节点集合，提供强大的云存储功能，支持AWS S3和腾讯云COS等多种对象存储服务。

## ✨ 特性

- 🏗️ **架构优雅**：采用抽象工厂模式和策略模式，遵循开闭原则
- 🔌 **易于扩展**：支持多种云存储服务，可轻松添加新的存储提供者
- 🛡️ **错误处理**：完善的错误处理机制和重试策略
- 📊 **类型安全**：完整的类型注解和参数验证
- 🧪 **测试覆盖**：全面的单元测试和集成测试
- 📝 **文档完善**：详细的API文档和使用指南

## 🚀 快速开始

### 安装

1. 将项目克隆到ComfyUI的自定义节点目录：
```bash
cd ComfyUI/custom_nodes/
git clone https://github.com/your-repo/ComfyUI-CustomNode.git
```

2. 安装依赖：
```bash
cd ComfyUI-CustomNode
pip install -r requirements.txt
```

### 配置

创建 `config.yaml` 文件并配置你的存储服务：

```yaml
# AWS S3 配置
aws_key_id: "your_aws_access_key"
aws_access_key: "your_aws_secret_key"

# 腾讯云 COS 配置  
cos_secret_id: "your_cos_secret_id"
cos_secret_key: "your_cos_secret_key"
cos_region: "ap-beijing"
cos_sucai_bucket_name: "your-cos-bucket"
```

或者使用环境变量：

```bash
export aws_key_id="your_aws_access_key"
export aws_access_key="your_aws_secret_key"
export cos_secret_id="your_cos_secret_id" 
export cos_secret_key="your_cos_secret_key"
export cos_region="ap-beijing"
```

## 📖 使用指南

### 可用节点

#### COS 节点
- **COSDownload**: 从腾讯云COS下载文件
- **COSUpload**: 上传文件到腾讯云COS

#### S3 节点  
- **S3Download**: 从AWS S3下载文件
- **S3Upload**: 上传文件到AWS S3
- **S3UploadURL**: 上传文件并返回访问URL
- **S3UploadIMAGEURL**: 上传图像张量并返回URL

### 基本用法示例

#### 1. 上传文件到S3
```python
# 在ComfyUI工作流中使用S3Upload节点
# 输入：
# - s3_bucket: "my-bucket"
# - path: "/path/to/file.jpg" 
# - subfolder: "images"
# 输出：文件在S3中的键名
```

#### 2. 从COS下载文件
```python
# 使用COSDownload节点
# 输入：
# - cos_bucket: "my-cos-bucket"
# - cos_key: "images/photo.jpg"
# 输出：本地文件路径
```

#### 3. 上传图像并获取URL
```python
# 使用S3UploadIMAGEURL节点  
# 输入：
# - image: [图像张量]
# - subfolder: "generated"
# 输出：图像的CDN访问URL
```

## 🏗️ 架构设计

### 设计模式

本项目采用了多种设计模式来确保代码的可维护性和可扩展性：

#### 抽象工厂模式
```python
# 存储提供者工厂
class StorageFactory(ABC):
    @abstractmethod
    def create_provider(self, config: Dict[str, Any]) -> StorageProvider:
        pass

# 具体工厂实现
class S3StorageFactory(StorageFactory):
    def create_provider(self, config):
        return S3StorageProvider(config)
```

#### 策略模式  
```python
# 存储管理器支持动态切换存储策略
storage_manager.register_factory("s3", S3StorageFactory())
storage_manager.register_factory("cos", COSStorageFactory())

# 运行时选择存储提供者
provider = storage_manager.create_provider("s3", config)
```

### 核心组件

#### 1. 抽象接口层 (`storage_interface.py`)
- `StorageProvider`: 存储提供者抽象基类
- `StorageFactory`: 存储工厂抽象基类  
- `StorageManager`: 存储管理器
- `UploadResult`/`DownloadResult`: 结果封装类

#### 2. 具体实现层
- `S3StorageProvider`: AWS S3实现
- `COSStorageProvider`: 腾讯云COS实现
- 各自的工厂类

#### 3. 节点层 (`object_storage_nodes.py`)
- ComfyUI节点实现
- 统一的错误处理
- 类型安全的接口

#### 4. 配置管理 (`config_utils.py`)  
- 统一配置加载
- 环境变量支持
- 配置验证

### 扩展新的存储服务

添加新的存储服务只需要三个步骤：

1. **实现存储提供者**：
```python
class NewStorageProvider(StorageProvider):
    def upload_file(self, local_path, remote_key, **kwargs):
        # 实现上传逻辑
        pass
    # ... 实现其他抽象方法
```

2. **实现存储工厂**：
```python
class NewStorageFactory(StorageFactory):
    def create_provider(self, config):
        return NewStorageProvider(config)
```

3. **注册到管理器**：
```python
storage_manager.register_factory("new_storage", NewStorageFactory())
```

## 🧪 测试

### 运行测试

```bash
# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/test_s3_provider.py

# 运行详细输出
pytest -v

# 运行代码覆盖率测试
pytest --cov=utils --cov-report=html
```

### 测试结构

```
tests/
├── __init__.py          # 测试模块初始化
├── conftest.py          # pytest配置和fixtures
├── test_storage_interface.py  # 接口层测试
├── test_s3_provider.py  # S3提供者测试
├── test_cos_provider.py # COS提供者测试  
├── test_nodes.py        # 节点测试
└── test_integration.py  # 集成测试
```

### 测试标记

```bash
# 只运行单元测试
pytest -m unit

# 只运行集成测试  
pytest -m integration

# 排除慢速测试
pytest -m "not slow"
```

## 📊 性能优化

### 1. 懒加载
- 存储客户端采用懒加载模式
- 减少初始化开销

### 2. 连接复用
- 复用HTTP连接
- 减少网络开销

### 3. 重试机制
- 指数退避重试
- 提高成功率

### 4. 并发处理
- 支持异步操作
- 提高并发性能

## 🔧 配置选项

### 全局配置

| 参数 | 类型 | 必需 | 描述 | 默认值 |
|------|------|------|------|-------|
| `aws_key_id` | string | 是 | AWS访问密钥ID | - |
| `aws_access_key` | string | 是 | AWS秘密访问密钥 | - |  
| `cos_secret_id` | string | 是 | COS秘钥ID | - |
| `cos_secret_key` | string | 是 | COS秘钥 | - |
| `cos_region` | string | 是 | COS区域 | - |

### 节点配置

每个节点支持的参数请参考节点的 `INPUT_TYPES()` 方法定义。

## 🚨 错误处理

### 常见错误及解决方案

#### 1. 配置错误
```
ValueError: S3配置缺失必要参数: ['access_key_id']
```
**解决方案**: 检查 `config.yaml` 或环境变量中的AWS配置

#### 2. 网络错误
```  
Exception: S3上传失败: 网络连接超时
```
**解决方案**: 检查网络连接，存储服务会自动重试

#### 3. 权限错误
```
Exception: COS下载失败: 权限不足
```
**解决方案**: 检查存储桶权限和访问密钥

## 📈 监控和日志

### 日志级别

使用 `loguru` 进行日志记录：

- `INFO`: 正常操作信息
- `WARNING`: 警告信息（重试等）
- `ERROR`: 错误信息
- `DEBUG`: 调试信息

### 监控指标

建议监控以下指标：

- 上传/下载成功率
- 响应时间
- 错误率
- 重试次数

## 🤝 贡献指南

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)  
3. 提交改动 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 开发规范

- 遵循 PEP 8 代码规范
- 添加类型注解
- 编写测试用例
- 更新文档

## 📄 License

本项目基于 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 🙏 致谢

- [ComfyUI](https://github.com/comfyanonymous/ComfyUI) - 强大的Stable Diffusion GUI
- [boto3](https://github.com/boto/boto3) - AWS SDK for Python
- [qcloud-cos-python-sdk](https://github.com/tencentyun/cos-python-sdk-v5) - 腾讯云COS SDK

## 📞 支持

如果遇到问题或有功能建议，请：

1. 查看 [FAQ](#常见问题)
2. 搜索现有的 [Issues](https://github.com/your-repo/issues)  
3. 创建新的 Issue

## 🔄 版本历史

### v2.0.0 (当前版本)
- 🏗️ 完全重构架构，采用抽象工厂模式
- ✨ 支持多种存储服务
- 🧪 添加全面的测试覆盖
- 📝 完善文档和注释
- 🛡️ 增强错误处理和重试机制

### v1.0.0 (历史版本)  
- 基础的S3和COS上传下载功能
- 简单的错误处理

---

**⭐ 如果这个项目对你有帮助，请给我们一个星标！**