Ubuntu24.04上从0部署Scaffold-GS遇到的问题与解决方案

摘要

本文记录了在 Ubuntu 24.04 系统上从零部署 Scaffold-GS 的完整过程，重点总结了 Conda 环境创建、PyTorch 与 MKL 兼容性、CUDA 编译器版本不一致、pip 编译 CUDA 扩展失败等问题的排查与解决方法。由于 Scaffold-GS 官方推荐环境相对较旧，而 Ubuntu 24.04 默认软件栈较新，因此部署过程中需要特别关注 Python、PyTorch、CUDA、GCC、Conda 依赖通道之间的版本匹配关系。

1. 背景说明

Scaffold-GS 是一个基于 3D Gaussian Splatting 的三维重建与渲染项目。其官方安装流程通常如下：

bash 复制代码

git clone https://github.com/city-super/Scaffold-GS.git --recursive
cd Scaffold-GS

conda env create --file environment.yml
conda activate scaffold_gs

需要注意的是，官方安装说明中包含如下命令：

bash 复制代码

SET DISTUTILS_USE_SDK=1 # Windows only

该命令仅适用于 Windows 环境，在 Ubuntu/Linux 系统中不应执行。

本次部署环境如下：

text 复制代码

操作系统：Ubuntu 24.04
项目路径：~/DownLoad/Scaffold-GS/Scaffold-GS
Conda 环境名：scaffold_gs
系统 CUDA 版本：CUDA 12.8
项目依赖 PyTorch CUDA 版本：CUDA 11.6

Scaffold-GS 的 environment.yml 中指定了较旧的深度学习环境，主要包括：

text 复制代码

python=3.7.13
pytorch=1.12.1
torchvision=0.13.1
torchaudio=0.12.1
cudatoolkit=11.6

同时，该项目需要编译两个本地 CUDA 扩展：

text 复制代码

submodules/diff-gaussian-rasterization
submodules/simple-knn

这也是部署过程中最容易出现问题的部分。

2. 基础依赖安装

进入项目目录后，首先安装基础编译工具：

bash 复制代码

cd ~/DownLoad/Scaffold-GS/Scaffold-GS

sudo apt update
sudo apt install -y build-essential cmake ninja-build git

执行后系统提示相关软件已经是最新版，说明基础编译工具已安装完成。

text 复制代码

build-essential 已经是最新版
cmake 已经是最新版
ninja-build 已经是最新版
git 已经是最新版

随后设置 C/C++ 编译器。由于 CUDA 扩展编译通常对 GCC 版本较敏感，建议优先使用较低版本的 GCC。例如：

bash 复制代码

export CC=/usr/bin/gcc-9
export CXX=/usr/bin/g++-9
export CUDAHOSTCXX=/usr/bin/g++-9

但在 Ubuntu 24.04 中，系统默认通常并不自带 GCC 9。因此需要先检查对应文件是否存在：

bash 复制代码

ls /usr/bin/gcc-9 /usr/bin/g++-9

如果不存在，可以改用 GCC 11：

bash 复制代码

sudo apt install -y gcc-11 g++-11

export CC=/usr/bin/gcc-11
export CXX=/usr/bin/g++-11
export CUDAHOSTCXX=/usr/bin/g++-11

3. 问题一：Conda 创建环境时下载中断

执行环境创建命令：

bash 复制代码

conda env create --file environment.yml
conda activate scaffold_gs

过程中出现如下错误：

text 复制代码

Connection broken: IncompleteRead(...)
EnvironmentNameNotFound: Could not find conda environment: scaffold_gs

3.1 问题原因

该问题并不是 conda activate 本身出错，而是 Conda 在下载较大的依赖包时网络连接中断，导致 scaffold_gs 环境没有完整创建。因此后续激活环境时，系统找不到该环境。

本次中断主要发生在下载 PyTorch 相关大包时：

text 复制代码

pytorch-1.12.1 | 1.20 GB

