Stable Diffusion WebUI：最主流的本地文生图 Gradio 界面，模型、LoRA、扩展生态一站式管理｜部署与使用全指南

项目仓库： https://github.com/AUTOMATIC1111/stable-diffusion-webui

开源协议：GNU AGPL v3.0（Copyright © 2023 AUTOMATIC1111） · 运行语言：Python（界面基于 Gradio 3.41.2） · 交付形态：本地 Web 界面与 HTTP API，官方未提供 Docker 镜像 · 默认端口：7860 · 官方文档：项目 Wiki

非官方声明：本文是基于官方 README、官方 Wiki 与仓库源码整理的部署使用指南，不代表项目官方立场。Stable Diffusion、Gradio、xformers、ControlNet 等名称归各自权利人所有；本文提及的模型权重、社区扩展与第三方模型站均遵循其自身许可协议与服务条款，使用者须自行确认合规边界。项目按现状（AS-IS）提供，本文不构成对生成内容、商用授权或平台账号安全的任何担保。

1 项目简介

Stable Diffusion WebUI（社区常称 A1111 WebUI、SD WebUI）是 AUTOMATIC1111 维护的开源 Web 界面，基于 Gradio 实现，用于在本机或自有服务器上运行 Stable Diffusion 系列模型完成文生图、图生图、局部重绘、扩图、放大修复与训练等任务。界面以标签页组织 txt2img、img2img、Extras、PNG Info、Checkpoint Merger、Train、Tokenizer、Settings、Extensions 等功能，模型、LoRA、文本反演（embedding）、VAE、超分与人脸修复模型全部以目录方式纳入管理，并通过扩展（extensions）接入社区大量第三方能力。

项目本身只提供界面、调度与配套工具链，不附带任何 Stable Diffusion 模型权重；首次启动时会按官方流程处理默认模型下载，使用者也可以自行把合规获取的 .ckpt / .safetensors 权重放入模型目录后在界面中切换。

1.1 核心信息一览

1.2 适用场景

• 在个人 Windows / Linux / macOS 工作站上搭建一套可控、可离线使用的 Stable Diffusion 绘图环境，按提示词、负向提示词、采样器、步数、CFG、种子与尺寸参数反复调参出图。
• 已有一张底图，需要做图生图、草图（Sketch）、局部重绘（Inpaint）、扩图（Outpaint）、色彩草图、批量处理（Batch）与高清修复（Hires. fix）等二次编辑。
• 集中管理大量主模型 Checkpoint、LoRA、Hypernetwork、文本反演 embedding、VAE 与超分 / 人脸修复模型，在界面下拉框中随时切换，并通过模型合并工具（Checkpoint Merger）组合权重。
• 通过 --api 暴露本地 HTTP 接口，把出图能力接入自己的脚本、自动化流水线或其他前端；接口说明可在 /docs 在线页面查看。
• 借助社区扩展扩展能力边界，例如 ControlNet 姿态 / 线稿 / 深度控制、Tiled VAE 大图分块、图片浏览器、提示词反推增强等；扩展生态索引见第 4 节。

1.3 能力边界（官方口径）

• 官方 README 自述为 “A web interface for Stable Diffusion, implemented using Gradio library”：项目定位是界面与调度层，模型能力、画质、显存占用与生成速度由所选 Stable Diffusion 权重、采样器、显卡与扩展共同决定，WebUI 本身不承诺特定出图质量。
• README 特性清单覆盖原始 txt2img / img2img、扩图、局部重绘、颜色草图、Prompt Matrix、SD 放大、注意力权重、Loopback、X/Y/Z 图、文本反演、Extras 修复与放大工具链、负向提示词、样式、变体、种子缩放、CLIP 反推、提示词中途编辑、批量处理、高清修复、在线重载 Checkpoint、模型合并、自定义脚本、Composable-Diffusion（AND 多提示词组合）、DeepDanbooru、xformers 加速、训练标签页、CLIP skip、Hypernetwork、LoRA、独立 VAE 切换、API 等；各能力的具体可用范围以当前版本 Wiki 与界面为准。
• 官方硬件口径为 README 中的 “4GB video card support (also reports of 2GB working)”，即 4GB 显存卡片可在优化参数下运行，另有用户反馈 2GB 可工作；低显存需要配合 --medvram / --lowvram 等牺牲速度的优化，具体表现以显卡型号与模型分辨率为准。
• ControlNet、Tiled VAE、图片浏览器、系统信息基准等 README 标注 “via extension” 的能力属于社区扩展，不是内置功能；扩展安装等价于允许第三方代码在本机执行，官方在远程可访问时默认禁用扩展安装入口（见第 10.13 节）。
• AMD 显卡在 Windows 上未获得官方支持，官方 Wiki 指向第三方 DirectML 分支；Linux AMD 走 ROCm 方案；Intel 集显 / 独显与昇腾 NPU 由外部 Wiki 与第三方仓库承接；这些路径的稳定性与版本兼容性以对应分支文档为准。
• 官方仓库不提供预训练模型、不托管模型权重；SD 1.x / SD 2.x / SDXL 等权重及其许可由模型发布方（Stability AI、CompVis、RunwayML 等）与各模型站规定，使用前必须核对许可与年龄限制条款。

