ComfyUI 的 assets 系统、数据库与 blake3 哈希：`--enable-assets` 到底要不要开

先把结论摆前面：在 ComfyUI v0.31.0（2026-08-08）上，assets 系统和它配套的 blake3 内容哈希都是默认关闭的，而且是两个独立的开关。你不主动加参数，它们一行代码都不跑。这一点跟很多人的印象不太一样——不少人以为「新版 ComfyUI 会自动给模型建索引」，实际上按 comfy/cli_args.py（v0.31.0）的定义，你得自己 opt in。

这就带来一个很现实的问题：既然默认关着，那我开不开？官方 help 文本里其实把收益和代价都写了，只是写得非常克制。下面按参数一个个拆。

一、--enable-assets 启用的是三样东西

comfy/cli_args.py（v0.31.0）里 --enable-assets 是一个 flag，help 的描述是：启用 assets 系统，具体包括 API 路由、数据库同步、后台扫描。

这三个词值得逐个念一遍，因为它们决定了这个开关的影响面：

• API 路由：意味着开启后服务端会多出一组与资产相关的 HTTP 端点。具体是哪些路径、请求格式怎么写，help 里没有列，官方 README 里也没有对应的清单，所以本文不给端点名——凡是你在别处看到的具体 assets 端点路径，请自己回源码确认。
• 数据库同步：assets 的状态要落到数据库里，而这个数据库就是下面第二节要讲的 --database-url 指向的那个。也就是说，--enable-assets 和 --database-url 是配套的，不是两个不相干的功能。
• 后台扫描：这是最容易被忽略的一条。help 给的就是「后台扫描」四个字，扫描对象的具体范围它没有展开。不过同一份 cli_args.py 里 --enable-asset-hashing 的 help 把代价明确挂钩在「大模型目录」上，所以模型目录的规模至少是这条线上的一个成本变量。

注意 help 里只说了「启用」，没有说扫描的触发时机、频率、增量策略。这几点卡不到官方原文，我就不替它编。你要是打算把 assets 系统用在自动化流程里，这些行为得自己在源码里确认，别按直觉假设它是「启动时扫一次然后监听文件变化」。

二、--database-url：默认落在 user 目录下的 sqlite

--database-url 的默认值是：

sqlite:///<ComfyUI>/user/comfyui.db

help 里另外举了一个例子——内存库可以写成：

python main.py --database-url sqlite:///:memory:

这两条信息组合起来，能推出几个实际用法上的判断：

第一，默认它是有状态的。 数据库文件落在 user/ 目录下，也就是跟你的用户设置、工作流放在同一层。你要做备份或者迁移机器，这个文件属于「要一起带走」的那一类，不是可以随手删的缓存。

第二，内存库的写法是官方给的，用途要自己想清楚。 sqlite:///:memory: 是 sqlite 自身的通用写法，库不落盘、随进程结束消失——这是 sqlite 的语义，不是 ComfyUI 的特殊行为。它适合什么场景？我能想到的是 CI、临时容器、或者你只是想验证某个行为跟数据库里的旧状态没关系。但 help 只给了这个写法本身，没有说「推荐在什么场景用」，所以别把它当成官方推荐的生产配置。

第三，数据库路径和 --user-directory 的关系，官方 help 没有明说。 默认值里写的是 <ComfyUI>/user/，而 --user-directory 这个参数确实可以把 user 目录改到别处（它会在启动时校验路径存在、是目录、可读）。但「改了 user 目录之后默认数据库会不会跟着走」这一点，cli_args 的 help 文本没有写。这一点官方没给明确说明，本文不做推断——你如果同时用这两个参数，最稳妥的做法是干脆把 --database-url 显式写全，别赌默认行为。

底层用的是什么？看依赖就知道：requirements 里有 SQLAlchemy>=2.0.0 和 alembic。SQLAlchemy 是 ORM，alembic 是它配套的迁移工具。alembic 出现在依赖里，只能说明官方为这个库准备了迁移工具链；具体在什么时机、以什么方式跑迁移，cli_args 的 help 与 README 都没有写，本文不做推断。同样，「删了这个文件会怎样」我也没有任何官方说明可依——所以稳妥的做法是把它当有状态数据对待，真要删之前先备份。

三、--enable-asset-hashing：官方自己把代价写在 help 里了

这是本篇最值得细看的一个开关。--enable-asset-hashing 的 help 说得相当完整，我把它的两半分开念：

收益那半：扫描资产时计算 blake3 内容哈希，help 说明哈希能支撑未来的资产可移植特性，并举了两个例子——去重、跨机器模型解析。

代价那半：会增加启动开销，以及大模型目录上的单次输出开销；默认关闭，需主动开启。

依赖里对应的包就是 blake3。

这段 help 里有两个地方特别容易读歪，值得停一下：

第一个坑：「未来的」这三个字不是修辞。 help 的原意是哈希用来支撑未来的资产可移植特性，去重和跨机器模型解析是被点名的例子。换句话说，你今天打开这个开关，得到的是「哈希被算出来并存下来了」，不等于今天就有一个能用的去重功能或者跨机器同步功能。如果你是冲着「我想让两台机器共享模型识别」去开的，请先确认当前版本到底有没有那个消费端功能，别把一个数据准备工作当成成品能力。

