项目定位与目标

ComfyUI 的核心定位是成为一个开源、可扩展、离线运行的 AI 内容生成平台。项目追求以下核心目标：

资料来源：README.md

核心特性

支持的模型类型

ComfyUI 原生支持多种前沿模型架构：

图像生成模型

• Stable Diffusion 系列（SDXL、SD3、SD3.5）
• Flux 系列（Flux Dev/Schnell/Kontext）
• Lumina Image 2.0、HiDream、Qwen Image
• HunyuanDiT、Hunyuan Image 2.1、AuraFlow

图像编辑模型

• Omnigen 2、HiDream E1.1
• Qwen Image Edit、Flux Kontext

视频生成模型

• Stable Video Diffusion、Mochi、LTX-Video
• Hunyuan Video、Wan 2.1、Wan 2.2

音频模型

• Stable Audio 系列

资料来源：README.md

高级功能

graph TD
    A[ComfyUI 核心功能] --> B[Textual Inversion]
    A --> C[Loras Locon/Loha]
    A --> D[Hypernetworks]
    A --> E[ControlNet/T2I-Adapter]
    A --> F[Inpainting]
    A --> G[Upscale Models]
    A --> H[GLIGEN]
    A --> I[Model Merging]
    A --> J[LCM models]
    A --> K[Latent Previews]

资料来源：README.md

系统架构

整体架构图

graph TD
    subgraph 前端层
        A[Web UI Frontend]
        B[Desktop App]
        C[API Endpoints]
    end
    
    subgraph 核心层
        D[Execution Engine]
        E[Node Graph System]
        F[Model Manager]
        G[Frontend Manager]
    end
    
    subgraph 数据层
        H[User Data Store]
        I[Model Storage]
        J[Workflow Files]
    end
    
    subgraph API层
        K[REST API]
        L[WebSocket]
    end
    
    A --> K
    B --> K
    C --> K
    K --> D
    K --> L
    D --> E
    E --> F
    F --> I
    G --> A
    H --> K
    J --> K

核心模块说明

资料来源：comfy/comfy_types/README.md, app/model_manager.py, app/user_manager.py, app/frontend_management.py, api_server/routes/internal/README.md

节点类型系统

ComfyUI 提供强类型的节点开发系统，基于 ComfyNodeABC 抽象基类：

from comfy.comfy_types import IO, ComfyNodeABC, CheckLazyMixin

class ExampleNode(ComfyNodeABC):
    @classmethod
    def INPUT_TYPES(s) -> InputTypeDict:
        return {"required": {}}

内置 IO 类型

资料来源：comfy/comfy_types/README.md

安装与运行

系统要求

基本安装步骤

# 1. 克隆仓库
git clone https://github.com/Comfy-Org/ComfyUI.git

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动程序
python main.py

资料来源：README.md

硬件平台特定安装

NVIDIA GPU

pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130

AMD GPU (ROCm)

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm

Apple Silicon (M1/M2)

# 参考 Apple 官方 PyTorch Metal 加速指南安装 nightly 版本

Intel XPU

pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/xpu

Ascend NPU

需要安装 Ascend Basekit 和 torch-npu，参考 Ascend 安装文档

资料来源：README.md

ComfyUI-Manager 扩展

pip install -r manager_requirements.txt
python main.py --enable-manager

资料来源：README.md

命令行选项

TLS/SSL 配置

# 生成自签名证书
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 3650 -nodes -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname"

# 启动 HTTPS 服务
python main.py --tls-keyfile key.pem --tls-certfile cert.pem

资料来源：README.md

高质量预览配置

TAESD 预览需要下载以下文件到 models/vae_approx 目录：

• taesd_decoder.pth
• taesdxl_decoder.pth
• taesd3_decoder.pth
• taef1_decoder.pth

然后使用 --preview-method taesd 启动。

资料来源：README.md

模型管理

模型文件发现机制

model_manager.py 实现了智能模型文件发现功能，支持以下特性：

# 自动匹配基础名称
# 支持 .preview 后缀预览图
# 支持 safetensors 元数据解析
# Base64 编码的封面图片提取

模型目录结构

models/
├── checkpoints/     # 主模型
├── loras/          # LoRA 模型
├── vae/            # VAE 模型
├── controlnet/     # ControlNet 模型
├── embeddings/     # Textual Inversion embeddings
└── vae_approx/     # TAESD 预览模型

资料来源：app/model_manager.py

用户数据管理

API 路由结构

/v1/userdata 和 /v2/userdata 端点支持以下查询参数：

资料来源：app/user_manager.py, api_server/routes/internal/README.md

前端版本管理

版本检查机制

frontend_management.py 模块负责管理前端包的版本一致性：

def check_frontend_version():
    # 获取已安装的前端版本
    # 获取需要的前端版本
    # 检查版本是否匹配

版本格式: X.Y.Z (语义化版本)

def parse_version(version: str) -> tuple[int, int, int]:
    return tuple(map(int, version.split(".")))

def is_valid_version(version: str) -> bool:
    pattern = r"^(\d+)\.(\d+)\.(\d+)$"
    return bool(re.match(pattern, version))

旧版前端

如需使用旧版前端，可通过命令行指定：

--front-end-version Comfy-Org/ComfyUI_legacy_frontend@latest

资料来源：app/frontend_management.py, README.md

快捷键参考

资料来源：README.md

发布流程

ComfyUI 采用周发布周期，目标是每周一发布新版本。

三个关联仓库

1. ComfyUI Core: 核心引擎和节点系统
2. ComfyUI Frontend: Web 前端界面
3. ComfyUI Manager: 节点管理和安装系统

资料来源：README.md

执行引擎特性

智能执行优化

graph LR
    A[提交工作流] --> B{检查输出是否变化}
    B -->|未变化| C[跳过执行]
    B -->|有变化| D{输入是否完整}
    D -->|完整| E[执行节点]
    D -->|不完整| F[等待上游完成]

执行规则：

1. 只有所有输入正确的节点输出才会被执行
2. 仅执行与上一次执行相比发生变化的节点
3. 连续提交相同工作流时，仅第一次会被执行

资料来源：README.md

离线特性

ComfyUI 的核心模块完全离线运行，不会自动下载任何资源，除非用户明确要求。这种设计使其非常适合：

• 企业内网环境
• 安全敏感的生产环境
• 网络受限的部署场景

可通过可选的 API 节点访问外部付费模型服务。

资料来源：README.md

配置示例

extra_model_paths.yaml

支持通过配置文件设置模型的搜索路径：

# 复制自 extra_model_paths.yaml.example
# 设置模型目录的额外搜索路径

这允许用户复用其他 UI 工具已下载的模型文件。

资料来源：README.md

概述

ComfyUI 是为视觉专业人士打造的最强大、最模块化的 AI 生成引擎，提供对模型、参数和输出的完全控制。其强大的模块化节点图界面使创作者能够生成图像、视频、3D 模型、音频等。资料来源：README.md

ComfyUI 原生支持最新的开源 SOTA 模型，并提供 API 节点以访问 Nano Banana、Seedance、Hunyuan3D 等顶级闭源模型。该平台可在 Windows、Linux 和 macOS 上本地使用，也可通过桌面应用程序或云端访问。资料来源：README.md

安装方式

桌面应用程序

桌面应用程序是入门最简单的方式，支持 Windows 和 macOS 系统。

