Linux上DKMS驱动构建失败,怎样从内核头文件和编译日志定位原因?

发布人:A5数据发布时间:2026-10-29 11:14阅读量:111

DKMS 驱动构建失败时,不应先把问题归结为“服务启动失败”或直接重启服务器。应先确认失败发生在链路的哪一层:内核头文件是否对应当前目标内核,编译器和构建工具是否完整,驱动源码是否适配该内核版本,还是模块已经构建成功但加载、签名或服务启动阶段失败。最有价值的两个证据通常是 dkms status 的状态和对应目录下的 make.log。

实际排查可以沿着“目标内核 → 头文件 → 编译依赖 → 编译日志 → 模块加载 → 服务状态 → 端口监听”逐层推进。这样可以避免把 systemctl 里看到的服务失败,误认为是 DKMS 编译本身导致,也能区分“模块没有生成”“模块无法加载”和“服务启动后没有监听端口”这三类不同故障。

DKMS 构建链路涉及内核、编译工具和应用服务,承载这些服务的服务器资源也需要与业务负载相匹配。A5idc数据提供香港、美国、日本、韩国、中国台湾、新加坡和马来西亚等地区的物理服务器,涵盖 Xeon 与 AMD EPYC 平台、SSD 或 NVMe 存储及不同网络线路,可用于部署网站、业务后台、数据库和接口服务。对于多任务计算或数据密集型业务,也有相应的高配置与存储方案,为 Linux 服务运行和扩展提供硬件基础。

确认症状:构建失败发生在哪个阶段

先记录当前运行内核、系统架构和 DKMS 注册状态。下面命令只读取信息,不会修改系统:

uname -r
uname -m
dkms status

uname -r 的结果是后续判断的基准。例如当前内核可能是:

6.8.0-52-generic

而 dkms status 可能同时列出多个内核版本:

example-driver/2.4.1, 6.5.0-41-generic, x86_64: installed
example-driver/2.4.1, 6.8.0-52-generic, x86_64: added

这个结果表示驱动曾经安装到旧内核,但当前内核只完成了注册,还没有完成构建或安装。此时即使源码本身没有问题,当前内核也可能无法加载对应模块。

可以先把故障现象分成四类:

观察到的现象更可能发生的阶段首要检查位置
dkms build 直接失败,没有生成 .ko 文件头文件、编译工具、源码兼容性或权限/var/lib/dkms/.../make.log
DKMS 显示已构建,但 modprobe 失败模块路径、依赖、签名或内核配置modinfo、dmesg、modprobe
模块能加载,但服务启动失败服务依赖、设备节点、配置或权限systemctl status、journalctl -u
服务显示运行,但端口未监听应用配置、监听地址、端口占用或服务实际未完成初始化ss、服务日志

如果服务本身已经处于失败状态,先查看状态和本次启动日志:

sudo systemctl status <service-name> --no-pager -l
sudo journalctl -u <service-name> -b --no-pager

<service-name> 需要替换成实际服务名。此处的输出只能说明服务启动阶段发生了什么,不能代替 DKMS 编译日志。若服务依赖某个内核设备,而模块尚未成功加载,日志中常见的表现是设备文件不存在、初始化接口失败或权限被拒绝。

建立原因树:从内核到应用逐层判断

一条典型链路如下:

驱动源码或软件包
    ↓
DKMS 调用编译器和内核构建目录
    ↓
生成 .ko 内核模块
    ↓
安装到 /lib/modules/<kernel>/
    ↓
depmod 生成依赖索引
    ↓
modprobe 加载模块
    ↓
设备节点或内核接口出现
    ↓
systemd 服务初始化
    ↓
应用监听端口或提供其他功能

其中任意一层失败,后续层都可能表现为启动失败。问题树可以分为以下几条分支:

建立原因树:从内核到应用逐层判断配图

  1. 目标内核和头文件不一致:编译器找不到 linux/module.h、autoconf.h 或内核构建规则。
  2. 编译工具链或系统依赖缺失:找不到 make、编译器、链接器、ELF 相关文件或 pahole。
  3. 驱动源码和内核 API 不兼容:结构体成员、函数参数、符号导出方式发生变化。
  4. 构建目录或权限异常:DKMS 无法创建临时文件、写入日志或生成模块。
  5. 模块构建成功但无法加载:模块依赖、签名、内核配置或架构不匹配。
  6. 模块已经加载但服务失败:服务用户、设备节点、启动顺序、配置文件或端口存在问题。
  7. 软件源或网络依赖异常:缺少头文件或工具包,但包管理器无法访问仓库或下载内容。