2 功能特性

以下条目整理自官方 README 特性清单、Features Wiki 与当前界面标签页；具体参数名称、默认值与菜单位置以安装版本为准。

2.1 文生图与图生图核心流程

• txt2img：输入正向提示词（Prompt）与负向提示词（Negative prompt），选择采样方法、采样步数、CFG Scale、宽高、批量数量 / 批量大小、随机种子，一键生成并实时预览进度条与缩略图。
• img2img：上传参考图，设置 Denoising strength（去噪强度）后按提示词重绘；标签页内再细分 Sketch、Inpaint、Inpaint sketch、Inpaint upload、Batch 等子标签，覆盖草图涂鸦、蒙版局部重绘、上传蒙版与批量文件处理。
• 扩图（Outpainting）：在原图边界之外延展画面；局部重绘（Inpainting）：在蒙版区域内重新生成内容，支持专用 inpainting 模型；另有 Color Sketch（颜色草图）模式。
• 高清修复（Hires. fix）：先以较低分辨率生成，再按放大倍率与二次步数上采样细化，避免直接高分辨率构图常见的变形与重复肢体问题。
• Loopback：把 img2img 结果作为下一轮输入连续处理多次；Batch Processing：对一组文件批量执行 img2img。

2.2 提示词控制与参数实验

• 注意力权重：用括号提高模型对局部文本的关注度，例如 a man in a ((tuxedo))，或使用替代语法 a man in a (tuxedo:1.21)；在 MacOS 上选中文字后可按 Command+Up / Command+Down，其他系统按 Ctrl+Up / Ctrl+Down 自动调整选中文本权重。
• Composable-Diffusion：多个提示词用大写 AND 组合，支持权重，例如 a cat :1.2 AND a dog AND a penguin :2.2。
• Prompt Matrix：批量组合提示词片段生成对比矩阵；X/Y/Z plot：把不同参数（采样器、步数、CFG、种子、LoRA 权重等）排成二维 / 三维参数网格图，便于横向对比。
• 提示词令牌实时校验：界面实时显示令牌长度计数；README 说明本界面突破原始 Stable Diffusion 75 令牌上限的提示词长度限制。
• 提示词编辑（Prompt Editing）：生成过程中途切换提示词，例如先生成西瓜再切换成动漫女孩；Variations：在保持构图前提下生成微小差异版本；Seed resizing：在相近分辨率下复现同一张图。
• Styles：把常用提示词片段保存为样式，通过下拉框后续一键套用；提示词历史：默认保留上一轮提示词，可在设置中关闭。

2.3 模型与权重管理

• Checkpoint 在线重载：切换主模型无需重启界面；顶部下拉框展示 models/Stable-diffusion 内的 .ckpt / .safetensors 权重。
• Checkpoint Merger：在独立标签页内把最多三个 Checkpoint 按权重比例合并为一个新模型。
• LoRA：LoRA 网络存放在 models/Lora，界面可带预览图选择要附加到提示词的 LoRA；同目录体系下还有 Hypernetwork（models/hypernetworks）与文本反演 embedding（embeddings），三者共用独立的选择 UI。
• 独立 VAE：在设置界面从 VAE 目录中选择与主模型分离的 VAE 权重，修正发灰、偏色等画面问题。
• 模型格式：支持 safetensors 格式加载；生成图像分辨率限制放宽为 8 的倍数（而非 64 的倍数）。

2.4 修复、放大与 Extras 工具链

Extras 标签页集中放置后处理能力：

• 人脸修复：GFPGAN 神经网络修复脸部；CodeFormer 作为 GFPGAN 之外的替代人脸修复工具。
• 超分放大：RealESRGAN、ESRGAN（含大量第三方模型）、SwinIR 与 Swin2SR、LDSR（Latent Diffusion 超分）；另有 BSRGAN、ScuNET、DAT 等模型目录在参数中可指定。
• SD Upscale：基于 Stable Diffusion 的二次放大流程；放大模型按目录扫描，.pth 扩展名即被识别并出现在界面下拉框中（RealESRGAN 与 ESRGAN 模型互不兼容，不可混放）。

2.5 训练与反推工具

• 训练标签页：提供 Hypernetwork 与 embedding（文本反演）训练选项；预处理包含裁剪、镜像，以及使用 BLIP 或 DeepDanbooru 自动打标（动漫提示词场景）。README 注明文本反演可在 8GB 显存上训练，也有 6GB 可用的反馈报告。
• CLIP Interrogator：根据上传图片反推描述提示词；另有 DeepDanbooru 集成，为动漫提示词生成 danbooru 风格标签。
• Tokenizer 标签页：查看提示词令牌化结果；PNG Info 标签页：把生成图拖入即可读取内嵌的生成参数并回填到界面。

2.6 生成参数留存与复现

