tcpassos/comfyui-runpod

ComfyUI RunPod Docker镜像

镜像概述

这是预构建的Docker镜像，用于在RunPod平台运行ComfyUI（AI图像生成工具），实现快速冷启动。镜像内置所有核心依赖（ComfyUI、Python、PyTorch、sage attention、ffmpeg等），工作流可变内容（自定义节点、模型、配置）存储于/workspace目录，支持持久化。

目录结构

构建镜像

bash
docker build -t tcpassos/comfyui-runpod:latest /path/to/comfyui-docker
docker push tcpassos/comfyui-runpod:latest

最终大小约16GB，良好网络下构建需10-15分钟（RunPod基础镜像约9GB）。

（可选）指定ComfyUI版本构建：

bash
docker build --build-arg COMFYUI_VERSION=v0.22.0 -t tcpassos/comfyui-runpod:v0.22 /path/to/comfyui-docker

本地验证（冒烟测试）

bash
docker run --rm --entrypoint python3 tcpassos/comfyui-runpod:latest -c "import torch, torchvision, torchaudio, xformers, sageattention; print('torch', torch.__version__, 'cuda', torch.version.cuda, 'tv', torchvision.__version__, 'ta', torchaudio.__version__, 'xf', xformers.__version__)"

预期输出：

torch 2.12.0+cu130 cuda 13.0 tv 0.27.0+cu130 ta 2.11.0+cu130 xf 0.0.35

需使用--entrypoint python3，否则默认入口会先执行节点/模型下载流程。

关于xformers

镜像安装xformers==0.0.35，但官方wheel基于torch 2.10/cu128/py3.10构建，本镜像使用torch 2.12/cu130/py3.12，其CUDA扩展会被禁用。建议使用sageattention（纯Triton实现，功能正常）作为主要优化方式。

RunPod部署步骤

1. 创建模板

RunPod控制台 → Templates → + New Template：

环境变量：

2. 部署Pod

Templates → 你的模板 → Deploy：

• GPU：选择支持CUDA 12.x+的型号（如RTX PRO 4500 Blackwell）；
• Volume：启用以持久化/workspace；
• Region：任意（复用卷时建议选卷所在区域）。

等待Pod状态为"Running"。

3. 首次启动

需5-15分钟，入口程序会：

1. 从CONFIG_URL下载config.json（若无则终止）；
2. 克隆自定义节点；
3. 安装节点依赖；
4. 下载模型（使用HF/***令牌）。

通过Connect → Logs查看进度，出现"Starting ComfyUI on port 8188"时即可使用。

4. 连接访问

Connect → HTTP Service Port 8188 → 访问地址：http://<pod-id>-8188.proxy.runpod.net。

5. 后续启动

停止重启同一Pod（带卷）→ 约30秒启动：

• 跳过节点/模型下载；
• 默认不更新节点；
• 依赖已满足无需重装。

编辑下载内容

SSH进入Pod，编辑/workspace/config.json，示例schema：

json
{
  "nodes": [
    "https://github.com/user/repo",
    {"url": "https://github.com/kijai/ComfyUI-KJNodes", "ref": "v1.0.0"}
  ],
  "models": [
    {"category": "checkpoints", "url": "...", "filename": "model.safetensors"},
    {"path": "models/loras/character", "url": "...", "filename": "char.safetensors"}
  ],
  "workflows": [
    {"url": "https://gist.../wan_i2v.json", "filename": "wan_i2v.json"}
  ]
}

编辑后重启Pod即可同步更新。

故障排除

• 日志：通过Connect → Logs查看；
• 健康检查：每30秒检查8188端口（启动期600秒）；
• 模型未跳过：确认filename与实际文件一致；
• HF 401：需接受模型条款并确保令牌有权限；
• xformers警告：正常现象，使用sageattention即可。