裸金属适配实战：网卡、存储与GPU三类芯片排障经验沉淀为AI Skill

1. 从一次深夜排障说起为什么裸金属适配这么难去年冬天一个做异构算力调度的朋友半夜给我打电话说他们新到的一批机器系统装完网卡拉不起来换了好几个内核版本驱动要么编译不过要么加载之后直接 panic。更离谱的是同一批机器里有两台是好的剩下六台怎么都不行。他当时的第一反应是是不是系统镜像有问题第二反应是是不是硬件坏了折腾到凌晨三点才想起来问我。我让他先把lspci -nn和dmesg | grep -i error的输出发过来。看完之后基本就清楚了这批机器混插了三家不同厂商的网卡其中一家的驱动需要额外固件另一家的驱动在某个内核版本之后改了 API还有一家的设备在 IOMMU 分组上跟别的设备绑在了一起导致直通配置怎么写都不对。三个问题叠在一起表现出来就是驱动装不上、透传总报错这一种症状。这件事后来成了我做裸金属适配的一个典型样本。裸金属环境跟虚拟机、容器最大的区别在于你没有中间层帮你兜底。硬件就是硬件内核就是内核中间任何一个环节对不上报错就是硬报错没有重启一下试试的余地。而驱动装不上和透传总报错这两类问题几乎覆盖了裸金属适配 80% 的排障场景。这篇文章想聊的就是怎么把这类经验沉淀成一个可复用的 AI Skill。标题里提到的三类芯片指的是我在实际项目里接触最多的三类网卡芯片、存储控制器芯片、以及加速卡/GPU 芯片。这三类的适配逻辑差异很大但排障思路有共通之处。我会把每一类的核心坑点、排查路径、以及怎么把这些经验写进一个 Skill 里完整地讲一遍。适合正在做裸金属交付、异构算力调度、或者想把自己排障经验产品化的同学参考。2. 三类芯片的适配差异先搞清楚你在跟谁打交道2.1 网卡芯片固件、内核 API、IOMMU 三座大山网卡是裸金属适配里最容易出问题的一类没有之一。原因很简单网卡驱动是内核里更新最频繁、厂商差异最大的模块之一。我接触过的网卡芯片大致可以分三档第一档是主流服务器网卡驱动基本都在内核主线里装完系统就能用偶尔需要更新一下固件。这类问题最少但也不是没有——我遇到过某型号网卡在特定内核版本下驱动加载正常但链路协商不上最后发现是固件版本太老跟交换机侧的协商参数对不上。第二档是需要额外编译的网卡驱动不在主线或者版本落后。这类问题的典型症状是modprobe报 Unknown symbol本质是驱动编译时用的内核头文件和当前运行内核不匹配。解决办法听起来简单——重新编译——但实际操作里你得先确认当前内核的uname -r、/lib/modules/$(uname -r)/build指向是否正确、gcc版本是否兼容任何一个环节错了都编译不过。第三档是最麻烦的驱动能装但一开直通就报错。这类问题往往跟 IOMMU 分组有关。IOMMU 分组的原则是同一个分组里的设备要么全部直通要么全部不直通而分组是按 PCIe 拓扑来的。如果网卡和某个不该直通的设备比如板载的 USB 控制器分在了一组你就得用pcie_acs_override之类的参数强行拆分分组但这又会带来安全性和稳定性的权衡。提示判断 IOMMU 分组问题的最快方法是ls -l /sys/kernel/iommu_groups/看目标设备所在分组里还有没有别的设备。如果有基本就是分组问题。2.2 存储控制器芯片RAID 模式与直通模式的切换陷阱存储控制器的问题跟网卡不太一样。网卡是能不能用存储是用哪种模式用。现在主流服务器上的存储控制器基本都支持两种模式RAID 模式和 HBA/直通模式。这两种模式在固件层面切换切换之后操作系统看到的设备完全不一样。我踩过的最大的坑是在 RAID 模式下装好了系统然后想切到直通模式跑分布式存储结果一切换系统起不来了——因为原来的系统盘在 RAID 模式下是一个逻辑卷切到直通模式之后变成了物理盘引导记录对不上。这个坑的正确做法是在装机之前就确定好存储模式装完再切基本等于重装。另一个常见问题是驱动版本。存储控制器的驱动往往跟固件强绑定固件升级了驱动不升级或者反过来都可能出问题。我遇到过某型号 RAID 卡固件升到最新之后旧版驱动直接认不到卡lspci能看到设备但/dev下没有对应节点。这种情况只能回退固件或者升级驱动没有第三条路。2.3 加速卡/GPU 芯片驱动、固件、容器运行时三层依赖加速卡的适配复杂度是三类里最高的因为它涉及三层内核驱动、用户态驱动、以及容器运行时。任何一层版本对不上表现出来都可能是驱动装不上。内核驱动层的问题通常是编译和签名。有些加速卡的驱动需要跟内核版本严格匹配内核升级之后必须重新编译。如果开了 Secure Boot还得给驱动签名否则加载会被拒绝。用户态驱动层的问题通常是版本兼容。CUDA、ROCm 这类框架对驱动版本有明确要求装错了版本nvidia-smi或者rocm-smi直接报错。容器运行时层的问题最隐蔽。裸金属上跑容器需要把加速卡设备、驱动库、以及运行时 hook 都配好。少配一个容器里就是看不到卡。我见过最离谱的一次是宿主机上nvidia-smi正常容器里死活看不到最后发现是nvidia-container-runtime的版本跟驱动版本不匹配。芯片类型核心难点典型症状排查入口网卡固件、内核 API、IOMMU 分组驱动加载失败、直通报错lspci -nn、dmesg、iommu_groups存储控制器模式切换、驱动固件绑定设备不识别、系统起不来固件界面、lspci、/dev节点加速卡三层依赖、版本匹配驱动装不上、容器看不到卡nvidia-smi、容器运行时配置3. 把排障经验写成 AI Skill结构设计与核心思路3.1 为什么是 Skill而不是文档传统的排障经验沉淀方式是写文档。但文档有个致命问题它是静态的。你写的时候覆盖了当时遇到的所有情况但下次遇到新问题文档里没有你还是得从头查。而且文档的检索效率很低一个新人拿到报错信息不知道该翻哪一页。Skill 的思路不一样。Skill 本质上是把排障决策树结构化让 AI 能够根据输入的症状自动走对应的分支。你不需要知道该翻哪一页你只需要把报错信息丢进去Skill 会引导你一步步缩小范围。我设计这个 Skill 的核心思路是以症状为入口以芯片类型为分类以排查动作为节点。具体来说Skill 的输入是症状描述 环境信息输出是排查步骤 判断依据 解决方案。3.2 Skill 的整体结构整个 Skill 分成四个模块第一个模块是环境采集。在开始排查之前先让用户跑一组命令把关键信息收集齐。这组命令包括lspci -nn、uname -r、dmesg | tail -100、lsmod、以及/sys/kernel/iommu_groups/的列表。这些信息是后续所有判断的基础缺一个都可能导致误判。第二个模块是症状分类。根据用户描述的症状把问题归到驱动装不上、透传报错、设备不识别、性能异常这几类里。每一类对应不同的排查路径。第三个模块是分支排查。这是 Skill 的核心。以驱动装不上为例分支逻辑是这样的先看lspci能不能看到设备看不到就是硬件或 BIOS 层面的问题看得到但lsmod里没有驱动就是驱动没加载驱动加载了但报错就看dmesg里的具体错误码根据错误码走对应的解决方案。第四个模块是方案输出。根据排查结果输出具体的操作步骤。这一步要尽量具体比如重新编译驱动要给出完整的编译命令调整 IOMMU 分组要给出具体的 grub 参数。3.3 三类芯片在 Skill 里的差异化处理虽然整体结构一样但三类芯片在具体分支上差异很大。网卡的分支重点在固件版本和 IOMMU 分组。Skill 里需要内置一个常见网卡型号的固件版本对照表以及 IOMMU 分组的判断逻辑。存储控制器的分支重点在模式判断。Skill 需要先确认当前是 RAID 模式还是直通模式然后根据模式走不同的排查路径。如果是模式切换导致的问题Skill 要能识别出来并给出回退模式或重装系统的建议。加速卡的分支重点在版本矩阵。Skill 需要内置驱动版本、框架版本、容器运行时版本的兼容矩阵根据用户当前的版本组合判断是否匹配。提示Skill 里的版本矩阵不需要覆盖所有版本覆盖最近两三个大版本就够了。太老的版本组合实际项目里基本不会遇到维护成本不划算。4. 实操从零搭建一个裸金属适配 Skill4.1 环境采集脚本的编写Skill 的第一步是环境采集。我写了一个 shell 脚本把需要的信息一次性收集齐输出成一个结构化的文本方便后续解析。#!/bin/bash # baremetal-env-collect.sh # 裸金属环境信息采集脚本 echo 系统信息 uname -a cat /etc/os-release | head -5 echo PCI 设备列表 lspci -nn echo 已加载模块 lsmod echo IOMMU 分组 for g in /sys/kernel/iommu_groups/*/devices/*; do echo Group $(echo $g | cut -d/ -f5): $(lspci -nns $(basename $g)) done echo 内核日志最近 200 行 dmesg | tail -200 echo 驱动相关错误 dmesg | grep -iE error|fail|unknown symbol|firmware | tail -50这个脚本的关键在于输出结构化。每一段都有明确的分隔符方便后续用正则解析。IOMMU 分组那段尤其重要它把每个分组里的设备都列出来了一眼就能看出有没有设备被错误地分到一组。4.2 症状分类的判断逻辑环境信息收集完之后进入症状分类。这一步的判断逻辑我写成了伪代码方便在 Skill 里实现输入用户描述的症状 环境信息 if 驱动装不上 in 症状: if 设备不在 lspci 输出中: return 硬件或 BIOS 层面问题 elif 设备在 lspci 但 lsmod 无对应模块: return 驱动未加载 elif dmesg 有 Unknown symbol: return 驱动与内核版本不匹配 elif dmesg 有 firmware 相关错误: return 固件缺失或版本不匹配 else: return 驱动加载失败需看具体错误码 elif 透传报错 in 症状: if IOMMU 分组中目标设备与其他设备同组: return IOMMU 分组问题 elif dmesg 有 DMAR 或 IOMMU 相关错误: return IOMMU 配置问题 else: return 透传配置问题需检查虚拟机配置这个逻辑不复杂但覆盖了大部分常见情况。实际用的时候Skill 会根据用户提供的信息自动走对应的分支。4.3 分支排查的具体实现以驱动与内核版本不匹配这个分支为例Skill 的输出应该是这样的第一步确认当前内核版本和驱动编译时用的内核版本uname -r modinfo 驱动名 | grep vermagic如果vermagic里的版本跟uname -r不一致就确认是版本不匹配。第二步重新编译驱动。以常见的网卡驱动为例# 安装内核头文件 apt install linux-headers-$(uname -r) # 进入驱动源码目录 cd /path/to/driver/source # 清理并重新编译 make clean make -j$(nproc) make install # 加载驱动 modprobe 驱动名第三步验证驱动加载lsmod | grep 驱动名 dmesg | tail -20如果lsmod里有驱动dmesg没有报错就说明驱动加载成功了。注意重新编译驱动之前一定要确认内核头文件版本跟当前运行内核一致。我见过太多次因为头文件版本不对编译出来的驱动加载时报 version magic 错误的情况。4.4 IOMMU 分组问题的处理IOMMU 分组问题是透传报错里最常见的一类。处理逻辑是这样的先确认分组情况ls -l /sys/kernel/iommu_groups/如果目标设备所在分组里有其他设备就需要拆分分组。拆分的方法是在 grub 里加pcie_acs_override参数# 编辑 grub 配置 vim /etc/default/grub # 在 GRUB_CMDLINE_LINUX 里添加 GRUB_CMDLINE_LINUX... pcie_acs_overridedownstream,multifunction # 更新 grub update-grub # 重启 reboot重启之后再检查分组如果目标设备已经单独成组就可以正常直通了。提示pcie_acs_override参数会降低 IOMMU 的隔离性只在必要时使用。如果设备本身支持 ACS优先在 BIOS 里开启 ACS而不是用这个参数强行拆分。5. 常见问题与排查技巧实录5.1 驱动装不上的五种典型情况在实际项目里驱动装不上这个症状背后至少有五种不同的原因。我把它们整理成了一个速查表症状可能原因排查命令解决方案lspci 看不到设备硬件未识别、BIOS 未开启lspci -nn、BIOS 设置检查插槽、开启 BIOS 选项设备在但无驱动模块驱动未编译或未加载lsmod、modprobe编译并加载驱动加载报 Unknown symbol内核版本不匹配modinfo、uname -r重新编译驱动加载报 firmware 错误固件缺失dmesg、/lib/firmware安装对应固件加载成功但设备不工作固件版本不匹配ethtool -i、厂商工具升级或回退固件这张表是我踩了无数次坑之后总结出来的基本上覆盖了 90% 的驱动装不上场景。实际用的时候按顺序排查就行。5.2 透传报错的三个隐藏坑透传报错比驱动问题更隐蔽因为报错信息往往不直接指向根因。我遇到过三个特别隐蔽的坑第一个坑是IOMMU 分组问题。前面已经讲过了这里补充一点有些主板默认的 IOMMU 分组非常粗一块网卡可能跟一堆设备分在一组。这种情况下除了pcie_acs_override还可以考虑换 PCIe 插槽。不同插槽的拓扑不一样换一个插槽可能就分到不同的组里了。第二个坑是中断重映射问题。有些老平台的中断重映射支持不完整直通之后中断送不到虚拟机里表现出来就是设备能识别但收不到数据。这个问题的排查方法是看/proc/interrupts里对应设备的中断计数有没有增长。如果没有基本就是中断重映射的问题。解决办法是在 grub 里加intremapon参数。第三个坑是设备复位问题。有些设备在直通之前需要复位如果驱动不支持复位直通就会失败。这个问题的典型症状是dmesg里有 Failed to reset device 之类的报错。解决办法是找支持复位的驱动版本或者用vfio-pci的reset参数。5.3 加速卡适配的版本矩阵加速卡的版本匹配是最容易出问题的环节。我整理了一个简化的版本矩阵覆盖了常见的组合驱动版本框架版本容器运行时版本兼容性5xxCUDA 11.xnvidia-container-runtime 3.x兼容5xxCUDA 12.xnvidia-container-runtime 3.x需驱动 5254xxCUDA 11.xnvidia-container-runtime 3.x兼容4xxCUDA 12.xnvidia-container-runtime 3.x不兼容这个矩阵的核心逻辑是驱动版本决定框架版本的上限容器运行时版本决定驱动版本的下限。装之前先确认这三个版本能省掉大量排查时间。注意容器运行时版本跟驱动版本的匹配关系经常被忽略。我见过好几次宿主机上驱动正常容器里看不到卡最后发现是容器运行时版本太老不支持新驱动的设备节点命名方式。5.4 独家避坑技巧最后分享几个我在实际项目里总结的避坑技巧都是文档里不会写的技巧一装机之前先跑一遍环境采集脚本。很多人是出了问题才去采集环境信息这时候往往已经错过了最佳排查时机。我的做法是装机完成之后立刻跑一遍采集脚本把基线信息存下来。后面出问题的时候跟基线对比差异点就是问题点。技巧二驱动编译用容器做不用宿主机。宿主机上编译驱动很容易把环境搞乱。我现在的做法是用一个跟目标内核版本一致的容器来编译编译完把.ko文件拷出来。这样既干净又可复现。技巧三IOMMU 分组问题优先换插槽其次改参数。pcie_acs_override参数虽然能解决问题但会降低隔离性。如果机器有空余插槽换一个插槽往往能直接解决分组问题而且没有副作用。技巧四加速卡适配先确认容器运行时再确认驱动。很多人一上来就折腾驱动其实容器运行时的问题更常见。先跑一个最简单的容器测试确认运行时没问题再去看驱动。技巧五把每次排障的过程记下来喂给 Skill。Skill 的价值在于积累。每次遇到新问题解决之后把排查路径补充到 Skill 里下次遇到类似问题就能直接命中。我现在的 Skill 里已经积累了上百个分支覆盖了大部分常见场景。6. 把 Skill 用起来从个人经验到团队资产6.1 Skill 的部署与调用Skill 写好之后部署方式取决于你用的平台。如果是自建的 AI 助手把 Skill 的内容作为系统提示词的一部分注入就行。如果是用现成的 Skill 平台按平台的格式要求打包上传。调用的时候用户只需要提供症状描述和环境信息Skill 会自动走排查流程。我一般建议用户在提问的时候把环境采集脚本的输出一起贴进来这样 Skill 的判断会更准确。6.2 持续迭代的方法Skill 不是写完就完了需要持续迭代。我的迭代方法是每次遇到 Skill 没覆盖到的问题解决之后立刻补充进去。补充的内容包括症状描述、排查路径、以及最终的解决方案。迭代的时候要注意一点不要把过于具体的案例直接写进去。比如某型号网卡在某个内核版本下的某个固件版本有问题这种太具体了换个环境就不适用。正确的做法是抽象成网卡固件版本不匹配这个通用分支然后在分支里举这个例子。6.3 团队协作中的注意事项如果 Skill 要在团队里共享有几个点需要注意第一环境采集脚本要统一。不同人用不同的脚本采集信息格式不一致Skill 解析起来会出问题。我们团队的做法是把采集脚本放在共享仓库里所有人用同一个版本。第二版本矩阵要定期更新。驱动、框架、容器运行时的版本更新很快矩阵不更新就会过时。我们团队是每个季度 review 一次把新版本加进去把太老的版本删掉。第三排障记录要脱敏。团队共享的排障记录里不能包含具体的客户信息、IP 地址、设备序列号这些。我们是在记录的时候就把这些信息替换成占位符。6.4 一个真实的迭代案例最后讲一个真实的迭代案例。有一次团队里一个同学遇到一个问题某型号加速卡在裸金属上驱动装好了nvidia-smi也正常但跑训练任务的时候报 CUDA error: unknown error。他排查了半天没找到原因最后把环境信息发给我。我看了一下发现他的驱动版本是 525CUDA 版本是 12.0容器运行时是 3.0。问题出在容器运行时版本太老不支持 CUDA 12.0 的设备节点。升级容器运行时到 3.5 之后问题解决。这个案例后来被我抽象成了一个分支驱动正常但容器内报错 → 检查容器运行时版本 → 对照版本矩阵。现在 Skill 里遇到类似症状会直接提示检查容器运行时版本省掉了大量排查时间。这个 Skill 到现在已经迭代了十几个版本覆盖了三类芯片的绝大部分常见问题。它最大的价值不是替代人而是把散落在各个人脑子里的经验变成了团队可以复用的资产。新人遇到问题先问 SkillSkill 解决不了的再找人。这样既降低了沟通成本也让老员工的经验能够沉淀下来。我个人在实际操作中的体会是裸金属适配这件事经验比技术更重要。技术文档到处都是但真正踩过坑、知道哪里会出问题的人不多。把这些经验结构化、产品化是让团队整体能力提升的最快路径。