• 用于生成图片的参数会随图片保存：PNG 写入 PNG chunk，JPEG 写入 EXIF；把图片拖到 PNG Info 标签页即可恢复生成参数并自动复制回界面。
• 支持把图片或文本参数直接拖放到提示词框；参数保存行为可在设置中关闭。
• 批次种子正确记录；进度条显示预计完成时间；可用独立神经网络生成几乎不占用显存与算力的预览图。

2.7 接口、扩展与工程化能力

• API：加 --api 启动后暴露 HTTP 接口，/docs 提供在线接口文档；内置 /sdapi/v1/txt2img、/sdapi/v1/img2img 等端点，响应中 images 为 base64 编码图像列表。
• 自定义脚本与扩展：README 提供 Custom Scripts Wiki 入口；扩展集中在 Extensions 标签页管理，内置扩展索引与社区仓库 stable-diffusion-webui-extensions。
• 安全代码执行：从界面运行任意 Python 代码需要显式加 --allow-code 才启用。
• 性能优化：--xformers 为支持的显卡带来明显提速；另有多种交叉注意力优化（--opt-sdp-attention、--opt-split-attention 等）、显存档位（--medvram、--lowvram）与 CPU 模式，详见第 8 节。
• 其他界面能力：设置页可调整默认值、混合 / 最大 / 步数范围与元素排序；鼠标悬停提示；平铺（Tiling）勾选后生成可作为纹理平铺的图像；随时中断当前生成；支持专用 inpainting 模型、Stable Diffusion 2.0、Alt-Diffusion 与 Segmind SSD-1B 等模型体系。

3 官方界面预览

3.1 txt2img 主界面

开篇图即官方 README 中的主界面截图：顶部为 Stable Diffusion Checkpoint 下拉框与刷新按钮；下方依次为 txt2img、img2img、Extras、PNG Info、Checkpoint Merger、Train、Tokenizer、Settings、Extensions 标签页。左侧为提示词、负向提示词、采样方法、采样步数、人脸修复、平铺、高清修复、宽高、批量数量、批量大小、CFG Scale、种子与脚本；右侧为生成结果画廊、保存 / 打包 / 发送到 img2img / inpaint / extras 的操作按钮，底部展示本次生成参数、耗时、torch 激活 / 保留显存与系统显存占用。

3.2 img2img 与反推界面

下图为官方 Features Wiki 中的 img2img 界面：提示词框右侧提供 Interrogate CLIP 与 Interrogate DeepDanbooru 两个反推按钮；img2img 区域内切换 Sketch、Inpaint、Inpaint sketch、Inpaint upload、Batch 子标签；底图可通过 “Copy image to” 发送到 img2img、sketch、inpaint、inpaint sketch；底部参数区展示步数、采样器、CFG、种子、尺寸、去噪强度与 Mask blur。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• Python：Windows 自动安装路径要求安装 Python 3.10.6（64 位），安装时勾选 “Add Python to PATH”；README 明确提示 “Newer version of Python does not support torch”，不建议自行更换其他版本。Linux Debian 系系统包为 python3 + python3-venv；README 说明系统过新时需要安装 python3.11 或 python3.10，并在启动脚本中通过 python_cmd 指定。
• Git：Windows 安装 git for Windows；Linux 包管理器安装 `git`；即便选择 ZIP 下载源码，Wiki Dependencies 仍要求本机具备 git。
• Linux 系统库（Debian 系）：

sudo apt install wget git python3 python3-venv libgl1 libglib2.0-0

Red Hat 系：sudo dnf install wget git python3 gperftools-libs libglvnd-glx；openSUSE：sudo zypper install wget git python3 libtcmalloc4 libglvnd；Arch：sudo pacman -S wget git python3（命令来自官方 README Installation 小节）。

• macOS（Apple Silicon）：先安装 Homebrew，再执行 brew install cmake protobuf rust python@3.10 git wget（命令来自官方 Apple Silicon Wiki）。
• 显卡驱动：NVIDIA 方案需安装与 PyTorch CUDA 版本匹配的显卡驱动；Linux AMD 方案需 ROCm 支持；CPU 模式无需显卡驱动，但速度显著变慢。
• 模型权重：首次启动若未放入模型，界面会按默认流程处理 SD 1.5 基础模型下载；也可以提前把合规获取的 .ckpt / .safetensors 放入 models/Stable-diffusion，跳过自动下载（详见 7.4 节）。
• 官方未提供 Docker 镜像：仓库内没有官方 Dockerfile 与 docker-compose.yml，本文第 6 节不编写 Compose 部署路径；社区第三方镜像不属于官方分发，使用前须自行核验其来源与完整性。

5.2 硬件与系统建议

5.3 端口与目录分配

注意：把 --listen 或 --share 后的界面暴露到局域网 / 公网时，应同时使用 --gradio-auth 配置账号密码，或在反向代理层加鉴权；未鉴权的暴露界面等价于把本机出图能力开放给任意访问者。

6 方式一：官方一键安装包与启动脚本（推荐日常使用）

