🚀 使用 Docker Compose 部署 Stable Diffusion WebUI（ComfyUI CPU 版）

🚀 使用 Docker Compose 部署 Stable Diffusion WebUI

本教程将指导您使用 Docker Compose 部署功能强大的 Stable Diffusion WebUI 项目，它整合了 AUTOMATIC1111 和 ComfyUI 两种流行的 Stable Diffusion Web 界面，提供了一套完整且可定制化的本地 AI 绘画解决方案。

📝 项目简介

Stable Diffusion WebUI Docker 项目整合了多种 Stable Diffusion Web 界面，让用户能够通过浏览器轻松访问和运用 Stable Diffusion 模型生成图像。

核心特点：

• 多界面支持：同时提供 AUTOMATIC1111 和 ComfyUI 两种流行界面，满足不同用户偏好
• 灵活的硬件配置：支持 GPU 加速和纯 CPU 运行两种模式，适应不同硬件环境
• 数据持久化：通过卷挂载确保模型数据和生成作品的安全存储
• 模块化服务：采用 Docker Compose 的服务模块化设计，方便扩展和管理
• 配置文件复用：使用 YAML 锚点和引用减少代码重复，提升配置可维护性

🔧 部署前准备

系统环境要求

• 操作系统：推荐 Linux 发行版（如 Ubuntu 22.04+），Windows 和 macOS 也可运行
• Docker 版本：Docker 24.0+
• Docker Compose：版本 2.0+
• 硬件资源：
• GPU 版本：需要 NVIDIA 显卡，安装最新 NVIDIA 驱动和 NVIDIA Container Toolkit
• CPU 版本：至少 8GB 内存，16GB 以上推荐
• 存储空间：至少 50GB 可用空间（用于存储模型和生成图片）

环境检查

1. 检查 Docker 服务状态 bash systemctl status docker 确保 Docker 服务处于 active (running) 状态

2. 检查 Docker 版本 bash docker -v 确保版本为 24.0 或更高

3. 检查 Docker Compose 版本 bash docker compose version 确保版本为 v2.0 或更高

4. 检查 NVIDIA 驱动（GPU 用户） bash nvidia-smi 确认能够正常输出 GPU 信息

（2）安装 Git（拉取源码）

# Ubuntu/Debian 系统
sudo apt update && sudo apt install -y git
# 验证：git --version

3. 目录与源码准备

本项目需从官方仓库拉取源码（服务基于 ./services/comfy/ 目录构建，非现成镜像），步骤如下：

# 1. 创建部署主目录（示例路径：/home/compose/stable-diffusion-webui-docker，与启动命令一致）
sudo mkdir -p /home/compose/stable-diffusion-webui-docker && cd /home/compose/stable-diffusion-webui-docker

# 2. 克隆官方源码仓库（包含配置文件和服务构建脚本）
git clone https://github.com/AbdBarho/stable-diffusion-webui-docker.git .
# （若 GitHub 访问慢，可改用 Gitee 镜像：git clone https://gitee.com/mirrors/stable-diffusion-webui-docker.git .）

# 3. 创建数据持久化目录（data 存模型，output 存生成图）
mkdir -p data output

# 4. 赋予目录读写权限（避免容器无法访问，新手推荐 777 权限）
sudo chmod -R 777 data output

⚙️ 配置 Docker Compose

创建部署目录

mkdir -p /home/compose/stable-diffusion-webui-docker
cd /home/compose/stable-diffusion-webui-docker

配置文件解析

创建 docker-compose.yml 文件，内容基于用户提供的配置：

# 1. 基础服务模板（复用配置，减少重复）
x-base_service: &base_service
    ports:
      - "${WEBUI_PORT:-7860}:7860"  # 端口映射，默认 7860，可通过环境变量改端口
    volumes:
      - &v1 ./data:/data  # 本地 data → 容器 /data（模型、配置持久化）
      - &v2 ./output:/output  # 本地 output → 容器 /output（生成图持久化）
    stop_signal: SIGKILL  # 强制停止信号（避免容器僵死）
    tty: true  # 保持容器交互模式（AI 服务需此配置）
    deploy:
      resources:
        reservations:
          devices:   # GPU 配置（comfy-cpu 会覆盖此部分）
              - driver: nvidia
                device_ids: ['0']
                capabilities: [compute, utility]

name: webui-docker

