企业官网建设流程全解析

简介：这份离线安装包面向需要在Ubuntu系统中搭建编译环境并安装Realtek r8125网卡驱动的用户，尤其适合无外网连接的服务器、内网开发机或临时应急修复场景。资源整体共42个文件，压缩后大小约30.01MB：其中23个deb软件包覆盖gcc、make、build-essential及其依赖库，可在离线状态下快速补齐从源码编译到程序打包的完整工具链；8个h头文件与6个c源文件构成r8125驱动的核心源码，2个Makefile定义编译规则，另有sh脚本和readme说明辅助自动安装与排错。该资源已有3767人学习下载，说明离线依赖场景在Ubuntu维护中颇为常见。对系统维护和开发人员而言，这份压缩包免去逐一下载和匹配依赖的繁琐流程，解压后即可按既有脚本和编译规则完成驱动安装；尤其适合Ubuntu 18.04等环境在网络不可用时搭建基础开发环境、编译Realtek网卡驱动或为其他内核模块准备工具链，是断网条件下实用的一套离线部署资料。

1. 离线安装 Realtek 网卡驱动：先把家底摸清再动手

在内网环境里折腾 Ubuntu 网卡，最磨人的不是编译报错，而是你发现机器根本没网、apt 也用不了，而手头只有一块 Realtek 网卡和一堆散落的源码包。这份资源把 gcc、make、build-essential 以及 r8125 驱动源码和它的依赖全都打成了一个离线包，说白了就是给你一份「断网自救指南」——在 Ubuntu 上装 Realtek 2.5G 网卡，不用联网、不用满世界找依赖，按顺序装完就能让网卡跑起来。适合机房运维、内网开发机部署、以及被 apt 源折腾到想砸键盘的入门用户。

2. 为什么 r8125 需要源码编译：内核模块不是装个包就完事

2.1 内核自带驱动和厂商驱动的差别

很多网卡在 Ubuntu 安装完就有驱动，因为主线内核里已经带了对应的内核模块。但 Realtek 的 RTL8125 这类 2.5G 网卡，在很长一段时间里并没有进主线内核，系统默认加载的是通用千兆驱动 r8169，性能上跑不满 2.5G，甚至在某些主板上干脆认不到。这个问题的本质是：内核模块必须和当前运行的内核版本严格匹配，厂商只能发布源码，由你在目标机器上现场编译。

这时候就涉及一个关键认知：所有的驱动源码编译，依赖的不是「编译器」这一个东西，而是整个构建链。光有 gcc 还不够，还需要 make 来调度编译过程，需要 build-essential 把整套编译工具链拉齐，还需要对应内核版本的 linux-headers 提供内核头文件和编译脚本。这套资源把前三者打进了离线包，linux-headers 一般由系统镜像自带或者在资源里附带了对应版本，你需要在安装前先确认内核版本是否匹配。

2.2 离线包的依赖顺序：为什么不能跳过 build-essential

我见过不少新手拿到离线包，直接跳到最后一个源码包去解压编译，然后报一堆找不到头文件的错。原因很简单——驱动源码在编译时会调用内核的构建系统，这套系统依赖 build-essential 提供的完整工具链，它不只是一个 gcc 那么简单，还包括了 ld、ar、make 以及一堆库文件。

正确顺序应该是：

# 先查看当前内核版本，这决定了后面要装哪个版本的 headers uname -r # 查看系统发行版信息，确认是 Ubuntu 哪个版本 lsb_release -a

这里的uname -r输出的是运行中内核的完整版本号，比如5.15.0-91-generic，后面安装 linux-headers 时需要用这个版本号精确匹配。lsb_release -a用来确认系统版本，因为不同 Ubuntu 版本的依赖库名称和版本要求会有差异，离线包里的 deb 文件虽然能通用，但版本不对会直接报依赖冲突。

安装 deb 包的逻辑是：先装底层工具链，再装头文件，最后才是驱动源码。如果跳过 build-essential，你会在编译驱动时报make: command not found或者一堆fatal error: linux/string.h: No such file or directory，这都不是源码问题，而是工具链没铺好。

2.3 离线安装 deb 包的两种姿势：dpkg 和 apt-offline

拿到离线包之后，解压出来会看到两个目录：一个是deb_packages/，里面是 gcc、make、build-essential 等所有依赖的 deb 文件；另一个是r8125_src/，里面是驱动源码。deb 目录里的文件全量装进去用 dpkg：

