企业官网建设流程全解析

先说个段子：有人高高兴兴把华为Atlas 300I Pro（model 3010）推理卡插进工作站的PCIe插槽，装好系统，照着官网教程一路操作，结果第一步就卡住了——官网支持列表里明明白白写着Ubuntu 18.04。心里不服？换上20.04再试，编译报错一个接一个，最后老老实实重装系统。这块卡到底为什么非要用18.04？20.04到底差在哪？我把安装前后的完整过程、踩过的坑、以及官方文档没写透的那些细节，一次性说清楚。

这篇内容适合两类人：一类是刚拿到Atlas 300I Pro准备做AI推理部署的工程师，另一类是已经被驱动折腾到怀疑人生、正在纠结“要不要为了一个驱动重装系统”的朋友。看完你应该能少走不少弯路。

1. 先搞清楚ATLAS 300I Pro model 3010到底是什么卡

1.1 型号定位：不是游戏卡，也不是通用计算卡

华为Atlas 300I Pro（型号3010）是一张纯推理卡，用的是昇腾310处理器，设计目标很明确：把训练好的模型跑起来，做视频分析、图像分类、OCR、推荐系统之类的线上推理服务。官方标称INT8算力在百TOPS级别，这个数字放在2020年前后发布的推理卡里属于优秀水平。它的外形是半高半长，功耗也不算离谱，PCIe插槽供电就能带起来，不需要外接供电线，这点对服务器和台式机都很友好。

但要注意，它和NVIDIA的T4、A10这类卡定位不太一样。T4既能做推理也能做轻量训练，Atlas 300I Pro从硬件设计到软件栈都偏向推理场景。你拿它来跑训练，可能用起来很别扭；你拿它来做高并发推理，在配套软件到位的情况下，性价比确实能打。

1.2 驱动安装的逻辑：和NVIDIA卡天差地别

用惯了NVIDIA卡的同学，拿到这张卡的第一反应是去官网下个.run驱动，然后像装NVIDIA驱动一样装完、nvidia-smi验证，完事。但昇腾卡的驱动安装逻辑不太一样，它不只是“装一个驱动程序”，而是包含整个CANN（Compute Architecture for Neural Networks）软件栈。驱动、固件、算子库、运行时环境是几个独立又互相依赖的组件。

还有个容易混淆的点：昇腾的“驱动”和“固件”是分开的两个包。固件负责硬件底层初始化，驱动负责操作系统和硬件之间的通信。后来官方把驱动包和固件包合并成一个“驱动固件包”，安装驱动的时候会自动检查和升级固件，但老版本的安装流程里还是分开的。如果你拿到的安装包是分体版，顺序一定不能乱：先装固件，再装驱动。顺序反了，轻则报错，重则设备状态异常。

另外一个和NVIDIA卡很不一样的地方：昇腾卡安装完驱动后，默认会创建一个名为HwHiAiUser的系统用户，很多运行进程（比如算子编译、推理服务）都需要在这个用户下跑，或者至少要让这个用户有权限访问设备。装驱动时不留意这个用户，后面跑样例代码时会莫名其妙地遇到权限问题。

2. 为什么官网只认Ubuntu 18.04：三个真实原因

2.1 看官网支持列表到底写了什么

打开昇腾社区的软件包下载页面，选择Atlas 300I Pro（model 3010）对应的CANN版本，支持的操作系统列表里，x86架构下Linux通常会列出Ubuntu 18.04、20.04等选项，但如果你仔细看驱动和固件包的适配列表，很多版本对Ubuntu的支持就只写了18.04。这个“只写18.04”不是官网懒，背后是实打实的技术原因。

CANN软件栈的Linux支持策略是“选一个主版本做完整验证，其他版本选择性适配”。在昇腾310那一代产品周期里，Ubuntu 18.04就是那个被选中的主验证版本。20.04虽然也属于Ubuntu生态，但内核、GCC、glibc、OpenSSL这些底层组件版本都变了，华为的验证矩阵没有覆盖到，所以官方不敢在支持列表里写“支持20.04”。

