企业官网建设流程全解析

在 Ubuntu 20.04 上把 IS-Fusion 环境从零搭起来，比我想象中要曲折得多。这个项目本身不复杂，真正麻烦的是 CUDA 11.1、PyTorch 1.10.1 和系统驱动三者之间的匹配关系，稍微有一个版本对不上，编译的时候就会冒出一堆看似莫名其妙、实际上全靠经验才能定位的报错。这篇文章把我从裸机开始部署的全部过程、踩过的坑、排查思路都整理出来了，包括为什么非要这个版本组合、哪些地方可以偷懒、哪些命令必须在 root 权限下执行。不管你是第一次接触神经三维重建，还是已经在不少环境里折腾过，照着这套流程走，基本能一次点亮。

1. 部署思路和版本选型：先把环境地图走通，再动手装

1.1 IS-Fusion 的依赖链条到底有多长

IS-Fusion 本质上是一个基于深度学习的多视角三维重建项目，运行链路里既有 Python 端的推理代码，又有需要编译的 CUDA 扩展，还牵扯到三维点云处理和可视化。这类项目的依赖通常不是“pip install 完事”，它至少包含这么几层：

• 底层 CUDA 运行时和驱动：负责调用 GPU 算力，驱动版本必须能支撑 CUDA 11.1。
• PyTorch 生态：PyTorch 1.10.1 在编译时依赖 CUDA 11.1 的算子库，torchvision 又依赖 PyTorch 的版本接口。
• CUDA 扩展：IS-Fusion 里用到的部分算子不会都出现在 PyTorch 官方安装包里，项目可能需要从源码编译 tiny-cuda-nn 这类高性能 CUDA 扩展。
• Python 库：Open3D、OpenCV、NumPy、trimesh 等，分别负责点云读写、图像读取、张量处理和网格处理。

关键在于，这一整条依赖链每一环都有版本约束，它们不是互相独立的。你可以在 PyPI 上装一个最新版 NumPy，但那可能会让旧版 PyTorch 直接报错；你可以在系统里装一个很新的驱动，但未必能和 CUDA 11.1 的编译工具链完美配合。所以我在动手之前，把所有版本约束先写在纸上，逐个确认兼容范围，而不是直接抄 README 的命令。

1.2 版本选型的核心原则：先看兼容性表再看 README

很多人拿到项目第一反应是打开 README，按部就班执行。这个思路没错，但 README 往往只写了“建议用 CUDA 11.1 + PyTorch 1.10.1”，不会告诉你这些版本是开发者在某台固定机器上验证过的，更不会告诉你为什么 Ubuntu 20.04 是相对稳妥的选择。

我当时选型的基本原则是：不追新，只看兼容矩阵。PyTorch 1.10.1 官方发布的预编译包里有四种 CUDA 变体，分别为 CPU、CUDA 10.2、CUDA 11.1、CUDA 11.3。其中 CUDA 11.1 是 IS-Fusion 依赖链里被验证次数最多的版本，因为项目源码中的 CMake 编译脚本和扩展模块，大多是在这个 CUDA 版本下调整过的。Ubuntu 20.04 的默认 GCC 是 9.4，而 CUDA 11.1 对 GCC 的支持范围恰好覆盖了 GCC 6 到 GCC 9，这意味着不需要额外切换编译器版本。

相比之下，Ubuntu 22.04 的默认 GCC 已经是 11，直接编译 CUDA 11.1 的代码时，会遇到大量不匹配警告，有些甚至直接致命。所以，如果项目没明确支持新版系统，老老实实装 Ubuntu 20.04 反而是节省时间的方式。

1.3 硬件上需要做好哪些确认

开始之前，先用最简单的方式确认手头机器的 GPU 型号，并判断其计算能力是否被项目支持。执行下面命令：

lspci | grep -i nvidia

