Stable Diffusion WebUI Docker环境搭建全指南

Ne0inhk

15 Mar 2026 — 10 min read

Stable Diffusion WebUI Docker环境搭建全指南

在生成式AI快速落地的今天，越来越多开发者和创作者希望本地部署 Stable Diffusion WebUI ——这个功能强大、插件丰富、社区活跃的文本生成图像平台。但面对复杂的依赖关系、Python版本冲突、CUDA兼容性问题，很多人在环境配置阶段就止步不前。

一个更优雅的解决方案是：用容器化技术封装整个运行时环境。借助 Docker 与 Miniconda 的组合，我们不仅能实现跨主机一键迁移，还能彻底隔离系统依赖，确保每次启动都干净如初。

本文将带你从零构建一个支持 GPU 加速、具备 Jupyter 调试能力、可远程 SSH 管理的 Stable Diffusion 容器化运行环境。无需担心“上次能跑这次报错”的窘境，一切皆可复现。

Miniconda-Python3.10 镜像：轻量而强大的起点

选择 continuumio/miniconda3:latest 作为基础镜像，并非偶然。相比直接使用官方 Python 镜像，Miniconda 提供了更精细的包管理和虚拟环境支持，特别适合需要混合使用 pip 与 conda 安装的 AI 工程项目。

它体积小巧（通常不到 500MB），却自带完整的 Conda 生态，允许你：

创建独立的 sd_env 环境避免污染全局
同时管理 PyTorch（pip）与 OpenCV（conda）等不同来源的库
快速切换 Python 版本以适配特定模型要求

更重要的是，Conda 对 CUDA 相关原生扩展的支持优于纯 pip 方案，这对后续启用 xFormers、TensorRT 至关重要。

初始化容器：GPU 支持与资源分配

在动手之前，请确认你的宿主机已准备就绪：

Docker Engine ≥ 20.10
已安装 NVIDIA 驱动（建议 ≥470）
已配置 NVIDIA Container Toolkit

推荐使用 Ubuntu 20.04/22.04 或 CentOS 7+ 系统，它们对 nvidia-docker2 的兼容性最佳。

接下来启动容器实例：

docker run -itd \ --name sd_webui_container \ --gpus all \ --shm-size=8gb \ -p 7860:7860 \ -p 8888:8888 \ -v $(pwd)/stable-diffusion-webui:/root/stable-diffusion-webui \ -v /mnt/models:/root/models \ continuumio/miniconda3:latest

进入容器进行后续操作：

docker exec -it sd_webui_container /bin/bash

几个关键参数值得说明：

--gpus all：暴露所有 GPU 设备给容器，这是启用 CUDA 的前提。
--shm-size=8gb：增大共享内存。Stable Diffusion 在加载大模型时会频繁使用 /dev/shm，默认 64MB 极易导致 OOM 错误。
-p 7860:7860：WebUI 默认端口。
-p 8888:8888：预留用于 Jupyter Notebook。
-v 挂载：将代码和模型目录持久化到宿主机，避免容器重启后丢失数据。

配置 Python 环境：创建隔离空间并加速下载

首次进入容器后，先初始化 Conda 环境：

conda init bash source ~/.bashrc

然后创建专用虚拟环境：

conda create -n sd_env python=3.10 -y conda activate sd_env

为什么选 Python 3.10？
因为大多数 SD 插件和依赖包（如 xformers、torchvision）对 3.10 的兼容性最成熟，高于或低于此版本均可能出现编译失败。

由于国内访问 PyPI 和 Anaconda 官方源较慢，强烈建议切换至国内镜像：

# 添加清华 TUNA 源 conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --set show_channel_urls yes # 设置 pip 使用清华源 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

此时你已经拥有一个干净、快速、可复用的 Python 3.10 环境，接下来可以开始部署核心组件。

安装 WebUI 及其依赖：手动控制更稳定

虽然 launch.py 提供了一键安装机制，但在实际使用中常因网络中断或版本冲突失败。推荐采用“手动分步安装”策略，掌控全过程。

首先克隆项目代码：

cd /root git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui.git cd stable-diffusion-webui

若宿主机网络较好，也可提前克隆并通过 -v 挂载进容器。

