这是一个专为云原生开发环境（如 CNB、AutoDL 等）设计的 ComfyUI 启动与运维方案。核心理念是 "存算分离" 与 "自动化运维"，确保环境可复现、数据不丢失、启动极速化。
- ⚡️ 极速启动：基于 Docker 缓存策略，非首次启动可实现秒级响应。
- 🛡️ 存算分离：所有模型、插件、生图结果均存储在
my_data（持久化目录），容器重置不丢数据。 - ⚙️ 灵活配置：通过
.env文件管理环境变量，支持跳过下载、自定义模型列表。 - 🤖 自动化运维 (Ops)：所有核心维护脚本均位于
ops/目录下，解耦且高效。ops/download_models.sh：- 功能: 智能下载模型，支持断点续传、SHA256 校验、自动跳过已存在文件。
- 独立运行: 支持手动运行以“热补充”模型，自动读取
.env配置。
ops/sync.sh：- 功能: 一键提交代码变动到 Git 仓库，自动处理嵌套 Git 目录。
my_data/get_file_list.py：- 功能: 自动抓取 Hugging Face / CNB 仓库文件列表生成 JSON 清单。
/workspace
├── .env # [配置] 环境变量 (不提交到 Git)
├── .env.example # [配置] 环境变量模板
├── start.sh # [入口] 唯一的启动脚本
├── ops/ # [运维] 存放核心维护脚本
│ ├── download_models.sh
│ └── sync.sh
└── my_data/ # [数据] 持久化存储 (建议挂载云盘)
├── custom_nodes/ # 插件安装位置
├── models/ # 模型下载位置
├── user/ # ComfyUI 用户配置与日志
├── file_list.json # 自动生成的模型下载清单
└── get_file_list.py # 模型抓取脚本
本项目基于定制化的 Docker 镜像运行，确保了依赖的确定性。
pytorch/pytorch:2.4.0-cuda12.1-cudnn9-devel
aria2：用于多线程断点续传下载模型coreutils：提供numfmt、stat等工具，用于下载统计git-lfs：支持大文件版本控制
opencv-python-headless：避免启动时编译耗时GitPython：ComfyUI Manager 核心依赖huggingface_hub、requests：支撑自动化运维脚本运行
首次使用时，复制模板并配置你的 Token（用于下载 SD3 等门禁模型）。
cp .env.example .env
# 使用编辑器修改 .env，填入 HF_TOKEN (如果需要)
⚠️ 重要提示：终端选择
请务必通过 VS Code 顶部菜单栏 Terminal > New Terminal 打开终端，或在终端窗口 + 号下拉菜单中选择 cnb (Default)。
- ❌ 不要选择
bash：这可能会进入无环境的宿主机 Shell（通常显示 Debian 系统）。 - ✅ 正确环境：运行
cat /etc/os-release应显示 Ubuntu。
执行根目录下的启动脚本，系统会自动完成以下步骤：
- 加载
.env配置 - 自动拉取/更新 ComfyUI 代码
- 安装 Python 依赖 & 插件依赖
- 根据
file_list.json下载/校验模型 - 启动服务
bash start.sh
启动成功后，访问终端提示的地址（如 http://0.0.0.0:8188）。
你可以在 .env 文件中定义以下变量来控制环境行为：
| 变量名 | 默认值 | 说明 |
|---|---|---|
HF_TOKEN | (空) | Hugging Face Access Token，用于下载受限模型（如 SD3）。 |
SKIP_DOWNLOAD | 0 | 设为 1 可跳过模型下载/校验阶段，直接启动（用于快速调试）。 |
BASE_DATA_DIR | /workspace/my_data | [新增] 自定义数据存储根目录。如果你挂载了外部云盘到其他路径（如 /mnt/data），可在此修改。 |
MODEL_LIST_FILE | .../file_list.json | 指定模型列表的 JSON 文件路径。 |
为了确保环境的一致性和可维护性，请遵循以下规范：
start.sh 是启动 ComfyUI 服务的唯一入口。
- ✅ 正确方式：
bash start.sh - ❌ 禁止方式：直接运行
python main.py（会导致配置缺失、路径错误）。
它负责：
- 初始化工作目录与持久化结构。
- 加载
.env环境变量。 - 统一调度依赖安装与模型下载。
所有的运维脚本（ops/*.sh）均经过特殊设计，支持独立运行。
- 场景：当你需要单独下载模型、或者单独备份代码时。
- 机制：脚本会自动检测是否由
start.sh调用。如果是手动运行，它们会自动加载.env配置。
常用命令：
- 补充下载模型：
bash ops/download_models.sh - 备份代码：
bash ops/sync.sh
无论你当前位于容器内的哪个路径，建议始终使用绝对路径或在根目录执行命令：
bash /workspace/start.sh
我们不再手动下载模型，而是通过脚本维护一个清单。
编辑 my_data/get_file_list.py，在 repos 列表中添加 Hugging Face 或 CNB 的仓库地址。
运行 Python 脚本，自动抓取文件的下载直链、SHA256 和大小：
python3 my_data/get_file_list.py
生成的清单会保存在 my_data/file_list.json。
再次运行 bash start.sh（或手动运行 bash ops/download_models.sh），脚本会自动识别新清单并下载缺失的模型。
当你安装了新插件或修改了 ComfyUI 设置后，建议执行同步脚本，将改动备份到远程 Git 仓库。
bash ops/sync.sh
该脚本会自动处理 custom_nodes 下的嵌套 Git 目录，防止提交冲突。
Q：启动时提示 ❌ 未检测到镜像指纹 或找不到 image-info 文件？
A：你可能进入了错误的终端环境（宿主机/Sidecar）。
- 现象：执行
cat /etc/os-release显示的是 Debian（正确应为 Ubuntu）。 - 原因：在 VS Code 终端下拉菜单中选择了错误的 Shell（如
bash）。 - 解决：关闭当前终端，使用菜单栏 Terminal > New Terminal 创建新终端，重新运行脚本。
Q：下载 SD3 Medium 等模型提示 403 Forbidden？
A：这是因为该模型需要 Hugging Face 授权。请去 HF 官网签署协议，申请 Access Token，并填入 .env 文件的 HF_TOKEN 字段。
Q：容器存储空间不足？
A：请检查云平台的"制品/构建缓存"页面，删除旧日期的 Docker 缓存层（只保留最新的一个）。
Q：如何重置环境但保留数据？
A：直接重建容器/实例即可。只要 my_data 目录是持久化的，所有模型和插件都会自动重新挂载。
