ARCHITECTURE · EXECUTION · INFERENCE · OPERATIONS

ComfyUI 技术体系

从节点界面背后的服务端、图执行和张量语义出发，系统说明生成管线如何组合、扩展如何接入、环境如何复现，以及问题如何被定位。

进入系统架构 →查看技术速查

系统形态Node graph + inference engine

执行核心Validate → Queue → Execute → Cache

扩展边界Python node + Web extension + API

文档定位技术参考 / 工程基线

00 · SYSTEM MAP

技术全景与边界

ComfyUI 不是单一的“画图网页”，而是一套由图编辑器、异步服务端、类型化执行图、模型生命周期管理和扩展生态组成的生成式媒体运行时。

CONTROL PLANE工作流与交互

画布、模板、队列、历史、预览、参数组件和 App Mode。

EXECUTION PLANE验证与调度

Prompt 校验、拓扑执行、缓存、部分执行、异步节点和进度事件。

INFERENCE PLANE模型与算子

模型加载、条件编码、噪声计划、采样、VAE、控制与后处理。

EXTENSION PLANE节点与接口

Python 自定义节点、前端扩展、服务端路由、Registry 与 API 集成。

本文讨论的系统边界

核心：ComfyUI Server、官方前端、Core Nodes、模型管理和工作流格式。
扩展：社区节点、前端脚本、模型适配、独立 API 客户端和部署层。
外部依赖：PyTorch 与设备后端、模型权重、FFmpeg、系统驱动、对象存储和反向代理。

阅读方法

先读 01–07 建立执行与推理模型，再按角色选择：工作流作者读 08–10，节点开发者读 11–13，平台工程师读 14–18。

01 · ARCHITECTURE

系统架构

官方前端和 Python 服务端是两个独立发布、协同运行的组件。浏览器负责图编辑与交互，服务端负责模型、文件、队列和真实计算。

Browser / FrontendLiteGraph 画布、节点组件、Workflow JSON、队列控制、WebSocket 状态与输出预览。

HTTP / WebSocket/prompt 提交 API Prompt；/ws 推送执行状态；文件、模型、历史与队列由 HTTP 路由提供。

Prompt Serveraiohttp 服务、请求验证、用户与文件管理、队列控制、事件广播和扩展路由。

Execution EngineDynamicPrompt、拓扑执行列表、节点输入解析、输出缓存、部分执行、异步节点和错误传播。

Inference RuntimePyTorch、设备后端、模型加载/卸载、注意力实现、采样器、VAE 和媒体算子。

Storagemodels/、input/、output/、user/、工作流元数据与外部模型路径。

一次请求的端到端路径

编辑工作流Workflow JSON

→

序列化提交API Prompt

→

验证并入队prompt_id

→

执行与缓存typed graph

→

事件与结果WS + files

关键源代码入口

位置	职责	排查问题
`main.py`	启动参数、路径初始化、服务启动	启动、监听地址、设备参数
`server.py`	HTTP/WS 路由与 PromptServer	接口、上传、事件、队列入口
`execution.py`	Prompt 执行、缓存、输出与异常	节点次序、缓存、执行错误
`nodes.py`	核心节点注册和加载	节点发现、输出节点、目录
`folder_paths.py`	模型与文件路径注册	模型不显示、路径扩展
`comfy/model_management.py`	设备、显存、加载和卸载策略	OOM、offload、精度与设备

02 · EXECUTION ENGINE

图、验证与执行引擎

画布上的 Workflow 与服务端执行的 Prompt 是相关但不同的表示。理解这一区别，是编写自动化、分析缓存和调试“为什么没执行”的前提。

两种 JSON

表示	主要内容	用途
Workflow JSON	节点位置、尺寸、颜色、分组、连线、组件值和界面状态	在前端恢复可编辑画布
API Prompt	以节点 ID 为键；每项包含 `class_type` 与解析后的 `inputs`	提交服务端执行

{ "3": { "class_type": "KSampler", "inputs": { "seed": 42, "steps": 24, "model": ["4", 0], "positive": ["6", 0], "negative": ["7", 0], "latent_image": ["5", 0] } } }

