ComfyUI 核心架构与执行引擎

ComfyUI 是一个模块化的 AI 内容创作引擎,其核心采用节点图（Node Graph）驱动的执行模型。整套系统由 Python 后端与外部前端包（comfyui-frontend-package）共同组成,后端负责节点注册、工作流调度、模型加载与推理执行,前端负责图形化编辑。本页聚焦后端核心架构与执行引擎的工作机制。

整体架构概览

ComfyUI 后端的启动入口是 main.py,它解析命令行参数后调用 server.py 启动基于 aiohttp 的异步 HTTP/WebSocket 服务。HTTP 端点负责接收前端发来的工作流 API(/prompt)、查询队列状态、获取节点元数据等;WebSocket 通道则向前端推送执行进度与预览图像。资料来源：main.py:1-50、server.py:1-80。

flowchart LR
    FE[前端 ComfyUI_frontend] -- HTTP/WS --> SRV[server.py]
    SRV --> EXE[execution.py]
    EXE --> GRAPH[comfy_execution/graph.py]
    EXE --> CACHE[comfy_execution/caching.py]
    EXE --> NODES[nodes.py 节点注册表]
    NODES --> CUSTOM[custom_nodes 目录]
    EXE --> MM[comfy.model_management 显存/内存管理]
    MM --> GPU[NVIDIA/AMD/Apple/Ascend 后端]

上图展示了请求从浏览器到 GPU 执行的完整路径:前端提交工作流 JSON → server.py 入队 → execution.py 调度 → graph.py 拓扑排序 → nodes.py 调用算子 → model_management 协调显存 → 推理完成后再经 WebSocket 回流到前端。

节点系统与工作流描述

节点（Node）是 ComfyUI 最小的功能单元,每个节点通过 INPUT_TYPES() 声明输入与输出,并实现 FUNCTION 指向的 Python 调用。所有节点（包括核心节点与第三方 custom_nodes）在启动时由 nodes.py 扫描并注册到全局字典中,前端通过 /object_info 端点拉取这些元数据来动态构建节点面板。资料来源：nodes.py:1-120。

工作流（Workflow）是一张有向无环图,JSON 格式中每个条目形如:

类型契约由 comfy_api/latest/_io_public.py 通过 IO 字符串枚举与 ComfyNodeABC 抽象基类对外提供,确保跨节点、跨 custom_node 的类型一致。资料来源：comfy/comfy_types/README.md:1-40。

执行引擎与缓存

执行引擎的核心位于 execution.py。当用户点击"Queue Prompt"后,服务端将工作流入队(PromptQueue),工作线程取出后调用 execute() 流程,大致步骤为:

1. 拓扑校验:借助 comfy_execution/graph.py 中的 Graph 类构建图、检测环路、确定执行层级。资料来源：comfy_execution/graph.py:1-100。
2. 缓存命中判断:对每个节点计算缓存键,优先复用上次执行结果以避免重复推理。该机制由 comfy_execution/caching.py 中的 HierarchicalCache、LRUCache 等策略实现。资料来源：comfy_execution/caching.py:1-90。
3. 节点调用:缓存未命中时,通过 nodes.py 查表得到 Python 类,实例化并传入上游输出(以 torch.Tensor 或 ComfyUI 内部数据对象表示),执行 FUNCTION。
4. 进度与预览推送:每个节点执行后将状态写入执行上下文,由 PromptServer 通过 WebSocket 推送到前端,实现实时进度条与潜在空间预览图。

