为什么建议用 Docker 部署 Stable Diffusion WebUI

Stable Diffusion WebUI 是常用的 AI 绘画工具。它支持文生图、图生图、局部重绘、扩展插件、模型切换等功能。

传统安装需要处理 Python、CUDA、PyTorch、依赖包版本等问题。初学者很容易遇到环境冲突。

Docker 部署的优势在于，它把运行环境封装到镜像里。用户只需要准备好 Docker、显卡驱动和模型文件，就能较快启动 WebUI。

这种方式尤其适合三类场景：

• 新机器快速搭建绘图环境。
• 多人团队统一运行版本。
• 本机已有复杂开发环境，不想再安装大量依赖。

注意：Docker 并不会减少显存需求，模型推理仍然依赖硬件性能。若使用 1.5 系列模型，建议显存 6GB 起步。若使用 SDXL 类模型，建议显存更高，并预留足够磁盘空间。

部署前准备：环境、目录与镜像选择

1. 环境确认

首先，确认系统已安装 Docker，并能正常执行 docker version。Linux 用户还应确认当前账号具备运行 Docker 的权限。Windows 用户建议使用支持 Linux 容器的 Docker Desktop。

其次，如果需要调用 NVIDIA 显卡，应提前安装匹配的显卡驱动。还需要配置 NVIDIA Container Toolkit。之后可通过以下命令测试容器是否能识别显卡：docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi。

2. 准备数据目录

建议在宿主机创建一个独立目录，例如 /data/sd-webui。在其中建立 models、outputs、extensions、config 等子目录。这样做的好处是：容器删除或升级后，模型和作品不会丢失。

Windows 用户可使用 D:sd-webui 这类路径。但在 Docker 命令中要注意路径写法，例如 -v D:sd-webuimodels:/app/stable-diffusion-webui/models。

3. 镜像选择

镜像选择要优先考虑：

• 维护状态和说明文档。
• 版本更新频率。
• 运行入口是否清晰。

常见做法是使用已集成 WebUI 的第三方镜像。也可以自行基于 CUDA 基础镜像构建。新手建议先选择成熟镜像完成部署，再根据需要定制。拉取前应查看镜像标签，尽量不要盲目使用 latest。生产或长期使用环境可固定版本号，方便后续回滚。

第一步：拉取 Stable Diffusion WebUI 镜像

镜像拉取命令通常为：docker pull 镜像名:标签。示例：docker pull ghcr.io/example/stable-diffusion-webui:latest。实际使用时，请替换为你选定的镜像地址。

若镜像体积较大，首次下载时间较长属于正常情况。下载完成后可执行 docker images 查看本地镜像列表，确认镜像名称、标签和大小。

如果团队内部统一部署，建议把镜像版本记录到部署文档中。例如：WebUI 版本、Python 版本、CUDA 版本、镜像摘要等。这样在排查问题时，可以判断是模型、插件还是镜像版本导致的异常。不要随意混用多个来源不明的镜像，尤其是带有未知启动脚本的镜像，避免产生数据泄露或恶意文件写入风险。

第二步：配置端口映射并启动容器

Stable Diffusion WebUI 默认常用端口是 7860。Docker 容器内的 7860 端口需要映射到宿主机端口，浏览器才能访问。

基础启动命令可写为：docker run -d --name sd-webui --gpus all -p 7860:7860 镜像名:标签。启动后执行 docker ps，看到容器处于 Up 状态，表示服务已运行。随后在浏览器访问 http://127.0.0.1:7860 即可进入界面。

端口映射格式是 宿主机端口:容器端口。例如 -p 17860:7860，表示浏览器访问 http://127.0.0.1:17860，容器内部仍使用 7860。若 7860 已被其他程序占用，就改用 17860、27860 等不冲突端口。

安全提示：不要把管理页面直接暴露到不受控网络中。如果确实需要多人访问，应放在受信任内网，并结合访问控制、日志审计和最小权限原则。

有些镜像要求添加启动参数，例如 --listen 让服务监听容器网络地址，或 --xformers 启用特定优化。不同镜像入口不同，参数应以镜像说明为准。若启动后页面打不开，先检查 docker logs sd-webui，看是否仍在下载依赖、加载模型，或是否报端口、权限、显卡相关错误。

第三步：挂载模型、输出与配置目录

