前阵子接手一台工控机主板板载的是Realtek RTL8125 2.5G有线网卡系统装的是Ubuntu 18.04。开机进系统后发现问题很直接有线网卡完全不工作ifconfig -a下面只有lo回环接口连eth0的影子都看不到。第一反应是网卡坏了切到Windows下一试网卡识别正常这才确认是Linux驱动层面的问题。更麻烦的是这台机器在纯内网隔离环境里apt源不指向任何镜像也没有任何外网通道想靠系统自己联网下载驱动完全不可能这是典型的离线安装驱动场景。这篇实战记录就是完整描述我从识别芯片型号、准备离线依赖、编译RTL8125驱动、到最终在Ubuntu 18.04里稳定跑通的全部过程。会给到每一步使用的命令、踩过的坑、以及排查思路。适合被板载2.5G网卡折磨的运维、自组NAS用户、嵌入式Linux开发以及任何一个需要在无网环境下搞定硬件驱动的朋友。1. 确认芯片型号先搞清楚网卡到底是谁家的1.1 用一条lspci命令锁定RTL8125排查网卡驱动问题第一步永远是先确认硬件身份。不管系统网络配置多复杂网卡驱动属于PCI设备驱动只要系统能识别这个PCI设备lspci里面就一定会有记录。在目标机器上执行lspci -nn | grep -i ethernet我这边输出的内容如下03:00.0 Ethernet controller [0200]: Realtek Semiconductor Co., Ltd. RTL8125 2.5GbE Controller [10ec:8125]方括号里的10ec:8125就是关键指纹。10ec是Realtek的PCI厂商ID8125是该芯片的设备ID。看到这个组合基本可以确认是RTL8125。如果机器上有多块网卡lspci -nn会列出多行Ethernet controller这时需要结合PCIe槽位或者lspci -vv里面的物理位置信息确认到底哪一块才是板载的RTL8125别把Intel的i225误认成目标设备。这个识别步骤非常关键因为Realtek不同系列网卡对应的驱动源码包完全不同。RTL8125对应的是r8125驱动而老款8111/8168对应r8168驱动还有内核自带的r8169驱动三者虽然名字相近但源码和适配范围差距很大认错芯片后面再怎么装都是白费。1.2 r8169、r8168、r8125别被这三个名字绕晕很多人第一次接触Realtek网卡驱动会被这三个名字搞晕。其实它们的区别很清楚r8169Linux内核自带的驱动模块老内核里只覆盖RTL8168/8111这一代千兆芯片后续内核版本才逐渐扩展支持RTL8125。r8168Realtek官方针对RTL8111/8168系列千兆网卡发布的源码驱动包。r8125Realtek官方针对RTL8125这颗2.5G芯片发布的源码驱动包。问题就出在Ubuntu 18.04自带的内核版本上。18.04默认内核是4.15.x那个年代的r8169驱动压根不认识RTL8125PCI ID列表里没有8125这一项。所以系统启动时内核虽然通过PCI枚举看到了这个设备但找不到任何匹配的驱动去绑定它结果就是网卡存在但不可用。我当时特意确认了这一点lspci能看到设备但lspci -k里看不到Kernel driver in use这一行说明确实没有驱动绑定。这也就解释了为什么ip link下面连个网卡接口都没有因为没有一个驱动为内核创建网络接口。1.3 为什么偏偏要离线安装有人可能会问Ubuntu 18.04不也可以联网执行apt install吗问题在于这台设备的运行环境是物理隔离的内网既没有可用的apt源也没有外网出口而且恰恰因为网卡驱动缺失连最基础的网络通道都没有这就形成了一个死循环要联网必须先装驱动要装驱动又必须先联网。这个场景在工控机、等保要求的内网服务器、部分嵌入式设备里非常普遍。离线安装的本质就是把联网获取软件包这个动作前置到另一台有网络的机器上完成然后把所有需要的源码包和deb依赖拷贝到目标机器再通过本地介质完成安装。整台目标机器自始至终不需要接触外网风险可控流程标准化。我在这次操作里总结出来的核心思路是三个字先备料。所有编译需要的工具、头文件、源码包在动手前全部备齐接下来就是按部就班执行命令。2. 在有网的机器上一次性备齐所有物资2.1 RTL8125驱动源码去哪拿版本怎么挑RTL8125的官方Linux驱动源码包正常渠道是去Realtek官网下载中心按网络设备分类里的Unix/Linux驱动列表找到RTL8125对应的Linux驱动下载下来一般是r8125-xxx.tar.bz2压缩包。如果官网改版后导航不好找也可以去一些开源镜像站寻找打包好的源码包但我个人还是建议优先官方版本官方包的编译行为和模块注册逻辑更稳定不会有第三方改过的坑。版本选择上建议直接跳过早期驱动。RTL8125驱动早期版本比如9.003.05、9.004.01虽然在老内核上能编译但遇到较新的硬件批次、最新的内核补丁版本时容易出现各种奇怪问题。我这次选用的是r8125-9.011.00在Ubuntu 18.04配套的4.15.0-213-generic内核上编译加载都很顺利。版本号越新官方针对内核兼容性的适配越多尽量不要拿老古董版本折磨自己。2.2 编译环境三件套gcc/make、linux-headers、dkms内核模块不是普通用户态程序编译它必须有对应的内核头文件。这里列一个我每次离线装驱动前都会核对的清单依赖项具体作用缺失后果build-essential提供gcc、make等编译工具直接报gcc: command not foundlinux-headers-$(uname -r)当前内核的头文件和Makefile片段编译时找不到内核构建系统直接失败dkms内核模块动态管理内核升级后自动重编内核一升级驱动失联网卡再次失效linux-headers这一点必须强调它要和当前正在运行的内核版本严格一致。驱动ko文件最终要加载进当前内核头文件版本差一个补丁版本都可能编出无法加载的模块。所以在准备物资之前先到目标机器上执行uname -r把完整的内核版本号记下来。我这边是4.15.0-213-generic后面所有下载都围绕这个版本展开。2.3 用apt-get把依赖打包带走有网机器和目标机器建议保持同一个Ubuntu版本、同一个CPU架构也就是同为amd64或同为arm64这能避免很多依赖版本冲突的问题。我习惯用apt-get install --download-only配合apt-get download两种方式结合。首先准备编译类基础包sudo apt-get update sudo apt-get install --download-only build-essential dkms执行完之后所有下载好的deb包都会缓存在/var/cache/apt/archives/目录下。立刻把它们拷贝到自己的工作目录mkdir ~/offline-debs cp /var/cache/apt/archives/*.deb ~/offline-debs/然后再单独下载目标内核的头文件包sudo apt-get download linux-headers-4.15.0-213-generic如果你的内核版本不同把命令里的版本号替换成uname -r的输出。linux-headers依赖关系比较复杂为了保险我一般也用--download-only方式把整个依赖树拉一遍sudo apt-get install --download-only linux-headers-4.15.0-213-generic这样linux-headers所有依赖包都会进到/var/cache/apt/archives整个目录拷走就行。最后把整个offline-debs目录复制到U盘或者通过内网共享目录传输到目标机器。扩展说明apt-get download适合精确下载某一个包但依赖要自己一个个列--download-only适合一次拉一整套依赖不擅长精确控制。我是先把build-essential和dkms用--download-only整体拉一遍再用apt-get download单独补linux-headers最后把整个缓存目录打包带走这样覆盖最全。2.4 离线机器上按顺序装好依赖到了目标机器先创建目录把U盘里的deb包复制过去然后进入目录执行sudo dpkg -i *.debdpkg是按文件顺序逐个安装的第一次执行大概率会报一些依赖错误。这是正常现象因为deb包之间的依赖关系有先后顺序第一批包可能还没装完后面的包就检查不到它依赖的那个包。看到报错千万别慌更不要中断后反复上网搜索直接再执行一次同样的命令sudo dpkg -i *.deb第二次执行时之前已经装好的包已经把依赖关系补齐剩余包的依赖检查自然就能通过。如果两轮之后还有报错说明某个依赖包确实漏掉了回有网机器用apt-get download补下载对应包再传到目标机器单独安装即可。装完之后按顺序验证which gcc make ls /usr/src/linux-headers-$(uname -r)/ dpkg -l | grep dkms三条命令不报错说明编译环境已经就绪可以进入驱动源码编译环节了。3. 编译安装RTL8125驱动全流程3.1 先验证编译环境再解压源码把r8125-9.011.00.tar.bz2拷贝到目标机器解压到一个普通用户可写的目录比如当前用户的家目录。内核模块的编译过程会生成大量中间文件放在只读介质或者没有写权限的目录里会导致莫名失败。tar xf r8125-9.011.00.tar.bz2 cd r8125-9.011.00 ls解压后目录里通常有Makefile、autorun.sh、src/等内容。src目录才是真正的驱动源码顶层Makefile和autorun.sh只是方便用户操作的封装层。在动手编译前花十秒钟确认内核头文件的软链接是正确的ls -l /lib/modules/$(uname -r)/build正常情况应该指向/usr/src/linux-headers-$(uname -r)且目标目录存在。如果显示软链接断掉或者目标目录不存在说明linux-headers没有正确安装先回头处理依赖别急着编译。3.2 手动编译而不是autorun.sh一把梭官方包里提供了autorun.sh一键脚本很多教程都会让你直接sudo ./autorun.sh一步到位。但我的建议是第一次安装不要用它。原因很简单这个脚本会自动卸载现有驱动、自动编译、自动复制模块、自动modprobe加载中间任何一个环节出问题它只给你一堆含糊的输出根本定位不到卡在哪一步。手动执行每个步骤才能在手忙脚乱的时候看清楚自己到底在哪一步栽的。先清理并编译sudo make clean makemake过程会打印大量编译日志。看到warning是正常现象不用太在意但如果出现error把报错信息里的关键字记下来比如implicit declaration of function、compiler version check failed等这些都是有明确含义的后面排错章节会细说。编译成功后在src目录下会生成r8125.ko文件。接下来安装到系统内核模块目录并刷新模块依赖关系sudo make install sudo depmod -a然后加载驱动sudo modprobe r8125加载完成后立刻检查lsmod | grep r8125如果输出里有r8125说明模块已经加载成功。这时候再看ip link应该能看到网卡接口出现了。接口名可能是enp3s0这类按PCIe位置生成的名称也可能是eth0具体取决于内核参数和udev规则。如果加载后接口状态是DOWN先手动启用sudo ip link set eth0 up再ip link show确认状态已经变为UP。3.3 用DKMS固化驱动内核升级不用慌直接make install安装的驱动有一个隐藏问题一旦系统以后升级内核旧内核模块目录会被替换新内核下模块不会自动重新生成网卡就会在重启后再次失效。生产环境里这是定时炸弹所以建议用DKMS管理。DKMS的原理不复杂把驱动源码放到/usr/src/r8125-9.011.00/注册一条构建记录之后每次内核更新DKMS自动检测到新内核并重新编译安装对应模块。把源码复制到/usr/srcsudo cp -r r8125-9.011.00 /usr/src/然后注册并构建sudo dkms add -m r8125 -v 9.011.00 sudo dkms build -m r8125 -v 9.011.00 sudo dkms install -m r8125 -v 9.011.00这里有几个容易出错的细节。如果之前已经手动执行过make installDKMS里可能已经存在同名记录add时会提示already installed这时候要先执行sudo dkms remove -m r8125 -v 9.011.00 --all清理掉旧记录再重新add。另外源码目录名里的版本号必须和dkms.conf里的MODULE_VERSION字段完全一致否则dkms会直接拒绝处理。这也是为什么源码目录一定要保持r8125-版本号这个命名格式不要自己改成其他名字。4. 装完驱动网卡还是不通这些坑我挨个踩了一遍4.1 Secure Boot签名验证失败这是我这次安装过程中遇到的最隐蔽的坑之一。如果机器预装过Windows或者BIOS里开启了Secure Boot即使模块编译成功modprobe加载也会直接失败报错如下modprobe: ERROR: could not insert r8125: Operation not permitted同时dmesg里会有更明确的记录Module verification failed: signature and/or required key missing - tainting kernel原因在于Secure Boot开启后内核只允许加载带受信任签名的模块手工编译的ko文件没有合法签名直接被内核拒绝。解决方式有两种。第一种最简单进BIOS把Secure Boot设为Disabled重启后一切正常。纯内网环境一般不会因为这个启动选项卡住但品牌服务器默认开启Secure Boot的概率不低。第二种更规范适合必须保持Secure Boot开启的生产环境使用mokutil给模块做自签名openssl req -new -x509 -newkey rsa:2048 -keyout MOK.priv -outform DER -out MOK.der -nodes -days 36500 -subj /CNMy Module Key/ sudo mokutil --import MOK.der重启后系统会进入蓝色MOK管理界面按提示选择Enroll Key并输入刚才设置的密码确认导入后继续启动。回到系统后用内核头文件里自带的sign-file工具对r8125.ko签名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 sudo modprobe r8125这个操作要安排在计划维护窗口执行因为涉及重启而且纯命令行界面也能完成但建议事先把命令准备好避免重启后手忙脚乱。4.2 头文件版本不一致导致的gcc编译错误如果你在make阶段看到大量类似implicit declaration of function或者Compiler version check failed的错误不要怀疑自己的操作问题大概率出在gcc版本和内核头文件版本不匹配上。Ubuntu 18.04的内核4.15是用gcc-7编译的如果离线deb包帮你装上了gcc-8甚至gcc-9或者系统里原本就存在多个gcc版本编译内核模块时很容易出现语法检查层面不兼容的问题。先看当前默认的gcc版本ls /usr/bin/gcc-* gcc --version如果默认gcc不是gcc-7不要轻易卸载现有gcc版本那可能破坏系统里其他依赖正确的做法是在make时显式指定编译器版本make CCgcc-7如果系统里确实没有gcc-7回有网机器下载gcc-7和g-7的deb包离线装上即可。这个坑在Realtek官方驱动的编译过程中尤其常见因为有相当一部分教程只告诉你make不提编译器版本这回事导致满屏报错时完全摸不着头脑。4.3 内核自带驱动抢先绑定Ubuntu 18.04默认内核4.15里自带r8169驱动不认识RTL8125但如果你用的是HWE内核版本比如5.4情况就不一样了。某些较新内核里r8169驱动已经扩展到支持RTL8125的PCI ID或者系统里以前装过其他版本的Realtek驱动就可能出现多个驱动抢一个设备的情况。判断方法一秒钟就能完成lspci -k | grep -A3 -i ethernet如果输出显示Kernel driver in use: r8169说明网卡设备被r8169抢先绑定而你想用的是r8125驱动。解决办法是先卸载r8169再加载r8125sudo modprobe -r r8169 sudo modprobe r8125如果希望重启后不再被r8169抢占可以将其加入黑名单echo blacklist r8169 | sudo tee /etc/modprobe.d/blacklist-r8169.conf sudo update-initramfs -u这里有一个重要提醒在执行黑名单和update-initramfs之前一定要先确认r8125驱动本身能正常工作否则重启后网卡彻底失联物理机还得接显示器进单用户模式处理非常狼狈。4.4 NetworkManager不接管新接口驱动加载成功、ip link下能看到接口但就是拿不到IP地址这是另一个高频问题。原因通常是NetworkManager不认识这个新出现的接口或者系统的网络配置文件里压根没有给这个接口分配DHCP的逻辑。先用nmcli查接口状态nmcli device status如果接口显示状态为unmanaged说明NetworkManager明确表示不管它。解决思路是给接口配上netplan配置。Ubuntu 18.04默认使用netplan作为网络配置工具编辑/etc/netplan/01-netcfg.yamlnetwork: version: 2 renderer: NetworkManager ethernets: enp3s0: dhcp4: yes执行netplan使配置生效sudo netplan apply几秒后ip addr show里应该能看到接口从DHCP服务器拿到IP地址。这个步骤看似简单但如果你不知道网卡接口名是什么记得先用ip link看清楚再填进yaml文件别把不存在的接口名写进去导致apply失败。4.5 网卡速率协商不到2.5G驱动装好、能上网了但用ethtool eth0一看Settings for eth0: Speed: 1000Mb/s跟2.5G网卡的名头完全对不上。这种情况先检查对端设备交换机端口是不是真正支持2.5G网线是不是至少Cat5e及以上线缆距离过长也会导致降级协商。如果对端确认支持2.5G可以尝试强制协商ethtool -s eth0 speed 2500 duplex full autoneg on不过说实话我的经验是多数情况下不要强制让网卡自动协商就好。只要对端设备没问题RTL8125默认就能协商到2500Mb/s。速率掉到1G时优先排查物理链路和交换机端口配置别一上来就改驱动参数改坏了还得多折腾一轮。5. 驱动加载后的完整验证和固化经验5.1 一套验证链路确认驱动真正接管很多人看到ifconfig里出现网卡接口就以为大功告成实际上驱动是否稳定接管设备还需要完整验证一遍。我每次装完驱动会按照下面这个顺序检查dmesg | grep -i r8125 | tail lspci -k | grep -A3 -i ethernet ip link show ethtool eth0 | grep -E Speed|Duplex ping -c 3 网关地址这里整理了每个检查项对应的期望结果检查项期望结果dmesgr8125模块加载成功出现link up日志lspci -kKernel driver in use: r8125ip link接口处于UP状态并拥有MAC地址ethtoolSpeed: 2500Mb/sDuplex: Fullping网关能通五步全过这个驱动才算真正装好了。特别强调一下lspci -k这行输出直接告诉你设备到底被哪个驱动接管很多装完不生效的问题本质都是驱动没接管设备只是模块加载了个寂寞。宽带测速或者内网大文件传输如果想要更严格地验证2.5G性能建议用iperf3跑一下不能只看协商速率还要看实际吞吐能不能达到2.5G的带宽。5.2 把离线驱动包变成你的运维工具箱经历了这次离线装驱动我最大的体会是离线环境最贵的不是硬件而是时间。每次遇到类似问题都要从头找包、传包、试错成本太高了。所以后来我在自己的运维机上专门建了一个离线驱动包目录里面按网卡芯片型号分类放好了常用网卡驱动源码包、对应Ubuntu版本的deb依赖以及一份安装脚本。以后只要在离线机器上执行uname -r和lspci -nn确定目标硬件和内核版本就能从运维仓库里直接拷贝对应的整套离线安装包到现场执行脚本二十分钟内搞定。这个习惯强烈建议所有经常接触内网机器的人都养成省下来的时间非常可观。哪怕不是自己维护的设备多保留一份离线驱动包遇到紧急情况也能应急不用临时到处找资源。最后再分享一个小细节我在这个项目里吃过亏在离线机器上执行dpkg -i *.deb时如果看到报错就频繁中断去查资料反而容易把依赖关系处理得更乱。dpkg二次执行就能自动补齐大部分依赖先跑完第二轮再判断问题也不迟。还有如果你也是给老机器装这类2.5G网卡的驱动动手前一定先把lspci -nn和uname -r两个输出拍照存档这两个字段是后面所有操作的起点丢了它们等于在黑暗里找路。希望这篇记录能让你的离线网卡驱动之路少走几个弯。