安装 PyTorch（带 CUDA 支持）

这是最关键的一步。务必根据你的 CUDA 版本选择对应 wheel 包：

# 示例：CUDA 11.8 pip install torch==2.1.0+cu118 torchvision==0.16.0+cu118 torchaudio==2.1.0 --extra-index-url https://download.pytorch.org/whl/cu118

常见版本对照：
- CUDA 11.8 → cu118
- CUDA 12.1 → cu121

可通过 nvidia-smi 查看驱动支持的最高 CUDA 版本。

安装 CLIP 与 OpenCLIP

这些是文本编码器的核心依赖：

pip install git+https://github.com/openai/CLIP.git@main pip install open-clip-torch==2.20.0

注意不要遗漏 open-clip-torch，某些 VAE 和 LoRA 模型依赖它。

安装 GFPGAN（人脸修复）

提升人像生成质量的重要插件：

pip install git+https://github.com/TencentARC/GFPGAN.git@master

其他必要库

pip install opencv-python-headless==4.8.0.74 pip install xformers==0.0.23 pip install gradio==3.42.0 pip install fastapi==0.104.1 pip install omegaconf==2.3.0 pip install pyyaml==6.0 pip install huggingface_hub==0.19.4

其中 xformers 是性能优化的关键，稍后会在启动参数中启用。

最后执行：

pip install -r requirements.txt

即使部分模块报错也不必惊慌，WebUI 具有良好的容错机制，非核心功能可后期补装。

模型管理：组织目录结构与合法获取

Stable Diffusion 模型需自行下载并放置于指定路径。建议建立清晰的目录结构以便维护：

mkdir -p /root/models/Stable-diffusion mkdir -p /root/models/ESRGAN mkdir -p /root/models/GFPGAN

例如下载 v1.5 剪枝版权重（请确保你有权使用该模型）：

cd /root/models/Stable-diffusion wget -c https://huggingface.co/runwayml/stable-diffusion-v1-5/resolve/main/v1-5-pruned.safetensors

典型目录结构如下：

/root/models/ ├── Stable-diffusion/ │ └── v1-5-pruned.safetensors ├── ESRGAN/ │ └── RealESRGAN_x4plus.pth └── GFPGAN/ └── GFPGANv1.4.pth

⚠️ 提示：.safetensors 格式比 .ckpt 更安全，可防止恶意代码注入，推荐优先使用。

启动服务：编写脚本并运行 WebUI

为了便于重复启动，建议编写一个启动脚本。

创建 /root/stable-diffusion-webui/webui.sh：

#!/bin/bash export PYTHONPATH=/root/stable-diffusion-webui:$PYTHONPATH export TORCH_CUDA_ARCH_LIST="5.0+PTX;6.0;6.1;7.0;7.5;8.0;8.6" export HF_HOME=/root/.cache/huggingface cd /root/stable-diffusion-webui conda activate sd_env python launch.py \ --listen \ --port 7860 \ --enable-insecure-extension-access \ --theme dark \ --disable-safe-unpickle \ --no-half-vae \ --xformers \ --gpu-device-id 0

赋予执行权限：

chmod +x webui.sh

各参数含义如下：

--listen：允许外部网络访问（否则只能 localhost）
--theme dark：启用深色主题，减少视觉疲劳
--disable-safe-unpickle：允许加载自定义模型（需信任来源）
--no-half-vae：避免 VAE 解码时出现色彩异常
--xformers：启用显存优化，提升推理速度
--gpu-device-id 0：指定主 GPU 编号

运行脚本：

sh webui.sh

打开浏览器访问 http://<your-host-ip>:7860，等待日志输出 “Running on local URL” 即表示服务已就绪。

首次加载可能耗时较长，尤其是模型反序列化阶段，请耐心等待。

扩展功能：不只是图形界面

使用 Jupyter 进行调试与实验

除了 WebUI，你还可以在容器内启用 Jupyter Notebook，用于探索模型行为、测试 prompt 效果或开发插件。

安装 Jupyter：

pip install jupyter

启动服务：

jupyter notebook --ip=0.0.0.0 --port=8888 --allow-root --no-browser

浏览器访问 http://<host-ip>:8888，输入终端打印的 token 即可进入。

