为什么建议用 Docker 部署 WebUI
Stable Diffusion WebUI 是很多用户接触本地 AI 绘图的首选工具，优点是插件丰富、参数可调、模型生态成熟。但它对 Python 版本、显卡驱动、CUDA 组件、依赖库比较敏感，直接在系统里安装容易出现环境冲突。Docker 的价值在于把运行环境打包到容器中，宿主机只需要准备好 Docker、显卡驱动和模型文件，就能减少“这台电脑能跑、换一台就报错”的问题。
适合使用 Docker 的场景包括：Windows 或 Linux 用户希望快速部署；已有显卡但不想手动配置 Python；团队需要统一环境；经常测试不同版本 WebUI 或插件；担心本机环境被大量依赖污染。需要注意的是，Docker 不是万能修复工具，显卡驱动、硬件性能、模型来源和磁盘空间仍然要自己确认。
部署前准备：先把环境检查清楚
硬件方面，建议使用支持 CUDA 的 NVIDIA 显卡，显存 6GB 可体验基础功能，8GB 以上更从容，生成高分辨率图片、使用 ControlNet 或多插件时最好准备更高显存。内存建议 16GB 起步，磁盘预留 30GB 以上，因为基础镜像、模型、插件和输出图片都会占空间。
软件方面，Windows 用户建议启用 WSL2 后安装 Docker Desktop，并在设置中确认 WSL 集成已开启；Linux 用户安装 Docker Engine 即可。使用 NVIDIA 显卡时，还要安装匹配的显卡驱动，并配置 NVIDIA Container Toolkit，让容器可以调用 GPU。检查命令可用 nvidia-smi，如果宿主机无法正常显示显卡信息，容器内通常也无法使用 GPU。
模型文件建议提前准备好，常见扩展名为 .safetensors 或 .ckpt。优先选择来源可信、说明完整的模型，不要随意运行陌生脚本。WebUI 的常用目录包括 models、extensions、outputs、embeddings、Lora 等，建议统一放在一个独立文件夹中，方便备份和迁移。
方式一：使用 docker run 快速启动
新手可以先用单条命令验证环境。假设本地目录为 /data/sd-webui，其中用于保存模型和输出内容，可执行类似命令：docker run --gpus all -it --name sd-webui -p 7860:7860 -v /data/sd-webui:/workspace/stable-diffusion-webui/models your-image-name。不同镜像的目录结构可能不同，实际挂载路径要以镜像说明为准。
启动后，查看日志中是否出现 WebUI running on local URL 或类似提示。浏览器访问 https://127.0.0.1:7860，能打开页面说明基础部署成功。如果部署在局域网服务器上，需要把启动参数设置为监听 0.0.0.0，并确认防火墙放行对应端口。端口默认多为 7860，如与其他服务冲突，可改为 -p 7861:7860。
第一次启动会比较慢，因为可能需要初始化依赖、扫描模型、生成缓存。不要看到日志短暂停顿就立刻关闭，建议等待数分钟。如果长时间无输出，再检查网络访问、镜像完整性和磁盘空间。
方式二：用 Docker Compose 管理长期运行
如果打算长期使用，更推荐 Docker Compose。它能把端口、目录、GPU、重启策略写进配置文件，后续只需要执行启动、停止、更新命令。配置思路是：指定镜像名称；映射 7860 端口；挂载模型、输出、插件目录；开启 GPU 访问；设置容器异常退出后自动重启。
典型目录可以设计为：sd-webui/models 放大模型，sd-webui/outputs 放生成图片，sd-webui/extensions 放插件，sd-webui/config 放配置。这样即使删除容器，核心数据仍在宿主机。更新镜像前先备份配置文件和重要模型，避免因版本变化导致插件不兼容。
启动后可用 docker compose logs -f 跟踪日志，用 docker compose down 停止服务，用 docker compose pull 获取新版镜像。若新版出现问题，可切回旧标签，不建议始终使用 latest，因为它可能在不经意间引入变化。
模型与插件目录怎么放
Stable Diffusion 主模型通常放在 models/Stable-diffusion，VAE 放在 models/VAE，LoRA 放在 models/Lora，ControlNet 模型放在对应扩展目录或 models/ControlNet。如果 WebUI 页面里看不到模型，先确认挂载路径是否正确，再点刷新按钮，最后看日志是否有权限或格式报错。
插件安装建议从少到多。先确认基础出图正常，再安装 ControlNet、图库管理、提示词辅助等扩展。一次性装太多插件，遇到白屏、按钮缺失、依赖冲突时很难定位。每安装一个关键插件，都记录版本和安装时间，出问题可快速回退。
常见问题排查清单
第一，容器启动但不能用 GPU。检查宿主机 nvidia-smi 是否正常；Docker 是否支持 --gpus all；NVIDIA Container Toolkit 是否安装；容器日志中是否出现 CUDA una vailable。若只能用 CPU，出图速度会非常慢。
第二，浏览器打不开页面。确认容器是否仍在运行，使用 docker ps 查看；确认端口映射是否正确；本机访问用 127.0.0.1，远程访问用服务器地址；若部署在服务器，还要检查安全组或系统防火墙规则。
第三，显存不足或生成中断。降低分辨率、批次数和采样步数，开启低显存参数，如 --medvram 或 --lowvram。同时关闭不必要的插件，避免多个任务并发运行。高分辨率修复、ControlNet、多 LoRA 叠加都会明显增加显存占用。
第四，模型加载失败。常见原因是文件未下载完整、放错目录、权限不足或模型格式不被当前版本支持。可先换一个小模型测试，确认 WebUI 本身正常，再排查目标模型。Linux 反赌意宿主机目录权限，容器用户可能没有读取权限。
第五，插件安装后页面异常。先进入扩展目录移除最近安装的插件，再重启容器。若依赖被改乱，最稳妥的办法是保留 models 和 outputs，重建容器。插件不要盲目追新，生产环境更适合固定版本。
安全边界与实用建议
WebUI 默认更适合在本机或可信局域网中使用，不建议直接暴露到公网。确需多人访问时，应增加访问控制、反向袋里认证或放在受控网络内。不要把管理端口随意开放，也不要在页面里执行来源不明的脚本。
模型、插件和启动脚本都可能影响运行安全。下载前看清项目说明、更新记录和用户反馈；对不熟悉的扩展，先在测试环境验证。生成内容也要遵守平台规范和版权要求，不要使用他人作品、商标或肖像做不当用途。
日常维护建议做到三点：一是固定镜像标签，避免自动升级带来不可控变化；二是定期备份 models、outputs、extensions 和配置文件；三是保留一份可正常运行的 Compose 配置。遇到问题时，先看日志，再查端口、GPU、目录权限和最近改动，通常能快速定位。
整体来看，Docker 部署 Stable Diffusion WebUI 的核心不是记住某条命令，而是把“驱动可用、容器可跑、目录持久化、端口可访问、插件可回退”这几件事做好。只要前期规划清楚，后续升级、迁移和故障恢复都会轻松很多。