# 进入离线包里的 deb 目录，用通配符安装所有 deb 文件 cd deb_packages/ sudo dpkg -i *.deb # 如果 dpkg 提示有依赖缺失但 deb 文件里确实存在，尝试修复 sudo apt-get install -f

注意这里的逻辑：dpkg -i *.deb会把当前目录下所有 deb 包按顺序安装，但 dpkg 本身不处理依赖解析，如果某个包依赖另一个包且顺序不对，会报错。sudo apt-get install -f的作用是修复依赖关系，它会检查系统里已经解包的依赖是否有延迟处理，在有网络时会自动下载缺失部分，在纯离线环境里，如果 deb 包是全量的话，这一步通常直接通过。

我一般会先跑dpkg -l | grep build-essential确认安装结果，再跑gcc --version和make --version验证工具链是否可用。这一步过了，才说明编译环境没问题，可以进源码编译阶段。

3. r8125 驱动编译实录：从解压到网卡点亮

3.1 解压源码包并确认硬件识别情况

Realtek 官方发布的 r8125 驱动源码包通常命名为r8125-<版本号>.tar.bz2或.tar.gz，解压后进入源码目录。在编译之前，先确认系统确实识别到了这块网卡，否则编出来的模块加载了也没对应硬件：

# 查看 PCI 总线上的网络设备，确认 Realtek 网卡是否被系统看到 lspci | grep -i ethernet # 查看网卡对应的内核驱动，如果显示 r8169 说明被旧驱动接管了 sudo lshw -class network | grep -A 5 "Realtek"

lspci列出的是 PCI 设备列表，如果你能看到类似Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8125 2.5GbE Controller这样的行，说明硬件识别没问题。lshw输出中 driver 字段如果显示 r8169，说明当前内核用通用驱动接管了这块卡，你需要卸载掉它，才能加载新编译的 r8125 模块。

编译前还有一个隐藏步骤：检查源码目录里的Makefile中的TARGET变量。Realtek 经常在同一个包里面放多个网卡的驱动，比如 RTL8125 和 RTL8168 共用一个 Makefile。默认的TARGET := r8125是对的，但你需要确认没有改过配置：

# 在源码根目录执行，用来查看默认目标模块名 grep "^TARGET" src/Makefile

这一步看着简单，但真有翻车的——有的发布版默认 TARGET 是 r8168，编译出来的模块和你手上的 RTL8125 对不上，加载后网卡依然没反应。

3.2 编译和安装：make 与 make install 的实际含义

Realtek 官方驱动的编译流程通常就两条命令，但每条里面都有坑需要展开讲：

# 编译驱动模块，生成 r8125.ko 文件 sudo make # 安装模块到系统内核模块目录 sudo make install

make这一步执行的是源码根目录的 Makefile，它会调用内核构建系统，把源码编译成r8125.ko这个内核模块文件。这里有个很常见的报错是Makefile: ... No such file or directory，原因就是前面说的 linux-headers 没装，内核构建系统找不到-C /lib/modules/$(uname -r)/build这个路径。解决方法是安装和当前内核完全一致的 headers 包：

# 确认 headers 是否已安装，注意版本号要和 uname -r 一致 ls /lib/modules/$(uname -r)/build # 如果不存在，用离线包里的 headers deb 安装 sudo dpkg -i linux-headers-*.deb

make install的作用是把编译好的r8125.ko复制到/lib/modules/$(uname -r)/kernel/drivers/net/ethernet/realtek/目录下，并自动运行depmod更新模块依赖关系。注意这个目录路径中的$(uname -r)是动态的，如果你在安装 headers 之后重启过内核，路径对不上，需要重新编译安装一次。

3.3 加载模块并验证：不重启也能让网卡生效

模块安装完成后，通过 modprobe 手动加载，不需要重启系统：

# 先卸载旧驱动 r8169（如果有），再加载新驱动 sudo rmmod r8169 sudo modprobe r8125 # 确认模块加载状态和依赖关系 lsmod | grep r8125 # 确认网卡接口是否生成，一般会多出一个 enpxxx 接口 ip link

这里需要注意rmmod r8169这步操作——如果旧驱动正在被使用，比如你正通过这块网卡连接 SSH，卸载会导致网络中断。本地操作没问题，远程操作建议先确保有其它通道。ip link输出中如果出现以enp或eth开头的新接口，说明模块加载成功，此时网卡尚未获取 IP 地址，还需要配置网络或者插网线等 DHCP。

