# https://github.com/Comfy-Org/ComfyUI-Manager 项目说明书 生成时间：2026-06-15 00:13:25 UTC ## 目录 - [Introduction & Installation Guide](#page-1) - [Backend Architecture](#page-2) - [Frontend & Node Database](#page-3) - [Configuration, Security & Operations](#page-4) ## Introduction & Installation Guide ### 相关页面 相关主题：[Backend Architecture](#page-2), [Frontend & Node Database](#page-3), [Configuration, Security & Operations](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md) - [__init__.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/__init__.py) - [docs/en/v3.38-userdata-security-migration.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/v3.38-userdata-security-migration.md) - [scripts/install-manager-for-portable-version.bat](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/scripts/install-manager-for-portable-version.bat) - [scripts/install-comfyui-venv-linux.sh](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/scripts/install-comfyui-venv-linux.sh) - [scripts/install-comfyui-venv-win.bat](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/scripts/install-comfyui-venv-win.bat) - [node_db/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/node_db/README.md) - [glob/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/README.md) - [js/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/README.md) - [notebooks/comfyui_colab_with_manager.ipynb](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/notebooks/comfyui_colab_with_manager.ipynb)
# 介绍与安装指南 ## 项目概述与核心功能 ComfyUI-Manager 是 [ComfyUI](https://github.com/comfyanonymous/ComfyUI) 的官方扩展，为 ComfyUI 提供自定义节点的**安装、卸载、禁用、启用**等管理能力，并整合了模型下载、快照管理、工作流分享等功能入口。该扩展**仅提供安装便利**，不保证第三方节点本身的功能正确性。 ### 系统组件架构 ```mermaid graph TB A[ComfyUI 前端界面] --> B[Manager JS 入口
comfyui-manager.js] B --> C[REST API 服务
manager_server.py] C --> D[核心业务逻辑
manager_core.py] D --> E[下载器
manager_downloader.py] D --> F[本地节点数据库
node_db/] D --> G[CNR 在线注册中心
registry.comfy.org] D --> H[安全检查模块
security_check.py] E --> I[Git 仓库] E --> J[Hugging Face] E --> K[Civitai] ``` 后端 Python 模块按职责分层（[glob/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/README.md)）：核心层 `manager_core.py` 与 `manager_server.py` 提供主要 API；工具层 `git_utils.py`、`cnr_utils.py`、`node_package.py` 提供专项工具；集成层 `security_check.py` 与 `share_3rdparty.py` 负责安全与第三方对接。前端 JavaScript 模块（[js/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/README.md)）包括节点管理、模型管理、快照、组件管理以及分享组件。数据库（[node_db/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/node_db/README.md)）的本地 JSON 文件正逐步过渡到在线 Custom Node Registry (CNR)。 ## 安装方法 ### 方法一：通用方式（仅安装 Manager） 适用于已有 ComfyUI 部署： 1. 在终端进入 `ComfyUI/custom_nodes` 目录 2. 执行 `git clone https://github.com/ltdrdata/ComfyUI-Manager comfyui-manager` 3. 重启 ComfyUI > 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md) — "Installation[method1]" ### 方法二：Windows Portable 版本 1. 安装 [Git for Windows](https://git-scm.com/download/win)（standalone 版，选用 "use windows default console window"） 2. 将 [scripts/install-manager-for-portable-version.bat](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/scripts/install-manager-for-portable-version.bat) 下载至 `ComfyUI_windows_portable` 目录（右击链接选择"另存为"） 3. 双击运行该批处理文件 ### 方法三：通过 comfy-cli（推荐） `comfy-cli` 提供从命令行管理 ComfyUI 的能力，可一次性安装 ComfyUI 与 Manager： **Windows：** ```commandline python -m venv venv venv\Scripts\activate pip install comfy-cli comfy install ``` **Linux/macOS：** ```commandline python -m venv venv . venv/bin/activate pip install comfy-cli comfy install ``` 前置依赖：Python 3 与 Git。 > 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md) — "Installation[method3]" ### 方法四：Linux + venv 全新安装 1. 下载 [scripts/install-comfyui-venv-linux.sh](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/scripts/install-comfyui-venv-linux.sh) 到空目录 2. `chmod +x install-comfyui-venv-linux.sh` 3. `./install-comfyui-venv-linux.sh` 前置依赖：`python-is-python3`、`python3-venv`、`git`。 ### Google Colab 项目提供 Colab 笔记本：[notebooks/comfyui_colab_with_manager.ipynb](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/notebooks/comfyui_colab_with_manager.ipynb)，支持 ComfyUI 安装、Manager 基础安装以及重启时自动安装自定义节点依赖。 ## 安装注意事项与常见故障 ### 路径位置决定安装成败 **正确路径**：`ComfyUI/custom_nodes/comfyui-manager`（目录名必须是 `comfyui-manager`）。 **常见错误路径**（会导致 Manager 无法被识别、无法自我更新，甚至出现重复安装）： - ❌ 直接解压到 `ComfyUI/custom_nodes`，使 `__init__.py` 等文件散落在该目录 - ❌ 嵌套路径 `ComfyUI/custom_nodes/ComfyUI-Manager/ComfyUI-Manager` - ❌ 解压路径 `ComfyUI/custom_nodes/ComfyUI-Manager-main` > 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md) — "Installation Precautions" 社区 Issue #2374（"ComfyUI-Manager disappeared after updating comfyui desktop"，51 条评论）中的多数反馈都与 ZIP 解压后路径不正确有关。 ### 默认安全等级可能阻止安装 Issue #2900 报告：默认配置实际上阻止 Manager 执行任何安装操作，前端却将失败任务标记为"成功"，需打开底部面板才能看到错误。`security_level` 决定了 Manager 的可用操作： | 等级 | 可用特性 | |------|----------| | `block` | 仅信任操作 | | `high` | 仅 Git URL 安装、pip 安装、默认频道外的注册节点、修复节点 | | `middle` | 卸载/更新、默认频道注册节点、快照恢复/删除、重启 | | `normal-` | 大多数特性可用 | | `weak` | 所有特性可用（仅开发环境） | `low` 等级保留用于"Update ComfyUI"操作。 > 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md) — "Security level" ### V3 至 V4 升级困惑 Issue #2916 中用户反映：UI 显示版本为 3.40，而最新发布已是 4.2.1。官方说明指出，`main` 分支目前指向 V3，V4 仍处于 Beta 阶段。升级前建议阅读迁移说明 [docs/en/v3.38-userdata-security-migration.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/v3.38-userdata-security-migration.md)，并备份现有 `/default/ComfyUI-Manager/` 下的快照与配置。 ### uv 环境下 pip 缺失 Issue #1828 指出：使用 `uv` 创建虚拟环境并仅安装 `requirements.txt` 中列出的依赖时，`pip` 不会被一并安装，导致 Manager 启动失败并触发 `[START] Security scan` 错误。V3.16 起已加入 `use_uv` 配置选项，但需在 `uv` 环境中手动确保 `pip` 可用。 ### Manager 菜单消失 Issue #328 中报告：ComfyUI 更新后 Manager 菜单消失，浏览器控制台报错 "Failed to fetch dynamically imported module: .../extensions/ComfyUI-Manager/comfyui-manager.js"。常见原因包括：路径不正确、浏览器缓存未清理，或 ComfyUI/Manager 版本不兼容。可通过重新执行 `git clone` 至正确路径解决。 ## 配置与路径 ### V3.38 起的受保护路径 自 V3.38 起，Manager 的数据迁移至受保护系统路径： | ComfyUI 版本 | Manager 路径 | |---------------|--------------| | v0.3.76+（含 System User API） | `/__manager/` | | 旧版本 | `/default/ComfyUI-Manager/` | 若未指定参数，`` 默认为 `ComfyUI/user`。 > 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md) — "Paths" ### 关键配置文件 - `config.ini`：基础配置（含 `security_level`、`network_mode`、`file_logging`、`always_lazy_install` 等） - `channels.list`：可配置频道列表 - `pip_overrides.json`：pip 包版本覆盖 - `pip_blacklist.list`：pip 黑名单 - `pip_auto_fix.list`：自动修复 pip 版本 - `snapshots/`：快照文件目录 - `components/`：组件文件目录 - `startup-scripts/`：启动脚本目录 > `config.ini` 的实际路径会在 Manager 启动日志中显示。 ### 环境变量 - `COMFYUI_PATH`：ComfyUI 安装路径 - `GITHUB_ENDPOINT`：GitHub 反向代理（用于受限网络环境） - `HF_ENDPOINT`：Hugging Face 反向代理 ### `extra_model_paths.yaml` 配置 `extra_model_paths.yaml` 中标记为 `is_default` 的 section 决定 Manager 使用的路径： - `custom_nodes`：自定义节点安装路径 - `download_model_base`：模型下载基础路径 > 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md) — "extra_model_paths.yaml Configuration" --- **See Also** - [Configuration Reference](https://github.com/Comfy-Org/ComfyUI-Manager) — `config.ini` 与环境变量详解 - [Security Model](https://github.com/Comfy-Org/ComfyUI-Manager) — 多级安全策略与风险评估 - [Node Database & CNR](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/node_db/README.md) — 本地数据库到在线注册中心的过渡 - [v3.38 Migration Guide](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/v3.38-userdata-security-migration.md) — 用户数据安全迁移说明 --- ## Backend Architecture ### 相关页面 相关主题：[Frontend & Node Database](#page-3), [Configuration, Security & Operations](#page-4), [Introduction & Installation Guide](#page-1)
相关源码文件 以下源码文件用于生成本页说明： - [glob/manager_core.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/manager_core.py) - [glob/manager_server.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/manager_server.py) - [glob/manager_downloader.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/manager_downloader.py) - [glob/manager_util.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/manager_util.py) - [glob/security_check.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/security_check.py) - [glob/cm_global.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/cm_global.py) - [glob/cnr_utils.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/cnr_utils.py) - [glob/git_utils.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/git_utils.py) - [glob/node_package.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/node_package.py) - [glob/share_3rdparty.py](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/share_3rdparty.py) - [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)
# Backend Architecture ## 概述与设计目标 ComfyUI-Manager 的后端架构由 `glob/` 目录下的 Python 模块组成，作为 ComfyUI 服务器进程内运行的扩展，负责自定义节点的全生命周期管理（安装、启用、禁用、卸载、版本切换），并提供 REST API 供前端调用。系统的核心设计目标是 **在不影响 ComfyUI 主进程稳定性的前提下，承担所有外部资源交互**，包括 Git 仓库克隆、pip 依赖解析、Hugging Face 模型下载与注册表查询。 后端遵循三层模块化结构： 1. **Core Layer（核心层）**：`manager_core.py`、`manager_server.py` 提供业务逻辑与 API 入口； 2. **Utility Layer（工具层）**：`manager_downloader.py`、`manager_util.py`、`git_utils.py`、`cnr_utils.py` 封装各外部协议； 3. **Integration Layer（集成层）**：`node_package.py`、`security_check.py`、`share_3rdparty.py`、`cm_global.py` 对接 ComfyUI 与第三方平台。 资料来源：[glob/README.md:1-30]() 描述了上述分层结构。 ## 模块架构图 ```mermaid flowchart TB FE[Frontend
js/comfyui-manager.js] -->|REST API| SRV[manager_server.py
API 路由层] SRV --> CORE[manager_core.py
业务逻辑核心] CORE --> UTIL[manager_util.py
通用工具] CORE --> GIT[git_utils.py
Git 操作封装] CORE --> DL[manager_downloader.py
资源下载] CORE --> CNR[cnr_utils.py
注册表通信] CORE --> PKG[node_package.py
节点包管理] CORE --> SEC[security_check.py
安全策略] CORE --> GLB[cm_global.py
全局状态] CORE --> S3P[share_3rdparty.py
第三方分享] PKG --> SEC DL --> SEC CNR --> SEC ``` 此图展示了后端模块的依赖方向：`manager_server.py` 是唯一对外暴露 HTTP 路由的模块，所有前端请求都必须经过它分发。 ## 核心模块详解 ### manager_core.py — 业务逻辑中枢 `manager_core.py` 是后端体量最大的模块，集中实现了以下功能： - **配置加载**：从 `config.ini`、`channels.list` 读取运行参数，支持 `security_level`、`network_mode`、`use_uv` 等关键开关； - **节点安装/卸载**：通过调用 `git_utils.py` 执行 `git clone`/`git pull`，再通过 `pip` 或 `uv` 解析依赖； - **快照管理**：将当前安装状态序列化为 JSON，保存至 `/default/ComfyUI-Manager/snapshots/`； - **缺失节点检测**：扫描当前工作流，识别未安装的节点类名并匹配到注册表条目。 社区中常见的"v3 → v4 升级困惑"（[#2916](https://github.com/Comfy-Org/ComfyUI-Manager/issues/2916)）正是源于 `manager_core.py` 在不同分支间对版本号与数据库通道的解析逻辑差异。 资料来源：[glob/README.md:9-11]()、[glob/manager_core.py:1-50]()。 ### manager_server.py — HTTP API 入口 `manager_server.py` 使用 ComfyUI 内置的 `aiohttp` 路由机制注册端点，对外提供 REST 接口。前端 `cm-api.js` 通过这些端点发起所有异步操作。典型端点包括： | 端点 | 方法 | 功能 | |------|------|------| | `/manager/install` | POST | 安装节点包 | | `/manager/uninstall` | POST | 卸载节点包 | | `/manager/update_all` | POST | 全量更新 | | `/manager/snapshot` | POST | 创建/恢复快照 | | `/manager/comfyui_manager/version` | GET | 读取管理器版本 | 资料来源：[glob/manager_server.py:1-80]()、[glob/README.md:46-55]()。 ### manager_downloader.py — 资源下载 下载模块统一处理三类资源： - **Hugging Face 模型**：通过 `HF_ENDPOINT` 环境变量支持镜像； - **GitHub 仓库**：通过 `GITHUB_ENDPOINT` 支持 `ghproxy.com` 等反向代理； - **本地缓存**：支持 `aria2` 多线程下载加速。 当用户处于 `network_mode = private` 或 `offline` 时，模块自动回退到本地缓存，缓存目录位于 `/default/ComfyUI-Manager/cache/`。 资料来源：[glob/manager_downloader.py:1-60]()、[README.md:255-273]()。 ## 安全模型与配置 `security_check.py` 实现了一套分层风险控制策略，覆盖前端所有高危操作。系统按 `security_level` 配置项划分为四个等级： | 级别 | 允许的操作 | |------|------------| | `strong` | 仅允许低风险操作（查看、浏览） | | `normal` | 允许 `middle` 级别操作（默认通道内的安装/卸载/快照恢复） | | `normal-` | 在非 `--listen` 公网监听时与 `normal` 等价 | | `weak` | 允许全部操作，包括 `Install via git url`、`pip install`、非默认通道安装 | `high` 级别操作包括：通过 Git URL 安装任意仓库、执行 `pip install`、安装非默认通道节点、Fix node 修复等。`security_check.py` 在 `manager_core.py` 每次执行高危操作前被调用，返回布尔值决定是否放行。 社区反馈 [#2979](https://github.com/Comfy-Org/ComfyUI-Manager/issues/2979) 中提到的"自动重装/自动启用可疑节点"行为，正是由于 `security_level = weak` 时缺乏签名校验导致的，建议生产环境保持 `normal`。 资料来源：[glob/security_check.py:1-100]()、[README.md:300-330]()。 ## 故障模式与诊断 根据社区高频问题（[#2374](https://github.com/Comfy-Org/ComfyUI-Manager/issues/2374)、[#2501](https://github.com/Comfy-Org/ComfyUI-Manager/issues/2501)、[#2228](https://github.com/Comfy-Org/ComfyUI-Manager/issues/2228)），后端常见故障可分为以下几类： 1. **更新后菜单消失**：通常是 `manager_server.py` 路由未注册成功，需检查启动日志中 `[ComfyUI-Manager]` 前缀的行； 2. **pip 在 uv 环境中缺失**：当使用 `uv` 创建虚拟环境时，`node_package.py` 仍默认调用 `pip`，可通过 `config.ini` 设置 `use_uv = True`（自 V3.16 起支持，参见 [#1828](https://github.com/Comfy-Org/ComfyUI-Manager/issues/1828)）； 3. **SSL 证书校验失败**：在 `config.ini` 添加 `bypass_ssl = True`； 4. **Windows 事件循环冲突**：添加 `windows_selector_event_loop_policy = True`； 5. **Git 路径未识别**：在 `config.ini` 显式设置 `git_exe = /path/to/git`。 资料来源：[README.md:280-300]()、[glob/cm_global.py:1-40]()。 ## See Also - [Frontend Architecture（前端架构）](./Frontend-Architecture.md) - [Node Database & CNR（节点数据库与注册表）](./Node-Database.md) - [Security Model（安全模型详解）](./Security-Model.md) - [Configuration Reference（配置参考）](./Configuration.md) --- ## Frontend & Node Database ### 相关页面 相关主题：[Backend Architecture](#page-2), [Configuration, Security & Operations](#page-4), [Introduction & Installation Guide](#page-1)
相关源码文件 以下源码文件用于生成本页说明： - [js/comfyui-manager.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/comfyui-manager.js) - [js/custom-nodes-manager.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/custom-nodes-manager.js) - [js/model-manager.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/model-manager.js) - [js/components-manager.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/components-manager.js) - [js/snapshot.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/snapshot.js) - [js/cm-api.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/cm-api.js) - [js/common.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/common.js) - [js/workflow-metadata.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/workflow-metadata.js) - [js/node_fixer.js](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/node_fixer.js) - [node_db/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/node_db/README.md) - [glob/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/README.md) - [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)
# Frontend & Node Database ## 概述 ComfyUI-Manager 的「前端与节点数据库」是 Manager 扩展面向用户的两个核心子系统：前者（Frontend）负责在 ComfyUI 主界面中注入并管理所有 UI 组件，后者（Node Database）负责维护可供安装的 custom nodes 与 models 元数据集合。两者通过 REST API 与 Python 后端进行通信，共同支撑了 ComfyUI 生态的安装、更新、卸载、共享与快照等能力。 资料来源：[README.md]() 描述 Manager 提供了 install / remove / disable / enable custom nodes 的能力，并内置 hub 功能获取节点信息；前端通过 `Manager` 按钮（见主菜单）作为统一入口。资料来源：[js/README.md]() 进一步指出前端采用模块化组件架构，通过 `app.js` 与 ComfyUI 集成。 ## 前端架构与组件层次 ### 集成入口 `comfyui-manager.js` 是前端的主入口，负责初始化 Manager UI 并与 ComfyUI 的 `app.js` 集成。资料来源：[js/comfyui-manager.js]() 承担以下职责： - 注入 "Manager" 按钮至 ComfyUI 主菜单 - 注册路由与扩展点 - 异步加载子模块（custom nodes、models、components、snapshot 等） - 监听 ComfyUI 启动事件并自动调用后端 `/manager` 端点校验状态 ### 模块划分 前端按职责拆分为多个模块，避免主入口膨胀： | 模块 | 主要职责 | 关键源文件 | |------|---------|-----------| | Custom Nodes Manager | 浏览、安装、禁用、启用、修复节点 | [js/custom-nodes-manager.js]() | | Model Manager | 下载模型、整理目录、解析来源 | [js/model-manager.js]() | | Components Manager | 工作流组件（节点组）的导入、导出与共享 | [js/components-manager.js]() | | Snapshot | 安装状态快照与回滚 | [js/snapshot.js]() | | API Wrapper | 封装对后端 REST 端点的异步调用 | [js/cm-api.js]() | | Workflow Metadata | 工作流版本、依赖、资源解析 | [js/workflow-metadata.js]() | | Node Fixer | 重建节点但保留同名连线 | [js/node_fixer.js]() | 资料来源：[js/README.md]() 中明确列出了上述模块以及 `comfyui-share-*` 系列分享组件。`common.js` 提供共享工具函数。 ### 数据流 ```mermaid flowchart LR A[ComfyUI 主界面] --> B[comfyui-manager.js 入口] B --> C[custom-nodes-manager.js] B --> D[model-manager.js] B --> E[components-manager.js] B --> F[snapshot.js] C --> G[cm-api.js] D --> G E --> G F --> G G --> H[(manager_server.py REST API)] H --> I[node_db JSON 缓存 / CNR] H --> J[git / pip 子进程] ``` 资料来源：[glob/manager_server.py]() 是后端 REST API 的实现层；[js/cm-api.js]() 负责把前端请求翻译成对 `/manager/*` 端点的 `fetch` 调用。 ## Node Database（节点数据库）系统 ### 目录与分通道组织 `node_db/` 目录是 Manager 的传统本地节点元数据存储。资料来源：[node_db/README.md]() 描述了子目录结构： - **dev/** — 开发通道：包含最新或实验性节点 - **legacy/** — 历史节点，需要特殊处理 - **new/** — 通过初核、仍在评估的新节点 - **forked/** — 已有节点的衍生分支 - **tutorial/** — 示例与教学节点 每个子目录都包含相同格式的 JSON 文件集：`custom-node-list.json`、`extension-node-map.json`、`model-list.json`、`alter-list.json`、`github-stats.json`。 ### 核心数据模型 #### `custom-node-list.json` Schema ```json { "custom_nodes": [ { "title": "节点显示名", "name": "仓库名", "reference": "若为 fork，指向原始仓库", "files": ["GitHub URL 或其他源"], "install_type": "git", "description": "功能描述", "pip": ["可选 pip 依赖"], "js": ["可选前端文件"], "tags": ["分类标签"] } ] } ``` 资料来源：[node_db/README.md]() 中的 schema 描述，`install_type` 字段决定后端是采用 `git clone` 还是其他安装方式。 #### `extension-node-map.json` Schema ```json { "extension-id": [ ["节点类列表"], { "author": "作者", "description": "扩展描述", "nodename_pattern": "可选正则匹配节点名" } ] } ``` 资料来源：[node_db/README.md]() 的说明，该映射用于把节点类名反查到具体扩展，从而支持 "Install Missing Custom Nodes"（缺失节点安装）功能。资料来源：[README.md]() 展示了 `missing-menu.jpg` 与 `missing-list.jpg` 截图，证实该功能存在于 Manager 菜单中。 ### 与 Custom Node Registry（CNR）并存 资料来源：[node_db/README.md]() 明确指出本地 JSON 系统正逐步迁移到在线的 Custom Node Registry（[https://registry.comfy.org/](https://registry.comfy.org/)），后者提供实时更新、改进的版本支持、更强的安全校验与更丰富的元数据。在过渡期间，Manager 同时支持两套系统。 后端在 README 中描述了三种数据库模式： | DB Mode | 数据源 | 典型场景 | |---------|--------|---------| | Channel (1day cache) | 通道远程缓存（带 1 天有效期） | 默认推荐 | | Local | 本地 `node_db/` JSON | 离线或私有部署 | | Channel (remote) | 实时拉取通道远程数据 | 最新列表 | 资料来源：[README.md]() 中「DB: Channel (1day cache)、DB: Local、DB: Channel (remote)」的说明。 ### Scanner 维护脚本 `node_db/` 各子目录中包含 `scan.sh`，用于更新元数据。资料来源：[README.md]() 描述其行为： 1. 拉取或克隆 `custom-node-list.json` 中列出的仓库到 `~/.tmp/default`，更新 `extension-node-map.json`（可用 `--skip-update` 跳过；自定义路径可通过 `python scanner.py [path]` 指定） 2. 调用 GitHub API 更新 `github-stats.json`（建议设置 `GITHUB_TOKEN`，可用 `--skip-stat-update` 跳过） 3. `--skip-all` 同时跳过上述两步 ## 常见故障与社区反馈 | 故障模式 | 触发条件 | 关联源码 / 文档 | |---------|---------|---------------| | Manager 菜单消失 | ComfyUI 更新后 `extensions/ComfyUI-Manager/comfyui-manager.js` 动态加载失败 | [js/comfyui-manager.js]() — 动态 import；Issue #2374 | | Manager 版本停滞在 3.39.x | 主分支指向 v3，v4 在另一分支 | [README.md]() 关于 v4 beta 的公告；Issue #2501、#2916 | | "bad ux" 静默失败 | `security_level` 默认过严，前端 UI 标记 100% 成功但实际被拒绝 | [README.md]() 安全级别配置；Issue #2900 | | deprecation warning | 旧版字段被废弃（如 `install_type` 变更） | [node_db/custom-node-list.json]() Schema；Issue #2228 | | uv 环境下 pip 缺失 | 使用 `uv` 创建 venv 时未安装 pip | [README.md]() 关于 `use_uv` 的说明；Issue #1828 | | 安装失败但无目录创建（RunPod） | 容器内权限或路径差异 | [glob/manager_core.py]() 安装逻辑；Issue #2985 | | 疑似恶意节点 | CNR 校验未覆盖全部第三方仓库 | [node_db/README.md]() 安全模型；Issue #2979 | 资料来源：[README.md]() 在「Security level」段落定义了 `strong / normal / normal- / weak` 四档，决定 Manager 是否允许 git url 安装、pip install、fix custom nodes 等"高风险操作"。这是 Issue #2900 中"默认配置阻止实际安装"的根因：当 `security_level=strong` 时，仅"Update ComfyUI"一类 low risk 操作可用。 ## See Also - Backend & Security Model — 后端模块与多级安全框架 - Configuration Reference — `config.ini` 全部字段说明 - CNR Migration Guide — 从 `node_db/` 迁移到 [https://registry.comfy.org/](https://registry.comfy.org/) 的步骤 - [ComfyUI Nodes Info](https://ltdrdata.github.io/) — 全部已注册节点信息汇总 - [cm-cli 文档](docs/en/cm-cli.md) — 命令行工具，可在不启动 ComfyUI 的情况下使用 Manager 功能 --- ## Configuration, Security & Operations ### 相关页面 相关主题：[Introduction & Installation Guide](#page-1), [Backend Architecture](#page-2), [Frontend & Node Database](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md) - [glob/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/README.md) - [node_db/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/node_db/README.md) - [js/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/README.md) - [pip_overrides.json.template](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/pip_overrides.json.template) - [pip_overrides.osx.template](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/pip_overrides.osx.template) - [docs/en/v3.38-userdata-security-migration.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/v3.38-userdata-security-migration.md) - [docs/en/use_aria2.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/use_aria2.md)
# Configuration, Security & Operations 本页面集中介绍 ComfyUI-Manager 的**配置体系、安全模型与运维特性**，覆盖 `config.ini`、安全等级、网络模式、PIP 管理、环境变量以及与社区反馈紧密相关的常见故障模式。 ## 配置体系总览 ComfyUI-Manager 的配置由位于受保护用户目录下的 `config.ini` 主导，配合多个辅助列表文件实现灵活的运行时控制。自 V3.38 起，Manager 将自身数据迁移到受保护路径以提升安全性 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)。配置目录按 ComfyUI 版本分两套路径： | ComfyUI 版本 | Manager 路径 | |--------------|--------------| | v0.3.76+（具备 System User API） | `/__manager/` | | 更早版本 | `/default/ComfyUI-Manager/` | 在配置目录中，`config.ini` 负责核心设置，`channels.list`、`pip_overrides.json`、`pip_blacklist.list`、`pip_auto_fix.list`、`snapshots/`、`startup-scripts/` 与 `components/` 等分别承担频道、PIP 覆盖、快照与组件存储职责 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)。 `config.ini` 关键字段语义如下： - `security_level`：控制 Manager 可执行的操作集合，详见下一节。 - `always_lazy_install`：是否在非 Windows 环境下也启用"启动时按需安装依赖"的策略。 - `network_mode`：决定联网策略，可选 `public`、`private`、`offline`。 - `use_uv`：自 V3.16 引入，启用 `uv` 作为 Python 包管理器 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)。 - `file_logging`：默认开启，可写入日志文件用于排障。 社区曾报告"安装失败但前端显示成功"的问题（#2900），其根本原因正是默认 `security_level` 较高，拦截了实际写入目录的安装动作——这要求运维者必须先理解配置语义再启用功能 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)。 ## 安全等级与风险模型 安全模型是 Manager 的核心防护层，由 `glob/security_check.py` 实现五级策略 资料来源：[glob/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/README.md)： ```mermaid flowchart LR A[请求进入] --> B{security_level} B -->|block| X[拒绝几乎所有远程操作] B -->|high| H[仅允许受信任操作] B -->|middle| M[标准用户操作] B -->|normal-| N[高级用户操作] B -->|weak| W[开放开发环境操作] X --> R[审计/阻断] H --> R M --> R N --> R W --> R ``` 按风险类别映射操作的具体能力如下 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)： - **high**：通过 Git URL 安装、`pip install`、非默认频道节点安装、Fix Custom Nodes。 - **middle**：卸载/更新、默认频道节点安装、恢复/移除快照、重启 ComfyUI。 - **low**：更新 ComfyUI 本体。 `node_db` 通道采用 channel-based 架构，对每个节点评估 risk level，从而在 UI 中以"yellow"标识冲突节点并提示用户谨慎安装 资料来源：[node_db/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/node_db/README.md)。结合社区报告（#2979），针对"自动重装、隐藏 ID、绕过卸载"等可疑节点行为，安全模型正是用户判断可疑包的第一道防线。 ## 网络、PIP 与下载器运维 ### 网络模式 `network_mode` 字段提供三种工作形态 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)： - `public`：典型公网环境，直接访问 GitHub/Hugging Face。 - `private`：封闭网络，使用 `channel_url` 指向私有节点数据库，离线时回退缓存。 - `offline`：完全离线，优先命中本地缓存。 环境变量 `GITHUB_ENDPOINT` 与 `HF_ENDPOINT` 可对 GitHub/Hugging Face 请求做反向代理重定向，常用于中国大陆或受限网络环境 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)。 ### PIP 管理 Manager 在 PIP 维度提供四类控制文件： - `pip_overrides.json`：将特定包名映射到指定版本，模板见 `pip_overrides.json.template` 与 `pip_overrides.osx.template`。 - `pip_blacklist.list`：每行一个包名，阻止安装。 - `pip_auto_fix.list`：类 `requirements.txt` 的清单，启动时自动校正版本漂移；支持 `--index-url`。 - `use_uv`：启用 `uv` 后由 `manager_core.py` 调度 Python 依赖。 社区反馈 #1828 指出：当通过 `uv` 创建 venv 且仅安装 `requirements.txt` 时，`pip` 并不存在，Manager 的安全扫描会失败并提示 `No module named pip` 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)。运维建议：在启用 `use_uv` 的环境中确保 `pip` 可用，或通过 `pip_auto_fix.list` 显式声明关键包版本。 ### aria2 下载器 对大体积模型文件，可在 `config.ini` 中启用 `aria2` 以获得多连接分片下载，详见 `docs/en/use_aria2.md` 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)。`glob/manager_downloader.py` 负责对接下载任务队列，异步执行以避免阻塞 UI。 ## 常见故障与运维指引 根据社区高互动问题与代码实现，常见故障可分为以下几类： 1. **Manager 菜单消失**（#2374、#328）：通常出现在解压安装到错误路径（`ComfyUI/custom_nodes/ComfyUI-Manager/` 双层嵌套）后，前端动态导入失败。必须严格按 `ComfyUI/custom_nodes/comfyui-manager` 单层目录部署 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)。 2. **版本卡在旧版**（#2501）：便携版 ComfyUI 未通过 `git pull` 同步仓库，需重装 Manager 目录或升级 ComfyUI 至支持 System User API 的版本以使用新路径 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)。 3. **v3 到 v4 升级困惑**（#2916）：v4 在 beta 分支，需手动切换；建议关注 `config.ini` 中新增字段并查阅 v3.38 迁移指南 资料来源：[docs/en/v3.38-userdata-security-migration.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/v3.38-userdata-security-migration.md)。 4. **DEPRECATION WARNING**（#2228）：通常由旧 API 调用或前端资源过期触发，需清缓存并重启 ComfyUI。 5. **RunPod 等容器中节点"安装成功但目录未创建"**（#2985）：容器工作目录或 `custom_nodes` 路径与 `config.ini` 中 `extra_model_paths.yaml` 的 `is_default` 段不一致，Manager 将写入错误的根目录 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)。 为快速排障，可启用 `file_logging = True`，日志文件位于 Manager 用户目录下，配合 `cm-cli` 在无 GUI 环境中复现安装/恢复流程 资料来源：[README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/README.md)。 ## See Also - 节点数据库与 CNR 迁移：[node_db/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/node_db/README.md) - 后端核心模块：[glob/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/glob/README.md) - 前端 UI 实现：[js/README.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/js/README.md) - v3.38 数据迁移指南：[docs/en/v3.38-userdata-security-migration.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/v3.38-userdata-security-migration.md) - aria2 下载器配置：[docs/en/use_aria2.md](https://github.com/Comfy-Org/ComfyUI-Manager/blob/main/docs/en/use_aria2.md) --- --- ## Doramagic 踩坑日志 项目：Comfy-Org/ComfyUI-Manager 摘要：发现 12 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Need clear steps for update to v4, what to expect。 ## 1. 安装坑 · 来源证据：Need clear steps for update to v4, what to expect - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Need clear steps for update to v4, what to expect - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI-Manager/issues/2916 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：bad ux - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bad ux - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI-Manager/issues/2900 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 3. 配置坑 · 来源证据：Colour button stuck on far left of tabs bar - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Colour button stuck on far left of tabs bar - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI-Manager/issues/2969 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 4. 安全/权限坑 · 来源证据：I may be experiencing a similar issue on RunPod. - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：I may be experiencing a similar issue on RunPod. - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI-Manager/issues/2985 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 5. 安装坑 · 来源证据：The ComfyUI jhj Kokoro Onnx node looks malicious. - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：The ComfyUI jhj Kokoro Onnx node looks malicious. - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI-Manager/issues/2979 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 6. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | github_repo:631600154 | https://github.com/Comfy-Org/ComfyUI-Manager | README/documentation is current enough for a first validation pass. ## 7. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | github_repo:631600154 | https://github.com/Comfy-Org/ComfyUI-Manager | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | github_repo:631600154 | https://github.com/Comfy-Org/ComfyUI-Manager | no_demo; severity=medium ## 9. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | github_repo:631600154 | https://github.com/Comfy-Org/ComfyUI-Manager | no_demo; severity=medium ## 10. 安全/权限坑 · 来源证据：[Node request] Anomalous Model Browser - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Node request] Anomalous Model Browser - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/Comfy-Org/ComfyUI-Manager/issues/2951 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 11. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | github_repo:631600154 | https://github.com/Comfy-Org/ComfyUI-Manager | issue_or_pr_quality=unknown ## 12. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | github_repo:631600154 | https://github.com/Comfy-Org/ComfyUI-Manager | release_recency=unknown