# 2. 服务列表（重点看 comfy-cpu）
services:
# ... 其他服务（auto、auto-cpu 省略，重点看 comfy 相关）...
  download:
    build: ./services/download/
    profiles: ["download"]
    volumes:
      - *v1

  auto: &automatic
    <<: *base_service
    profiles: ["auto"]
    build: ./services/AUTOMATIC1111
    image: sd-auto:78
    environment:
      - CLI_ARGS=--allow-code --medvram --xformers --enable-insecure-extension-access --api

  auto-cpu:
    <<: *automatic
    profiles: ["auto-cpu"]
    deploy: {}
    environment:
      - CLI_ARGS=--no-half --precision full --allow-code --enable-insecure-extension-access --api


  comfy: &comfy  # ComfyUI GPU 版模板
    <<: *base_service  # 继承基础模板配置
    profiles: ["comfy"]  # 标签：启动需指定 --profile comfy
    build: ./services/comfy/  # 从本地目录构建镜像（非拉取现成镜像）
    image: sd-comfy:7  # 构建后的镜像名
    environment:
      - CLI_ARGS=   # 运行参数（GPU 版默认空）


  comfy-cpu:  # 重点！ComfyUI CPU 版（我们要启动的服务）
    <<: *comfy  # 继承 ComfyUI 基础配置
    profiles: ["comfy-cpu"]  # 标签：启动需指定 --profile comfy-cpu
    deploy: {}  # 覆盖 GPU 配置（CPU 版无需 GPU 资源）
    environment:
      - CLI_ARGS=--cpu  # 关键参数：启用 CPU 模式运行
    restart: always  # 容器退出后自动重启（保障服务稳定）

关键配置说明

1. 网络配置：使用默认的 bridge 网络，端口映射到宿主机的 7860 端口
2. 数据持久化：
3. ./data:/data：模型数据和配置存储
4. ./output:/output：生成图片输出目录
5. 服务配置：
6. GPU 服务：使用 NVIDIA 运行时，device_ids 指定使用的 GPU 编号
7. CPU 服务：deploy 配置为空，不使用 GPU 资源
8. 启动参数：
9. --medvram：中等显存优化，适合 8GB 以下显存
10. --xformers：使用 xformers 库优化注意力机制
11. --api：启用 API 接口，便于其他程序调用

---

关键配置说明（新手必知）

• profiles: ["comfy-cpu"]：服务标签，启动时需通过 --profile comfy-cpu 指定，否则不会启动该服务；
• deploy: {}：清空 GPU 相关配置，避免因无 GPU 导致启动失败；
• CLI_ARGS=--cpu：强制启用 CPU 运行模式，是 comfy-cpu 与 GPU 版的核心区别；
• volumes: ./data:/data：模型默认存于 ./data/models，后续可手动放入自定义模型（如 SD 2.1、RealVis）。

---

🚀 启动与验证

启动服务

根据硬件配置选择对应的 profile 启动：

GPU 用户启动 ComfyUI：

docker compose -f /home/compose/stable-diffusion-webui-docker/docker-compose.yml --profile comfy up -d

CPU 用户启动 ComfyUI：

docker compose -f /home/compose/stable-diffusion-webui-docker/docker-compose.yml --profile comfy-cpu up -d

GPU 用户启动 AUTOMATIC1111：

docker compose --profile auto up -d

CPU 用户启动 AUTOMATIC1111：

docker compose --profile auto-cpu up -d

验证服务状态

1. 检查容器运行状态 bash docker ps 应该看到对应的服务容器处于 Up 状态

2. 查看服务日志 bash docker compose logs -f

3. 访问 Web 界面 在浏览器中访问 http://你的服务器IP:7860

初始设置

首次访问会加载界面，根据需要： - AUTOMATIC1111：功能丰富的经典界面，适合进阶用户 - ComfyUI：节点式工作流界面，适合可视化操作

🔌 基础配置与使用

模型管理

1. 放置模型文件
2. 将下载的 Stable Diffusion 模型（.safetensors 或 .ckpt 文件）放入 ./data/Models 目录

3. 模型会自动加载到对应的 WebUI 中

4. 常用模型推荐

5. 基础模型：SD 1.5、SDXL
6. 动漫风格：Anything V5、NovelAI
7. 写实风格：Realistic Vision、Deliberate

基本使用流程

步骤	操作	说明
1	选择模型	在 WebUI 左上角选择已下载的模型
2	输入提示词	用英文描述想要生成的画面内容
3	调整参数	设置图片尺寸、采样步数、引导系数等
4	生成图片	点击生成按钮，等待图片生成

