PVE系统中将2.5G网卡驱动由r8169切换为r8125的完整实践记录

一、背景说明

目前许多主板集成的2.5G网卡采用的是Realtek RTL8125芯片， 在Proxmox VE（简称PVE）系统中，默认会加载通用驱动模块：

r8169

虽然该驱动可以实现基本网络功能，但其性能和稳定性相对有限。

目标设定

本文旨在不重装系统的前提下，完成两张RTL8125网卡从默认驱动

r8169

向专用高性能驱动

r8125

的平滑迁移，并确保配置在重启后持续生效。 整篇内容基于一次实际操作的成功案例整理而成，所有关键命令均附带真实执行日志片段，便于初学者按步骤复现。

二、快速命令清单（适用于有经验用户）

以下为熟练用户的精简操作流程，建议顺序执行：

# 0. 查看当前驱动状态（可选）
lsmod | grep -E "r8169|r8125|r8168"
lspci -k | grep -A 3 RTL8125

# 1. 安装DKMS及内核头文件
apt update
apt install -y dkms pve-headers-$(uname -r)

# 2. 获取r8125源码包
cd /tmp
git clone https://github.com/awesometic/realtek-r8125-dkms.git
cd /tmp/realtek-r8125-dkms

# 3. 使用DKMS安装新驱动
./dkms-install.sh
dkms status

# 4. 屏蔽旧驱动r8169
echo "blacklist r8169" > /etc/modprobe.d/blacklist-r8169.conf
cat /etc/modprobe.d/blacklist-r8169.conf

# 5. 更新initramfs镜像
update-initramfs -u

# 6. 手动加载r8125驱动（可选）
modprobe r8125
lsmod | grep -E "r8169|r8125"

# 7. 重启系统
reboot

# 8. 验证结果
lspci -k | grep -A 3 RTL8125
lsmod | grep -E "r8169|r8125"
ip link show
ping -c 3 192.168.1.2   # 替换为你的网关IP

详细操作说明与日志示例见后续章节。

三、当前运行环境信息

为方便对照自身设备情况，列出本次操作的具体软硬件环境：

• 操作系统：Proxmox VE
• 内核版本：
  

  Linux 6.8.12-4-pve (2024-11-06T15:04Z)

• 网卡型号：Realtek
  

  RTL8125 2.5GbE Controller

• 网卡数量：2张
• 原始驱动：
  

  r8169

• 目标驱动：
  

  r8125

  
  （通过DKMS方式安装，版本号为
  

  9.016.01

  
  ）

四、整体操作流程概览

为帮助理解整个过程，先梳理清晰的操作路径：

1. 确认当前网卡及其所用驱动状态
2. 检查系统是否已存在r8125驱动模块
3. 安装DKMS工具与对应内核头文件
4. 获取r8125驱动源码（使用realtek-r8125-dkms项目）
5. 利用DKMS编译并注册新驱动
6. 屏蔽原生r8169驱动防止自动加载
7. 更新初始RAM文件系统（initramfs）
8. 手动加载r8125并重启系统
9. 重启后验证驱动生效及网络连通性

接下来将依照上述步骤逐一展开。

五、前置检查：当前网卡使用的驱动类型

5.1 查询已加载的网卡驱动模块

执行命令：

lsmod | grep -E "r8169|r8125|r8168"

实战输出节选：

root@pve:~# lsmod | grep -E "r8169|r8125|r8168"
r8169                 110592  0

结果显示仅加载了

r8169

未发现

r8125

表明当前尚未启用专用驱动。

5.2 检查RTL8125网卡绑定的内核驱动

运行指令：

lspci -k | grep -A 3 RTL8125

实际输出：

01:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8125 2.5GbE Controller (rev 05)
        Subsystem: Realtek Semiconductor Co., Ltd. RTL8125 2.5GbE Controller
        Kernel driver in use: r8169
        Kernel modules: r8169
--
04:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8125 2.5GbE Controller (rev 04)
        Subsystem: Micro-Star International Co., Ltd. [MSI] RTL8125 2.5GbE Controller
        Kernel driver in use: r8169
        Kernel modules: r8169

可见两块RTL8125网卡均使用