官方没有提供 Docker 一键部署，日常使用首选官方发布包与平台一键脚本：脚本首次运行时自动创建虚拟环境、安装依赖、拉取配套仓库并启动 Gradio 服务。

6.1 Windows：发布包一键安装（NVIDIA）

1. 前往 Release · v1.0.0-pre 下载 sd.webui.zip（README Installation and Running 小节指定的包），解压到目标目录。
2. 进入解压目录，双击运行 update.bat，等待脚本把 WebUI 更新到最新版本，完成后关闭窗口。
3. 双击 run.bat 启动；首次启动会下载大量依赖与模型文件，保持网络通畅。
4. 日志出现 Running on local URL: http://127.0.0.1:7860 后，在浏览器打开该地址即可进入界面。

50 系（Blackwell）显卡当前需要 PyTorch 2.7，官方 Wiki 提示使用包内的 switch-branch-toole.bat 切换到 dev 分支，相关讨论见 Wiki 安装小节引用的 GitHub Discussion；分支与驱动组合以最新 Wiki 为准。

如需调整启动参数，编辑 sd.webui\webui\webui-user.bat，在 set COMMANDLINE_ARGS= 后追加参数，例如：

set COMMANDLINE_ARGS=--autolaunch --update-check

多个参数以空格分隔；上面示例分别为启动后自动打开浏览器、启动时检查新版本。

6.2 Windows：Python + Git 自动安装（源码目录）

1. 安装 Python 3.10.6，勾选 “Add Python to PATH”；安装 Git。
2. 打开命令行克隆仓库：

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

3. 进入仓库目录，按 Wiki 安装小节说明在 webui-user.bat 中补充稳定仓库指向（当前 master 相关修复以 Discussion 17212 与 Wiki 最新说明为准）：

set STABLE_DIFFUSION_REPO=https://github.com/w-e-w/stablediffusion.git

4. 在 Windows 资源管理器中以普通用户身份（不要以管理员身份）双击运行 webui-user.bat；脚本自动创建 venv 虚拟环境、安装依赖并启动界面。

6.3 Linux：webui.sh 一键脚本

Debian 系先安装系统依赖：

sudo apt install wget git python3 python3-venv libgl1 libglib2.0-0

然后任选其一：

# 方式 A：直接下载官方启动脚本到目标目录
wget -q https://raw.githubusercontent.com/AUTOMATIC1111/stable-diffusion-webui/master/webui.sh
chmod +x webui.sh
./webui.sh

# 方式 B：克隆整个仓库（便于后续 git pull 更新，官方推荐方式）
git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui
cd stable-diffusion-webui
./webui.sh

启动前可编辑 webui-user.sh 调整变量（见第 8.1 节）。系统 Python 过新、默认没有 3.10 时，README 给出的处理方式是安装 python3.11 / python3.10 后在脚本中指定：

# Ubuntu 24.04
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11

# 在 webui-user.sh 中指定
python_cmd="python3.11"

Arch / Manjaro 对应 yay -S python311（注意与 python3.11 包区分）。

6.4 Apple Silicon 一键安装

1. 安装 Homebrew 后在新终端执行：

brew install cmake protobuf rust python@3.10 git wget

2. 克隆仓库并进入目录：

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

3. 把要使用的 Stable Diffusion 模型 / Checkpoint 放入 stable-diffusion-webui/models/Stable-diffusion；没有模型时可从 Hugging Face 模型卡下载 .ckpt / .safetensors（见 7.4 节）。
4. 执行 ./webui.sh；脚本自动创建并激活 venv、补装缺失依赖后启动界面。后续再次运行直接执行 ./webui.sh；该脚本不会自动更新 WebUI，更新前先执行 git pull。

6.5 局域网访问、临时公网链接与 API

局域网访问：在 COMMANDLINE_ARGS 中加入 --listen，服务将监听 0.0.0.0，同网段其他机器通过 http://<本机内网 IP>:7860 访问，例如 http://192.168.1.3:7860。

Gradio 临时公网链接：加入 --share，启动后会输出一个 xxx.app.gradio 形式的临时公网地址（Wiki 说明这是 Colab 等场景的预期用法）；可配合 --gradio-auth username:password 设置界面账号密码，多组账号用逗号分隔：

set COMMANDLINE_ARGS=--listen --port 7860 --gradio-auth <用户名>:<密码>

export COMMANDLINE_ARGS="--listen --port 7860 --gradio-auth <用户名>:<密码>"

开启 API：追加 --api，访问 http://127.0.0.1:7860/docs 查看在线接口文档；需要接口鉴权使用 --api-auth，记录全部 API 请求使用 --api-log，允许通过 API 停止 / 重启 / 终止服务使用 --api-server-stop。

凭据只写在本机启动脚本或反向代理配置中，不要提交到公开仓库，也不要写入文章、截图与分享链接。

7 方式二：源码克隆与本地开发运行

适合需要二次修改界面、调试扩展、跟踪 master 最新提交，或在无桌面环境的 Linux 服务器上手动部署的场景。

