企业官网建设流程全解析

最近给一台新装的主机部署Ubuntu 22.04，用的是一块Realtek R8125 2.5G网卡，本来觉得这是再常见不过的硬件，结果从系统装完到网络稳定跑满速，前前后后折腾了小半天。驱动编译报错、开机丢驱动、内核升级后失效、Secure Boot卡签名验证，这些坑基本踩了个遍。写这篇文章就是把整个安装过程、DKMS自动编译配置、以及各种报错排查方案做个完整复盘，给同样被R8125折磨的朋友一份能直接照抄的答案。

Ubuntu 22.04的内核默认使用r8169驱动来处理Realtek全系列网卡，理论上能驱动R8125，但实测2.5G速率协商不稳定、断流、掉速的情况非常多。尤其跑到2.5G满速时，r8169经常出现RX队列丢包，CPU占用还高。想让这块网卡稳定工作，正确操作是使用Realtek官方发布的r8125驱动源码，自己编译并注册到DKMS里，让内核升级后驱动能自动重新编译。

1. 网卡识别与安装前准备：先确认硬件再动手

1.1 用lspci确认网卡型号，避免装错驱动

网上很多人一上来就下载驱动包编译，结果编译报错或者装上没反应，最后发现网卡根本不是R8125。R8125芯片在系统里可能显示为RTL8125或RTL8168，因为Realtek共用驱动框架，判断起来有点迷惑性。

先用这个命令确认实际硬件型号：

lspci -vnn | grep -i ethernet

正常能看到类似输出：

05:00.0 Ethernet controller [0200]: Realtek Semiconductor Co., Ltd. RTL8125 2.5GbE Controller [10ec:8125] (rev 05)

重点关注设备ID：[10ec:8125]。如果是10ec:8168，那是RTL8168 1G网卡，驱动包就不一样；如果出现的是10ec:8126，那是RTL8126 5G网卡，同样不能用R8125的驱动包硬装。这一步花一分钟确认，后面能省一个小时。

1.2 安装编译环境和内核头文件

编译驱动必须有完整的内核头文件和编译工具链。很多人报错unable to find kernel headers，就是这步没做好。在Ubuntu 22.04上执行：

sudo apt update sudo apt install -y build-essential dkms linux-headers-$(uname -r)

注意linux-headers-$(uname -r)这种写法，它会自动匹配当前运行的内核版本。如果你升级过内核，重启前后头文件目录不一致，编译就会失败。

1.3 下载官方R8125驱动源码包

Realtek官方驱动在官网有发布，文件名通常是r8125-x.x.x.tar.gz，例如r8125-9.012.04-1.tar.gz。不要从第三方博客或网盘下载，版本新旧不说，还有被植入恶意代码的风险。

下载后解压到工作目录：

tar -xvf r8125-*.tar.gz cd r8125-*/

这里强调一下为什么要用官方源码包而不是直接加内核参数禁用r8169：官方驱动对R8125芯片的PHY配置、EEE节能策略、2.5G速率协商做了专门优化，内部有大量针对RTL8125的私有寄存器设置，这些是内核通用驱动r8169没有的。速度是关键，2.5G网卡本身就是为了跑满千兆以上的内网吞吐量，用r8169驱动能通但跑不满，那就失去意义了。

2. 官方R8125驱动安装流程与参数验证

2.1 快速安装：autorun.sh脚本的实际操作

Realtek驱动包自带一个autorun.sh脚本，它会自动完成编译、加载、复制到系统模块目录这三个动作。对于大多数用户，直接执行：

sudo ./autorun.sh

这个脚本内部做的事情是：先卸载系统里的r8169或r8125旧模块，然后执行make编译，将生成的r8125.ko复制到/lib/modules/$(uname -r)/kernel/drivers/net/ethernet/realtek/，最后执行depmod -a更新模块依赖。

脚本执行完，用lsmod | grep r8125确认模块加载状态。如果能看到类似输出：

r8125 191692 0

并且ip addr里网卡已经显示为eth0或enp5s0，物理层状态是UP，说明驱动已经生效。

2.2 手动编译安装的完整命令参考

如果你想更精细地控制安装过程，或者方便后续排查问题，推荐手动分步操作。这样每个阶段报错都能精准定位：

# 1. 清理旧模块，避免冲突 sudo modprobe -r r8169 sudo modprobe -r r8125 # 2. 编译 make clean make # 3. 安装到当前内核模块目录 sudo make install # 4. 刷新模块依赖 sudo depmod -a # 5. 加载驱动 sudo modprobe r8125

make install这里有个细节：它只会把模块安装到当前运行的内核版本目录下。如果你系统里有多个内核版本，只装这个版本的话，切到别的内核还是会丢驱动。这也是后面必须配DKMS的核心原因。