性能优化建议

1. GPU 显存优化 ```yaml environment:

   • CLI_ARGS=--medvram --xformers # 中等显存使用 # - CLI_ARGS=--lowvram --xformers # 低显存使用 ```

2. 图片生成参数

3. 分辨率：根据显存大小调整，推荐 512x512 或 768x768
4. 批处理数量：适当增加 batch count 提升生成效率

---

🔌 基础配置与使用2

ComfyUI 以 “节点式操作” 为核心，新手可按以下步骤生成第一张 AI 图片：

1. 步骤 1：加载默认工作流

首次访问 WebUI 时，界面会自动加载 “默认文本生成图片” 工作流（无需手动搭建节点），包含 4 个核心节点：

• Load Checkpoint：加载 AI 模型（默认加载 v1-5-pruned-emaonly.safetensors 模型）；
• CLIP Text Encode：输入文本提示词（描述要生成的内容）；
• KSampler：采样器（控制生成速度与质量）；
• Save Image：保存生成的图片（自动存到 ./output 目录）。

2. 步骤 2：输入文本提示词（Prompt）

1. 点击 CLIP Text Encode 节点中的 text 输入框，输入提示词（示例）：
   • 正面提示词：a beautiful girl, blue eyes, long hair, sunset, detailed, 8k（描述要生成的元素）；
   • 负面提示词（可选，点击 CLIP Text Encode (Neg) 节点）：ugly, blurry, low resolution, bad hands（描述要避免的元素）。

3. 步骤 3：调整生成参数（新手默认即可）

点击 KSampler 节点，可调整以下关键参数（新手建议默认）：

• Sampler：采样器（如 euler，速度快；dpmpp_2m，质量高）；
• Steps：采样步数（20-50，步数越多质量越高，但耗时越长）；
• Width/Height：图片尺寸（默认 512x512，CPU 建议不超过 768x768，避免内存不足）。

4. 步骤 4：生成图片

1. 点击界面右上角的 Queue Prompt 按钮（或按 Ctrl+Enter），开始生成图片；
2. 底部状态栏显示生成进度（如 10/20 steps），CPU 生成 512x512 图片约需 1-5 分钟（取决于 CPU 性能）；
3. 生成完成后：
   • 界面右侧会显示预览图；
   • 图片自动保存到本地 ./output 目录（文件名含时间戳，如 ComfyUI_00001_.png）。

---

🛠️ 维护与管理

日常维护操作

1.服务启动/停止

# 停止服务
docker compose down

# 启动服务
docker compose up -d

2.数据备份

# 备份模型和配置数据
tar -czf sd-backup-$(date +%Y%m%d).tar.gz ./data

# 备份生成的作品
tar -czf output-backup-$(date +%Y%m%d).tar.gz ./output

3.服务更新

# 进入部署目录
cd /home/compose/stable-diffusion-webui-docker

# 重新构建镜像（如果源码更新）
docker compose build

# 重启服务
docker compose down
docker compose up -d

监控与日志

1. 查看实时日志

docker compose logs -f [服务名]

1. 监控资源使用

docker stats

1. 检查存储空间

df -h  # 检查磁盘空间
du -sh ./data  # 查看模型数据大小

---

1. 容器基础操作

操作需求	命令（需在部署主目录执行）	说明
停止 comfy-cpu 服务	docker compose --profile comfy-cpu down	停止容器，数据保存在 data/output
重启服务	docker compose --profile comfy-cpu restart	配置修改或服务卡顿后执行
查看实时日志（排错）	docker compose logs -f comfy-cpu	查看生成过程、错误信息（按 Ctrl+C 退出）
进入容器内部（进阶）	docker exec -it stable-diffusion-webui-docker-comfy-cpu-1 /bin/bash	可手动查看模型、依赖（容器名需按实际修改）

2. 数据备份（防止丢失）

核心数据在 data（模型）和 output（生成图）目录，定期备份：

# 打包备份（文件名含日期，便于区分）
tar -czf sd-backup-$(date +%Y%m%d).tar.gz data output

3. 更新服务（获取新版本）

# 1. 拉取最新源码（同步官方配置更新）
git pull

# 2. 重新构建镜像并启动（若官方更新了依赖或服务逻辑）
docker compose -f docker-compose.yml --profile comfy-cpu up -d --build

4. 清理无用数据（释放空间）