由于包体积较大，网络不稳定时容易出现 IncompleteRead 或 RemoteDisconnected 等错误。

3.2 解决方案

首先清理 Conda 缓存：

bash 复制代码

conda clean -a -y

然后增加 Conda 的超时和重试次数：

bash 复制代码

conda config --set remote_connect_timeout_secs 60
conda config --set remote_read_timeout_secs 1000
conda config --set remote_max_retries 10

重新创建环境：

bash 复制代码

conda env create --file environment.yml

创建完成后再单独激活环境：

bash 复制代码

conda activate scaffold_gs

不建议将环境创建和环境激活连续写在同一组命令中执行，因为如果前一步失败，后一步必然失败，容易干扰问题判断。

4. 问题二：pip 阶段安装 CUDA 子模块失败，PyTorch 无法导入

Conda 依赖安装完成后，环境创建进入 pip 依赖安装阶段，但在安装 diff-gaussian-rasterization 时失败：

text 复制代码

ImportError: 
/home/ddsm/Installation/anaconda3/envs/scaffold_gs/lib/python3.7/site-packages/torch/lib/libtorch_cpu.so:
undefined symbol: iJIT_NotifyEvent

4.1 问题原因

该错误发生在导入 PyTorch 时：

python 复制代码

from torch.utils.cpp_extension import CUDAExtension, BuildExtension

也就是说，此时并不是 CUDA 扩展本身编译失败，而是 PyTorch 在当前 Conda 环境中无法正常导入。

iJIT_NotifyEvent 相关错误通常与 MKL 版本不兼容有关。旧版本 PyTorch 与较新的 MKL 运行库组合时，可能出现符号缺失问题。

本项目使用的是：

text 复制代码

PyTorch 1.12.1
CUDA 11.6
Python 3.7

该环境较旧，而 Conda 可能解析并安装了较新的 MKL 版本，从而导致 PyTorch 导入失败。

4.2 解决方案

首先进入已经创建出来的环境：

bash 复制代码

conda activate scaffold_gs

然后尝试降级 MKL：

bash 复制代码

conda install -y -c defaults mkl=2024.0.0

如果精确版本不可用，可以使用更宽松的约束：

bash 复制代码

conda install -y -c defaults "mkl<2024.1"

之后测试 PyTorch 是否能够正常导入：

bash 复制代码

python - <<'PY'
import torch
print("torch:", torch.__version__)
print("torch cuda:", torch.version.cuda)
print("cuda available:", torch.cuda.is_available())
print("gpu:", torch.cuda.get_device_name(0) if torch.cuda.is_available() else "None")
PY

如果不再出现 undefined symbol: iJIT_NotifyEvent，说明 MKL 兼容性问题已经解决。

由于环境创建时 pip 阶段已经失败，需要手动补装 pip 依赖：

bash 复制代码

cd ~/DownLoad/Scaffold-GS/Scaffold-GS

pip install einops wandb lpips laspy

5. 问题三：编译 CUDA 扩展时报 CUDA 版本不匹配

手动安装 pip 依赖后，继续安装两个本地 CUDA 子模块：

bash 复制代码

pip install -v submodules/diff-gaussian-rasterization
pip install -v submodules/simple-knn

此时出现新的错误：

text 复制代码

RuntimeError:
The detected CUDA version (12.8) mismatches the version that was used to compile
PyTorch (11.6). Please make sure to use the same CUDA versions.

5.1 问题原因

该错误的含义非常明确：

text 复制代码

当前系统检测到的 CUDA 编译器版本：12.8
当前 PyTorch 编译时使用的 CUDA 版本：11.6

也就是说，虽然 Conda 环境中安装的是 CUDA 11.6 版本的 PyTorch，但在编译 CUDA 扩展时，系统调用到的 nvcc 却来自系统 CUDA 12.8。

CUDA 扩展编译时，PyTorch 会检查当前 nvcc 的版本是否与 torch.version.cuda 一致。如果二者不匹配，就会终止编译。