也可以用nvidia-smi，不过新系统还没装驱动时这条命令大概率不可用。一般来说，IS-Fusion 这类只需 CUDA 11.1 的项目，对显卡要求并不算苛刻，GTX 10 系列、RTX 20 系列、RTX 30 系列都能跑，但不同架构对应的计算能力不同，比如 GTX 1080 Ti 是 6.1，RTX 2080 Ti 是 7.5，RTX 3090 是 8.6。提前知道这个数字很重要，后面编译 CUDA 扩展时需要精准设置TORCH_CUDA_ARCH_LIST，否则要么编译报错，要么编译出来的算子根本无法在当前显卡上执行。

还要确认内存和磁盘空间。建议系统盘至少预留 30GB 以上，光是 CUDA Toolkit、conda 环境和项目依赖，加起来就很容易超过 10GB，如果还打算下载数据集做训练，空间需求会更大。内存方面，16GB 是最低要求，32GB 会舒服很多，因为三维重建项目在处理点云和稠密网格时经常会出现短暂的高内存占用。

2. Ubuntu 20.04 系统准备：从装系统到点亮 NVIDIA 驱动

2.1 系统安装与 apt 源加速

部署环境的第一步是装一个干净的 Ubuntu 20.04。这里建议安装桌面版，虽然纯服务器版更轻量，但后续如果你想快速查看可视化结果或调试三维渲染，桌面环境能省掉不少麻烦。安装过程中选择最小安装即可，不需要额外装第三方软件。

系统装好之后，第一件事是更新 apt 源。默认源在国外，下载速度通常很慢，可以替换成清华镜像源，Ubuntu 20.04 的代号是 focal，对应路径如下：

sudo sed -i 's@http://archive.ubuntu.com/ubuntu@http://mirrors.tuna.tsinghua.edu.cn/ubuntu@g' /etc/apt/sources.list sudo sed -i 's@http://security.ubuntu.com/ubuntu@http://mirrors.tuna.tsinghua.edu.cn/ubuntu@g' /etc/apt/sources.list sudo apt update

如果你当初安装时选择的镜像源不是官方源，sources.list 里的地址可能已经不同，那就手动编辑/etc/apt/sources.list，确保里面出现的是mirrors.tuna.tsinghua.edu.cn/ubuntu。更新完成后，顺手把基础编译工具装上：

sudo apt install -y build-essential gcc g++ make wget git

这里有个隐藏坑：Ubuntu 20.04 默认自带 GCC 9.4，正合适，但如果你之前装过build-essential或者通过其他方式升级了 GCC，就要检查一下版本，避免冲掉 CUDA 11.1 的编译兼容性。

2.2 安装 NVIDIA 驱动并禁用 nouveau

Ubuntu 20.04 默认显卡驱动是开源的 nouveau，深度学习根本没法用，必须换成 NVIDIA 官方驱动。最推荐的方式不是去官网手动下驱动安装包，而是直接用 Ubuntu 自带的 ubuntu-drivers 工具：

sudo ubuntu-drivers devices

执行后系统会列出当前机器可用的 NVIDIA 驱动版本，并标注recommended。我当时看到推荐版本是 470，果断直接安装：

sudo apt install -y nvidia-driver-470

安装过程中会自动处理一部分 nouveau 禁用逻辑，但为了保险，我建议手动再写一个 blacklist 文件，防止重启后 nouveau 又抢占显卡：

sudo bash -c "echo 'blacklist nouveau' >> /etc/modprobe.d/blacklist-nvidia-nouveau.conf" sudo bash -c "echo 'options nouveau modeset=0' >> /etc/modprobe.d/blacklist-nvidia-nouveau.conf" sudo update-initramfs -u sudo reboot

重启后如果看到桌面正常，说明驱动基本没问题；如果黑屏或者卡在登录界面，可能是驱动和 display manager 冲突，可以在 GRUB 启动项里加nomodeset参数临时绕过，再排查驱动安装细节。

注意：这一步千万别跳过“禁用 nouveau”，否则你后面运行nvidia-smi时大概率会看到一个couldn't communicate with the NVIDIA driver的报错，问题定位起来很闹心。

2.3 验证驱动、gcc 和基础编译环境

重启后打开终端，查看驱动是否生效：

nvidia-smi

正常情况下会显示类似这样的信息：

NVIDIA-SMI 470.xx.xx Driver Version: 470.xx.xx CUDA Version: 11.4

