第三世界的妖孽ComfyUI 这个节点式 AI 绘画工具，圈子里玩 Stable Diffusion 的朋友应该都不陌生。但提到部署，很多人的第一反应还是秋叶整合包，或者手动去配 Python 环境、拉依赖、装 PyTorch，光是折腾环境就能劝退一半人。我自己从整合包一路用到 Docker，说实话，刚开始也觉得"能用就行，为啥要容器化"，但当你开始折腾多台机器、升级版本、迁移工作流的时候，Docker 的优势就会非常明显。
这篇东西不是官方文档的翻译，而是基于我自己实际部署过程中踩过的坑、总结出来的经验。我会从为什么选 Docker、怎么准备环境、如何一步步把镜像跑起来，到模型怎么挂、插件怎么装、性能怎么调，最后再把那些最让人头疼的报错整理成一份排查速查表。无论你是第一次接触 Docker 的新手，还是已经被各种报错折磨许久的老玩家，这篇应该都能帮你少走不少弯路。
1. 为什么推荐用 Docker 部署 ComfyUI
1.1 环境隔离：告别"在我机器上是好的"
很多人第一次意识到 Docker 的价值，往往是在环境出问题的时候。手动安装 ComfyUI 需要 Python、CUDA、cuDNN、PyTorch 一堆东西，版本稍微对不上，轻则报错，重则直接连显卡都认不出来。我认识的一些朋友，为了装 ComfyUI 把系统 Python 环境搞得一团糟，最后只能重装系统。
Docker 的思路很简单：把 ComfyUI 连同它依赖的运行环境一起打包成一个独立的镜像。你不再需要在宿主机上装任何 Python 依赖，只需要一个 Docker 运行时。容器内部是什么系统、什么版本的 CUDA、什么版本的 PyTorch，都和外面无关。这也意味着你可以同时跑多个不同版本的 ComfyUI，互不干扰。
我在一台机器上就同时跑过两个容器：一个是默认的 PyTorch 版本用于日常出图，另一个专门测试最新的 Flash Attention 分支，两个容器共用同一个模型目录，工作流文件也互不影响。这种隔离能力在手动部署下几乎是不可想象的。
1.2 可迁移性与团队协作
Docker 还有一个杀手级特性——可迁移性。你在一台机器上把整个环境调好，docker commit 或者写一份 Dockerfile 记录下来，到另一台机器上只需要重新构建一次，得到的是一模一样的环境。这一点在做多机协作或者备用机器部署时尤其方便。
对工作室或者团队来说，把 Dockerfile、docker-compose.yml 和启动脚本放进 Git 仓库，任何一个成员拉下来跑 docker compose up -d 就能得到一致的开发环境。新成员不需要再读一份几百行的安装文档，也不存在"我装的环境和你不一样"这种问题。
1.3 和本地直装、整合包的横向对比
我把常见的几种部署方式放在一起对比过：
| 对比项 | Docker 部署 | 秋叶整合包 | 手动安装 |
|---|---|---|---|
| 环境隔离 | 完全隔离 | 内部集成但固定 | 无隔离 |
| 升级回滚 | 镜像版本可控 | 覆盖安装有风险 | 需要手动处理 |
| 多版本共存 | 轻松支持 | 不支持 | 极难实现 |
| 命令操作 | 需要熟悉 Docker | 开箱即用 | 需要熟悉 Python 生态 |
| 适合人群 | 愿意折腾、追求可控 | 新手、追求省事 | 需要定制化的人 |
需要说明的是，秋叶整合包对新手非常友好，我至今仍然推荐纯小白先从整合包开始，等对 ComfyUI 有了基本认知后再转 Docker。这并不矛盾，工具没有高低之分，只有合不合适。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 部署前的准备：硬件要求与 Docker 环境搭建
2.1 显卡与硬件的硬性门槛
先泼一盆冷水：ComfyUI 主要靠 GPU 做推理，如果你没有一块 NVIDIA 显卡，Docker 部署的体验会大打折扣。虽然可以通过 CPU 跑，但出图速度只能用"惨烈"来形容，一张 512x512 的图可能要等好几分钟。
具体硬件建议如下：
- 显卡：NVIDIA 显卡，显存至少 8GB（推荐 12GB 以上），这直接决定了你能跑多大的模型和分辨率。
- 内存：16GB 起步，32GB 更稳妥。加载大模型时内存不足会导致系统卡死。
- 磁盘：模型文件动辄几个 GB，SDXL 模型 6~7GB，最新的一些大模型甚至有 10GB 以上。建议预留 100GB 以上空间，且优先使用固态硬盘。
- 操作系统：Linux（Ubuntu 20.04+ / Debian 11+）最省心，Windows 用 Docker Desktop 也能跑，但注意 GPU 直通的配置差异，macOS 只能跑 CPU 或 Apple Silicon 加速。
2.2 Docker 运行时安装：Linux 与 Windows 的差异
Linux 环境下的安装比较简单。以 Ubuntu 为例，官方提供了安装脚本，也可以走 apt 源安装。
bash复制# 安装依赖
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
# 使用官方脚本安装 Docker Engine
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# 将当前用户加入 docker 组，免 sudo 执行 docker 命令
sudo usermod -aG docker $USER
安装完成后记得注销重新登录，让用户组生效。验证一下：
bash复制docker --version
docker run hello-world
Windows 下一般用 Docker Desktop，安装过程基本都是图形界面，一路下一步即可。需要注意的一点是，Docker Desktop 在 Windows 上依赖 WSL2 或 Hyper-V，安装前必须在 BIOS 里开启虚拟化。开机自检时进 BIOS（不同主板按键不同，一般是 Del 或 F2），找到 Intel VT-x 或 AMD-V 选项并启用。这一步没做的话，装完 Docker Desktop 大概率会报错。Windows 下 GPU 透传，我建议用 WSL2 后端，兼容性和性能都比 Hyper-V 好。
macOS 用户则建议直接用 Docker Desktop 的 Apple Silicon 版本，部署方式与 Linux 基本一致，只是 GPU 加速需要额外配置，后续会提到。
2.3 镜像选择策略：官方镜像与社区镜像怎么权衡
镜像的选择直接影响后续的使用体验。ComfyUI 官方在 Docker Hub 上发布了镜像，但更多的用户社区维护版本在功能上更丰富，比如带上了常用自定义节点、预装了 Face Restore 等工具。
官方的优势是干净、可定制性强，适合想自己搭建一套环境的人；社区版通常体积更大，但开箱即用。我的建议是：新手用社区版起步，熟悉后再切官方镜像是更平滑的路径。
不过，无论你选哪个镜像，都要留意国内拉取 Docker Hub 镜像慢的问题。这里有一个很实用的技巧：配置镜像加速器。
json复制// 在 Docker Desktop 的设置 -> Docker Engine