Windows 便携版

Windows 提供独立的便携式构建版本，适用于 NVIDIA GPU 或仅使用 CPU 运行。资料来源：README.md

手动安装（跨平台）

ComfyUI 支持所有操作系统和 GPU 类型，包括 NVIDIA、AMD、Intel、Apple Silicon 和 Ascend。资料来源：README.md

依赖安装

系统依赖

根据不同的 GPU 类型，需要安装对应的 PyTorch 版本：

#### NVIDIA GPU

安装 stable 版本的 PyTorch：

pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130

如需 nightly 版本（可能有性能提升）：

pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu132

#### AMD GPU (ROCm)

安装 AMD 支持的 PyTorch：

pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/rocm

对于非官方支持的 AMD 显卡，使用以下命令：

#### Apple Mac Silicon

1. 安装 PyTorch nightly，参考 Apple 官方指南
2. 按照 Windows 和 Linux 的手动安装说明操作
3. 安装 ComfyUI 依赖
4. 运行 python main.py 启动

#### Intel GPU (XPU)

安装 PyTorch XPU nightly：

pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/xpu

#### Ascend NPU

1. 安装推荐的或更新的 Linux 内核版本
2. 安装 Ascend Basekit（包含驱动、固件和 CANN）
3. 安装 torch-npu 包
4. 按照 ComfyUI 手动安装说明操作

Python 依赖

安装所有必需的 Python 包：

pip install -r requirements.txt

运行 ComfyUI

安装完成后，通过以下命令启动 ComfyUI：

python main.py

命令行选项

TLS/SSL 配置

生成自签名证书：

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 3650 -nodes -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname"

启动时启用 TLS：

python main.py --tls-keyfile key.pem --tls-certfile cert.pem

高质量预览

使用 TAESD 启用高质量预览：

1. 下载 TAESD decoder 文件：

• taesd_decoder.pth
• taesdxl_decoder.pth
• taesd3_decoder.pth
• taef1_decoder.pth

1. 将文件放入 models/vae_approx 目录

1. 重启 ComfyUI 并使用 --preview-method taesd 启动

模型管理

目录结构

ComfyUI 使用以下目录结构管理模型：

graph TD
    A[ComfyUI Root] --> B[models]
    B --> C[checkpoints]
    B --> D[vae]
    B --> E[lora]
    B --> F[embeddings]
    B --> G[controlnet]
    B --> H[upscale_models]
    B --> I[vae_approx]

外部模型路径配置

通过 extra_model_paths.yaml 配置文件可以设置模型的外部搜索路径，便于复用其他 Stable Diffusion UI 的模型。资料来源：extra_model_paths.yaml.example

配置文件示例：

# 从其他 UI 导入模型路径
a1111:
    base_path: /path/to/stable-diffusion-webui/models
    # 或指定具体子目录
    # checkpoints: checkpoints
    # vae: vae

other_ui:
    base_path: /path/to/other/ui/models

ComfyUI-Manager

ComfyUI-Manager 是一个扩展，可轻松安装、更新和管理自定义节点。资料来源：README.md

安装

``bash pip install -r manager_requirements.txt ``

1. 安装管理器依赖：

``bash python main.py --enable-manager ``

1. 启用管理器：

功能

快捷键

基础操作

选择操作

视图操作

注意：macOS 用户可将 Ctrl 替换为 Cmd。

工作流示例

ComfyUI 支持多种高级功能：

详细示例请参考 ComfyUI Examples。

工作流程执行机制

ComfyUI 的执行优化机制：

graph LR
    A[提交工作流] --> B{检查输出}
    B --> |输入完整| C[执行节点]
    B --> |输入不完整| D[跳过执行]
    C --> E{与上次比较}
    E --> |有变化| F[重新执行]
    E --> |无变化| G[使用缓存]
    F --> H[更新输出]
    G --> H

执行规则

1. 完整性检查：只有所有输入都正确的节点才会被执行
2. 增量执行：仅执行与上次执行相比有变化的部分
3. 缓存机制：提交相同工作流两次，只有第一次会执行
4. 依赖传播：修改工作流的最后部分时，只有修改部分及其依赖部分会重新执行

发布周期

ComfyUI 采用每周发布周期，但会因模型发布或代码库重大变更而调整。

警告：稳定版本标签之外的提交可能非常不稳定，可能导致许多自定义节点失效。

故障排除

Torch CUDA 错误

如果遇到 "Torch not compiled with CUDA enabled" 错误：

pip uninstall torch
# 重新安装（参考上方 NVIDIA GPU 安装命令）
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130

AMD ROCm 性能优化

启用实验性内存高效注意力：

TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1 python main.py --use-pytorch-cross-attention

可选性能优化（首次运行较慢）：

PYTORCH_TUNABLEOP_ENABLED=1 python main.py

概述

ComfyUI 是一个模块化的 AI 创作引擎，采用节点图（Node Graph）架构设计。其核心设计理念是将复杂的 AI 生成流程分解为可复用、可组合的独立节点单元，用户通过可视化界面连接这些节点构建完整的工作流。

系统架构采用分层设计，从底层的张量计算到上层的 Web 服务，各层职责明确，模块间通过清晰定义的接口通信。这种设计使得 ComfyUI 能够支持多种硬件平台（NVIDIA、AMD、Intel、Apple Silicon、Ascend）以及多种 AI 模型类型。

核心架构分层

ComfyUI 的系统架构可以分为以下几个层次：

graph TD
    A[应用层 app] --> B[API层 api_server]
    B --> C[核心层 comfy + comfy_execution]
    C --> D[模型层 comfy_extras]
    D --> E[执行后端 PyTorch/CUDA/ROCm]
    
    A1[前端界面] --> A
    A2[用户管理 user_manager] --> A
    A3[模型管理 model_manager] --> A

核心模块职责

节点类型系统

ComfyUI 的节点系统基于类型化的输入输出设计，核心类型定义位于 comfy/comfy_types/ 模块。

内置数据类型

graph LR
    A[IO 枚举] --> B[基础类型]
    A --> C[特殊类型]
    A --> D[复合类型]
    
    B --> B1[STRING]
    B --> B2[FLOAT]
    B --> B3[INT]
    B --> B4[BOOLEAN]
    
    C --> C1[ANY "*"]
    C --> C2[NUMBER "FLOAT,INT"]
    C --> C3[PRIMITIVE "STRING,FLOAT,INT,BOOLEAN"]
    
    D --> D1[IMAGE]
    D --> D2[MODEL]
    D --> D3[LATENT]

节点基类设计

所有自定义节点应继承自 ComfyNodeABC 抽象基类：

from comfy.comfy_types import IO, ComfyNodeABC, CheckLazyMixin

class ExampleNode(ComfyNodeABC):
    @classmethod
    def INPUT_TYPES(s) -> InputTypeDict:
        return {"required": {}}

资料来源：comfy/comfy_types/README.md

执行引擎架构

图执行模型

ComfyUI 的执行引擎采用懒加载和增量执行策略：

1. 依赖解析：系统分析节点图的依赖关系，构建拓扑排序
2. 条件执行：仅执行所有输入都已就绪的节点
3. 缓存复用：对于相同输入的节点，结果会被缓存复用
4. 增量更新：重新执行时只运行发生变化的节点及其下游节点

