Linux 下使用 Docker 部署 ComfyUI

Linux 下使用 Docker 部署 ComfyUILinux 下使用 Docker 部署 ComfyUI准备工作硬件与系统要求安装 Docker安装 NVIDIA Container Toolkit部署 ComfyUI选择镜像版本创建数据目录启动容器验证部署下载模型使用 Hugging Face 镜像站下载模型存放位置使用 ComfyUI 进行图像生成常见问题与排查hf download 报错 No such optionComfyUI-Manager 网络超时容器内模型目录已存在导致启动失败PyTorch CUDA 版本警告进入容器调试总结参考由于本人水平有限难免出现错漏敬请批评改正。更多精彩内容可点击进入我的个人主页查看Linux 下使用 Docker 部署 ComfyUI准备工作硬件与系统要求操作系统Linux推荐 Ubuntu 20.04NVIDIA GPU支持 CUDA 的显卡本文以 RTX 3080 Ti 为例NVIDIA 驱动已正确安装可用nvidia-smi验证磁盘空间至少 20GB模型文件较大安装 Dockersudoapt-getupdatesudoapt-getinstalldocker.io-ysudosystemctl startdockersudosystemctlenabledocker验证安装docker--version安装 NVIDIA Container Toolkit这是让 Docker 容器访问 GPU 的关键组件。# 添加 NVIDIA Docker 软件源curl-fsSLhttps://nvidia.github.io/libnvidia-container/gpgkey\|sudogpg--dearmor-o/usr/share/keyrings/nvidia-container-toolkit-keyring.gpgcurl-s-Lhttps://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list\|seds#deb https://#deb [signed-by/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g\|sudotee/etc/apt/sources.list.d/nvidia-container-toolkit.list# 安装 nvidia-container-toolkitsudoapt-getupdatesudoapt-getinstall-ynvidia-container-toolkit# 配置 Docker 运行时sudonvidia-ctk runtime configure--runtimedockersudosystemctl restartdocker验证 GPU 是否可被 Docker 访问dockerrun--rm--gpusall nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi部署 ComfyUI选择镜像版本yanwk/comfyui-boot是国内社区流行的 ComfyUI Docker 镜像提供多个 CUDA 版本。镜像标签CUDA 版本适用显卡架构说明cu130-slim-v213.0RTX 30/40/50 系列推荐性能最佳cu126-slim12.6RTX 20/30 系列GTX 10/16 系列兼容性更广cu118-megapak11.8老旧显卡含大量预装插件提示slim版本仅包含 ComfyUI 和 ComfyUI-Manager依赖齐全适合初学者。如果不确定显卡架构可参考 NVIDIA 架构对照表。创建数据目录数据持久化是 Docker 部署的关键。建议先创建以下目录结构mkdir-p\storage-cache/dot-cache\storage-cache/dot-config\storage-nodes/dot-local\storage-nodes/custom_nodes\storage-models/models\storage-models/hf-hub\storage-models/torch-hub\storage-user/input\storage-user/output\storage-user/user-profile\storage-user/user-scripts各目录用途说明目录容器内对应路径用途storage-models/models/root/ComfyUI/models模型文件最重要storage-models/hf-hub/root/.cache/huggingface/hubHugging Face 缓存storage-user/output/root/ComfyUI/output生成的图片输出storage-user/input/root/ComfyUI/input输入图片storage-nodes/custom_nodes/root/ComfyUI/custom_nodes自定义节点启动容器以cu126-slim为例与你的环境一致dockerrun-it--rm\--namecomfyui\--runtimenvidia\--gpusall\-p8188:8188\-v$(pwd)/storage-cache/dot-cache:/root/.cache\-v$(pwd)/storage-cache/dot-config:/root/.config\-v$(pwd)/storage-nodes/dot-local:/root/.local\-v$(pwd)/storage-nodes/custom_nodes:/root/ComfyUI/custom_nodes\-v$(pwd)/storage-models/models:/root/ComfyUI/models\-v$(pwd)/storage-models/hf-hub:/root/.cache/huggingface/hub\-v$(pwd)/storage-models/torch-hub:/root/.cache/torch/hub\-v$(pwd)/storage-user/input:/root/ComfyUI/input\-v$(pwd)/storage-user/output:/root/ComfyUI/output\-v$(pwd)/storage-user/user-profile:/root/ComfyUI/user\-v$(pwd)/storage-user/user-scripts:/root/user-scripts\-eCLI_ARGS\yanwk/comfyui-boot:cu126-slim参数说明-it --rm交互模式容器停止后自动删除--runtime nvidia使用 NVIDIA 运行时--gpus all将所有 GPU 分配给容器-p 8188:8188端口映射主机端口:容器端口-v挂载数据卷实现数据持久化-e CLI_ARGS可传入额外启动参数如--lowvram验证部署启动成功后在浏览器访问http://你的服务器IP:8188查看容器日志dockerlogs comfyui下载模型使用 Hugging Face 镜像站下载由于国内访问 Hugging Face 较慢推荐使用镜像站hf-mirror.com。Step 1进入容器 Bashdockerexec-itcomfyuibashStep 2设置镜像源exportHF_ENDPOINThttps://hf-mirror.comStep 3使用hf命令下载模型注意旧版huggingface-cli已弃用请使用hf命令。以下载z_image_turbo模型为例# 下载 VAE 模型到 vae 目录hf download Comfy-Org/z_image_turbo\split_files/vae/ae.safetensors\--local-dir /root/ComfyUI/models/vae# 下载文本编码器hf download Comfy-Org/z_image_turbo\split_files/text_encoders/qwen_3_4b_fp8_mixed.safetensors\--local-dir /root/ComfyUI/models/text_encoders# 下载扩散模型hf download Comfy-Org/z_image_turbo\split_files/diffusion_models/z_image_turbo_int8_convrot.safetensors\--local-dir /root/ComfyUI/models/diffusion_modelshf download常用选项选项说明--local-dir指定下载目录--revision指定版本分支--tokenHugging Face 访问令牌--include/--exclude文件过滤模型存放位置下载后的模型文件会保存在挂载目录storage-models/models/下对应容器内的/root/ComfyUI/models/。ComfyUI 按模型类型读取不同子目录模型类型存放路径大模型 (Checkpoint)models/checkpoints/LoRAmodels/loras/VAEmodels/vae/ControlNetmodels/controlnet/文本编码器models/text_encoders/扩散模型models/diffusion_models/使用 ComfyUI 进行图像生成Dramatic black and white high fashion studio portrait, close-up bust shot, pale platinum blonde woman with sleek low ponytail,headtilted upward, eyes softly closed, wearing a fitted black turtleneck top. A large translucent pale white butterfly hovers gently right at her lips, delicate detailed wing veins visible. Hard rim light creates glowing bright white halo around her hair and face, deep inky pure black minimalist background, stark high contrast chiaroscuro lighting, film grain texture, moody ethereal atmosphere, monochrome, editorial fashion photography, shot on 35mm film, soft subtle skin texture, sharp focus on butterfly and facial profile, vertical composition, minimalist dark aesthetic, artistic surreal fashionA fluffy orange tabbycatsitting on a sunlit wooden windowsill, 8K ultra-high definition, soft golden hour lighting, sharp focus on individual fur strands and whiskers, warm natural colors, professional pet photography--ar3:2常见问题与排查hf download报错 “No such option”新版hf命令不支持--local-dir-use-symlinks和--resume-download直接使用--local-dir即可默认支持断点续传。ComfyUI-Manager 网络超时启动日志中可能出现Failed to perform initial fetching错误这是因为容器无法访问 GitHub。解决方法方案一配置代理在docker run中添加环境变量-eHTTP_PROXYhttp://代理IP:端口\-eHTTPS_PROXYhttp://代理IP:端口方案二忽略此错误手动下载模型使用不影响核心功能容器内模型目录已存在导致启动失败如果挂载了/root/ComfyUI整个目录可能与镜像预置内容冲突。建议按本文方式分别挂载子目录而非挂载整个/root。PyTorch CUDA 版本警告日志中出现You need pytorch with cu130 or higher是性能提示而非错误使用 CUDA 12.6 镜像时部分优化不可用但不影响正常使用。进入容器调试# 进入正在运行容器的 Bashdockerexec-itcomfyuibash# 查看 ComfyUI 日志dockerlogs comfyui# 实时跟踪日志dockerlogs-fcomfyui总结通过 Docker 部署 ComfyUI 的核心流程如下安装 Docker和NVIDIA Container Toolkit拉取镜像推荐yanwk/comfyui-boot:cu130-slim-v2创建数据目录并启动容器挂载数据卷实现持久化下载模型使用hf命令 镜像站浏览器访问http://服务器IP:8188Docker 部署的优势在于环境隔离、一键迁移、数据持久化非常适合在服务器上长期运行 ComfyUI。参考[1] https://github.com/Comfy-Org/ComfyUI.git[2] https://github.com/YanWenKun/ComfyUI-Docker.git[3] https://github.com/dam-pav/comfyui.git