第二个坑：「单次输出开销」这个措辞，官方就写到这儿了。 help 说的是在大模型目录上会有一次性的输出开销，但没有给任何量化数据——没有耗时数字，没有 IO 量，没有跟目录体积的换算关系。这一点官方没给数据，本文不比、也不猜。你只能拿到一条定性判断：目录越大，这笔一次性成本越高。

另外提醒一句，别把 --enable-asset-hashing 和 --default-hashing-function 搞混。后者是另一个参数，可选 md5/sha1/sha256/sha512，默认 sha256，help 里说的用途是重名/内容比对。它跟 assets 系统的 blake3 是两套东西，参数名长得像而已，别以为改了 --default-hashing-function 就能换掉 assets 的哈希算法——官方没有这么说。

四、决策路径：从你的模型目录和机器数量倒推

不罗列参数，直接给判断顺序。

第一问：你的模型目录有多大？

--enable-asset-hashing 的代价被官方明确挂钩在「大模型目录」上。所以模型目录规模是第一道分水岭：

• 目录很小（比如你只留了当前项目在用的几个模型）：代价那句 help 基本落不到你头上，开不开都不痛不痒。既然如此，看第二问。
• 目录很大（多年积累、几个 SD/视频模型混着放、还挂了 --extra-model-paths-config 引了别的盘）：这时候「增加启动开销」和「大模型目录上的单次输出开销」两句 help 就是冲你写的。建议是先只开 --enable-assets 不开哈希，看看后台扫描本身的体感能不能接受，再决定要不要加哈希。两个开关是分开的，这就是它们分开的意义。

第二问：你是单机还是多机？

• 单机、模型目录只有一份：help 点名的两个收益（去重、跨机器模型解析）都是「未来特性」的例子，而跨机器解析对单机没有意义。剩下的去重收益，你在一台机器上用文件系统层面的手段一样能做。结论倾向：不开哈希。 这是条件式结论——如果哪天官方把消费端功能落地了，这个判断要重算。
• 多机、或者你在往多机迁移：跨机器模型解析正是 help 点名的方向，开哈希在语义上是对路的。但请回到第一个坑：确认当前版本有没有真正能用的消费端。如果没有，你现在开的意义是提前把哈希算好，而不是马上收益。 这笔提前量值不值，取决于你的模型目录有多大——回到第一问。

第三问：你是不是要进生产 / 要走 API？

--enable-assets 里那条「API 路由」值得单独拎出来说。它会让服务端多出一组端点。ComfyUI 的服务端本来就有一系列跟暴露面相关的开关——--listen 默认只监听 127.0.0.1，不带参数时才是 0.0.0.0,::——开 assets 之前先确认你的监听范围是不是你以为的那个。在本机自己用，多一组端点没什么；如果你已经把服务开到了局域网甚至公网上，多开一组端点就是多一份要评估的暴露面。这里我只陈述参数语义，具体怎么加固属于通用运维范畴，不是本文话题。

另外补一条同属服务端 API 演进的记录：v0.23.0 新增了 OAuth 2.1 与 RFC 7591 DCR 端点，同版本 release notes 里还有若干 openapi 契约同步条目，说明 core 与 cloud 共享 API 契约。它跟 assets 是不是同一条线，官方没有明说，本文不替它们建立关联；引用它只是为了说明一件事——服务端这块一直在动，这些开关的行为会随版本变。

五、一个可复制的起手配置

如果你决定试，从最小面积开始：

# 只开 assets 系统本身，不开哈希，数据库用默认路径
python main.py --enable-assets

想把数据库挪个地方，或者临时跑一个不留状态的实例：

# 显式指定数据库位置（路径按你自己的部署改）
python main.py --enable-assets --database-url sqlite:///<你的路径>/comfyui.db

# 临时实例，进程退出即无状态
python main.py --enable-assets --database-url sqlite:///:memory:

确认了扫描开销可接受，再考虑加哈希：

python main.py --enable-assets --enable-asset-hashing

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

六、什么情况下这套东西不适合你

说几个我觉得该劝退的场景：

• 你只是想让 ComfyUI 认出模型目录里的新文件。 这个需求跟 assets 系统不是一回事，别为了它去开一整套带数据库同步和后台扫描的能力。
• 你的部署是一次性的、跑完就销毁的容器。 后台扫描和哈希的成本都是前置的，而你根本活不到收益兑现那天。这种场景 sqlite:///:memory: 反而更贴合。
• 你在排查一个跟 assets 无关的问题。 排查期间加变量是大忌，尤其这两个开关默认关着——默认状态本身就是你最干净的基线，别自己把基线弄脏了。
• 你指望它现在就能帮你在多台机器之间自动同步模型。 再重复一次，help 说的是「支撑未来的资产可移植特性」。这句话的主语是哈希，不是一个已经交付的功能。

最后一句老生常谈但确实每次都踩：ComfyUI 的版本节奏很快，参数、默认值和 help 文本都会变。本文所有结论的锚点是 v0.31.0（2026-08-08），你手上那版跟这个不一样的时候，--help 的输出永远比任何文章更可信。

延伸阅读

• 启用 ComfyUI-Manager 与它的三个开关
• 让 ComfyUI 完全离线跑：--disable-api-nodes 之外还要关掉哪些出网路径
• 桌面版 / portable / 手动装：ComfyUI 三条安装路怎么选

---

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