Skip to content

NVMe-oF 接法实战:RDMA 传输、configfs 导出与原生多路径 ​

站里讲 GPUDirect Storage 时说了一句"NVMe-oF 把远端 NVMe 当本地盘",但真正接的时候,卡点从来不在"能不能连上",而在连上之后:断一条链路为什么文件系统变成只读、为什么 128 线程的读取只跑出一半带宽、为什么 nvme list 里同一个命名空间出现四遍。

这篇文章只讲接法与参数语义,不评厂商。所有硬数字都来自官方文档原文:nvme-connect 手册页、内核 ABI 稳定接口文档、以及两家企业发行版的操作手册。

1. 先分清三层,别把三层混成一件事 ​

NVMe-oF 的"接法"其实是三层叠起来的:

层你配的东西出错的表现
链路层RDMA 传输(RoCE / InfiniBand / iWARP),IP 或 IB 地址连不上、丢包、重传
协议层NVMe-oF 控制器:NQN、traddr、trsvcid、队列nvme connect 超时或认证失败
多路径层Linux 原生 NVMe 多路径(ANA / path_state)一条路断了整盘只读,或带宽只用了一条路

NVMe-oF 的三层结构、600 秒默认超时链路与两笔账

nvme-connect 手册页对 --transport=rdma 的原文定义是:"rdma network(RoCE、iWARP、Infiniband、basic rdma 等)"。也就是说 -t rdma 不是"某一种网",而是"RDMA 这一族";具体走 RoCE 还是 IB 由地址与网卡决定,不是命令行参数决定的。这一点先记住,后面排错才不会在错误的层找原因。

2. 寻址三件套:NQN、traddr、trsvcid ​

连接一个 NVMe-oF 子系统,本质上只要三个坐标:

  • -n, --nqn:子系统名(NVMe Qualified Name),target 上创建的子系统标识;
  • -a, --traddr:控制器地址。手册页写明"对使用 IP 寻址的传输(例如 rdma),这里应是 IP 地址";
  • -s, --trsvcid:传输服务标识。手册页原文:"对使用 IP 寻址的传输,这个字段就是端口号;RDMA 传输的默认 IP 端口号是 4420"。

第四个坐标容易被忽略:host 自己的身份。-q, --hostnqn 可以显式指定;不指定时的解析顺序,手册页写得很清楚:先读 /etc/nvme/hostnqn,文件不存在则用 NVMe 主机内核模块自动生成的 NQN。

工程含义:如果 target 侧做了主机白名单(只允许特定 hostnqn 连接),而你在主机上重装过系统、内核模块重新生成了 NQN,就会出现"昨天能连、今天被拒"的现象。此时先比对两边的 hostnqn,而不是去查网络。

3. host 侧:discover 再 connect ​

标准两步:

bash
# 1) 发现:问目标端有哪些子系统
nvme discover -t rdma -a 10.0.0.3 -s 4420

# 2) 连接:按发现结果里的 NQN 连上
nvme connect -t rdma -a 10.0.0.3 -s 4420 -n nqn.2014-08.org.nvmexpress:uuid:xxxx

nvme connect 的关键参数(按 nvme-connect 手册页整理):

参数作用什么时候必须动
-t/--transport传输类型:loop、rdma、tcp、fc决定后面所有参数的有效性
-n/--nqn目标子系统 NQN必填
-a/--traddr、-s/--trsvcid目标地址与端口(RDMA 默认 4420)非默认端口时必填
-w/--host-traddr、-f/--host-iface指定主机侧源地址与网卡多网卡节点选错了出口
-q/--hostnqn主机 NQNtarget 做了白名单
-i/--nr-io-queues覆盖驱动默认创建的 IO 队列数高并发读取要抬高
-W/--nr-write-queues追加用于写 IO 的队列写密集负载
-P/--nr-poll-queues追加轮询队列,服务延迟敏感 IO要低延迟、不怕占核
-Q/--queue-size覆盖队列元素数(队列深度)单队列深度不够
-l/--ctrl-loss-tmo控制器丢失超时,默认 600 秒见下一节,几乎一定要改
-k/--keep-alive-tmo、-c/--reconnect-delay心跳周期与重连间隔链路抖动频繁
-g/--hdr-digest、-G/--data-digest头部/数据校验和链路有静默损坏风险

4. 最贵的默认值:ctrl-loss-tmo=600 ​

这是整套接法里最容易埋事故的一个数。

SUSE 存储管理指南原文说得很直接:路径丢失后,NVMe 子系统会在 ctrl-loss-tmo 指定的时间内持续重连,该时间默认 600 秒;超过之后该路径被移除并通知块层(文件系统),随后默认以只读方式重新挂载文件系统——"这种行为通常不符合预期"。官方给出的建议是把这个值设成无限重试:

bash
nvme connect --ctrl-loss-tmo=-1