本次问题的关键在于：

text 复制代码

PyTorch CUDA 版本：11.6
系统 nvcc 版本：12.8

两者不一致，因此 diff-gaussian-rasterization 和 simple-knn 都无法编译。

5.2 排查命令

在 scaffold_gs 环境中执行：

bash 复制代码

which nvcc
nvcc --version

如果输出显示 CUDA 12.8，例如：

text 复制代码

Cuda compilation tools, release 12.8

则说明当前环境调用的是系统 CUDA，而不是与 PyTorch 匹配的 CUDA 11.6 编译器。

同时检查 PyTorch 的 CUDA 版本：

bash 复制代码

python - <<'PY'
import torch
print(torch.__version__)
print(torch.version.cuda)
print(torch.cuda.is_available())
PY

如果输出为：

text 复制代码

1.12.1
11.6
True

则进一步证明 PyTorch 与当前 nvcc 不一致。

5.3 解决方案

需要在当前 Conda 环境中安装 CUDA 11.6 编译工具，并强制当前 shell 使用 Conda 环境内的 CUDA。

优先执行：

bash 复制代码

conda install -y -c conda-forge cuda-toolkit=11.6

如果解依赖失败，可以尝试：

bash 复制代码

conda install -y -c conda-forge cudatoolkit-dev=11.6

或者：

bash 复制代码

conda install -y -c nvidia cuda-nvcc=11.6

安装完成后设置环境变量：

bash 复制代码

export CUDA_HOME=$CONDA_PREFIX
export PATH=$CONDA_PREFIX/bin:$PATH
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$LD_LIBRARY_PATH

再次检查 nvcc：

bash 复制代码

which nvcc
nvcc --version

期望结果应类似：

text 复制代码

/home/ddsm/Installation/anaconda3/envs/scaffold_gs/bin/nvcc
Cuda compilation tools, release 11.6

只有当 nvcc --version 显示 CUDA 11.6 时，才应继续编译本地 CUDA 扩展。

6. 清理失败构建并重新安装子模块

在前面编译失败后，建议先清理残留的构建目录：

bash 复制代码

cd ~/DownLoad/Scaffold-GS/Scaffold-GS

rm -rf submodules/diff-gaussian-rasterization/build
rm -rf submodules/simple-knn/build

然后重新安装两个 CUDA 子模块：

bash 复制代码

pip install -v submodules/diff-gaussian-rasterization --force-reinstall --no-cache-dir
pip install -v submodules/simple-knn --force-reinstall --no-cache-dir

如果此时仍然失败，应重点检查以下三项：

bash 复制代码

which nvcc
nvcc --version
echo $CUDA_HOME

其中最重要的是，nvcc --version 必须与 PyTorch 的 CUDA 版本保持一致。

7. 最终验证

安装完成后，执行如下测试：

bash 复制代码

python - <<'PY'
import torch
import diff_gaussian_rasterization
import simple_knn

print("All OK")
print("torch:", torch.__version__)
print("torch cuda:", torch.version.cuda)
print("cuda available:", torch.cuda.is_available())
print("gpu:", torch.cuda.get_device_name(0) if torch.cuda.is_available() else "None")
PY

如果输出中没有 ImportError 或 RuntimeError，并显示：

text 复制代码

All OK
cuda available: True

则说明 Scaffold-GS 的 Python 环境和两个关键 CUDA 扩展已经安装完成。

8. 推荐的完整安装流程

综合本次部署经验，在 Ubuntu 24.04 上部署 Scaffold-GS 时，推荐按如下顺序执行：

bash 复制代码

# 1. 克隆仓库
git clone https://github.com/city-super/Scaffold-GS.git --recursive
cd Scaffold-GS

# 2. 确认子模块
git submodule update --init --recursive

# 3. 安装基础工具
sudo apt update
sudo apt install -y build-essential cmake ninja-build git