注意这里的CUDA Version是驱动支持的最高 CUDA 版本，不代表系统已经装了 CUDA Toolkit，也不代表项目能用 11.4 编译。只要这个数字大于等于 11.1，驱动层面就满足要求了。

然后再确认一下编译器版本和基本环境：

gcc --version python3 --version

gcc 9.x 是理想结果。python3 版本不关键，因为后面会用 conda 单独创建环境。到这里，系统层准备就完整了，可以开始处理深度学习环境。

3. 安装 CUDA 11.1 和 PyTorch 1.10.1

3.1 为什么系统要装 CUDA Toolkit，而不是全靠 PyTorch

不少新手会天真地以为，PyTorch 预编译包里已经带了 CUDA 运行时，就不需要再单独装 CUDA Toolkit 了。这个想法只对了一半。PyTorch 的 cu111 wheel 确实捆绑了部分 CUDA 动态库，但并没有捆绑 nvcc 编译器，也没有完整的 CUDA 头文件。当你需要从源码编译 CUDA 扩展时，编译器找不到cuda_runtime.h，就会直接报错。

所以系统层面必须有一个完整的 CUDA Toolkit。我这里选择安装 CUDA 11.1.1，下载地址和安装命令如下：

wget https://developer.download.nvidia.com/compute/cuda/11.1.1/local_installers/cuda_11.1.1_455.32.00_linux.run chmod +x cuda_11.1.1_455.32.00_linux.run sudo sh cuda_11.1.1_455.32.00_linux.run --toolkit --silent --no-opengl-libs

安装时添加--toolkit参数，表示只安装编译器和开发库，不重复安装 NVIDIA 驱动；--no-opengl-libs可以避免和桌面的 OpenGL 库冲突。安装完成后，CUDA 会被放到/usr/local/cuda-11.1，然后把相关路径写入 bashrc：

echo 'export PATH=/usr/local/cuda-11.1/bin:$PATH' >> ~/.bashrc echo 'export LD_LIBRARY_PATH=/usr/local/cuda-11.1/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc source ~/.bashrc

验证一下：

nvcc --version

如果能输出版本号，系统 CUDA 环境就准备好了。

3.2 PyTorch 1.10.1+cu111 的安装方式

PyTorch 的安装必须用 PyTorch 官方提供的 cu111 预编译包，不能直接从默认 PyPI 源安装，否则装出来的是最新版或者 CPU 版本。推荐用 conda 创建环境后，在环境内部执行：

conda create -n isfusion python=3.8 -y conda activate isfusion pip install torch==1.10.1+cu111 torchvision==0.11.1+cu111 torchaudio==0.10.1 --extra-index-url https://download.pytorch.org/whl/cu111

这里有个重要细节：--extra-index-url https://download.pytorch.org/whl/cu111不是装饰，它会告诉 pip 去 PyTorch 官方索引里寻找带+cu111的包。如果只写pip install torch==1.10.1，pip 会从 PyPI 搜索一个叫torch的包，而 PyPI 上的 1.10.1 大概率是 CPU 版本，后面直接浪费你半天时间。

PyTorch 1.10.1 对应的 torchvision 版本必须是 0.11.1，torchaudio 必须是 0.10.1，这三个版本是官方锁定的组合，不能混搭。装完先跑一条最关键的验证命令：

python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

看到1.10.1+cu111 True就说明 PyTorch 和 GPU 成功搭上线了。

3.3 使用 conda 隔离 Python 环境

我没有把 Python 依赖直接装在系统 python3 里，而是用了 Miniconda 来隔离。无论是 Anaconda 还是 Miniconda，核心价值都一样：避免不同项目之间因为包版本不同而互相打架。IS-Fusion 这类源码项目，很可能同时需要 numpy、open3d、opencv 等依赖，如果直接装在系统环境里，升级系统 Python 包时很容易把环境弄崩。

装 Miniconda：

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh source ~/.bashrc