执行过程

前端展开组件与连线把可视图转换为 API Prompt，引用写成 [上游节点ID, 输出索引]。
服务端验证检查 class_type、必填输入、常量范围、连接类型和输出可达性；失败会返回 node_errors。
加入 Prompt Queue返回 prompt_id 与队列号，执行与 HTTP 请求解耦。
从输出目标构造依赖图没有通向输出节点的孤立分支通常不执行；部分执行可指定目标。
前向拓扑调度只有依赖已满足的节点可运行；Lazy Evaluation 与 Node Expansion 可在执行期改变需求或扩展图。
缓存与事件命中缓存时复用输出；执行过程通过 WebSocket 发送状态、节点、进度与错误事件。

缓存语义

默认情况下，节点输入或组件值改变会使节点被视为已改变，并使依赖它的必要下游重新执行；未改变的输出可复用。输出节点是反向依赖分析的根。自定义节点可用 OUTPUT_NODE 声明输出，用 IS_CHANGED 修正外部文件、隐式随机数等默认无法观察的变化。[S4]

常见误解

Queue 并不等于整张画布从左到右全部执行；“值没变”“分支不通向输出”“命中缓存”都可能让节点跳过。把随机性做成显式 seed 输入，才能兼顾复现与缓存。

03 · TYPE SYSTEM

数据类型与张量约定

端口颜色体现的是类型约束。前端阻止多数错误连接，服务端仍会验证；运行时对象可以是张量、模型包装器、字典、列表或扩展自定义对象。

类型	典型运行时表示	关键约定
IMAGE	`torch.Tensor`	通常为 `[B,H,W,C]`，浮点且范围约 0–1；不是 PIL Image。
MASK	`torch.Tensor`	通常为 `[B,H,W]`、0–1；遮罩方向要由节点语义确认。
LATENT	`dict`	至少常含 `samples` 张量；通道数和空间压缩率由模型/VAE 家族决定，不能写死为 4 和 8。
CONDITIONING	嵌套 list/tuple	编码张量与 metadata 组合；metadata 可携带 pooled output、区域、遮罩、时间区间等。
MODEL	Comfy 模型包装对象	包含模型、patch、采样配置与设备管理信息，不等同裸 `torch.nn.Module`。
CLIP	文本编码器包装对象	负责 tokenizer、文本模型、权重 patch 和设备/精度。
VAE	VAE 包装对象	处理像素与 latent，包含缩放、平铺和设备策略。
COMBO	选项列表 → 字符串值	`INPUT_TYPES` 中用字符串列表声明，常在运行时动态生成。
INT/FLOAT/STRING/BOOLEAN	Python 标量	可带默认值、范围、步长、多行、占位符等前端提示。

批量是类型的一部分

IMAGE 名称是单数，但对象通常含 batch 维。节点要明确自己是逐项映射、整批处理还是改变 batch；自定义节点可通过 INPUT_IS_LIST、OUTPUT_IS_LIST 控制列表语义，不能把 batch 和 Python list 混为一谈。

自定义类型

扩展可以用唯一的大写字符串定义类型，运行时可以传递任意 Python 对象。前端不知道如何为它创建组件时，应以 forceInput 强制使用端口；跨节点包共享自定义类型需要稳定命名与版本契约。[S5]

04 · INFERENCE PIPELINE

扩散推理管线

ComfyUI 把推理拆成显式可替换阶段。不同模型家族会改变编码器数量、latent 结构、预测参数化和推荐采样方式，但数据流骨架保持稳定。

Load model familyMODEL / CLIP / VAE

→

Encode conditionsCONDITIONING

→

Prepare latent/noiseLATENT + NOISE

→

Samplesigmas + guider

→

Decode / outputIMAGE / media

四个核心计算角色

Text / multimodal encoder

把文本、图像或其他条件变成模型可消费的 embedding 与 metadata。

Denoising model

在给定噪声水平和条件下预测噪声、速度、流或其他目标。

Sampler + scheduler

