部署前先明确 ControlNet 的运行方式

ControlNet 常作为 AI 绘画工作流中的控制插件使用，典型场景是配合 Stable Diffusion WebUI，在生成图像时加入姿态、边缘、深度、线稿、分割图等条件控制，让出图结果更稳定、更可控。把它部署到 Linux 服务器上，适合团队共用算力、远程批量出图、长期运行推理服务，或者将绘图能力接入内部业务系统。

部署思路并不复杂：先准备 Linux 基础环境和显卡运行条件，再安装 WebUI 主程序，随后安装 ControlNet 插件，下载对应模型文件，最后配置后台运行和访问方式。真正容易出问题的地方通常不在插件本身，而在显卡驱动、CUDA、Python 版本、依赖冲突、模型路径和端口暴露上。

一、服务器与系统环境准备

建议使用 Ubuntu 20.04 或 22.04，也可以选择 Debian、CentOS Stream 等发行版，但教程生态和依赖兼容性以 Ubuntu 更友好。硬件方面，ControlNet 会显著增加显存占用，最低建议 8GB 显存，若要同时使用大尺寸图像、多 ControlNet 单元或高分辨率修复，建议 12GB 到 24GB 显存更稳妥。系统内存建议 16GB 起步，磁盘空间至少预留 80GB，因为 WebUI、模型、ControlNet 模型和缓存文件会持续增长。

首先更新系统软件包：sudo apt update && sudo apt upgrade -y。随后安装常用工具：sudo apt install -y git wget curl python3 python3-venv python3-pip build-essential。Python 版本建议使用 3.10，过高版本可能导致部分依赖不兼容。若系统默认 Python 不是 3.10，可以单独安装并在创建虚拟环境时指定。

如果使用 NVIDIA 显卡，需要提前安装正确驱动。可通过 nvidia-smi 检查驱动是否可用；如果命令能显示显卡型号、驱动版本和显存占用，说明基础驱动正常。CUDA 工具包不一定必须手动完整安装，因为 PyTorch 通常会自带匹配运行库，但驱动版本必须足够新。驱动过旧会出现无法调用 GPU、推理速度极慢或程序启动报错等问题。

二、安装 Stable Diffusion WebUI 主环境

选择一个固定目录存放项目，例如 /opt/ai 或当前用户目录下的 apps。为了减少权限问题，建议不要直接使用 root 长期运行服务。可以创建普通用户并赋予项目目录写入权限。进入目录后执行：git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui.git，然后进入 stable-diffusion-webui 目录。

首次启动可执行：./webui.sh。脚本会自动创建虚拟环境、安装 PyTorch 和依赖包。这个过程取决于网络环境和服务器性能，可能需要较长时间。启动成功后，终端会显示本地访问地址，默认端口通常为 7860。服务器部署时，如果需要局域网访问，可添加参数 --listen；如需指定端口，可添加 --port 7860。

常用启动命令示例为：./webui.sh --listen --port 7860 --xformers。xformers 可降低显存占用并提升部分场景的速度，但不是所有显卡和环境都能稳定使用；如果启动报错，可以先去掉该参数，保证基础功能可用后再优化。

三、安装 ControlNet 插件

ControlNet 插件一般安装在 WebUI 的 extensions 目录下。进入项目目录后执行：cd extensions，然后运行：git clone https://github.com/Mikubill/sd-webui-controlnet.git。克隆完成后回到 WebUI 根目录，重启 WebUI。进入页面后，在功能区域中看到 ControlNet 相关面板，说明插件已经加载成功。

如果页面没有显示插件，优先检查三个位置：第一，extensions/sd-webui-controlnet 目录是否存在；第二，启动日志中是否有依赖安装失败、Python 包冲突或插件加载失败提示；第三，WebUI 是否真的重启，而不是仍在运行旧进程。很多新手只刷新页面，没有重启服务，导致插件无法生效。

插件安装后还需要模型文件。ControlNet 的模型类型很多，例如 canny、openpose、depth、lineart、scribble、softedge、tile 等，不同模型对应不同控制能力。下载后的模型通常放到 stable-diffusion-webui/extensions/sd-webui-controlnet/models 目录，也可以在插件设置中指定其他模型目录。模型文件后缀常见为 .safetensors 或 .pth，优先选择来源可靠、说明完整的文件。

四、模型与路径配置要点

ControlNet 插件能否正常工作，很大程度取决于模型路径和预处理器是否匹配。例如使用边缘检测控制时，需要选择 canny 预处理器，并配套 canny 模型；使用人物姿态控制时，需要选择 openpose 预处理器，并配套姿态相关模型。预处理器负责从输入图中提取控制信息，模型负责根据这些控制信息约束生成结果，二者不匹配时，轻则效果差，重则直接报错。

建议按用途建立清晰命名，例如 control_v11p_sd15_canny.safetensors、control_v11p_sd15_openpose.safetensors。若使用 SDXL 模型，则应选择与 SDXL 适配的 ControlNet 模型，不要随意混用 SD1.5 版本模型。混用可能不会立刻崩溃，但生成质量往往不稳定，显存占用也可能异常。

