Ubuntu 24.04 LTS 本地部署 ComfyUI + Flux + Nunchaku 完整安装指南

home 编辑时间 2025/06/29

![flux](/api/file/getImage?fileId=68609ef6c0a657000b0d3862)

> 基于Ubuntu 24.04系统的完整安装记录，包含所有关键步骤和解决方案

## 📋 系统要求

- Ubuntu 24.04 LTS
- NVIDIA GPU (支持CUDA) 至少8G显存
- 至少16GB内存
- 50GB+可用存储空间
- 稳定的网络连接（需要代理）

再多提醒一句
如果你是买服务器安装配置这套环境，强烈建议选择海外服务器，虽然你连服务器经常速度慢断开连接。
但是部署过程丝滑流畅无卡顿，下载模型速度起飞。注意这个模型是不能用hf-mirror的，必须用魔法。
如果你就想要在国内服务器或者你自己家里电脑部署。就必须有一个速度快的代理，或者有一颗强大的内心。
我是在i9 12900f + 3080(12g) + 32gRAM 刷的ubuntu24.04然后开始部署的，总共花了12个小时。血压至少到200+

## 🚀 第一阶段：环境准备

### 1.1 系统信息检查
```bash
# 检查系统版本
lsb_release -a
uname -a

# 检查硬件信息
lscpu
free -h
nvidia-smi

# 检查GPU信息
lspci -nnk | grep -i vga -A3
```

### 1.2 更换APT镜像源（推荐）
```bash
# 备份原始源文件
sudo cp /etc/apt/sources.list /etc/apt/sources.list.backup
sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.backup

# 手动编辑源文件，替换为清华镜像源
sudo vim /etc/apt/sources.list
# 将 archive.ubuntu.com 替换为 mirrors.tuna.tsinghua.edu.cn
# 将 security.ubuntu.com 替换为 mirrors.tuna.tsinghua.edu.cn

sudo vim /etc/apt/sources.list.d/ubuntu.sources  
# 将 http://archive.ubuntu.com/ubuntu/ 替换为 https://mirrors.tuna.tsinghua.edu.cn/ubuntu/
# 将 http://security.ubuntu.com/ubuntu/ 替换为 https://mirrors.tuna.tsinghua.edu.cn/ubuntu/

# 验证修改
cat /etc/apt/sources.list
cat /etc/apt/sources.list.d/ubuntu.sources

# 更新包列表使新源生效
sudo apt update
```

### 1.3 安装基础工具
```bash
# 升级系统
sudo apt upgrade -y

# 安装必需工具
sudo apt install python3-pip git curl vim software-properties-common -y

# 检查Python版本
python3 --version
pip --version
```

## 🔧 第二阶段：网络代理配置

### 2.1 Git代理设置
```bash
# 配置Git代理（关键步骤）
git config --global http.proxy http://127.0.0.1:2080
git config --global https.proxy http://127.0.0.1:2080
```

### 2.2 环境变量设置
```bash
# 设置代理环境变量
export http_proxy="http://127.0.0.1:2080"
export https_proxy="http://127.0.0.1:2080"
export ALL_PROXY="http://127.0.0.1:2080"
```

## 🐍 第三阶段：Python环境配置

### 3.1 安装Python 3.10
```bash
# 添加Python源
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update

# 安装Python 3.10及相关工具
sudo apt install python3.10 python3.10-venv python3.10-dev -y
```

### 3.2 创建项目环境
```bash
# 创建项目目录
mkdir -p ~/comfyui && cd ~/comfyui

# 创建Python 3.10虚拟环境
python3.10 -m venv venv310

# 激活虚拟环境
source venv310/bin/activate

# 升级pip并配置代理
pip install --upgrade pip
pip config set global.proxy http://127.0.0.1:2080
```

这里要注意，如果你中途中断过操作，或者你重启过电脑之类的
必须再补上这句 `source venv310/bin/activate` 才可以继续
后续所有命令都必须基于这句，否则你离开虚拟环境再去安装就炸的家都不认识了

## 🤖 第四阶段：ComfyUI安装

### 4.1 安装PyTorch
```bash
# 安装PyTorch 2.6.0 + CUDA 12.4
pip install torch==2.6.0+cu124 torchvision==0.21.0+cu124 torchaudio==2.6.0+cu124 --extra-index-url https://download.pytorch.org/whl/cu124

# 验证安装
python -c "import torch; print(f'PyTorch版本: {torch.__version__}'); print(f'CUDA可用: {torch.cuda.is_available()}'); print(f'CUDA版本: {torch.version.cuda}')"
```

### 4.2 克隆ComfyUI
```bash
# 克隆ComfyUI仓库
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI

# 安装依赖
pip install -r requirements.txt
pip install huggingface_hub
```

## ⚡ 第五阶段：Nunchaku安装