定义噪声水平序列和数值更新规则，把初始噪声推进到目标 latent。

VAE / decoder

在像素空间和压缩 latent 空间之间转换；部分架构使用不同压缩倍率或通道。

模型家族为何需要专用模板

文本编码器可能是单个 CLIP、双编码器、T5 或其他组合。
网络可以是 UNet、DiT、MMDiT 或流匹配变体，预测目标不同。
latent 通道、缩放因子、VAE 和原生分辨率不同。
蒸馏或快速模型可能要求特定 guidance、步数和 scheduler。
量化权重需要匹配 loader、计算精度和设备后端。

工程原则

新模型先从内置 Workflow Templates 或项目官方示例开始。模板证明的不只是“节点能连上”，还包括文件拆分、编码器组合和采样约定。

05 · MODEL SYSTEM

模型系统与加载器

模型文件目录只是发现机制；加载器还负责识别 state dict、选择架构配置、创建包装器、处理精度和注册设备生命周期。

整合式与分体式

形式	文件组合	特点
Checkpoint	可能包含 MODEL、CLIP、VAE	加载简单，但组件版本被绑定；缺失部分时输出可能为空或不适用。
Diffusion model	去噪网络单独存放	需显式选择 text encoder 与 VAE，适合新架构和量化。
LoRA / patch	低秩或差分权重	在包装模型/文本编码器上创建 patch，强度与顺序影响最终权重。
Control / adapter	附加控制网络或视觉适配器	通常要求基础家族、视觉编码器、预处理和维度匹配。

目录与发现

ComfyUI/models/ ├─ checkpoints/ # 整合模型 ├─ diffusion_models/ # 分体去噪模型（部分版本兼容 unet/） ├─ text_encoders/ # 文本编码器（部分版本兼容 clip/） ├─ vae/ # VAE / AE ├─ loras/ # LoRA ├─ controlnet/ # 控制模型 ├─ clip_vision/ # 视觉编码器 ├─ upscale_models/ # 像素超分模型 └─ embeddings/ # textual inversion

folder_paths 管理类别到目录及扩展名的映射；extra_model_paths.yaml 可让多个实例共享权重。文件加入后需要刷新列表或重启，节点下拉框由 INPUT_TYPES 在运行时生成。

模型资产规范

记录来源 URL、许可证、下载时间、文件大小和 SHA-256；文件名不是身份。
优先 safetensors；对来源不明、能反序列化任意 Python 对象的格式保持警惕。
不要把不同架构仅凭扩展名混用；以 loader、模板和模型卡共同确定。
生产环境将模型 manifest 与工作流版本一起归档，避免“同名文件内容变化”。

06 · SAMPLING SYSTEM

采样系统

KSampler 是多个机制的组合界面。高级工作流把它拆成 Noise、Guider、Sampler、Sigmas 和采样执行，以便单独替换与分析。

Noiseseed → ε

＋

Latentshape / init

→

Guidermodel + conditions

＋

Sigmasscheduler / steps

＋

Samplernumerical update

参数	技术含义	分析方式
seed	噪声生成的控制输入	只在环境、图、模型和实现一致时讨论复现。
steps	sigma 序列上的更新次数	收益通常递减；蒸馏模型可能只需少量步数。
CFG / guidance	有条件与无条件预测的组合强度或模型专用引导	不同家族不可用同一经验区间。
sampler	ODE/SDE 数值更新策略	影响随机性、稳定性、纹理和低步效率。
scheduler	从高噪到低噪的 sigma 分配	必须与模型训练和 sampler 联合比较。
denoise	采用 sigma 序列的范围/重绘程度	图生图中越低越保留输入，但实现细节由节点决定。

可解释调参

锁定系统状态固定模型 hash、工作流、输入、seed、精度与设备。
先确定步数拐点粗扫低/中/高步数，找质量收益开始趋缓的位置。
再校准 guidance围绕模型官方建议区间小步调整，观察提示遵循与伪影。
最后比较 sampler/scheduler保留对照图和运行时间，不凭单张偶然结果下结论。

