Gazelle 部署排障指南：4 步跑通网卡绑定与 gazelle-pdump 抓包
【免费下载链接】gazelleA high performance user-mode stack, which powered by dpdk and lwip项目地址: https://gitcode.com/openeuler/gazelle
部署 Gazelle 时遇到No NIC is matched、Cannot set affinity，或者 DPDK 绑定过的网卡在 tcpdump 里一个包都抓不到？这篇 Gazelle 排障指南带你按网卡绑定、启动验证、抓包、报错速查 4 步走，把常见故障自己查明白。
第一步：把网卡绑定到 DPDK 用户态驱动
Gazelle 的用户态驱动绕过内核直接和网卡打交道，所以第一件事是先把网卡从内核驱动手里接过来。先确认网卡 MAC，并把它写进/etc/gazelle/lstack.conf的devices字段：
ip a预期现象：找到要用的网卡（比如 enp3s0）及其 MAC 地址。
然后加载驱动并绑定，两种方式二选一：
# 硬件 IOMMU 可用时，推荐 vfio-pci modprobe vfio-pci # IOMMU 不可用且 vfio 支持 noiommu 时：modprobe vfio enable_unsafe_noiommu_mode=1 && modprobe vfio-pci # 其它情况用 igb_uio：modprobe igb_uio dpdk-devbind -b vfio-pci enp3s0预期现象：命令执行完无报错输出。再验证：
dpdk-devbind -s预期输出：网卡出现在 "Network devices using DPDK-compatible driver" 一节下，内核ip a里对应的接口消失。
绑定后还要确认网卡驱动库是否要手动加载，速查如下：
| 网卡 | 驱动库 | 需要 dpdk-devbind 绑定？ |
|---|---|---|
| hinic（Hi1822） | librte_net_hinic.so（已链接） | 需要 |
| hns3（HNS 系列） | librte_net_hns3.so（需 -d 加载） | 需要 |
| mlx5（ConnectX 系列） | librte_net_mlx5.so（需 -d 加载） | 不需要 |
| ixgbe（X520/X550） | librte_net_ixgbe.so（已链接） | 需要 |
| e1000/e1000e/vmxnet3 虚拟网卡 | 对应 librte_net_*.so（需 -d 加载） | 需要 |
未链接的库，在 lstack.conf 的dpdk_args里追加-d /usr/lib64/<库名>.so；库路径可以用rpm -ql dpdk | grep <驱动关键字>确认。
🔧 卡在这怎么办：NUMA 不匹配报错
启动日志里出现这两行：
mlx5_common: Failed to initialize global MR share cache. # 报错关键行：跨 NUMA 访问内存失败 EAL: Requested device 0000:81:00.0 cannot be used说明网卡挂在某个 NUMA 节点上，而 Gazelle 用的 CPU 核和大页在另一个节点。两种改法：
改法 A，给网卡所在节点补大页：
echo 1024 > /sys/devices/system/node/node1/hugepages/hugepages-2048kB/nr_hugepages预期输出：grep Huge /proc/meminfo能看到 node1 上的页数。
改法 B，把 lstack.conf 里num_cpus改成和网卡同 NUMA 的核，例如num_cpus="2,22"，重启进程。
🔧 卡在这怎么办：大页内存没配或配错节点
现象：启动时看到EAL: Cannot get hugepage information，或 FreeHugePages 为 0。修复：
# 在 node0 分配 2M*1024=2G 大页（ltran 至少 1064MB，lstack 每个协议栈线程至少 800MB，按需加量） echo 1024 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages mkdir -p /mnt/hugepages-lstack /mnt/hugepages-ltran mount -t hugetlbfs nodev /mnt/hugepages-lstack -o pagesize=2M mount -t hugetlbfs nodev /mnt/hugepages-ltran -o pagesize=2M预期输出：grep Huge /proc/meminfo中 FreeHugePages 大于 0。两个挂载点必须挂同样页大小的大页；内存开大时建议用 1G 大页，避免占太多文件描述符。
🔧 卡在这怎么办：容器环境报 Cannot set affinity
日志出现EAL: FATAL: Cannot set affinity，说明num_cpus里的核不在容器启动时分配的 CPU 集合内。修复：
cat /sys/fs/cgroup/cpuset/cpuset.cpus预期输出：容器可用的 CPU 编号范围。把 lstack.conf 的num_cpus改成这个范围内的核即可。
自检：做完这步，你应该看到……网卡从内核接口列表里消失，dpdk-devbind -s显示它已绑定到 DPDK 驱动，启动日志不再出现绑定相关报错。
第二步：确认协议栈真的起来了
绑定完成后，按顺序启动 ltran（用 ltran 模式时）和应用程序：
ltran --config-file /etc/gazelle/ltran.conf GAZELLE_BIND_PROCNAME=redis-server \ LD_PRELOAD=/usr/lib64/liblstack.so redis-server redis.conf预期现象：日志里出现LSTACK: gazelle network init:342 gazelle network init success和gazelle_stack_thread:59 stack 00 start success；如果你看到No NIC is matched，回到第一步检查绑定和devices的 MAC。
接着用下面几条命令验证：
gazellectl lstack show ip预期输出：打印出 lstack 注册的 IP，与 lstack.conf 里的host_addr一致。
gazellectl lstack show -k nic-features预期输出：打印网卡 offload 与协议特性状态。
# 在对端机器上 ping Gazelle 的 host_addr ping 192.168.1.10预期输出：ping 有正常回显（Gazelle 支持长度不超过 14792B 的 ping 报文）。
自检：做完这步，你应该看到……对端能 ping 通host_addr，gazellectl 能正常输出统计。
第三步：用 gazelle-pdump 抓包并过滤 pcap 文件
在 Gazelle 绑定过的网卡上跑 tcpdump，一个包都出不来——不是包丢了，而是网卡已被 DPDK 用户态完全接管，不再经过内核，内核里的 tcpdump 自然没有入口。这也是"DPDK 抓不到包"的结构性原因，不是过滤语句写错了。
gazelle-pdump 是 Gazelle 的从进程，借助 DPDK 多进程模式和主进程（lstack/ltran）共享网卡驱动收发队列，把报文拷贝出来按 pcap 格式写成文件，Wireshark 可以直接打开。注意：ltran 模式下它抓到的是 ltran 与网卡直接通信的流量，想看某个 lstack 实例的流量，还要再用 tcpdump 过滤。
常用参数一句话说明：
device_id：被抓网卡的 PCI 地址，必须和dpdk-devbind -s结果一致；vdev 类网卡（如 af_xdp）填--vdev的值rx-dev/tx-dev：收、发包存放路径，两者配同一路径则一个文件里同时有收发-d：手动加载网卡驱动库，库名对照第一步的速查表queue=*：抓全部队列
# hinic：库已链接，直接跑 gazelle-pdump -- --pdump 'device_id=0000:01:00.0,queue=*,rx-dev=/root/capture-rx.pcap,tx-dev=/root/capture-tx.pcap' # af_xdp：vdev 网卡，device_id 填 --vdev 的值 gazelle-pdump -d /usr/lib64/librte_net_af_xdp.so -- --pdump 'device_id=net_af_xdp,queue=*,rx-dev=/root/capture-rx.pcap,tx-dev=/root/capture-tx.pcap' # mlx：需要加载驱动库 gazelle-pdump -d /usr/lib64/librte_net_mlx5.so -- --pdump 'device_id=0000:07:00.0,queue=*,rx-dev=/root/capture-rx.pcap,tx-dev=/root/capture-tx.pcap'预期现象：按 Ctrl+C 停止后，终端打印 PDUMP DEBUG STATS，其中 packets dequeued 大于 0，说明抓到了包。
拿到 pcap 文件后，可以用 tcpdump 继续过滤：
# 按源 IP 过滤并另存 tcpdump -r /root/capture.pcap src host 192.168.1.10 -w /root/filter-capture.pcap # 只看 80 端口的流量 tcpdump -r /root/capture.pcap port 80预期输出：逐条打印报文记录，能看到 IP、端口和 TCP 标志位。
💡 device_id 对不上时的修复
看到PDUMP: client request for pdump enable/disable failed时，基本可以断定你传的device_id不是主进程实际在用的网卡。修复只需一步：dpdk-devbind -s查出真实 PCI 地址，改写命令里的device_id。
自检：做完这步，你应该看到……应用程序跑流量时 pcap 文件持续变大，Ctrl+C 后 dequeued 包数大于 0。
第四步：报错症状速查
部署和抓包阶段的高频报错，统一按"现象 → 原因 → 一条修复"组织。
1. 启动报 No NIC is matched
LSTACK: ethdev_port_id:369 No NIC is matched # 报错关键行：没找到匹配的网卡 EAL: Error - exiting with code: 1 Cause: gazelle_network_init:306 init_dpdk_ethdev failed- 原因：网卡没绑定到 DPDK 驱动，或 lstack.conf 的
devices与真实网卡 MAC 对不上。 - 修复：
dpdk-devbind -b vfio-pci enp3s0，再用ip a核对devices的值。
2. hinic VF 报 nic mac not match
LSTACK: ethdev_port_id:363 nic mac:02:09:c0:f5:05:bc not match # 报错关键行：MAC 不一致 LSTACK: ethdev_port_id:369 No NIC is matched- 原因：hinic VF 直通场景下 VF 的 MAC 是随机的，配置里必须填你手动固定的 MAC。
- 修复：
ip link set enp5s0 vf 0 mac 18:3d:5e:bf:6c:22预期现象：ip link show enp5s0里 VF 0 的 MAC 变成你设置的值；随后把这个 MAC（而不是ip a显示的那个）写进 lstack.conf 的devices。
3. gazelle-pdump 报设备未由主进程驱动
Device 0000:02:08.0 is not driven by the primary process # 报错关键行：该网卡不由主进程驱动 EAL: Requested device 0000:02:08.0 cannot be used PDUMP: client request for pdump enable/disable failed- 原因：gazelle-pdump 指定的
device_id不是 lstack/ltran 实际在用的网卡。 - 修复：
dpdk-devbind -s查出真实 PCI 地址，改写device_id参数。
4. vdev 初始化失败
vdev_probe(): failed to initialize net_af_xdp device EAL: Bus (vdev) probe failed. EAL: Error - exiting with code: 1- 原因：没有加载网卡对应的驱动库。
- 修复：命令后加
-d /usr/lib64/librte_net_af_xdp.so，其它网卡对照第一步速查表找对应库。
5. vdev 创建失败 create_mp_ring_vdev
EAL: Failed to hotplug add device EAL: Error - exiting with code: 1 Cause: vdev creation failed:create_mp_ring_vdev:700- 原因：lstack/ltran 没链接 pcap 驱动库（DPDK 21.11 为 librte_net_pcap.so，19.11 为 librte_pmd_pcap.so），多进程共享内存通道建不起来。
- 修复：在 DPDK 编译配置里打开 PDUMP 选项重编 dpdk，或直接用 openEuler 打包的 gazelle-pdump。
自检：做完这步，你应该能把启动或抓包时遇到的任何报错日志，对上其中一条修复命令。
避坑清单
- mlx5 系列网卡不需要 dpdk-devbind 绑定，其余物理网卡都要先绑定再启动。
devices的 MAC 必须和真实网卡核对；hinic VF 用手动设置的固定 MAC，不要用ip a看到的。num_cpus的核要和网卡在同一 NUMA，且落在容器分配的 CPU 集合内。/mnt/hugepages-lstack与/mnt/hugepages-ltran两个挂载点必须同页大小；ltran 至少 1064MB，lstack 每个协议栈线程至少 800MB。- ltran 模式下 gazelle-pdump 抓的是 ltran 网卡级流量，区分具体 lstack 实例要靠 tcpdump 过滤表达式。
更多细节可参考 用户指南 doc/zh/user-guide.md、网卡支持与使用 doc/zh/nic-support.md、[
【免费下载链接】gazelleA high performance user-mode stack, which powered by dpdk and lwip项目地址: https://gitcode.com/openeuler/gazelle
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
