Z-Image-ComfyUI一键启动.sh使用说明，超简单
你刚部署完 Z-Image-ComfyUI 镜像，点开终端准备开始生成第一张图，却卡在了“接下来该敲什么命令”这一步？别急——这不是你的问题，而是很多新手第一次面对 ComfyUI 时的真实困惑。它不像 Web UI 那样点几下就能跑，但也不需要你从零配置 Python 环境、安装依赖、下载模型、写启动脚本……因为阿里开源团队已经把所有这些事，压缩进了一个名字朴实到不能再朴实的文件里：一键启动.sh。
这个.sh文件不是噱头，也不是半成品。它是一条真正意义上的“快捷通道”，从镜像启动完成那一刻起，到 ComfyUI 网页可访问、工作流可加载、第一张 Z-Image-Turbo 图片成功渲染出来，全程只需3个动作、不到90秒、零手动编辑配置。本文不讲原理、不列参数、不堆术语，只说清楚一件事：你该怎么用它，以及为什么它能这么简单。
1. 为什么需要“一键启动”？ComfyUI 的真实门槛在哪
ComfyUI 本身是极简设计的：它不带图形安装向导，不自动检测 GPU，不预置模型路径，也不帮你区分/models/checkpoints和/models/controlnet应该放什么。它的强大，恰恰建立在“高度自由”的基础上；而这份自由，对新手来说，就是一堵看不见的墙。
常见卡点包括：
- 运行
comfyui/main.py报错No module named 'torch'—— 实际上 PyTorch 已预装，但环境变量没生效； - 访问
http://localhost:8188显示空白页 —— 因为 ComfyUI 默认未启用--enable-cors-header，跨域被拦截； - 加载工作流时报
Model not found—— Z-Image 的三个变体（Turbo/Base/Edit）虽已内置，但模型权重路径未正确注册进 ComfyUI 的加载器； - 点击“Queue Prompt”后无响应 —— 缺少
--gpu-only或显存分配策略，导致任务卡在 CPU fallback 模式。
这些问题，单个看都不难解决，但组合起来，就足以让一个想快速试效果的用户，在终端里反复查文档、改配置、重试、再失败。
而一键启动.sh的价值，正在于它把所有这些“隐性前提”打包成一次确定性操作：它不是绕过问题，而是提前把问题全部闭环。
2. 启动前的两个确认动作（30秒搞定）
在运行脚本前，请花半分钟做两件事。它们不复杂，但跳过可能导致后续无法访问网页或模型加载失败。
2.1 确认镜像已完全初始化
部署完成后，进入 Jupyter Lab（或直接通过 SSH 登录），执行：
nvidia-smi -L你应该看到类似输出：
GPU 0: NVIDIA H800 PCIe (UUID: GPU-xxxxxx)如果显示NVIDIA-SMI has failed或无输出，说明 GPU 驱动未就绪，需重启实例或联系平台支持。Z-Image-Turbo 对 GPU 有硬依赖，CPU 模式不可用。
小贴士：本镜像默认启用
nvidia-container-toolkit，无需手动安装驱动。只要平台提供合规 GPU 资源，驱动即开即用。
2.2 确认脚本位置与权限
进入/root目录，查看脚本是否存在且可执行：
cd /root ls -l 一键启动.sh正常应显示：
-rwxr-xr-x 1 root root 2456 Apr 5 10:15 一键启动.sh若权限为-rw-r--r--（即无x），请立即修复：
chmod +x 一键启动.sh注意：脚本名含中文，部分终端可能显示乱码，但不影响执行。如遇报错
No such file or directory，请确认是否复制了全角空格或隐藏字符，建议直接用ls列出后./补全执行。
3. 三步走：从敲命令到看见图片（实测平均82秒）
整个流程无需记忆命令，只需按顺序执行以下三步。每步都有明确反馈，失败会立刻提示原因。
3.1 执行启动脚本
在/root目录下，直接运行：
./一键启动.sh你会看到滚动日志，关键信息如下（节选）：
[INFO] 正在检查 CUDA 环境... [OK] CUDA 12.1 + cuDNN 8.9.7 已就绪 [INFO] 正在加载 Z-Image 模型索引... [OK] Z-Image-Turbo (6B) 已注册至 ComfyUI 模型管理器 [INFO] 启动 ComfyUI 服务... [OK] ComfyUI 已在端口 8188 启动，启用 CORS 与 GPU 加速成功标志：最后一行出现[OK] ComfyUI 已在端口 8188 启动...，且光标回到新行等待输入。
❌ 常见失败及应对：
CUDA initialization: no CUDA-capable device is detected→ GPU 未识别，返回第2.1步检查nvidia-smi；Permission denied→ 权限未设置，执行chmod +x 一键启动.sh后重试；- 卡在
Loading model...超过 90 秒 → 内存不足（本镜像最低要求 32G 系统内存），需升级实例规格。
3.2 返回控制台，点击“ComfyUI网页”
此时脚本已后台运行 ComfyUI 服务。不要关闭终端窗口，也不要按 Ctrl+C —— 关闭会导致服务中断。
打开浏览器，访问实例控制台页面（如 CSDN 星图、阿里云容器服务等平台提供的 Web 控制台），找到【应用访问】或【服务入口】区域，点击“ComfyUI网页”按钮。
小贴士：该按钮本质是反向代理，自动将
https://your-instance-url/comfyui映射到容器内http://localhost:8188，无需手动拼 URL，也无需暴露 8188 端口。
3.3 加载工作流并生成首图
页面加载后，左侧会出现工作流列表（Workflow Gallery）。Z-Image-ComfyUI 预置了 3 个开箱即用的工作流：
| 工作流名称 | 适用模型 | 典型用途 | 推荐首次尝试 |
|---|---|---|---|
Z-Image-Turbo_Text2Image.json | Turbo | 中文/英文提示词生成高清图（1024×1024） | 强烈推荐 |
Z-Image-Base_Text2Image.json | Base | 高保真细节生成（适合艺术创作） | △ 次选 |
Z-Image-Edit_Image2Image.json | Edit | 上传图片+文字指令进行编辑（换背景/改风格） | △ 进阶 |
点击Z-Image-Turbo_Text2Image.json，工作流自动加载到画布。找到CLIP Text Encode (Prompt)节点，双击修改提示词（例如输入：一只穿着宇航服的橘猫，站在月球表面，超现实风格，8K）。
然后点击右上角“Queue Prompt”按钮。约 3~5 秒后，右侧Preview区域将显示生成结果。
成功标志：预览图清晰、无马赛克、无黑边、文字渲染准确（中英文混合提示词可正常识别）。
4. 脚本背后做了什么？（不深究也能用，但知道更好）
你不需要理解下面这段内容就能用好脚本，但它能帮你建立掌控感：这个“一键”不是魔法，而是经过工程验证的确定性封装。
4.1 它自动完成了五件关键事
| 动作 | 说明 | 手动实现难度 |
|---|---|---|
| GPU 环境自检与绑定 | 检测nvidia-smi输出，强制 ComfyUI 使用--gpu-only --lowvram，避免 CPU fallback | ☆（需查文档配参） |
| 模型路径自动注册 | 将/root/models/z-image/下的三个子目录（turbo/base/edit）注入 ComfyUI 的extra_model_paths.yaml | ☆☆（路径易写错） |
| CORS 与安全头启用 | 添加--enable-cors-header --listen 0.0.0.0 --port 8188，确保平台反向代理可穿透 | ☆☆☆（常被忽略导致白屏） |
| 日志与错误重定向 | 所有输出写入/root/logs/comfyui-startup.log，失败时直接打印关键错误行 | ☆☆☆☆（手动排查需翻日志） |
| 进程守护与端口占用检查 | 启动前校验 8188 是否被占用，若存在旧进程则自动 kill，防止端口冲突 | ☆☆（新手常因重复启动卡死） |
重点：脚本不修改系统级配置（如
.bashrc）、不安装新包、不写入/etc，所有变更仅作用于本次 ComfyUI 会话，完全可逆。
4.2 它刻意没做的事（为什么这是优点）
- ❌ 不自动下载额外模型（如 Lora、ControlNet）—— 避免首次启动耗时过长或网络失败；
- ❌ 不修改 ComfyUI 核心代码（如
main.py）—— 保证与上游版本兼容，升级无风险； - ❌ 不启用
--auto-launch（自动弹浏览器）—— 因为平台 Web 控制台已提供更可靠的访问入口； - ❌ 不预设采样器/步数/CFG 值—— 这些属于创作参数，应由用户在工作流中自主调整。
这种“克制式封装”，正是它稳定、轻量、可预期的根本原因。
5. 常见问题与即时应对（不用查文档，这里全有）
我们整理了 90% 新手会在前 10 分钟遇到的问题，并给出一行命令即可解决的答案。
5.1 网页打不开，显示“连接被拒绝”或“502 Bad Gateway”
→ 大概率是 ComfyUI 服务未启动成功。执行：
tail -n 20 /root/logs/comfyui-startup.log查看最后 20 行日志。若含OSError: [Errno 98] Address already in use，说明端口被占：
lsof -i :8188 | awk 'NR>1 {print $2}' | xargs kill -9 2>/dev/null ./一键启动.sh5.2 工作流加载后，节点显示红色报错：“Z-Image-Turbo not found”
→ 模型注册失败。手动触发注册：
cd /root/comfyui python main.py --extra-model-paths-config /root/models/z-image/extra_model_paths.yaml --disable-auto-launch等待提示[OK] Loaded extra model paths from ...后，再运行./一键启动.sh。
5.3 生成图片模糊、有严重 artifacts（伪影）
→ 当前使用的是 Turbo 模型的默认低步数（12 NFEs）。在工作流中找到KSampler节点，将steps改为20，cfg改为7，重试即可显著提升质量。
5.4 想换用 Base 或 Edit 模型，但工作流里找不到对应选项
→ 打开工作流 JSON 文件（如/root/comfyui/custom_nodes/ComfyUI-Z-Image/workflows/Z-Image-Base_Text2Image.json），查找"model_name"字段，将其值改为：
- Base 模型：
"z-image-base.safetensors" - Edit 模型：
"z-image-edit.safetensors"
保存后重新加载该工作流。
5.5 启动后终端卡住不动，光标不返回
→ 这是正常现象！脚本已将 ComfyUI 启为后台服务，终端处于“挂起监听”状态。你只需最小化窗口，去点“ComfyUI网页”即可。如需释放终端，按Ctrl+Z后输入bg，服务仍持续运行。
6. 总结：简单，是因为有人替你扛下了所有复杂
Z-Image-ComfyUI 的一键启动.sh，不是偷懒的捷径，而是工程化思维的具象体现：把重复、易错、依赖上下文的操作，固化为可验证、可复现、可交付的原子动作。
它不掩盖技术深度，而是把深度藏在确定性之下——你知道每次执行都会得到相同结果，不必担心环境漂移；它不剥夺学习权利，而是把入门门槛从“配置工程师”降为“创作者”，让你在 90 秒内就获得正向反馈，从而愿意继续探索更深层的能力。
所以，下次当你双击那个看似普通的.sh文件，看到终端滚动出[OK]，网页弹出熟悉的 ComfyUI 界面，第一张由 Z-Image-Turbo 生成的高清图静静躺在预览区时，请记住：这份“超简单”，背后是无数次环境适配、参数调优和失败重试的沉淀。
而你要做的，只是开始创作。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