确定性边界

相同 seed 不是跨设备、PyTorch、注意力实现或量化后端的逐像素确定性保证。生产复现应固定完整环境，而不是只记录 seed。

07 · CONDITIONING SYSTEM

条件系统

提示词、ControlNet、参考图、区域、遮罩和时间区间最终都要影响模型条件。CONDITIONING 不是纯 embedding，而是 embedding 与附加属性的组合。

条件来源

Text conditioning

Tokenizer 与文本编码器产生 token embedding、pooled output 或模型专用附加向量。

Structural control

边缘、姿态、深度、法线、分割等预处理结果进入匹配的 ControlNet。

Visual reference

CLIP Vision/IPAdapter 类系统把参考图编码为主体、风格或构图约束。

Spatial / temporal metadata

区域、mask、strength、start/end percent 等限制条件的空间与采样阶段。

ControlNet 数据流

Input imageIMAGE

→

Preprocessoredge/depth/pose

→

Control modelfamily matched

→

ApplyCONDITIONING

→

Samplerguided denoise

组合约束的原则

先分别验证每个条件源，再叠加；否则无法判断冲突来自预处理、权重还是模型兼容。
ControlNet 更偏几何结构，视觉适配器更偏语义/外观，文本提供显式描述；这只是职责倾向，不是硬边界。
强度过大、作用区间过长会让生成僵硬；先降低 strength，再调整 start/end。
预处理分辨率和裁切决定控制图表达的尺度，不能只调下游权重。

08 · IMAGE PIPELINE

图像、遮罩与放大

图生图、局部重绘、扩图和高分辨率修复都建立在 IMAGE、MASK 与 LATENT 的转换上。问题应按空间、遮罩和采样三个层面拆开。

图生图

Load Image[B,H,W,C]

→

VAE Encodepixels → latent

→

Sampledenoise < 1

→

VAE Decodelatent → pixels

局部重绘

Mask 定义允许修改的区域；节点可能执行反转、裁切、膨胀或噪声遮罩，必须预览确认。
遮罩羽化解决边缘融合，遮罩膨胀给模型留下重建上下文；两者不是同一操作。
专用 inpaint 模型/conditioning 可能需要额外通道或输入，不能用普通 checkpoint 的经验替代。
先修几何，再修材质，最后统一颜色；每一步保存中间输出。

放大的三条路径

路径	机制	优势	风险
像素超分	Upscale model 在 IMAGE 上运行	快、结构稳定	放大已有伪影，语义重建有限
Latent upscale + resample	放大 latent 或重新编码后低 denoise 采样	可生成新细节	改脸、改字、改结构
Tiled refine	重叠分块处理并融合	降低峰值显存	接缝、重复纹理、全局不一致

09 · MEDIA PIPELINES

视频、音频与 3D

ComfyUI 的类型化图可以承载多媒体，但媒体模型、编解码和节点包更新速度远高于核心概念。工程上要把模型推理与封装/后处理分层。

视频管线

Conditiontext/image/video

→

Temporal modelvideo latent

→

Decode framesIMAGE batch

→

Postprocessinterpolate/upscale

→

EncodeMP4/WebM

显存通常随空间分辨率、帧数、batch、上下文窗口和模型规模共同增长。
短片低分辨率验证运动，再增加帧数，最后放大和插帧；不要同时放大所有维度。
FFmpeg 属于媒体封装依赖，不是扩散模型的一部分；编码失败要与采样失败分开定位。
首尾帧、关键帧和参考图控制的是不同条件通路，以模板和节点说明为准。

音频与 3D

音频链路应明确采样率、声道、时长、codec 与声画时间基；3D 链路应明确相机、坐标系、单位、网格拓扑、UV、纹理空间和导出格式。它们都需要独立的资产验证，不能只检查预览。

10 · WORKFLOW ENGINEERING

工作流工程

工作流是可执行程序，不只是画布。生产质量取决于接口清楚、变更可控、缓存有效、证据完整和失败可恢复。

工程规则

