> 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/ufs/hdfs.md).

# HDFS

本指南介绍了将 [HDFS](https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-hdfs/HdfsDesign.html) 配置为 Alluxio 的底层存储系统的说明。 HDFS，即 Hadoop 分布式文件系统，是 Hadoop 应用程序使用的主要分布式存储，为 Hadoop 生态系统中的大数据处理提供可靠且可扩展的存储。 有关 HDFS 的更多信息，请阅读其[文档](https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-hdfs/HdfsUserGuide.html)。

## 先决条件

在开始之前，请确保您已具备下列所需信息：

在使用 HDFS 和 Alluxio 之前：

| `<HDFS_NAMENODE>`  | 处理到集群的客户端连接的 NameNode 的 IP 地址。NameNode 是 Apache Hadoop HDFS 体系结构中的主节点，负责维护和管理 DataNode（从节点）上存在的块。 |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| `<HDFS_PORT>`      | NameNode 接受客户端连接的端口。                                                                              |
| `<HADOOP_VERSION>` | Hadoop 的版本                                                                                        |

## 基本设置

使用[挂载表示例](/ee-ai-cn/ufs.md) 添加新的挂载点，指定创建挂载的 Alluxio 路径和作为 UFS URI 的 HDFS 地址。 凭据和配置选项也可以作为挂载操作的一部分指定，如[配置挂载点](/ee-ai-cn/ufs.md)中所述。

{% tabs %}
{% tab title="Kubernetes (Operator)" %}
使用 operator 创建挂载点的 `ufs.yaml` 示例：

```yaml
apiVersion: k8s-operator.alluxio.com/v1
kind: UnderFileSystem
metadata:
  name: alluxio-hdfs
  namespace: alx-ns
spec:
  alluxioCluster: alluxio-cluster
  path: hdfs://<HDFS_NAMENODE>:<HDFS_PORT>
  mountPath: /hdfs
  mountOptions:
    alluxio.underfs.version: <HADOOP_VERSION>
```

{% endtab %}

{% tab title="Docker / 裸机" %}
如果不使用 operator，将 `hdfs://<HDFS_NAMENODE>:<HDFS_PORT>` 挂载到 `/hdfs` 的示例命令：

```shell
bin/alluxio mount add --path /hdfs/ --ufs-uri hdfs://<HDFS_NAMENODE>:<HDFS_PORT> \
  --option alluxio.underfs.version=<HADOOP_VERSION>
```

{% endtab %}
{% endtabs %}

如果您在本地运行 HDFS namenode 并使用默认端口并将 HDFS 根目录映射到 Alluxio，则 UFS URI 可以是 `hdfs://localhost:8020`， 如果仅将 HDFS 目录 `/alluxio/data` 映射到 Alluxio，则为 `hdfs://localhost:8020/alluxio/data`。 要找出 HDFS 正在运行的位置，请使用 `hdfs getconf -confKey fs.defaultFS` 获取 HDFS 正在侦听的默认主机名和端口。