排查时应优先处理低风险、信息量高的检查,不要一看到服务失败就清理 DKMS 目录或重装内核。

逐层排除:先核对内核头文件

1. 确认 DKMS 使用的是哪个内核

DKMS 可以为当前运行内核构建,也可以为尚未启动的目标内核构建。不要只看系统中是否安装了某个头文件包,而要确认 /lib/modules/<目标内核>/build 指向的目录是否正确。

kernel="$(uname -r)"
build_dir="/lib/modules/$kernel/build"

printf 'kernel: '
printf '%s\n' "$kernel"

printf 'build link: '
readlink "$build_dir"

printf 'resolved path: '
readlink -f "$build_dir"

test -e "$build_dir" && echo "build path exists" || echo "build path missing"
test -f "$build_dir/Makefile" && echo "kernel Makefile exists" || echo "kernel Makefile missing"
test -f "$build_dir/include/linux/module.h" && echo "module.h exists" || echo "module.h missing"
test -f "$build_dir/.config" && echo "kernel config exists" || echo "kernel config missing"

正常情况下,/lib/modules/<kernel>/build 应该是指向相应内核头文件或内核构建目录的符号链接,且该目录中存在内核 Makefile。以下结果具有不同含义:

  • build path missing:当前内核对应的构建目录不存在,通常是头文件包未安装或被清理。
  • Makefile missing:目录可能不是完整的内核构建目录,或者符号链接指向错误位置。
  • module.h missing:头文件不完整、路径错误,或者安装的是不匹配的源码包。
  • .config missing:不一定单独说明故障,但如果同时出现 Kernel configuration is invalid,就应检查内核开发包是否完整。
  • readlink -f 指向另一个内核版本:这是典型的头文件和目标内核不匹配。

uname -r 的字符串必须完整匹配包版本。比如 6.8.0-52-generic、6.8.0-52-cloud-amd64 和 6.8.0-52 不是可以随意互换的名称。通用头文件包即使版本号相近,也不一定包含当前内核需要的配置和构建脚本。

2. 检查头文件包是否完整安装

不同发行版的包名不同。Debian 或 Ubuntu 系列通常使用 linux-headers-$(uname -r),部分 RHEL、Rocky Linux、AlmaLinux 系列则更关注 kernel-devel-$(uname -r)。

可以先查询,不要直接假定包名:

kernel="$(uname -r)"

if command -v dpkg-query >/dev/null 2>&1; then
    dpkg-query -W "linux-headers-$kernel" 2>/dev/null || true
fi

if command -v rpm >/dev/null 2>&1; then
    rpm -q "kernel-devel-$kernel" 2>/dev/null || true
    rpm -q "kernel-headers-$kernel" 2>/dev/null || true
fi

如果包管理器显示未安装,再根据发行版安装对应依赖。例如:

sudo apt install "linux-headers-$(uname -r)" build-essential dkms

或:

sudo dnf install "kernel-devel-$(uname -r)" gcc make dkms elfutils-libelf-devel

这两个命令不能在所有发行版上混用。执行前应确认系统类型、当前内核是否来自仓库,以及软件源是否提供完全匹配的版本。若安装过程出现解析域名失败、仓库返回 404 或包版本不存在,问题首先在软件源或网络依赖,不应继续修改 DKMS 源码。

如果当前运行的是云厂商、定制发行版或自行编译的内核,仓库可能没有对应的开发包。此时需要使用该内核发布方提供的匹配构建目录,不能用一个“接近的”通用头文件目录替代。

3. 检查编译器、链接器和辅助工具

DKMS 通常依赖 make、C 编译器、链接器以及内核模块构建需要的库文件。先确认命令是否存在:

for tool in dkms make gcc clang ld objcopy; do
    printf '%-8s' "$tool"
    command -v "$tool" || echo "not found"
done

dkms --version 2>/dev/null || true
make --version 2>/dev/null | head -n 1
gcc --version 2>/dev/null | head -n 1