7.1 克隆仓库

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

Windows 上在目标文件夹右键选择 “Git Bash here” 后执行同样的克隆命令；选择 ZIP 下载替代方案时仍需安装 Git，且更新只能重新下载 ZIP 覆盖文件，不如 git pull 方便（口径来自 Dependencies Wiki）。

7.2 手动创建虚拟环境与安装依赖

以 Linux / macOS 为例：

# 1. 创建虚拟环境（脚本默认 venv 目录为仓库下 venv）
python3.10 -m venv venv
source venv/bin/activate

# 2. 升级 pip 与 wheel
python -m pip install --upgrade pip wheel

# 3. 安装依赖（官方依赖清单：requirements_versions.txt 为固定版本，requirements.txt 为宽松版本）
#    启动脚本会根据硬件选择 torch 安装命令；手动环境下请先按 PyTorch 官方渠道安装匹配 CUDA / ROCm / CPU 版本的 torch 与 torchvision
pip install -r requirements_versions.txt

Windows 手动环境激活路径为 venv\Scripts\activate；torch 版本必须与显卡 CUDA 驱动匹配，建议先到 PyTorch 官网选择对应组合复制安装命令，再安装 WebUI 其余依赖。

7.3 手动启动 launch.py

官方启动脚本 webui.sh / webui.bat 最终调用的入口是 launch.py（LAUNCH_SCRIPT 默认值）。虚拟环境激活后可直接启动：

# 本机默认启动
python launch.py

# 指定端口、开启 API、自动打开浏览器
python launch.py --port 7860 --api --autolaunch

# 低显存档位
python launch.py --medvram --xformers

# CPU 模式（无显卡调试用）
python launch.py --use-cpu all --precision full --no-half --skip-torch-cuda-test

Windows 下对应在 venv\Scripts\ 激活后执行 python launch.py ...；也可以在 webui-user.bat 的 COMMANDLINE_ARGS 中写好参数再调用脚本，效果一致。

7.4 放入模型权重

1. 主模型（Checkpoint）放入 models/Stable-diffusion/，支持 .ckpt 与 .safetensors；界面顶部下拉框刷新后即可选择。
2. LoRA 放入 models/Lora/；Hypernetwork 放入 models/hypernetworks/；文本反演 embedding 放入 embeddings/；自定义 VAE 放入 models/VAE/（目录首次运行前可能不存在，可手动创建）。
3. 基础模型可从 Hugging Face 模型卡下载，例如 SD 1.5：v1-5-pruned-emaonly.safetensors；SD 2.0 / 2.1 还需要配套配置 .yaml 并与模型同名放在同一目录（方法见 Apple Silicon Wiki Downloading Stable Diffusion Models 小节）。
4. 跳过默认模型自动下载可在启动参数中加入 --no-download-sd-model；不需要随 checkpoint 附带的 CLIP 时可加 --do-not-download-clip。

7.5 开发者补充说明

• 配套源码仓库由启动脚本自动克隆到 repositories/ 目录，例如 Stable Diffusion 主干、k-diffusion、BLIP、generative-models（SDXL 依赖）等；首次启动失败并提示找不到仓库时，优先排查 Git 网络与 repositories/ 目录完整性（见 10.2 节）。
• 二次开发请先阅读 Wiki Contributing 说明；扩展开发参考 Wiki Developing extensions。
• 启动参数 --tests 可运行功能自测；--dump-sysinfo 把有限系统信息写入磁盘后退出，便于在 Issue 中附上环境信息；--disable-all-extensions 与 --disable-extra-extensions 用于排障时临时关闭扩展。

8 配置项说明

8.1 启动脚本用户变量

webui-user.bat（Windows）与 webui-user.sh（Linux / macOS）是官方预留的个性化配置位，脚本其余部分不要改动。

8.2 常用命令行参数

完整表见 Wiki · Command-Line Arguments and Settings，下表按用途分组摘录高频参数与默认值。

8.2.1 网络、端口与鉴权

8.2.2 模型与目录

8.2.3 性能、显存与精度

8.2.4 功能、调试与其他

8.3 界面设置文件

• config.json：界面运行设置，保存采样器默认值、默认尺寸、保存行为、扩展参数等；首次启动后生成，可在 Settings 页修改。
• ui-config.json：界面元素默认值、最小值、最大值、步数与布局顺序；README 提到可通过文本配置修改 UI 元素默认值与混合 / 最大 / 步数范围。
• styles.csv：Styles 下拉框保存的提示词片段；可在文本编辑器中批量维护。
• 设置保存项：Settings → Saving images 中可配置 samples_save（始终保存生成图）、samples_format（默认 png）、samples_filename_pattern、grid_save、grid_format、save_images_before_face_restoration、save_images_before_highres_fix、save_mask 等；默认输出位置在 outputs/ 对应子目录。

8.4 环境变量补充

启动脚本读取的环境变量与 webui-user.sh 中可导出的配置一一对应：

不要把模型站点 Token、账号密码、鉴权口令写进 config.json、styles.csv 或公开分享的启动脚本；API 鉴权信息应通过本机脚本或代理层注入。

