ComfyUI 完整部署与模型管理图文教程：Windows、Linux、节点、工作流与排错
从隔离环境、GPU 依赖、模型目录、额外路径、自定义节点到首个工作流和可复现备份，覆盖新手最常见的全部环节。
它解决什么问题
选择安装方式
Windows NVIDIA 新手优先使用官方 Desktop 或 Portable；需要精确控制依赖、Linux 服务器、AMD/Intel/Apple Silicon 时使用手动安装。官方文档明确说明 ComfyUI 没有官方 Docker 镜像，第三方镜像必须自行承担维护与安全风险。生产服务建议从手动安装开始，并固定代码提交和 Python 依赖。
硬件与软件检查
ComfyUI 支持 Windows、Linux、macOS，GPU 后端取决于 PyTorch。先记录系统、GPU 型号、显存、驱动、Python、Git、磁盘与浏览器版本。模型通常占用数 GB 到数十 GB；视频模型还会产生大量临时文件，因此模型盘应至少保留 20% 空间。CPU 模式可以启动但生成很慢，只适合排错。
隔离 Python 环境
不要把依赖安装进系统 Python。使用 venv 或
Conda 创建独立环境，之后所有 pip、自定义节点依赖和启动命令都在这个环境内执行。官方当前推荐 Python 3.13，遇到自定义节点兼容问题可退回 3.12。GPU PyTorch 安装命令必须以官方最新系统要求页为准，不要混装 CUDA 与 ROCm 包。
模型目录
基础模型放在 models/checkpoints，LoRA 放在 models/loras，VAE 放在 models/vae，ControlNet 放在 models/controlnet，独立扩散模型通常放在 models/diffusion_models。模型文件名要包含模型、版本、精度和来源；旁边保存许可证与下载 URL。把文件放错目录时，Loader 下拉框不会出现它。
共享模型盘
当模型放在扩容盘或与其他 UI 共用时，把 extra_model_paths.yaml.example 复制为 extra_model_paths.yaml，只修改副本。base_path 必须存在，YAML 使用空格缩进，Windows 路径建议使用正斜杠或正确转义。保存后重启 ComfyUI。不要移动 Desktop 自动生成的配置；应在现有配置中追加并先备份。
自定义节点安全
当前 ComfyUI Manager 可管理已登记节点。节点本质上是会在本机执行的 Python/前端代码，可能读取文件或发起网络请求。只装可信作者的节点，检查仓库、许可证和更新记录，固定版本，依赖安装在 ComfyUI 环境。启动日志出现 IMPORT FAILED 时先修复依赖，不要无视错误继续堆节点。
第一个工作流
从内置模板开始，避免一开始导入几十个未知节点的复杂 JSON。选择与模型匹配的模板，确认 Loader 选中正确 checkpoint，设置正向/负向提示词、尺寸、步数、CFG、seed 与保存节点。第一次使用 512 或 768 边长、批量 1、固定 seed。点击 Queue 后检查执行节点顺序、显存和输出目录。
远程访问
默认只在本机监听最安全。局域网或公网使用时，不要直接裸露 ComfyUI 端口；通过反向代理配置 HTTPS、登录、请求大小、速率限制和 IP 策略。自定义节点与上传文件均属于高风险入口。网页服务用户与模型文件应使用最小权限，输出目录设置配额。
更新、快照与回滚
更新前保存核心提交、Python 包列表、节点清单、模型哈希和成功工作流。Portable 使用官方更新脚本；手动安装执行 git pull 后重新安装 requirements.txt。先复制环境或做快照，更新后用固定 seed 工作流回归。节点更新与核心更新分开做，避免同时变化导致无法定位。
常见问题定位顺序
- 启动失败：查看终端第一条异常，而不是最后一行。
- GPU 不可用：在同一环境执行
python -c "import torch; print(torch.cuda.is_available())"。
- 模型不显示：确认目录、扩展名、配置缩进并重启。
- 节点红色或缺失：检查自定义节点仓库与依赖，或换成官方模板。
- CUDA OOM：关闭其他程序、降低尺寸/批量/帧数、使用低显存模式或更小模型。
- 输出全黑/NaN：确认 VAE、模型精度、工作流版本和分辨率约束。
- 更新后坏掉：回滚核心提交或节点快照，再逐项升级。
完成标准
冷启动无红色导入错误；模板能生成并保存；重启后模型仍可识别；固定 seed 可复现；工作流 JSON 可在干净副本加载；模型来源、许可证、版本和哈希有记录；备份可恢复；远程入口有认证与 HTTPS。
安装 / 开始使用
git clone https://github.com/Comfy-Org/ComfyUI.git
cd ComfyUI
python -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\Activate.ps1 # Windows PowerShell
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130
pip install -r requirements.txt
python main.py额外模型路径示例：
aitroys_models:
base_path: /mnt/ai-models
checkpoints: checkpoints
loras: loras
vae: vae
controlnet: controlnet
diffusion_models: diffusion_models自定义节点手动安装后，在该节点目录执行 pip install -r requirements.txt，重启并检查启动日志。公网部署使用反向代理与认证，不直接暴露 8188。