日志中如果出现以下信息,判断方向通常比较明确:

  • cc: command not found、gcc: not found:编译器缺失或 PATH 不完整。
  • make: command not found:构建工具缺失。
  • ld: command not found:链接器或 binutils 缺失。
  • No rule to make target ...:更可能是内核构建目录不完整、Makefile 路径错误或驱动的构建脚本与当前内核不匹配。
  • pahole: not found:可能影响 BTF 类型信息生成。若日志明确将其作为错误处理,应补充对应工具;若只是警告,需要结合最终是否生成模块判断。

编译器版本提示不一定是根因。例如日志中的 compiler differs from the one used to build the kernel 可能只是警告。只有当后面出现 ABI、汇编指令或编译错误时,才需要把编译器版本作为主线继续调查。

从 make.log 提取真正的第一处错误

1. 找到与目标版本对应的日志

DKMS 的详细构建日志通常位于:

/var/lib/dkms/<module>/<module-version>/<kernel>/<architecture>/log/make.log

实际目录以 dkms status 输出为准。可以先查找所有日志:

sudo find /var/lib/dkms -type f -name make.log -print

不要只查看文件最后几行。make[1]: *** [Makefile:xxx: modules] Error 2 往往只是上游错误的结果,不是根因。建议先筛选关键行:

sudo grep -nE \
'error:|fatal error:|No such file|not found|Permission denied|undefined reference|undefined!|invalid|incompatible|No rule to make target|sign-file' \
/path/to/make.log

然后围绕第一条有意义的错误,向前查看约 20 到 40 行,确认当时执行的编译命令、使用的内核目录和具体源文件。示例中的路径和日志均为演示,不代表某台服务器的实际输出。

2. 按错误文本建立对应关系

日志片段示例常见原因下一步检查
fatal error: linux/module.h: No such file or directory头文件缺失、构建路径错误或目标内核不匹配检查 /lib/modules/$(uname -r)/build
Kernel configuration is invalid.config、include/config/auto.conf 或生成文件不完整核对内核开发包和目标内核
No rule to make target ...内核构建目录不完整、Makefile 路径错误查看日志中的 make -C 和 M= 参数
gcc: command not found编译器未安装或环境变量不完整检查 command -v gcc 和包管理器
implicit declaration of function驱动调用了已删除或未声明的内核接口查驱动版本支持范围
struct ... has no member named ...内核结构体发生变化对照源码支持的内核版本
incompatible pointer type函数签名或回调接口发生变化检查驱动补丁或适配版本
modpost: "xxx" undefined!符号未导出、依赖模块未参与构建或配置未启用检查 EXPORT_SYMBOL、依赖和内核配置
Permission denied构建目录、临时目录或日志目录不可写检查路径权限、挂载属性和安全策略
sign-file: ... No such file模块签名工具或密钥配置缺失检查签名配置,不要直接关闭安全启动
No space left on device磁盘空间或 inode 耗尽检查 df -h 和 df -i

3. 区分头文件问题和 API 兼容问题

这两类错误经常被混为一谈,但处理方向完全不同。

如果错误发生在包含头文件之前,例如:

fatal error: linux/module.h: No such file or directory

重点是修复头文件路径、包版本或构建目录。

如果头文件已经成功读取,错误出现在驱动自己的 .c 文件中,例如:

error: ‘struct device’ has no member named ‘xxx’
error: too few arguments to function ‘yyy’
error: implicit declaration of function ‘zzz’

则更可能是驱动源码与内核 API 不兼容。此时继续安装同一个头文件包通常没有帮助,应确认:

  • 驱动版本声明支持哪些内核版本;
  • 当前内核是否引入了接口变更;
  • 发行版是否提供针对该内核的补丁;
  • DKMS 软件包是否需要升级到与当前内核匹配的版本。

modpost 阶段的错误也要单独判断。它说明大部分 C 代码可能已经编译完成,但模块符号检查没有通过,不等同于“头文件缺失”。

检查目录权限、空间和软件源依赖

1. 权限错误不能靠扩大权限解决

DKMS 通常由 root 调用,但其源码、构建缓存和临时目录仍可能因为手工复制、错误的属主或只读挂载而无法写入。可以检查具体路径的每一层权限:

sudo namei -l /var/lib/dkms
sudo namei -l /usr/src
df -h /var /usr
df -i /var /usr
findmnt -no TARGET,OPTIONS /var /usr 2>/dev/null

如果日志显示 Permission denied,需要区分:

  • 目录没有写权限;
  • 文件系统以只读方式挂载;
  • 磁盘空间或 inode 耗尽;
  • SELinux 或其他安全策略拦截;
  • 构建脚本试图访问不允许使用的路径。

