在 RTX 4060 Ti 16G 上使用 Docker 部署 ComfyUI Z-Image (FP8版)

摘要：RTX 4060 Ti 16G 是运行 Z-Image 的“黄金甜点”显卡。本文记录了如何利用 FP8 量化技术、Docker 容器化部署，最终实现生图的全过程。

随着 Z-Image (S3-DiT架构) 的发布，AI 绘画进入了新的画质里程碑。但其庞大的参数量（6B 模型 + 3.4B 文本编码器）让许多显卡望而却步。

经过实测，RTX 4060 Ti 16GB 配合 FP8 量化 是目前性价比最高的解决方案。本文将手把手教你使用 Docker 部署这套环境。

1. 核心策略：为什么选 FP8？

在开始动手前，我们需要明确模型版本的选择。Z-Image 有三种主流格式，对于 4060 Ti 16G 来说：

• BF16 (原版)：总显存占用超 20GB，会导致显存溢出，速度极慢。
• GGUF (CPU量化)：虽然显存占用极低 (8GB)，但无法利用 40 系显卡的 Tensor Core 加速。
• FP8 (8-bit浮点)：这是正确答案。
  • 显存占用约 14GB（完美适配 16GB 显存）。
  • 利用 Ada Lovelace 架构的 FP8 硬件加速，推理速度比 BF16 快一倍。
  • 画质几乎无损。

2. 准备工作：文件下载与目录规划

为了数据持久化，我们需要在宿主机创建一个标准目录结构。

2.1 目录结构

在 Linux/WSL 中创建以下文件夹：

comfyui-z-image/
├── docker-compose.yml       # 容器编排文件
├── Dockerfile               # 镜像构建文件
├── storage/                 # 数据挂载目录
│   ├── models/              # 模型存放区
│   │   ├── diffusion_models/
│   │   ├── text_encoders/   # 注意：不要放错位置
│   │   └── vae/
│   ├── output/              # 图片输出区
│   └── custom_nodes/        # 插件区

2.2 关键模型下载

请务必下载正确的文件版本，并放入对应的文件夹：

1. 扩散模型 (Diffusion Model)
   • 文件：z_image_turbo_fp8_e4m3fn.safetensors
   • 路径：storage/models/diffusion_models/
   • 注意：选择 e4m3fn 版本，它的精度比 e5m2 更高，适合推理。
2. 文本编码器 (Text Encoder)
   • 文件：qwen_3_4b.safetensors
   • 路径：storage/models/text_encoders/
   • 警告：新手最容易放错到 checkpoints 或 LLM 目录，必须是 text_encoders。
3. VAE 解码器
   • 文件：ae.safetensors (Z-Image 专用版)
   • 路径：storage/models/vae/

3. Docker 环境构建

由于国内网络环境极其复杂，直接构建 PyTorch 镜像极其容易失败。我们需要对 Dockerfile 做特殊的优化。

3.1 编写 Dockerfile

创建一个名为 Dockerfile 的文件。我们做出了两个关键决策：

1. 替换国内源：使用清华源加速 apt 和 pip。
2. 跳过 Flash-Attn 编译：使用 Runtime 镜像而非 Devel 镜像，跳过复杂的编译过程（PyTorch 2.4 的原生 SDPA 加速在 40 系显卡上已经足够快）。

# 1. 这里必须跟您手动 pull 的名称一模一样，确保直接使用本地缓存
FROM docker.io/pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime

WORKDIR /app

ENV DEBIAN_FRONTEND=noninteractive

# 2. 替换 APT 源为清华源 (加速系统软件安装)
RUN sed -i 's@//.*archive.ubuntu.com@//mirrors.tuna.tsinghua.edu.cn@g' /etc/apt/sources.list \
    && sed -i 's@//ports.ubuntu.com@//mirrors.tuna.tsinghua.edu.cn@g' /etc/apt/sources.list \
    && apt-get update && apt-get install -y \
    git \
    wget \
    libgl1-mesa-glx \
    libglib2.0-0 \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# 3. 克隆 ComfyUI
RUN git clone https://github.com/comfyanonymous/ComfyUI.git .

# 4. 安装 Python 依赖 (加入清华源 -i 参数，加速下载)
# 这里非常关键，否则 huggingface_hub 等大包会下载失败
RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
RUN pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple \
    transformers>=4.44.0 \
    protobuf \
    sentencepiece \
    accelerate \
    huggingface_hub

# 5. 安装 flash-attn (依然尝试安装，如果太慢卡住，可以注释掉这一行)
#RUN pip install --no-cache-dir flash-attn --no-build-isolation -i https://pypi.tuna.tsinghua.edu.cn/simple

EXPOSE 8188

CMD ["python", "main.py", "--listen", "0.0.0.0", "--fp32-vae", "--fast"]

3.2 编写 docker-compose.yml

创建一个名为 docker-compose.yml 的文件，配置 GPU 直通：

services:
  comfyui-z-image:
    build: .
    container_name: comfyui-z-image
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=compute,utility
      - CLI_ARGS=--preview-method auto
    ports:
      - "8188:8188"
    volumes:
      # 挂载模型目录
      - ./storage/models:/app/models
      # 挂载输出目录
      - ./storage/output:/app/output
      # 挂载自定义节点目录 (可选)
      - ./storage/custom_nodes:/app/custom_nodes
      # 挂载输入目录 (可选，用于图生图)
      - ./storage/input:/app/input
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    # 针对 4060 Ti 16GB 的启动参数优化:
    # --fp32-vae: 防止黑图
    # --fast: 开启 Flash Attention 加速
    # --listen: 允许局域网/宿主机访问
    command: python main.py --listen 0.0.0.0 --fp32-vae --fast --lowvram
    restart: unless-stopped

4. 启动与验证

4.1 启动容器

在终端执行以下命令。得益于国内源配置，构建速度应该非常快：

docker-compose up --build -d

4.2 验证日志

启动后，查看日志确认没有报错：

docker-compose logs -f

如果你看到 Total VRAM 16380 MB 和 To see the GUI go to: http://0.0.0.0:8188，恭喜你，环境部署成功！