Ubuntu 22.04 安装 Realtek R8125 2.5G 网卡驱动：DKMS 配置全记录

长话短说这篇文章是我在 Ubuntu 22.04 上折腾 Realtek R8125 2.5G 网卡驱动的完整记录。板载 2.5G 网卡在现在的 B660/B760 主板上非常常见其中相当一部分用的就是 Realtek R8125 芯片。装好 Ubuntu 之后发现网卡没被系统驱动起来上不了网没驱动就没法上网没网就没法装驱动——这个鸡生蛋蛋生鸡的死循环我是深有体会。这篇文章就把我从头到尾踩过的坑、试错出来的正确步骤全部写清楚尤其是 DKMS 自动编译配置确保内核升级后驱动不会失效免得隔几个月系统一更新又断网。这内容适合所有在 Ubuntu/Debian 系系统上使用 R8125/RTL8125 板载网卡的朋友或者准备装 Ubuntu 22.04 双系统但担心驱动问题的人。我会把方案选型、编译安装、DKMS 配置、Secure Boot 排查全部拆开讲保证每一步你照着敲就行。1. 方案选型为什么不能直接依赖内核自带的 r81691.1 先搞清楚你的网卡到底是什么芯片很多朋友第一步就搞错了以为系统里有网卡就能用。Ubuntu 22.04 默认内核里确实包含了一个名叫r8169的驱动模块但请记住一个关键点这个模块不是万能的对 R8125 的支持非常不完整甚至可以说是时好时坏。R8125 是 Realtek 后来的 2.5G Ethernet 控制芯片它的硬件设计相比老款 8111/8168 有很大改动。虽然内核的 r8169 驱动代码里名义上兼容了 RTL8125但实际用起来两个问题非常突出部分主板上的 R8125 在r8169驱动下根本无法识别ip link里压根看不到网卡设备。就算能识别2.5G 速率协商不稳定经常掉到 1000Mbps 甚至 100Mbps大文件传输直接拉胯。我当时的主板是七彩虹的 B760M板载 R8125装完 Ubuntu 22.04 后lspci能看到网卡但dmesg里面一堆报错链路状态始终是 DOWN。后来我直接放弃内核自带驱动改用 Realtek 官方闭源驱动问题才彻底解决。所以在动手之前第一步永远是确认芯片型号lspci -nn | grep -i ethernet输出类似这样03:00.0 Ethernet controller [0200]: Realtek Semiconductor Co., Ltd. RTL8125 2.5GbE Controller [10ec:8125] (rev 05)只要看到10ec:8125这个设备 ID基本可以确定就是 R8125。如果你还不太确定可以用lspci -v查看当前被哪条驱动接管或者直接看主板官网的网卡参数确认。1.2 官方驱动 vs 内核自带驱动 vs DKMS 管理的差异我把常见的驱动来源做了个直观对比这个表挺重要的建议你先看一遍再决定走哪条路驱动来源优点缺点适合场景内核自带 r8169装完系统就有不用额外操作R8125 支持不完善速率不稳甚至无法识别不追求 2.5G 满速、且运行稳定的少数情况Realtek 官方 r8125 源码手动编译官方优化2.5G 支持完善性能稳定内核升级后模块失效需要重新编译临时救急、一次性部署Realtek 源码 DKMS 注册官方驱动性能 自动跟随内核编译初始配置需要多花几分钟长期使用强烈推荐核心结论一句话别懒直接走 DKMS 方案。手动编译安装只需要一条make install看似更快但下次内核一升级网卡又变回原来的状态你还得重新下载源码、重新编译、重新安装而且如果不记得当时的编译选项整个流程又要重新摸一遍。1.3 为什么 R8125 在 Ubuntu 22.04 上特别容易出问题讲点背景知识。Ubuntu 22.04 使用的是 5.15 LTS 内核这个内核版本对较新的 2.5G 网卡硬件本身的适配成熟度是不如后续 5.19/6.x 内核的。Realtek R8125 的官方驱动更新节奏又很迷经常是几个月才发一版很多用户发现刚适配好新内核过两个月内核更新又把驱动弄坏了。另外还有一个隐藏问题部分主板在默认 BIOS 设置下会把网络接口的电源管理模式打开导致网卡在空闲时进入低功耗状态系统挂起后恢复时驱动异常表现为睡眠后断网重启后必须冷启动才能识别。这些和网卡驱动本身强相关官方驱动相比内核自带的 r8169 在电源管理处理上要成熟一些。所以我在这篇文章里所有的操作都基于一个原则官方驱动源码 DKMS 自动化编译最大化稳定性最小化人工干预。2. 编译前的环境准备装好这些再动手能省一半时间2.1 确认内核头文件和编译工具链在开始编译网卡驱动之前系统里必须已经有当前内核对应的头文件。如果头文件版本和运行时内核版本不匹配编译 100% 会报错最常见的错误长这样Makefile: ... 找不到 generated/autoconf.h所以第一步确认内核版本并安装匹配的头文件uname -r假设输出的是5.15.0-91-generic那么依次执行sudo apt update sudo apt install linux-headers-$(uname -r) build-essential dkms其中linux-headers-$(uname -r)是保证编译驱动时能找到内核构建接口build-essential提供 gcc/make 整套工具dkms是我们后面要用的自动编译框架。顺便说一句这里有一个常见坑有些教程让你直接sudo apt install linux-headers-generic这个包装的是当前推荐版本的通用头文件如果你的系统内核不是它对应的版本编译核心模块时依然会报版本不匹配。最稳妥的做法永远是带上$(uname -r)动态匹配。2.2 提前处理 Secure Boot这一步真的非常关键我后来在多个群里帮人排查发现很多人 R8125 驱动装上之后modprobe加载模块报错卡的都在这。如果你主板开启了 UEFI Secure Boot系统内核默认只允许加载经过签名的内核模块手动编译的驱动没有签名就会触发拒绝加载。具体症状是modprobe: ERROR: could not insert r8125: Required key not available或者dmesg里出现Lockdown: modprobe: unsigned module loading is restricted; see man kernel_lockdown.7处理方案有两个方案 A推荐进 BIOS 关闭 Secure Boot。大多数 DIY 用户没有强安全需求关了省事一切模块随便加载。方案 B保留 Secure Boot用mokutil导入自定义密钥给模块签名。流程比较复杂适合企业环境或者非要开 Secure Boot 的朋友。考虑到这篇博文面向的受众大部分是个人电脑我建议直接关掉。如果实在不想关我后面在常见问题章节会单独写签名操作的大概流程。2.3 从 Realtek 官方获取驱动源码Realtek 官网的下载链接经常变但驱动源码的打包命名一般比较规律通常是r8125-9.xxx.xx.tar.gz这种格式。你可以去 Realtek 官网的网络界面控制器 / PCIe 接口 / 2.5G Ethernet 分类下找到 RTL8125 的 Linux 驱动下载入口。下载后得到的是一个压缩包。假设你下载到的是r8125-9.011.00.tar.bz2解压tar -xjf r8125-9.011.00.tar.bz2 cd r8125-9.011.00操作之前你最好先看一眼目录内容尤其是README.md或autorun.sh文件。Realtek 官方驱动包里面自带一个脚本方式的一键安装但我实测不推荐直接用原因跟前面说的一样——它只是自动 make 和 make install没有注册 DKMS。内核一更新照样断网。3. 编译安装与 DKMS 配置手把手实操记录3.1 先手动编译一次确认源码没问题我习惯先把驱动模块编译出来跑一遍确认源码在当前内核下能通过再进 DKMS 流程。这样如果后续 DKMS 构建失败你能更快定位是 DKMS 配置的问题还是源码本身的问题。make clean make -j$(nproc)-j$(nproc)的意思是用 CPU 所有核心并行编译速度能快不少。在 8 核 16 线程的机器上整个编译过程通常 30 秒到 1 分钟就能完成。如果你的网络环境是在装好系统但没驱动的情况下利用 USB 共享网络或者手机 USB 网络共享先把需要的包全部装好之后再进入正常流程。编译完成后手动加载模块验证当前内核可以直接使用sudo insmod src/r8125.ko然后查看网卡是否出现ip link能看到enp3s0之类的新接口说明编译出来的模块没问题。这里先不要急着make install直接用rmmod r8125把模块卸载掉方便下一步交给 DKMS 接管。3.2 DKMS 配置文件写法与目录规范要让 DKMS 能自动帮我们编译安装驱动需要做两件事把源码放到 DKMS 管理的源码目录然后写一个dkms.conf描述编译信息。先创建源码目录。DKMS 目录命名规范是模块名-模块版本/这里模块名用r8125版本和源码目录里的版本一致我这里是9.011.00sudo mkdir -p /usr/src/r8125-9.011.00 sudo cp -r . /usr/src/r8125-9.011.00/然后创建/usr/src/r8125-9.011.00/dkms.confsudo vim /usr/src/r8125-9.011.00/dkms.conf内容如下PACKAGE_NAMEr8125 PACKAGE_VERSION9.011.00 BUILT_MODULE_NAME[0]r8125 DEST_MODULE_LOCATION[0]/kernel/drivers/net/ethernet/realtek AUTOINSTALLyes MAKE[0]make -C ${dkms_tree}/${PACKAGE_NAME}/${PACKAGE_VERSION}/build/src clean make -C ${dkms_tree}/${PACKAGE_NAME}/${PACKAGE_VERSION}/build/src CLEANmake -C ${dkms_tree}/${PACKAGE_NAME}/${PACKAGE_VERSION}/build/src clean几个关键点解释一下BUILT_MODULE_NAME指定编译产出的内核模块叫什么R8125 官方驱动的模块名就是r8125.ko。DEST_MODULE_LOCATION决定 DKMS 构建完成后把模块安装到内核模块树的哪个子目录一般放在realtek厂商目录比较规范。MAKE这一行里的${dkms_tree}变量是 DKMS 内置的指向/usr/src核心动作是先在源码目录里make clean再执行make防止旧编译产物污染新构建。AUTOINSTRUCTyes是灵魂配置告诉 DKMS 在后续每次内核更新后自动为新内核重新编译模块。这就是自动编译配置的核心。3.3 初始化 DKMS 并验证自动编译链路源码目录和配置都齐了接下来执行三条命令把驱动加入 DKMS 管理sudo dkms add -m r8125 -v 9.011.00 sudo dkms build -m r8125 -v 9.011.00 sudo dkms install -m r8125 -v 9.011.00步骤如下dkms add只是把源码登记到 DKMS 的数据库里不会立刻编译。dkms build会真正执行编译。这一步如果前面环境准备没做好就会在这里暴露问题。构建成功的话输出最后几行是Building module...然后cleaning build area...。dkms install把编译好的r8125.ko安装到内核模块目录并刷新模块依赖。安装完成后先卸载之前手动加载的模块如果之前 insmod 过再重新加载确保走的是 DKMS 新装的那条路径sudo modprobe -r r8125 sudo modprobe r8125然后确认模块加载状态和网卡识别lsmod | grep r8125 ip link show看到enp3s0之类的网口有UP状态通常 DHCP 就能获取到 IP 了。检查网络sudo dhclient enp3s0或者直接看 NetworkManager 是否自动弹出连接提示。如果到这里一切正常恭喜你2.5G 网卡的驱动部分已经搞定。3.4 验证 DKMS 自动编译确实生效很多人做完上面三步以为就完事了其实漏了最关键的一步验证 DKMS 真的能在内核升级后自动兜底。我建议用下面的命令确认当前模块在 DKMS 中的状态sudo dkms status输出类似这样r8125/9.011.00, 5.15.0-91-generic, x86_64: installed这个状态说明当前内核的模块已经 installed。未来如果你执行sudo apt upgrade升级了内核系统重启后你不需要做任何操作DKMS 会自动对新内核执行一次 build install。想验证的话可以用sudo dkms status再看一次你会发现同一版本号下面多出了对应新内核的记录。如果不小心删除了 DKMS 注册信息或者某次升级后网卡又消失了可以手动触发一次sudo dkms autoinstall这个命令会让 DKMS 检查所有已注册模块对本地所有新内核重新编译缺失的模块。4. 常见问题排查与避坑技巧实录4.1 编译报错或加载失败怎么办我在折腾过程中遇到过几个典型问题直接列成速查表你遇到类似情况可以对号入座现象排查方向解决方案dkms build报Makefile: ... 没有那个文件没有安装对应内核头文件执行sudo apt install linux-headers-$(uname -r)modprobe r8125报Required key not availableSecure Boot 阻止未签名模块关闭 Secure Boot 或用 mokutil 签名编译成功但ip link没有新网口模块没有自动加载旧模块冲突sudo modprobe r8125必要时sudo depmod -a刷新依赖网卡能识别但协商速率只有 1000Mbps网线质量、路由器端口或 EEE 节能以太网问题换线或使用ethtool -s eth0 speed 2500 duplex full强制速率系统升级后网卡失效DKMS 注册丢失或新内核编译失败sudo dkms autoinstall再检查/var/lib/dkms下的日志这其中有几个值得展开说的经验。第一个是Secure Boot 问题其实比很多人想得更隐蔽。就算你在 BIOS 里明明记得关掉了 Secure Boot装完系统之后某些主板尤其是部分品牌机会在系统更新完 firmware 之后悄悄把 Secure Boot 重新启用或者 UEFI 设置里存在重置安全启动状态之类的隐藏选项。遇到可疑加载失败问题时重新进一次 BIOS 检查比在系统里瞎折腾更高效。第二个是强制 2.5G 速率不一定是好事。Realtek R8125 的协商逻辑在遇到不合格的网线或者对端设备只支持千兆时会自动降级。如果你发现网卡始终只有 1000Mbps先用ethtool看自我协商的对端能力而不是盲目强制。强制 2500 速率但链路质量不够可能导致丢包率飙升。第三个是关于r8169和r8125模块共存的问题。如果系统之前加载过r8169然后你又手动加载r8125有可能出现两个模块抢占同一 PCI 设备的情况。安全做法是sudo rmmod r8169 sudo modprobe r8125然后把r8169加入黑名单避免重启后它抢着绑设备echo blacklist r8169 | sudo tee /etc/modprobe.d/blacklist-r8169.conf4.2 DKMS 注册太多旧版本导致构建混乱这种情况我遇到过一次源代码包更新了几版我在/usr/src下积累了多个版本目录同时在 DKMS 里注册了多个同名模块版本。这会导致dkms status输出很长而且dkms autoinstall会尝试对所有旧版本内核逐个编译浪费时间和磁盘。清理方法sudo dkms remove -m r8125 -v 旧版本号 --all sudo rm -rf /usr/src/r8125-旧版本号只保留一个稳定版就好。另外要注意如果dkms.conf里写的版本号和目录名不一致dkms add会直接报错所以每次升级驱动源码时一定要同时修改目录名和 dkms.conf 里的PACKAGE_VERSION。4.3 网卡休眠唤醒后失联的问题这个我在多台设备上遇到过Sleep 或 Hibernate 后网卡彻底失联必须重启才能恢复。原因主要是网卡的节能特性与内核电源管理交互不完美。从驱动侧缓解的话可以用 ethtool 关闭部分节能特性sudo ethtool -s enp3s0 wol d或者用ethtool --set-eee enp3s0 eee off关闭 EEEEnergy Efficient Ethernet。不过这两个选项在重启后会恢复默认想持久化的话可以写一个 systemd 服务或者直接放在/etc/rc.local里执行。作为一个更省心的方式很多主板 BIOS 里有关闭 ErP / 深度节能 / 网络唤醒的选项对于纯台式机用户直接在 BIOS 里把和网络唤醒相关的选项关掉是比系统侧调 ethtool 更彻底的办法。我在自己那台机器上就是这样处理的系统挂起恢复后网卡从来没再掉过链子。4.4 如何判断你的驱动到底是不是官方的有几次群里朋友发截图说我的网卡识别了但是速度只有 100Mbps结果让他们跑命令一看驱动模块名是r8169固件根本没走 R8125 官方驱动。判断当前网卡被哪个驱动接管ls -l /sys/class/net/enp3s0/device/driver输出会显示驱动的名字比如.../drivers/r8125看到r8125就是官方驱动接管看到r8169说明还是内核通用驱动的状态。这一步排查应该在任何网络性能异常之前就先做掉。5. 从零到稳定使用的完整命令清单写到这里我把整个流程压成一份可以直接照抄的操作清单未来你在别的机器上装 R8125不用再翻前文直接按这份清单走就行# 1. 安装编译依赖 sudo apt update sudo apt install -y dkms build-essential linux-headers-$(uname -r) # 2. 下载并解压官方驱动源码包假设文件名为 r8125-9.011.00.tar.bz2 tar -xjf r8125-9.011.00.tar.bz2 cd r8125-9.011.00 # 3. 注册 DKMS sudo mkdir -p /usr/src/r8125-9.011.00 sudo cp -r * /usr/src/r8125-9.011.00/ sudo vim /usr/src/r8125-9.011.00/dkms.conf # 填入前文提供的配置内容 # 4. 构建并安装 sudo dkms add -m r8125 -v 9.011.00 sudo dkms build -m r8125 -v 9.011.00 sudo dkms install -m r8125 -v 9.011.00 # 5. 加载模块并验证 sudo modprobe r8125 ip link # 6. 可选黑名单 r8169 避免冲突 echo blacklist r8169 | sudo tee /etc/modprobe.d/blacklist-r8169.conf实际操作中唯一可能变化的版本号。只要保持dkms.conf里的版本和/usr/src目录名一致就不会出问题。6. 比驱动安装更重要的长期维护习惯6.1 内核升级后的检查流程装了 DKMS 不代表可以完全当甩手掌柜建议每次系统内核升级后养成快速检查的习惯。操作顺序是# 更新系统 sudo apt upgrade # 查看当前运行内核 uname -r # 查看系统已安装的内核列表 dpkg --list | grep linux-image # 查看 DKMS 模块状态 sudo dkms status如果dkms status里新内核对应的记录显示 installed说明驱动已经自动搞定了。如果显示 build 失败那就进/var/lib/dkms/r8125/9.011.00/下面看构建日志最常见的原因是新内核头文件没装齐全装好之后执行sudo dkms autoinstall一般能救回来。6.2 备份 dkms.conf避免再次踩坑我已经把dkms.conf的内容备份到自己的配置仓库里连同blacklist-r8169.conf一起。以后重装系统直接拷贝出来用省去了重新回忆写法的过程。这一点推荐你也学一下特别是如果你管理多台 Ubuntu 机器哪怕只是几台测试机有一份标准配置能少掉很多头发。6.3 谁说不需要官方驱动别急着信论坛里经常有人安利Ubuntu 自带 r8169 就行不用折腾这个观点在部分主板上是成立的但在 R8125 上我见过太多翻车案例。也有部分高手会说新内核6.x对 R8125 支持已经不错了确实如此如果你的内核版本较新可以先试试不装驱动直接ip link看能不能识别。能识别、速率稳定 2.5G那确实可以省事。但如果你要求 100% 可控或者遇到过无故断流那么官方驱动 DKMS 始终是最稳的选择。结合我自己的现行做法每台 Ubuntu 机器装完系统的第一件事就是把这个 R8125 驱动流程走一遍已经重复做了七八次成功率从第一次折腾时的 60% 提升到现在基本一次过。核心就靠两件事环境准备别跳步DKMS 配置别想当然。尤其是linux-headers-$(uname -r)和主板的 Secure Boot 状态这两处只要有一个疏忽后面大概率浪费时间。最后分享一个小技巧很多朋友在编译时喜欢加-j参数加速但如果是在虚拟机或者低配小主机上编译反而建议不加并行参数直接用make因为并行编译占用内存较多某些小内存机器甚至会出现 OOM。驱动编译本身也就几十秒等一会完全无所谓稳定优先。