graph TD
    A[提交工作流] --> B{检查节点输入}
    B -->|所有输入就绪| C[执行节点]
    B -->|输入缺失| D[跳过执行]
    C --> E{结果缓存}
    E -->|首次执行| F[缓存结果]
    E -->|命中缓存| G[返回缓存]
    F --> H[下游节点执行]
    G --> H
    H --> I[完成输出]

资料来源：README.md

执行流程特点

根据源码分析，ComfyUI 的执行机制具有以下特点：

• 只有图中所有输出都具有正确输入的节点才会被执行
• 只有相比上次执行发生变化的节点及其依赖链会被重新执行
• 连续提交相同的工作流定义，第二次将跳过执行

API 服务架构

服务端路由设计

API 服务层位于 api_server/ 目录，采用分层路由设计：

内部路由规范

所有 /internal 路径下的路由均为 ComfyUI 内部使用，不对外部应用开放，可能在任何版本中发生变更而无另行通知。

资料来源：api_server/routes/internal/README.md

用户数据管理

用户数据管理通过 app/user_manager.py 实现，提供文件系统的安全隔离访问。

文件列表接口

GET /v2/userdata?path=<relative_path>&recurse=<true|false>&full_info=<true|false>&split=<true|false>

安全机制

• 路径验证：所有请求路径必须位于用户数据目录内
• 路径遍历防护：自动阻止 .. 等路径遍历攻击
• 仅返回文件：目录不包含在结果中

资料来源：app/user_manager.py

模型管理

模型文件发现

模型管理器 (app/model_manager.py) 负责模型文件的自动发现和元数据提取：

graph TD
    A[请求模型预览] --> B[查找同名图片]
    A --> C[查找 .preview 后缀图片]
    A --> D[检查 safetensors 元数据]
    B --> E[返回预览图列表]
    C --> E
    D --> F[提取 ssmd_cover_images]
    F --> E

模型预览格式

模型预览支持以下格式：

资料来源：app/model_manager.py

前端资源管理

前端资源通过 app/frontend_management.py 进行版本控制和管理。

版本检查机制

graph TD
    A[启动时检查] --> B{版本匹配?}
    B -->|匹配| C[正常启动]
    B -->|不匹配| D[显示警告]
    D --> E[提示更新前端包]

版本验证规则

版本字符串必须符合语义化版本规范 (X.Y.Z)：

def is_valid_version(version: str) -> bool:
    """Validate if a string is a valid semantic version (X.Y.Z format)."""
    pattern = r"^(\d+)\.(\d+)\.(\d+)$"
    return bool(re.match(pattern, version))

前端切换选项

部署架构

启动入口

ComfyUI 的主入口为 python main.py，支持多种启动参数：

资料来源：README.md

多硬件支持

graph TD
    A[ComfyUI] --> B[PyTorch Backend]
    B --> C[NVIDIA CUDA]
    B --> D[AMD ROCm]
    B --> E[Intel XPU]
    B --> F[Apple Metal]
    B --> G[Ascend NPU]

类型系统详解

输入类型定义

节点的 INPUT_TYPES 返回字典结构：

{
    "required": {
        "input_name": input_definition,
        ...
    },
    "optional": {
        "input_name": input_definition,
        ...
    },
    "hidden": {
        "input_name": input_definition,
        ...
    }
}

输入定义选项

每个输入定义可包含以下属性（通过类型提示获取完整信息）：

• INPUT_TYPES() 返回值自动补全
• 单个输入选项的自动补全
• 返回值类型提示

资料来源：comfy/comfy_types/README.md

总结

ComfyUI 采用现代化的分层架构设计，核心优势包括：

1. 模块化节点设计：通过 ComfyNodeABC 基类提供统一的节点开发接口
2. 高效的执行引擎：懒加载和增量执行减少不必要的计算
3. 灵活的 API 层：内部路由和公共 API 分离，便于扩展
4. 多平台支持：统一的抽象层支持 NVIDIA、AMD、Intel、Apple Silicon、Ascend 等多种硬件
5. 安全的数据访问：用户数据目录隔离，路径遍历防护
6. 版本化管理：前端资源与后端核心分离独立版本控制

概述

ComfyUI 的执行引擎是整个系统的核心组件，负责解析、管理和执行基于节点图的工作流。该引擎采用智能缓存机制，仅执行图中发生变化的部分，从而实现高效的迭代开发体验。执行引擎与工作流系统协同工作，将用户通过可视化界面构建的节点图转换为可执行的任务序列。

ComfyUI 采用模块化的节点架构，每个节点代表一个特定的功能单元，节点之间通过输入输出端口形成数据流连接。工作流执行时，引擎会根据节点之间的依赖关系自动确定执行顺序，确保每个节点在其所有依赖输入可用时才开始执行。

工作流图结构

节点图表示

ComfyUI 的工作流以有向无环图（DAG）结构存储，每个节点包含以下核心属性：

节点类型定义在节点的 INPUT_TYPES 类方法中，描述了节点接受的所有输入类型、默认值和约束条件。

数据流连接

节点之间的数据通过端口连接传递。每个连接包含源节点、源端口、目标节点和目标端口四个要素。当执行引擎处理工作流时，它会沿着这些连接追踪数据流动，确保信息正确地从上游节点传递到下游节点。

执行模型

增量执行机制

ComfyUI 执行引擎实现了智能增量执行策略，这是其核心性能优化特性之一：

1. 变化检测：当用户提交工作流执行时，引擎首先比较当前工作流与上一次执行的差异
2. 影响分析：确定工作流中被修改的部分及其所有下游依赖节点
3. 选择性执行：仅执行必要的节点，保留未受影响节点的缓存结果

这种机制使得用户可以在修改工作流的某个环节后快速获得更新结果，而无需重新执行整个图。资料来源：README.md:变化检测逻辑

执行顺序确定

执行引擎采用拓扑排序算法确定节点的执行顺序。拓扑排序确保每个节点在其所有前驱节点执行完成之前不会开始执行，从而保证数据依赖的正确性。

当工作流中存在并行执行的节点（即没有相互依赖关系的节点）时，引擎会将它们分配到同一批次并行执行，充分利用多核处理器的计算能力。

条件执行

只有当节点的输出端口被其他节点使用时，该输出才会被计算。引擎会自动识别工作流图中实际需要执行的路径，忽略未被引用的分支。这种优化显著减少了不必要的计算开销。

执行流程

graph TD
    A[提交工作流] --> B[验证工作流结构]
    B --> C{与上次工作流比较}
    C -->|完全相同| D[返回缓存结果]
    C -->|存在差异| E[确定脏区域]
    E --> F[拓扑排序]
    F --> G[构建执行批次]
    G --> H[按批次执行节点]
    H --> I[缓存输出结果]
    I --> J{所有批次完成?}
    J -->|否| G
    J -->|是| K[返回最终输出]

缓存系统

节点输出缓存

执行引擎维护一个结果缓存系统，用于存储已执行节点的输出。当工作流被重新提交时，引擎会检查哪些节点的输出可以从缓存中复用：

• 完全匹配：如果节点的输入和参数与上次执行完全相同，则直接使用缓存输出
• 部分变化：只有受变化影响且无法从缓存复用的节点才需要重新执行

缓存键由节点的输入值、参数配置和节点类型共同计算生成，确保缓存的唯一性和正确性。

缓存清理策略