# 4. 创建 Conda 环境
conda clean -a -y
conda config --set remote_connect_timeout_secs 60
conda config --set remote_read_timeout_secs 1000
conda config --set remote_max_retries 10

conda env create --file environment.yml
conda activate scaffold_gs

# 5. 修复可能出现的 MKL 兼容性问题
conda install -y -c defaults "mkl<2024.1"

# 6. 安装与 PyTorch 匹配的 CUDA 11.6 编译工具
conda install -y -c conda-forge cuda-toolkit=11.6

# 7. 设置 CUDA 环境变量
export CUDA_HOME=$CONDA_PREFIX
export PATH=$CONDA_PREFIX/bin:$PATH
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$LD_LIBRARY_PATH

# 8. 设置 GCC
sudo apt install -y gcc-11 g++-11
export CC=/usr/bin/gcc-11
export CXX=/usr/bin/g++-11
export CUDAHOSTCXX=/usr/bin/g++-11

# 9. 检查 CUDA 版本
which nvcc
nvcc --version

# 10. 手动补装 pip 依赖
pip install einops wandb lpips laspy

# 11. 清理失败构建目录
rm -rf submodules/diff-gaussian-rasterization/build
rm -rf submodules/simple-knn/build

# 12. 编译并安装 CUDA 子模块
pip install -v submodules/diff-gaussian-rasterization --force-reinstall --no-cache-dir
pip install -v submodules/simple-knn --force-reinstall --no-cache-dir

# 13. 验证安装
python - <<'PY'
import torch
import diff_gaussian_rasterization
import simple_knn

print("All OK")
print("torch:", torch.__version__)
print("torch cuda:", torch.version.cuda)
print("cuda available:", torch.cuda.is_available())
print("gpu:", torch.cuda.get_device_name(0) if torch.cuda.is_available() else "None")
PY

9. 经验总结

本次部署过程中遇到的问题主要集中在三个方面。

第一，Conda 下载大体积依赖包时可能因网络波动中断。对于 PyTorch 这类超过 1GB 的包，建议提前清理缓存，并增加 Conda 的超时与重试次数。

第二，旧版 PyTorch 与新版 MKL 之间可能存在 ABI 或符号兼容性问题。如果出现 libtorch_cpu.so: undefined symbol: iJIT_NotifyEvent，应优先检查 MKL 版本，并尝试将其限制在 mkl<2024.1。

第三，编译 CUDA 扩展时，PyTorch 使用的 CUDA 版本必须与当前调用的 nvcc 版本一致。系统安装了 CUDA 12.8 并不代表 Conda 环境中的 PyTorch 也能使用 CUDA 12.8 编译扩展。本项目中 PyTorch 是 CUDA 11.6 版本，因此必须确保 nvcc --version 也显示 CUDA 11.6。

对于 Scaffold-GS、3D Gaussian Splatting、Mip-Splatting 等依赖 CUDA 扩展编译的项目，部署时不能只关注显卡驱动是否可用，还必须同时检查以下内容：

text 复制代码

Python 版本
PyTorch 版本
torch.version.cuda
nvcc --version
CUDA_HOME
GCC/G++ 版本
本地 CUDA 扩展编译日志

其中，torch.version.cuda 与 nvcc --version 的一致性，是判断 CUDA 扩展能否顺利编译的关键。

10. 结论

在 Ubuntu 24.04 上部署 Scaffold-GS 的主要困难来自新系统软件栈与项目旧依赖之间的版本差异。通过逐步排查 Conda 下载、PyTorch 导入、MKL 兼容性、CUDA 编译器版本和 GCC 设置，可以较为系统地解决部署过程中的问题。

本次问题的最终核心结论是：Scaffold-GS 使用 PyTorch 1.12.1 + CUDA 11.6，因此在编译 diff-gaussian-rasterization 和 simple-knn 时，必须确保当前环境调用的 nvcc 也是 CUDA 11.6，而不是 Ubuntu 24.04 系统中较新的 CUDA 12.x。