350 lines
8.2 KiB
Markdown
350 lines
8.2 KiB
Markdown
# ComfyUI CustomNode - 对象存储节点
|
||
|
||
[](https://www.python.org/downloads/)
|
||
[](https://opensource.org/licenses/MIT)
|
||
[](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上传下载功能
|
||
- 简单的错误处理
|
||
|
||
---
|
||
|
||
**⭐ 如果这个项目对你有帮助，请给我们一个星标！** |