创建环境时，我用了 Python 3.8，而不是最新版。原因很简单，PyTorch 1.10.1 时代官方支持的 Python 版本最高到 3.9，而 3.8 是当时生态最稳的版本，许多基于 PyTorch 的旧项目对 3.8 的兼容性都验证过。如果你的电脑上已经存在了别的 conda 环境，不要偷懒直接conda activate base，务必新建独立环境，后面一旦依赖崩溃，删除重建是最快的恢复方案。

提示：我个人习惯在项目目录里放一个requirements-lock.txt，把完整的 pip 依赖版本列出来，方便完全复现实验环境。人为控制版本，比依赖项目 README 里的“最新版”靠谱得多。

4. IS-Fusion 依赖编译：CUDA 扩展是最容易翻车的地方

4.1 编译前必设的环境变量和工具链检查

IS-Fusion 项目里通常会有几个需要从源码编译的 CUDA 扩展，常见的就是 tiny-cuda-nn 这类高性能算子库。这些扩展既没有现成的 pip wheel，也无法直接用pip install从网上下载编译好的包，必须依靠你本机的 nvcc 编译器现场构建。

编译前先确认以下环境变量，确保 CUDA 工具链能被正确找到：

export CUDA_HOME=/usr/local/cuda-11.1 export PATH=/usr/local/cuda-11.1/bin:$PATH export LD_LIBRARY_PATH=/usr/local/cuda-11.1/lib64:$LD_LIBRARY_PATH nvcc --version

然后把这几行也写进~/.bashrc，防止每次开新终端都要手动 export。接下来，最关键的变量是TORCH_CUDA_ARCH_LIST，它告诉编译器要为哪些 GPU 架构生成算子。如果设置错误，编译会报类似Unsupported gpu architecture的错误，或者编译成功后在运行时提示算子不支持当前设备。

根据你自己的显卡架构来设置：

export TORCH_CUDA_ARCH_LIST="6.1;7.0;7.5;8.6"

这段的意思是同时编译支持 GTX 10 系、RTX 20 系、RTX 30 系的算子，编译时间会长一些，但兼容性最好。如果你确定只用一张卡，比如 RTX 3090，可以把范围缩到"8.6"，能明显加快编译速度。注意，如果项目里的 CMakeLists 写死了sm_86之类架构，而你设置的范围不包括它，会直接编译失败，所以不要盲目追求“越小越好”。

4.2 CUDA 扩展编译常见报错

我在编译过程中遇到的第一个高频报错是：

fatal error: cuda_runtime.h: No such file or directory

看到这个先别慌，它基本可以断定是CUDA_HOME没设置，或者设置指向了不存在的路径。在编译进程的环境变量里，CUDA_HOME是扩展构建脚本用来定位头文件的基准路径。我见过有人把CUDA_HOME设置成/usr/local/cuda，但这个软链接在安装 11.1 时可能并不存在，或者指向了其他版本，这种情况需要检查一下：

ls -l /usr/local/

如果没有/usr/local/cuda-11.1或者/usr/local/cuda指向不对，重新执行 CUDA Toolkit 安装时使用的--prefix或者手动创建软链接即可。注意，不要只设置PATH不设置LD_LIBRARY_PATH，否则编译阶段能过，运行时还会在加载动态库这一步继续报错。

第二个常见报错是：

nvcc fatal : Unsupported gpu architecture 'compute_90'

这条通常意味着编译脚本检测到的 GPU 架构太新，而你安装的 CUDA 11.1 并不认识。CUDA 11.1 发布于 2021 年前后，对 RTX 40 系这种新卡支持不完善。如果手头是 RTX 4090，最合理的解决方式是设置TORCH_CUDA_ARCH_LIST="8.9"，但需要提前确认 CUDA 11.1 是否支持compute_89/sm_89。如果你没有合适的硬件，建议找个旧一点的 GPU，或者考虑更换整个项目的 CUDA 环境，而不是和编译器硬刚。

4.3 运行时报错：“libXXX not found”怎么定位

编译扩展这一关过了之后，运行阶段也会遇到动态库找不到的问题，最常见的就是：

ImportError: libcudnn.so.8: cannot open shared object file: No such file or directory

