企业官网建设流程全解析

简介：Realtek RTL8125B 网卡驱动包的 Linux 版本，专为解决 Ubuntu 18.04 系统无法识别该千兆网卡、有线网络不可用的问题，安装成功后无需更换硬件或调整内核，即可恢复稳定的有线连接。内含一键安装脚本与完整驱动源码，通过项目自带 Makefile 即可编译加载，也方便手动调整编译选项；压缩包共 16 个文件，以 C 源码、H 头文件、Makefile 构建文件和 README 说明为主，并提供旧版内核构建适配，整体大小仅 103KB，轻量、易于保存和分发。已有 5406 人学习下载，验证了其在同类硬件环境中的实用价值。使用前需确认系统已安装 GCC，可借助无线网卡或离线源完成准备；安装时只需在解压目录执行 sudo sh ./autorun.sh，即可自动完成驱动编译与装载。整个压缩包还保留了源码级目录结构，适合希望了解 RTL8125B 驱动初始化流程和寄存器配置的开发者作为参考。

1. RTL8125B 驱动在 Linux 上的麻烦：自带驱动能用，但你大概率想换掉

很多主板的板载 2.5G 网卡用的都是瑞昱 RTL8125B 这颗芯片，Linux 内核里自带的 r8169 驱动也能认出来，但“能认”和“好用”是两回事。常见情况是：系统装完，网卡亮着，驱动显示 r8169，但一跑 iperf3 只有 940Mbps 上下，看着像千兆口；或者高负载下 ping 网关开始掉包，过一会儿链路直接消失。这些不是硬件坏了，而是内核通用驱动对 RTL8125B 的兼容边界没有覆盖到你那张主板的具体布线和电源管理特性。

这篇笔记就是围绕“Realtek RTL8125B Driver for Linux”这条主线展开的：先说清楚为什么需要换官方 r8125 驱动，再给出从环境检查、编译安装、开机自启到内核升级后不失效的完整路径，最后把我在实际部署里踩过的几个典型坑摊开讲。适合三类人：主板板载 8125B 但网络不稳的桌面用户、拿它做 NAS 或软路由的人，以及帮别人维护机器的运维。目标是让你照着操作一遍后，网卡稳定跑在 2.5Gbps 上，并且下次升内核不用再折腾。

2. 装驱动之前先把环境和现状摸清楚：芯片型号、当前驱动与编译依赖

2.1 别急着编译：先用 lspci 确认你手里的芯片是哪一颗

驱动装不上的第一类问题，是根本对着错误的芯片型号折腾。RTL8125B 这个名字经常被缩写、被混用，实际 PCI 设备 ID 是 10ec:8125，但市场上还有 8125BG、8125BS 等衍生型号，它们硬件略有差异，驱动分支也可能不同。先确认自己板载网卡的准确型号，能省掉后面很多排查时间。

# 查看 PCI 设备列表，过滤 Realtek 网卡 lspci -nn | grep -i realtek # 如果你知道网卡接口名，比如 enp3s0，也看看当前驱动是谁 ethtool -i enp3s0

第一行命令的输出里，10ec:8125就是你想要的 RTL8125B；如果看到的是10ec:8168，那是老的千兆芯片，对应的是另一套驱动逻辑。第二行的ethtool -i会显示 driver 字段，如果显示的是r8169，说明当前正在被内核通用驱动接管；如果显示r8125，那说明之前你或厂商已经装过官方驱动。这一步不是走过场，很多“为什么我编译失败”的求助帖，最后都死在芯片型号没对上。

2.2 r8169 与 r8125 的差异：为什么内置驱动会被替换掉

搞清楚这个差异，你就明白这篇笔记真正在做的事。r8169 是内核里维护的通用驱动，覆盖瑞昱的 8168/8169/8125 等多个芯片，好处是开箱即用；坏处是它要以一个驱动兼容多代硬件，很多针对 8125B 的电源管理策略、多队列中断绑定、EEE 节能协商只能做折中处理。在很多主板上，r8169 驱动跑 8125B 会随机触发断流，尤其是在开启了 ASPM 电源管理的笔记本或低负载桌面场景。

我的习惯是：如果 r8169 下跑了一周没有异常，不折腾；如果出现断流、协商速率不稳定、或者需要用到官方驱动的特定 ethtool 参数，再切 r8125。这个决策顺序很重要，不要为了“装官方驱动”而装。

2.3 编译依赖：内核头文件与工具链的一次性准备

RTL8125B 官方驱动不是二进制包，拿回来是一份 C 源码，需要针对你当前运行的内核现场编译。这一步依赖两样东西：一是 gcc 和 make，二是与当前内核版本完全一致的内核头文件。头文件版本对不上，编译必挂，报错五花八门，实际都是同一个原因。

