> For the complete documentation index, see [llms.txt](https://documentation.alluxio.io/ee-ai-cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.alluxio.io/ee-ai-cn/performance/rdma-networking.md).

# 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 或更高版本，且所有 Worker 和 Client 节点的 UCX 版本必须保持一致**
* 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`