Stable Diffusion WebUI Docker 环境搭建指南

配套的 entrypoint.sh 脚本如下：

#!/bin/bash
# 启动 SSH 服务
service ssh start
# 激活 conda 环境
eval "$(conda shell.bash hook)"
conda activate py310
# 如果传入命令，则执行；否则保持容器运行
if [ $# -gt 0 ]; then
    exec "$@"
else
    while true; do
        sleep 1000
    done
fi

小贴士：这里使用 eval "$(conda shell.bash hook)" 是为了正确加载 conda 命令环境，避免 command not found: conda 错误。

构建镜像：

docker build -t miniconda-py310-sd:latest .

耐心等待完成后，你就拥有了一个集成了 Conda、Python 3.10、国内源加速、SSH 支持的基础开发镜像。

启动容器：带上 GPU 和数据卷

接下来就是最关键的一步：启动容器。我们需要确保 GPU 可用、内存足够、代码和模型可持久化。

docker run -dit \
    --name sd-webui \
    --gpus all \
    --shm-size=8gb \
    -p 7860:7860 \
    -p 8888:8888 \
    -p 2222:22 \
    -v $(pwd)/stable-diffusion-webui:/workspace/stable-diffusion-webui \
    -v /mnt/data/models:/workspace/models \
    miniconda-py310-sd:latest

参数说明：

• --gpus all：启用所有可用 GPU（需提前安装 NVIDIA Container Toolkit）
• --shm-size=8gb：增大共享内存，防止多线程加载图像时出现 OOM
• -p：分别映射 WebUI、Jupyter 和 SSH 端口
• -v：挂载项目代码和模型目录，实现数据持久化

进入容器：

docker exec -it sd-webui bash

你应该会看到类似提示符：

(py310) root@container-id:/workspace#

说明 conda 环境已自动激活，可以开始安装依赖了。

部署 Stable Diffusion WebUI

1. 克隆项目

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

建议固定某个稳定提交版本，避免因主干更新导致兼容性问题：

git checkout <commit-hash>

2. 安装关键依赖

（1）PyTorch with CUDA 支持

这是最容易出错的一环。务必根据宿主机 CUDA 版本选择正确的安装命令。

查看宿主机 CUDA 版本：

nvidia-smi

假设输出显示 CUDA Version: 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

验证是否可用 GPU：

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

预期输出：

2.1.0+cu118 True

⚠️ 注意：不要盲目 pip install torch，这会安装 CPU 版本！

（2）安装 CLIP 与 OpenCLIP

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

OpenCLIP 支持更多模型变体，如 ViT-bigG，对高级用户很有用。

（3）人脸修复模块 GFPGAN

pip install gfpgan

如果需要从源码编译（例如支持最新特性），可手动克隆安装：

git clone https://github.com/TencentARC/GFPGAN.git
cd GFPGAN
pip install -r requirements.txt
python setup.py develop

（4）其他必要依赖

pip install -r requirements.txt
pip install opencv-python-headless
pip install xformers --index-url https://download.pytorch.org/whl/cu118

关于 xformers：它能显著降低显存占用并提升推理速度，尤其在高分辨率生成时效果明显。但必须确保其 CUDA 版本与 PyTorch 匹配，否则会报错。

如果你遇到 xformers 安装失败，可以尝试以下替代方案：

# 方法一：使用预编译包
pip install -U xformers --index-url https://download.pytorch.org/whl/cu118
# 方法二：关闭 xformers，在启动参数中添加 --disable-xformers

启动 WebUI 服务

一切准备就绪后，回到项目根目录：

cd /workspace/stable-diffusion-webui

使用优化后的启动命令：

COMMANDLINE_ARGS="--listen --port=7860 --enable-insecure-extension-access --no-half-vae --xformers" ./webui.sh

各参数含义：

首次运行会自动下载基础配置文件（如 config.yaml）和安全检查模型（model.safetensors）。如果你已经准备好模型，建议提前放入：

/workspace/models/Stable-diffusion/

这样可以跳过漫长的网络下载过程。

启动成功后，浏览器访问：

http://<your-server-ip>:7860

你应该能看到熟悉的 WebUI 界面，包括：

• 文生图（txt2img）
• 图生图（img2img）
• 局部重绘（Inpaint）
• 模型管理
• 插件中心

调试利器：Jupyter 与 SSH

虽然 WebUI 已经很强大，但在做模型微调、数据处理或实验探索时，交互式编程仍然不可替代。

Jupyter Notebook 使用方式

在容器内安装 Jupyter：

pip install jupyter

生成配置文件：

jupyter notebook --generate-config

设置密码（推荐）：

python -c "from notebook.auth import passwd; print(passwd())"

复制输出的哈希值，编辑配置文件：

vim ~/.jupyter/jupyter_notebook_config.py

添加以下内容：

c.NotebookApp.ip = '0.0.0.0'
c.NotebookApp.port = 8888
c.NotebookApp.open_browser = False
c.NotebookApp.allow_remote_access = True
c.NotebookApp.password = 'sha1:xxxxxxx' # 替换为你生成的密码哈希
c.NotebookApp.notebook_dir = '/workspace'

启动服务：

jupyter notebook --allow-root

访问地址：http://<your-server-ip>:8888

此时你可以在浏览器中新建 .ipynb 文件，测试 GPU 是否可用：

import torch
print(torch.cuda.is_available())
print(torch.randn(1000, 1000).cuda().sum()) # 应正常输出

SSH 登录：长期维护更方便

对于服务器部署或团队协作，SSH 是比 docker exec 更优雅的选择。

我们在 Dockerfile 中已经安装了 openssh-server，只需确保服务启动即可。

修改 /etc/ssh/sshd_config：

sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config
sed -i 's/PasswordAuthentication no/PasswordAuthentication yes/' /etc/ssh/sshd_config

设置密码：

echo 'root:mypassword' | chpasswd

然后在 entrypoint.sh 中确保 service ssh start 被调用。

之后即可从外部连接：

ssh root@<server-ip> -p 2222

这样即使断开终端，容器内的进程依然运行，非常适合长时间训练任务。

生产级建议：稳定性与可维护性

1. 模型存储分离

强烈建议将模型目录单独挂载到高速 SSD 或 NAS 存储上：

-v /data/sd-models:/workspace/models

并在 WebUI 设置中指定路径：

Settings → Stable Diffusion → Checkpoint name → Browse Models

这样做有两个好处：

• 模型不随容器销毁而丢失
• 多个容器可共享同一组模型，节省空间

2. 使用 .env 管理环境变量

在项目根目录创建 .env 文件：

CUDA_VISIBLE_DEVICES=0
TORCH_CUDA_ARCH_LIST="8.6"
SD_WEBUI_LOG_LEVEL=INFO

然后在启动脚本中加载：

set -a
[ -f .env ] && source .env
set +a

这些变量会影响 PyTorch 编译行为和日志输出级别，对调试非常有用。

3. 自动备份与迁移

定期提交容器为新镜像，防止意外损坏：

docker commit sd-webui sd-webui:backup-$(date +%Y%m%d)

导出镜像便于跨机迁移：

docker save -o sd-webui-backup.tar sd-webui:latest
scp sd-webui-backup.tar user@remote:/backup/
# 在目标机器导入
docker load -i sd-webui-backup.tar

当然，更现代的做法是结合 Kubernetes 或 CI/CD 流水线实现自动化部署，但这超出了本文范围。

常见问题与解决方案

还有一个隐藏陷阱：Python 版本太高会导致某些旧插件不兼容。目前最稳妥的是锁定在 Python 3.10，避免升级到 3.11 或更高。

总结

通过 Docker + Miniconda 的组合，我们实现了：

✅ 环境完全隔离
✅ 依赖精确可控
✅ GPU 支持开箱即用
✅ 支持 Jupyter 和 SSH 远程调试
✅ 数据持久化与快速迁移

这一架构不仅适用于个人开发者本地测试，也完全可以作为团队共享的 AI 开发平台基础模板。未来还可以进一步扩展：

• 添加 HTTPS 反向代理（Nginx + Let's Encrypt）
• 集成 MinIO 实现模型版本管理
• 结合 Redis + Celery 构建异步任务队列
• 使用 Prometheus + Grafana 监控 GPU 使用率

⚠️ 最后提醒一句：请合法合规使用生成模型，切勿生成违法不良信息。

现在，你已经有了一个稳定、高效、可复用的 Stable Diffusion 开发环境。下一步，不妨试试接入 ControlNet、训练 LoRA 模型，或是打造自己的 AI 绘画工作流。

生成式 AI 的大门，已经为你敞开。