# 检查工具链是否可用 gcc --version make --version # 查看当前内核版本 uname -r # apt 系发行版安装对应版本的头文件 sudo apt install linux-headers-$(uname -r)

注意linux-headers-$(uname -r)里的命令替换会在执行时自动带入当前内核版本号，因此装出来的头文件版本一定是匹配的。redhat 系发行版对应的是kernel-devel-$(uname -r)，但别照抄，先用包管理器搜一下。还有一个隐藏坑：如果你重启过并选择了旧内核启动，uname -r会跟着变，头文件版本也必须匹配当前这个，而不是你上次装的时候那个。把这句话记住，能帮你少踩一半的编译报错。

3. 编译安装 r8125 驱动：autorun 脚本与手动 make 两条路线

3.1 官方驱动源码包与 autorun.sh 一键流程

从瑞昱官网的软件下载页面拿到的是 tar.bz2 压缩包，文件名形如r8125-x.x.x.tar.bz2，里面除了源码，还带着autorun.sh和一份dkms.conf。autorun.sh是官方提供的自动化脚本，它在绝大多数标准环境下能一步完成解压编译、模块安装和加载。这是我最推荐新手走的第一步，因为脚本内部已经处理好了模块目录复制和 depmod 刷新。

# 解压源码包 tar xf r8125-*.tar.bz2 # 进入解压出来的目录 cd r8125-*/ # 一键编译安装加载 sudo ./autorun.sh

autorun.sh会依次做这几件事：清掉旧编译产物、调用 make 编译内核模块、把生成的r8125.ko复制到/lib/modules/$(uname -r)/kernel/drivers/net/ethernet/realtek/、执行depmod -a刷新依赖，最后尝试modprobe r8125并输出类似r8125: module verified的提示。看到这个输出，驱动就已经在运行了。需要注意的是，如果你系统里之前已经加载了 r8169 并且占用了网卡设备，modprobe阶段可能因为设备被占用而跳过加载，但脚本不会因此报错，你需要看完输出后主动验证。

3.2 手动编译安装与模块加载验证

autorun.sh是一条好路，但服务器环境、定制内核、加固过的系统里，脚本可能会因为权限策略或安全软件中断。手动方式每一步可追踪，出现问题知道退到哪一步排查，这也是我喜欢在熟悉的机器上手动编译的原因。整个过程就是把脚本拆开，自己控制每一步的输出。

cd r8125-*/ # 清理旧编译产物，防止残留 .o 干扰 sudo make clean # 编译当前内核版本对应的模块 sudo make # 安装模块到内核模块目录 sudo make install # 刷新模块依赖并加载 sudo depmod -a sudo modprobe r8125 # 验证模块是否加载成功 lsmod | grep r8125

make clean不是可有可无，源码包如果之前在别的内核版本下编译过，残留的对象文件会导致当前版本编译出现奇怪的链接错误。make install执行期间如果看到类似“file exists”的提示，说明系统里已经有旧版 r8125，先modprobe -r r8125卸载旧模块再装。lsmod | grep r8125能查到模块，只是第一步，接下来还要确认网卡接口真的被它接管了。

# 确认网卡接口现在用哪个驱动 ethtool -i enp3s0

这个命令的输出里如果 driver 字段从 r8169 变成了 r8125，说明驱动切换成功。如果没有网卡接口出现，看下一章的排查流程。

3.3 让 r8125 开机自动加载：黑名单与 modules-load 配合

模块编译安装完，不意味着重启后还会加载。Linux 的模块加载机制里，r8169 作为内核自带驱动存在优先级，开机阶段很可能先于 r8125 被加载并绑定网卡设备。要让 r8125 稳定接管，需要做两件事：把 r8169 加入黑名单，把 r8125 加入开机加载列表。

# 将 r8169 加入黑名单，防止开机时抢占设备 sudo tee /etc/modprobe.d/blacklist-r8169.conf > /dev/null <<EOF blacklist r8169 EOF # 设置开机自动加载 r8125 sudo tee /etc/modules-load.d/r8125.conf > /dev/null <<EOF r8125 EOF # 重新生成 initramfs，让黑名单在早期启动阶段生效 sudo update-initramfs -u

黑名单的原理是告诉内核的模块加载子系统，在自动探测时不要加载 r8169，这样 r8125 才能在 udev 设备发现阶段顺利绑定网卡。/etc/modules-load.d/r8125.conf则是由 systemd 的开机流程读取，主动加载 r8125。最后一步update-initramfs -u很关键，黑名单配置如果不打进 initramfs，在根文件系统挂载前的早期启动阶段仍然会被忽略。r8169 被黑名单拦下后，如果你后来又要用回它，直接删掉配置文件重新生成 initramfs 即可，后悔药是有的。