缓存系统会持续监控内存使用情况，当缓存数据量超过配置阈值时，引擎会采用最近最少使用（LRU）策略清理旧条目，释放内存空间供新结果使用。

验证机制

工作流验证

在执行工作流之前，引擎会执行多层次验证：

1. 结构验证：检查节点图是否有断开的连接或循环依赖
2. 类型验证：确认连接的数据类型是否兼容
3. 完整性验证：确保所有必需输入都已连接

输入验证

每个节点类型定义了自己的输入约束条件，包括：

• 数据类型要求（如必须为图像、必须为浮点数等）
• 取值范围限制
• 维度约束（如张量形状要求）

验证失败的节点会阻止工作流执行，并向用户报告具体的错误信息和位置。

节点类型系统

内置类型

ComfyUI 通过 comfy/comfy_types 模块提供了一套类型系统，用于标准化节点间的数据交换：

自定义节点开发

开发者可以通过继承 ComfyNodeABC 抽象基类来创建自定义节点：

from comfy.comfy_types import IO, ComfyNodeABC, CheckLazyMixin

class ExampleNode(ComfyNodeABC):
    @classmethod
    def INPUT_TYPES(s) -> InputTypeDict:
        return {"required": {}}

资料来源：comfy/comfy_types/README.md:节点开发示例

API 与路由

执行端点

ComfyUI 通过 RESTful API 暴露执行功能：

内部路由

部分路由标记为内部使用，仅供 ComfyUI 前端调用，这些路由的实现可能在版本更新时发生变化：

资料来源：api_server/routes/internal/README.md:内部路由说明

性能优化

批处理执行

对于相互独立的节点，引擎会自动将它们批处理并行执行。这种批处理机制能够充分利用硬件的并行计算能力，特别是在处理大量相似操作时效果显著。

内存管理

执行引擎实现了智能内存管理策略：

• 流式处理：对于大型中间结果，采用流式处理避免一次性加载到内存
• 及时释放：节点执行完成后立即释放不再需要的中间数据
• 显存优化：在 NVIDIA GPU 上利用 CUDA 内存管理优化显存使用

配置选项

ComfyUI 提供了多个命令行参数用于调整执行引擎行为：

资料来源：README.md:命令行参数

相关文件结构

ComfyUI/
├── execution.py              # 执行入口
├── comfy_execution/
│   ├── graph.py             # 图结构定义
│   ├── jobs.py              # 任务调度
│   ├── caching.py           # 缓存实现
│   └── validation.py        # 验证逻辑
└── app/
    └── api_server/          # API 路由

1. 模型类型概述

ComfyUI 支持的模型主要分为以下几个大类：

资料来源：README.md

2. 图像生成模型

2.1 主流图像模型

ComfyUI 原生支持最新的开源图像生成模型，包括：

• Stable Diffusion 系列 - 包括 SD 1.5、SD 2.x、SDXL 等
• Flux - 包括 Flux Dev、Flux Schnell 等
• HiDream - 包括 HiDream I1、HiDream E1.1 等
• SDXL - 高分辨率图像生成
• LCM (Latent Consistency Models) - 快速图像生成

2.2 图像编辑模型

资料来源：README.md

2.3 图像生成增强技术

ComfyUI 支持多种图像增强技术：

• Hires Fix - 高分辨率修复，提升生成图像质量
• Inpainting - 局部重绘，支持常规模型和专用修复模型
• Area Composition - 区域构图，多区域组合生成
• Textual Inversion - 文本嵌入自定义概念
• Loras - 支持常规 LoRA、LoCon 和 LoHA
• Hypernetworks - 超网络训练与使用

资料来源：README.md

3. 视频生成模型

ComfyUI 支持多种视频生成模型，覆盖从开源到商业级的解决方案：

3.1 开源视频模型

3.2 商业视频模型

通过 API 节点访问的商业模型：

• Seedance - 商汤视频生成
• Nano Banana - 实验性模型
• Hunyuan3D - 3D 模型生成

资料来源：README.md

4. 音频模型

ComfyUI 支持音频内容的生成与处理：

资料来源：README.md

5. 条件控制模型

5.1 ControlNet

ControlNet 提供对图像生成的精确控制，支持多种条件输入：

• Canny 边缘检测
• Depth Map 深度图
• Pose 姿态估计
• Semantic Segmentation 语义分割
• 更多... 官方示例

5.2 T2I-Adapter

T2I-Adapter 是另一种条件控制方案，与 ControlNet 类似但更轻量。

5.3 GLIGEN

GLIGEN (Grounded Layout-to-Image Generation) 允许基于布局边界框生成图像。

资料来源：README.md

6. 超分辨率模型

ComfyUI 内置多种图像超分辨率模型：

资料来源：README.md

7. 模型合并

ComfyUI 支持模型合并功能，可以将多个模型合并生成新的模型：

• 支持不同的合并策略
• 可以保留多个源模型的特点
• 参考示例：Model Merging

资料来源：README.md

8. Embeddings 和 Loras

8.1 Embeddings

自定义概念可以通过 Embeddings 加载：

将 embedding 文件放入 models/embeddings 目录，即可在 CLIPTextEncode 节点中使用。

8.2 Loras 支持

ComfyUI 支持三种 Lora 类型：

参考示例：LCM models and Loras

资料来源：README.md

9. 模型管理

9.1 模型目录结构

ComfyUI 使用 folder_paths 模块管理模型文件，主要目录包括：

9.2 模型发现机制

模型文件管理器 (ModelFileManager) 负责发现和索引模型文件：

class ModelFileManager:
    def __init__(self) -> None:
        self.cache: dict[str, tuple[list[dict], dict[str, float], float]] = {}

支持以下 API 端点：

• GET /experiment/models - 获取所有模型文件夹
• GET /experiment/models/{folder} - 获取指定文件夹中的所有模型

资料来源：app/model_manager.py

9.3 自定义模型路径

可以通过 extra_model_paths.yaml.example 配置文件设置额外的模型搜索路径，便于与现有工作流集成。

资料来源：README.md

10. 硬件支持

10.1 NVIDIA GPU

推荐使用 CUDA 加速的 PyTorch：

pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130

或使用夜间版本以获得更好的性能：

pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu132

10.2 AMD GPU (ROCm)

AMD GPU 用户可以使用 ROCm 版本的 PyTorch：

pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm6.1

针对特定显卡的兼容性问题，可设置环境变量：

# 对于 6700, 6600 及更早的 RDNA2 显卡：
HSA_OVERRIDE_GFX_VERSION=10.3.0 python main.py

# 对于 AMD 7600 及 RDNA3 显卡：
HSA_OVERRIDE_GFX_VERSION=11.0.0 python main.py

启用实验性内存高效注意力：

TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1 python main.py --use-pytorch-cross-attention

10.3 Apple Silicon

Mac 用户（ M1/M2/M3 ）可使用 Metal 加速的 PyTorch：

1. 安装 PyTorch 夜间版本
2. 按标准流程安装 ComfyUI

10.4 Intel XPU

Intel 显卡用户可使用 XPU 后端：

pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/xpu

10.5 Intel/Ascend NPU

使用 NPU 加速的 PyTorch 版本。

资料来源：README.md

11. 模型执行机制

ComfyUI 采用智能图执行策略：