这是因为某些扩展在链接阶段显式依赖了 cuDNN，而 PyTorch wheel 自带的 cuDNN 并不一定在系统库搜索路径中。解决方式是到 NVIDIA Developer 网站下载对应 CUDA 11.1 的 cuDNN 8.2 版本，解压后把lib64下的文件拷贝到系统库目录：

sudo cp cudnn-linux-x86_64-8.2.x.x/lib64/* /usr/local/cuda-11.1/lib64/ sudo ldconfig

如果不想手动下载，也可以试试从 conda 安装 cudnn：

conda install -c conda-forge cudnn=8.2

然后把 conda 环境的 lib 目录加入LD_LIBRARY_PATH。这个方案胜在方便，但要注意 conda 的 cudnn 版本不能和 PyTorch 内部使用的 cuDNN 版本冲突，如果torch.cuda.is_available()为 True 但运行扩展时崩溃，大概率就是这里出现了版本冲突。

5. 环境验证与常见问题速查

5.1 一条命令确认 PyTorch 是否识别 GPU

验证环境是否正常，不要一上来就猛跑完整 Demo，先用最小命令确认关键点：

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"

输出应该是：

1.10.1+cu111 True NVIDIA GeForce RTX 3090

如果torch.cuda.is_available()返回 False，可能性只有三种：驱动没装好、PyTorch 装成了 CPU 版本、或者 nouveau 还在占用显卡。依次排查即可。

接下来再验证关键扩展库能否正常导入：

python -c "import open3d; print(open3d.__version__)" python -c "import cv2; print(cv2.__version__)"

如果 Open3D 报错，大概率是 NumPy 版本问题。PyTorch 1.10.1 对 NumPy 的兼容范围是numpy<1.24，而新环境默认可能会装 1.26 甚至更高。遇到类似module 'numpy' has no attribute 'float'这类错误时，执行：

pip install "numpy<1.24"

我没有在安装命令里把 numpy 固定为numpy==1.21，但只要你后面不出兼容性问题，建议装上numpy==1.21.6，这是 PyTorch 1.10.x 时代最常见的搭配。

5.2 常见问题速查表

下面这堆问题，都是我实际部署时碰到或者帮人排查过的高频问题，整理成速查表，方便你遇到报错时直接对照。

第一列就是报错原文或者现象，第二列是成因，第三列是处理方式。如果你遇到的报错不在表格里，还有一个通用排查方法：把ImportError后面的.so文件名复制到搜索引擎里搜一遍，通常立刻能定位到是哪个系统库缺失。

5.3 给新手的最终建议：先跑内置 Demo，别直接上自己的数据

环境配置好之后，建议先跑项目自带 Demo，而不要第一时间用自己的数据。原因很简单，Demo 数据经过项目作者验证，输入格式、标定文件、相机参数都是齐全的，能快速暴露环境剩余的问题。如果 Demo 能正常跑出结果，说明环境基本没问题，这时候再换成自己的数据，遇到问题就可以判断是环境问题还是数据问题。

如果你在运行 Demo 时看到类似这样一段信息：

Loading configuration from configs/demo.yaml Creating model with device: cuda:0

说明 CUDA 已经被正确调用，项目正式进入可用状态。此时可以观察显存占用和帧率消耗，判断硬件是否能支撑后续实验。

最后再补充几句实在话

这套环境我前后折腾了差不多两天，最后复盘发现，绝大多数时间都耗在了版本冲突和手动编译上，IS-Fusion 项目本身的代码反而没出什么幺蛾子。建议你遇到奇怪报错时，先检查几个最容易出错的位置：驱动是否生效、CUDA_HOME 是否指对路径、PyTorch 是否装成 CPU 版、NumPy 是不是过新。这四个位置能覆盖八成问题。

还有一个我自己的小习惯：每完成一个步骤，就拍个屏幕或者把输出存到日志文件里。尤其是nvcc --version和python -c "import torch; print(torch.__version__, torch.cuda.is_available())"这些关键输出，后面排错时翻出来看，一眼就能定位是哪一步开始跑偏。环境部署这种活，最怕的不是问题多，而是问题出现了你却不知道它是从哪个环节冒出来的。