为什么用Docker部署ComfyUI
ComfyUI是目前使用率很高的AI绘画工作流工具，特点是节点化、可复用、可扩展，适合搭建文生图、图生图、高清修复、局部重绘、视频帧处理等流程。传统安装需要处理Python版本、CUDA、依赖包和插件冲突，环境稍有差异就可能报错。Docker部署的优势是把运行环境封装在容器里，镜像拉取后即可启动，迁移到新机器时只要保留模型、工作流、输出文件和自定义节点目录即可。
这种方式尤其适合三类用户：一是有NVIDIA显卡的本地工作站，希望快速搭建稳定环境；二是团队共用一台GPU服务器，需要统一路径和端口；三是经常测试插件、模型版本，希望通过容器隔离降低系统被依赖污染的风险。需要注意的是，Docker并不会让显卡性能凭空提升，它解决的是部署一致性和维护便利性，显存大小、驱动版本和模型体积仍然决定实际体验。
部署前准备
开始前先确认三项条件。第一，系统已安装Docker，并能正常执行docker ps。Windows用户建议使用Docker Desktop，并把项目目录放在性能较好的磁盘；Linux用户建议使用较新的Docker Engine。第二，如果要使用NVIDIA GPU，需要安装匹配的显卡驱动，并配置NVIDIA Container Toolkit，执行docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi能看到显卡信息，才说明容器可调用GPU。第三，规划好数据目录，不要把模型和输出文件只放在容器内部，否则删除容器后数据会丢失。
建议目录结构如下：/data/comfyui/models用于存放大模型、VAE、LoRA、ControlNet等文件；/data/comfyui/output用于保存生成结果；/data/comfyui/input用于上传参考图；/data/comfyui/custom_nodes用于放置插件；/data/comfyui/user用于保存部分用户配置和工作流。路径可以按实际磁盘调整，但应避免中文路径、空格路径和权限混乱的网络目录。
镜像选择与拉取
ComfyUI生态中常见做法有两种：直接使用维护较活跃的社区镜像，或自己基于官方项目构建镜像。新手更适合先使用现成镜像，例如ghcr.io/ai-dock/comfyui:latest这类包含运行环境的镜像。不同镜像内部目录可能不同，部署前要查看镜像说明，确认ComfyUI根目录、模型目录和启动参数写法。为了降低不可控风险，不建议随意使用来源不明、长期未更新或说明缺失的镜像。
拉取镜像可执行：docker pull ghcr.io/ai-dock/comfyui:latest。如果服务器访问镜像仓库较慢，可以更换可靠的镜像源服务或在网络条件较好的环境预先拉取，再通过docker sa ve和docker load迁移。生产环境不建议永远使用latest标签，因为它可能在某次更新后改变依赖版本。更稳妥的方式是先用latest验证，再固定到具体版本标签，便于回滚。
一键启动命令示例
创建目录后，可以用一条命令启动容器。Linux示例：mkdir -p /data/comfyui/{models,output,input,custom_nodes,user}，随后执行：docker run -d --name comfyui --restart unless-stopped --gpus all -p 8188:8188 -v /data/comfyui/models:/workspace/ComfyUI/models -v /data/comfyui/output:/workspace/ComfyUI/output -v /data/comfyui/input:/workspace/ComfyUI/input -v /data/comfyui/custom_nodes:/workspace/ComfyUI/custom_nodes -v /data/comfyui/user:/workspace/ComfyUI/user -e CLI_ARGS="--listen 0.0.0.0 --port 8188" ghcr.io/ai-dock/comfyui:latest。
命令里有几个关键点。--name comfyui用于指定容器名，后续查看日志、停止、重启都更方便；--restart unless-stopped表示系统重启后自动拉起服务；--gpus all让容器使用显卡，如果没有GPU可以删除该参数，但生成速度会明显下降；-p 8188:8188表示把宿主机8188端口映射到容器8188端口；多个-v参数负责把宿主机目录挂载到容器中，实现数据持久化；--listen 0.0.0.0允许从宿主机之外访问服务，否则可能只能在容器内部访问。
端口映射怎么配置
ComfyUI默认Web端口通常是8188。本机使用时，启动后打开https://127.0.0.1:8188即可；局域网内其他设备访问时，使用https://宿主机IP:8188。如果8188已被占用，可把宿主机端口改成其他值，例如-p 8288:8188，表示外部访问8288，容器内部仍然是8188。
端口不要随意暴露到公网。ComfyUI本身主要面向工作流操作，并不等同于带完整账号体系的业务系统。如果必须远程使用，建议放在受控网络环境内，至少通过访问控制、登录校验、反向袋里限流和防火墙规则进行保护。不要把包含私有模型、客户素材、未公开工作流的目录挂载到不可信环境中，也不要运行来源不明的节点脚本。
数据目录与模型放置
模型文件通常放在models/checkpoints，VAE放在models/vae，LoRA放在models/loras，ControlNet相关文件放在models/controlnet。不同节点可能还会要求clip、unet、upscale_models等目录。放置文件后，如果页面没有显示新模型，可以在ComfyUI界面刷新模型列表，或重启容器：docker restart comfyui。
输出目录建议定期清理。AI绘画工作流很容易产生大量中间图和高清结果，数十GB增长很常见。团队环境可按日期、项目或用户建立子目录，避免文件混杂。对于重要工作流，建议将JSON工作流文件单独备份，不要只依赖浏览器缓存或输出图片中的元数据。
查看日志、升级与回滚
启动后如果页面打不开，先查看容器状态：docker ps -a，再查看日志：docker logs -f comfyui。常见问题包括镜像未拉取完整、端口被占用、目录权限不足、GPU运行时不可用、模型文件损坏或插件依赖安装失败。Linux目录权限问题可通过调整目录所有者或读写权限解决，但不要为了省事给整个系统目录开放过高权限。
升级前务必备份models、custom_nodes、user和重要工作流。升级流程一般是：停止容器docker stop comfyui，删除旧容器docker rm comfyui，拉取新镜像docker pull ghcr.io/ai-dock/comfyui:latest，再用原来的挂载参数启动。由于数据在宿主机目录中，删除容器不会删除模型和输出。若升级后插件报错，可先回到旧镜像标签，或临时移走最近新增的自定义节点目录排查。
常见问题与实用建议
显卡无法识别时，先在宿主机执行nvidia-smi，再用CUDA测试容器验证Docker GPU支持，不要直接判断是ComfyUI问题。显存不足时，可降低分辨率、批量数量和采样参数，或使用更小的模型。插件安装失败时，优先查看该节点支持的ComfyUI版本和Python依赖，多个插件依赖冲突时，Docker虽然能隔离系统环境，但容器内部仍可能冲突。
新手建议先保持基础镜像稳定，只安装必要节点；每次新增插件后立即重启并测试一个简单工作流，确认无误再继续扩展。团队使用时，应约定模型目录命名规则和版本记录，避免同名不同版本造成结果不一致。对于长期运行的服务，建议监控磁盘空间、显存占用和容器日志大小。Docker部署不是免维护方案，但只要端口、目录、镜像版本和备份策略规划清楚，ComfyUI就能以较低成本稳定运行，成为可复用的AI绘画工作流平台。
