1. 为什么值得折腾手动编译驱动这件事手上有一块 Realtek RTL8125 2.5G 网卡插在 Ubuntu 22.04 的机器上lspci能看到设备ip link却死活不出接口或者勉强认出来之后跑个 iperf3 只有几百兆、传大文件隔几分钟断一次——这种场景我遇到过不止一次。RTL8125 这颗芯片在近几年的主板、NUC、软路由、NAS 上铺得非常多2.5G 的带宽对家庭内网、小型办公环境来说性价比极高但它在 Linux 下的驱动支持一直是个老大难问题。Ubuntu 22.04 自带内核里的r8169驱动虽然能识别一部分 RTL8125但版本偏旧功能残缺性能也上不去真正能把这颗芯片跑满的是 Realtek 官方维护的r8125独立驱动。这篇内容就是把我自己在 Ubuntu 22.04 上手动编译安装 r8125 驱动的完整过程整理出来包括源码获取、编译环境准备、驱动编译安装、中断配置调优以及装完之后怎么验证、怎么排查问题。适合两类人看一类是刚接触 Linux 驱动编译、想照着一步步做下来的新手另一类是用过 r8169 但被性能和稳定性坑过、想换官方驱动但不确定细节的老手。整个过程不需要你懂内核开发但需要你愿意敲命令、看日志、动手改配置。我先把结论摆在这儿Ubuntu 22.04 默认的 r8169 驱动对 RTL8125 的支持是能用但不好用手动编译 r8125 官方驱动之后2.5G 带宽能真正跑起来中断分布也更合理长时间大流量传输的稳定性明显改善。下面从设计思路开始一步步拆。2. 整体方案设计与选型思路拆解2.1 为什么不用系统自带的 r8169 驱动Ubuntu 22.04 的内核版本是 5.15 系列这个内核里的r8169驱动确实包含了对 RTL8125 的基本支持但问题在于版本滞后内核里的 r8169 是随内核发布的Realtek 后续对 RTL8125 的很多修复和优化没有回移到 5.15 这个 LTS 分支里。你可能遇到的现象是网卡能认出来但跑不满 2.5G或者在高负载下丢包。功能缺失r8169 对 RTL8125 的一些高级特性支持不完整比如多队列、中断合并、节能以太网EEE的精细控制等。这些特性直接影响到吞吐量和 CPU 占用。中断处理粗糙默认的中断分配策略在多核机器上往往把所有中断压到一个 CPU 核上2.5G 满速时那个核直接跑满成为瓶颈。Realtek 官方维护的r8125驱动是独立于内核的更新频率高针对 RTL8125 系列做了专门优化。它的源码包在 Realtek 官网可以下载到编译出来是一个独立的r8125.ko模块加载后会接管 RTL8125 设备r8169 就不再管这块网卡了。2.2 编译安装 vs DKMS两条路怎么选手动编译安装驱动有两条路方式优点缺点适用场景直接 make 编译安装步骤少直接可控内核升级后驱动失效需重新编译内核版本固定、不常升级的机器DKMS 方式内核升级自动重编译配置稍复杂依赖 dkms 包经常升级内核的开发机、服务器我个人的选择是生产环境或长期运行的机器用 DKMS一次性配好后面内核升级不用管临时测试或内核锁定的机器直接 make 安装省事。这篇内容两种都会讲但主线走直接编译安装因为这样你能看清楚每一步在干什么理解了之后再套 DKMS 就是水到渠成的事。2.3 中断配置为什么是重点2.5G 网卡满速跑起来每秒要处理几十万个数据包。如果所有中断都落到一个 CPU 核上这个核光处理中断就忙不过来应用层拿不到 CPU 时间表现就是吞吐上不去、延迟抖动大。RTL8125 支持多队列Multi-Queue可以配置多个发送/接收队列每个队列绑定不同的中断分散到不同 CPU 核上。中断配置的核心是两件事一是让驱动启用多队列二是通过irqbalance或者手动设置中断亲和性SMP Affinity把不同队列的中断分配到不同 CPU 核。这部分如果配好了2.5G 满速时 CPU 占用能降下来一大截传输也更稳。后面会详细讲怎么查中断号、怎么绑核、怎么验证效果。3. 编译环境准备与源码获取实操3.1 确认网卡型号和当前驱动状态动手之前先确认你手上这块卡确实是 RTL8125别忙活半天发现是别的芯片。执行lspci -nn | grep -i ethernet输出里找 Realtek 相关的行RTL8125 的设备 ID 通常是10ec:8125。比如03:00.0 Ethernet controller [0200]: Realtek Semiconductor Co., Ltd. RTL8125 2.5GbE Controller [10ec:8125] (rev 05)看到10ec:8125就对了。然后看当前用的是哪个驱动lspci -k -s 03:00.0-s后面跟的是你上一步查到的 PCI 地址。输出里Kernel driver in use:那一行会告诉你现在挂的是r8169还是r8125。如果是r8169说明系统自带驱动在管我们要把它换成 r8125。再看一眼当前链路速度和状态ip link show ethtool 接口名接口名一般是enp3s0这种格式根据 PCI 地址来的。ethtool输出里Speed那一行如果是1000Mb/s而你的交换机和网线都支持 2.5G那基本可以确定是驱动拖后腿了。3.2 安装编译所需的依赖包Ubuntu 22.04 上编译内核模块需要这几个包sudo apt update sudo apt install -y build-essential linux-headers-$(uname -r) dkms逐个说明一下build-essential提供 gcc、make、libc 开发头文件等基础编译工具。没有它make直接报错。linux-headers-$(uname -r)当前运行内核的头文件。编译内核模块必须要有对应版本的头文件$(uname -r)会自动替换成你当前内核版本号。这一步最容易出问题如果 apt 源里没有完全匹配的头文件编译会失败后面常见问题部分会讲怎么处理。dkms如果你打算走 DKMS 方式就需要它直接 make 安装的话可以不装但装上没坏处。注意linux-headers的版本必须和uname -r的输出完全一致。如果你之前升级过内核但没重启uname -r显示的是旧内核而 apt 装的是新内核的头文件就会对不上。保险起见先sudo apt update sudo apt upgrade然后重启一次确保运行内核和头文件版本一致。装完之后验证一下uname -r dpkg -l | grep linux-headers两个版本号应该一致。3.3 获取 r8125 驱动源码Realtek 官方驱动源码的获取渠道有几个我一般用 Realtek 官网下载页面提供的 tarball。下载下来是一个类似r8125-9.xxx.xx.tar.bz2的压缩包。把它传到目标机器上解压tar -xjf r8125-9.xxx.xx.tar.bz2 cd r8125-9.xxx.xx解压后的目录里应该有src/子目录里面是驱动源码还有Makefile、README等文件。先看一眼 README里面通常有编译安装的简要说明和版本信息。如果你习惯用包管理的方式也可以看看 Ubuntu 的mainline或者第三方 PPA 有没有打包好的 r8125-dkms但我不太推荐因为第三方包的版本更新不一定及时而且出了问题不好排查。自己编译虽然多几步但每一步都透明。实操心得下载源码包之后先核对一下版本号。Realtek 的驱动版本迭代挺快新版本对 RTL8125 的兼容性和性能优化更好。如果官网有多个版本选最新的稳定版别选 beta 版。4. 驱动编译与安装的完整流程4.1 编译前的配置检查进入源码目录后先别急着make。看一眼src/Makefile里面有一些编译选项可以调整。常见的几个CONFIG_ASPM控制 ASPMActive State Power Management电源管理。默认可能是开启的但有些主板配合 RTL8125 开 ASPM 会导致断流可以考虑关掉。ENABLE_EEE节能以太网。2.5G 场景下建议关掉EEE 在高速率下容易引起兼容性问题。CONFIG_R8125_NAPINAPI 轮询模式默认开启保持就好。这些选项可以在make的时候通过命令行传进去比如make CONFIG_ASPMn ENABLE_EEEn也可以直接改 Makefile 里的默认值。我一般不改文件编译时传参这样源码保持干净下次编译换个参数就行。4.2 执行编译确认当前目录在源码根目录有 Makefile 的那一层执行make clean makemake clean先清一下之前的编译产物避免残留文件干扰。make开始编译正常的话几十秒到一两分钟就完了最后会生成src/r8125.ko这个内核模块文件。编译过程中如果报错最常见的是头文件路径问题。错误信息里一般会提到include/linux/...找不到这说明linux-headers没装对或者版本不匹配。回到 3.2 节检查。编译成功的话你会看到类似这样的输出make[1]: Entering directory /usr/src/linux-headers-5.15.0-xx-generic CC [M] /home/user/r8125-9.xxx/src/r8125_n.o ... LD [M] /home/user/r8125-9.xxx/src/r8125.ko make[1]: Leaving directory /usr/src/linux-headers-5.15.0-xx-generic看到r8125.ko生成就说明编译通过了。4.3 安装驱动模块编译出来的.ko文件需要放到内核模块目录里并更新模块依赖sudo make install这个命令会做几件事把r8125.ko拷贝到/lib/modules/$(uname -r)/kernel/drivers/net/ethernet/realtek/下然后运行depmod -a更新模块依赖关系。如果你想手动控制也可以自己拷贝sudo cp src/r8125.ko /lib/modules/$(uname -r)/kernel/drivers/net/ethernet/realtek/ sudo depmod -a效果一样。make install省事一点。4.4 卸载旧驱动并加载新驱动现在系统里 r8169 还在管着网卡需要先把它从内存里卸载再加载 r8125。注意如果你是通过这块网卡远程 SSH 连过去的卸载驱动会断网所以要么本地操作要么准备好带外管理。sudo modprobe -r r8169 sudo modprobe r8125如果modprobe -r r8169报错说模块正在使用可以先sudo ip link set 接口名 down再试。加载 r8125 之后检查一下lspci -k -s 03:00.0Kernel driver in use:应该变成r8125了。再看ip link接口应该还在但驱动换了。4.5 配置开机自动加载 r8125重启之后系统可能又加载回 r8169因为 r8169 是内核自带的优先级高。要确保每次开机都用 r8125需要做两件事第一把 r8169 加入黑名单echo blacklist r8169 | sudo tee /etc/modprobe.d/blacklist-r8169.conf第二把 r8125 加入开机加载列表echo r8125 | sudo tee /etc/modules-load.d/r8125.conf这样重启后系统会先屏蔽 r8169再主动加载 r8125。做完之后重启验证sudo reboot重启后再次lspci -k确认驱动是 r8125。注意黑名单 r8169 之前确认你机器上没有其他 Realtek 千兆网卡依赖 r8169。如果有黑名单会导致那块卡也认不出来。可以用lspci -nn | grep 10ec看看有几块 Realtek 网卡。5. 中断配置详解与性能调优5.1 理解 RTL8125 的中断机制RTL8125 支持多队列驱动加载后可以创建多个发送队列TX Queue和接收队列RX Queue每个队列有独立的中断号。默认情况下驱动可能只启用一个队列或者启用了多队列但中断都落在 CPU0 上。查看当前队列和中断情况# 查看接口的队列数 ethtool -l 接口名 # 查看中断号 cat /proc/interrupts | grep r8125ethtool -l会显示Pre-set maximums和Current hardware settings后者是当前实际生效的队列数。/proc/interrupts里能看到每个队列对应的中断号以及每个 CPU 核上处理了多少次中断。如果看到所有 r8125 的中断都集中在 CPU0 那一列说明中断没有分散这就是性能瓶颈所在。5.2 启用多队列并调整队列数如果当前队列数是 1可以尝试调大sudo ethtool -L 接口名 combined 4combined表示发送和接收合并计数4是队列数。具体能设多少取决于硬件和驱动ethtool -l里的Pre-set maximums会告诉你上限。一般 2.5G 网卡设 2 到 4 个队列就够了设太多反而增加开销。设置完之后再ethtool -l确认然后看/proc/interrupts应该能看到多个 r8125 中断号了。5.3 中断亲和性绑定把中断分到不同 CPU 核多队列启用了但中断还是可能都落在 CPU0。需要手动设置中断亲和性SMP Affinity。每个中断号在/proc/irq/中断号/smp_affinity里有一个掩码表示允许哪些 CPU 处理这个中断。先列出所有 r8125 的中断号grep r8125 /proc/interrupts | awk -F: {print $1} | tr -d 假设输出是130 131 132 133对应 4 个队列。然后逐个绑定到不同 CPU# 队列0绑到CPU0 echo 1 | sudo tee /proc/irq/130/smp_affinity # 队列1绑到CPU1 echo 2 | sudo tee /proc/irq/131/smp_affinity # 队列2绑到CPU2 echo 4 | sudo tee /proc/irq/132/smp_affinity # 队列3绑到CPU3 echo 8 | sudo tee /proc/irq/133/smp_affinity这里的掩码是十六进制位图1是 CPU02是 CPU14是 CPU28是 CPU3以此类推。也可以用smp_affinity_list直接写 CPU 编号更直观echo 0 | sudo tee /proc/irq/130/smp_affinity_list echo 1 | sudo tee /proc/irq/131/smp_affinity_list设置完之后cat /proc/interrupts观察一段时间看中断是否分散到了不同 CPU 列。5.4 用 irqbalance 自动管理还是手动绑定irqbalance是一个自动中断负载均衡的服务Ubuntu 默认可能已经装了。它会根据负载动态调整中断亲和性。对于通用场景irqbalance 够用但对于网卡这种高吞吐场景手动绑定往往更稳定因为 irqbalance 可能在负载变化时把中断挪来挪去引起抖动。我的做法是如果机器上只有这一块高速网卡手动绑定如果有多块网卡或者中断源复杂用 irqbalance 并配置它忽略 r8125 的中断。配置 irqbalance 忽略特定中断可以在/etc/irqbalance.conf里加IRQBALANCE_BANNED_INTERRUPTS130,131,132,133。5.5 中断合并参数调优中断合并Interrupt Coalescing控制网卡攒多少个包或者等多长时间才发一次中断。攒得多CPU 中断次数少但延迟高攒得少延迟低但 CPU 占用高。2.5G 大流量场景下适当增大合并参数能降低 CPU 占用。查看当前参数ethtool -c 接口名调整接收和发送的合并参数sudo ethtool -C 接口名 rx-usecs 50 tx-usecs 50rx-usecs是接收中断的最大等待微秒数tx-usecs是发送的。默认值可能很小调到 50 到 100 之间通常是个平衡点。具体多少合适要结合你的实际负载测没有万能值。实操心得中断合并参数调大之后用iperf3测吞吐可能变化不大但用top看 CPU 的si软中断占用会明显下降。如果你的应用对延迟敏感比如游戏、实时通信别调太大50 微秒以内比较安全。6. 验证、测试与常见问题排查6.1 验证驱动版本和链路状态装完之后先确认基本信息# 驱动版本 modinfo r8125 | grep version # 链路状态 ethtool 接口名 | grep -E Speed|Duplex|Link detectedSpeed应该是2500Mb/sLink detected是yes。如果还是1000Mb/s检查网线需要 Cat5e 以上、交换机端口是否支持 2.5G、以及是否协商失败。6.2 用 iperf3 实测吞吐找另一台机器做 iperf3 测试。服务端iperf3 -s客户端iperf3 -c 服务端IP -t 30 -P 4-t 30跑 30 秒-P 4开 4 个并行流。2.5G 网卡理想情况下应该跑到 2.3Gbps 左右扣除协议开销。如果只有 1Gbps 出头说明还有瓶颈回去检查中断配置和队列数。测试时同时开一个终端看 CPUtop -d 1观察si那一列的占用。如果某个核的si接近 100%说明中断还是集中了回去检查亲和性绑定。6.3 常见问题速查表现象可能原因排查方法解决方法编译报错找不到头文件linux-headers 版本不匹配uname -r对比dpkg -l | grep headers安装对应版本头文件或重启到匹配内核modprobe r8125 报错模块依赖未更新dmesg | tail看错误运行sudo depmod -a重启后驱动变回 r8169黑名单未生效lspci -k确认检查/etc/modprobe.d/下黑名单文件链路只有 1Gbps网线或交换机限制ethtool看协商结果换 Cat5e 以上网线检查交换机端口大流量传输断流ASPM 或 EEE 兼容性问题dmesg看有无 link down 日志编译时关掉 ASPM 和 EEE中断全在 CPU0多队列未启用或亲和性未设cat /proc/interrupts启用多队列手动绑定亲和性吞吐上不去但 CPU 不高中断合并参数过小ethtool -c查看适当增大 rx-usecs/tx-usecs6.4 几个我踩过的坑坑一头文件版本对不上。有次我apt upgrade之后没重启uname -r还是旧内核但linux-headers装的是新版本编译直接失败。后来养成习惯编译驱动前先重启一次确保运行内核和头文件一致。坑二黑名单 r8169 导致另一块网卡失效。有台机器上除了 RTL8125 还有一块板载 Realtek 千兆卡也是 r8169 驱动。我黑名单之后那块卡直接不认了。解决办法是用pcinoacpi之类的参数不现实正确做法是只针对特定设备黑名单或者干脆不黑名单靠/etc/modules-load.d/里 r8125 的加载顺序来抢设备。实测下来只要 r8125 先加载r8169 就不会再接管 RTL8125。坑三中断绑定重启后失效。/proc/irq/下的设置是临时的重启就没了。要持久化可以写个 systemd service 或者 udev rule在网卡上线后自动执行绑定脚本。我一般写个简单的 systemd unitAfternetwork.targetExecStart 跑一个绑定脚本。坑四DKMS 方式下内核升级后驱动没自动编译。DKMS 虽然能自动重编译但前提是linux-headers也自动装了。有些最小化安装的系统没装linux-headers-generic这个元包内核升级后头文件没跟上DKMS 编译失败但你可能没注意。定期dkms status检查一下。7. 内核升级后的维护与 DKMS 方案补充7.1 直接编译安装的维护成本直接make install装的驱动内核一升级就失效因为新内核的模块目录里没有 r8125.ko。表现是升级重启后网卡又变回 r8169或者干脆不认。解决办法是每次内核升级后重新编译安装一遍。如果你机器内核不常升级这不算大问题如果经常升级还是上 DKMS。7.2 切换到 DKMS 管理的步骤DKMS 的思路是把驱动源码注册到 DKMS 框架里每次内核更新DKMS 自动为新内核编译一遍。操作步骤把源码目录放到/usr/src/下命名规范是模块名-版本sudo cp -r r8125-9.xxx.xx /usr/src/r8125-9.xxx.xx然后在源码目录里创建dkms.confPACKAGE_NAMEr8125 PACKAGE_VERSION9.xxx.xx BUILT_MODULE_NAME[0]r8125 DEST_MODULE_LOCATION[0]/kernel/drivers/net/ethernet/realtek AUTOINSTALLyes注意PACKAGE_VERSION要和目录名里的版本一致。然后注册并编译sudo dkms add -m r8125 -v 9.xxx.xx sudo dkms build -m r8125 -v 9.xxx.xx sudo dkms install -m r8125 -v 9.xxx.xx之后dkms status应该能看到 r8125 已安装。内核升级后DKMS 会自动为新内核编译前提是新内核的 headers 已经安装。7.3 验证 DKMS 是否正常工作模拟一次内核升级比较麻烦简单的验证方法是sudo dkms status输出里 r8125 应该显示installed并且对应你当前内核版本。如果显示built但没installed说明编译成功但没装到模块目录手动dkms install一下。实操心得DKMS 虽然省心但有个坑是源码目录权限。/usr/src/下的目录如果权限不对DKMS 编译时可能写不进去。确保目录属主是 root权限 755。另外dkms.conf里的DEST_MODULE_LOCATION路径要和实际模块安装路径一致写错了模块会装到奇怪的地方。8. 一些收尾的实用建议整个流程走下来最花时间的其实不是编译本身而是排查各种环境问题——头文件版本、驱动冲突、中断绑定。我的建议是动手之前先把机器的内核版本、网卡型号、当前驱动状态摸清楚把linux-headers装对后面就顺了。中断配置这块别一上来就追求极致调优。先把多队列启用了看看/proc/interrupts分布如果已经分散了就不用折腾亲和性。只有发现中断集中、CPU 单核跑满的时候才需要手动绑核。中断合并参数也是默认值先用着测出来 CPU 占用高再调。最后分享一个小技巧如果你不确定某个参数改了之后有没有效果用ethtool -S 接口名看统计计数器里面有队列的包数、丢包数、中断次数等。改参数前后对比这些计数器比凭感觉判断靠谱得多。比如调了中断合并之后rx_interrupts计数应该下降而rx_packets不变说明合并生效了。这套流程我在好几台机器上复现过Ubuntu 22.04 加 RTL8125 的组合按这个步骤走基本都能跑通。遇到问题优先看dmesg驱动加载、链路协商、中断注册的信息都在里面比瞎猜快得多。