把频繁修改的参数集中成显式入口，避免散落在几十个节点中。
Group 用于表达阶段，Reroute 用于整理传输，Subgraph 用于封装稳定接口；三者职责不同。
每个昂贵阶段提供 Preview/Save 和可旁路路径，调试时启用部分执行。
节点标题写业务语义，输出前缀包含工作流、模型、日期或任务 ID。
禁止隐藏关键常量和隐式随机性；所有影响结果的输入都应可追踪。

复现清单

Graph

Workflow JSON 与 API Prompt、输出目标和子图版本。

Runtime

ComfyUI、前端、Python、PyTorch、设备后端和启动参数。

Extensions

节点包 ID、版本/commit、依赖锁和 Manager snapshot。

Models

基础模型、编码器、VAE、LoRA、ControlNet 的文件 hash 与许可证。

Inputs

原始素材、遮罩、裁切、预处理参数和颜色空间。

Evidence

seed、采样参数、日志、耗时、峰值显存和原始输出元数据。

11 · BACKEND EXTENSIONS

自定义节点架构

服务端自定义节点是 Python 模块。ComfyUI 启动时扫描 custom_nodes/，导入模块并读取 NODE_CLASS_MAPPINGS 完成注册。[S3]

最小节点契约

class InvertImage: CATEGORY = "examples/image" FUNCTION = "invert" RETURN_TYPES = ("IMAGE",) RETURN_NAMES = ("image",) @classmethod def INPUT_TYPES(cls): return {"required": {"image": ("IMAGE",)}} def invert(self, image): return (1.0 - image,) NODE_CLASS_MAPPINGS = {"ExampleInvertImage": InvertImage} NODE_DISPLAY_NAME_MAPPINGS = {"ExampleInvertImage": "Invert Image (Example)"}

INPUT_TYPES

类方法；声明 required、optional、hidden 输入以及组件约束。

RETURN_TYPES

输出类型元组；单输出也必须保留尾逗号。

FUNCTION

执行方法名；参数按输入名传入，返回值顺序与 RETURN_TYPES 对齐。

节点实现原则

保持设备、dtype、batch 和通道约定；不要无条件把张量搬到 CUDA 或 CPU。
推理路径使用 torch.inference_mode() 或遵循宿主上下文，不保留无用计算图。
不在节点执行时安装 pip 包、下载不可验证代码或修改全局环境。
错误信息包含输入、预期和修复建议，但不泄露密钥与私密路径。
长任务提供进度；外部 I/O 明确超时、取消、重试和幂等语义。

12 · FRONTEND EXTENSIONS

前端扩展与通信

前端扩展用于节点呈现、组件、菜单、画布行为和客户端通信。计算逻辑应留在服务端，前端负责交互与序列化。

加载边界

节点包可以通过 WEB_DIRECTORY 暴露前端资源。扩展通常使用前端提供的 app/api 模块注册回调、修改节点原型或发送请求。前端与核心服务端独立发布，使用私有实现细节会带来升级风险。

通信模式

方向	机制	适用
Client → Server	现有 HTTP API 或自定义 aiohttp route	配置、上传、显式命令
Server → Client	PromptServer 事件 / WebSocket	进度、状态、预览、节点 UI 输出
Workflow serialization	Widgets 与 node inputs	需要参与缓存和复现的参数

设计约束

能成为节点输入的状态，不要只存浏览器全局变量。
自定义路由要做输入验证、权限检查和错误码，不要暴露任意文件路径。
避免 monkey patch 核心执行逻辑；官方执行模型和前端接口会演进。
前端版本兼容范围要在 manifest/README 中说明，并提供降级行为。

13 · LOCAL API

本地 API 与自动化

自动化客户端提交的是 API Prompt。执行是异步任务：提交后取得 prompt_id，通过 WebSocket 或历史接口跟踪，再用文件接口读取输出。

核心路由

