Linux 下使用 Docker 部署 ComfyUI-平芜编程栈

Linux 下使用 Docker 部署 ComfyUI

Linux 下使用 Docker 部署 ComfyUI
- 准备工作
- - 硬件与系统要求
  - 安装 Docker
  - 安装 NVIDIA Container Toolkit
- 部署 ComfyUI
- - 选择镜像版本
  - 创建数据目录
  - 启动容器
  - 验证部署
- 下载模型
- - 使用 Hugging Face 镜像站下载
  - 模型存放位置
- 使用 ComfyUI 进行图像生成
- 常见问题与排查
- - `hf download` 报错 "No such option"
  - ComfyUI-Manager 网络超时
  - 容器内模型目录已存在导致启动失败
  - PyTorch CUDA 版本警告
  - 进入容器调试
- 总结
参考

由于本人水平有限，难免出现错漏，敬请批评改正。
更多精彩内容，可点击进入我的个人主页查看

Linux 下使用 Docker 部署 ComfyUI

准备工作

硬件与系统要求

操作系统：Linux（推荐 Ubuntu 20.04+）
NVIDIA GPU：支持 CUDA 的显卡（本文以 RTX 3080 Ti 为例）
NVIDIA 驱动：已正确安装，可用nvidia-smi验证
磁盘空间：至少 20GB（模型文件较大）

安装 Docker

sudoapt-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\|sed's#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--runtime=dockersudosystemctl 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-v2`	13.0	RTX 30/40/50 系列	推荐，性能最佳
`cu126-slim`	12.6	RTX 20/30 系列，GTX 10/16 系列	兼容性更广
`cu118-megapak`	11.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/hub`	Hugging 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：进入容器 Bash

dockerexec-itcomfyuibash

Step 2：设置镜像源

exportHF_ENDPOINT=https://hf-mirror.com

Step 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_models

hf download常用选项：

选项	说明
`--local-dir`	指定下载目录
`--revision`	指定版本分支
`--token`	Hugging Face 访问令牌
`--include`/`--exclude`	文件过滤

模型存放位置

下载后的模型文件会保存在挂载目录storage-models/models/下，对应容器内的/root/ComfyUI/models/。ComfyUI 按模型类型读取不同子目录：

模型类型	存放路径
大模型 (Checkpoint)	`models/checkpoints/`
LoRA	`models/loras/`
VAE	`models/vae/`
ControlNet	`models/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 fashion

A 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_PROXY=http://代理IP:端口\-eHTTPS_PROXY=http://代理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:8188

Docker 部署的优势在于环境隔离、一键迁移、数据持久化，非常适合在服务器上长期运行 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

Linux 下使用 Docker 部署 ComfyUI

Linux 下使用 Docker 部署 ComfyUI

Linux 下使用 Docker 部署 ComfyUI

准备工作

硬件与系统要求

安装 Docker

安装 NVIDIA Container Toolkit

部署 ComfyUI

选择镜像版本

创建数据目录

启动容器

验证部署

下载模型

使用 Hugging Face 镜像站下载

模型存放位置

使用 ComfyUI 进行图像生成

常见问题与排查

`hf download`报错 “No such option”

ComfyUI-Manager 网络超时

容器内模型目录已存在导致启动失败

PyTorch CUDA 版本警告

进入容器调试

总结

参考

【2014-05-09】某《魔鬼训练营》读书笔记：特定服务扫描

【2014-05-19】某《魔鬼训练营》读书笔记：msfpayload的使用及免杀工具

纺织印染生产线底层通信重构：破解非标异构协议的边缘解析算法与伪代码实战

极简产品不是藏按钮：用真实任务决定渐进式暴露

硬件测试内容之十二：TDC（芯片）

Linux文件操作核心：mv与cp命令深度解析与实战技巧

Linux 下使用 Docker 部署 ComfyUI

Linux 下使用 Docker 部署 ComfyUI

准备工作

硬件与系统要求

安装 Docker

安装 NVIDIA Container Toolkit

部署 ComfyUI

选择镜像版本

创建数据目录

启动容器

验证部署

下载模型

使用 Hugging Face 镜像站下载

模型存放位置

使用 ComfyUI 进行图像生成

常见问题与排查

hf download报错 “No such option”

ComfyUI-Manager 网络超时

容器内模型目录已存在导致启动失败

PyTorch CUDA 版本警告

进入容器调试

总结

参考

【2014-05-09】某《魔鬼训练营》读书笔记：特定服务扫描

【2014-05-19】某《魔鬼训练营》读书笔记：msfpayload的使用及免杀工具

纺织印染生产线底层通信重构：破解非标异构协议的边缘解析算法与伪代码实战

极简产品不是藏按钮：用真实任务决定渐进式暴露

硬件测试内容之十二：TDC（芯片）

Linux文件操作核心：mv与cp命令深度解析与实战技巧

`hf download`报错 “No such option”