本项目是一个基于 CNB (Cloud Native Build) 平台的 ComfyUI 基础设施项目，提供高性能的 AI 图像生成环境，支持 CUDA 加速和完整的依赖管理。

┌─────────────────────────────────────────────────────────────┐
│                    CNB 平台                                  │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐    ┌─────────────────┐                │
│  │   Infra Layer    │ →  │   App Layer     │                │
│  │  (基础环境)      │    │  (应用层)       │                │
│  └─────────────────┘    └─────────────────┘                │
└─────────────────────────────────────────────────────────────┘

• Infra Layer: 基础 CUDA 12.8 + Python 3.11 + PyTorch 环境
• App Layer: ComfyUI 应用及其依赖
• 多阶段构建: BuildKit 缓存优化
• 数据持久化: 符号链接存储策略

• CNB 平台账号
• Docker 支持
• GPU 资源 (推荐)

# 构建 Infra 基础镜像
./test_build_infra.sh

# 构建 App 应用镜像
./test_build_app.sh

# 锁定依赖版本
./compile_app_deps.sh

workspace/
├── .cnb.yml                    # CNB 配置文件
├── app/                        # 应用层配置
│   ├── Dockerfile             # 应用层 Dockerfile
│   ├── requirements.in        # 依赖定义文件
│   └── requirements.txt       # 锁定的依赖版本
├── infra/                      # 基础设施层
│   ├── Dockerfile             # 基础层 Dockerfile
│   ├── requirements.txt       # 基础依赖
│   └── requirements.system.txt # 系统依赖
├── scripts/                    # 工具脚本
│   ├── cnbcache.sh            # CNB缓存镜像管理脚本
│   ├── comfyui-start.sh       # ComfyUI 启动脚本
│   ├── storage-setup.sh       # 存储初始化脚本
│   └── docker_subtree_commands.sh # Git subtree 管理
├── comfyui_data/              # ComfyUI 数据目录
│   ├── models/               # 模型文件
│   ├── input/                # 输入文件
│   ├── output/               # 输出文件
│   ├── custom_nodes/         # 自定义节点
│   └── user/                 # 用户配置
└── build-logs/               # 构建日志 (已 gitignore)

• Python: 3.11
• CUDA: 12.8
• PyTorch: cu128 版本
• UV: 现代包管理器
• Docker: 容器化部署
• CNB: 云原生构建平台

• torch, torchaudio, torchvision (cu128)
• transformers, diffusers, accelerate
• xformers, bitsandbytes
• safetensors, onnxruntime-gpu

• opencv-contrib-python-headless
• Pillow, albumentations
• scikit-image, imageio

• fastapi, gradio
• uvicorn, aiohttp

• comfyui-frontend-package
• comfyui-workflow-templates
• comfyui-embedded-docs

项目采用多阶段 Docker 构建的缓存策略：

• Builder Stage: 包含 UV 缓存的胖镜像，用于下次构建加速
• Release Stage: 精简的生产镜像，不包含构建缓存
• 缓存镜像: docker.cnb.cool/ainewstonb/comfyui-infra/comfyui-app:build-cache

# 更新依赖定义
vim app/requirements.in

# 重新锁定版本
./compile_app_deps.sh

# 检查变更
git diff app/requirements.txt

# 测试基础层
./test_build_infra.sh

# 测试应用层
./test_build_app.sh

# 查看构建日志
ls -la build-logs/

# 分析构建效果
grep "Using cache" build-logs/*.log

• 模型文件: /workspace/comfyui_data/models - 避免重复下载
• 输入文件: /workspace/comfyui_data/input - 持久化存储
• 输出文件: /workspace/comfyui_data/output - 防止数据丢失
• 用户配置: /workspace/comfyui_data/user - 保持设置一致性
• 自定义节点: /workspace/comfyui_data/custom_nodes - 插件持久化

运行 scripts/storage-setup.sh 自动创建符号链接映射。

# 现象：缓存未命中
# 原因：首次构建或缓存已清理

# 设置更长超时时间
export UV_HTTP_TIMEOUT=120
export UV_REQUEST_TIMEOUT=120

# 重新锁定依赖
./compile_app_deps.sh

# 检查冲突详情
uv pip check

# 构建日志位置
build-logs/manual-build-*.log

# 查找缓存使用情况
grep "Using cache" build-logs/*.log

# 查找错误信息
grep -i "error\|failed" build-logs/*.log

1. 配置 .cnb.yml

   $:
     tag_push:
       - stages:
           - name: docker build
             volumes: [...]
   

2. 触发构建

   git push origin main
   

3. 监控构建

   • CNB 控制台查看构建进度
   • 检查缓存命中率
   • 分析构建日志

# 启动开发环境
docker run -it --gpus all \
  -v $(pwd):/workspace \
  comfyui-app:test

# 运行 ComfyUI
cd /workspace
./scripts/comfyui-start.sh

• ✅ BuildKit 多阶段构建缓存
• ✅ UV bind mount 缓存
• ✅ 模型文件缓存

• ✅ CUDA 加速支持
• ✅ 内存优化配置
• ✅ 并行处理设置
• ✅ 缓存预热策略

1. 代码风格: 遵循 PEP 8
2. 提交信息: 使用语义化提交
3. 依赖管理: 通过 requirements.in 管理依赖
4. 文档更新: 重要变更需更新文档

# 1. 创建功能分支
git checkout -b feature/new-feature

# 2. 开发和测试
./test_build_app.sh

# 3. 提交变更
git add .
git commit -m "feat: add new feature"

# 4. 推送分支
git push origin feature/new-feature

• ✅ 实现BuildKit多阶段构建缓存
• ✅ 添加构建日志记录
• ✅ 更新依赖到最新版本

• v13.0: 引入 UV 包管理器
• v12.0: CUDA 12.8 支持
• v11.0: CNB 平台集成
• v10.0: 容器化架构重构

• 项目仓库: https://cnb.cool/Ainewstonb/comfyui-infra
• 问题反馈: 通过 Git Issues
• 技术支持: CNB 平台文档

---

最后更新: 2025-11-27