### 5.1 安装CUDA工具包
```bash
# 安装NVIDIA CUDA工具包
sudo apt install nvidia-cuda-toolkit

# 验证安装
nvcc --version
```

### 5.2 安装Nunchaku（关键步骤）
```bash
# 下载特定版本的nunchaku wheel文件
wget https://github.com/mit-han-lab/nunchaku/releases/download/v0.3.1/nunchaku-0.3.1+torch2.6-cp310-cp310-linux_x86_64.whl

# 安装nunchaku
pip install ./nunchaku-0.3.1+torch2.6-cp310-cp310-linux_x86_64.whl

# 验证安装
pip show nunchaku
```

### 5.3 安装ComfyUI-Nunchaku插件
```bash
# 进入custom_nodes目录
cd custom_nodes

# 克隆nunchaku插件
git clone https://github.com/mit-han-lab/ComfyUI-nunchaku.git
cd ComfyUI-nunchaku

# 安装插件依赖
pip install -r requirements.txt
```

## 📦 第六阶段：模型下载

### 6.1 HuggingFace配置
```bash
# 登录HuggingFace 改为你的token 没有去注册一个
export HF_TOKEN="改为你自己的token"
huggingface-cli login --token $HF_TOKEN
```

### 6.2 下载Flux模型文件
```bash
cd ~/comfyui/ComfyUI

# 下载Nunchaku量化的Flux模型 - 注意svdq-int4_r32文件的特殊路径！
huggingface-cli download mit-han-lab/svdq-int4-flux.1-dev svdq-int4_r32-flux.1-dev.safetensors --local-dir models/diffusion_models

# 下载VAE模型
huggingface-cli download black-forest-labs/FLUX.1-dev ae.safetensors --local-dir models/vae

# 下载文本编码器
huggingface-cli download comfyanonymous/flux_text_encoders clip_l.safetensors --local-dir models/clip
huggingface-cli download comfyanonymous/flux_text_encoders t5xxl_fp16.safetensors --local-dir models/clip
```

### 6.3 验证模型文件
```bash
# 检查下载的文件
ls -lh models/unet/
ls -lh models/vae/
ls -lh models/clip/
```

## 🔌 第七阶段：安装附加依赖

### 7.1 安装图像处理依赖
```bash
# 安装OpenCV和其他图像处理库（必需依赖）
pip install opencv-python
pip install insightface
pip install onnxruntime onnx 
pip install scikit-image matplotlib
pip install facexlib
pip install timm

# 注意：如果某个依赖安装失败，ComfyUI启动时会提示缺少该包，按需补装即可
```

### 7.2 安装XFormers
```bash
# 安装XFormers加速库
pip install xformers==0.0.29.post2
```

### 7.3 安装Apex（可选但推荐）
```bash
# Apex是NVIDIA的混合精度训练库，可以提升性能（非必需）
# ⚠️ 注意：这是一个"血坑"，需要从源码编译且有版本检查问题

# 首先安装CUDA工具包
sudo apt install nvidia-cuda-toolkit

# 检查nvcc路径并创建符号链接（解决nvcc路径问题）
which nvcc
sudo mkdir -p /usr/local/cuda/bin
sudo ln -sf /usr/bin/nvcc /usr/local/cuda/bin/nvcc

# 克隆Apex仓库
git clone https://github.com/NVIDIA/apex
cd apex

# 手动编辑setup.py解决CUDA版本检查问题
vim setup.py
# 找到第40-48行的以下代码段，在每行前面加上 # 进行注释：
#
# if (bare_metal_version != torch_binary_version):
#     raise RuntimeError(
#         "Cuda extensions are being compiled with a version of Cuda that does "
#         "not match the version used to compile Pytorch binaries.  "
#         "Pytorch binaries were compiled with Cuda {}.\n".format(torch.version.cuda)
#         + "In some cases, a minor-version mismatch will not cause later errors:  "
#         "https://github.com/NVIDIA/apex/pull/323#discussion_r287021798.  "
#         "You can try commenting out this check (at your own risk)."
#     )

# 编译安装Apex（耗时30分钟-3小时）
pip install -v --disable-pip-version-check --no-cache-dir --no-build-isolation ./

# 返回ComfyUI目录
cd ~/comfyui/ComfyUI
```

> ⚠️ **重要提醒**: Apex安装可能需要30分钟-3小时，且容易出错。如果遇到编译问题，可以跳过此步骤，ComfyUI仍可正常运行。

### 7.4 安装ComfyUI Manager
```bash
cd ~/comfyui/ComfyUI/custom_nodes

# 克隆ComfyUI Manager
git clone https://github.com/ltdrdata/ComfyUI-Manager.git
```

### 7.5 通过ComfyUI Manager安装Crystools插件
```bash
# 启动ComfyUI后，在Web界面中：
# 1. 点击右侧的"Manager"按钮
# 2. 选择"Install Custom Nodes" 
# 3. 搜索"Crystools"
# 4. 点击"Install"按钮安装
# 5. 重启ComfyUI使插件生效
```