路由	方法	作用
`/prompt`	POST / GET	提交 Prompt；查询队列状态。
`/ws`	WebSocket	状态、开始、缓存、节点执行、进度、完成和错误事件。
`/history/{prompt_id}`	GET	查询任务输出与执行记录。
`/view`	GET	按 filename/type/subfolder 读取输出或输入文件。
`/upload/image`	POST	上传输入图像。
`/object_info`	GET	获取节点类型、输入输出和组件定义。
`/queue`	GET / POST	查看或管理队列。
`/interrupt`	POST	请求中断当前执行。
`/system_stats`	GET	系统与设备信息。

最小客户端流程

workflow = load_json("workflow_api.json") workflow[PROMPT_NODE]["inputs"]["text"] = prompt workflow[SAMPLER_NODE]["inputs"]["seed"] = seed response = POST("/prompt", { "prompt": workflow, "client_id": client_id }) prompt_id = response["prompt_id"] watch_websocket(client_id, prompt_id) history = GET(f"/history/{prompt_id}") download_declared_outputs(history)

自动化契约

不要依赖画布节点位置；以稳定节点 ID、class_type 或显式业务映射定位参数。
提交前校验模型和节点存在，可用 /object_info 建立能力快照。
任务用 prompt_id 幂等关联；保存请求 manifest、响应、日志和输出 hash。
设置请求超时不等于取消任务；需要显式调用中断或队列管理接口。

服务端路由与 WebSocket 事件以官方 Routes 文档为准。[S6]

14 · PERFORMANCE

设备与性能管理

ComfyUI 的性能不只由显存容量决定。模型加载、注意力、采样、VAE、数据搬运、磁盘和节点实现都可能成为瓶颈。

内存生命周期

Discoverstate dict / config

→

LoadRAM → device

→

Executeweights + activations

→

Offloaddevice → RAM

→

Cache / unloadpolicy driven

主要压力源

压力源	增长变量	优先措施
权重常驻	模型规模、编码器、ControlNet、精度	删除非必要并行模型，使用受支持的 dtype/量化，分阶段运行。
激活与注意力	分辨率、batch、帧数、上下文	batch=1、降低工作尺寸/帧数、分块或窗口。
VAE	像素面积、batch	tiled encode/decode，避免一次解码超大图。
主机内存与 I/O	模型数量、缓存、文件体积	快速本地盘、合理缓存、模型 manifest 和预热。
扩展算子	复制、CPU/GPU 往返、同步点	profiling，保持 device/dtype，消除不必要转换。

基准记录

Environment: OS / GPU-or-NPU / driver / backend / torch / ComfyUI Graph: workflow hash / node versions / model hashes Workload: resolution / frames / batch / steps / sampler / controls Metrics: cold start / warm run / peak VRAM / RAM / per-stage time Quality: reference outputs / acceptance criteria / failure rate

优化次序

先确认正确性，再测冷启动和热运行；先找占比最大的阶段，再更改精度、注意力或量化。没有基线的“加速”无法证明。

15 · DEPLOYMENT

部署与远程运行

安装形态决定升级、驱动和权限边界；模型规模决定存储；访问方式决定安全。生产部署不应照搬个人桌面环境。

形态	适用	技术特征
Desktop	个人桌面、低运维	稳定发布、托管环境；自定义底层能力较少。
Windows Portable	Windows + NVIDIA/特定实验后端	嵌入 Python；便于迁移，但扩展必须安装到内置环境。
Manual + venv/conda	开发、Linux、多环境	版本可控；需自己管理 PyTorch、驱动和依赖。
Container	服务器、团队、CI	镜像可复现；模型与输出应挂载卷，设备运行时需正确透传。
Cloud / hosted API	弹性任务、无需本地设备	并发、资产、成本、网络与数据策略由平台约束。

远程服务

默认只监听回环地址最安全；--listen 会扩大网络面。
公网前必须有 TLS、认证、反向代理、速率限制、防火墙和输出隔离。
自定义节点和 Manager 拥有代码执行/安装能力，不应暴露给不可信用户。
多租户需要任务、文件、模型与日志隔离；不要依赖文件名前缀实现权限。

国产异构卡 / DTK

