# RDMA 网络

Alluxio 支持多种 AI 和 HPC 集群中常见的高速网络技术。本页介绍各支持选项的配置方法和性能参考。

| 技术                            | 状态    | 适用场景                                     |
| ----------------------------- | ----- | ---------------------------------------- |
| 基于 InfiniBand 或 RoCE 的原生 RDMA | ✅ 已支持 | 零拷贝数据传输，完全绕过内核网络栈                        |
| IPoIB（IP over InfiniBand）     | ✅ 已支持 | 在 IB 硬件上运行标准 TCP/IP                      |
| AWS EFA                       | 不支持   | 如需使用原生 RDMA，请使用受支持的 InfiniBand 或 RoCE 环境 |
| iWARP                         | 不支持   | 如需使用原生 RDMA，请使用受支持的 InfiniBand 或 RoCE 环境 |

## 原生 RDMA

> **注意：** 该功能自 AI-3.9-16.0.0 起为实验性特性。

### 概述

原生 RDMA 绕过内核网络栈，在 Alluxio Worker 与客户端之间实现零拷贝数据传输。相比 [IPoIB](#ipoib)（在 InfiniBand 硬件上承载 TCP/IP），可显著降低缓存读取延迟并提升吞吐。

**适用范围**

* 仅支持读 I/O；写路径继续使用 TCP。
* 仅支持 InfiniBand 与 RoCE；不支持 AWS EFA 与 iWARP。

**推荐场景**

* Worker 与客户端通过 InfiniBand 或 RoCE 互联的集群
* 延迟敏感型负载（如模型加载、推理服务）
* 需最大化 Alluxio 缓存读取吞吐的场景

### 前提条件

#### 硬件

* 支持 InfiniBand 或 RoCE 的网卡（如 Mellanox/NVIDIA ConnectX-4 或更高版本）
* InfiniBand 交换机网络或支持 RoCE 的以太网交换机
* RDMA 网卡必须安装在数据路径上的**所有 Worker 节点**和**所有客户端/FUSE 节点**上
* 原生 RDMA 不支持 AWS EFA 和 iWARP 网卡

#### 软件

* 已加载 RDMA 内核模块的 Linux 操作系统（内核 5.0 或更高版本推荐）
* MLNX OFED ≥ 25.10（或 DOCA-OFED）或上游 `rdma-core` ≥ 35
* 所有节点安装 OpenUCX 1.20 或更高版本
* JUCX（UCX 的 Java 绑定）—— 已随 Alluxio 捆绑

#### 环境验证

在启用 Alluxio 原生 RDMA 之前，请验证 RDMA 环境是否正确配置。

**验证 RDMA 设备和端口状态**

```shell
ibv_devinfo
```

预期输出（关键字段）：

```console
hca_id: mlx5_0
     port:  1
        state:         PORT_ACTIVE (4)
        link_layer:    InfiniBand
        rate:          200 Gb/sec
```

验证：

* `state` 为 `PORT_ACTIVE`
* `link_layer` 为 `InfiniBand`（原生 IB）或 `Ethernet`（IB 网卡配置为以太网模式，使用 RoCE 协议）

如果 `ibv_devinfo` 未找到，请安装 `rdma-core` 或 MLNX\_OFED 驱动。

**安装和验证 UCX**

Alluxio 使用 OpenUCX 实现原生 RDMA 传输。需在所有 Worker 和客户端节点上安装 UCX 1.20 或更高版本。

通过包管理器安装（Ubuntu/Debian）：

```shell
sudo apt-get install -y libucx-dev ucx-utils
```

通过包管理器安装（RHEL/CentOS）：

```shell
sudo yum install -y ucx ucx-devel
```

或者从源码编译以获取最新版本：

```shell
# 安装编译前置依赖
sudo apt-get install -y libibverbs-dev librdmacm-dev libnuma-dev
```

```shell
wget https://github.com/openucx/ucx/releases/download/v1.20.0/ucx-1.20.0.tar.gz
tar xzf ucx-1.20.0.tar.gz
cd ucx-1.20.0
./contrib/configure-release --prefix=/usr/local --with-verbs --with-rdmacm
make -j$(nproc)
sudo make install
sudo ldconfig
```

编译参数说明：

| 参数              | 用途                                  |
| --------------- | ----------------------------------- |
| `--with-verbs`  | 启用 InfiniBand Verbs 传输（RDMA 数据传输必需） |
| `--with-rdmacm` | 启用 RDMA Connection Manager（连接建立必需）  |

验证安装：

```shell
ucx_info -v
```

预期输出：UCX 版本 1.20 或更高。

验证 RDMA 传输是否可用：

```shell
ucx_info -d | grep -E "rc_verbs|rc_mlx5|rdmacm"
```

预期输出：列出一个或多个传输设备。如果无任何输出，说明 UCX 编译时未找到 RDMA 开发库——重新安装 `libibverbs-dev` 和 `librdmacm-dev`，然后重新编译 UCX。

更多安装选项请参考 [OpenUCX 文档](https://openucx.readthedocs.io/en/master/running.html#ucx-build-and-install)。

**验证 bRPC 环境（推荐）**

bRPC 提供 RDMA 加速的元数据 RPC，推荐在 RDMA 环境中启用以获得最佳性能。请验证 bRPC 原生库是否可用：

```shell
ls /usr/lib/libbrpc* /usr/local/lib/libbrpc* 2>/dev/null
```

预期输出：一个或多个 `libbrpc*.so` 文件。如果未找到，需单独安装 bRPC 原生库。原生 RDMA 数据传输（UCX）不依赖 bRPC，但元数据 RPC 会回退到 gRPC over TCP。

### 快速开始

本章节提供启用原生 RDMA 的最小步骤。高级调优请参考[配置](#配置)章节。

在**所有 Worker 和客户端节点**的 `alluxio-site.properties` 中添加：

```properties
# 启用 RDMA 数据传输（UCX），同时对 Worker 和客户端生效
alluxio.network.rdma.data.enabled=true

# 启用 RDMA 加速的元数据 RPC（bRPC）—— 推荐
alluxio.network.rdma.metadata.enabled=true
```

重启所有 Worker 和客户端进程。验证 Worker RDMA 服务已启动：

```shell
grep -i "RdmaServer" /opt/alluxio/logs/worker.log | tail -5
```

> **重要**：当 `alluxio.network.rdma.data.enabled=true` 时，客户端将完全使用 RDMA 进行数据读取——不会自动回退到 TCP。如果 Worker 的 RDMA 端口不可达，读取操作将失败（如果存在多副本，会尝试其他 Worker）。

### 配置

#### 数据加速

| 属性                                      | 默认值       | 说明                                                                                                                                                                               |
| --------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alluxio.network.rdma.data.enabled`     | `false`   | 统一控制 Worker 和客户端的 RDMA 数据传输                                                                                                                                                      |
| `alluxio.network.rdma.data.bind.device` | （未设置）     | 用于**数据平面**的 RDMA Verbs 设备名（如 `mlx5_0:1`）。通过 `ibv_devinfo` 获取（格式：`设备名:端口号`）。支持逗号分隔的多设备配置（如 `mlx5_0:1,mlx5_1:1`）。如果只配置单个设备，Alluxio 会自动从该网卡解析 RDMA 监听地址。未设置时，UCX 自动选择所有可用的 RDMA 设备。 |
| `alluxio.network.rdma.data.bind.host`   | `0.0.0.0` | Worker RDMA 数据服务的监听地址。主要用于不希望从 `alluxio.network.rdma.data.bind.device` 自动推导绑定地址，或配置了多个 RDMA 设备的场景。                                                                               |
| `alluxio.network.rdma.data.hostname`    | （未设置）     | 客户端连接 Worker RDMA 数据服务时使用的主机名或 IP。未设置时使用 Worker 的通用主机名。                                                                                                                          |
| `alluxio.network.rdma.data.port`        | `59999`   | Worker RDMA 数据服务端口。                                                                                                                                                              |

> 大多数单网卡部署中，默认配置无需额外设置地址即可工作。对于多网卡环境，请将 `alluxio.network.rdma.data.hostname` 设为客户端可达的 IP，使用 `alluxio.network.rdma.data.bind.device` 固定 RDMA 网卡；如果不希望从单个 RDMA 设备自动推导监听地址，可额外设置 `alluxio.network.rdma.data.bind.host`。

#### 缓冲池

原生 RDMA 数据传输使用已注册内存缓冲池。当工作负载需要更高 RDMA 并发、更大的预取容量，或需要降低首次读取延迟时，可以调优以下配置。

| 属性                                                   | 默认值     | 说明                                                                                                    |
| ---------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `alluxio.network.rdma.data.buffer.pool.initial.size` | `256MB` | RDMA 注册缓冲池在启动时的初始大小预算。                                                                                |
| `alluxio.network.rdma.data.buffer.pool.prewarm.size` | `256MB` | 启动时在 4MB chunk bucket 中预热的 RDMA 注册缓冲池内存量。该值不能超过 `alluxio.network.rdma.data.buffer.pool.initial.size`。 |
| `alluxio.network.rdma.data.buffer.pool.max.size`     | `8GB`   | RDMA 注册缓冲池的最大大小。缓冲池不会超过该限制继续扩容，缓冲池满时 RDMA 预取会停止。                                                      |

#### RDMA 预取器

RDMA 预取器复用 legacy async prefetcher 的配置项。这些属性与标准客户端异步预取器具有相同的顺序读取语义，但 RDMA 使用它们来控制 RDMA chunk 预取，而不是基于 TCP 的异步预取读取。

关于通用异步预取行为，请参考[文件读取](https://documentation.alluxio.io/ee-ai-cn/performance/pages/adxFGOId5YtwslRC8EE9#为顺序读取调整客户端预取)。

以下属性是推荐的 RDMA 预取器调优项。除非 Alluxio 支持团队建议，否则不推荐自定义其他继承自 async prefetcher 的属性。

| 属性                                                                            | 默认值 | RDMA 行为                                                         |
| ----------------------------------------------------------------------------- | --- | --------------------------------------------------------------- |
| `alluxio.user.position.reader.streaming.async.prefetch.max.part.number`       | `8` | 单个 stream 最多向前预取的 RDMA chunk 数。该属性与 legacy async prefetcher 共享。 |
| `alluxio.user.position.reader.streaming.async.prefetch.file.length.threshold` | `0` | 如果文件长度小于或等于该值，RDMA 预取器会尝试立即预取整个文件。小于或等于 `0` 表示禁用该小文件行为。         |

推荐调优：

* 对于大文件读取，如果客户端和 Worker 内存资源充足，建议设置 `alluxio.user.position.reader.streaming.async.prefetch.max.part.number=16`，并相应增大 `alluxio.network.rdma.data.buffer.pool.max.size=16GB`。
* 对于通过 FUSE 读取小文件，建议启用 `alluxio.fuse.open.read.status.cache.enabled=true`，以减少重复只读打开文件时的 metadata RPC；同时将 `alluxio.user.position.reader.streaming.async.prefetch.file.length.threshold` 设置为希望 RDMA 立即预取的最大小文件大小。

#### 元数据加速

| 属性                                        | 默认值     | 说明                                                                  |
| ----------------------------------------- | ------- | ------------------------------------------------------------------- |
| `alluxio.network.rdma.metadata.enabled`   | `false` | 启用实验性的 Worker RDMA 元数据访问路径。关闭时，Worker 不会启动元数据传输服务，客户端继续使用原有 RPC 路径。 |
| `alluxio.network.rdma.metadata.port`      | `29995` | Worker RDMA 元数据服务端口。                                                |
| `alluxio.network.rdma.metadata.device`    | （未设置）   | 元数据服务使用的 RDMA 设备。未设置时，元数据传输选择默认的活动设备。                               |
| `alluxio.network.rdma.metadata.ib.port`   | `1`     | 元数据服务使用的 InfiniBand 端口。                                             |
| `alluxio.network.rdma.metadata.gid.index` | `-1`    | 元数据服务使用的 GID index。负值表示由元数据传输选择默认 GID。                              |

> Worker RDMA 元数据服务在地址层面仍复用 Worker 的 host/bind host。`alluxio.network.rdma.metadata.port` 控制服务端口，而 `alluxio.network.rdma.metadata.*` 用于指定原生元数据传输所使用的 RDMA 设备、端口和 GID。

#### 诊断

| 属性                                                  | 默认值     | 说明                         |
| --------------------------------------------------- | ------- | -------------------------- |
| `alluxio.network.rdma.data.trace.enabled`           | `false` | 启用日志中的 RDMA 数据传输详细逐操作跟踪统计。 |
| `alluxio.network.rdma.data.trace.print.interval.ms` | `20s`   | 启用跟踪时，打印 RDMA 数据传输跟踪统计的间隔。 |

### 基准测试

Alluxio 提供 RDMA 基准测试 CLI 命令，用于在运行生产工作负载之前验证 RDMA 连接和测量原始性能。

**命令帮助**

```shell
alluxio exec rdmaBenchmark --help
```

可用参数：

| 参数              | 默认值     | 说明                                                                 |
| --------------- | ------- | ------------------------------------------------------------------ |
| `--mode`        | （自动推断）  | 测试模式：`server` 或 `client`（根据 `--remote-ip` 自动推断）                    |
| `--local-ip`    | （自动检测）  | 本地 IP 地址                                                           |
| `--local-port`  | `20600` | 本地端口                                                               |
| `--delay-us`    | `0`     | 模拟服务端处理延迟（微秒）                                                      |
| `--remote-ip`   | -       | 远端 IP 地址（仅客户端模式，必填）                                                |
| `--remote-port` | `20600` | 远端端口（仅客户端模式）                                                       |
| `--case`        | `all`   | 测试用例：`basic`、`latency`、`stress`、`stress-write`、`stress-read`、`all` |
| `--duration`    | `10`    | 压测时长（秒）                                                            |
| `--numjobs`     | `-1`    | 并发线程数（-1 表示根据负载大小自动调整）                                             |
| `--iodepth`     | `-1`    | 单线程最大 In-Flight 请求数（-1 表示根据负载大小自动调整）                               |

**启动服务端**

在一个节点上启动基准测试服务端：

```shell
cd /opt/alluxio
./bin/alluxio exec rdmaBenchmark
```

输出示例：

```console
[INFO] RDMA Server running on 10.0.1.10:20600 with Delay 0 us. Press Ctrl+C to exit.
```

**运行延迟测试**

在另一个 RDMA 连通的节点上启动客户端并运行延迟测试：

```shell
cd /opt/alluxio
./bin/alluxio exec rdmaBenchmark --remote-ip 10.0.1.10 --case latency --duration 10
```

输出示例：

```console
===============================================================
               RDMA ZERO-COPY BENCHMARK SUITE
===============================================================
[INFO] Test started at: 2026-04-14 08:16:02
[INFO] Connecting to 10.0.1.10:20600...

[INFO] Test Case: latency
[INFO] Duration: 10 seconds

--- LATENCY TESTS (Sequential, Zero-Copy) ---
[LATENCY - WRITE] Payload: 4096    Bytes | Iterations: 5000
  -> Min:     1.2 us | Avg:     1.8 us | P50:     1.7 us | P99:     3.5 us | P99.9:    4.8 us | Max:     6.2 us
[LATENCY - READ ] Payload: 4096    Bytes | Iterations: 5000
  -> Min:     0.8 us | Avg:     1.3 us | P50:     1.2 us | P99:     2.8 us | P99.9:    3.5 us | Max:     4.5 us

[LATENCY - WRITE] Payload: 65536   Bytes | Iterations: 5000
  -> Min:     1.8 us | Avg:     2.5 us | P50:     2.3 us | P99:     5.2 us | P99.9:    7.5 us | Max:     9.8 us
[LATENCY - READ ] Payload: 65536   Bytes | Iterations: 5000
  -> Min:     1.5 us | Avg:     2.2 us | P50:     2.0 us | P99:     4.8 us | P99.9:    6.5 us | Max:     8.2 us

[LATENCY - WRITE] Payload: 1048576 Bytes | Iterations: 5000
  -> Min:     4.5 us | Avg:     7.2 us | P50:     6.8 us | P99:    18.5 us | P99.9:   24.2 us | Max:    28.5 us
[LATENCY - READ ] Payload: 1048576 Bytes | Iterations: 5000
  -> Min:     4.8 us | Avg:     7.8 us | P50:     7.5 us | P99:    20.5 us | P99.9:   26.8 us | Max:    32.5 us

===============================================================
                   ALL TESTS COMPLETED
===============================================================
```

**运行压力读取测试**

指定并发参数运行压力读取测试：

```shell
cd /opt/alluxio
./bin/alluxio exec rdmaBenchmark --remote-ip 10.0.1.10 --case stress-read \
  --duration 10 --numjobs 8 --iodepth 32
```

输出示例：

```console
===============================================================
               RDMA ZERO-COPY BENCHMARK SUITE
===============================================================
[INFO] Test started at: 2026-04-14 08:19:13
[INFO] Connecting to 10.0.1.10:20600...

[INFO] Test Case: stress-read
[INFO] Duration: 10 seconds

--- BANDWIDTH STRESS TESTS (Multi-Threaded Concurrent, Zero-Copy) ---
[BANDWIDTH - READ ] Payload: 4096    Bytes | Duration: 10 sec
  -> Config: threads=8, inFlightPerThread=32
  -> [Live]  1280000 ops/s |   42.00 Gbps
  -> [Live]  1360000 ops/s |   44.59 Gbps
  -> [Live]  1420000 ops/s |   46.55 Gbps
  -> [Live]  1385000 ops/s |   45.41 Gbps
  -> [Live]  1445000 ops/s |   47.37 Gbps
  -> [Live]  1398000 ops/s |   45.84 Gbps
  -> [Live]  1472000 ops/s |   48.25 Gbps
  -> [Live]  1508000 ops/s |   49.43 Gbps
  -> [Live]  1536000 ops/s |   50.33 Gbps

[BANDWIDTH - READ ] Payload: 65536   Bytes | Duration: 10 sec
  -> Config: threads=8, inFlightPerThread=32
  -> [Live]   285440 ops/s |  149.68 Gbps
  -> [Live]   295680 ops/s |  155.04 Gbps
  -> [Live]   298240 ops/s |  156.39 Gbps
  -> [Live]   301312 ops/s |  158.00 Gbps
  -> [Live]   304128 ops/s |  159.47 Gbps
  -> [Live]   306560 ops/s |  160.75 Gbps
  -> [Live]   308480 ops/s |  161.75 Gbps
  -> [Live]   310144 ops/s |  162.63 Gbps
  -> [Live]   312064 ops/s |  163.64 Gbps
  -> [Live]   313600 ops/s |  164.45 Gbps

[BANDWIDTH - READ ] Payload: 1048576 Bytes | Duration: 10 sec
  -> Config: threads=8, inFlightPerThread=32
  -> [Live]    18880 ops/s |  158.46 Gbps
  -> [Live]    19264 ops/s |  161.68 Gbps
  -> [Live]    19456 ops/s |  163.29 Gbps
  -> [Live]    19584 ops/s |  164.37 Gbps
  -> [Live]    19648 ops/s |  164.91 Gbps
  -> [Live]    19712 ops/s |  165.45 Gbps
  -> [Live]    19776 ops/s |  165.98 Gbps
  -> [Live]    19840 ops/s |  166.52 Gbps
  -> [Live]    19904 ops/s |  167.05 Gbps

===============================================================
                   ALL TESTS COMPLETED
===============================================================
```

### 故障排查

**未发现 RDMA 设备**

```shell
ls /sys/class/infiniband/
```

如果目录为空：

* 确认网卡已物理安装：`lspci | grep -i mellanox`
* 确认 RDMA 内核模块已加载：`lsmod | grep ib_core`
* 安装或重新安装 MLNX\_OFED 驱动

**RDMA 设备端口未处于 ACTIVE 状态**

* 检查物理线缆连接
* 验证交换机配置
* 运行 `ibstat` 查看详细的适配器和端口状态

**UCX 初始化失败**

* 确认 UCX 已安装：`ucx_info -v`
* 检查 `UCX_NET_DEVICES` 是否设置为正确的设备（如 `mlx5_0:1`）
* 确保 `LD_LIBRARY_PATH` 包含 UCX 库路径

**RDMA 操作超时**

* 增大 `alluxio.network.rdma.data.operation.timeout.ms`（如设为 `60s`）
* 通过 `ibstat` 检查网络健康状况，确认端口状态为 ACTIVE
* 验证 Worker RDMA 端口可从客户端节点访问

**缓冲池耗尽**

* 如果分配失败频繁发生，增大 `alluxio.network.rdma.data.buffer.pool.max.size`
* 如果观察到首次读取延迟尖峰，增大 `alluxio.network.rdma.data.buffer.pool.initial.size`

**RDMA 端口在重启后被占用**

* RDMA 连接管理器端口在进程退出后可能保持占用状态最多 10 秒。服务端会以 1 秒间隔自动重试。
* 如果端口持续被占用，确认无其他进程使用该端口：

  ```shell
  ss -tlnp | grep 59999
  ```

**客户端 RDMA 读取失败**

* RDMA 不会回退到 TCP。请确保所有目标 Worker 已设置 `alluxio.network.rdma.data.enabled=true` 且 RDMA 端口可达。
* 查看客户端日志中的 RDMA 连接错误。

## IPoIB

### 概述

InfiniBand（IB）是 AI 训练集群中常见的高带宽、低延迟互联技术。Alluxio 支持 **IP over InfiniBand（IPoIB）**，即在 IB 硬件上运行标准 TCP/IP 协议栈。由于 Alluxio 通过标准 TCP/IP socket 通信，无需任何代码改动或特殊驱动——只需加载 IPoIB 内核模块并将 Alluxio 服务绑定到 IB 网络接口即可。

> **适用范围**：本节适用于配置为 **InfiniBand 链路层**的网卡（通过 `ibstat | grep "Link layer"` 确认）。如果您的 ConnectX 网卡运行在以太网链路层模式下，它作为标准高速以太网卡工作，Alluxio 可直接使用，无需任何 IPoIB 配置。

#### IPoIB 与原生 RDMA 的对比

|            | IPoIB               | 原生 RDMA        |
| ---------- | ------------------- | -------------- |
| 协议         | TCP/IP over IB 硬件   | 绕过内核，零拷贝直接内存访问 |
| Alluxio 支持 | ✅ 完全支持              | ✅ 完全支持         |
| 配置方式       | 绑定到 IB 网络接口         | 参见[配置](#配置)    |
| 典型吞吐量      | 100–400 Gbps（取决于硬件） | 延迟更低，峰值带宽相近    |

### 前提条件

#### 硬件

* Mellanox/NVIDIA ConnectX-4 或更高版本网卡
* InfiniBand 交换机网络

#### 软件

加载 IPoIB 内核模块，并确认 IB 驱动和接口已正常运行：

```shell
# 加载 IPoIB 内核模块
modprobe ib_ipoib

# 验证 OFED 驱动已加载且链路层为 InfiniBand
ibstat
# 预期输出：adapter state "Active"，link layer: InfiniBand

# 列出 IB 网络接口
ip addr show | grep -E "^[0-9]+: ib"
# 预期输出：一个或多个 ib* 接口（如 ib0、ibs22）

# 确认 IB 接口已分配 IP 地址
ip addr show ib0
# 预期输出：inet <IP>/prefix scope global ib0

# 验证 InfiniBand 设备可访问
ibv_devinfo
# 预期输出：hca_id，port_state: PORT_ACTIVE
```

#### MTU 配置

IPoIB 有两种传输模式，决定了最大支持的 MTU：

| 模式            | 最大 MTU    | 典型环境                      |
| ------------- | --------- | ------------------------- |
| Datagram（UD）  | 2,044 字节  | 云托管 IB（Azure HPC、AWS EFA） |
| Connected（RC） | 65,520 字节 | 本地 InfiniBand 网络          |

设置 MTU 前，先确认当前模式：

```shell
cat /sys/class/net/ib0/mode
ip link show ib0 | grep mtu
```

如果模式为 `datagram`（云端 IPoIB 常见），硬件限制为 2,044 字节。将 MTU 设置为 9000 会报 `RTNETLINK answers: Invalid argument`——这是预期行为，并非错误。Alluxio 在 MTU 2,044 下可正常运行。

如果模式为 `connected`（通常为本地部署），可将 MTU 设置为 9000 以获得最大吞吐量：

```shell
ip link set ib0 mtu 9000

# 验证
ip link show ib0 | grep mtu
# 预期输出：mtu 9000
```

如需在重启后保持 MTU 设置，请将配置写入系统网络配置文件（如 `/etc/network/interfaces` 或 systemd-networkd 配置单元）。

### 将 Alluxio 绑定到 IB 接口

Alluxio 的热数据通路在 **Worker** 和 **FUSE / 客户端节点**之间——这是 IB 带宽发挥作用的地方。Coordinator 负责后台任务（元数据操作、后台作业等），不在数据服务的关键路径上，因此无需运行在具备 IB 网卡的机器上。

通用的 NIC 绑定配置请参考[集群管理](/ee-ai-cn/administration/managing-alluxio.md)。以下步骤在通用配置基础上针对 IPoIB 场景做了扩展。

{% tabs %}
{% tab title="Kubernetes (Operator)" %}
对于具备 IB 硬件的 Kubernetes 集群，可通过以下方式将 IPoIB 暴露给 Pod：

* **NVIDIA Network Operator**：自动化部署 MLNX\_OFED 驱动和 SR-IOV Device Plugin
* **Multus CNI**：为 Alluxio Pod 挂载辅助 IB 网络接口
* **SR-IOV Device Plugin**：将 IB 虚拟功能（VF）作为 Pod 资源暴露

具体配置请参考 [NVIDIA Network Operator 文档](https://docs.nvidia.com/networking/display/cokan10/network+operator) 和 [Multus CNI](https://github.com/k8snetworkplumbingwg/multus-cni)。Pod 内 IB 接口可用后，参照裸机 tab 中的 `alluxio-site.properties` 配置即可。
{% endtab %}

{% tab title="Docker / 裸机" %}
**Worker 配置**

在每个 Worker 节点的 `alluxio-site.properties` 中添加以下配置。将 `ib0` 替换为实际的 IB 接口名称（通过 `ip addr show` 查询）：

```properties
# 将所有 Worker 服务绑定到 IB 网络接口
alluxio.worker.rpc.bind.device=ib0
alluxio.worker.data.bind.device=ib0
alluxio.worker.web.bind.device=ib0
alluxio.worker.rest.bind.device=ib0
```

启动 Worker 后进行验证：

```shell
# 确认 Worker RPC 端口正在监听 IB 接口的 IP 地址
ss -tlnp | grep 29999
# 预期输出：监听地址与 ib0 的 IP 地址一致
```

**FUSE / 客户端配置**

对于运行 Alluxio FUSE 或直接客户端访问的节点，将数据通道绑定到 IB 接口：

```properties
# 将客户端数据通道绑定到 IB 网络接口
alluxio.user.network.data.bind.device=ib0
```

FUSE 挂载选项和前提条件（包括 `allow_other` 配置）请参考 [POSIX API (FUSE)](/ee-ai-cn/data-access/fuse-based-posix-api.md)。

**Coordinator 配置**

Coordinator 无需运行在具备 IB 网卡的机器上。将 `alluxio.coordinator.hostname` 设置为 Coordinator 节点的可达 IP 地址（通常为其以太网接口）：

```properties
alluxio.coordinator.hostname=<coordinator IP>
```

**验证端到端连接**

启动所有服务后，确认 Worker–Client 数据流量通过 IB 接口传输：

```shell
# 检查 IB 接口 IP 上的活跃连接
ss -tnp | grep <IB 接口 IP>
# 预期输出：Worker 与 FUSE 客户端之间的 ESTABLISHED 连接

# 在读取数据时确认 IB 流量（观察 ib0 的 rx_bytes 递增）
cat /sys/class/net/ib0/statistics/rx_bytes
```

{% endtab %}
{% endtabs %}

### 参考性能

以下测试结果来自一个使用 IPoIB 的示例测试环境，Alluxio 运行在物理机上。

#### 测试环境

| 参数   | 值                                         |
| ---- | ----------------------------------------- |
| 网络   | 2 × 200 Gbps IPoIB（bonding），实测吞吐：360 Gbps |
| 网卡   | Mellanox ConnectX-7（IB 链路层，200 Gbps）      |
| 缓存磁盘 | RAID0，2 × NVMe，读/写：\~12 GB/s              |
| UFS  | 对象存储，100 Gbps 专线                          |
| 部署方式 | 物理机，FUSE 与 Worker 混部署                     |

#### 网络层吞吐（iperf3）

| 配置                          | 实测吞吐     |
| --------------------------- | -------- |
| 单 IB 端口                     | 180 Gb/s |
| Bonding（2 × 200 Gbps IPoIB） | 360 Gbps |

#### Alluxio 读取吞吐（热读，大文件，32 并发）

| 配置                                | 顺序读           |
| --------------------------------- | ------------- |
| 1 FUSE + 1 Worker，1 × NVMe        | 6.3 GB/s      |
| 1 FUSE + 1 Worker，RAID0 2 × NVMe  | 12.5 GB/s     |
| 3 FUSE + 3 Workers，RAID0 2 × NVMe | **36.6 GB/s** |

> **观察**：在 3 Worker + RAID0 NVMe 缓存的配置下，Alluxio 热读吞吐接近裸盘带宽上限（\~36 GB/s 实测 vs. \~36 GB/s RAID0 理论上限），表明在此规模下 IPoIB 网络不是性能瓶颈。

### 故障排查

**Worker 未绑定到 IB 接口**

* 运行 `ip addr show ib0` 确认接口已分配 IP 地址。
* 检查 `alluxio.worker.rpc.bind.device` 中的接口名是否与实际名称完全一致（区分大小写）。
* 查看 `alluxio-worker.log` 中的 `bind` 相关错误。

**Worker 通过以太网而非 IB 提供数据**

* 确认每个 Worker 节点上设置了 `alluxio.worker.data.bind.device=ib0`，且修改后已重启 Worker 进程。
* 确认 FUSE / 客户端节点上设置了 `alluxio.user.network.data.bind.device=ib0`。

**`ip link set ib0 mtu 9000` 报 `RTNETLINK answers: Invalid argument`**

* 您的 IPoIB 接口处于 datagram 模式，MTU 上限为 2,044 字节。这在云托管 InfiniBand（Azure HPC、AWS EFA）上很常见。Alluxio 在默认 MTU 下可正常运行，无需任何操作。参见 [MTU 配置](#mtu-配置)。

**IPoIB 吞吐偏低**

* 在节点间运行 `iperf3 -c <other node ib0 IP>` 建立网络层基准。
* 检查 `cat /sys/class/net/ib0/mode`——datagram 模式（MTU 2,044）与 connected 模式（MTU 9,000）相比峰值吞吐会受限。
* 确认所有服务均通过 IB 接口通信：`ss -tnp | grep <ib0 IP>`。

**重启后 IB 接口消失**

* MTU 和 bonding 配置可能未持久化，请将其写入系统网络配置文件。
* 验证 MLNX\_OFED 驱动是否随系统启动加载：`lsmod | grep ib_core`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.alluxio.io/ee-ai-cn/performance/rdma-networking.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.