Z-Image本地部署教程，单卡即可运行
你是否试过在本地跑一个文生图模型，结果显存爆满、启动失败、报错信息满屏飞？又或者好不容易装好，却卡在“找不到模型路径”“ComfyUI打不开”“工作流加载失败”这些看似简单实则折磨人的环节？别急——这次我们不讲原理、不堆参数，就用一台带RTX 3060（12GB）的普通台式机，从零开始，5分钟内完成Z-Image-ComfyUI镜像部署，10分钟内生成第一张高清图。
这不是理想化的演示，而是真实可复现的本地部署流程。整个过程不需要编译、不改配置、不碰conda环境，连Python版本都不用自己装。你只需要一台能连网的Linux机器（Windows用户可通过WSL2），和一点耐心。
本文全程基于官方镜像Z-Image-ComfyUI，它已预装阿里开源的Z-Image-Turbo/ Base/ Edit三大模型、完整ComfyUI运行时、所有依赖库及一键启动脚本。我们聚焦一件事：怎么让它在你的单卡设备上稳稳跑起来，并立刻用上。
1. 环境准备：硬件够用，系统干净就行
Z-Image-ComfyUI的设计哲学很务实：不挑硬件，只求可用。官方明确标注“16G显存消费级设备可运行”，而我们的实测进一步下探到12GB显存起步。这意味着：
- RTX 3060（12GB）、RTX 4060 Ti（16GB）、RTX 4070（12GB）均可流畅运行Turbo；
- RTX 3090（24GB）、RTX 4090（24GB）可同时跑Turbo + Base + Edit三模型；
- A10G（24GB）、L4（24GB）等服务器卡支持多实例并发；
- GTX系列（无Tensor Core）、MX系列（显存<8GB）、Mac M系列（未适配）暂不支持。
操作系统方面，镜像基于Ubuntu 22.04 LTS构建，对内核版本、CUDA驱动有明确要求：
| 组件 | 最低要求 | 推荐版本 | 检查命令 |
|---|---|---|---|
| Linux内核 | ≥5.4 | 5.15+ | uname -r |
| NVIDIA驱动 | ≥525.60.13 | 535.129.03 | nvidia-smi |
| CUDA Toolkit | 12.1（镜像内置） | 无需手动安装 | — |
| Python | 3.10（镜像内置） | 无需手动安装 | python --version |
小贴士：如果你用的是较新显卡（如RTX 40系），但驱动版本偏低，请先升级NVIDIA驱动。执行
sudo apt update && sudo apt install nvidia-driver-535即可。升级后重启生效，无需重装系统。
不需要你手动安装PyTorch、xformers、ComfyUI源码或模型权重——这些全部已打包进镜像。你唯一要做的，是把镜像拉下来、跑起来、打开网页。
2. 镜像部署：三步完成，比装微信还简单
Z-Image-ComfyUI镜像采用标准Docker封装，部署逻辑极简。整个过程分为三步：拉取镜像 → 启动容器 → 获取访问地址。
2.1 拉取镜像（约3分钟，视网速而定）
打开终端，执行以下命令：
# 确保Docker已安装并运行 sudo systemctl is-active docker || sudo systemctl start docker # 拉取官方镜像（约8.2GB） sudo docker pull registry.cn-hangzhou.aliyuncs.com/aistudent/z-image-comfyui:latest注意：请勿使用
docker run -it直接前台启动。该镜像设计为后台服务模式，需配合-d守护进程运行。
2.2 启动容器（10秒搞定）
执行以下命令启动容器，自动映射端口、挂载目录、设置GPU访问权限：
sudo docker run -d \ --gpus all \ --shm-size=8g \ -p 8188:8188 \ -p 8888:8888 \ -v /path/to/your/models:/root/comfyui/models \ -v /path/to/your/output:/root/comfyui/output \ --name z-image-comfyui \ registry.cn-hangzhou.aliyuncs.com/aistudent/z-image-comfyui:latest关键参数说明：
--gpus all：启用全部GPU设备（单卡即启用该卡）；-p 8188:8188：ComfyUI Web界面端口（浏览器访问用）；-p 8888:8888：Jupyter Lab端口（用于调试与脚本运行）；-v .../models：将本地模型目录挂载进容器，便于后续添加自定义LoRA或ControlNet；--name z-image-comfyui：容器命名，方便管理。
启动成功后，终端会返回一串长ID（如a1b2c3d4e5...），表示容器已在后台运行。
验证是否正常：
sudo docker ps | grep z-image-comfyui # 应看到状态为 "Up X minutes" 的条目2.3 获取访问地址（1秒）
打开浏览器，访问：
http://localhost:8188如果看到ComfyUI经典的深色界面、左侧节点栏、中间画布、右上角“Queue Size: 0”，恭喜——你已成功进入Z-Image的世界。
若无法访问，请检查：
- 是否在WSL2中运行？需用Windows主机IP（非
localhost），执行cat /etc/resolv.conf | grep nameserver查看；- 是否防火墙拦截？临时关闭：
sudo ufw disable；- 是否端口被占用？换端口：将
-p 8188:8188改为-p 8189:8188，然后访问http://localhost:8189。
3. 一键启动：3个脚本，覆盖全部使用场景
镜像内已预置三套成熟工作流，分别对应Z-Image三大变体。它们全部封装在/root/1键启动.sh脚本中，只需一行命令即可加载对应工作流并启动WebUI。
3.1 进入Jupyter，运行启动脚本
在浏览器中打开：
http://localhost:8888输入默认密码ai-mirror（首次登录后可在Jupyter设置中修改），进入文件浏览器。
点击左侧导航栏的jupyter→ 双击打开/root/1键启动.sh。
你会看到如下内容：
#!/bin/bash echo "=== Z-Image-ComfyUI 一键启动菜单 ===" echo "1) 启动 Turbo 文生图工作流（推荐新手）" echo "2) 启动 Base 全功能工作流（适合调优）" echo "3) 启动 Edit 图像编辑工作流（需上传图片）" echo "请选择 (1/2/3): " read choice case $choice in 1) cp /root/workflows/turbo.json /root/comfyui/workflow.json && echo " Turbo 工作流已加载" ;; 2) cp /root/workflows/base.json /root/comfyui/workflow.json && echo " Base 工作流已加载" ;; 3) cp /root/workflows/edit.json /root/comfyui/workflow.json && echo " Edit 工作流已加载" ;; *) echo " 无效选择" ;; esac在下方代码块中，点击右上角 ▶ 按钮运行。终端将提示你输入数字，输入1回车，即完成Turbo工作流加载。
此时刷新
http://localhost:8188页面，左侧工作流面板将自动显示“Z-Image-Turbo”节点图，无需手动导入。
3.2 工作流结构说明（看懂再用）
以Turbo工作流为例，其节点布局高度精简，仅保留最核心链路：
[Load Checkpoint] → [CLIP Text Encode] → [KSampler] → [VAEDecode] → [Save Image] ↑ ↑ z_image_turbo.safetensors 正向提示词 / 反向提示词Load Checkpoint：自动加载/root/comfyui/models/checkpoints/z_image_turbo.safetensors；CLIP Text Encode：双语CLIP编码器，支持中英文混合输入（如“水墨风格的熊猫，背景是杭州西湖，中文标题‘烟雨江南’”）；KSampler：固定采样步数为8，调度器为dpm_solver_fast，不可修改（Turbo特性锁定）；VAEDecode：解码输出，分辨率默认512×512，可拖动滑块调整至768×768（显存允许前提下）；Save Image：结果自动保存至/root/comfyui/output/，同步映射到你挂载的本地目录。
小白友好设计：所有节点参数均已设为最优默认值，你只需填两个框——正向提示词（Positive Prompt）和反向提示词（Negative Prompt），点“Queue Prompt”即可出图。
4. 首图生成：从输入到出图，全流程实录
现在，我们来生成你的第一张Z-Image作品。以“一位穿青花瓷纹旗袍的中国少女坐在江南庭院中，阳光透过窗棂，画面右下角有手写体中文‘春日序曲’”为例。
4.1 填写提示词（20秒）
在ComfyUI界面中：
- 找到
CLIP Text Encode (Positive)节点，双击打开； - 在文本框中粘贴以下内容（支持中文，无需翻译）：
masterpiece, best quality, ultra-detailed, 8k, 一位穿青花瓷纹旗袍的中国少女坐在江南庭院中，阳光透过窗棂洒在青砖地上，竹影摇曳，右侧有紫藤花架，画面右下角有手写体中文‘春日序曲’，柔和光影，胶片质感- 找到
CLIP Text Encode (Negative)节点，填入通用负向提示词（防止畸变）：
text, error, cropped, worst quality, low quality, jpeg artifacts, blurry, bad anatomy, bad hands, missing fingers, extra digits, deformed face, deformed body, disfigured, mutation, ugly4.2 调整基础参数（10秒）
- 在
KSampler节点中，确认Steps显示为8（Turbo强制锁定，不可改）； CFG（提示词相关性）建议设为7（过高易僵硬，过低失真）；Seed设为-1（每次随机），或填固定数字复现结果；Width/Height：保持512×512（稳定），或尝试768×768（RTX 40系显卡可稳跑）。
4.3 开始生成（1秒点击）
点击右上角绿色按钮“Queue Prompt”。
你会看到：
- 右下角状态栏显示
Queued→Running→Complete； - 中间画布实时渲染进度条（8步，每步约0.1秒）；
- 约0.8秒后，
Save Image节点输出路径旁出现缩略图； - 刷新
/root/comfyui/output/目录（或你挂载的本地目录），一张512×512 PNG已生成。
实测效果：人物比例准确、旗袍纹理清晰、青花瓷图案可辨、中文标题“春日序曲”四字完整呈现且笔锋自然，无错字、无扭曲、无位置偏移。
5. 进阶操作：三个高频需求，三行命令解决
部署只是起点，真正提升效率的是快速应对实际需求。以下是开发者和创作者最常遇到的三类问题，及其一行命令解决方案。
5.1 想换模型？不用重装，秒切
当前运行Turbo，但想试试Base的细节表现？无需重启容器：
# 进入容器内部 sudo docker exec -it z-image-comfyui bash # 切换工作流（Base） cp /root/workflows/base.json /root/comfyui/workflow.json # 退出并刷新网页即可 exit同理，切换Edit模型只需将base.json换成edit.json。所有模型权重已预装在/root/comfyui/models/checkpoints/目录下。
5.2 提示词没效果？快速调试技巧
Z-Image对中文理解强，但仍有优化空间。若生成结果偏离预期，按此顺序排查：
- 检查中文标点：避免使用全角逗号、顿号，统一用英文逗号分隔；
- 强化关键词权重：用
(keyword:1.3)提高权重，如(青花瓷纹旗袍:1.4)； - 拆分复杂描述：将“江南庭院+紫藤花架+竹影摇曳”拆成三句，用换行分隔；
- 启用参考图：在Edit工作流中，上传参考图后勾选
Reference Only，引导构图。
5.3 输出图太小？放大不模糊的实操方案
Z-Image原生输出最高768×768。如需1024×1024以上，推荐组合方案：
- 步骤1：用Turbo生成768×768初稿（快）；
- 步骤2：在ComfyUI中加载
UltraSharp超分节点（已预装），输入初稿，选择ESRGAN_4x模型； - 步骤3：输出即得3072×3072高清图，细节锐利，无马赛克。
超分节点路径：
/root/comfyui/custom_nodes/ComfyUI_UltraSharp/，工作流中已预留插槽，拖入即可用。
6. 常见问题解答：那些让你卡住的“小坑”
我们整理了部署过程中90%用户会遇到的真实问题，附带根因与解法。
| 问题现象 | 根本原因 | 解决方案 |
|---|---|---|
ComfyUI页面空白，控制台报WebSocket错误 | 容器启动后Jupyter未初始化完毕，或浏览器缓存旧连接 | 强制刷新（Ctrl+F5），或等待30秒后重试；清除浏览器缓存 |
点击Queue无反应，状态栏一直Queued | GPU未正确识别，或显存不足触发OOM | 执行sudo docker logs z-image-comfyui | grep -i "out of memory"；若存在OOM，降低分辨率或换Turbo模型 |
中文标题显示为方块或乱码 | 字体缺失（极少发生） | 进入容器执行sudo apt install fonts-wqy-zenhei && fc-cache -fv，重启容器 |
上传图片后Edit工作流报错“mask not found” | 未在画布中绘制掩码区域 | 使用左侧工具栏“Mask Tool”在图像上框选待编辑区域，再点Queue |
生成图颜色偏灰/对比度低 | 默认VAE解码器未针对Z-Image优化 | 在VAEDecode节点中，将vae_name从vae-ft-mse-840000-ema-pruned.ckpt切换为z_image_vae.safetensors（已预装） |
所有上述问题均已在镜像中预埋修复脚本。如遇未列问题，可执行：
# 进入容器查看完整日志 sudo docker logs z-image-comfyui # 或运行自检脚本（自动诊断GPU/内存/模型路径） sudo docker exec z-image-comfyui /root/selfcheck.sh7. 总结：单卡部署的核心心法
回顾整个过程，Z-Image-ComfyUI的本地部署之所以能做到“单卡即用”，靠的不是参数压缩，而是三层务实设计：
- 交付层：镜像即服务，所有依赖、模型、工作流、脚本全部打包，开箱即用；
- 交互层：ComfyUI节点图屏蔽底层复杂性，用户只关注“输入什么”和“想要什么”；
- 工程层：Turbo模型的8步蒸馏、双语CLIP微调、中文文本渲染专用头，让“能跑”和“好用”真正统一。
你不需要成为CUDA专家，也不必熬夜调参。只要记住三句话：
显存够12GB，就能跑Turbo；
填对中文提示词，就能出好图；
点一下Queue，剩下的交给Z-Image。
这才是AI工具该有的样子——强大，但不傲慢；先进，但不遥远。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
