SwarmUI 保姆级部署教程：模块化 AI 图像生成 Web UI，从 Windows 一键安装到 Linux 服务器部署

SwarmUI（原名 StableSwarmUI）是一个模块化的 AI 图像生成 Web 用户界面，当前版本 v0.9.8 Beta。它的定位是"全功能一站式 AI 图像生成工具"——支持 Stable Diffusion、Flux、Krea 2 等主流图像模型，还支持 MiniMax H3、Wan、LTX-2 等视频模型，以及 ACE-Step 等音频模型。和站点此前写过的 ComfyUI、SD WebUI 相比，SwarmUI 的特色是"powertools 易于上手"：新手有 Generate 标签页，高级用户有 Comfy Workflow 标签页，同时支持多 GPU 集群协同生成（"Swarm"这个名字就是从"一群 GPU 同时干活"来的）。本文按官方 README，从 Windows 一键安装、Linux 源码部署、macOS M 系列安装到 Docker 部署全流程讲清楚。

一、项目介绍与适用场景

SwarmUI 由 mcmonkey（Alex Goodwin）开发维护，MIT 协议发布。它不是一个"生成模型"，而是一个"前端界面"——底层调用 ComfyUI 作为推理后端，上面套了一层自己的 Web UI。它的核心价值是把 ComfyUI 的强大能力包装成更易用的界面，同时保留了 Comfy Workflow 的完整灵活性。

适用场景：

• AI 绘画爱好者：在浏览器里用 SD/Flux 生成图片，不需要懂 ComfyUI 的节点；
• 多 GPU 集群用户：SwarmUI 的"Swarm"特性就是把多台机器的 GPU 组成一个集群，一起跑大图批量生成；
• 视频/音频生成：除了图像，还支持 Wan、LTX-2 视频模型和 ACE-Step 音频模型；
• 企业内部部署：Docker 方式一键部署成团队共享的生成服务；
• 研究/二次开发：基于 SwarmUI 扩展 API 构建自定义生成流水线。

与 ComfyUI 的区别：ComfyUI 是节点式界面，强大但学习曲线陡；SwarmUI 在 ComfyUI 上面加了一层"Generate"标签页，把常用参数做成表单，新手直接填 prompt 就能出图。高级用户仍然可以切到 Comfy Workflow 标签页用完整节点。

"Swarm"这个名字是什么意思？官方 README 说："The 'Swarm' name is in reference to the original key function of the UI: enabling a 'swarm' of GPUs to all generate images for the same user at once (especially for large grid generations)."——意思是它最初的设计目标是把多台机器的 GPU 组成一个集群，一起为同一个用户生成图片（特别是大图批量生成）。比如你有 4 张显卡分布在 4 台机器上，SwarmUI 可以把一个大任务拆成 4 份，4 张卡同时跑，速度是单卡的 4 倍。这个特性在批量生成几百张图、做网格对比图时特别有用。

底层架构：SwarmUI 本身是一个 .NET 8 写的 Web 服务器（监听 7801 端口），它通过 API 调用底层的 ComfyUI（Python 进程）做实际推理。你在 SwarmUI 界面里选模型、调参数，SwarmUI 把这些参数翻译成 ComfyUI 的工作流，发给 ComfyUI 执行，再把结果拿回来显示。所以 SwarmUI 本质上是 ComfyUI 的一个"高级前端"。这也意味着你需要同时装 .NET 运行时（跑 SwarmUI 本身）和 Python 环境（跑 ComfyUI 后端）。

二、核心功能逐条拆解

1. 多模型支持：Stable Diffusion、Flux、Krea 2、SDXL 等图像模型；Wan、LTX-2、MiniMax H3 视频模型；ACE-Step 音频模型。
2. 双界面模式：Generate 标签页（新手友好）+ Comfy Workflow 标签页（高级用户）。
3. 多 GPU Swarm：把多台机器的 GPU 组成集群，协同生成。
4. Grid Generator：批量生成网格图（不同参数组合的对比图）。
5. Image Editor：内置图片编辑器，可以在 UI 里直接修图、重绘。
6. 自动 Workflow 生成：根据你选的参数自动生成 Comfy 工作流，不用手搭节点。
7. Google Colab 支持：提供 Colab notebook，白嫖 GPU。
8. 云 GPU 支持：Runpod、Vast.ai 都有一键模板。
9. Docker 支持：官方 Docker.md 文档。
10. 跨平台：Windows、Linux、macOS（仅 M 系列）。
11. 云 GPU 一键模板：Runpod、Vast.ai 都有社区维护的一键模板，不用自己配环境。
12. Google Colab 白嫖：官方提供 Colab notebook，可以免费用 Google 的 GPU 跑。