社区中常见的 LTX-Video "OOM after commit 0a2dd86" 问题(Issue #14126)即与执行引擎调度顺序和缓存键的微小变化相关,提示我们在跨版本升级工作流时需留意执行顺序的潜在差异。资料来源：execution.py:1-200。

模型管理与硬件后端

节点在执行时往往需要加载数十 GB 的模型权重,显存管理是 ComfyUI 的另一关键支柱,由 comfy.model_management 模块承担。它会探测当前硬件(通过 torch.cuda、torch.backends.mps、ROCm、Intel XPU、Ascend NPU 等),决定采用以下策略:

• NORMAL / HIGH_VRAM:模型常驻显存,适用于消费级与专业级显卡。
• LOW_VRAM / NO_VRAM:分块加载与 CPU 卸载,适用于显存不足场景。
• CPU:纯 CPU 推理,作为兜底。

AMD APU 用户在 Issue #14274 中反馈 Radeon 890M 的 GTT 共享内存被误判为 VRAM 而触发 gpu-only 压力,正体现了 model_management 中显存探测对硬件细节的敏感性。类似地,ROCm 平台在 bf16 下出现 NaN 的问题(Issue #14249)也属于执行引擎在特定数值精度与硬件后端组合下的边界 case,可通过 --force-fp32 等参数规避。资料来源：comfy/model_management.py:1-150。

前端资源由 app/frontend_management.py 负责加载,默认从 comfyui-frontend-package 导入编译后的 JS,亦可通过 --front-end-version Comfy-Org/ComfyUI_frontend@latest 切换到每日构建版本。资料来源：app/frontend_management.py:1-100、README.md:120-160。

常见失败模式与排障思路

排障时建议先按 官方指引 禁用 custom_nodes 复现,再结合日志中的 execute() 栈、缓存键哈希与模型管理器的显存报告,定位到具体模块。

See Also

• Node Replace Manager — 节点替换与版本迁移
• Subgraph Manager — 子图(Blueprint)管理
• Frontend Package Integration — 前端包加载与版本切换
• Comfy Types Reference — 节点类型系统

概述

ComfyUI 围绕"模型即资产"的设计理念，将模型文件管理、设备与内存分配、用户/设置持久化以及自定义节点扩展统一纳入运行时基础设施。在文件层面，ModelFileManager 提供基于缓存的扫描和实验性 REST 路由；在节点生态层面，SubgraphManager 与 NodeReplaceManager 共同支持子图发现与节点替换；在模型结构层面，潜在扩散（Latent Diffusion）架构的 Autoencoder 与 UNet 配置定义于 models/configs/v2-inference-v.yaml 中，并由 comfy/ldm/models/autoencoder.py 中的 AbstractAutoencoder 与正则化器实现。

graph LR
    MM[ModelFileManager] -->|cache + scan| FP[folder_paths]
    MM -->|/experiment/models| API[REST 路由]
    UM[UserManager] --> AS[AppSettings]
    UM --> UD[用户目录]
    SM[SubgraphManager] --> CN[custom_nodes]
    SM --> TP[templates]
    NRM[NodeReplaceManager] --> NR[NodeReplace 映射]
    AE[AbstractAutoencoder] --> CFG[v2-inference-v.yaml]

模型文件管理与发现

ModelFileManager 维护一个进程内的 cache 字典，键为模型分类，值为 (列表, 字典, 时间戳) 三元组，用于避免重复磁盘扫描 资料来源：app/model_manager.py:7-9。在 add_routes 中定义了 /experiment/models 与 /experiment/models/{folder} 两个实验性端点，前者枚举 folder_paths.folder_names_and_paths 中除 configs 与 custom_nodes 之外的目录 资料来源：app/model_manager.py:18-25。在文件过滤方面，工具使用 folder_paths.filter_files_extensions 与 filter_files_content_types 保证仅返回支持的文件类型。

社区曾报告"缺失模型下载"面板的"Download"按钮在浏览器端下载而非服务端下载到 extra_model_paths.yaml 配置的路径（参见 issue #13676 与 issue #14287），这是浏览器层按钮事件与服务端模型路径解析之间协调不充分所致。ModelFileManager 的实验性路由展示了服务端枚举的可行方案。

内存、设备与模型集成

潜在扩散栈通过 YAML 配置驱动模型实例化。v2-inference-v.yaml 中 first_stage_config 指向 ldm.models.autoencoder.AutoencoderKL，与 comfy/ldm/models/autoencoder.py 中的 AbstractAutoencoder 抽象类保持一致 资料来源：models/configs/v2-inference-v.yaml:39-44。DiagonalGaussianRegularizer 通过 DiagonalGaussianDistribution 实现潜在空间采样与 mode() 两种推理模式 资料来源：comfy/ldm/models/autoencoder.py:9-22。

UNetModel 的 use_fp16: True 与 use_checkpoint: True 配置表明 ComfyUI 默认依赖检查点（gradient/activation checkpointing）以节约显存。v0.24.0 发布说明指出对 triposplat 预览与旧版 offloading 模式的修复（参见 v0.24.0 release notes），而 v0.23.0 引入了多线程从磁盘加载模型以及"Offload to disk"特性以提升加载速度（参见 v0.23.0 release notes）。

社区已知与内存/设备相关的问题包括：

• 在 ROCm 平台上 Radeon 890M APU 的 GTT/共享内存被错误地计入 VRAM，导致 HIGH_VRAM/gpu-only 内存压力（issue #14274）。
• 特定提交（0a2dd86）后出现的 OOM 错误（issue #14126）。
• Float8_e4m3fn 在某些 CUDA 内核中尚未实现（issue #14285），需要降级精度或回退到受支持的数据类型。

节点、子图与扩展集成

SubgraphManager 通过 Source 枚举区分 custom_node 与 templates 两种来源，并将每个子图 JSON 文件构造为带 SHA-256 哈希 entry_id 的 SubgraphEntry 资料来源：app/subgraph_manager.py:7-29。NodeReplaceManager 提供幂等的 register 方法：当 (old_node_id, new_node_id) 对已存在时忽略重复，防止 ComfyUI-Manager 等扩展热重载后残留过期映射 资料来源：app/node_replace_manager.py:24-37。

UserManager 在 multi_user 关闭时回退到单一 default 用户配置，并在启用时从 users.json 加载多用户记录 资料来源：app/user_manager.py:30-37。AppSettings 提供 /settings、/settings/{id} 的 GET/POST 端点用于读写 comfy.settings.json 资料来源：app/app_settings.py:23-39。结合 README.md 中 --enable-manager、--disable-manager-ui 等标志，ComfyUI 形成了从模型到节点再到用户偏好的完整集成链路。

已知限制

See Also

• ComfyUI-Manager 扩展配置：README.md#comfyui-manager
• 类型系统与节点开发：comfy/comfy_types/README.md
• 释放说明：v0.23.0、v0.24.0

部署、配置与硬件支持

概述

ComfyUI 是一个基于节点图（node graph）的开源 AI 内容生成引擎，支持图像、视频、3D、音频等多模态输出。本章聚焦其部署形态、运行时配置与硬件兼容性，帮助运维人员和开发者在不同操作系统与加速器平台上落地 ComfyUI。

项目提供三种主要部署路径：桌面应用（Desktop Application）、Windows 便携包（Portable Package）以及手动安装（Manual Install），并通过 python main.py 启动本地 HTTP 服务 README.md。此外，官方提供云端版本 Comfy Cloud，用户也可通过 comfy-cli 进行命令行安装：pip install comfy-cli && comfy install README.md。

安装与部署方式

手动安装（Manual Install）

README 中明确指出，手动安装支持全部操作系统和 GPU 类型——NVIDIA、AMD、Intel、Apple Silicon、Ascend NPU README.md。Python 3.13 兼容性最佳；Python 3.14 已可工作但部分自定义节点可能存在兼容问题 README.md。

依赖检查逻辑在 utils/install_util.py 中实现。该模块会解析仓库根目录下的 requirements.txt，对每个形如 pkg==X.Y.Z 的条目校验语义化版本号（is_valid_version 使用正则 ^(\d+)\.(\d+)\.(\d+)$ 校验），并通过 get_required_packages_versions() 缓存当前要求的依赖版本 utils/install_util.py:18-58。当依赖缺失时，get_missing_requirements_message() 会向用户输出 pip install -r requirements.txt 的修复提示，便携包用户则被引导到 update\update_comfyui.bat utils/install_util.py:7-17。

前端管理

自 2024 年 8 月 15 日起，前端代码已迁移到独立仓库 ComfyUI_frontend，并以 comfyui-frontend-package 的形式作为 PyPI 依赖安装 README.md。app/frontend_management.py 中的 check_comfy_packages_versions() 会枚举所有 comfy* 开头的包，对比安装版本与 requirements.txt 中的要求版本，输出"已安装 X 版本低于推荐版本 Y"的告警 app/frontend_management.py。用户可通过 --front-end-version Comfy-Org/ComfyUI_frontend@latest 或 @1.2.2 切换到日构建或指定版本 README.md。

配置系统

命令行参数

comfy/cli_args.py 是 ComfyUI 的 CLI 参数定义入口，覆盖监听地址、端口、TLS 证书、模型路径、显存策略、API 节点开关等关键配置。常用配置项包括：

额外模型路径

extra_model_paths.yaml 允许用户把外部已存在的模型目录挂载到 ComfyUI 的逻辑路径下，从而在"不复制模型"的前提下复用其他 UI 的模型库 README.md。folder_paths.py 负责将这些 YAML 路径解析为 checkpoints、loras、vae、embeddings 等内置子目录，并在工作流引用模型时回退搜索。

用户与多用户

app/user_manager.py 中的 UserManager 在启动时检查 folder_paths.get_user_directory() 是否存在，若不存在则自动创建并提示从浏览器存储迁移到服务端存储 app/user_manager.py。--multi-user 启用时，users.json 记录所有用户档案，文件信息通过 get_file_info() 提供 path/size/modified/created 四元组 app/user_manager.py。

硬件支持与已知问题

加速器平台

README 明确列出支持的硬件范围：NVIDIA（含 RTX 10 系以上的便携版）、AMD（ROCm 便携版）、Intel、Apple Silicon、华为 Ascend NPU README.md。其中 Apple Silicon 要求安装 PyTorch nightly，并复用 Windows/Linux 的手动安装步骤 README.md。Ascend NPU 用户需先按 torch_npu 官方指南 安装 Basekit（驱动/固件/CANN）和内核，再继续 ComfyUI 的安装流程 README.md。

部署环境检测

comfy/deploy_environment.py 提供运行时环境识别能力，用于在云端（Comfy Cloud）与本地部署之间做差异化处理。该模块与 cli_args.py 共同决定默认值，例如云端会自动注入 API 节点密钥而本地需要用户手动配置。

社区关注的硬件痛点

v0.23.0 引入了"多线程从磁盘加载模型"以及"卸载到磁盘"以缓解大模型的加载时间与 OOM 风险 Release v0.23.0；但部分用户在 commit 0a2dd86 之后报告了新的 OOM 错误 Issue #14126，建议在升级到 v0.24.x 时关注显存相关的回退开关。

最佳实践小结

• 部署前先确认 requirements.txt 与本机 Python 版本匹配，便携包用户使用 update\update_comfyui.bat 同步 utils/install_util.py。
• 通过 extra_model_paths.yaml 复用外部模型库，避免重复下载 README.md。
• 生产环境务必使用 --tls-keyfile / --tls-certfile 启用 HTTPS，并使用受信 CA 签发的证书替代自签证书 README.md。
• 在 ROCm、Apple Silicon 等非 NVIDIA 平台上遇到数值异常（NaN/Inf）时，先用 --force-fp32 验证是否为精度问题，再寻找长期修复 Issue #14249。
• 多用户场景下必须显式启用 --multi-user，否则用户设置会落入默认档案 app/user_manager.py。

See Also

• Frontend & Node Development — 前端包管理与节点扩展机制
• Model Loading & Memory Management — 显存分配、模型分片与多线程加载
• Release Process — 双周发布周期与补丁回退策略

API、Custom Nodes、API Nodes 与前端集成

概述与目标

ComfyUI 是一个模块化、基于节点图（node graph）的 AI 内容创作引擎，核心能力围绕"前端渲染工作流、后端调度执行"展开。本页聚焦于四个紧密耦合的子系统：HTTP/REST API 端点、Custom Nodes（用户/社区扩展节点）、API Nodes（调用闭源商业模型的代理节点），以及与外部前端仓库的集成与版本管理。

• API 端点：通过 README.md 中提及的 OpenAPI 规范（openapi.yaml）以及 api_server/ 子模块对外暴露 HTTP 接口，使工作流可被外部应用驱动。
• Custom Nodes：放置在 custom_nodes/ 目录中的 Python 扩展，遵循 ComfyNodeABC 抽象基类规范以注册新节点。
• API Nodes：可选的付费/远程推理节点，可通过 --disable-api-nodes 命令行参数关闭。
• 前端集成：自 2024-08-15 起前端从主仓库迁出为独立仓库 ComfyUI_frontend，并以 comfyui-frontend-package pip 依赖形式分发。

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

自定义节点（Custom Nodes）开发与类型系统

ComfyUI 提供 comfy.comfy_types 模块作为节点开发者的官方类型提示入口，核心导出包括 IO、ComfyNodeABC、CheckLazyMixin 与 InputTypeDict。

from comfy.comfy_types import IO, ComfyNodeABC

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

IO 枚举聚合了常见数据类型，其中几个特殊复合类型对开发体验至关重要：

这套类型系统让 IDE（如 VS Code）能为 INPUT_TYPES 的 required、optional、hidden 字段提供自动补全与悬浮提示。资料来源：comfy/comfy_types/README.md:1-60

节点替换（NodeReplace）管理

NodeReplaceManager 维护一个 old_node_id -> list[NodeReplace] 映射表，支持旧节点到新节点的迁移。当自定义节点在同一进程内被 ComfyUI-Manager 之类的工具重载时，注册逻辑是幂等的：若 (old_node_id, new_node_id) 组合已存在，重复条目会被忽略以避免陈旧映射堆积。资料来源：app/node_replace_manager.py:30-65

flowchart LR
    A[Custom Node 启动] --> B[NodeReplaceManager.register]
    B --> C{已存在相同 old→new?}
    C -- 是 --> D[logging.debug 忽略重复]
    C -- 否 --> E[追加到 _replacements 字典]
    E --> F[执行工作流时按映射替换 class_type]

子图（Subgraph）管理

SubgraphManager 负责发现并缓存两类子图源：

• Source.custom_node：从自定义节点包的 subgraphs/*.json 加载。
• Source.templates：内置模板（蓝色打印）来源。

每个子图条目以 SHA-256 哈希（sha256(source||file)）作为唯一 ID，确保不同来源下的同名子图不会冲突。条目中 info 字段在 custom node 场景下会回填 node_pack（节点包名称），方便前端在 UI 中按包分组。资料来源：app/subgraph_manager.py:1-80

前端集成与版本管理

FrontendManager 是连接核心与前端的桥梁，关键职责包括：

1. 版本比对：通过 comfyui-frontend-package 这个 pip 依赖来声明所需前端版本，启动时调用 check_comfy_packages_versions() 比对已安装版本与 requirements.txt 中规定的版本；若低于要求，记录告警日志。资料来源：app/frontend_management.py:120-180
2. 自定义前端目录：CUSTOM_FRONTENDS_ROOT = web_custom_versions/，允许用户放置自编译的前端构建产物，便于测试本地修改。
3. 按需下载 release：download_release_asset_zip() 从 GitHub Release 拉取 dist.zip，写入临时文件后解压到目标目录。
4. 命令行覆盖版本：使用 --front-end-version Comfy-Org/ComfyUI_frontend@latest 或固定版本号（如 @1.2.2）切换前端。

当版本不匹配时，会输出形如 Installed comfyui-frontend-package X is lower than the recommended version Y 的告警，并提示用户执行 pip install -r requirements.txt 或在便携版上运行 update\update_comfyui.bat。资料来源：utils/install_util.py:40-90

用户、设置与模型管理

• 用户管理：UserManager 在单用户模式下默认使用 default 用户；当传入 --multi-user 时从 users.json 加载多用户配置；用户相关文件统一存放在 folder_paths.get_user_directory()。资料来源：app/user_manager.py:1-60
• 应用设置：AppSettings 暴露 GET/POST /settings 路由（comfy.settings.json），所有用户偏好持久化到磁盘而非浏览器存储，便于跨设备恢复。资料来源：app/app_settings.py:1-50
• 模型管理：ModelFileManager 提供 GET /experiment/models 与 /experiment/models/{folder} 实验性端点，返回带缓存的模型清单，并排除 configs 与 custom_nodes 这两个黑名单目录。资料来源：app/model_manager.py:1-50

社区反馈与已知问题

社区中与本页相关的高频痛点包括：

• 缺失模型下载行为异常：在 Workflow Overview 错误面板中点击 "Download" 按钮触发的实际是浏览器原生下载（写入 OS 下载目录），而非按 extra_model_paths.yaml 配置的路径在服务端落盘——这是前后端职责未对齐导致的体验偏差（参见 issue #13676 与 issue #14287）。
• 版本升级回退：v0.23.0 → v0.24.1 中 Load Video 节点出现回退，社区建议升级时同步检查 comfyui-frontend-package 与核心版本绑定（参见 issue #14292）。
• 关闭 API 节点：若不需要使用 Nano Banana、Seedance、Hunyuan3D 等闭源模型，可通过 --disable-api-nodes 完全禁用，减少启动耗时与外部依赖。

See Also

• Node Execution & Graph Internals — 工作流执行与图遍历机制
• Model Loading & Memory Management — 显存/内存策略与 extra_model_paths.yaml 配置
• Frontend Development Guide — 前端独立仓库与每日构建发布
• Comfy API 文档 — API Nodes 接入指南

Pitfall Log / 踩坑日志

项目：Comfy-Org/ComfyUI

摘要：发现 38 个潜在踩坑项，其中 15 个为 high/blocking；最高优先级：安装坑 - 来源证据：AttributeError: 'ModelMMAP' object has no attribute 'get_file_handle'。

1. 安装坑 · 来源证据：AttributeError: 'ModelMMAP' object has no attribute 'get_file_handle'

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：AttributeError: 'ModelMMAP' object has no attribute 'get_file_handle'
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/14295 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Download Missing Models opens Windows Save As dialog instead of downloading automatically

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Download Missing Models opens Windows Save As dialog instead of downloading automatically
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/14287 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：Flatpak Support

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Flatpak Support
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/8284 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 安装坑 · 来源证据：Hook cuMemAlloc_v2 failed | - Windows fatal exception: access violation

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Hook cuMemAlloc_v2 failed | - Windows fatal exception: access violation
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/14405 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：Native PiD pixel-space sampling outputs NaN in bf16 on ROCm (gfx1151); only --force-fp32 produces a valid image

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Native PiD pixel-space sampling outputs NaN in bf16 on ROCm (gfx1151); only --force-fp32 produces a valid image
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/14249 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 安装坑 · 来源证据：VRAM OOM on Linux with large singular allocation but should be within limits

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：VRAM OOM on Linux with large singular allocation but should be within limits
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/14340 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

7. 安装坑 · 来源证据：You broke ComfyUI-LTXVideo and countless other nodes by forcing the update to Kornia 0.8.3

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：You broke ComfyUI-LTXVideo and countless other nodes by forcing the update to Kornia 0.8.3
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/14296 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

8. 配置坑 · 来源证据："Download" button in missing models panel uses browser download instead of server-side download to configured paths

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题："Download" button in missing models panel uses browser download instead of server-side download to configured paths
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/13676 | 来源类型 github_issue 暴露的待验证使用条件。

9. 配置坑 · 来源证据：Cannot access my models sitting on my second drive

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Cannot access my models sitting on my second drive
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/14325 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

10. 配置坑 · 来源证据：Dynamic VRAM causes model reload on every prompt after workflow/model switch (v0.23)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Dynamic VRAM causes model reload on every prompt after workflow/model switch (v0.23)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/14276 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 配置坑 · 来源证据：Loading .safetensors files requires double memory on DGX Spark

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Loading .safetensors files requires double memory on DGX Spark
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/10896 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

12. 配置坑 · 来源证据：PiD — Latent Upscale & Decode uses incompatible dimensions

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：PiD — Latent Upscale & Decode uses incompatible dimensions
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/14330 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

13. 配置坑 · 来源证据：Using LoRA hooks produces garbage on Anima

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Using LoRA hooks produces garbage on Anima
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/12853 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

14. 配置坑 · 来源证据：[ROCm][AMD APU] Radeon 890M GTT/shared memory is reported as VRAM, causing HIGH_VRAM/gpu-only memory pressure

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[ROCm][AMD APU] Radeon 890M GTT/shared memory is reported as VRAM, causing HIGH_VRAM/gpu-only memory pressure
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/14274 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

15. 配置坑 · 来源证据：an existing Workflows directory can no longer be opened by the app

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：an existing Workflows directory can no longer be opened by the app
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/14407 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

16. 安装坑 · 失败模式：installation: Comfy 0.23.0 -> 0.24.1 Load Video node is broken

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Comfy 0.23.0 -> 0.24.1 Load Video node is broken
• 对用户的影响：Developers may fail before the first successful local run: Comfy 0.23.0 -> 0.24.1 Load Video node is broken
• 证据：failure_mode_cluster:github_issue | https://github.com/Comfy-Org/ComfyUI/issues/14292 | Comfy 0.23.0 -> 0.24.1 Load Video node is broken

17. 安装坑 · 失败模式：installation: Download Missing Models opens Windows Save As dialog instead of downloading automatically

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Download Missing Models opens Windows Save As dialog instead of downloading automatically
• 对用户的影响：Developers may fail before the first successful local run: Download Missing Models opens Windows Save As dialog instead of downloading automatically
• 证据：failure_mode_cluster:github_issue | https://github.com/Comfy-Org/ComfyUI/issues/14287 | Download Missing Models opens Windows Save As dialog instead of downloading automatically

18. 安装坑 · 失败模式：installation: Flatpak Support

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Flatpak Support
• 对用户的影响：Developers may fail before the first successful local run: Flatpak Support
• 证据：failure_mode_cluster:github_issue | https://github.com/Comfy-Org/ComfyUI/issues/8284 | Flatpak Support

19. 安装坑 · 失败模式：installation: You broke ComfyUI-LTXVideo and countless other nodes by forcing the update to Kornia 0.8.3

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: You broke ComfyUI-LTXVideo and countless other nodes by forcing the update to Kornia 0.8.3
• 对用户的影响：Developers may fail before the first successful local run: You broke ComfyUI-LTXVideo and countless other nodes by forcing the update to Kornia 0.8.3
• 证据：failure_mode_cluster:github_issue | https://github.com/Comfy-Org/ComfyUI/issues/14296 | You broke ComfyUI-LTXVideo and countless other nodes by forcing the update to Kornia 0.8.3

20. 安装坑 · 失败模式：installation: how to disable update anything?

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: how to disable update anything?
• 对用户的影响：Developers may fail before the first successful local run: how to disable update anything?
• 证据：failure_mode_cluster:github_issue | https://github.com/Comfy-Org/ComfyUI/issues/11773 | how to disable update anything?

21. 安装坑 · 失败模式：installation: v0.23.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.23.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.23.0
• 证据：failure_mode_cluster:github_release | https://github.com/Comfy-Org/ComfyUI/releases/tag/v0.23.0 | v0.23.0

22. 安装坑 · 来源证据：how to disable update anything?

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：how to disable update anything?
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI/issues/11773 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

23. 配置坑 · 失败模式：configuration: "Download" button in missing models panel uses browser download instead of server-side downlo...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: "Download" button in missing models panel uses browser download instead of server-side download to configured paths
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: "Download" button in missing models panel uses browser download instead of server-side download to configured paths
• 证据：failure_mode_cluster:github_issue | https://github.com/Comfy-Org/ComfyUI/issues/13676 | "Download" button in missing models panel uses browser download instead of server-side download to configured paths

24. 配置坑 · 失败模式：configuration: hostbuf_file_reader_read failed

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: hostbuf_file_reader_read failed
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: hostbuf_file_reader_read failed
• 证据：failure_mode_cluster:github_issue | https://github.com/Comfy-Org/ComfyUI/issues/14281 | hostbuf_file_reader_read failed

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

• 严重度：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.

26. 运行坑 · 失败模式：runtime: AttributeError: 'ModelMMAP' object has no attribute 'get_file_handle'

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: AttributeError: 'ModelMMAP' object has no attribute 'get_file_handle'
• 对用户的影响：Developers may hit a documented source-backed failure mode: AttributeError: 'ModelMMAP' object has no attribute 'get_file_handle'
• 证据：failure_mode_cluster:github_issue | https://github.com/Comfy-Org/ComfyUI/issues/14295 | AttributeError: 'ModelMMAP' object has no attribute 'get_file_handle'

27. 运行坑 · 失败模式：runtime: ideogram-4 fp8 NotImplementedError: "mul_cuda" not implemented for 'Float8_e4m3fn'

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: ideogram-4 fp8 NotImplementedError: "mul_cuda" not implemented for 'Float8_e4m3fn'
• 对用户的影响：Developers may hit a documented source-backed failure mode: ideogram-4 fp8 NotImplementedError: "mul_cuda" not implemented for 'Float8_e4m3fn'
• 证据：failure_mode_cluster:github_issue | https://github.com/Comfy-Org/ComfyUI/issues/14285 | ideogram-4 fp8 NotImplementedError: "mul_cuda" not implemented for 'Float8_e4m3fn'

28. 运行坑 · 失败模式：runtime: v0.20.1

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: v0.20.1
• 对用户的影响：Upgrade or migration may change expected behavior: v0.20.1
• 证据：failure_mode_cluster:github_release | https://github.com/Comfy-Org/ComfyUI/releases/tag/v0.20.1 | v0.20.1

29. 维护坑 · 失败模式：migration: Dynamic VRAM causes model reload on every prompt after workflow/model switch (v0.23)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: Dynamic VRAM causes model reload on every prompt after workflow/model switch (v0.23)
• 对用户的影响：Developers may hit a documented source-backed failure mode: Dynamic VRAM causes model reload on every prompt after workflow/model switch (v0.23)
• 证据：failure_mode_cluster:github_issue | https://github.com/Comfy-Org/ComfyUI/issues/14276 | Dynamic VRAM causes model reload on every prompt after workflow/model switch (v0.23)

30. 维护坑 · 失败模式：migration: v0.21.1

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v0.21.1
• 对用户的影响：Upgrade or migration may change expected behavior: v0.21.1
• 证据：failure_mode_cluster:github_release | https://github.com/Comfy-Org/ComfyUI/releases/tag/v0.21.1 | v0.21.1

31. 维护坑 · 失败模式：migration: v0.22.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v0.22.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.22.0
• 证据：failure_mode_cluster:github_release | https://github.com/Comfy-Org/ComfyUI/releases/tag/v0.22.0 | v0.22.0

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

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | no_demo; severity=medium

35. 运行坑 · 失败模式：performance: Native PiD pixel-space sampling outputs NaN in bf16 on ROCm (gfx1151); only --force-fp32 prod...

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: Native PiD pixel-space sampling outputs NaN in bf16 on ROCm (gfx1151); only --force-fp32 produces a valid image
• 对用户的影响：Developers may hit a documented source-backed failure mode: Native PiD pixel-space sampling outputs NaN in bf16 on ROCm (gfx1151); only --force-fp32 produces a valid image
• 证据：failure_mode_cluster:github_issue | https://github.com/Comfy-Org/ComfyUI/issues/14249 | Native PiD pixel-space sampling outputs NaN in bf16 on ROCm (gfx1151); only --force-fp32 produces a valid image

36. 运行坑 · 失败模式：performance: [ROCm][AMD APU] Radeon 890M GTT/shared memory is reported as VRAM, causing HIGH_VRAM/gpu-only...

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: [ROCm][AMD APU] Radeon 890M GTT/shared memory is reported as VRAM, causing HIGH_VRAM/gpu-only memory pressure
• 对用户的影响：Developers may hit a documented source-backed failure mode: [ROCm][AMD APU] Radeon 890M GTT/shared memory is reported as VRAM, causing HIGH_VRAM/gpu-only memory pressure
• 证据：failure_mode_cluster:github_issue | https://github.com/Comfy-Org/ComfyUI/issues/14274 | [ROCm][AMD APU] Radeon 890M GTT/shared memory is reported as VRAM, causing HIGH_VRAM/gpu-only memory pressure

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:589831718 | https://github.com/Comfy-Org/ComfyUI | release_recency=unknown