Ubuntu下R8125网卡驱动安装全攻略：DKMS自动编译与内核升级防失效

装完Ubuntu 22.04之后右上角网络图标一直转圈有线连接永远显示“未连接”而在Windows下上网一切正常——如果你遇到的是这种情况不用急着怀疑硬件坏了大概率是主板上的Realtek R8125 2.5G网卡没有吃到正确的Linux驱动。这个问题几乎每个月都有人在Ask Ubuntu和各大Linux论坛上提问坑位固定踩的人一轮接一轮。这篇文章就把R8125驱动安装这件事彻底讲透从芯片确认、编译依赖、DKMS自动编译配置到离线环境应急方案、内核升级后的驱动失效处理尽量让你看完就能一次搞定不用再对着终端发呆。1. 装完Ubuntu后“有线网络已断开”R8125这款板载网卡为什么总在Linux上栽跟头1.1 先说清楚R8125和r8169到底是不是一家人RTL8125是Realtek推出的2.5Gbps以太网控制器这几年大量出现在七彩虹、华硕、微星等品牌的中端主板上。板商喜欢它是因为性价比高、集成简单对用户来说就是“网口是2.5G的看着很香”。但问题来了这个芯片在Linux下并不是开箱即用的。Ubuntu 22.04自带内核是5.15里面有一个叫r8169的驱动模块。从名字看它好像是RTL8125的亲戚但实际上r8169最初是给RTL8169、RTL8111这些老芯片准备的。后来内核维护者尝试让r8169也能绑定RTL8125结果就是“能认但不好用”——有的主板在r8169下链路根本起不来有的能跑但只能协商到千兆有的跑着跑着网卡假死需要重启网络服务才能恢复。原因很简单RTL8125和老的Realtek芯片内部架构差异很大r8169驱动对它的支持不完整像EEE节能以太网、多队列这些特性基本是缺失或者不稳定的。所以如果你主板板载的是RTL8125绕过系统自带的r8169、安装Realtek官方r8125驱动基本是必做的一步。这不是说内核自带的驱动完全不能用而是它太不可控。我自己帮朋友装系统时遇到过好几种“奇怪现象”最后全部是切到r8125官方驱动才解决。1.2 翻车现场自查你遇到的是不是这几个典型症状我先列几个典型的“R8125翻车症状”你可以对照一下症状可能原因装完系统后完全没有有线连接选项r8169未正确绑定R8125或驱动加载失败网络连接显示但频繁断开/假死r8169驱动稳定性问题或节能特性导致的兼容问题网卡只能协商到1000Mb/s而非2500Mb/s驱动不支持2.5G协商或网线/路由器不满足条件内核更新后网卡突然失效第三方模块没有跟随内核版本重新编译dmesg日志出现r8169相关报错驱动与芯片不匹配需要切换官方r8125驱动如果你的现象在表里那基本就是R8125驱动没弄对。别急接下来按步骤来。2. 开始动手前把这三件事确认清楚才不至于白忙一场2.1 用lspci确认网卡芯片到底是R8125还是别的Realtek型号很多人一上来就下载驱动、编译、重启结果发现网卡芯片根本不是R8125而是RTL8111、RTL8168甚至是Intel的芯片方向直接错了。安装之前第一件事确认芯片型号。在Ubuntu终端执行lspci | grep -i ethernet然后看输出比如我手头这块主板显示的是03:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8125 2.5GbE Controller (rev 05)如果你看到类似的RTL8125 2.5GbE字样那就确认无疑了。有时候rev版本不同但没关系官方驱动包兼容。也可以用更详细的命令看到PCI IDlspci -nn | grep -i realtek输出中的[10ec:8125]就是Realtek的RTL8125芯片的标准ID。记住这个ID后面排查的时候很好用。2.2 确认系统版本、内核版本以及编译环境是否就绪确认芯片后再确认系统和内核版本lsb_release -a uname -r我这里以Ubuntu 22.04 5.15内核为例。Realtek官方驱动从9.0xx系列开始对5.15内核的支持已经比较成熟正常情况下编译不会有大问题。编译环境方面需要安装这些依赖sudo apt update sudo apt install -y build-essential dkms linux-headers-$(uname -r)其中linux-headers-$(uname -r)非常关键它提供了内核模块编译需要的头文件和构建脚本。如果缺少这一步后面编译会报一长串类似“leaf not found”或“cannot find module”的错误实际上就是头文件没装齐。判断编译环境有没有问题的快速方法是看/lib/modules/$(uname -r)/build是否存在且指向正确的目录。如果这个软链接不存在说明内核头文件没有安装好。2.3 Secure Boot开着还是关着这一步决定了你后面会不会加载失败这是很多教程没提但实操中非常容易踩的坑。Ubuntu 22.04默认在启用UEFI的机器上开启Secure Boot而内核模块如果未经签名在Secure Boot开启时是无法加载的。检查Secure Boot状态mokutil --sb-state如果输出是SecureBoot enabled那你编译出来的r8125模块在modprobe时大概率会失败dmesg会显示类似“module verification failed: signature not found”或“Required key not available”的报错。处理方式有两种一是进BIOS把Secure Boot关掉最简单直接适合自己用的机器二是用mokutil为模块签名这个过程涉及生成密钥、导入MOK、重启确认比较繁琐适合必须在Secure Boot开启环境下运行的情况。我的建议是个人电脑直接关Secure Boot。如果这是一台不能随便关Secure Boot的工作站或服务器再去研究mokutil签名方案。3. 标准安装流程从Realtek官方源码到DKMS自动接管3.1 下载解压官方驱动注意区分src、rtl8125_offload、rtl8125_vnet三个目录Realtek官网提供RTL8125 Linux驱动源码包下载后解压目录结构大致如下rtl8125_9.011.01/ ├── autorun.sh ├── Makefile ├── README ├── src/ │ ├── Makefile │ ├── r8125.h │ ├── r8125_n.c │ └── ... ├── rtl8125_offload/ └── rtl8125_vnet/这里需要注意rtl8125_offload是带硬件卸载功能的变体rtl8125_vnet是虚拟网卡支持普通物理网卡用主目录下的src就可以了。很多教程直接让你make或者跑autorun.sh最后也能装上但那个不会配置DKMS下次内核一升级就废了。所以我们要做的第一步不是急着make而是把这个源码包注册给DKMS。3.2 手写一份dkms.conf把驱动交给DKMS托管DKMSDynamic Kernel Module Support的设计目的是解决“第三方内核模块与内核版本强绑定”的问题。内核模块必须和当前运行的内核版本严格匹配内核升级后模块就需要用新版内核头文件重新编译。如果没有DKMS你每次升级内核都要手动重编一次驱动非常痛苦。把源码放到DKMS的指定目录并创建一个dkms.conf配置文件。以版本9.011.01为例# 将源码复制到 /usr/src 下的 rtl8125-9.011.01 目录 sudo mkdir -p /usr/src/rtl8125-9.011.01 sudo cp -r src /usr/src/rtl8125-9.011.01/然后创建/usr/src/rtl8125-9.011.01/dkms.confsudo vim /usr/src/rtl8125-9.011.01/dkms.conf内容如下PACKAGE_NAMErtl8125 PACKAGE_VERSION9.011.01 BUILT_MODULE_NAME[0]r8125 DEST_MODULE_LOCATION[0]/kernel/drivers/net/ethernet/realtek AUTOINSTALLyes MAKE[0]make -C src CLEANmake -C src clean几个关键字段解释一下PACKAGE_NAME和PACKAGE_VERSIONDKMS用来识别模块的标识必须和/usr/src/下的目录名对应也就是rtl8125-9.011.01。BUILT_MODULE_NAME编译出来的模块名官方驱动编译产物是r8125.ko所以填r8125。DEST_MODULE_LOCATION模块安装到内核树中的位置这里放到/kernel/drivers/net/ethernet/realtek/目录符合内核驱动目录的组织习惯。AUTOINSTALLyes让DKMS在新内核安装后自动触发重编译这是整个方案的核心开关。MAKE和CLEAN指定编译和清理命令官方驱动的Makefile在src子目录里所以用make -C src。创建完成后执行DKMS注册和安装sudo dkms add -m rtl8125 -v 9.011.01 sudo dkms build -m rtl8125 -v 9.011.01 sudo dkms install -m rtl8125 -v 9.011.01dkms add是注册build是编译install是把编译好的模块安装到当前内核的模块目录。执行完dkms status应该能看到类似这样的输出r8125/9.011.01, 5.15.0-91-generic, x86_64: installed到这一步驱动已经被DKMS接管了内核升级的时候它会自动重编。3.3 屏蔽r8169并加载r8125完成驱动切换驱动装好之后系统默认可能还是会优先加载r8169所以需要把r8169屏蔽掉否则两个驱动都尝试绑定同一个PCI设备容易出问题。echo blacklist r8169 | sudo tee /etc/modprobe.d/blacklist-r8169.conf然后重新加载模块sudo modprobe r8125如果一切正常ip link就能看到新的网卡接口了。注意接口名不一定和之前一样可能是enp3s0、eno1之类这个由系统的可预测网络接口命名规则决定看到哪个就用哪个。另外需要说明的是屏蔽r8169只适用于芯片确实是R8125的情况。如果你的网卡是老旧的RTL8111/8168千万别屏蔽r8169否则会直接断网。这也是为什么前面强调要先确认芯片型号的原因。3.4 验证安装结果lsmod、ethtool、ip a三连查安装完成后做三个快速检查# 查看模块加载状态 lsmod | grep r8125 # 查看驱动信息和模块版本 ethtool -i enp3s0 # 替换成你实际的网卡名 # 查看IP地址和链路状态 ip addr showethtool -i输出里应该有driver: r8125字样ip addr里网卡应该显示为UP状态。如果这些都没问题说明驱动已经正常工作。很多人做完这一步就以为万事大吉其实漏掉了真正重要的验证环节——内核升级后驱动是否还能自动恢复这个放到第5章细讲。4. 万一断网装不了驱动离线环境的应急链路4.1 用Android手机USB共享网络绕开“没网装驱动”的死循环R8125没驱动就上不了网上不了网就没法apt安装编译依赖这就是典型的“先有鸡还是先有蛋”。最快捷的解决方案是拿一台Android手机用USB线连接电脑在手机设置里打开“USB网络共享”。Ubuntu通常会自动识别出一个usb0接口并且自动通过DHCP拿到IP地址这时候就能正常联网了。这个方案不需要装额外的驱动因为Linux内核自带cdc_ether/rndis模块支持USB网络共享。实测下来Ubuntu 22.04对Android手机的USB网络共享识别率很高插上打开开关几秒钟就能看到usb0接口出现。有了网络之后就可以正常执行apt install build-essential dkms linux-headers-$(uname -r)等操作。这个方法是我在帮人救砖系统时最常用的简单高效值得优先尝试。如果你用的是iPhone操作会麻烦一点需要安装libimobiledevice工具开启热点模式不如Android方便。所以在装系统前就准备一台Android手机能省不少事。4.2 提前在能联网的机器上离线下载依赖包如果不能通过手机共享网络那就只能在另一台能上网的机器上把编译依赖提前下载好拷到目标机器上离线安装。在一台联网的Ubuntu 22.04机器上执行mkdir /tmp/r8125-offline cd /tmp/r8125-offline apt download build-essential dkms linux-headers-$(uname -r)注意linux-headers-$(uname -r)的版本必须和目标机器一致。如果目标机器已经能进系统可以用uname -r查看版本如果还没装好系统就比较麻烦需要提前知道目标系统对应内核版本。最简单的办法是在目标机器上装的是Ubuntu 22.04.3的话内核版本一般是5.15.0-x-generic去联网机器上apt-cache search linux-headers-5.15找到对应版本下载。把整个目录拷到目标机器后执行cd /tmp/r8125-offline sudo dpkg -i *.deb如果依赖有缺失dpkg会报错这时候补下缺失的包即可。总之离线安装的核心思路是先解决依赖再编译驱动。4.3 最原始的方案手动拷贝编译好的.ko到对应内核目录还有一种更“粗暴”的方式在另一台相同内核版本的机器上把驱动编译好直接把r8125.ko文件拷贝到目标机器的内核模块目录然后depmod -a最后modprobe r8125。# 在编译好的机器上找到模块文件 find /lib/modules/$(uname -r) -name r8125.ko # 拷贝到目标机器的相同路径 sudo cp r8125.ko /lib/modules/$(uname -r)/kernel/drivers/net/ethernet/realtek/ # 更新模块依赖 sudo depmod -a # 加载 sudo modprobe r8125这个方案有个硬性条件两台机器的内核版本必须完全一致连小版本号都不能差。因为内核模块是直接和内核数据结构和函数接口绑定的版本对不上加载时大概率会报“invalid module format”或“version magic mismatch”。所以这个方案只适合应急后续还是要配置好DKMS否则永远只能手工维护。5. 内核升级后驱动又失效之谜DKMS的自动重建机制实测5.1 为什么内核一升级第三方模块就“消失”了先弄明白一个基础概念内核模块不是通用的它和编译时对应的内核版本严格绑定。你在5.15.0-91内核下编译的r8125.ko到5.15.0-100内核下就可能加载不了。这是因为内核模块加载时会检查模块的vermagic信息包括内核版本、是否配置了SMP、是否开启了抢占等。只要有一项不匹配模块就会被拒绝加载。系统升级内核时/lib/modules/下会生成新版本的目录但第三方驱动模块不会自动出现在新目录里所以驱动就“消失”了。这也是为什么我非常不推荐直接用make make install装驱动的根本原因。官方驱动自带的autorun.sh也只是执行一次编译安装不会处理内核升级。你用这种方式装好驱动一旦apt upgrade更新了内核重启后网卡又没了只能回到终端前重新编译一遍。5.2 用一次真实的apt upgrade来验证DKMS是否自动接盘配好DKMS之后验证方式很简单。在系统提示有内核更新时正常执行sudo apt upgrade过程中如果安装了一个新内核DKMS就会自动启动编译流程把r8125模块按照新内核重新编译一遍。你会看到类似这样的输出dkms: running auto installation service for kernel 5.15.0-100-generic Building module: cleaning build area... make -C src KERNELDIR/lib/modules/5.15.0-100-generic/build...这一步就说明DKMS已经开始工作了。它会在新内核对应的/lib/modules/目录下重新生成r8125.ko。重启进入新内核后再执行dkms status lsmod | grep r8125dkms status输出里应该显示新内核版本对应的模块状态为installedlsmod也能看到r8125模块已经加载。到这一步才算真正一劳永逸地解决了驱动维护问题。5.3 没配DKMS的补救办法和“老鸟翻车”提醒如果你已经用autorun.sh或手动make方式装好了驱动现在想补上DKMS也不用把系统搞重装。把源码包重新放到/usr/src写好dkms.conf然后执行dkms add、build、install即可已经存在的r8125.ko会被覆盖不需要先卸载旧模块。我见过不少“老鸟”在这个问题上翻车内核升级到6.2或6.5之后旧的官方驱动源码编译不过去报错信息是内核API已经变了。这时候的正确做法是去Realtek官网下载新版本驱动把/usr/src下的旧版本目录删掉重新注册新版本。DKMS可以同时注册多个版本的同一模块但建议只保留一个避免dkms status里出现混乱。还有一个细节如果内核更新跨度很大比如从5.15直接升到6.5AUTOINSTALLyes只会对新安装的内核生效旧的模块记录会留在dkms status里显示built或installed但对应内核已不在系统里。这些记录可以清理掉执行sudo dkms remove -m rtl8125 -v 9.011.01 --all会去掉所有记录但如果你只是想清掉旧内核的残留不推荐用--all手动确认版本状态即可。6. 装完能上网只是第一步链路协商、性能与休眠恢复的经验补充6.1 确认网卡真的协商到2.5Gbps而不是卡在千兆驱动装好不是终点网卡能不能跑满2.5G才是很多人真正关心的。用ethtool查看当前的协商速率ethtool enp3s0输出里找Speed这一行Speed: 2500Mb/s如果这里是1000Mb/s那说明链路协商出了问题。排查思路按优先级排列网线必须是超五类以上最好六类。五类线在2.5G距离稍长时很容易协商失败。对端设备路由器、交换机的网口必须支持2.5G如果对端只有千兆口协商结果自然是1000Mb/s。网线接口接触不良也会导致协商降级可以重新插拔或换一根线测试。值得一提的是R8125支持EEEEnergy Efficient Ethernet节能以太网某些交换机和这个特性兼容不好会导致协商异常或传输延迟波动。如果遇到这种问题可以关闭EEE试试sudo ethtool --set-eee enp3s0 eee off如果确认有效可以把这条命令写入systemd服务开机自动执行。6.2 影响R8125稳定性的几个调优选项除了EEE还有几个在实际使用中影响R8125稳定性的选项需要注意。一个是中断合并interrupt coalescing。R8125驱动支持通过ethtool调整rx-usecs等参数在高PPS小包场景下默认配置可能导致CPU占用偏高或延迟偏大。普通家用场景不用动但如果你是跑软路由或NAS可以关注一下。另一个是TCP offload相关选项。在某些内核版本下开启TSO/GSO后大文件传输可能偶发丢包表现为传输速度波动明显。可以用以下命令暂时关闭并测试sudo ethtool -K enp3s0 tso off gso off如果关闭后传输稳定了说明是offload兼容问题结合自己的使用场景决定是否常驻关闭。注意这些设置重启后会失效生产环境建议写systemd服务或rc.local持久化。还有一个被很多人忽略的点R8125支持多队列官方驱动编译时默认会开启多队列支持可以通过ethtool -l enp3s0查看队列数。如果系统只有一个CPU核心多队列意义不大但如果是多核机器做转发或下载多队列能显著降低CPU占用。6.3 休眠唤醒后网卡消失怎么处理笔记本电脑或者开启了休眠的台式机从休眠唤醒后有时会发现网卡消失了。ip link里看不到接口dmesg末尾能看到r8125相关的报错。这个问题的根源一般是PCIe电源管理设备进入D3状态后唤醒时重新初始化失败。最简单的恢复方法sudo systemctl restart NetworkManager如果不行就强制重新加载模块sudo modprobe -r r8125 sudo modprobe r8125如果频繁出现唤醒后断网建议检查BIOS中PCIe ASPM主动电源管理相关设置尝试关闭ASPM或设为“Disabled”。在Linux侧也可以给内核添加启动参数pcie_aspmoff但这是全局关闭对笔记本续航有一定影响需要权衡。我个人的习惯是部署在固定场所的机器直接在BIOS里关掉ASPM和任何网卡节能选项一劳永逸。移动场景再单独测试确认。最后分享一个小经验R8125这个网卡在Linux下的口碑两极分化其实芯片本身的硬件素质不差问题大多出在驱动维护和内核集成上。只要把DKMS这套机制用起来让它自动接管驱动的滚动更新后面几年基本可以忘记“网卡驱动”这四个字。如果你按照上面流程装完后还有问题别急着删帖重发先跑一遍dmesg | grep r8125把报错贴出来比单纯描述“上不了网”有用得多。