2.3 检查网卡速率协商与基本连通性

驱动装完不等于万事大吉，还要验证协商速率。用ethtool查看：

sudo ethtool enp5s0

重点关注Speed: 2500Mb/s这一行。如果显示Speed: 1000Mb/s或100Mb/s，说明协商没到2.5G，一般原因是对端设备不支持或者网线质量不行。R8125对线材质量比较敏感，六类线起步，超五类勉强，劣质线直接协商失败。

联通性测试，建议用iperf3打流验证，不要只看ping通就完事：

iperf3 -c 192.168.1.10 -t 30

局域网内iperf3打流如果稳定在2.3Gbps以上，驱动状态才算真正达标。如果掉到几百Mbps，优先检查网线、交换机端口和两端设备的EEE节能设置。

3. DKMS自动编译配置：内核升级不再丢驱动

3.1 为什么必须用DKMS：内核升级与驱动失效的因果关系

手动安装驱动最大的坑在于：内核模块与内核版本严格绑定。Ubuntu每次升级内核，旧模块在/lib/modules下的路径会整体更换，你之前手动拷贝的r8125.ko在新内核目录里根本不存在。系统启动时modprobe找不到模块，网卡就变成未识别状态，表现为开机后没有网络。

DKMS（Dynamic Kernel Module Support）就是解决这个问题的标准方案。它把驱动源码纳入一个独立的管理目录，在系统安装新内核后自动触发一次针对新内核的编译，然后把生成的新模块安装到对应目录下。简单说，DKMS就是给内核模块装了一个自动重编译家政服务，内核换一版，它帮你重新建一版模块，完全不用手动干预。

3.2 配置dkms.conf文件：关键参数逐项解释

要让驱动包被DKMS识别，必须在解压出来的源码目录里建一个dkms.conf配置文件。官方源码包默认带了一份，但缺省参数经常有问题。我个人推荐手动创建一份标准配置：

sudo nano dkms.conf

写入以下内容：

PACKAGE_NAME="r8125" PACKAGE_VERSION="9.012.04" BUILT_MODULE_NAME[0]="r8125" DEST_MODULE_LOCATION[0]="/kernel/drivers/net/ethernet/realtek" AUTOINSTALL="yes" MAKE[0]="make" CLEAN="make clean"

几个关键参数解释一下：

• PACKAGE_NAME是标识名，随便定义，但建议与驱动名一致。
• PACKAGE_VERSION必须与源码版本对应，否则DKMS会报版本不一致。版本号可以在源码目录的Makefile里查到，通常有DRIVER_VERSION变量。用grep DRIVER_VERSION Makefile查看确认。
• BUILT_MODULE_NAME指定编译生成的模块文件名，R8125编译出来是r8125.ko。
• DEST_MODULE_LOCATION表示模块安装到内核目录树下的位置，路径写错的话系统起来还是找不到。
• AUTOINSTALL="yes"是让DKMS在新内核安装后自动执行编译，这是配置自动化的核心开关。

3.3 注册模块到DKMS并验证状态

执行以下命令把驱动源码注册到DKMS：

sudo dkms add . sudo dkms build -m r8125 -v 9.012.04 sudo dkms install -m r8125 -v 9.012.04

注意第一行的dkms add .，这个点是当前目录。DKMS会把源码复制到/usr/src/r8125-9.012.04/下统一管理。build过程中如果没有任何报错，dkms status输出应该是：

r8125/9.012.04, 5.15.0-91-generic, x86_64: installed

installed状态表示当前内核版本的模块已经编译并安装成功。这里有个常见的坑：dkms build报No such file or directory错误时，大概率是dkms.conf里的PACKAGE_VERSION与实际源码目录名不一致，仔细对照检查即可。

3.4 完整自动化：结合驱动黑名单实现开机稳定加载

R8125驱动和内核自带的r8169模块存在竞争关系。系统启动时如果先加载了r8169，即使DKMS把r8125装好了，也可能因为r8169占用了PCI设备导致r8125加载失败。因此需要把r8169加入黑名单：

sudo nano /etc/modprobe.d/blacklist-r8169.conf

写入：

blacklist r8169

保存后执行sudo update-initramfs -u更新initramfs镜像。这一步非常关键，如果不执行，重启后黑名单配置不会生效。

然后配置模块自动加载：

echo "r8125" | sudo tee /etc/modules-load.d/r8125.conf

这段操作的含义是：确保系统每次都加载r8125模块，同时彻底阻止r8169抢占设备。两个文件配合，才能保证重启后网卡稳定在R8125驱动下工作。

4. 安装过程中的常见报错与排查实践

4.1 Secure Boot导致模块被拒载：MOK签名处理