此外，您应将属性 `alluxio.underfs.version` 指定为您的 HDFS 版本。 请参阅[使用特定版本挂载 HDFS](#shi-yong-te-ding-ban-ben-gua-zai-hdfs)。

## 高级设置

请注意，配置选项可以指定为挂载选项或 `conf/alluxio-site.properties` 中的配置属性。 以下部分将介绍如何将配置设置为属性，但它们也可以通过 `--option <key>=<value>` 设置为挂载选项。

### 指定 HDFS 配置位置

当 HDFS 具有非默认配置时，您需要配置 Alluxio 服务器以使用正确的配置文件访问 HDFS。 请注意，一旦设置了此项，使用 Alluxio 客户端的应用程序就不需要任何特殊配置。

有两种可能的方法：

* 将 `hdfs-site.xml` 和 `core-site.xml` 从您的 Hadoop 安装复制或创建符号链接到 `${ALLUXIO_HOME}/conf`。 确保在所有运行 Alluxio 的服务器上都进行了此设置。
* 或者，您可以在 `conf/alluxio-site.properties` 中将属性 `alluxio.underfs.hdfs.configuration` 设置为指向您的 `hdfs-site.xml` 和 `core-site.xml`。 确保在所有运行 Alluxio 的服务器上都配置了此配置。

```properties
alluxio.underfs.hdfs.configuration=/path/to/hdfs/conf/core-site.xml:/path/to/hdfs/conf/hdfs-site.xml
```

### HDFS Namenode HA 模式

要将 Alluxio 配置为与 HA 模式下的 HDFS namenode 一起使用，请首先配置 Alluxio 服务器以[使用正确的配置文件访问 HDFS](#zhi-ding-hdfs-pei-zhi-wei-zhi)。

此外，将底层存储地址设置为 `hdfs://nameservice/`（`nameservice` 是 已在 `hdfs-site.xml` 中配置的 [HDFS 名称服务](https://hadoop.apache.org/docs/r3.3.1/hadoop-project-dist/hadoop-hdfs/HDFSHighAvailabilityWithQJM.html#Configuration_details)）。 要将 HDFS 子目录挂载到 Alluxio 而不是整个 HDFS 命名空间，请将底层存储地址更改为类似 `hdfs://nameservice/alluxio/data` 的内容。

```shell
bin/alluxio mount add --path /hdfs/ --ufs-uri hdfs://nameservice/
```

### 用户/权限映射

为确保 HDFS 中文件/目录的权限信息（包括用户、组和模式）与 Alluxio 一致 （例如，由用户 Foo 在 Alluxio 中创建的文件在持久化到 HDFS 时也以用户 Foo 为所有者）， 启动 Alluxio Coordinator和 worker 进程的用户必须是：

1. [HDFS 超级用户](http://hadoop.apache.org/docs/r3.3.1/hadoop-project-dist/hadoop-hdfs/HdfsPermissionsGuide.html#The_Super-User) 即，使用启动 HDFS namenode 进程的同一用户也启动 Alluxio Coordinator和 worker 进程。
2. [HDFS 超级用户组](http://hadoop.apache.org/docs/r3.3.1/hadoop-project-dist/hadoop-hdfs/HdfsPermissionsGuide.html#Configuration_Parameters)的成员。 编辑 HDFS 配置文件 `hdfs-site.xml` 并检查配置属性 `dfs.permissions.superusergroup` 的值。 如果此属性设置为一个组（例如，“hdfs”），则将启动 Alluxio 进程的用户（例如，“alluxio”）添加到此组（“hdfs”）； 如果未设置此属性，则向此属性添加一个组，其中您的 Alluxio 运行用户是此新添加组的成员。

上面设置的用户只是启动 Alluxio Coordinator和 worker 进程的身份。 一旦 Alluxio 服务器启动，**不必**使用此用户运行您的 Alluxio 客户端应用程序。

### 连接到安全的 HDFS

如果您的 HDFS 集群已启用 Kerberos，请首先配置 Alluxio 服务器以[使用正确的配置文件访问 HDFS](#zhi-ding-hdfs-pei-zhi-wei-zhi)。

此外，需要安全配置才能使 Alluxio 与 HDFS 集群通信。 在 `alluxio-site.properties` 中设置以下 Alluxio 属性：

```properties
alluxio.security.kerberos.server.keytab.file=<YOUR_HDFS_KEYTAB_FILE_PATH>
alluxio.security.kerberos.server.principal=hdfs/<_HOST>@<REALM>
alluxio.security.kerberos.client.keytab.file=<YOUR_HDFS_KEYTAB_FILE_PATH>
alluxio.security.kerberos.client.principal=hdfs/<_HOST>@<REALM>
```

如果连接到安全的 HDFS，请在所有 Alluxio 节点上运行 `kinit`。 使用主体 `hdfs` 和您之前在 `alluxio-site.properties` 中配置的 keytab。 一个已知的限制是 Kerberos TGT 可能会在最大续订生命周期后过期。 您可以通过定期续订 TGT 来解决此问题。 否则，在启动 Alluxio 服务时，您可能会看到 `No valid credentials provided (Mechanism level: Failed to find any Kerberos tgt)`。 另一个选项是设置 `alluxio.hadoop.kerberos.keytab.login.autorenewal=true`，以便自动刷新 TGT。

用户还可以使用 `alluxio.hadoop.security.krb5.conf` 指定 `krb5.conf` 文件位置 并使用 `alluxio.hadoop.security.authentication` 指定身份验证方法。

#### 自定义 Kerberos 领域/KDC

默认情况下，Alluxio 将使用机器级 Kerberos 配置来确定 Kerberos 领域 和 KDC。您可以通过设置 JVM 属性 `java.security.krb5.realm` 和 `java.security.krb5.kdc` 来覆盖这些默认值。

要设置这些，请在 `conf/alluxio-env.sh` 中设置 `ALLUXIO_JAVA_OPTS`。

```sh
ALLUXIO_JAVA_OPTS+=" -Djava.security.krb5.realm=<YOUR_KERBEROS_REALM> -Djava.security.krb5.kdc=<YOUR_KERBEROS_KDC_ADDRESS>"
```

### 使用特定版本挂载 HDFS

用户有多种方法可以将具有指定版本的 HDFS 集群作为底层存储挂载到 Alluxio 命名空间中。 在使用特定版本的 HDFS 挂载之前，请确保您已使用该特定版本的 HDFS 构建了客户端。 您可以通过转到 Alluxio 目录下的 `lib` 目录来检查此客户端是否存在。

#### 使用站点属性

当使用特定 HDFS 版本挂载 Alluxio 根目录的底层存储时，可以在站点属性文件 (`conf/alluxio-site.properties`) 中添加以下行

```properties
alluxio.underfs.version=3.3
```

#### 支持的 HDFS 版本

Alluxio 支持以下 HDFS 版本作为挂载选项 `alluxio.underfs.version` 的有效参数：

* Apache Hadoop：2.10、3.3

如果所需版本不可用，请通过 `sales@alluxio.com` 联系您的 Alluxio 客户代表。

### 使用 Hadoop 本机库

Hadoop 附带一个本机库，与 Java 实现相比，它提供更好的性能和附加功能。 例如，当使用本机库时，HDFS 客户端可以使用本机校验和函数，这比默认的 Java 实现更有效。 要将 Hadoop 本机库与 Alluxio HDFS 底层文件系统一起使用，请首先按照 [此页面](https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/NativeLibraries.html)上的说明在 Alluxio 节点上安装本机库。 在机器上安装 hadoop 本机库后，通过添加以下行来更新 `conf/alluxio-env.sh` 中的 Alluxio 启动 Java 参数：

```sh
ALLUXIO_JAVA_OPTS+=" -Djava.library.path=<local_path_containing_hadoop_native_library> "
```

确保重新启动 Alluxio 服务以使更改生效。

### \[实验性] HDFS 回收站支持

HDFS 默认支持回收站功能。当删除 HDFS 文件时，它将被移动到回收站目录，稍后才被实际删除。 用户可以通过设置 `alluxio.underfs.hdfs.trash.enabled=true` 来启用 HDFS 回收站功能。

如果启用了该功能，当用户通过 Alluxio 删除存储在 HDFS 中的文件时， Alluxio 将尝试将其移动到 HDFS 回收站目录，而不是直接从 HDFS 中删除它。 请注意，必须在 `core-site.xml` 中配置 HDFS 以启用回收站功能。 如果 HDFS 中未启用回收站功能，Alluxio 将直接删除文件，而不管此配置如何。