ComfyUI 核心以 PyTorch 为基础，因此设备能否运行取决于该后端是否提供足够的 PyTorch 与算子兼容。SCNet 的 BW 资源使用 DTK 兼容栈，适合通过 Linux Notebook 和匹配 DTK 的 PyTorch 镜像手动安装，而不是使用 Windows Portable。纯 PyTorch 核心图通常更容易适配；直接编译 CUDA、依赖 xformers/flash-attn/Triton 特定实现的节点需要单独验证。[S9]

多卡边界

申请两张卡不会自动把显存合并。默认工作流常以单设备运行；模型切分、流水线并行或多实例分发需要对应节点/后端和明确调度设计。

16 · SECURITY

安全与供应链

工作流是数据，自定义节点是代码，模型是大体积外部资产，远程 ComfyUI 是可执行服务。三者必须采用不同的信任策略。

威胁面

Custom node code

导入时执行 Python；install.py、requirements 和运行节点均可能访问系统与网络。

Model files

不安全序列化格式可能执行代码；模型来源和许可证也构成供应链风险。

Workflow inputs

文件路径、URL、表达式、模板和第三方 API 节点可能触发 SSRF、路径穿越或密钥泄露。

Network exposure

未认证服务可能允许上传、执行、读取输出、安装扩展或消耗昂贵算力。

基线控制

只从可追踪仓库/Registry 安装节点，固定版本，审查安装脚本和依赖。
优先 safetensors；记录 hash；模型和工作流进入隔离扫描流程。
密钥使用环境变量或平台 Secret，不写入工作流 JSON、节点组件或日志。
服务使用最小权限账户，输入/输出目录白名单，容器只挂载必要路径。
更新前做 snapshot 与回归；不允许节点运行时调用 pip 安装。

Registry 标准禁止 eval/exec、混淆代码和运行时 subprocess pip 安装等高风险做法。[S8]

17 · OBSERVABILITY

可观测性与调试

调试以“最早失败点”为中心：启动、发现、验证、加载、执行、解码、保存和网络是不同故障域。先缩小域，再修改环境。

分层诊断

阶段	典型信号	第一检查
Bootstrap	进程启动失败、Import Failed	Python/torch/设备后端、最早堆栈、自定义节点导入。
Discovery	模型或节点不在下拉框	folder_paths、扩展名、目录、模块映射和启动日志。
Validation	node_errors、红框、无法入队	class_type、必填输入、类型、组件范围、输出可达性。
Model load	state dict mismatch、dtype/device 错误	模型家族、loader、配套编码器/VAE、量化后端。
Execution	节点异常、算子不支持	失败节点输入、shape、dtype、device、扩展版本。
Resource	OOM、进程被杀、极慢	峰值显存/RAM、分辨率、batch、帧数、VAE、其他进程。
Output	黑图、偏色、空历史、保存失败	VAE、数值范围、输出节点、路径权限和磁盘空间。
Remote/API	连接失败、任务看不到	监听地址、代理端口、client_id、prompt_id、WS 与 HTTP 日志。

最小复现协议

保留现场复制最早完整异常、prompt_id、工作流和环境信息。
回到 Core-only用内置模板、单模型、单输出证明核心路径。
按域二分禁用最近节点包或后处理，逐段接回。
验证单一假设每次只改变一个版本、参数或节点。
完成回归修复后运行目标工作流和至少一个已知正常工作流。

建议日志字段

timestamp / prompt_id / client_id / workflow_hash node_id / class_type / phase / elapsed_ms / cache_hit device / dtype / input_shapes / output_shapes model_hashes / extension_versions / peak_memory error_type / sanitized_message / traceback_id

18 · COMPATIBILITY

兼容性与演进

ComfyUI 核心、前端、模板、内置文档、自定义节点、PyTorch 和模型支持各自演进。兼容性问题通常发生在这些版本边界，而不是单个“ComfyUI 版本”。

版本矩阵

Core

服务端 API、执行引擎、Core Nodes、模型检测和加载。

Frontend

画布、节点 UI、序列化、App Mode；作为独立包发布。

Templates

内置工作流与模型下载信息；体现当前官方支持组合。