1. 为什么一块2.5G网卡值得你花半小时手动编译驱动
手里有块Realtek RTL8125的2.5G网卡，插上Ubuntu 22.04之后lspci能看到设备，但ip link里死活不出网口，或者出来了却只能跑在1G甚至100M——这个场景我遇到过不止一次。RTL8125这颗芯片在消费级主板和USB/PCIe网卡里铺货量极大，2.5G的带宽对家庭NAS、内网大文件传输、软路由来说都是实打实的提升，但它在Linux下的驱动支持一直是个"半吊子"状态：内核自带的r8169驱动虽然能认，但经常出现协商速率上不去、断流、大流量下丢包的问题，真正稳的是Realtek官方维护的r8125独立驱动。
这篇内容就是把我自己反复折腾RTL8125的过程完整记录下来，从确认硬件、装编译环境、拉源码、编译安装，一直到中断配置的调优，全部走一遍。适合两类人看：一是刚装完Ubuntu 22.04发现网卡不对劲的新手，二是想让2.5G网卡真正跑满、而不是"能上网就行"的折腾党。整个过程不需要你懂内核开发，但需要你愿意敲命令、看得懂报错。我会把每一步"为什么这么做"讲清楚，因为照着命令抄谁都会，出了问题能自己定位才是关键。
先说结论：Ubuntu 22.04默认内核（5.15/5.19系列）自带的r8169对RTL8125的支持是"能用但不理想"，官方r8125驱动在稳定性、速率协商、中断处理上都更靠谱。手动编译安装并不复杂，真正的坑集中在编译环境缺失、Secure Boot拦截、驱动冲突、中断绑定这几个地方，下面逐个拆。
2. 动手之前：先把硬件和系统底细摸清楚
2.1 确认你的网卡到底是不是RTL8125
别急着下驱动，第一步永远是确认硬件型号。很多人拿到的是RTL8125B、RTL8125BG，或者干脆是RTL8168/8111（千兆），驱动装错了白忙活。用下面这条命令看：
lspci -nn | grep -i ethernet输出里会带厂商和设备ID，Realtek的2.5G网卡通常长这样：
03:00.0 Ethernet controller [0200]: Realtek Semiconductor Co., Ltd. RTL8125 2.5GbE Controller [10ec:8125] (rev 05)关键看方括号里的[10ec:8125]，10ec是Realtek的厂商ID，8125是设备ID。如果是[10ec:8168]那就是千兆的RTL8168，别装8125的驱动。rev后面的版本号（01/05等）代表芯片修订版本，官方驱动一般都能覆盖，但太老的rev偶尔有兼容问题，记下来备用。
顺便看一眼当前用的是哪个驱动：
lspci -k | grep -A 3 -i ethernet会显示Kernel driver in use: r8169之类的信息。如果显示的是r8169，说明系统用的是内核自带驱动，这正是我们要替换掉的对象。
2.2 系统版本和内核版本要心里有数
Ubuntu 22.04的默认内核是5.15，后续更新可能到5.19或6.x。内核版本直接影响编译驱动时的头文件匹配，所以必须确认：
uname -r lsb_release -auname -r给出的是当前运行的内核版本，比如5.15.0-91-generic。这个信息后面装linux-headers的时候要用到，版本必须严格对应，否则编译出来的模块加载会报invalid module format。
提示：如果你最近升级过内核但还没重启，
uname -r显示的是旧内核，而/lib/modules下可能已经有新内核的目录了。编译前最好重启一次，确保运行内核和头文件一致。
2.3 编译环境：别等报错了才想起来装
手动编译内核模块需要build-essential、gcc、make和对应版本的内核头文件。Ubuntu 22.04最小化安装或者Server版经常缺这些，我建议一次性装齐：
sudo apt update sudo apt install -y build-essential gcc make linux-headers-$(uname -r) dkms这里解释几个选择：
linux-headers-$(uname -r)：这是编译模块的必需品，里面包含内核的配置和符号表。用$(uname -r)自动匹配当前内核，避免手打版本号出错。dkms：Dynamic Kernel Module Support。装它不是为了这次编译，而是为了以后内核升级时能自动重新编译驱动。RTL8125这种第三方驱动，内核一升级就失效是常态，有了DKMS能省很多事。虽然本文走的是手动编译路线，但DKMS作为兜底值得装上。build-essential：包含gcc、make、libc-dev等一整套编译工具链，缺了它make会直接报错。
装完验证一下：
gcc --version make --version ls /lib/modules/$(uname -r)/build最后一条如果能看到目录内容（而不是"No such file"），说明头文件就位了。
2.4 Secure Boot：最容易让人卡住的隐形墙
这一步很多人会忽略，然后编译一切正常，modprobe却报Operation not permitted或者模块加载后网卡依然不工作。原因就是Secure Boot在拦截未签名的内核模块。
先查状态：
mokutil --sb-state如果输出SecureBoot enabled，你有两个选择：
- 进BIOS关掉Secure Boot：最简单，适合个人机器、测试环境。重启进BIOS，在Security或Boot选项里找到Secure Boot设为Disabled。
- 给模块签名：保留Secure Boot，用
mokutil和sign-file给编译出的.ko文件签名。流程稍复杂，适合不能关Secure Boot的生产环境。
我个人在自用机器上直接关Secure Boot，省事。如果是公司设备或者双系统（尤其和Windows共存）不方便关，那就走签名流程。本文主线按关闭Secure Boot来讲，签名作为补充在后面的章节提。
3. 拿到官方驱动源码：版本选择和下载的讲究
3.1 为什么不用内核自带的r8169
先把这个疑问解决掉。内核里的r8169驱动是社区维护的，它确实支持RTL8125，但支持程度参差不齐。我实测下来主要问题有三个：
- 速率协商不稳：插上千兆交换机偶尔协商成100M，或者2.5G环境下跑不满。
- 大流量断流：NAS持续传输几十GB文件时，偶发link down再up。
- 中断处理粗糙：默认配置下中断全压在CPU0，多核机器上单核跑满、其他核闲着。
Realtek官方的r8125驱动针对自家芯片做了优化，中断合并、多队列、速率协商都更细致。所以只要你对网络稳定性有要求，换官方驱动是值得的。
3.2 从哪拿源码，选哪个版本
Realtek官方驱动发布在他们的官网（搜索"Realtek PCIe FE / GbE / 2.5GbE / 5GbE / 10G Ethernet Family Controller Software"），下载页面里找Linux版本的r8125。截至我写这篇时，稳定版本在9.011到9.013之间。
选版本的原则：
- 优先选最新稳定版：新版本修复了老版本的bug，对新内核兼容性更好。
- 看发布日期：如果最新版发布没多久，而你用的是较老内核，可以退一个版本，避免新驱动用了老内核没有的API。
- 别用太老的版本：比如9.004这种，对5.15内核的支持可能有问题。
下载下来是个tar.gz包，比如r8125-9.013.02.tar.gz。如果你在无网络的机器上操作，提前在能上网的机器下好，用U盘拷过去。
3.3 解压和目录结构速览
tar -xzf r8125-9.013.02.tar.gz cd r8125-9.013.02 ls你会看到类似这样的结构：
Makefile README src/ r8125.h r8125_n.c r8125_rss.c ...src/里是驱动源码，Makefile是编译脚本。先扫一眼README，里面通常有编译和安装的官方说明，虽然写得比较简略，但版本相关的注意事项会在这里提。
注意：解压后的目录路径里不要有中文或空格，否则
make可能因为路径解析问题报错。放在~/r8125或者/usr/local/src/r8125这种干净路径下最稳妥。
4. 编译与安装：每一步都在做什么
4.1 make之前先理解Makefile在干嘛
直接sudo ./autorun.sh或者make当然能跑，但我想让你知道背后发生了什么，出问题时才好定位。打开Makefile看关键部分，它主要做几件事：
- 检测当前内核版本和头文件路径（
/lib/modules/$(uname -r)/build）。 - 调用内核的kbuild系统编译
src/下的源码，生成r8125.ko。 - 根据配置决定是否启用多队列、RSS（接收端缩放）等特性。
编译命令本质上是：
make -C /lib/modules/$(uname -r)/build M=$(pwd)/src modules-C切到内核源码目录，M=指定外部模块路径，modules是kbuild的目标。理解这个，你就知道为什么头文件版本必须匹配——kbuild要用内核的构建系统。
4.2 正式编译
在驱动目录下执行：
make clean makemake clean先清掉可能残留的旧编译产物，避免版本混淆。make开始编译，正常的话最后会输出：
LD [M] /home/user/r8125-9.013.02/src/r8125.ko看到r8125.ko生成就成功了。如果报错，常见的有：
| 报错信息 | 原因 | 解决 |
|---|---|---|
No such file or directory: /lib/modules/.../build | 内核头文件没装 | sudo apt install linux-headers-$(uname -r) |
error: implicit declaration of function | 驱动版本和新内核API不兼容 | 换驱动版本，或打补丁 |
Permission denied | 没用sudo或目录权限问题 | 检查目录归属，必要时sudo make |
gcc: command not found | 编译工具链缺失 | sudo apt install build-essential |
编译过程一般几十秒到一两分钟，取决于机器性能。
4.3 安装模块并处理驱动冲突
编译出的r8125.ko要装到系统模块目录，同时必须阻止r8169抢占设备，否则两个驱动会打架。步骤：
sudo make install这个命令会把r8125.ko复制到/lib/modules/$(uname -r)/kernel/drivers/net/ethernet/realtek/，并运行depmod更新模块依赖。
然后屏蔽r8169：
echo "blacklist r8169" | sudo tee /etc/modprobe.d/blacklist-r8169.conf再让系统优先加载r8125：
echo "r8125" | sudo tee /etc/modules-load.d/r8125.conf这两步的逻辑：blacklist告诉系统别自动加载r8169，modules-load确保开机加载r8125。做完之后，卸载当前驱动再重新加载：
sudo modprobe -r r8169 sudo modprobe r8125如果r8169正在使用中卸不掉，先sudo ip link set <网卡名> down，或者直接重启。
4.4 验证驱动是否生效
重启后（或者手动加载后），检查：
lspci -k | grep -A 3 -i ethernet应该看到Kernel driver in use: r8125。再看网口：
ip link show ethtool <网卡名>ethtool输出里Speed: 2500Mb/s说明速率协商正确。如果还是1000或100，检查网线（Cat5e以上才支持2.5G）、对端设备（交换机/路由器端口是否2.5G）、以及ethtool里的Advertised link modes是否包含2500baseT。
5. 中断配置：让2.5G网卡真正跑满的关键
5.1 为什么中断配置决定性能上限
网卡收发包靠中断通知CPU。默认情况下，很多驱动把所有中断都绑到CPU0，2.5G满速时每秒几十万包，CPU0直接被中断打满，其他核心闲着，结果就是吞吐上不去、延迟抖动大。这就是"网卡是2.5G，实际只能跑1G"的常见原因之一。
RTL8125支持多队列（Multi-Queue）和MSI-X中断，可以把不同队列的中断分散到不同CPU核心，实现并行处理。配置好中断，是榨干2.5G带宽的核心操作。
5.2 先看中断现状
cat /proc/interrupts | grep r8125输出类似：
45: 1234567 0 0 0 PCI-MSI 524288-edge r8125 46: 2345678 0 0 0 PCI-MSI 524289-edge r8125 ...每一行是一个中断，后面几列是各CPU核心处理的中断数。如果只有第一列有数字，说明全压在CPU0上，这就是要优化的点。
看网卡支持几个队列：
ethtool -l <网卡名>输出里的Combined就是当前队列数，Pre-set maximums是硬件上限。RTL8125一般支持4个队列左右。
5.3 开启多队列并调整队列数
如果队列数不是最大值，可以调：
sudo ethtool -L <网卡名> combined 4把队列数设成4（按硬件上限来）。队列多了，中断源就多，才能分散。
5.4 用irqbalance还是手动绑核
有两个思路：
思路一：交给irqbalance。Ubuntu默认装了irqbalance服务，它会自动把中断分散到各核心。检查是否运行：
systemctl status irqbalance如果没装，sudo apt install irqbalance。对大多数场景，irqbalance够用，省心。
思路二：手动绑核。对性能敏感的场景（比如软路由、高频交易），手动把每个中断绑到固定核心，避免irqbalance动态调整带来的抖动。先找到每个中断号，再写smp_affinity：
# 查看中断号 grep r8125 /proc/interrupts # 把中断45绑到CPU1（掩码0x2） echo 2 | sudo tee /proc/irq/45/smp_affinity # 把中断46绑到CPU2（掩码0x4） echo 4 | sudo tee /proc/irq/46/smp_affinitysmp_affinity是十六进制掩码，CPU0对应1，CPU1对应2，CPU2对应4，CPU3对应8，以此类推。绑核的原则是避开处理其他重负载的核心，比如别和你的应用主线程抢同一个核。
提示：手动绑核重启后会失效。要持久化，可以写个systemd服务或者udev规则，在网卡上线后自动执行绑核脚本。
5.5 中断合并：吞吐和延迟的权衡
中断合并（Interrupt Coalescing）让网卡攒一批包再发一次中断，减少中断次数、提升吞吐，代价是增加一点延迟。查看当前设置：
ethtool -c <网卡名>调整接收和发送的合并参数：
sudo ethtool -C <网卡名> rx-usecs 50 tx-usecs 50rx-usecs 50表示收到包后最多等50微秒再发中断。数值越大吞吐越高、延迟越大。文件传输、NAS场景可以设大点（100-200），游戏、实时通信设小点（10-30）甚至关闭。这个没有标准答案，得按你的实际负载调。
5.6 实测对比：配置前后的差距
我在一台4核机器上做过对比，用iperf3打流：
| 配置 | 吞吐 | CPU0占用 |
|---|---|---|
| 默认（单队列，中断全在CPU0） | 1.6 Gbps | 95% |
| 开启4队列 + irqbalance | 2.35 Gbps | 40% |
| 4队列 + 手动绑核 + 合并调优 | 2.42 Gbps | 25% |
差距很明显。默认配置下CPU0是瓶颈，优化后接近2.5G线速，CPU还有余量。这就是中断配置的价值。
6. 踩过的坑和那些文档不会告诉你的事
6.1 内核升级后驱动失效
这是最常见的"回魂"问题。Ubuntu自动更新内核后，r8125.ko还在旧内核的目录里，新内核找不到驱动，网卡又回到r8169或者干脆没网。解决办法有两个：
- 装DKMS：把驱动源码放到
/usr/src/r8125-<版本>/，写个dkms.conf，dkms add/build/install，之后内核升级会自动重编。 - 手动重编：每次内核升级后，重新
make && make install。麻烦但可控。
我建议装DKMS，一劳永逸。Realtek的驱动包里有些版本自带dkms.conf，直接sudo ./dkms-install.sh就行。
6.2 网卡名变了导致配置失效
换了驱动之后，网卡名可能从enp3s0变成eth0或者别的。如果你在/etc/netplan/或者/etc/network/interfaces里写死了旧名字，网络配置就失效了。用ip link确认新名字，改配置文件。更稳的做法是用MAC地址绑定网卡名，写udev规则。
6.3 双系统下Windows的快速启动搞鬼
Windows的"快速启动"（Fast Startup）会让网卡在关机时处于半休眠状态，切到Linux后网卡初始化异常，表现为驱动加载了但网口不通。进Windows电源选项关掉快速启动，或者每次切换系统前完整关机。
6.4 编译报错别慌，先看内核日志
模块加载失败时，dmesg是最有用的工具：
sudo dmesg | tail -50r8125相关的报错会在这里，比如Unknown symbol（符号不匹配，通常是头文件版本不对）、module verification failed（Secure Boot拦截）。对着报错搜，比瞎猜快得多。
6.5 别在生产环境直接替换
如果你在远程管理一台服务器，替换网卡驱动有断网风险。稳妥流程是：先确认有带外管理（IPMI、串口）或者物理接触，再操作。替换前把新驱动编译好、测试加载成功，再改blacklist和开机加载配置，最后重启验证。别在只有SSH一条路的时候贸然modprobe -r当前网卡驱动。
7. 收尾：几个我常用的验证和回滚手段
装完之后，我习惯做一轮完整验证：ethtool看速率和队列、iperf3打流看吞吐、cat /proc/interrupts看中断分布、dmesg看有没有报错。这套下来基本能确认驱动工作正常。
万一要回滚，也简单：删掉/etc/modprobe.d/blacklist-r8169.conf和/etc/modules-load.d/r8125.conf，sudo make uninstall（驱动目录下执行），重启后系统回到r8169。所以操作前把这两个配置文件的路径记好，回滚就是删文件的事。
最后分享一个我自己的小习惯：把整个编译安装过程写成一个脚本，包括装依赖、下载、编译、配置blacklist、绑核，存起来。下次换机器或者重装系统，一条命令跑完，比翻教程快得多。RTL8125这卡折腾一次就够了，脚本化之后就是几分钟的事。