验证驱动实际工作时，最直接的方法是查 ethtool 的连接速率：

# 用 ethtool 查看网卡速度，确认跑在 2500Mb/s 而非 1000Mb/s sudo ethtool enp3s0 | grep -i speed

如果输出显示Speed: 2500Mb/s，说明 2.5G 速率被正确协商。如果依然是1000Mb/s，可能是网线质量、交换机端口或者 BIOS 里 PCIe 链路设置的问题，这时候先别急着怀疑驱动。

4. 离线编译避坑：五条血泪经验一次说清

4.1 modprobe 报 module not found，但 ko 文件明明存在

现象：编译安装都显示成功，sudo modprobe r8125却报Module r8125 not found。

原因：安装模块时make install写入的路径是编译时内核版本对应的目录。如果你在编译前装的是 A 版本 headers，后来内核更新到 B 版本（或者装 headers 时顺手升级了内核），模块装到了 A 版本的目录下，B 版本内核根本找不到。

解决：重新执行make clean && make && sudo make install，确保整个流程用的是当前内核的 headers。我一般会在编译前强制跑一次uname -r并和/lib/modules/下现有目录做对比，不一致直接放弃编译，先把环境对齐。

4.2 编译报错 unknown type name，源码和内核版本不兼容

现象：make时报出各种 HashMap 结构体相关的unknown type name错误，还有一堆宏未定义的警告。

原因：新内核的 API 和驱动源码预期的 API 有差距，最常见的是内核 6.x 后移除了某些旧的 PCIe API，而 r8125 老版本源码还在用。这不是你操作的问题，是 Realtek 官方源码发布节奏落后于内核主线更新。

解决：优先用资源里附带的 r8125 源码版本而不是去官网找最新版。如果实在要用老版本，看报错文件是不是r8125_n.c这类主要源码文件，对照内核源码include/linux/pci.h看 API 签名变化，手动替换为新的 API。这种打补丁的方式对新手不友好，建议直接换源码版本或者用 DKMS 方式管理。

4.3 Secure Boot 开启，模块加载直接被拒绝

现象：modprobe加载模块后，内核日志显示Lockdown: modprobe: unsigned module is restricted。

原因：UEFI Secure Boot 开启时，内核只允许加载经过有效签名的模块。自己编译出来的 r8125.ko 是未签名模块，直接被内核拒绝。

解决：两个方向——一是进 BIOS 关闭 Secure Boot，这招最快但会影响系统安全策略；二是给模块做本地签名。先用mokutil --generate-key生成密钥，再用/usr/src/linux-headers-$(uname -r)/scripts/sign-file签名模块。我个人的习惯是：生产机从 BIOS 层面直接关掉 Secure Boot，开发机无所谓。签名这条路径 mokutil 的交互非常反人性，很容易卡在 MOK 管理界面不知道怎么操作。

4.4 网卡灯亮了但没 IP，DHCP 拿不到地址

现象：ip link能看到enp3s0接口，状态是NO-CARRIER或者DOWN，dhclient也等了很久没结果。

原因：大部分情况是网络管理服务没有接管这个新接口。Ubuntu 用的是 Netplan + systemd-networkd 的组合，新网卡的接口名不一定被 netplan 配置覆盖，所以 DHCP 客户端不会自动跑。

解决：最省事的是用 NetworkManager 交互式接管：

# 查看接口名，然后手动拉起 DHCP sudo nmcli dev status sudo nmcli dev set enp3s0 managed yes sudo nmcli con add type ethernet ifname enp3s0 autoconnect yes sudo nmcli con up enp3s0

4.5 装完驱动系统启动变慢，卡在 wait-for-network

现象：重启后卡在A start job is running for Wait for Network to be Configured这种界面。

原因：r8125 模块加载后网络接口出现了，但系统里配置的旧接口（比如原来静态配置的 eth0）对应不存在的网卡名，网络服务一直超时等待。

解决：先确认旧的网络配置是否存在残留，重点检查/etc/netplan/下的 yaml 文件和/etc/network/interfaces。如果旧配置里指定了eth0，而现在网卡变成enp3s0，把配置同步替换即可。另外把模块加入/etc/modules-load.d/可以避免驱动加载过晚导致的通知混乱。

5. 验证驱动可用性：不止是 ping 通那么简单的检查清单

5.1 用 lspci 和 ethtool 双重确认硬件链路

网卡驱动装完，第一件事不是去 ping 网关，而是确认物理链路状态。很多情况下驱动加载了，但链路是坏的，会造成「看起来驱动没问题，却怎么也连不上」的假象。

