ComfyUI本地部署教程：Docker方案30分钟跑通出图

用 Docker 部署 ComfyUI 的完整流程：准备环境、编写 docker-compose.yml、下载模型、启动容器、验证 GPU，并附显存不足参数与常见报错排查。

想用 ComfyUI 画图又不想折腾 Python 和 CUDA 环境，可以用 Docker 一条命令把服务跑起来。整条 ComfyUI 本地部署链路只有三步：写 docker-compose.yml、下载模型、执行 docker compose up，30 分钟内能出第一张图。

为什么用 Docker 部署 ComfyUI

ComfyUI 是目前主流的开源 AI 绘图工具之一，但手动部署容易踩三个坑：

Python 版本冲突：它需要 Python 3.10 以上，而系统自带环境往往是 3.8。
CUDA / cuDNN 版本匹配：装错一个版本，GPU 直接跑不起来。
依赖互相打架：torch、xformers、triton 的版本需要精确对应。

换成 Docker 后，环境隔离、版本锁定、一键重建都能解决，换机器只要带上配置文件即可。

部署前需要准备什么

一台带 NVIDIA 显卡的机器，建议 6GB 显存以上。
已安装 Docker 与 Docker Compose。
能访问 Docker Hub，国内可配置镜像加速。

没装 Docker 的话先执行（Ubuntu / Debian）：

curl -fsSL https://get.docker.com | sh
sudo systemctl enable docker
sudo systemctl start docker

ComfyUI Docker 部署的五个步骤

第 1 步：创建项目目录

mkdir -p /opt/comfyui/{models,output,input}
cd /opt/comfyui

目录分工如下：

docker-compose.yml：部署配置
models/：模型文件，内部再分 checkpoints（主模型）、loras（LoRA）、vae（VAE 模型）
output/：生成的图片
input/：上传的图片

第 2 步：编写 docker-compose.yml

核心内容包含：版本声明 3.8，服务名 comfyui，镜像 yanwick/comfyui:latest，容器名 comfyui，重启策略 unless-stopped，端口映射 8188:8188，把 ./models、./output、./input 三个本地目录挂载进容器，环境变量 CLI_ARGS 设为 --listen 0.0.0.0 --port 8188，并在 deploy 段声明 NVIDIA GPU 预留。

该镜像并非 ComfyUI 官方发布，发布前需核验镜像来源、版本更新与安全性。

参数	作用
--listen 0.0.0.0	允许外部访问，不写则只能本机访问
--port 8188	Web 界面端口
volumes	本地目录映射进容器，模型与图片不会丢
capabilities: [gpu]	把 GPU 透传给容器

第 3 步：下载模型

ComfyUI 至少需要一个 Checkpoint 模型才能出图。推荐 SDXL 1.0（约 6.9GB），显存偏小可改用 SD 1.5（约 4GB）。把文件下载到 models/checkpoints/ 目录：

cd /opt/comfyui/models/checkpoints
wget https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors

国内下载慢，可把域名替换为 hf-mirror.com 镜像站。SD 1.5 对应文件名为 v1-5-pruned-emaonly.safetensors。下载地址与文件名发布前需核验。

第 4 步：启动服务

执行 docker compose up -d，等待约 10 秒，浏览器打开 http://你的IP:8188，能看到界面即部署成功。

第 5 步：确认 GPU 是否生效

运行 docker exec comfyui nvidia-smi，能看到显卡信息说明 GPU 已透传成功。若报错，先检查宿主机是否安装 NVIDIA 驱动与 nvidia-container-toolkit：

sudo apt-get install nvidia-container-toolkit
sudo systemctl restart docker

出第一张图

打开 http://你的IP:8188，默认工作流已加载好，点右下角 Queue Prompt 按钮，等待 10–30 秒，图片会出现在右侧。没出图大概率是模型位置不对，检查一下：

ls /opt/comfyui/models/checkpoints/

目录里必须存在 .safetensors 或 .ckpt 文件。

显存不够怎么办

6GB 显存跑 SDXL 比较勉强，在 CLI_ARGS 后追加参数可以省显存：

environment:
- CLI_ARGS=--listen 0.0.0.0 --port 8188 --lowvram --reserve-vram 1

参数	效果
--lowvram	低显存模式，分块加载模型
--reserve-vram 1	预留 1GB 给系统，防止卡死

4GB 显存建议直接用 SD 1.5 模型，不要跑 SDXL。

常见报错排查

报错	原因与处理
CUDA out of memory	显存不足，加 --lowvram 参数或换 SD 1.5 模型
Model not found	模型没放对，确认文件在 models/checkpoints/ 且为 .safetensors 格式
Connection refused	容器没起来，用 docker compose logs comfyui 查看日志
重启后模型丢失	检查 volumes 挂载，模型要放宿主机 models/checkpoints/，不是容器内部

进阶：安装自定义节点

ComfyUI 的插件生态是它相对其他绘图前端的主要优势。以中文汉化插件为例：

docker exec -it comfyui bash 进入容器
cd /app/ComfyUI/custom_nodes
git clone https://github.com/AIGODLIKE/AIGODLIKE-COMFYUI-TRANSLATION.git
exit 退出后执行 docker compose restart 重启容器

服务器无法直接访问 GitHub 时，可以在本地下载 ZIP 包，通过 SFTP 上传到服务器再解压。

Docker 部署与手动部署怎么选

对比项	手动部署	Docker 部署
安装成本	装 Python、CUDA、依赖，耗时较长	docker compose up 一条命令
环境稳定性	版本冲突容易崩	环境隔离，互不影响
迁移	换机器要重来	带上 docker-compose.yml 就能跑
升级	比较麻烦	换镜像版本即可

一个实际运行案例

作者在医院的一台服务器上长期运行 ComfyUI：Tesla V100 32GB 显卡，使用 sdXL_v10.safetensors 模型，Docker 镜像为自定义版本（在基础镜像上装了 ReActor 换脸、SeedVR2 视频超分等节点），启动参数为 --listen 0.0.0.0 --port 8188 --reserve-vram 1 --lowvram。其中的运行稳定性与日均出图量为作者自述，发布前需核验。