r8169

作为驱动程序。

5.3 查看网卡接口与桥接配置情况

使用命令查看接口状态：

ip link show

部分输出示例：

2: enp1s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master vmbr1 state UP group default qlen 1000
    link/ether 88:c9:b3:bb:d2:1f brd ff:ff:ff:ff:ff:ff
3: enp4s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master vmbr0 state UP group default qlen 1000
    link/ether 2c:f0:5d:da:a1:ab brd ff:ff:ff:ff:ff:ff
5: vmbr0: <BROADCAST,MULTICAST,UP,LOWER_UP> ...
6: vmbr1: <BROADCAST,MULTICAST,UP,LOWER_UP> ...

结合路由表信息

ip route show

可得出结论：

enp4s0

经由

vmbr0

承担管理接口及默认路由功能；
而

enp1s0

通过

vmbr1

用于其他业务用途。
综上所述，两张网卡均处于工作状态且均依赖

r8169

驱动，因此驱动更换将影响全部相关接口。

六、确认系统是否预装r8125驱动

执行如下命令检测是否存在r8125模块：

find /lib/modules/$(uname -r) -name "*r8125*" -o -name "*8125*"

同时查看DKMS当前管理状态：

dkms status

实战反馈：

root@pve:~# find /lib/modules/$(uname -r) -name "*r8125*" -o -name "*8125*"
root@pve:~#

root@pve:~# dkms status
-bash: dkms: command not found

分析可知：系统既无r8125驱动模块，也未安装DKMS服务，需从源码进行完整部署。

七、安装DKMS及相关内核开发组件

7.1 同步软件包索引

执行更新命令：

apt update

部分执行日志：

Hit:1 https://mirrors.ustc.edu.cn/debian bookworm InRelease
...
Err:7 https://enterprise.proxmox.com/debian/ceph-quincy bookworm InRelease
  401  Unauthorized [IP: 51.79.228.122 443]
...
E: The repository 'https://enterprise.proxmox.com/debian/ceph-quincy bookworm InRelease' is not signed.

提示中的401错误源于
PVE企业版Ceph仓库
因未订阅而导致无法访问，此问题不影响本次驱动更换任务，可忽略。

7.2 安装必要组件

继续执行：

apt install -y dkms pve-headers-$(uname -r)

此举将安装动态内核模块支持框架以及当前运行内核所需的头文件，为后续编译提供基础支持。

八、下载并部署r8125驱动源码

进入临时目录并克隆开源项目：

cd /tmp
git clone https://github.com/awesometic/realtek-r8125-dkms.git
cd /tmp/realtek-r8125-dkms

九、通过DKMS构建并安装驱动

执行内置安装脚本：

./dkms-install.sh

完成后查看DKMS管理状态：

dkms status

正常情况下应显示r8125驱动已成功注册并构建完成。

十、禁用旧驱动r8169

为避免系统启动时自动加载老旧驱动，创建黑名单规则：

echo "blacklist r8169" > /etc/modprobe.d/blacklist-r8169.conf

验证写入内容：

cat /etc/modprobe.d/blacklist-r8169.conf

确保输出为“blacklist r8169”。

十一、更新初始内存文件系统

使黑名单设置在启动时生效，必须重建initramfs：

update-initramfs -u

该步骤确保新的模块策略被固化进引导镜像。

十二、手动加载新驱动并准备重启

可选地立即加载新驱动以测试兼容性：

modprobe r8125

再次检查模块加载状态：

lsmod | grep -E "r8169|r8125"

确认r8125已载入且无冲突。

十三、重启系统

执行重启命令：

reboot

十四、重启后验证驱动切换效果

系统恢复后，重点验证以下几项：

• 驱动绑定情况：

  lspci -k | grep -A 3 RTL8125

  确认输出中显示使用的是r8125而非r8169。
• 模块加载状态：

  lsmod | grep -E "r8169|r8125"

  应仅出现r8125，r8169不应被加载。
• 网络接口状态：

  ip link show

  所有网卡接口应正常呈现。
• 网络连通性测试：

  ping -c 3 192.168.1.2

  （请替换为你本地网络的网关地址），确保通信正常。

