让 ComfyUI 完全离线跑：`--disable-api-nodes` 之外还要关掉哪些出网路径

2026-08-09

「我们内网不能出网，ComfyUI 能跑吗」——这个问题在交付现场几乎每次都会被问一遍。答案是能，但「能离线跑」和「我这条启动命令确实一个包都不往外发」是两件事，中间隔着几个不太显眼的参数。

先把官方口径摆出来。ComfyUI 的 README 在 Features 里写的是：完全离线运行，核心不会下载任何东西，除非你要求；用 --disable-api-nodes 关掉可选的付费 Comfy API 节点，强制所有内置功能保持离线。这句话有两层意思要拆开读——「核心不下载」说的是默认行为，「除非你要求」说的是你只要传了某些参数，它就会去下载。离线部署翻车基本都翻在后半句上。

下文所有参数一律以 v0.31.0（2026-08-08）的 comfy/cli_args.py 为准。ComfyUI 大约每两周一个版本，参数名和默认值都会动，落地前请以你那台机器上 python main.py --help 的实际输出为准。

一、先把这条命令抄走

Linux / macOS 侧：

python main.py \
  --disable-api-nodes \
  --disable-all-custom-nodes \
  --listen 127.0.0.1 \
  --port 8188 \
  --base-directory /srv/comfy-data \
  --extra-model-paths-config /srv/comfy-data/extra_model_paths.yaml \
  --disable-auto-launch \
  --verbose DEBUG

Windows 侧（PowerShell，一行写完，路径按你自己的盘符改）：

python main.py --disable-api-nodes --disable-all-custom-nodes --listen 127.0.0.1 --port 8188 --base-directory D:\comfy-data --disable-auto-launch --verbose DEBUG

以上为按官方参数语义组合的示例，未逐项实测，以官方文档与 --help 输出为准。

逐项说说每个选项为什么在这：

--disable-api-nodes：help 原文是「不加载所有 api 节点，同时阻止前端与互联网通信」。注意后半句——这个参数不只是少注册一批节点，它连带管住了前端那一侧的联网行为。离线部署里它是第一个要加的，也是唯一一个 README 明确点名用来「强制内置功能保持离线」的开关。
--disable-all-custom-nodes：help 原文就一句「不加载任何自定义节点」。离线机器上加它的理由不是省内存，而是把不确定性砍掉：自定义节点的代码不在官方仓库里，它在 import 阶段会不会去连点什么，官方文档不会替你保证。如果你确实有几个必须用的节点，配套参数是 --whitelist-custom-nodes NAME [NAME ...]，help 写的是「在开启上一条时，仍然加载指定的自定义节点目录」——这是白名单模式，比全开安全得多。
--listen 127.0.0.1：--listen 默认值就是 127.0.0.1，写出来是为了防手滑。这个参数不带参数值时等于 0.0.0.0,::，也就是所有 ipv4 与 ipv6 网卡全听。离线部署最讽刺的翻车方式，是出网确实断了，结果服务面向整个内网敞开。
--base-directory：help 说它一次性设置 models、custom_nodes、input、output、temp、user 六类目录的基准目录。离线机上模型多半在单独的数据盘，用它一把抓最省事。如果某一类要单独挪，用 --output-directory / --models-directory 这些单项参数覆盖——源码里单项是 Overrides --base-directory 的，二者同时给时单项赢。另外 --models-directory 和 --user-directory 会在启动时校验路径存在、是目录、可读，而 --base-directory 在源码里走的不是同一套校验，所以别指望它替你把路径写错这件事挡下来。
--extra-model-paths-config：加载 extra_model_paths.yaml，可以重复 append 多个。仓库里给的是 extra_model_paths.yaml.example，改名后编辑即可让 ComfyUI 去别处找模型、和其它 UI 共享同一份模型库。standalone windows 构建里这个文件就在 ComfyUI 目录下。
--port 8188：默认值本来就是 8188，写出来同样是为了让这条命令自解释——内网机器上端口经常要按运维规范挪，把它显式写在脚本里，改的时候不用去翻默认值。
--disable-auto-launch：和 --auto-launch 是一对。源码里 --disable-auto-launch 最后生效，会把 auto_launch 置假。离线机往往是无头服务器或者远程连过去的，别让它启动时去拉浏览器。顺带提一句，--windows-standalone-build 在源码里会把 auto_launch 置真，用 standalone 包起服务时这条尤其值得加。
--verbose DEBUG：--verbose 可以不带值、给一个 LEVEL、或者给 LEVEL FILE 两个值，合法等级是 DEBUG、DETAIL、INFO、WARNING、ERROR、CRITICAL，不带值时等价于 DEBUG，控制台默认等级是 INFO。离线首启建议拉到 DEBUG，因为你要靠日志确认加载路径。顺带一提 DETAIL 这一级是 v0.30.0 新加的，老版本上没有。