2.2 20.04装不上/装完跑不动的三个技术差异

第一个差异，也是最直接的：内核版本。Ubuntu 18.04默认内核是4.15系列，20.04是5.4系列（后续小版本可能升到5.6、5.8）。昇腾驱动的内核模块在发布前是针对特定内核版本编译和验证的，内核模块对内核版本极其敏感——不是“差不多就行”，而是接口、数据结构和编译标志都得对得上。在20.04上装18.04时代的驱动，最常见的报错就是内核模块编译失败，或者编译通过但加载时报Unknown symbol。我见过有人在20.04上用DKMS强行编译旧版驱动，折腾半天驱动模块加载了，但一跑推理就死机。

第二个差异：GCC工具链和glibc版本。18.04自带GCC 7.5和glibc 2.27，20.04自带GCC 9.4和glibc 2.31。昇腾的很多二进制组件（尤其是CANN工具链里的算子编译器和Runtime库）是在老版本GCC/glibc环境下编译的，拿到新系统上可能出现GLIBC_2.29 not found这类经典报错。反过来，驱动模块编译时如果用GCC 9去编，又可能因为编译器的检查规则更严格或者宏定义变化，直接编译失败。说白了，版本跨度太大，两头都容易出问题。

第三个差异：OpenSSL和其他依赖库。华为的驱动和固件安装脚本会调用OpenSSL、libxml2等基础库做签名校验和配置解析。20.04的OpenSSL是1.1.1系列，默认安全级别更高，某些旧版安装包的签名算法在新OpenSSL下会被拒绝，导致安装程序压根没法启动。这个报错很迷惑，经常显示成Failed to verify the integrity of the package，看起来像包坏了，其实是系统环境太新。

2.3 是不是真的打死不能用20.04

也不能把话说死。CANN版本越新，对20.04的支持就越多，到CANN 6.x甚至7.x时代，官方已经正式支持Ubuntu 20.04和22.04了。但问题在于，Atlas 300I Pro model 3010对应的很多稳定版CANN是2021-2023年发布的，那个时间段的CANN对20.04的支持并不可靠。如果非要强行上20.04，你可能需要解决内核模块编译、GCC降级、glibc兼容性、OpenSSL策略等一系列问题，而且是“今天解决一个，明天又冒出一个”的连环坑。我个人的建议是：除非你有必须用20.04的硬性理由，否则老老实实装18.04，别和自己的时间过不去。

这里也回答标题里“别被官网骗了”的意思：官网支持列表看着像是一句话的事，但背后的含义是整个软件栈的适配边界。你非要在边界外操作，不是不行，但风险没人替你兜底，官方工单大概率也会让你换系统。

3. 实操安装：从零到npu-smi info

3.1 安装前要准备的材料

安装前把下面这些搞清楚，能省很多事：

要特别强调的是，下载软件包时一定要选对“型号”和“操作系统”。昇腾社区的下载页面支持按硬件型号筛选，选Atlas 300I Pro（型号3010），再选Ubuntu 18.04 x86_64，出来的版本才能对上。如果选错成Atlas 300I（非Pro版）或者选了aarch64，安装时会直接报错。

3.2 系统环境检查与配置

拿到Ubuntu 18.04后，别急着装驱动，先做三件事。

第一，更新系统并安装基础编译工具：

sudo apt update sudo apt upgrade -y sudo apt install -y gcc make dkms linux-headers-$(uname -r)

这里装DKMS和linux-headers很关键。昇腾驱动安装时会动态编译内核模块，没有内核头文件，编译直接失败。很多人在这一步报错，然后开始怀疑是不是卡坏了，其实是没装headers。

第二，检查是否已经存在HwHiAiUser用户：

id HwHiAiUser

如果没有输出，就手动创建：

sudo useradd -m -d /home/HwHiAiUser -s /bin/bash HwHiAiUser sudo passwd HwHiAiUser

设置一个密码，后面跑推理服务时会用到。