换算一下:600 秒是 10 分钟。也就是说,一次交换机重启、一次光模块抖动、一次 target 侧 10 分钟内没恢复,你的训练作业拿到的就不是"IO 报错",而是文件系统静默转只读——正在跑的 checkpoint 写入会失败,而且报错点会落在应用层,看起来像框架 bug。

排查口径:见到"突然只读、重启进程也不好、但网络其实已经恢复",先看 nvme list-subsys 里路径还在不在,再回头看 ctrl-loss-tmo。这也是为什么生产环境应当把 -1 写进连接配置,而不是等出事再改。

顺带一个开机自动连接的落点:SUSE 文档给出的做法是在主机上建 /etc/nvme/discovery.conf,把 discover 的参数写进去,例如 -t tcp -a 10.0.0.3 -s 4420(RDMA 同理换成 -t rdma),这样启动时可按配置发现并连接,不必手工敲命令。

5. target 侧:configfs 十步导出 ​

以 RHEL 10 存储管理手册的 NVMe/RDMA 章节为准,一台已有可用块设备(如本地 NVMe 盘)的节点,导出步骤是固定的十步:

bash
modprobe nvmet-rdma
mkdir /sys/kernel/config/nvmet/subsystems/<nqn>
cd /sys/kernel/config/nvmet/subsystems/<nqn>
echo 1 > attr_allow_any_host            # 仅测试环境
mkdir namespaces/10
cd namespaces/10
echo -n /dev/nvme0n1 > device_path      # 后端块设备
echo 1 > enable
mkdir /sys/kernel/config/nvmet/ports/1
cd /sys/kernel/config/nvmet/ports/1
echo -n 172.31.0.202 > addr_traddr      # 本地监听地址
echo rdma > addr_trtype
echo 4420 > addr_trsvcid
echo ipv4 > addr_adrfam
ln -s /sys/kernel/config/nvmet/subsystems/<nqn> /sys/kernel/config/nvmet/ports/1/subsystems/<nqn>

验收方式官方也给了一条:dmesg | grep "enabling port",应能看到类似 nvmet_rdma: enabling port 1 (172.31.0.202:4420) 的记录。这句内核日志是"导出成功"最直接证据,比在 host 侧反复试连更快。

配置的持久化:SUSE 文档给出 nvmetcli saveconfig nvme-target-backup.json 保存、restore 恢复。configfs 是内存态,重启即失;用 JSON 存档是必须做的一步。

6. 三条 configfs 属性约束(踩了就白折腾) ​

内核 ABI 稳定接口文档把属性语义写得很细,其中三条直接影响操作顺序:

  1. 端口属性必须在端口 disabled 状态下修改。addr_traddr、addr_trsvcid、addr_trtype、addr_adrfam、addr_tsas、param_max_queue_size、param_mdts、param_inline_data_size 全部要求先禁用端口——先改再启用,而不是边跑边改。
  2. attr_qid_max 的取值范围是 1 到 128,且改动会强制所有已连接控制器重连。这意味着调整队列上限是一个"掉线级"操作,不能放在训练高峰做。
  3. attr_allow_any_host=1 与 allowed_hosts/ 里的显式主机白名单互斥:只要链接了显式 host,就不能再设 1。要么全开(仅测试),要么逐个 hostnqn 放行。

另外两个属性值域值得记住:

  • addr_adrfam 接受 pcie、ipv4、ipv6、ib、fc、pci、loop——注意 ib 与 ipv4 是两种不同的地址族,用 IB 地址时不要填 ipv4。
  • addr_tsas 对 RDMA 传输显示的是 QP 类型:connected 或 datagram;对 TCP 传输则是 none 或 tls1.3。QP 类型不同,多路径与重连行为都不同,改之前先确认对端 target 的实现口径。

param_max_queue_size、param_mdts、param_inline_data_size 的默认值都是 -1,含义是"交给传输层自己选"。看到 -1 不要以为是异常值。

7. 队列数不是随便填的:上限在 target 的 CPU 数 ​

这是高并发读取跑不满带宽时最常见的根因。内核文档在讲 NVMe target 时明确写了两条约束:

  • NVMe target 核心代码把最大 IO 队列数限制在在线 CPU 数;
  • 队列对总数上限还受中断资源(MSI/MSI-X 向量)等硬件条件约束。

于是这笔账可以直接算:如果 target 节点 nproc 是 32,那么它对外的 IO 队列上限就是 32。host 侧即便 -i 64,也拿不到 64 条 IO 队列——多出来的部分要么被拒,要么退化。

实操口径:

  1. 先看 target 的 nproc,把它当成 host 侧 -i 的硬上限;
  2. 结合负载形态分配:读密集抬 -i,写密集再补 -W,延迟敏感补 -P(轮询队列占核,别在 CPU 紧张的节点开);
  3. 单队列深度不足时调 -Q,但注意这也是 target 侧 param_max_queue_size 允许范围内的协商结果。