4. r8125 驱动安装的常见问题排查与避坑记录

4.1 编译报错 version.h missing：头文件路径先查软链

现象：make执行到一半，报error: linux/version.h: No such file or directory，或者cannot find linux/autoconf.h。很多人在这一步以为源码包坏了，重下重解压，反复翻车。原因基本只有两个：内核头文件根本没装，或者装了但/lib/modules/$(uname -r)/build软链接没有指向正确的头文件目录。后者更隐蔽，因为包管理器显示头文件已安装，但软链断了。

解决：先确认软链接指向。ls -l /lib/modules/$(uname -r)/build，如果显示指向路径不存在，手动重建链接到/usr/src/linux-headers-$(uname -r)。注意软链的属主是 root，直接 ln -s 后别忘用sudo depmod -a刷新，然后回头重新make clean && make。如果头文件确实没装，先把 2.3 节的安装命令跑完再回来。

4.2 Secure Boot 拒绝未签名模块：签名或关闭二选一

现象：编译安装一切正常，modprobe r8125却报Required key not available，或者dmesg里出现unsigned module loading is restricted。lsmod 里没有模块，但模块文件明明在。原因：UEFI Secure Boot 开启后，内核只允许加载有有效签名的模块，第三方驱动的.ko没有签名，自然被拦。

解决：个人机器最简单的方法是进 BIOS 关闭 Secure Boot；不想关就用 MOK 签名，步骤也不复杂：生成一对密钥，用 mokutil 导入，重启后按提示 enroll，再对模块文件签名。签名后的模块就能通过校验。注意签名需要在内核头文件的 scripts 目录里用 sign-file 工具，不同发行版路径不同。

# 生成签名密钥对 openssl req -new -x509 -newkey rsa:2048 -keyout MOK.priv -outform DER -out MOK.der -nodes -days 36500 -subj "/CN=Local Signing Key/" # 导入密钥，重启后进入 MOK 管理界面选择 Enroll key sudo mokutil --import MOK.der # 重启并完成 enroll 后，对模块签名 sudo /usr/src/linux-headers-$(uname -r)/scripts/sign-file sha256 ./MOK.priv ./MOK.der /lib/modules/$(uname -r)/kernel/drivers/net/ethernet/realtek/r8125.ko sudo depmod -a

签完名再modprobe r8125，这个报错应该消失。如果 MOK 界面错过了，需要重新执行 mokutil --import 再重启一次。建议在装机维护时把这个流程写成脚本，每次升内核后重签一次，别靠记忆。血泪经验：忘记 enroll 密钥的同学，基本都会围着这四条命令折腾半小时。

4.3 模块加载了但网卡不出现：先看 dmesg 再动配置

现象：lsmod | grep r8125有输出，但ip link里看不到任何新的网卡接口，或者只看到老的接口且 driver 还是 r8169。很多人上来就改 udev 规则、改接口命名，折腾一圈没用。原因大概率是设备被 r8169 占用，或者驱动加载了但没和 PCI 设备成功绑定。

解决：先卸载 r8169，再重新加载 r8125，观察 dmesg 输出。sudo modprobe -r r8169 && sudo modprobe r8125，然后立刻看dmesg | tail -50。如果出现rtl8125: unknown chip之类日志，是驱动版本和芯片衍生型号不匹配，需要换更新的驱动包；如果没有任何 r8125 的初始化日志，说明模块没绑定到 PCI 设备，此时检查 BIOS 里板载网卡是否被禁用，以及 PCIe 槽位拆分配置。一步步来，不要同时改多个配置项，否则出了新问题你都分不清是哪一步引起的。

4.4 协商速率上不去：线缆与对端端口往往比驱动更玄学

现象：驱动装好了，模块也加载了，ethtool enp3s0一看 Speed 是 1000Mb/s，甚至 100Mb/s。这时候第一反应别是回滚驱动，先看协商对象。2.5G 协商需要网线至少是超五类以上、八芯全通，对端设备也必须支持 2.5G。现实中大量案例是：驱动折腾一下午，最后发现配线架到桌面那段跳线只有四芯，或者对端接的是千兆交换机。

解决：ethtool enp3s0看 Speed 和 Supported link modes，如果驱动正常，Supported link modes 里应该有 2500BaseT。协商在 1000Mb/s 时，换根成品 Cat6 线直连另一台 2.5G 设备排除；协商在 100Mb/s 时，八成是线序或接触问题，先处理物理层。驱动这层反而很少卡协商，它只是把硬件能力暴露给上层。我一般把这条放在所有脚本化排查的最后，因为它最像玄学，但命中率最高。