若以上各项均通过，则表示驱动切换成功，系统现已运行于优化后的r8125驱动之上，具备更佳的2.5G网络性能与稳定性。

不影响后续 dkms 与内核头文件的安装操作，相关提示可安全忽略。

2.2 安装 dkms 及匹配的内核头文件

使用以下在实际环境中验证有效的命令进行安装：

apt install -y dkms pve-headers-$(uname -r)

执行该命令后，在你的系统中输出结果如下所示：

root@pve:~# apt install -y dkms pve-headers-6.8.12-4-pve
Note, selecting 'proxmox-headers-6.8.12-4-pve' instead of 'pve-headers-6.8.12-4-pve'
dkms is already the newest version (3.0.10-8+deb12u1).
...
Setting up proxmox-headers-6.8.12-4-pve (6.8.12-4) ...

安装完成后，可能出现“已是最新版本”的提示，均属正常情况。

关键点在于确认已成功安装与当前运行内核版本相匹配的头文件包。

dkms

proxmox-headers-6.8.12-4-pve

若系统未预装 git 工具，建议一并安装（此步骤适用于尚未安装 git 的用户，你当前环境已具备，无需重复操作）：

apt install -y git

七、获取 r8125 驱动源码（realtek-r8125-dkms）

3.1 切换至临时目录并克隆代码仓库

进入临时工作目录，并从 GitHub 拉取 Realtek r8125 的 DKMS 封装驱动：

cd /tmp
git clone https://github.com/awesometic/realtek-r8125-dkms.git

实际执行过程中的输出信息如下：

root@pve:/tmp# git clone https://github.com/awesometic/realtek-r8125-dkms.git
Cloning into 'realtek-r8125-dkms'...
remote: Enumerating objects: 617, done.
remote: Counting objects: 100% (206/206), done.
...
Resolving deltas: 100% (437/437), done.

进入克隆后的目录，检查内容是否存在：

cd /tmp/realtek-r8125-dkms
ls -la

部分输出示例如下：

drwxr-xr-x 5 root root  4096 Nov 23 19:41 .
drwxrwxrwt 9 root root  4096 Nov 23 19:41 ..
-rw-r--r-- 1 root root  2469 Nov 23 19:41 autorun.sh
drwxr-xr-x 3 root root  4096 Nov 23 19:41 debian
-rw-r--r-- 1 root root   379 Nov 23 19:41 dkms.conf
...
drwxr-xr-x 2 root root  4096 Nov 23 19:41 src

进一步查看 dkms 配置文件，确认模块名称及版本信息：

cat dkms.conf

输出内容如下：

PACKAGE_NAME="realtek-r8125"
PACKAGE_VERSION="9.016.01"
...
BUILT_MODULE_NAME[0]="r8125"
BUILT_MODULE_LOCATION[0]="src"
DEST_MODULE_LOCATION[0]="/updates"
AUTOINSTALL="yes"

八、通过 dkms 编译并部署 r8125 驱动

4.1 推荐方式：一键安装脚本

在以下目录中执行安装脚本：

cd /tmp/realtek-r8125-dkms
./dkms-install.sh

/tmp/realtek-r8125-dkms

执行过程中部分输出日志如下：

About to run dkms install steps...
Creating symlink /var/lib/dkms/r8125/9.016.01/source -> /usr/src/r8125-9.016.01
...
Building module:
Cleaning build area...
'make' -j12 KVER=6.8.12-4-pve BSRC=/lib/modules/6.8.12-4-pve modules......
Signing module /var/lib/dkms/r8125/9.016.01/build/src/r8125.ko
...
r8125.ko:
 - Installation
   - Installing to /lib/modules/6.8.12-4-pve/updates/dkms/
depmod...
Finished running dkms install steps.

当看到如下提示时：

Finished running dkms install steps.

表明驱动已完成编译并成功注册到系统中。

4.2 验证模块文件与 dkms 状态

检查编译生成的内核模块是否存在于指定路径：

ls -la /lib/modules/$(uname -r)/updates/dkms/r8125.ko

同时查看 dkms 当前管理的模块状态：

dkms status

输出结果如下：