三、全套官方链接

四、硬件与环境前置要求

官方 README 按平台列出了要求：

Windows： - Windows 10 或 11； - Windows 10 需要手动装 git 和 .NET 8 SDK；Windows 11 自动装； - GPU：推荐 NVIDIA GPU，6GB+ 显存。

Linux： - 需要 git 和 python3（推荐 3.11 或 3.12，3.10 也可以，3.13 可能行，不要用 3.14+）； - 需要 .NET 8 SDK 和 .NET 10 SDK； - Ubuntu Desktop：sudo apt install git python3-pip python3-venv； - Debian/Ubuntu Server：sudo apt install git python3-full。

macOS： - 仅支持 M 系列 Apple Silicon（M1/M2/M3/M4）； - 需要 brew install dotnet、brew install python@3.11、brew install virtualenv。

官方出处：README "Installing on Windows/Linux/Mac" 三个小节。

补充说明：无 GPU 能不能跑？能，但极慢。SDXL 模型在 CPU 上生成一张 1024x1024 的图可能要几分钟。建议至少有一张 6GB 显存的 NVIDIA GPU（如 RTX 3060），跑 Flux 大模型建议 12GB+（如 RTX 3090/4070Ti 以上）。Apple Silicon Mac 用 MPS 加速，速度比 NVIDIA 同价位慢但可用。显存不够时 SwarmUI 会自动启用内存交换（offload），但速度会明显下降。

五、多平台部署步骤

5.1 Windows 一键安装（官方推荐）

第 1 步：下载 install-windows.bat：

# 官方下载链接
https://github.com/mcmonkeyprojects/SwarmUI/releases/download/0.9.8-Beta/install-windows.bat

第 2 步：把这个 bat 文件放到你想安装的目录（不要放 Program Files），双击运行。

第 3 步：命令窗口会自动安装依赖。如果窗口闪退没继续，再跑一次（官方 README 说"it sometimes needs to run twice"）。

第 4 步：安装完成后桌面会出现图标，浏览器自动打开 http://localhost:7801/Install。

第 5 步：按网页引导完成后续安装（下载模型等）。

5.2 Linux 一键安装（官方 Easy Install）

第 1 步：装前置依赖：

# Ubuntu Desktop
sudo apt install git python3-pip python3-venv

# Debian / Ubuntu Server
sudo apt install git python3-full

第 2 步：下载并运行安装脚本：

wget https://github.com/mcmonkeyprojects/SwarmUI/releases/download/0.6.5-Beta/install-linux.sh -O install-linux.sh
chmod +x install-linux.sh
./install-linux.sh

第 3 步：脚本会自动安装所有依赖、克隆仓库、启动服务，最终在浏览器打开 http://localhost:7801。

5.3 Linux 手动安装（官方）

第 1 步：克隆仓库：

git clone https://github.com/mcmonkeyprojects/SwarmUI
cd SwarmUI

第 2 步：装 .NET 8 和 .NET 10 SDK：

./launchtools/linux-dotnet-install.sh

第 3 步：启动：

# 本地桌面
./launch-linux.sh

# 无头服务器模式（远程访问）
./launch-linux.sh --launch_mode none --host 0.0.0.0

第 4 步：浏览器打开 http://localhost:7801/Install 完成安装。

5.4 macOS M 系列安装（官方）

第 1 步：装依赖：

brew update
brew doctor
brew install dotnet
brew install python@3.11
brew install virtualenv

第 2 步：克隆并启动：

git clone https://github.com/mcmonkeyprojects/SwarmUI
cd SwarmUI
./launch-macos.sh

第 3 步：浏览器自动打开，按引导完成安装。

5.5 Docker 部署

官方文档指向 /docs/Docker.md。在服务器上用 Docker 跑 SwarmUI 适合团队共享，不用每个人本地装。

六、配置文件全部参数解释

SwarmUI 无传统配置文件，参数通过启动命令和 Web UI 调整。按官方 README 整理：