换句话:host 侧的队列参数是"申请",target 侧的 CPU 数与端口参数是"批复"。带宽上不去时,两边都要看,只调 host 一侧往往白调。

8. 多路径:默认就开着,别用错工具看 ​

两块官方文档给出同一个结论:

  • NVMe 原生多路径默认启用;若控制器标识里设置了 CMIC 选项,NVMe 栈会默认把该盘识别为多路径设备;
  • multipath -ll(DM 多路径)在 NVMe/RDMA 与 FC 上不受支持,NEVER 支持 NVMe/TCP;要用它看 NVMe 设备得先打开 enable_foreign;
  • 关闭原生多路径的开关是启动参数 nvme-core.multipath=N。

查看路径布局的正确命令是 nvme list-subsys。而判断"哪条路坏了"的正确落点是 sysfs 的 path_state,内核文档给出的四个取值与含义:

path_state含义
enabled该路径可用于 IO
ctrl-down控制器不存活,路径被禁用
ana-pending有 ANA 状态变更待处理
ns-not-ready命名空间未就绪

再往下还有三类诊断计数器(需开启 CONFIG_NVME_MULTIPATH),这是判断"到底丢了多少 IO"的唯一硬证据:

  • /sys/block/nvmeXcYnZ/diag/multipath_failover_count:路径切换次数;
  • /sys/block/nvmeXnY/diag/io_requeue_no_usable_path_count:无可用路径时 IO 被重新排队的次数;
  • /sys/block/nvmeXnY/diag/io_fail_no_available_path_count:无可用路径导致 IO 直接失败的次数。

这三个数如果都在涨,说明问题不在应用,而在路径层;如果只有第三个涨,说明切换都来不及,直接失败了。

路径选择策略(iopolicy)也影响观测:文档里出现的 numa 与 queue-depth 两种策略下,numa_nodes 与 queue_depth 这两个 sysfs 文件才有意义(queue_depth 在非 queue-depth 策略下返回空)。

9. 链路校验:两个 digest 与一个地址族 ​

三个容易忽略但关键时刻救命的开关:

  • -g/--hdr-digest:开启头部校验和;
  • -G/--data-digest:开启数据校验和;
  • addr_adrfam:确认地址族与链路一致(IP 走 ipv4/ipv6,IB 地址走 ib)。

digest 的代价是 CPU 与带宽开销,收益是把"静默损坏"从"数据悄悄错了"变成"链路层报错重传"。对 checkpoint 这类"错了就白训"的写入,建议开启;对纯读的临时数据可以评估后再定。本站另有一篇讲存储侧端到端校验的 数据完整性实战,两处配合才闭环。

10. 六步验收顺序(按这个顺序查,别跳) ​

接完一台机器,按下面顺序逐条验收,任何一步不过都不要往下走:

bash
# 1) 发现:能否看到目标的子系统
nvme discover -t rdma -a <target_ip> -s 4420

# 2) 连接:是否出现控制器
nvme connect -t rdma -a <target_ip> -s 4420 -n <nqn>
nvme list

# 3) 多路径布局:路径数、ANA 状态
nvme list-subsys

# 4) 路径健康:四值 path_state
cat /sys/block/nvme*n*/path_state

# 5) target 侧导出证据
dmesg | grep "enabling port"

# 6) 计数器基线:接完就取一次,方便后面判断"是否在涨"
for f in /sys/block/nvme*/diag/*count; do echo "$f: $(cat $f 2>/dev/null)"; done

第 6 步常被跳过,但它决定了后面能不能做因果判断:没有基线,你无法区分"这些失败计数是历史遗留"还是"刚发生的"。

11. 六个坑与一句总结 ​

现象根因处置
断链后文件系统变只读ctrl-loss-tmo 默认 600 秒到期,路径被移除连接时设 --ctrl-loss-tmo=-1
昨天能连今天被拒hostnqn 变了(/etc/nvme/hostnqn 丢失或重装)比对两端 hostnqn,必要时 -q 指定
改端口属性报错端口未 disabled 就修改先禁用端口,改完再启用
调队列上限后训练掉线attr_qid_max 变更强制所有控制器重连变更放在维护窗口
高并发读取带宽只到一半target 侧 IO 队列上限 = 在线 CPU 数host -i 不超过 target nproc,必要时扩 target
multipath -ll 看不到 NVMe 盘DM 多路径不支持 NVMe/RDMA 与 TCP用 nvme list-subsys + path_state

一句话总结:NVMe-oF 的难点不是"接上",而是接上之后四件事——把 ctrl-loss-tmo 从 10 分钟改成无限重试、把队列数按 target 的 CPU 数批复、用 path_state 与三个计数器判断路径层、把 digest 与地址族对齐链路。这四件事做完,远端 NVMe 才真的像本地盘。

相关文章 ​

相关文章 ​

AI-HPC 智算超算专家 · Contact: openaihpc@gmail.com