把 ComfyUI 部署到服务器上：`--listen`、目录参数与日志落盘的完整启动命令

2026-08-09

本地跑 ComfyUI 和把它放到一台服务器上跑，中间隔的不是”多加一个 --listen”这么简单。默认配置是按”自己电脑上自己用”设计的：只听本机、上传体积有上限、日志往终端打。一旦这台机器有别人能访问，这几个默认值的含义全都变了。

下面这些参数语义，全部以 ComfyUI v0.31.0（核对日 2026-08-09）的 comfy/cli_args.py 为准。ComfyUI 版本节奏很快，参数和默认值会随版本变动，落地前请以 python main.py --help 的实际输出为准。

动手之前：先确认版本，这一步不能跳

服务器部署最怕的是把一个旧版本长期挂在网上。ComfyUI 在 2026-07-15 一次性发布了四条 GitHub Security Advisory，严重等级均为 high，修复版本均为 0.28.0：

GHSA ID	等级	官方 summary	修复版本
GHSA-rj8c-c4p8-3c5h	high	Stored XSS via SVG file upload on the `/view` endpoint	0.28.0
GHSA-53g8-45wq-pcv8	high	Stored XSS via `/userdata/{file}` due to missing Content-Type sanitization	0.28.0
GHSA-rvxv-29p8-pxgq	high	Path traversal in LoadImage via the `/prompt` API allows arbitrary file existence probing and image exfiltration	0.28.0
GHSA-pj59-g5vv-74q4	high	Path traversal in `/experiment/models/preview` allows arbitrary image file read	0.28.0

对应的 release note 是 v0.28.0（2026-07-15）里那条「security: fix four vulnerabilities（GHSA-779p-m5rp-r4h4），PR #14734」。结论很直接：运行 0.28.0 之前版本的实例存在这四个 high 级问题。这是少有的可以硬气地说”请升级”的场合。

顺带提一个真实教训：这次安全修复的 PR #14734 后来引出了一个回归——v0.30.0（2026-08-03）有一条「Fix user.css loading broken by #14734」（PR #15000），也就是前端资源加载被修坏了，两周后才补回来。所以升级不是”升上去就完事”，升完照样要过一遍你自己的验收动作。

网络这一层：`--listen` 的三种写法差别很大

--listen 的默认值是 127.0.0.1，也就是只听本机。这解释了绝大多数”部署完局域网访问不到”的现象——不是防火墙，是它压根没往外听。

但这个参数有个容易踩的细节：不带参数使用 --listen 时，值是 0.0.0.0,::，等于监听所有 IPv4 与 IPv6 网卡。它还支持逗号分隔多个地址，help 里给的例子是 127.2.2.2,127.3.3.3。

所以服务器上有三种常见写法，含义完全不同：

--listen（不带值）：对所有网卡开放，包括公网网卡（如果这台机器有的话）
--listen 127.0.0.1：仍然只听本机，适合前面挂反向代理的场景
--listen 10.0.0.5：只听某一张内网网卡

服务器上更稳妥的是第二种或第三种写法。“不带值的 --listen” 看起来最省事，但按 help 的语义，它是把暴露面从”本机”一次性放大到”这台机器所有网卡”，很少有场景真的需要这么宽。

端口用 --port 指定，默认是 8188。

上传体积与响应压缩

--max-upload-size 是 float 类型，默认 100，单位 MB。做视频或高分辨率素材时这个默认值会顶到；调大它是明牌操作，但要意识到你同时也放大了别人往这台机器塞东西的余量，不要习惯性写一个很夸张的数。

--enable-compress-response-body 是一个 flag，作用是启用响应体压缩。在服务器与浏览器之间跨网段、带宽不宽裕时值得开。

`--multi-user` 是”按用户分离存储”，不是登录

这是本篇最需要点破的一处误读。--multi-user 在 cli_args.py 里的 help 原意是启用按用户分离的存储——它管的是数据怎么放，不是”谁能进来”。

认证是什么现状？官方仓库 issue #987 提出了「[Feature Request] Add authentication with username and password arguments」，创建于 2023-07-27，标签为 Feature，有 26 个 reactions，截至 2026-08-09 仍为 open。也就是说，用户名密码认证到今天仍然是一个开着的功能请求。

这里要说得准确一点：这不等于”ComfyUI 没有任何鉴权”。v0.23.0 确实新增过 OAuth 2.1 与 RFC 7591 DCR endpoints（PR #14026）。两件事不冲突，但都不足以支撑”服务器上开了 --multi-user 就有账号体系了”这种结论。把 --multi-user 当登录用，是这份参数表里最容易被误读成安全能力的一处。

目录参数：`--base-directory` 与五个单项谁赢

服务器上模型和输出通常要落到独立的数据盘，所以目录参数几乎必用。