七、启动、后台常驻与开机自启

Linux 服务器上用 systemd 常驻：

[Unit]
Description=SwarmUI Service
After=network.target

[Service]
User=your_user
WorkingDirectory=/your/path/SwarmUI
ExecStart=/your/path/SwarmUI/launch-linux.sh --launch_mode none --host 0.0.0.0
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now swarmui

修改端口：在 Web UI 的 Settings 里改，或改启动参数。

八、功能实操教程

第 1 步：Windows 一键安装完成后，浏览器打开 http://localhost:7801。

第 2 步：首次进入会看到 Install 页面，按引导下载模型（推荐先下 SDXL 或 Flux 小模型试手）。

第 3 步：进入 Generate 标签页： 1. 在 Prompt 框里输入描述词，比如"a cute cat, sitting on a windowsill, sunlight, 4k"； 2. 选模型（下拉框）； 3. 设尺寸（比如 1024x1024）； 4. 点 Generate 按钮。

第 4 步：等待生成完成，图片出现在右侧预览区。可以点 Save 保存。生成速度取决于你的 GPU——一张 1024x1024 的图在 RTX 3060 上大约 5-10 秒，在 RTX 4090 上约 1-2 秒。

第 5 步：Grid Generator（批量对比）：在 Generate 标签页找到 Grid 选项，设置多个参数组合（比如不同的 seed、不同的 sampler），SwarmUI 会一次生成一张网格图，方便你对比哪个参数效果好。比如你可以设 3 个 sampler x 3 个 seed = 9 张图排成 3x3 网格，一眼看出哪个组合效果最好。

第 6 步：Comfy Workflow 标签页：高级用户切到这个标签页，可以看到完整的 Comfy 节点图，可以手动调整每个节点。

第 7 步：远程访问（Linux 服务器）：用 --host 0.0.0.0 启动后，在浏览器输入 http://服务器IP:7801 就能访问。如果服务器在云端，记得在防火墙/安全组里放行 7801 端口。

第 8 步：切换视频模型：在模型选择器里选 Wan 或 LTX-2，就可以生成视频（需要对应模型文件）。

第 9 步：多 GPU Swarm 集群配置。如果你有多台机器想组集群： 1. 在每台机器上都装好 SwarmUI； 2. 在主机器的 Settings 里添加从机器的 IP:端口； 3. SwarmUI 会自动把生成任务分发到所有可用 GPU 上。

这个功能对批量生成特别有用——比如你要生成 1000 张图，4 张卡一起跑比 1 张卡快 4 倍。

第 10 步：安装扩展。SwarmUI 支持扩展系统，在 Extensions 标签页可以安装社区开发的扩展（比如 LLM 辅助写 prompt、自定义采样器等）。官方 README 提到"LLM-assisted prompting"目前是扩展形式，未来会原生支持。

九、全套报错故障排查

1. 报错：Windows 安装 bat 闪退。 原因分析：官方 README 说"it sometimes needs to run twice"。 分步解决方案：再双击运行一次 install-windows.bat。

2. 报错：dotnet: command not found。 原因分析：没装 .NET SDK。 分步解决方案：Windows 去 https://dotnet.microsoft.com/en-us/download/dotnet/8.0 下载 SDK x64；Linux 跑 ./launchtools/linux-dotnet-install.sh；macOS 跑 brew install dotnet。

3. 报错：Python 依赖装不上。 原因分析：Python 版本不对（用了 3.14+）。 分步解决方案：装 Python 3.11 或 3.12：sudo apt install python3.11 python3.11-venv。

4. 报错：CUDA out of memory。 原因分析：显存不够。 分步解决方案：把生成尺寸调小（1024→768）；换用更小的模型；关掉其他占显存的程序。

5. 报错：浏览器打不开 http://localhost:7801。 原因分析：服务没启动成功，或端口被占用。 分步解决方案：看终端输出有没有报错；用 netstat -tlnp | grep 7801 检查端口占用。

6. 报错：macOS 上启动失败。 原因分析：你用的是 Intel Mac，SwarmUI 只支持 M 系列。 分步解决方案：官方 README 明确说"only run on Mac computers with M-Series Apple silicon"，Intel Mac 只能用 Docker 或云端 GPU。

7. 报错：模型下载很慢。 原因分析：HuggingFace 访问慢。 分步解决方案：在 Web UI 的 Settings 里设置 HF 镜像站；或手动下载模型文件放到 Models/ 目录。