第三，检查BIOS里PCIe设置。如果这台机器原本插着NVIDIA卡，BIOS里可能启用了Above 4G Decoding之类的选项，这些选项对昇腾卡一般没影响，但Resizable BAR（可调整基地址寄存器）功能如果开启，个别主板会和昇腾卡的驱动冲突，建议先关掉。另外，如果服务器有多个PCIe x16插槽，尽量把卡插在直连CPU的插槽上（一般是第一根或第二根），别插南桥扩展出来的插槽，否则性能损失明显且容易识别异常。

3.3 固件与驱动的完整安装步骤

把从昇腾社区下载的安装包放到同一个目录下，假设目录是/home/user/ascend。先看下文件权限，安装包一般需要执行权限：

cd /home/user/ascend chmod +x *.run

如果你下载的是分体版（驱动包和固件包分开），按以下顺序安装。先装固件：

sudo ./Ascend-cann-firmware_<版本号>_linux-x86_64.run --full --install-for-all

其中--full表示全量安装，--install-for-all表示安装到系统全局路径（/usr/local/Ascend），而不是当前用户目录。这一步不需要重启，但会把固件写入设备ROM和系统固件目录。

接着装驱动：

sudo ./Ascend-cann-driver_<版本号>_linux-x86_64.run --full --install-for-all

安装过程中终端会打印一堆日志，最后一行如果没有出现driver install success之类的提示，而是报错，先不要慌，去看日志文件：

tail -50 /var/log/ascend_install.log

日志里有具体的失败原因，常见的有内核头文件缺失、GCC版本不对、Python版本不对等。把前面的依赖问题解决了再重新安装。

如果你下载的是“驱动固件合一包”（安装包文件名里同时带driver和firmware字样），安装顺序就简单了，直接：

sudo ./Ascend-cann-driver_<版本号>_linux-x86_64.run --full --install-for-all

脚本会自动先升级固件，再安装驱动。这个方案是我现在推荐的，因为它省去了手动匹配固件和驱动版本的麻烦。

安装完成后，重启系统：

sudo reboot

重启后检查设备状态：

npu-smi info

如果看到类似下面这样的输出，说明驱动和固件都正常工作：

+-------------------+-----------------+------------------------------------------------------+ | NPU Name | Health | Power(W) Temp(C) Hugepages-Usage(page) | | Chip | Bus-Id | AICore(%) Memory-Usage(MB) HBM-Usage(MB) | +===================+=================+======================================================+ | 310P3 | OK | ...

如果提示npu-smi: command not found，说明驱动没装上或者环境变量没配置。npu-smi工具一般在/usr/local/Ascend/driver/tools/目录下，可以手动调用：

/usr/local/Ascend/driver/tools/npu-smi info

如果能输出，就把它加进PATH：

echo 'export PATH=/usr/local/Ascend/driver/tools:$PATH' >> ~/.bashrc source ~/.bashrc

3.4 环境变量与CANN工具链安装

驱动装好了，只完成了一半。想让这张卡真正跑起推理，还需要装CANN Toolkit。

同样从昇腾社区下载Toolkit包（文件名类似Ascend-cann-toolkit_<版本号>_linux-x86_64.run），执行：

sudo ./Ascend-cann-toolkit_<版本号>_linux-x86_64.run --install

注意，这里我没加--install-for-all，因为Toolkit也支持安装到当前用户目录。对于单机单卡的个人工作站来说，安装到当前用户目录其实更省心，卸载时直接删目录就行。但如果你是在多人共用服务器上配置，建议用--install-for-all，让所有用户都能使用。

安装完成后，Toolkit默认会放在/usr/local/Ascend/ascend-toolkit/目录下。需要设置环境变量：

source /usr/local/Ascend/ascend-toolkit/set_env.sh

如果要永久生效，把它写入~/.bashrc：

echo 'source /usr/local/Ascend/ascend-toolkit/set_env.sh' >> ~/.bashrc source ~/.bashrc

验证Toolkit是否可用，可以跑一个Python绑定的示例：

python3 -c "from te import tvm; print('TE OK')"

正常情况下会输出TE OK。TE（Tensor Engine）是CANN的算子开发引擎，能跑通说明Runtime和算子库都正常了。