root@pve:~# ls -la /lib/modules/$(uname -r)/updates/dkms/r8125.ko
-rw-r--r-- 1 root root 505869 Nov 23 19:43 /lib/modules/6.8.12-4-pve/updates/dkms/r8125.ko

root@pve:~# dkms status
r8125/9.016.01, 6.8.12-4-pve, x86_64: installed

至此，新驱动已成功集成进系统。下一步是确保系统优先加载 r8125 而非默认的 r8169 驱动。

九、禁用旧版 r8169 驱动（加入黑名单）

5.1 创建黑名单配置文件

将 r8169 模块列入禁止自动加载列表：

echo "blacklist r8169" > /etc/modprobe.d/blacklist-r8169.conf
cat /etc/modprobe.d/blacklist-r8169.conf

执行结果如下：

root@pve:~# cat /etc/modprobe.d/blacklist-r8169.conf
blacklist r8169

该操作的作用是通知内核：今后不再自动载入 r8169 模块。

十、更新 initramfs 以持久化配置

由于涉及内核模块加载策略变更，需重新生成 initramfs 镜像：

update-initramfs -u

执行更新后部分输出如下：

update-initramfs: Generating /boot/initrd.img-6.8.12-4-pve
Running hook script 'zz-proxmox-boot'..
No /etc/kernel/proxmox-boot-uuids found, skipping ESP sync.

完成此步后，重启时系统将依据新的 initramfs 配置来加载驱动模块。

十一、重启前手动加载 r8125（用于初步验证）

此步骤非强制，但有助于提前确认模块可用性。

# 手动加载 r8125 模块
modprobe r8125

# 查看当前内存中活跃的网卡驱动
lsmod | grep -E "r8169|r8125"

# 显示 r8125 模块基本信息
modinfo r8125 | head -20

部分实战输出如下：

root@pve:~# lsmod | grep -E "r8169|r8125"
r8125                 307200  0
r8169                 110592  0

root@pve:~# modinfo r8125 | head -20
filename:       /lib/modules/6.8.12-4-pve/updates/dkms/r8125.ko
version:        9.016.01-NAPI
license:        GPL
description:    Realtek r8125 Ethernet controller driver
...

说明：此时 r8125 模块已成功载入内存，但物理网卡仍由 r8169 驱动控制。真正的切换将在重启后由系统自动完成设备绑定。

十二、重启系统以启用新驱动

执行重启命令：

reboot

待系统启动完毕后，通过控制台或 SSH 登录，继续进行功能验证。

十三、重启后验证 r8125 驱动是否生效

8.1 查看网卡当前使用的驱动

使用以下命令检测 RTL8125 设备所关联的驱动：

lspci -k | grep -A 3 RTL8125

输出结果如下：

01:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8125 2.5GbE Controller (rev 05)
        Subsystem: Realtek Semiconductor Co., Ltd. RTL8125 2.5GbE Controller
        Kernel driver in use: r8125
        Kernel modules: r8169, r8125
--
04:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8125 2.5GbE Controller (rev 04)
        Subsystem: Micro-Star International Co., Ltd. [MSI] RTL8125 2.5GbE Controller
        Kernel driver in use: r8125
        Kernel modules: r8169, r8125

重点关注这一行：

Kernel driver in use: r8125

表明两张 RTL8125 网卡均已切换至 r8125 驱动。

8.2 确认仅加载了 r8125 模块

检查当前运行模块中是否排除了 r8169：

lsmod | grep -E "r8169|r8125"

输出如下：

root@pve:~# lsmod | grep -E "r8169|r8125"
r8125                 307200  0

仅存在

r8125

而无

r8169

说明黑名单机制已起效。

8.3 检查网络接口状态

查看网卡接口详情：

ip link show

节选输出如下：

2: enp1s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq master vmbr1 state UP mode DEFAULT group default qlen 1000
    link/ether 88:c9:b3:bb:d2:1f brd ff:ff:ff:ff:ff:ff
3: enp4s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq master vmbr0 state UP mode DEFAULT group default qlen 1000
    link/ether 2c:f0:5d:da:a1:ab brd ff:ff:ff:ff:ff:ff