• 部分执行：只有输出具有所有正确输入的图部分才会被执行
• 增量执行：只有相比上次执行发生变化的图部分才会重新执行
• 缓存机制：相同图提交两次，只有第一次会被执行

这种机制确保了高效的模型利用和快速的迭代工作流。

资料来源：README.md

12. 高质量预览

ComfyUI 支持多种预览方法：

启用高质量预览：

1. 下载 TAESD 解码器文件（taesd_decoder.pth、taesdxl_decoder.pth、taesd3_decoder.pth、taef1_decoder.pth）
2. 放入 models/vae_approx 目录
3. 使用 --preview-method taesd 启动

资料来源：README.md

13. 离线工作

ComfyUI 核心功能完全离线运行：

Works fully offline: core will never download anything unless you want it to.

资料来源：README.md

14. 相关文档链接

• 官方示例集
• ComfyUI Manager - 模型和节点管理扩展
• Comfy API - 商业 API 节点文档

概述

ComfyUI 的模型管理与加载系统负责组织、定位、缓存和加载各类 AI 模型文件（包括检查点模型、LoRA、VAE、ControlNet、嵌入模型等）。该系统采用集中化的路径管理机制，支持自定义模型搜索路径，并通过 HTTP API 提供模型文件的发现和预览功能。

核心职责包括：

• 模型文件的路径解析与目录管理
• 模型元数据读取（特别是 safetensors 格式）
• 模型预览图片提取与缓存
• 运行时模型注册与访问接口

资料来源：app/model_manager.py:1-50

核心组件

ModelFileManager

ModelFileManager 是模型文件管理的核心类，提供模型文件发现、缓存和元数据提取功能。

class ModelFileManager:
    def __init__(self) -> None:
        self.cache: dict[str, tuple[list[dict], dict[str, float], float]] = {}

    def get_cache(self, key: str, default=None) -> tuple[list[dict], dict[str, float], float] | None:
        return self.cache.get(key, default)

    def set_cache(self, key: str, value: tuple[list[dict], dict[str, float], float]):
        self.cache[key] = value

    def clear_cache(self):
        self.cache.clear()

缓存机制

缓存数据结构为 tuple[list[dict], dict[str, float], float]，包含三个元素：

资料来源：app/model_manager.py:32-46

模型预览与元数据处理

ModelFileManager 支持从 safetensors 文件中提取嵌入的预览图片和元数据：

if safetensors_file:
    safetensors_filepath = os.path.join(dirname, safetensors_file)
    header = comfy.utils.safetensors_header(safetensors_filepath, max_size=8*1024*1024)
    if header:
        safetensors_metadata = json.loads(header)

safetensors_images = safetensors_metadata.get("__metadata__", {}).get("ssmd_cover_images", None)
if safetensors_images:
    safetensors_images = json.loads(safetensors_images)
    for image in safetensors_images:
        result.append(BytesIO(base64.b64decode(image)))

处理流程

graph TD
    A[查找同名 .safetensors 文件] --> B{文件存在?}
    B -->|是| C[读取文件头 max 8MB]
    B -->|否| D[仅返回 image 文件]
    C --> E{解析 JSON 元数据}
    E -->|成功| F[提取 ssmd_cover_images]
    E -->|失败| D
    F --> G[Base64 解码图片]
    G --> H[返回预览图片流]

资料来源：app/model_manager.py:54-73

API 端点

ComfyUI 通过 aiohttp 提供模型相关的 REST API。

实验性端点

以下端点为实验性功能，用于探索新的模型管理接口：

#### GET /experiment/models

获取所有模型文件夹类型列表。

@routes.get("/experiment/models")
async def get_model_folders(request):
    model_types = list(folder_paths.folder_names_and_paths.keys())
    folder_black_list = ["configs", "custom_nodes"]
    output_folders: list[dict] = []
    for folder in model_types:
        if folder in folder_black_list:
            continue
        output_folders.append({"name": folder, "folders": folder_paths.get_folder_paths(folder)})
    return web.json_response(output_folders)

响应格式

[
  {
    "name": "checkpoints",
    "folders": ["/path/to/models/checkpoints"]
  },
  {
    "name": "loras",
    "folders": ["/path/to/models/loras"]
  }
]

资料来源：app/model_manager.py:49-60

#### GET /experiment/models/{folder}

获取指定文件夹中的所有模型文件。

路径参数

资料来源：app/model_manager.py:62-65

模型存储结构

ComfyUI 采用规范的目录结构管理不同类型的模型文件：

graph TD
    A[models/] --> B[checkpoints/]
    A --> C[loras/]
    A --> D[vae/]
    A --> E[controlnet/]
    A --> F[embeddings/]
    A --> G[upscale_models/]
    A --> H[vae_approx/]
    A --> I[custom_nodes/]
    
    B --> B1[.ckpt, .safetensors]
    C --> C1[.safetensors]
    F --> F1[.pt, .bin]
    H --> H2[taesd_decoder.pth]

嵌入模型使用

嵌入模型放置在 models/embeddings 目录后，可在 CLIPTextEncode 节点中通过前缀引用：

embedding:embedding_filename.pt

注意：扩展名 .pt 可省略。

资料来源：README.md:1-5

预览图片生成

TAESD 高质量预览

ComfyUI 支持使用 TAESD (Temporal Audio Encoding Super Resolution for Diffusion) 实现高质量的潜在空间预览。

安装步骤

1. 下载以下文件到 models/vae_approx 目录：

• taesd_decoder.pth
• taesdxl_decoder.pth
• taesd3_decoder.pth
• taef1_decoder.pth

1. 使用 --preview-method taesd 参数启动

命令行配置

python main.py --preview-method taesd

资料来源：README.md:7-15

模型路径配置

ComfyUI 支持通过配置文件自定义模型搜索路径。配置文件模板位于仓库根目录：

extra_model_paths.yaml.example

该配置允许用户：

• 设置额外的模型搜索目录
• 共享其他 Stable Diffusion UI 的模型目录
• 避免重复下载相同模型

资料来源：README.md:1-5

相关模型类型

ComfyUI 原生支持多种模型类型：

高级功能支持

• Textual Inversion（文本反转）
• LoRA（regular、locon、loha）
• Hypernetworks（超网络）
• ControlNet 和 T2I-Adapter
• GLIGEN
• 模型合并
• LCM 模型和 Lora
• 潜在预览（TAESD）

资料来源：README.md:1-5

与其他模块的关系

graph LR
    A[model_manager.py] --> B[folder_paths]
    A --> C[comfy/utils]
    D[API Routes] --> A
    E[前端] --> D
    F[comfy/model_management] --> A
    
    C --> C1[safetensors_header]
    B --> B1[get_folder_paths]

• folder_paths：提供模型目录路径解析
• comfy/utils：提供 safetensors 文件头读取工具
• API Routes：暴露模型发现接口给前端

最佳实践

1. 模型组织：将不同类型的模型放置在对应目录，便于 ComfyUI 自动识别
2. 使用 safetensors：优先使用 safetensors 格式，可自动提取预览图片
3. 预览性能：如需高质量预览，安装 TAESD 解码器文件
4. 共享配置：多用户环境下使用 extra_model_paths.yaml 共享模型目录
5. 离线工作：核心功能完全离线运行，不会自动下载任何内容

概述