9 常用运维命令

以下命令按日常使用场景整理；Windows 对应操作在资源管理器双击批处理或在 venv\Scripts 激活后的命令行中执行。

9.1 启动、停止与重启

# Linux / macOS：启动（首次自动建 venv、装依赖）
./webui.sh

# 带参数启动
./webui.sh --listen --port 7860 --api --autolaunch --xformers

# 直接入口（已激活 venv）
python launch.py --port 7860 --api

REM Windows：启动
webui-user.bat

REM 手动停止：在运行窗口按 Ctrl+C，或关闭命令行窗口

• 重启：关闭当前窗口后重新执行 webui-user.bat / ./webui.sh；修改模型目录、更换启动参数后需要重启生效。
• 加 --api-server-stop 后可通过 API 触发服务停止 / 重启 / 终止（接口路径以 /docs 在线文档为准）。

9.2 更新 WebUI 与扩展

# 源码目录更新（官方推荐 git 安装方式）
git pull

# 启动时自动检查新版本
./webui.sh --update-check

# 启动时更新全部已安装扩展
./webui.sh --update-all-extensions

Windows 发布包方式双击 update.bat 更新；扩展在 Extensions 标签页的 Installed 子标签中勾选对应条目后点击 Apply and restart，或在 Available 子标签浏览官方扩展索引。

9.3 查看日志与环境信息

# 详细启动日志
./webui.sh --log-startup

# 调试日志级别
./webui.sh --loglevel DEBUG

# 写出有限系统信息（不含扩展与选项信息）后退出
python launch.py --dump-sysinfo

运行日志直接输出在启动窗口；Windows 可把窗口输出保存为文本后附到 Issue；排查显卡问题时可配合社区扩展 sd-extension-system-info 收集基准与环境信息（见 NVIDIA Wiki 优化小节引用）。

9.4 备份与恢复

建议定期备份以下路径与文件：

# Linux 下打包配置与样式（不含大模型与图片）
tar -czf webui-config-backup.tar.gz \
  config.json ui-config.json styles.csv \
  webui-user.sh extensions/

恢复时把备份文件放回对应目录即可；模型目录通过 --models-dir 或 --ckpt-dir 等参数指向备份位置也可以不复制进仓库。

9.5 状态检查与排障辅助

# 临时关闭全部扩展，定位是否由扩展引起异常
python launch.py --disable-all-extensions

# 仅关闭非内置扩展
python launch.py --disable-extra-extensions

# 跳过安装步骤直接启动（依赖已就绪时）
python launch.py --skip-install

# 查看当前 commit 与界面页脚版本信息
git rev-parse --short HEAD

10 常见故障排查

以下问题整理自官方 Troubleshooting Wiki、NVIDIA / AMD / Apple 安装 Wiki 与命令行参数 Wiki；排查时先复现最小场景（默认参数、关闭扩展、单张图片），再逐项加回变量定位。

10.1 Python 版本不匹配

• 现象：安装阶段报 torch 安装失败、NameError: name 'xformers' is not defined、依赖版本冲突。
• 口径：官方测试通过的是 Python 3.10.6；Troubleshooting Wiki 明确提示 “Don't use other versions unless you are looking for trouble”。
• 处理：确认 python --version 输出为 3.10.x；多版本共存时在 webui-user.bat 写 set PYTHON=B:\soft\Python310\python.exe，在 webui-user.sh 写 python_cmd="python3.10"。requirements_versions.txt 与当前 Python 不匹配时，可临时改 set REQS_FILE=requirements.txt 尝试（Wiki Troubleshooting 口径），但优先修正 Python 版本。

10.2 “Couldn't clone Stable Diffusion” 或提示输入 GitHub 用户名

• 原因：Git 未安装、repositories/ 目录不完整，或访问 GitHub 网络受限。
• 处理：确认 git --version 可用；删除 repositories/ 与 venv/ 目录后重新执行启动脚本让其重新克隆；检查代理 / 网络对 github.com 与 raw 文件地址的可达性；不要以 root 身份在 Windows 普通安装目录下反复重建环境。

10.3 双击 webui-user.bat 后窗口立即关闭

• 处理：先在命令行中进入目录执行 webui-user.bat，让错误信息停留在窗口内；常见原因为 Python 未加入 PATH、Python 版本不符、venv 创建失败。按 10.1 节修正 Python 路径后重试。

10.4 低显存 OOM 报错

• 现象：启动后生成图片时报显存不足（CUDA out of memory）。
• 处理（参数顺序来自 Troubleshooting Wiki Low VRAM 小节）：
  • 4GB 显存、想生成约 1.3 倍大图：加 --medvram。
  • --medvram 仍 OOM：改用 --lowvram --always-batch-cond-uncond。
  • 需要比 --medvram 更大的图：使用 --lowvram。
  • 加载全量权重时 OOM：加 --disable-model-loading-ram-optimization（v1.6.0 加入）。
  • 大图可结合社区 Tiled VAE 扩展分块编码 VAE，降低显存峰值（见扩展 Wiki MultiDiffusion with Tiled VAE）。
  • 降低分辨率、批量数量、批量大小，先以 512×512 单张验证流程。