二、前端这道坎：`--front-end-version` 和离线是冲突的

这是本篇最值得单独拎出来的一条。

--front-end-version 的默认字符串是 comfyanonymous/ComfyUI@latest，格式为 [repoOwner]/[repoName]@[version]。它的 help 明确注明：该命令需要联网，去 GitHub releases 查询和下载可用的前端实现。

也就是说，一个用来「拿最新前端」的参数，天然要求出网。很多人是从教程里抄启动脚本的，教程里为了让读者用上每日版前端，往往会带一句 --front-end-version Comfy-Org/ComfyUI_frontend@latest。这条抄进离线机器的启动脚本，等于给自己埋了一个必然失败的联网动作。

离线场景下的正确姿势有两种：

什么都不加，用随包安装的那份前端。README 的 Frontend Development 章节说明，2024-08-15 起前端迁到独立仓库 Comfy-Org/ComfyUI_frontend，编译产物发布到 pypi 的 comfyui-frontend-package 并作为 ComfyUI 的依赖安装；v0.31.0 的 requirements.txt 里 pin 的是 1.48.7。既然它是依赖包，装 core 的时候就一起装进来了，跑起来不需要再去 GitHub 要一次。
用 --front-end-root PATH，指向一个本地前端目录。它的语义是 Overrides --front-end-version，并且会校验目录存在与可读。适合你已经在一台能出网的机器上备好了前端产物，再整体搬进内网的情况。

顺便记一个版本关系：主仓库里的前端每两周更新一次，独立仓库有每日发布。离线机器天然拿不到每日版，这不是故障，是你选了离线就该接受的代价。

三、`--comfy-api-base` 是个配置项，不是开关

--comfy-api-base 的默认值是 https://api.comfy.org，help 说它设置的是 ComfyUI API 的 base URL。

会有人想到「那我把它指到一个内网地址，不就出不去了吗」。这个念头要打住：官方文档只说了它能改 base URL，没有任何一句话说明改了它就等于切断了其它出网路径。真正被 README 指名用于「强制内置功能保持离线」的参数只有 --disable-api-nodes。把 --comfy-api-base 当成离线开关用，属于拿一个配置项去承担安全边界的职责，风险自负。

它值得知道的地方在于排查：当你看到一个和 api.comfy.org 相关的连接尝试时，你至少知道这条链路存在一个可配置的 base，而不是硬编码。

四、Manager 与「后台任务」的边界

ComfyUI-Manager 的官方定位是「方便地安装、更新和管理 ComfyUI 的自定义节点」的扩展，启用方式是先 pip install -r manager_requirements.txt，再 python main.py --enable-manager。

离线机器上要注意的是这组开关的边界：--disable-manager-ui 的 help 写的是「只禁用 Manager 的 UI 与端点，计划中的安装等后台任务仍会运行」，README 补充说安全检查、计划安装的完成流程等后台功能会保留，且这个参数要求已经开了 --enable-manager。

也就是说，「我把 Manager 的界面关了」和「Manager 什么都不做了」不是一回事。这些后台任务具体有没有网络行为，官方文档没有写，我们也没有读过它的源码，所以不替它下结论——但在一台要求严格离线的机器上，最省事的选择是根本不传 --enable-manager，让这套东西压根不上场。

五、产出物长什么样：文件先落位，别指望它替你下载

离线部署的活儿，大头其实在启动之前。README 明确的目录约定只有这么几条，照着放就行：

内容	目录
小模型 / checkpoint	`ComfyUI/models/checkpoints`
VAE	`ComfyUI/models/vae`
textual inversion 与 embedding	`ComfyUI/models/embeddings`
TAESD 预览解码器	`ComfyUI/models/vae_approx`

其余模型 README 只说「按各模型说明放进 ComfyUI\models\ 下对应子目录」，没有给完整清单，别照着别的教程猜子目录名——放错位置，ComfyUI 就是找不到这份模型，而离线机上它也不会替你去别处补一份回来。