这个问题在Ubuntu 22.04上非常高频。如果你的系统开启了Secure Boot（UEFI安全启动），运行modprobe r8125时很可能会报：

Lockdown: modprobe: Loading of unsigned module is blocked

原因是Secure Boot只允许加载经过签名验证的内核模块。解决方法两个：

第一个方法是进BIOS关闭Secure Boot。注意不同主板表述不同，有的叫Secure Boot Control，有的叫Security Boot，设为Disabled即可。

第二个方法是给模块签名。如果不想关Secure Boot，可以生成一对密钥并注册到MOK（Machine Owner Key）列表：

sudo apt install mokutil sudo mokutil --import /path/to/your/private-key.der

签名过程比较繁琐，需要重启进入MOK管理界面完成确认。我更推荐直接关闭Secure Boot，对个人桌面系统影响不大，省时省力。

4.2 编译报错详解：从缺少头文件到Makefile兼容问题

最常见的编译报错是：

fatal error: linux/version.h: No such file or directory

这是内核头文件没装或者路径不对。确认一下：

ls /lib/modules/$(uname -r)/build

如果这个目录不存在或者指向空路径，执行：

sudo apt install linux-headers-$(uname -r)

再有一种情况是驱动包太老，对5.15内核的兼容性有问题，报错信息里能看到unknown symbol之类的字样。这时建议换更新版本的官方驱动包，或者直接编辑Makefile，在高版本gcc下去掉一些废弃的编译flag。

4.3 模块加载失败：网卡设备被占用问题

有时候r8169黑名单配好了，但r8125加载还是失败，报错显示：

r8125: probe of 0000:05:00.0 failed with error -22

这个-22表示EINVAL，通常是网卡被其他驱动占用，或者PCI设备状态异常。先检查当前占用情况：

lspci -k -s 05:00.0

输出里可以看到Kernel driver in use。如果显示r8169，说明黑名单没生效，或者模块已经被手动加载。执行：

sudo modprobe -r r8169 sudo modprobe r8125

再查看dmesg | tail确认加载信息。这种问题一般不是驱动本身的问题，是模块加载顺序管理不到位。

4.4 网卡WOL和节能导致的断网问题：iptables与ethtool辅助排查

安装完驱动后，部分用户遇到开机一段时间后网卡断流，ping不通，但网卡状态还是显示UP。这种情况八成是网卡的EEE（Energy Efficient Ethernet）节能特性在作怪。R8125为了实现低功耗，会在链路空闲时主动降低收发功耗，但在某些交换机和路由器配合下，唤醒协商会失败，导致链路假死。

排查时用命令：

sudo ethtool --show-eee enp5s0

如果显示EEE status: enabled，可以临时关闭测试：

sudo ethtool --set-eee enp5s0 eee off

这个设置重启后失效，确认是EEE问题后，建议写一个systemd服务在开机时自动关闭EEE。这也是我在实际使用中遇到最隐蔽的问题，R8125驱动本身没有提供直接关闭EEE的模块参数，只能用ethtool在用户态处理。

5. 速度跑不满2.5G的深层排查方向

5.1 网线、交换机与MTU的问题优先级

驱动装好、链路显示2500Mb/s，但实际传输速度只有几百Mbps，问题排查顺序很重要。按我个人经验，优先级从高到低：

第一查网线。2.5G对线材要求虽然不如10G那么高，但本身已经超出千兆范畴。检查网线是不是六类或超六类，水晶头是否是带屏蔽的金属头，线序是否标准。我之前就遇到过一条“伪六类”网线，外皮印着CAT6，拆开看内部是铝箔屏蔽但没有十字骨架，四对线松松散散，跑千兆没问题，上2.5G就疯狂丢包。

第二查交换机端口协商。不少千兆交换机标称支持2.5G，但部分端口实际是共享带宽或者有限速策略。插到不同端口，用ethtool对比协商速率和实际打流数据。

第三查MTU。默认MTU是1500，如果你内网有NAS并启用了Jumbo Frame，网卡端建议同步调整：

sudo ip link set enp5s0 mtu 9000

就我测试R8125的经验来说，这个网卡在MTU 1500下表现正常，但一些固件版本的交换机在握手时会出现Local fault情况，调整MTU反而能触发重新协商。不过这是小众情况，不建议默认修改，先用iperf3跑几轮看基础速率。

5.2 多队列与中断绑定优化

R8125驱动默认开启多队列（Multi-Queue）支持，但在高负载场景下，中断处理可能集中在单个CPU核心上，成为瓶颈。用以下命令查看中断分布：

cat /proc/interrupts | grep r8125

如果看到中断都落在CPU0上，可以用irqbalance服务优化，或者手动设置RPS（Receive Packet Steering）：