只启动容器还不够，关键是把宿主机目录挂载到容器内。常见命令示例：

docker run -d --name sd-webui --gpus all -p 7860:7860 -v /data/sd-webui/models:/app/stable-diffusion-webui/models -v /data/sd-webui/outputs:/app/stable-diffusion-webui/outputs -v /data/sd-webui/extensions:/app/stable-diffusion-webui/extensions 镜像名:标签

不同镜像的 WebUI 安装路径可能不一样。常见位置包括：/app/stable-diffusion-webui、/workspace/stable-diffusion-webui 或 /stable-diffusion-webui。挂载前一定要查看镜像说明，确保容器路径正确。若路径挂错，表现通常是模型放入宿主机目录后 WebUI 不显示，或生成图片没有保存到预期位置。

模型文件一般放在以下目录：

• Stable Diffusion 模型：放在 models/Stable-diffusion 目录。
• VAE：放在 models/VAE 目录。
• LoRA：放在 models/Lora 目录。
• ControlNet 模型：放在 extensions 对应目录或 models/ControlNet，具体取决于插件版本。

模型文件体积较大，建议按类型分目录管理。并保留来源、版本和用途说明，避免后期混乱。输出目录 outputs 应定期整理，长时间使用后会占用大量空间。

使用 Docker Compose 简化一键启动

如果需要长期使用，推荐写 docker-compose.yml。把端口、挂载目录、显卡参数和重启策略固定下来。核心配置包括：image、container_name、ports、volumes、restart 等。

启动时只需在配置文件所在目录执行 docker compose up -d。停止服务执行 docker compose down。查看日志执行 docker compose logs -f。相比长命令，Compose 更便于修改和留档，也方便迁移到新机器。

升级镜像时，不要直接覆盖旧环境。稳妥做法是：

1. 先停止容器，备份配置目录和插件目录。
2. 再拉取新镜像并启动。
3. 若新版本出现插件不兼容、界面报错或推理异常，可恢复旧镜像标签和原目录。

长期项目建议使用固定标签，例如 v1.x，而不是始终跟随最新版本。

常见问题与排查方法

问题一：容器启动后页面无法访问

先执行 docker ps 查看容器是否运行，再确认端口映射是否正确。如果容器反复退出，使用 docker logs sd-webui 查看报错。常见原因包括：模型路径不存在、启动参数不匹配、端口被占用、显卡不可用。

问题二：WebUI 无法识别显卡

先在宿主机运行 nvidia-smi，确认驱动可用。再用测试容器验证 Docker 是否能调用显卡。启动命令中要包含 --gpus all。若仍失败，通常与驱动版本、容器运行时配置或镜像 CUDA 版本有关。

问题三：模型列表为空

检查模型是否放入正确目录，文件扩展名是否为 safetensors 或 ckpt。并确认挂载路径没有写错。也可以在容器内执行 ls 查看实际目录内容。若模型刚放入，可在 WebUI 界面刷新模型列表。

问题四：生成速度慢或显存不足

可尝试以下方法：

• 降低分辨率。
• 减少批量数量。
• 关闭高消耗插件。
• 使用更轻量模型。

部分优化参数能改善性能，但可能带来兼容问题。建议逐项启用并记录变化，不要一次修改过多设置。

安全边界与实用建议

安全方面

部署 AI 绘画工具时，安全边界不能忽视。

• 镜像、模型和插件都应来自可信来源，下载后尽量核对文件信息。
• 不要运行来源不明的脚本。
• 不要在容器中挂载无关的重要系统目录。
• 不要使用特权模式启动，除非你清楚每个参数的影响。
• 对外提供服务时，应限制访问范围，避免把后台页面暴露给陌生访问者。

数据管理方面

• 建议把 models、outputs、extensions、config 分开挂载。
• 定期备份 config 和常用插件配置。
• 模型文件可单独归档，不必每次全量备份。
• 多人共用时，应约定模型命名规范和输出目录规则，避免误删或覆盖。
• 若用于商业设计，还需确认模型授权、素材来源和生成内容的使用范围。

总结

总体来看，Docker 部署 Stable Diffusion WebUI 的核心并不复杂：选对镜像，映射好端口，挂载好数据目录，再通过日志排查问题。只要把版本、路径、参数记录清楚，后续升级、回滚和迁移都会轻松很多。