用于集群多轨fullmesh网络丢包率检查并汇总为CSV报表输出

cluster_ping_check脚本使用手册

版本	1.0	发布人	张建	发布日期	2026年3月8日

适用环境：AI训练集群 / HPC集群 / RoCE / InfiniBand 网络

脚本语言：Bash

1. 脚本简介

用于 AI 集群网络连通性检测 的自动化脚本工具，主要用于验证：

• RoCE / InfiniBand 网络连通性
• 多网卡网络路径检查
• 节点间通信矩阵
• 网络丢包率
• 网络延迟
• 网络异常链路识别

脚本通过 ping + 并发任务 + 网络矩阵分析，实现对集群网络的快速验证。

实测在264个AI计算节点（每节点8个IB网口）规模下，采用默认选项测试一轮（264 * 8 = 2112个ping）耗时约30秒，使用-fullmesh选项进行全互联测试，一轮（264 * 8 * 8 = 16896个ping）耗时约7分钟。

2.运行环境

建议环境：

项目	要求
OS	Linux
Bash	≥ 4.x
ping	标准Linux工具
sed	GNU sed
awk	GNU awk
RDMA	可选

3. 脚本结构

示例目录：

cluster_ping_check/

├── cluster_ping_check.sh
├── nodes_ip.txt
└── cluster_ping_check_log/

4. 节点列表文件

默认文件：

nodes_ip.txt

格式：

node_name ip1 ip2 ... ipN

说明：

字段	含义
node_name	节点名称
ip1	网络1
ip2	网络2

IP顺序需要 与接口顺序一致，实际节点列表文件示例：

5. 使用流程

Step 1

配置：

nodes_ip.txt

Step 2

选择一个健康的节点执行

./cluster_ping_check.sh -fullmesh -c 5 -p 1000

Step 3

检查：

FAIL LINKS 和 节点连通性矩阵

Step 4

查看 CSV

cluster_ping_check_log/

6. 使用方法

6.1 基本运行

bash cluster_ping_check.sh

命令帮助界面（实际输出示例）：

默认参数说明：

参数	默认
hostfile	nodes_ip.txt
ping count	1
timeout	1s
parallel	20

6.2 指定 Hostfile

./cluster_ping_check.sh -hostfile my_nodes

6.3 FULLMESH 网络测试

./cluster_ping_check.sh -fullmesh

适用于：

• 复杂网络
• 交换机排错

6.4 增加 Ping 次数

./cluster_ping_check.sh -c 5  # 推荐设置为10以内，并搭配-p选项提高执行速度

每个测试发送：

5个 ping 包

6.5 调整 Timeout

./cluster_ping_check.sh -t 3  # 默认为1秒，过小的数值会导致ping失败，如0.1秒。网络极差时可以适当增大排查问题

表示：

3 秒 timeout

6.6 调整并发数

./cluster_ping_check.sh -p 1000  # 未使用-c选项时，增大并发数效果不明显，使用-c 10这类选项时，增大并发数提速效果显著

适用于：

• 大规模集群
• 使用-c指定了更多的测试次数时
• 减少测试时间

6.7 完整命令示例

./cluster_ping_check.sh -hostfile nodes_ip.txt -fullmesh -c 5 -t 2 -p 1000

含义：

参数	含义
fullmesh	全网互测
5	每次5个包
timeout=2	2秒
1000并发	高速检测

7.结果输出

7.1. FAIL 链路汇总输出

7.2 端口状态矩阵输出

颜色：

状态	颜色
OK	绿色
FAIL	红色

8. 日志文件

位置：

cluster_ping_check_log/

文件名示例：

net_check_20260305_102031.csv

实际输出示例：

9. 功能特性

9.1 自动检测 RDMA 设备

自动读取：

/sys/class/infiniband

并显示：

• RDMA设备名称
• GUID
• 物理状态
• 链路状态
• 对应网络接口
• 本机IP

实际输出示例：

9.2 自动检测网络接口

自动识别以下接口：

ib*
mlx*
ens*
eth*

只检测 存在IP地址的接口。

9.3 支持两种测试模式

NORMAL模式（默认）

每个接口只测试 对应网络，例如：

本机接口	对端IP
ib0	node2 ib0
ib1	node2 ib1

适用于：

• 标准RoCE网络

FULLMESH模式

所有接口 互相测试，例如：

本机接口	对端IP
ib0	node2 ib0
ib0	node2 ib1
ib1	node2 ib0
ib1	node2 ib1

适用于：

• 多路径网络
• 复杂Fabric
• 交换机排错

9.4 并发网络测试

默认：

20 并发 ping

可调节：

-p 1000

适用于：

• 大规模集群
• 减少检测时间

9.5 延迟统计

Ping延迟会自动统计至csv日志文件，4个数值分别解释如下：

0.059/0.177/0.519/0.159  # 4个数值分别代表：最小延时/平均延时/最大延时/平均偏差（延迟抖动）

9.6 丢包统计

Ping丢包率会自动统计至csv日志文件

3  # 表示ping丢包率为3%

10. 常见问题

10.1 出现 FAIL

可能原因：

原因	排查
IP配置错误	检查 hostfile
VLAN错误	检查交换机
NIC down	ip link
RDMA link down	ibstat
防火墙	关闭 firewalld

10.2 RDMA设备未显示

检查：

ibstat

或：

rdma link