ComfyUI 的文本编码器系统是将自然语言提示词（Prompt）转换为神经网络可处理的数值向量的核心模块。该系统支持多种文本编码架构，包括 CLIP、T5 等，并提供了灵活的节点接口供工作流调用。文本编码器生成的向量表示直接决定了生成内容的语义准确性，是图像、视频、音频等多模态生成任务的关键环节。

架构设计

核心组件

ComfyUI 的文本编码器系统由以下核心模块组成：

系统流程图

graph TD
    A[用户输入 Prompt] --> B[CLIPTextEncode 节点]
    B --> C[文本预处理与分词]
    C --> D[CLIP模型编码]
    D --> E[条件向量 embedding]
    E --> F[扩散模型去噪]
    G[负向提示词 Negative] --> H[负面条件向量]
    E --> F
    H --> F
    F --> I[生成图像]

CLIPTextEncode 节点

功能说明

CLIPTextEncode 是ComfyUI工作流中最常用的文本编码节点，负责将输入的文本提示词转换为条件向量。每个工作流通常包含正向提示词的编码节点和负向提示词的编码节点。

使用方式

在 CLIPTextEncode 节点中使用嵌入文件时，可通过以下语法引用：

embedding:embedding_filename.pt

其中 .pt 扩展名可以省略。资料来源：README.md:1

节点输入输出

支持的文本编码模型

Stable Diffusion 1.x 系列

SD1.x 系列使用单 CLIP 编码器架构，采用 openai/clip-vit-large-patch14 预训练权重。该编码器将文本转换为 768 维的向量表示。资料来源：comfy/sd1_clip.py

Stable Diffusion XL 系列

SDXL 系列采用双 CLIP 编码器设计，包含：

• CLIP-L：与 SD1.x 类似的 ViT-L/14 编码器，输出 768 维向量
• CLIP-G：更大的 ViT-g/14 编码器，输出 1280 维向量

两个编码器的输出通过融合层合并，生成最终的条件向量。资料来源：comfy/sdxl_clip.py

Flux 系列

Flux 模型采用更先进的文本编码方案，支持更长的上下文长度和更精细的语义理解。

分词器与词汇表

分词过程

文本编码器系统的工作流程如下：

graph LR
    A[原始文本] --> B[词汇表匹配]
    B --> C[分词 tokenization]
    C --> D[添加特殊标记]
    D --> E[Padding/截断]
    E --> F[转换为ID序列]
    F --> G[Embedding查找]
    G --> H[Transformer编码]
    H --> I[条件向量输出]

特殊标记

系统支持以下特殊标记格式：

与注意力机制的集成

交叉注意力机制

文本编码器输出的条件向量通过交叉注意力（Cross Attention）机制与图像特征进行交互。在 comfy/ldm/modules/attention.py 中实现了关键的注意力计算逻辑。资料来源：comfy/ldm/modules/attention.py

注意力计算流程

graph TD
    A[图像特征 Query] --> D[注意力计算]
    B[文本向量 Key] --> D
    C[文本向量 Value] --> D
    D --> E[注意力权重矩阵]
    E --> F[加权求和]
    F --> G[特征增强]

嵌入管理与加载

嵌入文件位置

ComfyUI 在以下目录管理文本嵌入文件：

models/embeddings/

嵌入格式支持

系统支持以下嵌入文件格式：

从图片元数据加载

系统支持从 PNG、WebP、FLAC 等图片文件的元数据中提取工作流信息，包括文本编码器相关的配置和嵌入数据。资料来源：README.md:1

类型定义与接口

ComfyUI 提供了 ComfyNodeABC 抽象基类用于节点开发，文本编码器节点可通过继承该基类实现类型安全的开发：

from comfy.comfy_types import IO, ComfyNodeABC, CheckLazyMixin

class ExampleTextEncoder(ComfyNodeABC):
    @classmethod
    def INPUT_TYPES(s) -> InputTypeDict:
        return {"required": {}}

资料来源：comfy/comfy_types/README.md

配置与优化

命令行选项

文本编码器系统可通过以下命令行参数进行配置：

性能优化

系统采用惰性加载机制，仅在需要时才初始化文本编码器模型，以减少内存占用和启动时间。资料来源：comfy/comfy_types/README.md

常见问题排查

编码器加载失败

如果遇到文本编码器无法加载的问题，请检查：

1. 模型文件是否完整下载并放置在正确目录
2. PyTorch 是否正确安装并支持 CUDA（如使用GPU）
3. 依赖包版本是否满足 requirements.txt 要求

内存优化

对于显存有限的环境，可考虑：

• 使用量化后的CLIP模型
• 减少同时加载的编码器数量
• 利用系统的执行优化：仅执行图中输入完整的节点

相关文档

• 工作流示例
• LoRA与文本反转
• ControlNet与文本条件

概述

ComfyUI 的节点系统是整个工作流引擎的核心，它采用模块化的图（Graph）结构来定义和管理 AI 生成任务。每个节点（Node）代表一个具体的计算单元，通过输入/输出端口与其他节点连接，形成完整的工作流程。

ComfyUI 的节点系统具备以下核心特性：

• 类型安全：提供强类型输入/输出定义
• 懒执行：仅执行图中需要计算的部分
• 热重载：支持自定义节点的动态加载
• 可扩展性：允许通过自定义节点扩展功能

资料来源：comfy/comfy_types/README.md:1-15

节点类型层级

ComfyUI 的节点类型采用层级化的组织结构：

graph TD
    A[ComfyNodeABC] --> B[基础节点]
    A --> C[图像处理节点]
    A --> D[模型加载节点]
    A --> E[条件节点]
    B --> F[Latent 节点]
    B --> G[VAE 编解码节点]

核心基类：ComfyNodeABC

ComfyNodeABC 是所有节点的基础抽象类，提供统一的接口定义和类型提示支持。

class ExampleNode(ComfyNodeABC):
    @classmethod
    def INPUT_TYPES(s) -> InputTypeDict:
        return {"required": {}}

资料来源：comfy/comfy_types/README.md:10-15

内置数据类型

ComfyUI 提供以下内置数据类型：

资料来源：comfy/comfy_types/README.md:20-25

输入类型系统

INPUT_TYPES 结构

每个节点必须定义 INPUT_TYPES 类方法，返回值包含以下键：

{
    "required": {},    # 必需输入
    "optional": {},    # 可选输入
    "hidden": {}       # 隐藏输入
}

输入选项配置

节点开发者可以为每个输入定义详细选项：

资料来源：comfy/comfy_types/README.md:35-45

子图系统

ComfyUI 支持将多个节点封装为子图（Subgraph），便于工作流的复用和模块化管理。

graph TD
    A[子图入口] --> B[子节点1]
    A --> C[子节点2]
    B --> D[子图出口]
    C --> D

子图数据结构

class SubgraphEntry(TypedDict):
    source: str           # 来源：custom_node 或 templates
    path: str             # 相对路径
    name: str             # 子图文件名
    info: dict            # 附加信息
    data: str              # 子图数据

资料来源：app/subgraph_manager.py:15-35

子图来源

资料来源：app/subgraph_manager.py:10-14

模型管理与节点集成

ComfyUI 的模型管理器与节点系统紧密集成，负责处理模型文件的发现、加载和缓存。

模型文件匹配逻辑

# 模型加载节点会根据 basename 匹配以下文件：
# - basename.png / jpg / webp
# - basename.safetensors
# - basename_preview.png (预览图)