> 💡 **提示**: Crystools是一个实用的工具集插件，提供图像处理和工作流优化功能。

## ⚙️ 第八阶段：系统优化

### 8.1 调整交换空间设置
```bash
# 编辑系统配置
sudo vim /etc/sysctl.conf

# 添加以下行（降低swap使用频率）
vm.swappiness=10

# 应用配置
sudo sysctl -p

# 验证设置
cat /proc/sys/vm/swappiness
```

## 🎯 第九阶段：启动和测试

### 9.1 启动ComfyUI
```bash
cd ~/comfyui/ComfyUI
source ../venv310/bin/activate

# 启动ComfyUI
python main.py --port 8188
```

### 9.2 访问Web界面
- 打开浏览器访问：`http://localhost:8188`
- 或者局域网访问：`http://your-ip:8188`

## 🛠️ 常见问题解决

### Q1: svdq-int4_r32-flux.1-dev.safetensors 模型加载失败
**解决方案**：⚠️ **关键！** 这个文件必须放在 `models/diffusion_models/` 目录，而不是 `models/unet/` 目录！

### Q2: Apex编译失败或CUDA版本不匹配
**解决方案**：
```bash
# 1. 确保nvcc路径正确
which nvcc
sudo mkdir -p /usr/local/cuda/bin  
sudo ln -sf /usr/bin/nvcc /usr/local/cuda/bin/nvcc

# 2. 手动编辑setup.py，注释掉第40-48行的版本检查代码
cd apex
vim setup.py
# 在第40-48行前添加 # 号注释掉版本检查代码

# 3. 重新编译安装
pip install -v --disable-pip-version-check --no-cache-dir --no-build-isolation ./
```
**注意**：Apex安装失败不影响ComfyUI正常运行，可以跳过。

### Q3: Nunchaku安装失败
**解决方案**：确保使用Python 3.10和正确的wheel文件版本

### Q4: 模型下载中断
**解决方案**：检查代理设置，重新设置环境变量后继续下载

### Q5: CUDA内存不足
**解决方案**：
```bash
# 设置内存优化环境变量
export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512
```

### Q6: 启动时报依赖错误
**解决方案**：按需安装缺失的包
```bash
pip install 缺失的包名
```

## 📝 重要文件路径

- **ComfyUI主目录**: `~/comfyui/ComfyUI/`
- **模型文件**: `~/comfyui/ComfyUI/models/`
- **自定义节点**: `~/comfyui/ComfyUI/custom_nodes/`
- **虚拟环境**: `~/comfyui/venv310/`

## 🎉 安装完成检查清单

- [ ] APT镜像源已更换（可选）
- [ ] Python 3.10虚拟环境创建成功
- [ ] PyTorch 2.6.0 + CUDA 12.4安装成功
- [ ] ComfyUI克隆并安装依赖成功
- [ ] Nunchaku 0.3.1安装成功
- [ ] 所有必需依赖包安装完成
- [ ] XFormers安装成功
- [ ] Apex安装成功（可选）
- [ ] 所有Flux模型文件下载完成
- [ ] ComfyUI Manager插件安装成功
- [ ] Crystools插件安装成功
- [ ] ComfyUI能够正常启动
- [ ] Web界面可以正常访问
- [ ] 能够加载Nunchaku节点

## 📄 版本信息

- **ComfyUI**: 最新版本
- **PyTorch**: 2.6.0+cu124
- **Nunchaku**: 0.3.1+torch2.6
- **Python**: 3.10
- **CUDA**: 12.4
- **系统**: Ubuntu 24.04 LTS

---

**安装日期**: 根据实际安装日期填写  
**耗时**: 约2-4小时（取决于网络速度）  
**难度**: ⭐⭐⭐⭐☆（需要一定Linux经验）

> 💡 **提示**: 建议先在测试环境中完整走一遍流程，确认无误后再在生产环境部署。

## 📜 附录：快速启动脚本 (flux.sh)

为了方便日常使用，可以创建一个启动脚本：

```bash
#!/bin/bash
echo "设置代理..."
export ALL_PROXY=http://127.0.0.1:2080

echo "启动 ComfyUI + Nunchaku FLUX..."
echo "正在切换到工作目录..."
cd ~/comfyui

echo "激活虚拟环境..."
source venv310/bin/activate

echo "进入 ComfyUI 目录..."
cd ComfyUI

echo "启动 ComfyUI 服务器..."
echo "访问地址: http://127.0.0.1:8188"
echo "按 Ctrl+C 停止服务器"
python main.py --port 8188
```

**使用方法**：
```bash
# 保存为 flux.sh
chmod +x flux.sh
./flux.sh
```

这个脚本会自动完成所有启动步骤，包括代理设置、环境激活和ComfyUI启动。

送人玫瑰,手留余香