到这一步，从驱动到工具链的安装链路就完整了。接下来可以跑一下昇腾社区提供的样例工程（比如ResNet-50推理），验证整条软硬件链路端到端跑通。

4. 我踩过的坑：常见问题与排查实录

4.1 问题速查表

下面这些坑，是我自己或者周围朋友在实际部署中真实遇到的，按出现频率排序：

4.2 最容易被忽视的几个细节

第一个细节：Ubuntu小版本别太老。我之前用过Ubuntu 18.04.2，当时的内核是4.15.0-20，昇腾驱动的DKMS编译在那个内核版本下能过，但加载时总会报Invalid module format。后来升级到18.04.5，内核换到4.15.0-176左右，问题就消失了。如果你用的是老镜像，先跑sudo apt upgrade把内核更新到较新的4.15小版本，再做驱动安装。

第二个细节：驱动包和CANN Toolkit版本要匹配。曾经下载了最新版Toolkit，却配了一个半年前发布的驱动包，结果在算子编译阶段频繁报ascend_install.info not found。后来把驱动升级到和Toolkit同期的版本，问题消失。以后下载软件包时，注意看昇腾社区每个版本的配套关系说明，或者在安装前把两个包的版本号发到CANN社区工单里确认。

第三个细节：虚拟机里装驱动需要网卡直通。如果你是在VMware或KVM虚拟机里给Atlas 300I Pro装驱动，要先确认虚拟机能不能看到这个PCIe设备。VMware默认不直通PCIe设备，需要在虚拟机设置里把Atlas 300I Pro对应的PCI设备添加进去（即PCI直通），而且要启用“内存映射I/O”（MMIO）。如果虚拟机配置不对，驱动装得再认真，设备也不会出现。这个坑在测试环境里特别常见。

第四个细节：安装日志才是真正的老师。昇腾的安装脚本很友好，会把日志写到/var/log/ascend_install.log，但很多人一看终端输出没有success就慌了，直接论坛发帖求助。实际上日志里写得清清楚楚。遇到报错先执行：

cat /var/log/ascend_install.log | tail -100

80%的问题在日志里能找到明确原因。

5. 一点关于“为什么非要较真系统版本”的个人体会

装上Ubuntu 18.04之后，你会发现自己回到了一个比较“古早”的软件环境：GCC 7.5、内核4.15、OpenSSL 1.1.1。然后你就会明白，为什么昇腾社区的很多教程都在强调“请使用Ubuntu 18.04”——因为整个昇腾软件栈在18.04上经历了几年的测试、修复和优化，各种问题都在这个版本上被磨平了。

回想我自己第一次装Atlas 300I Pro的时候，也是不信邪，偏要在20.04上折腾。结果花了两天时间，解决了内核模块编译错误，又解决了GCC降级问题，最后死在算子编译阶段——CANN的编译器直接从glibc层面拒绝执行。后来一个朋友一句话点醒我：AI卡是用来跑模型的，不是用来折腾驱动编译的。系统版本稳固、工具链稳定，比什么都重要。

如果你需要在生产环境部署多张Atlas 300I Pro，我的建议是：把Ubuntu 18.04做成镜像模板，通过PXE批量部署，然后把驱动和CANN工具链的安装过程写成脚本固化下来。这样每台机器装完系统后，执行一个脚本，十几分钟就能把环境拉起来。这也是我在多个现场项目里验证过的做法。

最后分享一个小技巧：如果你拿到一块已经装过其他版本固件的Atlas 300I Pro（比如二手卡或者同事用过的卡），安装驱动固件包之前，先用/usr/local/Ascend/driver/tools/upgrade-tool --device_index 0 --software_version（具体参数以当前版本工具为准）查看一下板上固件版本，然后到华为昇腾社区查一下当前版本驱动对固件的最低要求。固件版本太老的话，驱动装完可能识别正常，但跑推理时会出现莫名其妙的超时或报错。先把固件升上去，再装驱动，能省掉后续大量的排查时间。