资料来源：app/model_manager.py:35-55

Safetensors 元数据

支持从 .safetensors 文件中读取嵌入的元数据和封面图像：

safetensors_metadata = json.loads(header)
safetensors_images = safetensors_metadata.get("__metadata__", {}).get("ssmd_cover_images", None)

资料来源：app/model_manager.py:50-55

节点执行模型

懒执行机制

ComfyUI 采用懒执行（Lazy Execution）策略：

只有当节点的输出端口连接了其他节点且所有必需输入都就绪时，该节点才会被执行。

执行优化规则

资料来源：README.md:执行相关说明

自定义节点开发

基础模板

from comfy.comfy_types import IO, ComfyNodeABC, CheckLazyMixin

class MyCustomNode(ComfyNodeABC, CheckLazyMixin):
    @classmethod
    def INPUT_TYPES(s) -> InputTypeDict:
        return {
            "required": {
                "model": ("MODEL",),
                "clip": ("CLIP",),
            },
            "optional": {
                "vae": ("VAE",),
            }
        }
    
    RETURN_TYPES = ("MODEL",)
    FUNCTION = "process"
    CATEGORY = "custom"
    
    def process(self, model, clip, vae=None):
        # 处理逻辑
        return (processed_model,)

类型提示支持

Visual Studio Code 等 IDE 可为 INPUT_TYPES 提供自动补全：

def INPUT_TYPES(s) -> InputTypeDict:
    # IDE 会提示正确的类型和结构

资料来源：comfy/comfy_types/README.md:25-40

常见节点类型

扩展节点集

comfy_extras 模块提供了额外的节点类型，包括但不限于：

• 高级采样器算法
• 图像增强工具
• 额外的模型格式支持
• 性能优化工具

总结

ComfyUI 的节点系统采用清晰的抽象层级设计，通过 ComfyNodeABC 基类提供统一的开发接口。类型系统确保了节点间的数据传递安全，而子图机制则支持复杂工作流的模块化管理。懒执行模型和增量更新策略保证了大规模工作流的高效运行。

概述

ComfyUI 中的工作流模板（Workflow Templates）和 Blueprints 是用于标准化、可复用和快速部署 AI 生成工作流的机制。这些功能使用户能够保存复杂的工作流配置，并在不同环境或用户之间轻松共享。

Blueprints 是 ComfyUI 系统中模板的核心实现方式，它们以结构化格式定义工作流的节点图、参数配置和资源路径。资料来源：app/frontend_management.py:1-1

核心概念

工作流模板的架构

ComfyUI 的工作流模板系统包含以下几个关键组件：

模板资源映射机制

ComfyUI 通过 template_asset_map() 方法维护模板资产名称到绝对路径的映射关系。资料来源：app/frontend_management.py:70-90

def template_asset_map(cls) -> Optional[Dict[str, str]]:
    """Return a mapping of template asset names to their absolute paths."""
    try:
        from comfyui_workflow_templates import (
            get_asset_path,
            iter_templates,
        )
    except ImportError:
        logging.error(...)
        return None

工作流模板包

comfyui_workflow_templates 包

工作流模板通过独立的 pip 包 comfyui_workflow_templates 分发，与 ComfyUI 核心代码分离管理。资料来源：app/frontend_management.py:74-85

comfyui_workflow_templates/
├── templates/           # 模板定义文件
├── assets/             # 关联资源（图像、配置等）
└── __init__.py         # 包入口

模板资产解析流程

graph TD
    A[用户选择模板] --> B[加载模板元数据]
    B --> C{检查资产可用性}
    C -->|资产存在| D[解析资产路径]
    C -->|资产缺失| E[记录错误日志]
    D --> F[构建完整工作流]
    F --> G[前端渲染节点图]

Blueprints 系统

Blueprints 目录结构

Blueprints 存储在仓库根目录的 blueprints 文件夹中，包含以下子目录：

GLSL 集成

ComfyUI 的 Blueprints 系统支持 GLSL 着色器，这些着色器通过 comfy_extras/nodes_glsl.py 模块与节点系统集成。资料来源：comfy_extras/nodes_glsl.py

GLSL 着色器允许在 Blueprints 中实现自定义图像处理和特效节点。

模板管理 API

模板版本检查

ComfyUI 实现了模板包的版本验证机制：资料来源：app/frontend_management.py:30-45

def check_frontend_version():
    """Check if the frontend version is up to date."""
    try:
        frontend_version_str = get_installed_frontend_version()
        frontend_version = parse_version(frontend_version_str)
        required_frontend_str = get_required_frontend_version()

版本解析规则

资料来源：app/frontend_management.py:20-30

工作流保存与加载

文件格式支持

ComfyUI 支持多种工作流保存格式：资料来源：README.md:1-1

用户数据管理

工作流模板与用户数据通过 UserManager 类管理，支持多用户环境：资料来源：app/user_manager.py:1-30

class UserManager():
    def __init__(self):
        user_directory = folder_paths.get_user_directory()
        self.settings = AppSettings(self)

ComfyUI-Manager 集成

ComfyUI-Manager 扩展提供了模板和工作流的安装、更新、管理功能：资料来源：README.md:ComfyUI-Manager

启用方式

python main.py --enable-manager

管理功能

类型系统与节点定义

ComfyNodeABC 基类

工作流模板中的节点通过 ComfyNodeABC 抽象基类定义：资料来源：comfy/comfy_types/README.md:1-20

from comfy.comfy_types import IO, ComfyNodeABC, CheckLazyMixin

class ExampleNode(ComfyNodeABC):
    @classmethod
    def INPUT_TYPES(s) -> InputTypeDict:
        return {"required": {}}

输入类型定义

资料来源：comfy/comfy_types/README.md:10-25

最佳实践

模板开发建议

1. 版本锁定：在模板元数据中明确依赖的包版本
2. 资源封装：将模板相关资源打包在同一目录结构下
3. 路径相对化：使用相对路径确保模板可移植性
4. 节点验证：确保所有依赖节点已安装或提供安装指引

性能考虑

• 模板加载时会检查资产完整性，应提前验证资源可用性
• 大型模板建议使用增量加载机制
• GLSL 着色器应进行预编译验证

故障排除

常见问题

诊断命令

# 检查模板包版本
pip show comfyui-workflow-templates

# 验证蓝图目录
ls -la blueprints/

# 检查前端包依赖
python -c "from app.frontend_management import check_frontend_version; check_frontend_version()"

总结

ComfyUI 的工作流模板与 Blueprints 系统提供了强大的工作流复用和分享能力。通过模块化的模板设计、独立的资源管理和灵活的节点类型系统，用户可以高效地构建、分享和部署复杂的 AI 生成工作流。Blueprints 作为模板的核心实现，结合 GLSL 着色器支持和类型安全的节点定义，为高级用户和开发者提供了极大的灵活性。

概述

ComfyUI 的服务器与 API 接口系统是整个框架的核心通信层，负责处理客户端请求、管理用户会话、提供模型访问、管理工作流执行以及前端资源分发。该系统基于 aiohttp 异步 Web 框架构建，支持高性能并发请求处理，同时提供 TLS/SSL 加密传输能力。