• 清理旧生成图：直接删除 ./output 目录下不需要的图片；
• 清理未使用模型：删除 ./data/models/Stable-diffusion 目录下不需要的模型文件（如旧版本模型）；
• 清理 Docker 缓存：docker system prune -a（谨慎！会删除所有未使用的镜像、容器）。

---

🐛 常见问题排查

1. 容器启动失败

问题现象：docker ps 显示容器状态不是 Up

解决方案： - 检查日志：docker compose logs [服务名] - 验证端口占用：netstat -tulpn | grep 7860 - 检查 GPU 驱动：nvidia-smi（GPU 用户）

2. 无法访问 Web 界面

问题现象：浏览器访问 http://IP:7860 无响应

解决方案： - 检查防火墙设置： bash # 开放 7860 端口 ufw allow 7860 - 验证服务绑定地址：确保服务绑定到 0.0.0.0 而不是 127.0.0.1

3. GPU 无法使用

问题现象：GPU 服务启动但无法识别 GPU

解决方案： - 检查 NVIDIA Container Toolkit 安装： bash docker run --rm --runtime=nvidia nvidia/cuda:11.8-base-ubuntu22.04 nvidia-smi - 验证 device_ids 配置：确保 device_ids: ['0'] 与实际 GPU 编号一致

4. 显存不足错误

问题现象：生成图片时出现 CUDA out of memory

解决方案： - 使用低显存模式：在环境变量中添加 --lowvram - 降低图片分辨率：使用 512x512 而不是更高分辨率 - 减少批处理大小：设置 --batch-size 1

5. 模型加载失败

问题现象：模型在 WebUI 中显示但无法加载

解决方案： - 检查模型文件完整性：重新下载模型文件 - 验证模型格式：支持 .safetensors 和 .ckpt 格式 - 检查文件权限：确保 Docker 容器有读取权限

通过本教程，您应该已经成功部署并配置了 Stable Diffusion WebUI，现在可以开始创作 AI 生成的图片了。如果在使用过程中遇到其他问题，可以参考项目官方文档或社区支持资源。

---

🐛 常见问题排查2

1. 容器启动失败，日志提示 “permission denied”

• 原因：data 或 output 目录权限不足，容器无法读写。
• 解决：重新执行 sudo chmod -R 777 data output，再重启服务。

2. 访问 WebUI 提示 “无法连接”（ERR_CONNECTION_REFUSED）

• 原因 1：容器未启动（State 为 Exited）。

  解决：查看日志修复错误（docker compose logs -f comfy-cpu），再启动服务。 - 原因 2：端口被占用（7860 被其他程序使用）。

  解决：修改端口，执行 WEBUI_PORT=7861 docker compose --profile comfy-cpu up -d，通过 7861 端口访问。 - 原因 3：远程访问时 IP 错误（如 WSL2 用 localhost 访问）。

  解决：WSL2 需用 hostname -I 查看 WSL2 内网 IP（如 192.168.123.45），通过 http://192.168.123.45:7860 访问。

3. 生成图片时提示 “out of memory”（内存不足）

• 原因：CPU 内存不足，无法支撑当前图片尺寸或采样步数。
• 解决：
  1. 减小图片尺寸（如从 768x768 改为 512x512）；
  2. 降低采样步数（如从 50 改为 20）；
  3. 关闭其他占用内存的程序（如浏览器、文档）。

4. 生成图片模糊或质量差

• 原因：模型不合适、采样步数少或提示词不精准。
• 解决：
  1. 更换高质量模型（如从 SD 1.5 换成 RealVis 1.0，放入 ./data/models/Stable-diffusion 目录）；
  2. 增加采样步数（如 30-50）；
  3. 优化提示词（添加更多细节描述，如 photorealistic, ultra detailed, cinematic lighting）。

5. 容器启动慢，卡在 “Building comfy”

• 原因：网络问题导致依赖下载慢（如 Python 包、模型）。
• 解决：
  1. 重试启动命令（docker compose --profile comfy-cpu up -d），Docker 会自动续传；
  2. （进阶）修改 Docker 镜像源为国内源（如阿里云），加速依赖下载。

通过以上步骤，新手可快速启动 ComfyUI CPU 版，实现 AI 图像生成。如需尝试 GPU 版（需 NVIDIA 显卡），可将启动命令中的 --profile comfy-cpu 改为 --profile comfy，并确保安装 NVIDIA Docker 驱动。更多功能（如自定义模型、插件）可参考 Stable Diffusion WebUI Docker 官方文档。