10.5 “Torch is not able to use GPU” / CUDA 检测失败

• 原因：WebUI 默认检测 CUDA，仅 NVIDIA 提供官方 CUDA 支持；AMD、Mac、Intel、NPU 场景该检测失败属于预期。
• 处理：非 NVIDIA 环境在 COMMANDLINE_ARGS 中加入 --skip-torch-cuda-test，再按对应平台 Wiki 启动；NVIDIA 环境则检查显卡驱动版本、torch CUDA 版本是否匹配，必要时用 --reinstall-torch 重装匹配版本（升级后移除该参数）。

10.6 生成黑图、绿图或 VAE NaN

• 黑 / 绿图：部分显卡不支持半精度。先尝试 --upcast-sampling（与 --xformers 叠加使用）；仍未修复再使用 --precision full --no-half，该组合显存占用明显增加，可能需要同时加 --medvram（NVIDIA Wiki Troubleshooting 口径）。
• NansException: A tensor with all NaNs was produced in VAE：模型与 VAE 组合容易触发，尝试 --no-half-vae 缓解。
• AMD Linux：不能正常跑 fp16 的显卡可使用 --upcast-sampling --opt-sub-quad-attention / --opt-split-attention-v1；仍失败时按显卡型号配置 export HSA_OVERRIDE_GFX_VERSION=...，具体数值需对照 Wiki 与 GitHub Issues 检索。

10.7 xformers 报 “no kernel image is available” 或未定义

• 现象：启用 --xformers 后报 CUDA kernel 不可用，或提示 NameError: name 'xformers' is not defined。
• 处理：Windows + Python 3.10 + Pascal 及以上显卡时，临时在参数中加入 --reinstall-xformers --xformers 重装匹配版本；升级完成后删除 --reinstall-xformers，避免每次启动重复安装。NameError: name 'xformers' is not defined 多为 Python 版本过旧，回到 10.1 节处理。

10.8 端口被占用

• 现象：启动日志提示端口 7860 已被占用，或界面打不开。
• 处理：用 --port <其他端口> 指定 1024 以上的新端口；确认占用进程是残留的上一次 WebUI 实例，先关闭旧窗口或结束对应 Python 进程再启动。

10.9 模型 / 依赖下载失败

• 现象：首次启动卡在下载 SD 模型、CLIP 或配套仓库；输出图目录缺模型。
• 处理：提前把合规获取的模型放入 models/Stable-diffusion 后加 --no-download-sd-model 启动；检查本机网络、代理与 Hugging Face 连通性；repositories/ 克隆失败时按 10.2 节重建。模型站下载的权重务必核对来源与 SHA / 文件大小，避免加载被篡改的 .ckpt。

10.10 权限与目录问题

• 不要在 Linux 上以 root 身份长期运行图形界面环境；Troubleshooting Wiki 专门列出 “Launching as root” 注意事项，普通用户目录下创建仓库与 venv 即可。
• 模型、输出与扩展目录所在磁盘需要可写权限；把模型放到其他盘符时，用 --models-dir、--ckpt-dir、--lora-dir 等参数指向，而不是移动脚本目录。
• Windows 路径与文件名含中文 / 空格时，注意引号与批处理转义；默认文件名最大长度 --filenames-max-length 为 128，超长会被截断。

10.11 反向代理、CORS 与子路径

• 经 Nginx / Caddy 等反向代理对外提供服务时，使用 --subpath 配置与代理一致的子路径；跨域前端调用接口时用 --cors-allow-origins 显式列出允许来源（逗号分隔、不加空格），复杂匹配用 --cors-allow-origins-regex。
• 完整启用 TLS 需要同时提供 --tls-keyfile 与 --tls-certfile；生产环境建议由反向代理统一终结 HTTPS，后端保持 HTTP。
• 公网暴露必须叠加鉴权：--gradio-auth / --api-auth 或代理层登录校验；不要在无认证情况下把界面挂到公网。

10.12 AMD 与 macOS 专属问题

• Windows AMD：官方未提供支持，Wiki 指向 lshqqytiger 的 DirectML 分支；训练在该分支当前不可用，LoRA、ControlNet 等部分功能可用，问题反馈到分支仓库 Issues。4–6GB 显存可尝试 --opt-sub-quad-attention --lowvram --disable-nan-check。
• Linux AMD：./webui.sh 会自动安装 PyTorch ROCm 版本；很多 AMD 卡必须加 --precision full --no-half 或 --upcast-sampling 才能避免 NaN 或崩溃；--upcast-sampling 生效时相对全精度有接近 2 倍速度。
• macOS Apple Silicon：CLIP 反推默认走 CPU，速度慢；训练可用但极慢且占用大量内存，属于官方已知限制。性能差时先尝试 --opt-split-attention-v1；仍不理想再按 Apple Silicon Wiki 其余建议排查。启动异常可删除 repositories 与 venv 目录，git pull 后重新 ./webui.sh。