# 查看所有网络接口的链路状态 sudo lspci -v -s $(lspci | grep -i ethernet | awk '{print $1}' | head -1) # 查看接口速率、双工模式和链路是否 up sudo ethtool enp3s0

ethtool输出中重点看三个字段：Speed应该是2500Mb/s，Duplex是Full，Link detected是yes。如果 Speed 显示1000Mb/s或者100Mb/s，说明链路协商到了百兆或千兆，先检查网线是不是四芯的，再确认交换端口是否支持 2.5G。现实中打到百兆通常和驱动无关，更多是网线老化。

5.2 跑一次实际吞吐测试，排除驱动瓶颈

ping 通只能证明链路通，不能证明驱动把 2.5G 跑满了。在一个千兆交换机上测试很容易误导，即使驱动的性能只有几百 Mbps，在这个环境里也测不出来。真正验证要用 iperf3，并且在两端都是 2.5G 口直连的情况下：

# 服务端，IP 地址假设为 192.168.1.100，先启动监听 iperf3 -s -i 1 # 客户端，打流测试 60 秒，看实际带宽 iperf3 -c 192.168.1.100 -t 60 -i 5

正常 2.5G 网卡直连跑 iperf3，吞吐应该稳定在 2300Mbps 以上。如果实测只有 900Mbps 左右，说明链路协商在千兆档位，要么网线没接好，要么交换机对应端口插的是千兆口。如果吞吐不稳定、锯齿状波动，先检查网卡是否开启了巨帧、中断合并等特性，和驱动版本无关，反而和 BIOS 里的 PCIe ASPM（电源管理）相关，建议在 BIOS 里直接关掉 ASPM。

5.3 驱动自动加载：重启不慌的配置方法

手工modprobe只对当前会话有效，重启后驱动不会自动加载。这一步不能靠rc.local或 systemd 里硬写modprobe，因为模块加载时机在网络配置之前，正确的做法是把模块名写入模块加载配置：

# 创建模块加载配置，写入 r8125 echo "r8125" | sudo tee /etc/modules-load.d/r8125.conf # 确认模块在 depmod 数据库里的依赖完整 sudo depmod -a

/etc/modules-load.d/r8125.conf这个文件会让 systemd 在启动早期加载 r8125 模块。depmod -a是重新生成模块依赖树，如果你make install之后没跑过，新模块可能没有被 depmod 收录，前面步骤虽然成功但重启还是会失效。这个细节经常被人忽略，以为make install就会自动处理一切，实际上部分老版本 Makefile 不会主动触发 depmod。

6. 一条命令复现安装：把整个流程固化成脚本

手动步骤全部走通后，我习惯把整个过程写成一个 shell 脚本，方便后续在多台机器上部署。脚本不追求一行完成所有事，核心是每一步都要有明确的失败退出：

#!/bin/bash # r8125 离线安装脚本，基于离线包 root 目录执行 set -e # 检查是否 root if [ "$EUID" -ne 0 ]; then echo "请用 sudo 或 root 运行此脚本" exit 1 fi # 参数 1：离线包所在目录 DRV_DIR=${1:-$(pwd)} DEB_DIR="$DRV_DIR/deb_packages" SRC_DIR="$DRV_DIR/r8125_src" echo ">>> 开始安装依赖..." cd "$DEB_DIR" dpkg -i *.deb || apt-get install -f echo ">>> 确认编译工具链..." gcc --version && make --version echo ">>> 开始编译驱动源码..." cd "$SRC_DIR" make clean || true make make install echo ">>> 加载模块..." rmmod r8169 2>/dev/null || true modprobe r8125 # 验证装入 lsmod | grep r8125 && ip link

脚本里的set -e是关键，任何一个命令失败都直接退出，不会让后续步骤带着错误继续。make clean || true的意思是首次编译时没有历史产物，clean 会返回非零退出码，|| true吞掉这个错误避免脚本提前退出。rmmod r8169 2>/dev/null || true同理，如果系统里本来就没加载 r8169，rmmod 报错也不影响继续。

从那以后我在每次批量部署前，都会强制走一遍这个脚本，并且把输出的每行日志保存下来。确认新机器环境没问题后再批量推送，而不是面对面每台机器手工点命令。断网环境下的网卡驱动安装，最怕的不是报错，而是报错时你分不清是环境问题还是操作问题——脚本能帮你把环境问题排除掉，希望帮到你。

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