ComfyUI 的架构采用前后端分离设计，后端服务器负责处理业务逻辑和模型管理，前端通过 RESTful API 与之通信。所有核心功能都通过 HTTP/HTTPS 接口暴露，供前端界面、第三方工具和自动化脚本调用。

架构设计

系统组件架构

ComfyUI 的服务器系统由多个协同工作的模块组成：

graph TD
    A[客户端/前端] -->|HTTP/HTTPS| B[API Server]
    B --> C[用户管理 UserManager]
    B --> D[模型管理 ModelFileManager]
    B --> E[前端管理 FrontendManagement]
    B --> F[内部路由 Internal Routes]
    C --> G[AppSettings]
    D --> H[folder_paths]
    B --> I[Comfy API]
    I --> J[protocol.py]

服务启动流程

服务器在启动时执行以下初始化步骤：

1. 解析命令行参数和配置文件
2. 初始化文件夹路径管理系统
3. 加载用户设置和用户目录
4. 注册所有 API 路由
5. 配置中间件和安全策略
6. 启动 aiohttp Web 服务器

API 服务器核心

服务入口

服务器主入口文件 server.py 负责初始化和启动整个 Web 服务。该文件定义了应用的生命周期管理、路由注册和请求处理逻辑。

API 服务器支持以下启动方式：

python main.py

路由注册机制

API 服务器采用模块化路由注册方式，不同功能模块通过 add_routes() 方法注册自己的路由：

TLS/SSL 配置

ComfyUI 支持通过 TLS/SSL 加密通信以确保数据传输安全。要启用 HTTPS，需要提供证书和私钥文件：

证书生成命令：

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 3650 -nodes -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname"

启动参数：

python main.py --tls-keyfile key.pem --tls-certfile cert.pem

启用后，服务将通过 https://... 协议访问。

用户管理模块

UserManager 类

用户管理模块 (app/user_manager.py) 负责管理用户数据和会话状态。在单用户模式下，系统使用默认用户配置；在多用户模式下，支持完整的用户隔离和管理功能。

用户目录结构

用户数据存储在专用目录中，通过 folder_paths.get_user_directory() 获取。首次启动时，如果目录不存在，系统会自动创建。

API 端点

#### 列出用户数据

端点： GET /v2/userdata

查询参数：

返回值：

# full_info = false 时返回
str | list[str]  # 文件路径或路径数组

# full_info = true 时返回
FileInfo: {
    "path": str,      # 相对路径
    "size": int,      # 文件大小（字节）
    "modified": int,  # 修改时间（毫秒时间戳）
    "created": int    # 创建时间（毫秒时间戳）
}

错误码：

• 400：请求路径无效、超出用户数据目录范围或路径不是目录
• 404：请求路径不存在

多用户支持

启用多用户模式需要在启动时添加 --multi-user 参数：

python main.py --multi-user

在此模式下，用户数据相互隔离，每个用户拥有独立的工作流、设置和历史记录。

模型管理模块

ModelFileManager 类

模型管理模块 (app/model_manager.py) 提供对模型文件的访问和管理功能。该模块实现了模型目录浏览、模型元数据读取和模型预览图片获取等功能。

实验性模型路由

#### 获取模型文件夹列表

端点： GET /experiment/models

响应示例：

[
  {
    "name": "checkpoints",
    "folders": ["/path/to/models/checkpoints"]
  },
  {
    "name": "loras",
    "folders": ["/path/to/models/loras"]
  }
]

#### 获取特定文件夹中的所有模型

端点： GET /experiment/models/{folder}

模型预览机制

ModelFileManager 支持多种模型预览格式，包括：

• 与模型同名的 .preview.png 文件
• SafeTensor 格式嵌入的封面图片（存储在 __metadata__.ssmd_cover_images 中）

当查询模型时，系统会自动收集并返回相关的预览资源。

缓存机制

模型管理模块实现了内存缓存以提高性能：

class ModelFileManager:
    def __init__(self) -> None:
        self.cache: dict[str, tuple[list[dict], dict[str, float], float]] = {}

    def clear_cache(self):
        self.cache.clear()

缓存键基于模型路径和查询参数，缓存内容包含文件列表、修改时间和元数据。

前端管理模块

FrontendManagement 类

前端管理模块 (app/frontend_management.py) 负责 ComfyUI 前端资源的分发和版本管理。

前端版本检查

系统会自动检查已安装的前端包版本是否与要求匹配：

def check_frontend_version():
    frontend_version_str = get_installed_frontend_version()
    required_frontend_str = get_required_frontend_version()
    # 版本比较逻辑...

版本不匹配时会输出警告信息，提示用户更新前端包。

前端路径管理

前端静态文件存储在 pip 包 comfyui_frontend_package 中，系统通过 importlib.resources 动态定位资源路径。

工作流模板

系统支持工作流模板功能，模板文件存储在 comfyui_workflow_templates 包中：

def template_asset_map(cls) -> Optional[Dict[str, str]]:
    from comfyui_workflow_templates import get_asset_path, iter_templates
    # 返回模板资源名称到绝对路径的映射

ComfyUI-Manager 扩展

简介

ComfyUI-Manager 是一个可选扩展，用于简化自定义节点的安装、更新和管理。

安装与启用

``bash pip install -r manager_requirements.txt ``

1. 安装依赖：

``bash python main.py --enable-manager ``

1. 启用管理器：

管理器相关参数

API 协议

protocol.py

protocol.py 文件定义了 ComfyUI 的通信协议规范，包括消息格式、请求/响应结构等内部协议细节。

OpenAPI 规范

ComfyUI 提供完整的 OpenAPI 规范文档 (openapi.yaml)，定义了所有公开 API 的结构、参数和响应格式。该规范可用于：

• 生成客户端 SDK
• 自动化 API 测试
• 文档自动生成

执行模型

图执行策略

ComfyUI 的图执行采用增量计算策略：

1. 部分执行：只有输出端具有所有正确输入的图部分才会被执行
2. 变更检测：仅执行与上次执行相比发生变化的节点
3. 依赖追踪：自动追踪节点间的数据依赖关系

graph LR
    A[提交工作流] --> B{检测变更}
    B -->|无变更| C[跳过执行]
    B -->|部分变更| D[执行变更节点及依赖]
    B -->|完整变更| E[执行全部节点]

工作流持久化

系统支持通过 API 保存和加载工作流：

• 支持的工作流格式：JSON
• 支持嵌入元数据的图片格式：PNG、WebP、FLAC

脚本示例

script_examples 目录包含与 API 交互的示例脚本，可供参考学习 API 的使用方法。

安全考虑

内部路由

所有位于 /internal 路径下的路由仅供 ComfyUI 内部使用，可能在任何版本中变更而无需提前通知。外部应用不应依赖这些端点。

路径遍历防护

API 服务器实现了路径遍历防护机制，用户数据请求被限制在用户目录范围内，防止越权访问。

异步安全

服务器采用 aiohttp 异步框架，所有 I/O 操作均为非阻塞，支持高并发连接。

命令行参数汇总

参考资料

• ComfyUI 官方文档与 README.md
• 各模块源码文件中的内联文档和类型定义

Pitfall Log / 踩坑日志

项目：Comfy-Org/ComfyUI

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 comfyui 与安装入口 comfy-cli 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令：pip install comfy-cli
• 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：identity.distribution | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | repo=comfyui; install=comfy-cli

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | last_activity_observed missing

4. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | release_recency=unknown