在启用 SELinux 的系统上,可以查看状态和近期拒绝记录:

getenforce 2>/dev/null || true
sudo ausearch -m avc -ts recent 2>/dev/null | tail -n 30

不要对 /usr/src 或 /var/lib/dkms 执行 chmod -R 777。这会扩大系统写权限,掩盖真正原因,也可能破坏软件包管理。若目录属主被手工改动,应先保存日志,再根据具体软件包的文件归属恢复,必要时使用包管理器重新安装相关包。任何删除或重装操作前,都应保留 /var/lib/dkms/<module> 下的构建日志;回滚方式通常是重新安装原驱动包并为目标内核重新执行 DKMS 构建。

2. 缺少依赖但软件源不可用

如果头文件或编译工具未安装,包管理器报错可能来自网络或软件源,而不是 DKMS 本身。典型信息包括:

Temporary failure resolving ...
404 Not Found
Unable to locate package ...
No matching package ...

这时应先确认系统版本、仓库配置和目标内核是否仍在仓库中。不要用下载到的其他内核版本头文件“凑合”构建。对于长期支持内核、云内核或自定义内核,最好使用同一来源、同一发布批次的内核和开发包。

编译成功后,继续判断模块加载和服务启动

1. 确认模块文件属于目标内核

DKMS 状态显示 built 或 installed 后,还要确认模块元数据和路径:

module="<module-name>"
kernel="$(uname -r)"

modinfo -k "$kernel" "$module"

如果提示找不到模块,可能是模块没有安装到当前内核目录,或者模块名与文件名不同。Linux 模块名中的连字符和下划线通常可以互换,但不能把软件包名、DKMS 名和实际模块名直接当成同一个值。

在不真正加载模块的情况下,可以先查看 modprobe 将执行什么:

modprobe -n -v "$module"

需要加载当前内核模块时,应先确认维护窗口,因为驱动可能直接影响磁盘、网络、存储或硬件设备。加载后检查:

sudo modprobe "$module"
lsmod | grep -E "^${module//-/_}\b"
sudo dmesg -T | tail -n 80

如果 modprobe 返回:

Required key not available

而 dmesg 中出现模块签名被拒绝,说明构建可能已经成功,失败发生在内核安全策略验证阶段。此时应检查发行版的模块签名流程、签名密钥和安全启动状态,不能把它继续当作头文件错误处理。直接关闭安全启动会改变整机安全边界,应由管理员根据环境和合规要求决定,并保留可恢复方案。

2. 查看服务依赖,而不是盲目重启

当模块能够加载后,再回到服务层:

sudo systemctl status <service-name> --no-pager -l
sudo journalctl -u <service-name> -b --no-pager
sudo systemctl cat <service-name>
sudo systemctl show <service-name> \
    -p Requires -p Wants -p After -p ExecStart -p User

重点观察以下类型的状态:

  • status=203/EXEC:服务的 ExecStart 路径不存在、不可执行或权限不正确。
  • status=217/USER:配置的服务用户不存在或无法切换。
  • No such file or directory:可能是设备节点、配置文件、动态库或模块提供的路径缺失。
  • Permission denied:可能是服务用户无权访问设备、目录或套接字。
  • Address already in use:服务已经进入监听阶段,但目标端口被其他进程占用。
  • 服务在启动后立即退出:需要结合应用日志和 ExecStart 参数判断,不能仅凭 systemctl 的一行状态归因于 DKMS。

如果服务必须在设备出现后启动,应检查单元文件中的 After=、Requires= 或设备依赖是否合理。不要直接修改发行版提供的单元文件;如确需调整,应使用 drop-in 配置,并在变更前备份原配置,验证失败时删除对应 drop-in 或恢复备份即可回滚。

3. 端口只用于确认应用层是否完成监听

查看端口时,先确认服务是否真的应该监听 TCP 或 UDP 端口:

sudo ss -lntup

若已知端口,例如 8443,可以缩小范围:

sudo ss -lntup | grep ':8443'