--base-directory 是”一把抓”，一次性设置 models、custom_nodes、input、output、temp、user 六类目录的基准目录。此外还有五个单项参数：--output-directory、--temp-directory、--input-directory、--user-directory、--models-directory，help 里对它们都写了 Overrides --base-directory（--models-directory 是覆盖 --base-directory 里的 models 文件夹）。

规则因此很清楚：两者同时给，单项赢。 典型服务器排布是——--base-directory 指向数据盘，再单独把 --output-directory 挑出来指向另一块盘或另一个挂载点。

还有一处启动期差异值得记住：--user-directory（要求绝对路径）与 --models-directory 在启动时会校验路径必须已存在、是目录且可读；而 --base-directory 的校验路径不同（源码里没走 is_valid_directory）。这意味着目录写错时，前者会在启动阶段就拦下你，后者不一定。第一次部署建议先把 --user-directory 显式写出来，让它替你把路径拼写错误暴露在启动那一刻。

模型分散在多处的话，用 --extra-model-paths-config PATH [PATH ...] 加载一个或多个 extra_model_paths.yaml，这个参数可以重复 append。

日志落文件：`--verbose` 的两段式写法

服务器上没人盯着终端，日志必须落盘。--verbose 的接受形式是：不带值、给一个 LEVEL、或者给 LEVEL FILE 两个值；并且可以重复使用以增加输出目标。

合法等级常量是 ('DEBUG', 'DETAIL', 'INFO', 'WARNING', 'ERROR', 'CRITICAL')。不带值时等价于 DEBUG。控制台等级取所有”无文件”输出里最详细的那一个，默认是 INFO。参数写错时的报错文案是 expects no values, a console LEVEL, or LEVEL FILE——看到这句就知道是 --verbose 的形参组合非法，不用往别处查。

DETAIL 这一级来自 v0.30.0 的「可配置 DETAIL 日志侧通道」（PR #15064），属于较新的等级，旧版本上没有，跨版本抄启动脚本时留意。

另外 --log-stdout 会把正常进程输出送到 stdout，默认是 stderr。用 systemd 或容器收集日志时，如果不改这个默认值，正常输出就会走 stderr 通道，看上去像”日志全被当成错误流”。

组合成一条完整的启动命令

Linux / macOS 侧：

python main.py \
  --listen 127.0.0.1 \
  --port 8188 \
  --base-directory /srv/comfyui-data \
  --output-directory /srv/comfyui-out \
  --user-directory /srv/comfyui-data/user \
  --max-upload-size 512 \
  --enable-compress-response-body \
  --multi-user \
  --disable-api-nodes \
  --log-stdout \
  --verbose INFO /srv/comfyui-data/logs/comfyui.log \
  --verbose WARNING

逐条说明为什么它在这：

--listen 127.0.0.1：显式写死只听本机，把”对外怎么访问”这件事交给前面的反向代理去决定，而不是让 ComfyUI 自己敞着
--port 8188：写成显式值，方便和代理配置、健康检查脚本对上
--base-directory + --output-directory + --user-directory：一把抓做基准，输出单独挑出去；--user-directory 显式给，是为了拿到它的启动期路径校验
--max-upload-size 512：默认 100MB 对素材上传偏紧，按需要抬高
--enable-compress-response-body：跨网段访问时压一压响应体
--multi-user：启用按用户分离的存储（再强调一次，它不提供登录）
--disable-api-nodes：help 原意是不加载所有 api 节点，同时阻止前端与互联网通信；服务器实例不需要付费 Comfy API 节点时，关掉能让内置功能保持离线
--verbose INFO <日志文件> 加一条 --verbose WARNING：前者把 INFO 级写进文件，后者作为”无文件”输出决定控制台等级；这是按 help 里”可重复使用以增加输出目标""控制台等级取所有无文件输出里最详细的一个”两句组合出来的写法
--log-stdout：让正常输出走 stdout，配合日志收集

Windows 侧写成一行，注意路径分隔符和续行符都不同（PowerShell 用反引号续行，这里直接给单行版更省事）：

python main.py --listen 127.0.0.1 --port 8188 --base-directory D:\comfyui-data --output-directory E:\comfyui-out --user-directory D:\comfyui-data\user --max-upload-size 512 --enable-compress-response-body --multi-user --disable-api-nodes --log-stdout --verbose INFO D:\comfyui-data\logs\comfyui.log --verbose WARNING

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

这条命令跑起来之后，东西都落在哪

启动日志会逐行打印什么，我们没有依据描述，所以这一节只讲由参数语义能确定的落点——这些恰恰是你事后要去翻的地方：

