规划部署前，先掌握 SD.Next 与 Docker 方案的核心要点
SD.Next 是一款面向本地生成式图像工作流的 AI 绘画工具，它兼容多种主流模型与扩展，特别适合需要长期稳定运行、频繁切换不同模型、以及统一管理运行环境的用户。相较于直接在操作系统中安装 Python、各种依赖库和显卡组件，采用 Docker 部署的核心优势在于环境隔离、迁移便捷以及版本升级可控；其不足之处在于需要提前配置好容器运行环境，尤其是显卡驱动与容器调用 GPU 的能力。
这种部署方式主要适用于三类典型场景：个人电脑希望减少软件依赖冲突；工作站需要固定服务端口，方便局域网内设备访问；团队机器希望将模型文件、输出图片和配置目录独立保存，避免容器删除后重要数据丢失。在正式操作之前，建议您至少准备 30GB 的可用磁盘空间，如果计划保存多个大模型和大量生成结果，预留 100GB 以上的空间会更加稳妥。
环境准备：系统选型、Docker 安装与显卡支持配置
宿主机操作系统可以是 Linux、Windows 或 macOS，但当涉及显卡推理时，Linux 与 Windows 的使用体验通常更为稳定可靠。虽然 CPU 也能运行 SD.Next，但速度较慢，更适合用于测试界面和熟悉操作流程。使用 NVIDIA 显卡时，务必先安装与显卡匹配的驱动程序，并确认 Docker 能够调用 GPU。Linux 用户通常还需要额外安装 NVIDIA Container Toolkit；Windows 用户则建议使用 WSL2 后端，并在 Docker Desktop 中启用对应的集成选项。
要检查 Docker 是否安装就绪，可以执行 docker version 命令；要验证容器能否调用显卡，可以尝试运行 docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi。如果终端能够正常显示显卡信息，说明基础环境已经具备。若系统提示无法识别 --gpus 参数，多半是 Docker 版本过旧，或者显卡容器组件未正确安装。
镜像拉取：选择可信来源并锁定特定版本
部署 SD.Next 时，应优先以项目官方文档或维护者仓库公布的镜像地址为准。常见的示例镜像为 ghcr.io/vladmandic/sdnext:latest，实际使用前建议核对项目页面，避免拉取来源不明的镜像。拉取镜像的命令示例：docker pull ghcr.io/vladmandic/sdnext:latest。
对于生产环境或长期使用，不建议一直依赖 latest 标签，因为它会随着维护者的更新而频繁变化。更稳妥的做法是选择明确的版本标签，例如 docker pull ghcr.io/vladmandic/sdnext:版本号。这样当升级出现问题时，可以快速回滚到旧版本。如果拉取速度较慢，可以更换合规的镜像源，或选择在网络状况较好的时段操作，切忌使用来历不明的二次封装包。
数据目录规划：容器可随时删除，但数据绝不能丢失
在“一键部署”过程中，最容易忽略的就是数据目录的规划。容器内部的文件在容器重建时可能会被清空，因此模型、输出图片、扩展插件、配置文件等都应挂载到宿主机中。建议建立一个统一的目录，例如 /data/sdnext，并在其中划分 models、outputs、extensions、config、cache 等子目录。Windows 用户可以使用 D:\AI\sdnext 这类路径，但需要注意 Docker Desktop 的文件共享权限设置。
模型目录用于存放 checkpoint、LoRA、VAE 等文件；outputs 目录用于保存生成的图片结果；config 目录用于保存界面配置与启动参数；cache 目录则用于存放依赖或模型缓存。目录命名不必完全固定，但必须确保与容器内 SD.Next 读取的路径相对应。如果不太确定路径，可以先启动一次容器查看默认的目录结构，再将关键目录重新挂载。
端口映射：让浏览器顺利访问 Web 界面
SD.Next 常见的 Web 服务端口为 7860。Docker 端口映射的格式为 -p 宿主机端口:容器端口，例如 -p 7860:7860。部署完成后，在宿主机浏览器中访问 https://127.0.0.1:7860 即可打开操作界面。如果希望局域网内的其他设备也能访问，需要让程序监听 0.0.0.0，并确认系统防护策略允许该端口通信。
如果本机 7860 端口已被其他程序占用，可以改用宿主机其他端口，例如 -p 17860:7860，此时访问地址变为 https://127.0.0.1:17860。排查端口问题时，可以使用 docker ps 查看容器是否正在运行，使用 docker logs 容器名 查看启动日志，从而确认 Web 服务是否真正启动成功。
一键运行示例：通过 docker run 快速部署
以下命令可以作为基础模板，实际镜像名与路径请根据你的环境进行调整：docker run -d --name sdnext --gpus all -p 7860:7860 -v /data/sdnext/models:/app/models -v /data/sdnext/outputs:/app/outputs -v /data/sdnext/config:/app/config --restart unless-stopped ghcr.io/vladmandic/sdnext:latest。
参数含义非常关键：-d 表示后台运行；--name 指定容器名称，方便后续管理；--gpus all 允许容器使用全部 NVIDIA 显卡；-p 负责端口映射；-v 负责数据挂载；--restart unless-stopped 可在系统重启后自动恢复服务。如果你的镜像内部工作目录并非 /app，需要按照镜像说明修改挂载目标，否则可能出现模型放入宿主机目录后，界面仍无法识别的问题。
使用 Compose 管理：更适合长期稳定运行
如果你需要频繁升级、调整端口或增加环境变量，强烈建议使用 Docker Compose 进行管理。创建一个 compose.yaml 文件，写入服务名、镜像、端口、挂载目录、GPU 配置和重启策略，然后执行 docker compose up -d。相比于一长串命令，Compose 文件更便于保存和复用，也能方便地迁移到另一台机器。
在 Compose 文件中，应明确指定 image 标签，端口可写为 "7860:7860"，目录挂载写为 /data/sdnext/models:/app/models。升级时，先执行 docker compose pull，再执行 docker compose up -d。如果新版本出现异常，只需将 image 标签改回旧版本并重新启动，数据目录仍然保留在宿主机中，不受影响。
启动后的基础配置与模型放置指南
容器启动后，先打开 Web 界面确认是否能正常加载。首次启动时可能会下载依赖或初始化缓存，日志中短时间内出现等待提示并不一定是故障。将模型文件放入挂载的 models
建议先用一个体积适中的模型测试出图，再逐步加入 LoRA、ControlNet 模块或其他扩展插件。扩展越多，启动时间和故障概率也会相应增加。对于多用户共用的机器，应约定统一的目录规范，避免重复下载同一模型造成磁盘空间浪费。
升级、回滚与备份策略：确保数据安全
升级前，务必先备份 config、extensions 以及关键模型索引文件，outputs 目录可按日期进行归档。使用 latest 标签时，升级命令虽然简单，但风险更高；使用版本标签时，升级路径则更加清晰可控。推荐的升级流程是：停止容器、备份配置、拉取新镜像、启动新容器、检查日志、测试基础生图、确认扩展可用。
回滚时不要急着删除数据目录，只需停止当前容器，使用旧镜像标签重新创建容器，并挂载原来的目录即可。如果是扩展插件导致异常，可以临时移走 extensions 目录中的新增内容，再启动排查问题。大型模型文件通常无需重复备份，但重要配置文件和自定义工作流应定期保存。
常见问题与排查方向：快速解决部署难题
问题一：页面打不开。首先检查 docker ps 是否有容器运行，其次确认端口映射是否正确，最后使用 docker logs 查看服务是否绑定到正确的地址。如果只监听 127.0.0.1，局域网设备可能无法访问。
问题二：无法调用显卡。检查宿主机显卡驱动、Docker GPU 支持以及启动参数 --gpus all。在容器内运行 nvidia-smi 是最直接的验证方式。如果显存不足，可以降低生成分辨率、减少批量数量或换用更轻量的模型。
问题三：模型不显示。通常是挂载路径错误、目录层级不符合程序要求，或者模型文件尚未刷新。可以进入容器查看目标目录是否真的存在文件。
问题四：升级后扩展失效。先禁用近期新增的扩展，确认主程序正常运行，再逐个恢复启用。不要在同一个目录混用多个来源不明的扩展版本。
安全边界与实用建议：保障运行环境
SD.Next 默认更适合本机或可信局域网内使用，不建议直接暴露到公网。如果确实需要远程访问，应使用成熟的身份验证、访问控制和日志审计方案，并严格限制可访问的来源 IP。不要将含有隐私素材、商业素材或未授权模型随意放入共享目录。
镜像与扩展只从可信渠道获取，启动命令中避免随意加入不理解的高权限参数。容器虽然提供了隔离性，但并不等于绝对安全。对普通用户来说，最稳妥的部署原则是：固定镜像版本、明确端口映射、持久化数据目录、升级前做好备份、出现问题先查看日志。按照这个思路部署，SD.Next 的 Docker 环境将更容易维护，也更适合长期作为本地 AI 绘画工具使用。