不同结果代表不同方向:

  • 服务失败且没有监听端口:先看服务日志和模块依赖,不要先排查防火墙。
  • 服务显示 active,但端口不存在:检查应用配置、监听地址、启动后初始化错误,或该服务实际使用 Unix 套接字。
  • 端口被其他进程占用:先用 ss 识别进程,再根据业务安排停止或调整配置。不要直接执行强制终止命令。
  • 本机端口存在,但远端访问不到:此时才继续检查监听地址、防火墙、安全组和上游网络;这不是 DKMS 编译日志能够解释的问题。

端口检查不能证明驱动已经正确工作。只有模块状态、内核日志、服务状态和端口监听都符合预期,才能说明故障链路已经恢复。

定位根因:用证据链替代单点猜测

将检查结果整理成一条因果链更容易避免误判。例如:

当前内核为 6.8.0-52-generic
→ build 链接指向 6.8.0-41-generic
→ make.log 报 linux/module.h 找不到
→ DKMS 未生成 .ko
→ modprobe 找不到模块
→ 依赖该设备的服务启动失败
→ 服务没有监听端口

这条链路的根因是头文件和目标内核不匹配,服务和端口只是后续表现。

另一种链路可能是:

目标内核头文件完整
→ 驱动源码在 struct 成员处编译失败
→ make.log 报 API 不兼容
→ 没有生成 .ko
→ 服务启动失败

此时安装更多通用编译工具不会解决问题,应该更换兼容的驱动版本、应用补丁,或选择驱动支持的内核版本。

还有一种容易混淆的情况:

DKMS 显示 installed
→ modinfo 能找到模块
→ modprobe 返回 Required key not available
→ dmesg 报签名校验失败
→ 服务因设备不存在而失败

此时构建阶段已经通过,根因是模块加载策略或签名配置,不能继续围绕 make.log 反复重建。

修复后验证:从模块到端口逐级确认

在头文件、依赖或驱动版本修复后,优先执行针对目标内核的构建,而不是对所有 DKMS 模块做批量操作。版本号应替换为 dkms status 中显示的实际值:

sudo dkms build -m <module-name> -v <module-version> -k "$(uname -r)"

构建成功后再安装:

sudo dkms install -m <module-name> -v <module-version> -k "$(uname -r)"
sudo depmod -a "$(uname -r)"

build 通常只生成模块,install 会把模块放入目标内核的模块目录。安装前应确认当前没有正在使用该驱动的关键业务,尤其是存储、网络和硬件控制类模块。不要在不了解影响范围时卸载正在使用的模块。

验证顺序建议保持一致:

dkms status
modinfo -k "$(uname -r)" <module-name>
sudo modprobe <module-name>
lsmod | grep -E '^<module-name>'
sudo dmesg -T | tail -n 80
sudo systemctl status <service-name> --no-pager -l
sudo ss -lntup

如果修复针对的是尚未启动的内核,当前系统中的 modprobe 验证并不能替代重启后的验证。重启前应确认:

  • dkms status 对目标内核显示 installed;
  • 目标内核的 /lib/modules/<kernel>/ 下存在模块;
  • 模块签名符合安全启动策略;
  • 服务单元依赖和配置没有指向旧内核路径;
  • 具备控制台或带外管理方式,以便新内核启动异常时回退。

不要在没有保留旧内核、没有备份服务配置或没有远程恢复通道的情况下清理旧内核。若必须执行定向 dkms remove,应先备份对应日志和配置,并明确该操作会移除哪个内核版本下的模块;回滚通常是重新安装驱动包、重新执行针对目标内核的 dkms install,而不是简单重启。

复发监控点:把故障留在构建阶段

DKMS 问题经常在内核升级后再次出现,适合建立以下检查点:

  • 内核更新完成后,检查 dkms status 是否为新内核生成并安装模块;
  • 将 /var/lib/dkms/<em>/</em>/<em>/</em>/log/make.log 纳入故障采集,保留首次错误附近的日志;
  • 对 /lib/modules/<kernel>/build 建立存在性和目标路径检查;
  • 监控 /var、/usr 的磁盘空间与 inode 使用量;
  • 对关键服务同时监控 systemctl 状态、设备是否存在和端口是否监听;
  • 记录安全启动、模块签名和内核配置的变更;
  • 内核、驱动或发行版升级前,确认驱动版本的内核支持范围。

这样处理后,下一次故障可以快速回答三个问题:模块是否为当前内核成功构建,构建失败的第一条有效错误是什么,以及服务是在模块加载前失败,还是在模块正常后又因自身配置、权限或端口问题失败。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/6360.html

相关推荐