5. 用 dkms 托管 r8125：内核升级后不用再手动重编

5.1 为什么说每次内核升级都是驱动黑匣子

r8125 是编译进当前内核模块目录的，一旦系统升级内核，新内核的模块目录下没有 r8125.ko，而黑名单又把 r8169 挡住了，结果就是重启后网卡彻底消失，你只能通过 SSH 以外的途径去救机器。没有 dkms 的时候，每次内核升级都要手动重跑一遍编译安装流程，还得祈祷新内核的头文件已经装好。dkms 解决的就是这个黑匣子：它监听内核安装事件，在检测到新内核时自动完成模块的编译和安装，把驱动状态从“手动维护”变成“开机自动维护”。

5.2 把 r8125 注册进 dkms 的最小命令

官方源码包自带 dkms.conf，所以不需要自己写配置，只需要把源码目录放到 dkms 的搜索路径下，并按“模块名-版本号”的规则命名目录。注意：源码包解压出来的目录名通常已经是这种格式，直接使用即可，不要手动改名加后缀，否则 dkms add 会报找不到模块名的错。

# 安装 dkms 框架 sudo apt install dkms # 将源码目录复制到 /usr/src，保持原有的 模块名-版本号 目录名 sudo cp -a r8125-版本号 /usr/src/ # 注册、编译并安装到当前内核 sudo dkms add -m r8125 -v 版本号 sudo dkms build -m r8125 -v 版本号 sudo dkms install -m r8125 -v 版本号 # 查看状态 sudo dkms status

dkms add的作用是登记，build是在当前内核源码树下编译，install把编译好的模块软链进/lib/modules/$(uname -r)/updates/。dkms status输出里看到installed状态就说明托管成功。之后每次内核升级，dkms 会尝试用新内核的头文件自动 rebuild，前提是新内核的头文件包已经安装，所以建议同时安装对应发行版的 generic 头文件包，让未来内核都有头文件可用。

5.3 dkms、blacklist 与 initramfs 的配合关系

dkms 管的是模块的编译和安装，不管模块的加载时机。前面第 3.3 节做的 blacklist 和 modules-load 配置依然有效，两者是配合关系而不是替代关系。dkms 负责让新内核里有 r8125.ko 文件，blacklist 负责挡住 r8169，modules-load 负责在开机时主动加载 r8125，三个环节缺一个都可能出问题。

另外，内核升级后 initramfs 会被重新生成，这时黑名单配置如果没有保留在/etc/modprobe.d/下，新 initramfs 里就不会包含它。解决办法很简单：保证黑名单配置写在/etc/modprobe.d/下的独立文件里，不要写在旧的、可能被升级脚本清理的临时配置里。升级完内核后主动跑一次sudo update-initramfs -u也是稳妥习惯。这套组合下来，r8125 驱动的维护成本基本降为零。

6. 性能验证与调优习惯：先确认协商速率，再谈 2.5G 跑满

驱动装完，最重要的事情不是看灯亮，而是验证实际链路状态。我每装完一台机器，固定执行下面这三组命令，顺序不换：

# 第一看协商速率与链路能力 ethtool enp3s0 # 第二看链路错误计数，驱动或线缆问题常体现在这里 ethtool -S enp3s0 | grep -Ei "error|drop|missed" # 第三跑实际的吞吐测试，对端也需要是 2.5G 设备 iperf3 -c 192.0.2.10 -t 60 -P 4

ethtool不带参数直接看 Speed 字段，确认是不是 2500Mb/s；如果不对，先回到 4.4 节的物理层排查。ethtool -S里的 rx_errors、tx_errors、rx_missed 这类计数如果持续增长，说明链路质量有问题，常见诱因是网线质量差或者接触不良。最后的 iperf3 打流，只有对端也协商到 2.5G，才能跑出 1.8Gbps 以上的实际吞吐，否则测出来 940Mbps 完全是合理的。我还习惯顺手看一眼/proc/interrupts里有没有多个中断号绑定到 r8125，多队列正常的话，中断会分散到多个核上，这也是判断驱动是否正确启用硬中断收包的一个旁证。

我第一次给某公司的一台机器切 r8125 驱动，编译一次通过，模块加载成功，结果打流死活只有 950Mbps，折腾了一晚上，从 BIOS 配置到 ethtool 参数全查了一遍，最后发现是机房配线架到工位那段跳线只通了四芯。从那以后我养成了先看协商速率再谈调优的习惯，也提醒你一句：驱动层面的坑大多有日志可查，物理层的坑常常让人空转。希望这篇笔记能让你在 RTL8125B 这条路上少走两趟弯路，装完就能稳定跑满。

本文还有配套的精品资源，点击获取