Linux上DKMS驱动构建失败,怎样从内核头文件和编译日志定位原因?
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 服务初始化
↓
应用监听端口或提供其他功能
其中任意一层失败,后续层都可能表现为启动失败。问题树可以分为以下几条分支:

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



