ComfyUI CustomNode - 对象存储节点

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

✨ 特性

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

🚀 快速开始

安装

1. 将项目克隆到ComfyUI的自定义节点目录：

cd ComfyUI/custom_nodes/
git clone https://github.com/your-repo/ComfyUI-CustomNode.git

2. 安装依赖：

cd ComfyUI-CustomNode
pip install -r requirements.txt

配置

创建 config.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"

或者使用环境变量：

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

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

2. 从COS下载文件

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

3. 上传图像并获取URL

# 使用S3UploadIMAGEURL节点  
# 输入：
# - image: [图像张量]
# - subfolder: "generated"
# 输出：图像的CDN访问URL

🏗️ 架构设计

设计模式

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

抽象工厂模式

# 存储提供者工厂
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)

策略模式

# 存储管理器支持动态切换存储策略
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. 实现存储提供者：

class NewStorageProvider(StorageProvider):
    def upload_file(self, local_path, remote_key, **kwargs):
        # 实现上传逻辑
        pass
    # ... 实现其他抽象方法

2. 实现存储工厂：

class NewStorageFactory(StorageFactory):
    def create_provider(self, config):
        return NewStorageProvider(config)

3. 注册到管理器：

storage_manager.register_factory("new_storage", NewStorageFactory())

🧪 测试

运行测试

# 运行所有测试
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  # 集成测试

测试标记

# 只运行单元测试
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 文件了解详情

🙏 致谢

• ComfyUI - 强大的Stable Diffusion GUI
• boto3 - AWS SDK for Python
• qcloud-cos-python-sdk - 腾讯云COS SDK

📞 支持

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

1. 查看 FAQ
2. 搜索现有的 Issues
3. 创建新的 Issue

🔄 版本历史

v2.0.0 (当前版本)

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

v1.0.0 (历史版本)

• 基础的S3和COS上传下载功能
• 简单的错误处理

---

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