10.13 远程访问下扩展安装被禁用

• 现象：使用 --share 或 --listen 后，Extensions 标签页安装入口报错 extension access disabled because of command line flags。
• 原因：安装扩展等价于允许任意代码执行，属于显著安全风险，官方默认在界面可被其他计算机访问时关闭该能力（扩展 Wiki Security 小节）。
• 处理：确有远程安装需求时，临时加 --enable-insecure-extension-access；官方强烈建议日常使用不要开启，用完立即移除该参数。扩展来源优先选择官方扩展索引与高星社区仓库，安装前阅读其源码与更新状态。

11 风险与合规说明

以下条款整理自官方 LICENSE.txt、README、Wiki 安全说明与通用合规口径；如与官方原文不一致，以仓库 LICENSE.txt、README 与 项目 Wiki 最新版本为准。

11.1 开源协议（AGPL-3.0）

WebUI 源码采用 GNU Affero General Public License v3.0（LICENSE.txt，Copyright © 2023 AUTOMATIC1111）。AGPL v3 属于强 copyleft 许可证：

• 允许自由使用、研究、修改与再分发；分发修改版本时必须以相同许可证开源，并保留版权声明与许可证副本。
• 网络分发义务：通过网络向用户提供服务（SaaS / 自托管对外界面）也属于触发 AGPL 披露义务的场景；把 WebUI 修改后嵌入自有产品或对外提供服务前，应咨询法务确认开源义务。
• 仓库中借用的第三方代码许可可在界面 Settings → Licenses 与 html/licenses.html 中查看；k-diffusion、GFPGAN、CodeFormer、ESRGAN、SwinIR、MiDaS、xformers、DeepDanbooru、LyCORIS 等组件各自遵循其原始许可。

11.2 模型权重与第三方素材许可

• WebUI 仓库不附带模型权重；Stable Diffusion 1.4 / 1.5 由 CompVis、RunwayML 等基于 Stability AI 模型发布，使用其权重需先接受对应模型卡（如 CreativeML Open RAIL-M）的使用条款，部分条款包含禁止用途与年龄限制。
• SD 2.x、SDXL、社区微调大模型、LoRA、embedding、超分与人脸修复模型来自不同发布方，许可各异：有的仅允许非商用，有的要求署名，有的禁止在特定平台上传训练；下载时必须阅读模型卡 / 模型站说明，不要默认 “能下载即可商用”。
• 用他人照片、插画、角色形象训练或生成的内容，涉及肖像权、著作权与商标权；公开发布、商用或参赛前应取得授权或确认素材处于可训练许可范围。

11.3 生成内容版权与平台风控

• 各司法辖区对 AI 生成图像的可版权性规定不同；WebUI 不保证生成内容可注册版权、不保证内容原创，也不替代人工审核。
• 商业使用生成图前，核对所使用模型 / LoRA 的许可、训练素材来源与目标市场法规；在电商、广告、出版、社交平台发布时，遵守平台关于 AI 生成内容标注、审核与限流的规则。
• 提示词与生成结果不会自动上传云端（本机模式下），但启用 --share、API 远程调用或接入第三方扩展后，数据流向由对应服务与扩展决定。

11.4 扩展与代码执行安全

• 社区扩展可以读取本机文件、访问网络、执行 Python 代码，能力等价于在本机安装第三方软件；只从可信来源安装，定期在 Extensions 标签页更新，不用的扩展及时移除。
• --allow-code 允许界面执行任意 Python 代码，--disable-safe-unpickle 关闭 PyTorch 反序列化恶意代码检查；两者都会降低本机安全水位，仅在明确需要时临时启用。
• 来历不明的模型文件、脚本与扩展可能包含恶意代码；加载前核对发布者、下载量、模型卡与社区评价，不要把公网可访问界面交给不可信访客使用。

11.5 数据隐私

• 默认本机运行模式下，提示词、参考图与生成图保存在本机磁盘；outputs/ 中的图片内嵌生成参数（PNG chunk / JPEG EXIF），公开发布前如需去掉参数信息，使用第三方工具剥离元数据或使用专门导出选项。
• 使用 --share、ngrok、第三方 Colab 镜像或云端部署时，提示词、参考图会离开本机网络；敏感人物照片、未公开产品图与商业素材不要通过此类渠道生成。
• API 鉴权凭据、代理口令、模型站 Token 只保存在本机脚本与环境变量中，不要写入公开仓库、截图、文档或聊天记录。

11.6 免责声明

项目按现状（AS-IS）提供，官方不保证在特定硬件、系统版本、模型组合下持续可用，不保证生成结果正确、合规或无侵权风险；使用者自行承担出图质量、模型许可、内容版权、数据泄露与业务损失风险。如认为仓库内特定文件侵犯合法权益，请通过 GitHub Issues 提交说明，不要在公开 Issue 中上传账号凭据、模型 Token、未公开图片或敏感配置。