预览这块是离线场景里最容易被忘掉的一处。--preview-method 的取值是 none / auto / latent2rgb / taesd，而源码里的默认是 none。README 的说法是：用 --preview-method auto 开启预览，默认安装自带一个低分辨率的快速 latent 预览；想要更高质量的预览，需要下载 TAESD 的 taesd_decoder.pth、taesdxl_decoder.pth、taesd3_decoder.pth、taef1_decoder.pth 放进 models/vae_approx，重启后用 --preview-method taesd 启动。这四个文件必须在联网的那台机器上先下好一起搬过去，离线机不会自己去取。

启动之后能确认的产出物，我们有依据的只有两类：一是日志，--verbose 决定它的详细程度（控制台默认等级是 INFO，--log-stdout 可以把正常进程输出从 stderr 改到 stdout）；二是目录，输出会落到 --base-directory 或 --output-directory 指定的位置。至于日志具体打哪几行、界面上会弹什么提示，官方文档没有逐行给出，各版本也不一样，我们不替它下结论——别按别人的截图去对，以你自己屏幕上的为准。

六、怎么验收「真的没出网」

按依赖强弱排，从最硬的证据往下：

python main.py --help 自证。第一步不是跑工作流，是确认你机器上这个版本确实有 --disable-api-nodes、--disable-all-custom-nodes、--front-end-root 这几个参数，且 help 文本和你预期一致。参数随版本增删，抄来的脚本在新版本上静默失效是常事。
物理断网跑一遍完整业务链路。把网卡禁掉（或拔线），从启动到出图/出视频完整走一遍你真正要用的那个工作流。这一步能过，说明这条链路上没有必须联网的环节。这是最没有技术含量、也最可信的验收方式。
系统层出站阻断 + 观察。在防火墙上对运行 ComfyUI 的那个 Python 进程做出站拒绝并开日志，再跑一遍工作流，看有没有被拒记录。这是通用运维做法，不是 ComfyUI 官方文档的内容，具体命令按你们的操作系统与安全基线来，我不在这里给一条可能不适用于你环境的规则。

人最容易在哪一步出错？按顺手程度排：一是启动脚本里留着从教程抄来的 --front-end-version；二是 --listen 被顺手写成不带参数值的形式，出网是断了、内网全开；三是模型和 TAESD 解码器只搬了一半，启动那一刻看不出来，等工作流跑到用它的那个节点才暴露。

七、什么情况不适用

这套做法有明确的边界，下面几种情况别硬上：

你的工作流依赖 API 节点。 README 说 API 节点提供的是对闭源模型的访问，举的例子是 Nano Banana、Seedance、Hunyuan3D。既然是「访问闭源模型」，这条链路本身就依赖出网，--disable-api-nodes 一加，它就没了。这不是配置能绕过去的取舍，是你得先决定业务上要不要这类模型。
你需要每日版前端。 前面说过，每日发布在独立仓库，--front-end-version 又要求联网。离线机上你只能吃随包 pin 的那个版本（v0.31.0 是 1.48.7），或者走 --front-end-root 人工搬运。想要「离线 + 永远最新前端」，这两件事本身就打架。
你要靠 Manager 装节点。 Manager 的定位就是装和更新自定义节点，离线机上这件事做不成，节点得在别处准备好再整体搬进来。
你严重依赖 partner / API 节点的工作流长期可用。 这条和离线无关，但值得在同一场评估里想清楚：release notes 里能看到 partner 节点被移除的实例，比如 v0.28.0 移除了 StabilityAI 节点（PR #14737）、移除了 IdeogramV1 与 IdeogramV2 节点（PR #14712），v0.31.0 移除了 Kling 已退役的 legacy 模型与 Virtual Try-On API（PR #15249）。上游模型退役 → 节点被移除 → 老工作流打不开，是有实例支撑的风险，升级前值得翻一眼 release notes 的移除条目。

最后说句实在的：离线部署的难点从来不在 ComfyUI 的参数，而在「搬运清单」——模型、前端产物、预览解码器、你要的那几个自定义节点目录，哪一样漏了都是白跑一趟内网机房。参数这部分，--disable-api-nodes 加上 --disable-all-custom-nodes 基本就是官方给的全部答案了，剩下的靠清单和验收流程兜。

延伸阅读

本文依据 ComfyUI 官方仓库（github.com/Comfy-Org/ComfyUI）的 README、comfy/cli_args.py、 release notes 与官方安全公告整理，核对日 2026-08-09，对应版本 v0.31.0；文中引用的 issue 状态为该日期的快照。本文内容为官方文档与源码口径，非本机实测。参数、默认值与功能随版本变动，请以官方文档与 python main.py --help 的实际输出为准。