8. 报错：生成的图片全是噪点或纯黑。 原因分析：模型文件没下完整，或 VAE 文件缺失。 分步解决方案：检查 Models 目录下模型文件大小是否正确；重新下载模型；在 Settings 里指定正确的 VAE 文件。

9. 报错：Permission denied 或目录写入失败。 原因分析：安装目录权限不对，或装在了 Program Files 这种受保护目录。 分步解决方案：把 SwarmUI 装在用户目录下（比如 C:\Users\yourname\SwarmUI 或 ~/SwarmUI），不要装在 Program Files。

十、升级、回滚与卸载

升级：cd SwarmUI && git pull && ./launch-linux.sh（Windows 重新跑 install-windows.bat）。SwarmUI 处于 Beta 阶段，更新频繁，建议每次升级前看 GitHub Releases 的 changelog。升级时 .NET 运行时和 Python 依赖也会自动更新，不需要手动装。

备份建议：SwarmUI 的用户数据在 Data/ 目录（生成的图片、自定义工作流、设置等），备份这个目录即可；模型文件在 Models/ 目录，可以单独备份。由于模型文件通常几个 GB 起步，备份时建议只备份 Data/ 目录，模型文件可以重新下载。

回滚：git checkout <旧版本tag>。SwarmUI 在 GitHub Releases 里有版本 tag。

卸载：直接删 SwarmUI 文件夹即可；systemd 方式 sudo systemctl disable --now swarmui 并删 unit 文件。Windows 安装的话，直接删文件夹 + 删桌面图标。

十一、商用许可与合规风险提示

MIT 协议，允许商用、修改、分发，只需保留版权声明。SwarmUI 本身是前端界面，不涉及模型权重许可——你用的模型（SD/Flux/Wan 等）各自有自己的许可证，商用前需要单独确认每个模型的许可。另外，生成内容的版权归属按你所在地法律判断，本教程不构成法律意见。

附录：SwarmUI vs ComfyUI vs SD WebUI 怎么选

一句话：新手想快速上手、需要多 GPU 批量生成、还要玩视频模型，选 SwarmUI；追求最大节点灵活性和插件生态，选 ComfyUI；习惯传统表单界面、老用户，继续用 SD WebUI。

附录：新手常见问题 FAQ

Q1：我是新手，Windows 一键安装包会不会搞坏我电脑？ A：不会。install-windows.bat 就是下载文件、装依赖、建个文件夹，不会动系统目录。唯一要注意的是不要把安装包放在 Program Files 里（权限不够）。

Q2：SwarmUI 和 ComfyUI 是什么关系？ A：SwarmUI 是 ComfyUI 的前端。你在 SwarmUI 里点的按钮，最终都会翻译成 ComfyUI 的工作流，由 ComfyUI 执行推理。所以装 SwarmUI 会自动帮你装好 ComfyUI。

Q3：我已经有 ComfyUI 了，还要装 SwarmUI 吗？ A：SwarmUI 会自己带一套 ComfyUI 后端，和你已有的 ComfyUI 不冲突，但也不共用。如果你想体验 SwarmUI 的表单界面和多 GPU 特性，可以单独装一套。

Q4：远程访问安全吗？ A：--host 0.0.0.0 会让服务监听所有网卡，任何人都能访问你的 7801 端口。公网服务器建议加反向代理 + 密码认证，或用 cloudflared 隧道（官方文档 Advanced Usage 里有写）。

Q5：生成的图片存在哪里？ A：默认在 Output/ 目录下，按日期分文件夹。你也可以在 Settings 里改输出目录。Web UI 里点图片右键可以直接下载。

Q6：支持 ControlNet 吗？ A：支持。因为底层是 ComfyUI，ComfyUI 支持的所有 ControlNet 模型 SwarmUI 都能用。在 Generate 标签页的 ControlNet 区域上传参考图即可。

参考链接

• GitHub 仓库：https://github.com/mcmonkeyprojects/SwarmUI
• 官方文档：https://github.com/mcmonkeyprojects/SwarmUI/blob/master/docs/README.md
• 官网：https://swarmui.net
• Colab：https://colab.research.google.com/github/mcmonkeyprojects/SwarmUI/blob/master/colab/colab-notebook.ipynb