东西	落到哪	依据
生成结果	`--output-directory` 指定的目录（`/srv/comfyui-out`）	单项参数覆盖 `--base-directory`
models / custom_nodes / input / temp / user	`--base-directory` 下对应的六类目录之一	`--base-directory` 是一次性设置这六类的基准目录
user 数据	`--user-directory` 指定的绝对路径	单项覆盖，且启动时校验存在/是目录/可读
日志文件	`--verbose INFO <路径>` 里给的那个文件	`LEVEL FILE` 两值形式的语义
控制台输出	走 stdout（因为加了 `--log-stdout`），等级由那条无文件的 `--verbose WARNING` 决定	控制台等级取所有无文件输出里最详细的一个

有两处默认值容易被忽略。一是 temp 目录默认在 ComfyUI 安装目录内，如果系统盘空间紧张，要么靠 --base-directory 一起挪走，要么单独给 --temp-directory。二是数据库，--database-url 的默认值是 sqlite:///<ComfyUI>/user/comfyui.db；官方 help 只给了这个默认值，并没有说明它和 --user-directory 之间怎么联动，所以真要把数据也放到数据盘，稳妥做法是把 --database-url 显式写出来，而不是指望它跟着 user 目录走。

需要走 https 时：TLS 参数必须成对

--tls-keyfile 与 --tls-certfile 有一条硬约束：必须同时给出才生效，只给一个不会启用 TLS。生效后应用走 https://。

README 给出的自签证书生成命令是：

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-keyfile key.pem --tls-certfile cert.pem 启动。

但 README 自己明确注明，这个自签证书 “not appropriate for shared/production use”（不适合共享或生产使用）。 这句必须记住——官方对自己的示例都没打包票，我们更不该把它当成生产方案。Windows 用户执行上面这条命令可以用 alexisrolland/docker-openssl 或第三方 OpenSSL 二进制发行版；容器场景下 -v 支持相对路径，例如 ... -v ".\:/openssl-certs" ... 会把 key 与 cert 生成到当前目录。

至于反向代理、防火墙规则这类做法：它们属于通用运维做法，不是 ComfyUI 官方文档内容，本文不给具体配置。

起来之后怎么验收

启动日志的具体内容我们没有依据逐行描述，所以验收动作落在这几处可自查的地方：

端口有没有按预期监听。在服务器本机用你熟悉的端口查看工具确认 8188 的监听地址，重点是核对它是 127.0.0.1 还是 0.0.0.0 ——这一处最能反映 --listen 是否按你想的那样生效。带不带值的差别就体现在这里。
日志文件是否真的生成了。去 --verbose 指定的那个路径看文件在不在、有没有在增长。日志目录不存在是最常见的第一次失败点，先把目录建好。
目录是否落到你规划的位置。跑一次最简单的工作流，看输出是否出现在 --output-directory 指定的目录，而不是 ComfyUI 安装目录内的默认 output。temp 目录默认在 ComfyUI 目录内，如果数据盘和系统盘分离，记得一并用 --temp-directory 挪走。
启动阶段没有被路径校验拦下。--user-directory 与 --models-directory 写错会在启动时报错，这是好事——它比”跑了半天发现模型没扫到”要便宜得多。
开了 TLS 就必须用 https:// 访问验证，还留在 http:// 上说明参数没成对生效。

按参数语义倒推，最容易出错的一步集中在三处：日志目录没预先创建、--listen 写了不带值的版本导致暴露面超预期、--base-directory 与单项参数互相打架导致结果和预期不一致。这三处都不会以”报错”的形式提醒你——前两处照样能起来，第三处只是把文件写到了别处。

什么情况下别这么部署

不要把它当多租户服务对外开放。 前面说过，--multi-user 只是存储分离，用户名密码认证仍是 open 的 feature request #987。给不特定人群开放访问，需要你在 ComfyUI 之外自己解决身份这一层，而这不在本文和官方参数覆盖的范围内。
不要用自签证书顶生产。 README 原话已经把这条堵死了。
自定义节点是独立的风险面。 社区在 issue #11791 中报告了通过 Comfy Registry 分发的名为 Upscaler_4K 的自定义节点携带 Akira Stealer 的情况，该 issue 创建于 2026-01-10，截至 2026-08-09 仍为 open。服务器实例上装第三方节点，请自己评估。官方在参数层面给了对应手段：--disable-all-custom-nodes 不加载任何自定义节点，--whitelist-custom-nodes NAME [NAME ...] 在前者开启时仍加载指定目录。这两个组合起来也是排查的利器——--disable-all-custom-nodes 能起来，说明问题在自定义节点侧，再用白名单逐步放行定位。
需要 Manager 后台能力时注意 --disable-manager-ui 的语义：它只禁用 Manager 的 UI 与端点，计划中的安装等后台任务仍会运行（README 补充说安全检查、计划安装完成这类后台功能保留），要配合 --enable-manager 使用。以为”禁了 UI 就什么都不会跑”是错的。
最后一条：上面这些开关都只是官方提供的能力边界，不构成”配好就没风险”的结论。把一台跑推理的机器放到网络上，风险要按你自己的环境评估。

延伸阅读

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