在 WebUI 设置中可以调整 ControlNet 的最大模型数量、缓存策略和允许同时使用的单元数。服务器显存较小的情况下，不建议一次启用多个控制单元。可以先从单个 ControlNet 开始测试，确认显存余量和出图速度，再逐步增加复杂度。

五、后台运行的两种常用方式

临时调试可使用 tmux。安装命令为 sudo apt install -y tmux，创建会话：tmux new -s webui，进入项目目录后执行启动命令。按 Ctrl+b 再按 d 可将会话挂起到后台，之后用 tmux attach -t webui 重新进入。tmux 适合测试和人工维护，优点是简单直观，缺点是服务器重启后不会自动恢复。

长期运行更推荐 systemd。可创建服务文件，例如 /etc/systemd/system/sd-webui.service。服务内容需要包含运行用户、项目目录和启动命令，核心思路是让系统托管进程。配置完成后执行 sudo systemctl daemon-reload，然后 sudo systemctl enable sd-webui，再执行 sudo systemctl start sd-webui。查看状态可用 sudo systemctl status sd-webui，查看日志可用 journalctl -u sd-webui -f。

systemd 方式的关键是不要把工作目录、用户和启动命令写错。如果 WebUI 项目位于 /home/aiuser/stable-diffusion-webui，服务中的 WorkingDirectory 就必须指向该路径，User 也应为拥有读写权限的用户。启动命令可写为 /bin/bash webui.sh --listen --port 7860 --xformers；若 xformers 不稳定，应先移除。

六、远程访问与安全边界

服务器部署经常需要远程访问页面，但不建议把 WebUI 无保护地暴露到公网。AI 绘画服务会消耗大量 GPU 资源，一旦被陌生访问者滥用，可能导致显存占满、服务不可用、磁盘被大量图片写满。更稳妥的方式是在内网使用，或通过带认证的反向袋里、访问白名单、堡垒机等方式限制访问范围。

如果确实需要开放端口，应至少设置 WebUI 的用户名和密码参数，例如 --gradio-auth user:password，并避免使用弱密码。还应限制上传目录和输出目录权限，定期清理 outputs、extensions 缓存和临时文件。不要在公共页面启用不明脚本，不要安装来源不清的插件，不要把服务器密钥、业务配置文件放在 WebUI 可访问目录中。

ControlNet 常用于图像生成和图像参考控制，使用时应遵守素材授权和平台规则。上传他人图片、商用素材或内部资料前，要确认使用权限和数据合规要求。服务器日志、输入图片和输出图片都可能保留痕迹，团队环境中应建立清理策略和访问规范。

七、常见问题排查

问题一：启动时提示找不到 GPU。先运行 nvidia-smi，若不可用，说明显卡驱动层面存在问题；若可用，再检查 PyTorch 是否安装了 GPU 版本。可进入虚拟环境后测试 torch.cuda.is_a vailable()。如果返回 False，通常需要重新安装匹配版本的 PyTorch。

问题二：ControlNet 面板出现但模型列表为空。检查模型是否放在 extensions/sd-webui-controlnet/models 目录下，文件后缀是否正确，文件是否下载完整。也可以在 WebUI 页面点击刷新模型列表，或重启服务后再查看。

问题三：一用 ControlNet 就显存不足。可以降低分辨率、减少 batch size、关闭多余 ControlNet 单元、启用低显存参数，例如 --medvram。必要时更换更小的基础模型，或减少高分辨率修复倍率。不要盲目堆叠多个控制模型。

问题四：预处理器报错或加载很慢。通常与依赖缺失、模型首次下载、CPU 性能不足有关。可查看启动日志，确认 opencv、annotator 相关依赖是否安装成功。首次运行某些预处理器会生成缓存，后续速度通常会改善。

问题五：systemd 启动失败但手动启动正常。重点检查服务运行用户是否拥有项目目录权限，环境变量是否缺失，启动命令是否依赖交互式 shell。可通过 journalctl -u sd-webui -n 100 查看最近日志，按报错逐项处理。

八、实用优化建议

完成基础部署后，建议先建立一套标准测试流程：固定基础模型、固定提示词、固定输入控制图，分别测试 canny、depth、openpose 等常用能力，记录显存占用、生成耗时和稳定性。这样后续升级插件或更换模型时，可以快速判断是否出现退化。

生产使用中不要频繁在线更新所有插件。更稳妥的做法是先备份项目目录中的配置文件、启动参数和关键模型清单，再选择维护窗口升级。升级后若出现异常，可回退到旧版本提交。Git 项目可通过 git log 查看历史，通过 git checkout 指定版本，但回退前要确认扩展和依赖是否同步兼容。

最后，建议将模型文件、输出文件和程序目录分开管理。程序目录用于 WebUI 与插件，模型目录用于统一存放大文件，输出目录定期归档或清理。这样既便于迁移，也能避免磁盘写满导致服务异常。只要环境、模型、后台服务和访问控制四个环节处理妥当，ControlNet 在 Linux 服务器上的长期运行会非常稳定。