sudo systemctl enable irqbalance sudo systemctl start irqbalance

实测中，启用irqbalance后，多任务下载和NAS传输场景下CPU负载更均衡，吞吐量稳定性更好。不过对单核小主机来说，效果不明显，不必强求。

5.3 驱动参数调整：通过选项优化性能

R8125驱动源码支持一些模块参数，可以在src/r8125_n.c里搜索module_param查看。比较实用的是关闭流控：

options r8125 RxFlowControl=0

写入/etc/modprobe.d/r8125.conf。流控默认开启，在某些国产交换机的配合下会产生PFC死锁，表现为传输突然停顿几秒然后恢复。关闭后能明显减少这类问题。

去找驱动支持的其他参数，我在实际使用中发现这行配置还能配合TxFlowControl=0同步禁用，性能提升有限，但稳定性确实改善了。这个参数组合在Realtek官方论坛里有人专门测试过，评价不错。

6. 内核升级后的自动重编验证与回归测试

6.1 模拟一次完整的内核升级流程

DKMS配置完成后，要验证它是否真的能在内核升级后自动编译。最直接的测试方式：安装一个新内核版本并重启。

sudo apt install linux-generic

Ubuntu会拉取最新的HWE内核。安装过程中，DKMS会在post-install脚本里自动执行dkms autoinstall。注意观察终端输出，如果出现：

Building r8125 module for 5.15.0-92-generic dkms: autoinstall for kernel 5.15.0-92-generic

说明自动编译触发成功。如果没有任何r8125相关的编译输出，dkms status状态变成built而不是installed，说明大概率是源码在旧内核上编译时生成了缓存，新内核复用缓存失败导致的，重新dkms build一次可以解决。

重启验证：

reboot

开机后运行：

lsmod | grep r8125 ethtool enp5s0 | grep Speed

都正常就说明DKMS链路完整闭环。

6.2 清理旧内核残留模块，避免版本混乱

每次升级内核，旧版本的模块文件都会残留在/lib/modules/下。长期累积会导致硬盘空间浪费，更严重的是，如果同一网卡驱动在不同内核版本下模块格式不兼容，旧文件可能干扰新内核的模块加载。

定期清理：

sudo apt autoremove

但要小心，这个命令只会清理系统自动安装的内核包，不会动DKMS管理的源码目录。如果你确认旧版本不再需要，可以指定删除：

sudo dkms remove r8125/9.012.04 --all

不过这个操作是把所有版本的DKMS记录都清了，下次要重新编译还得手动注册。所以实际执行前要想清楚。我的习惯是保留当前DKMS配置，只清理系统内旧的内核头文件，用：

sudo apt autoremove --purge

这样最安全。

7. 最后分享几个实操中的小经验

R8125这个卡在Ubuntu下的驱动解决方案，其实没有太多黑魔法，核心就两条：用官方源码、配好DKMS。但我在实际帮别人处理过程中，发现80%的问题都出在细节上。

第一个细节是环境变量。很多人在编译前没有把/usr/src/linux-headers-$(uname -r)软链接建立好，导致make脚本找不到源码树。在Ubuntu 22.04上，执行sudo apt install linux-headers-$(uname -r)时通常自动建好，但如果之前手动删过build目录，就需要手动重建：

sudo ln -s /usr/src/linux-headers-$(uname -r) /lib/modules/$(uname -r)/build

第二个细节是modprobe.d目录下的配置文件名必须要有.conf后缀。有次我写了个blacklist-r8169文件没有后缀，结果配置一直不生效，网卡随机丢驱动，排查了半天才定位到是命名的低级问题。

第三个细节是DHCP获取IP失败。驱动加载正常但dhclient拿不到IP时，检查一下NetworkManager是否识别到网卡。有时驱动加载太晚，NM已经完成启动扫描。手动重新激活网络连接：

sudo nmcli device reapply enp5s0

或者干脆重启NetworkManager：

sudo systemctl restart NetworkManager

这个问题在桌面版Ubuntu上出现频率高，服务器版用netplan的话基本没影响。

还有一个很多人不知道的小技巧：Realtek官方驱动包里有一个r8125.spec文件，这是给RPM系系统打包用的。如果你用的不是Ubuntu而是Fedora或RHEL系列，可以用它配合dkms打包，步骤类似，但dkms.conf需要自己参考spec文件里的%kernel_module_package宏来写。Ubuntu用户不需要管这个文件，知道有这回事就行。

R8125驱动安装这件事，本质上就是三板斧：确认硬件、编译源码、配DKMS。只要把这三步的细节做扎实，之后内核升级再频繁也不会出问题。希望这篇踩坑复盘能帮你在2.5G网卡驱动的路上少走几步弯路。