docs: add user collaboration and technical stack rules
本项目是一个基于 CNB (Cloud Native Build) 平台的 ComfyUI 基础设施项目，提供高性能的 AI 图像生成环境，支持 CUDA 加速和完整的依赖管理。
最新更新: Python 3.12 + PyTorch 2.9.1 升级完成 (2025-12-27)
🔧 启动优化: 修复 ComfyUI Manager 目录冲突，完善符号链接策略 (2025-12-28)
┌─────────────────────────────────────────────────────────────┐
│ CNB 云原生平台 │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Infra 基础层 │ → │ App 应用层 │ → ComfyUI服务 │
│ │ CUDA+Python环境 │ │ ComfyUI+依赖 │ (8188端口) │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
↓ ↓
┌─────────────┐ ┌─────────────┐
│ BuildKit │ │ 数据持久化 │
│ 多级缓存 │ │ 符号链接策略 │
└─────────────┘ └─────────────┘
- CNB 平台账号
- Docker 支持
- GPU 资源 (推荐)
# 构建 Infra 基础镜像 (CUDA + Python + PyTorch)
./test_build_infra.sh
# 构建 App 应用镜像 (ComfyUI + 依赖)
./scripts/build_app.sh latest
# 锁定依赖版本 (更新 uv.lock)
./compile_app_deps.sh
# CNB 平台自动执行：
# 1. 构建镜像 → 2. 启动容器 → 3. 设置存储 → 4. 启动ComfyUI
# 访问: http://your-cnb-domain:8188
workspace/
├── .cnb.yml # CNB 构建配置
├── .env.example # 环境变量示例
├── app/ # 应用层
│ ├── Dockerfile # 多阶段构建配置
│ ├── pyproject.toml # UV项目配置
│ ├── uv.lock # 依赖锁定文件
│ └── main.py # 应用入口
├── infra/ # 基础设施层
│ ├── Dockerfile # CUDA+Python基础环境
│ ├── requirements.txt # PyTorch核心依赖
│ ├── requirements.system.txt # 系统依赖
│ └── wheels/ # 预编译轮子
├── scripts/ # 自动化脚本
│ ├── build_app.sh # 应用构建
│ ├── build_base.sh # 基础环境构建
│ ├── comfyui-start.sh # ComfyUI启动
│ └── storage-setup.sh # 存储设置
├── comfyui_data/ # 数据持久化 (1.6T CNB空间)
│ ├── models/ # AI模型文件
│ ├── input/ # 输入数据
│ ├── output/ # 生成结果
│ ├── custom_nodes/ # 自定义节点
│ └── user/ # 用户配置
├── test_build_infra.sh # 基础镜像测试
├── compile_app_deps.sh # 依赖锁定脚本
└── README.md # 项目文档
- Python: 3.12 (最新稳定版)
- CUDA: 12.8 (最新支持)
- PyTorch: 2.9.1 (cu128优化)
- UV: 现代包管理器
- Docker: 多阶段构建
- AI/ML核心: torch, transformers, diffusers, xformers
- 图像处理: opencv-contrib-python-headless, pillow
- Web服务: fastapi, gradio, uvicorn
- ComfyUI生态: comfyui-frontend, comfyui-manager
缓存效果:
- 首次构建: ~25分钟
- 增量构建: ~3-5分钟 (85%+缓存命中率)
- 镜像大小: Builder ~8GB, Release ~3.5GB
设计理念：充分利用CNB的1.6T存储空间，提供开发便利性和数据集中管理
- 开发便利性：在
/workspace中直接访问所有ComfyUI功能 - 数据集中化：所有数据统一在
comfyui_data/目录管理 - 空间最大化：利用1.6T空间存储大型模型和生成结果
- 版本无关性：容器升级不影响用户数据
# 自动映射关系 (通过 storage-setup.sh)
/workspace/comfyui_data/models/ → /opt/ComfyUI/models/
/workspace/comfyui_data/input/ → /opt/ComfyUI/input/
/workspace/comfyui_data/output/ → /opt/ComfyUI/output/
/workspace/comfyui_data/custom_nodes/ → /opt/ComfyUI/custom_nodes/
/workspace/comfyui_data/user/ → /opt/ComfyUI/user/
# 开发便利性链接
/workspace/ComfyUI → /opt/ComfyUI
- 符号链接机制：无性能损耗的目录映射
- 自动迁移：首次运行时自动迁移现有数据
- 冲突处理：强制重新创建链接，避免ComfyUI Manager冲突
- 状态检查：启动时验证链接完整性
-
配置环境变量
cp .env.example .env # 编辑 .env 填入 CNB_TOKEN 等配置 -
触发构建
git push origin main -
监控部署
- CNB 控制台查看构建进度
- 访问 http://your-domain:8188
# 启动开发环境
docker run -it --gpus all \
-v $(pwd):/workspace \
-p 8188:8188 \
docker.cnb.cool/ainewstonb/comfyui-infra/comfyui-app:latest
# 运行 ComfyUI
./scripts/comfyui-start.sh
# 缓存失效 - 重建缓存
./scripts/build_app.sh cache-rebuild
# 依赖超时 - 增加超时设置
export UV_HTTP_TIMEOUT=300
./compile_app_deps.sh
# 检查 GPU 支持
docker run --gpus all <image> python -c "import torch; print(torch.cuda.is_available())"
# 重新设置存储映射
docker exec <container> /workspace/scripts/storage-setup.sh
- 缓存命中率: 85%+
- 并行下载: UV 比 pip 快 3-5倍
- 增量更新: 只重新下载变更依赖
- 冷启动: ~30秒
- GPU利用率: 95%+
- 并发处理: 支持多任务队列
# 添加新依赖
uv add package-name
# 移除依赖
uv remove package-name
# 更新锁文件
uv lock
# 检查依赖冲突
uv pip check
[project.optional-dependencies]
core = ["torch", "numpy<2.0", "transformers"]
vision = ["opencv-contrib-python-headless", "pillow"]
web = ["fastapi", "gradio", "uvicorn"]
dev = ["black", "pytest", "mypy"]
-
创建功能分支
git checkout -b feature/new-feature -
开发和测试
./test_build_app.sh -
提交变更
git add . git commit -m "feat: add new feature" git push origin feature/new-feature
- 遵循 PEP 8
- 使用语义化提交信息
- 更新相关文档
- 项目仓库: https://cnb.cool/Ainewstonb/comfyui-infra
- 问题反馈: 通过 Git Issues
- 技术文档: CNB 平台文档
# 临时测试文件
app/test-push-build.txt # 测试用临时文件
app/.trigger-build # 空的触发文件
infra/.trigger-build # 空的触发文件
# 示例文件 (可能重复)
comfyui_data/custom_nodes/example_node.py.example
comfyui_data/custom_nodes/websocket_image_save.py
# 超大脚本 (56KB) - 包含418个插件的subtree命令
scripts/docker_subtree_commands.sh # 建议拆分为模块化配置
comfyui_data/user/default/comfyui_issues_report.md # 用户报告，可能过期
UPDATE_LOG.md # 更新日志，建议整合到主文档
#!/bin/bash
# 清理冗余文件脚本
# 删除临时文件
rm -f app/test-push-build.txt
rm -f app/.trigger-build
rm -f infra/.trigger-build
# 删除示例文件 (如果不需要)
rm -f comfyui_data/custom_nodes/example_node.py.example
rm -f comfyui_data/custom_nodes/websocket_image_save.py
# 整理重复文档 (可选)
# mv UPDATE_LOG.md docs/CHANGELOG.md
echo "✅ 清理完成！建议提交前检查 git status"
📁 总文件数: 1000+ (包含插件)
📦 镜像大小: 3.5GB (生产) / 8GB (缓存)
⚡ 构建速度: 85%+ 缓存命中率
🔧 依赖包: 240+ 个 (已优化)
📚 插件数: 418+ 个 (自定义节点)
最后更新: 2025-12-27 - Python 3.12 + PyTorch 2.9.1 升级
Sponsor
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