你可以编写如下代码快速测试生成效果：

from diffusers import StableDiffusionPipeline import torch pipe = StableDiffusionPipeline.from_pretrained("/root/models/Stable-diffusion/v1-5-pruned") pipe = pipe.to("cuda") image = pipe("a beautiful landscape").images[0] image.save("test_output.png")

这种交互式开发方式非常适合研究人员和算法工程师。

启用 SSH 实现远程管理

如果你希望通过多台设备连接容器，或者需要长期运维，开启 SSH 是个明智选择。

安装 SSH 服务：

apt update && apt install -y openssh-server sudo

修改配置文件：

echo 'PermitRootLogin yes' >> /etc/ssh/sshd_config echo 'PasswordAuthentication yes' >> /etc/ssh/sshd_config echo 'Port 2222' >> /etc/ssh/sshd_config mkdir -p /var/run/sshd

设置 root 密码：

passwd root # 输入密码，如 sd123456

启动服务：

/usr/sbin/sshd

别忘了在运行容器时映射端口：-p 2222:2222

从任意设备连接：

ssh root@<host-ip> -p 2222

成功登录后即可执行命令、传输文件、监控 GPU 使用率（nvidia-smi）、查看日志等。

性能调优：让每一块显存都物尽其用

启用 xFormers 显著提升效率

xFormers 是 Facebook 开源的注意力优化库，能在不损失精度的前提下大幅降低显存占用，并加快生成速度。

安装方式：

pip install xformers==0.0.23 --index-url https://download.pytorch.org/whl/cu118

只要在启动命令中加入 --xformers，WebUI 会自动检测并启用。

实测结果表明，在 A100 上生成 512×512 图像时，显存消耗可减少约 20%，迭代速度提升 15%~30%。

探索 TensorRT 极致加速（进阶）

对于追求极致性能的用户，可尝试集成 NVIDIA TensorRT 对 UNet 进行图级优化。

步骤概览：

下载 TensorRT 8.6.x for CUDA 11.8
解压并配置环境变量：

tar -xzvf TensorRT-8.6.1.6.Linux.x86_64-gnu.cuda-11.8.tar.gz -C /opt/ export LD_LIBRARY_PATH=/opt/TensorRT-8.6.1.6/lib:$LD_LIBRARY_PATH export PATH=/opt/TensorRT-8.6.1.6/bin:$PATH

安装 Python binding：

cd /opt/TensorRT-8.6.1.6/python pip install tensorrt-8.6.1-cp310-none-linux_x86_64.whl

利用 diffusers + tensorrt 构建加速 pipeline（需自定义转换脚本）

更详细教程见官方文档：https://github.com/NVIDIA/TensorRT

尽管配置复杂，但一旦成功，推理延迟可下降 40% 以上，尤其适合高并发 API 服务场景。

日常运维：高效管理你的 AI 容器

以下是一些常用命令，建议收藏备用：

功能	命令
查看容器状态	`docker ps -a`
进入容器	`docker exec -it sd_webui_container /bin/bash`
停止容器	`docker stop sd_webui_container`
删除容器	`docker rm -f sd_webui_container`
删除镜像	`docker rmi <IMAGE_ID>`
提交为新镜像	`docker commit sd_webui_container my_sd_webui:v1.0`
导出镜像	`docker save -o sd_webui_v1.0.tar my_sd_webui:v1.0`
导入镜像	`docker load -i sd_webui_v1.0.tar`

当你完成一次成功的环境配置后，建议使用 docker commit 将其保存为私有镜像。这样下次只需 docker run 即可秒级恢复完整环境，极大提升部署效率。

这种基于 Docker + Miniconda 的构建思路，本质上是一种“基础设施即代码”（IaC）的实践。它不仅解决了环境一致性难题，还为团队协作、CI/CD 流水线、生产部署提供了坚实基础。

未来你可以进一步将其接入 Kubernetes 实现弹性伸缩，或通过 Traefik/Nginx 暴露为统一 API 服务。无论你是个人玩家、小型工作室还是企业研发团队，这套方案都能平滑演进，支撑起不断增长的 AI 应用需求。

Stable Diffusion WebUI Docker环境搭建全指南

Ne0inhk