5: vmbr0: <BROADCAST,MULTICAST,UP,LOWER_UP> ...
6: vmbr1: <BROADCAST,MULTICAST,UP,LOWER_UP> ...

可见：

• 所有接口处于

UP

• 状态
• 队列类型由原先的

pfifo_fast

• 变为

mq

• （支持多队列），这是 r8125 驱动的典型特征之一

8.4 测试网络连通性

发起 ping 测试验证基本通信能力：

ping -c 3 192.168.1.2

输出结果如下：

64 bytes from 192.168.1.2: icmp_seq=1 ttl=64 time=0.734 ms
64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=0.677 ms
64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=0.904 ms
...
3 packets transmitted, 3 received, 0% packet loss

结论：默认网关可达，网络功能正常，驱动切换顺利完成。

十四、多网卡场景下的注意事项（本机配备双 RTL8125 网卡）

由于两张网卡均为 RTL8125 型号，故会统一由同一内核模块驱动：

r8169

r8125

建议提前明确哪张为管理口网卡。

通常 PVE 的 Web 管理界面绑定于特定接口，实践中可通过以下方式识别：

vmbr0

在你的环境中具体表现为：

enp4s0

→

vmbr0

→ 默认路由

enp1s0

切换过程中网络连接会短暂中断，特别是在执行重启操作时。因此强烈建议采取以下方式操作：

• 在机房现场进行操作，或
• 通过 IPMI / iKVM，或者使用显示器和键盘直连服务器进行管理。

十五、故障排查建议

问题 1：重启后网卡无法工作或未获取到 IP 地址

可能原因包括：

• initramfs

  驱动更新未成功完成
• 黑名单配置未生效

• r8169

  r8169 模块仍被系统加载

• r8125

  r8125 驱动未能成功编译或安装

建议使用的排查命令如下：

# 查看黑名单文件是否正确配置
cat /etc/modprobe.d/blacklist-r8169.conf

# 重新生成 initramfs 镜像以确保配置生效
update-initramfs -u

# 检查 DKMS 模块的当前状态
dkms status

问题 2：r8125 模块加载失败或系统无法识别网卡

可能原因：

• 所用内核版本与 r8125 驱动不兼容
• 编译过程中缺少必要的依赖包

推荐排查方法：

# 查阅内核日志中关于 r8125 的错误信息
dmesg | grep -i r8125
journalctl -k | grep -i r8125

# 尝试重新安装驱动
cd /tmp/realtek-r8125-dkms
./dkms-remove.sh
./dkms-install.sh

问题 3：无法卸载正在使用的 r8169 模块

若尝试在网卡运行期间执行卸载操作：

modprobe -r r8169

通常会失败，这属于正常现象。

正确的处理方式是：

1. 将 r8169 添加至黑名单
2. 更新 initramfs
3. 重启系统

让系统在启动阶段就避免加载 r8169 模块，而非尝试在线移除。

十六、如何回滚至 r8169（恢复原始状态）

如果对切换结果不满意，或出现兼容性问题，可按以下步骤恢复原始配置：

# 1. 删除黑名单配置文件
rm /etc/modprobe.d/blacklist-r8169.conf

# 2. 卸载当前已加载的 r8125 模块（如存在）
modprobe -r r8125 || true

# 3. 更新初始 RAM 文件系统
update-initramfs -u

# 4. 重启系统以应用变更
reboot

重启完成后，系统将自动重新启用内核自带的

r8169

驱动模块。

十七、总结

本文详细记录了从 r8169 驱动切换至 r8125 的完整实践流程，所有关键操作均附有真实执行日志作为参考。

核心步骤仅需三步：

1. 使用 DKMS 正确安装 r8125 驱动模块
2. 将原生 r8169 模块加入黑名单
3. 更新 initramfs 并重启系统

完成切换后，您将获得：

• 更优的 2.5GbE 网络性能
• 更稳定的网络连接表现
• 对多队列等高级功能的支持

• mq

参考资料

• Realtek r8125 驱动 GitHub 仓库
• DKMS 官方文档
• Proxmox VE 官方文档

测试环境

Proxmox VE, Linux 6.8.12-4-pve

vmbr1