---

前言

本文档旨在详细介绍 hdfs dfsadmin 的主要功能及其使用方法，帮助读者更好地掌握如何利用这一工具来管理和优化HDFS集群。我们将按照不同的类别组织命令，并提供详细的语法说明和实际应用示例，以便于读者快速查找所需信息并应用于实践当中。

---

一、hdfs分布式文件系统管理命令

1. 介绍

hdfs dfsadmin 是Hadoop分布式文件系统（HDFS）提供的一个管理工具，主要用于执行与HDFS集群管理和维护相关的各种操作。这些命令通常需要以HDFS超级用户的身份运行，因为它们涉及到对整个文件系统的控制和配置调整。

2. 语法及解释

Usage: hdfs dfsadmin
Note: Administrative commands can only be run as the HDFS superuser.
        [-report [-live] [-dead] [-decommissioning] [-enteringmaintenance] [-inmaintenance]]
        [-safemode <enter | leave | get | wait | forceExit>]
        [-saveNamespace [-beforeShutdown]]
        [-rollEdits]
        [-restoreFailedStorage true|false|check]
        [-refreshNodes]
        [-setQuota <quota> <dirname>...<dirname>]
        [-clrQuota <dirname>...<dirname>]
        [-setSpaceQuota <quota> [-storageType <storagetype>] <dirname>...<dirname>]
        [-clrSpaceQuota [-storageType <storagetype>] <dirname>...<dirname>]
        [-finalizeUpgrade]
        [-rollingUpgrade [<query|prepare|finalize>]]
        [-upgrade <query | finalize>]
        [-refreshServiceAcl]
        [-refreshUserToGroupsMappings]
        [-refreshSuperUserGroupsConfiguration]
        [-refreshCallQueue]
        [-refresh <host:ipc_port> <key> [arg1..argn]
        [-reconfig <namenode|datanode> <host:ipc_port> <start|status|properties>]
        [-printTopology]
        [-refreshNamenodes datanode_host:ipc_port]
        [-getVolumeReport datanode_host:ipc_port]
        [-deleteBlockPool datanode_host:ipc_port blockpoolId [force]]
        [-setBalancerBandwidth <bandwidth in bytes per second>]
        [-getBalancerBandwidth <datanode_host:ipc_port>]
        [-fetchImage <local directory>]
        [-allowSnapshot <snapshotDir>]
        [-disallowSnapshot <snapshotDir>]
        [-shutdownDatanode <datanode_host:ipc_port> [upgrade]]
        [-evictWriters <datanode_host:ipc_port>]
        [-getDatanodeInfo <datanode_host:ipc_port>]
        [-metasave filename]
        [-triggerBlockReport [-incremental] <datanode_host:ipc_port> [-namenode <namenode_host:ipc_port>]]
        [-listOpenFiles [-blockingDecommission] [-path <path>]]
        [-help [cmd]]

Generic options supported are:
-conf <configuration file>        specify an application configuration file
-D <property=value>               define a value for a given property
-fs <file:///|hdfs://namenode:port> specify default filesystem URL to use, overrides 'fs.defaultFS' property from configurations.
-jt <local|resourcemanager:port>  specify a ResourceManager
-files <file1,...>                specify a comma-separated list of files to be copied to the map reduce cluster
-libjars <jar1,...>               specify a comma-separated list of jar files to be included in the classpath
-archives <archive1,...>          specify a comma-separated list of archives to be unarchived on the compute machines

The general command line syntax is:
command [genericOptions] [commandOptions]

状态报告与节点管理

• [-report [-live] [-dead] [-decommissioning] [-enteringmaintenance] [-inmaintenance]]: 生成整个HDFS集群的状态报告。可以使用附加标志来过滤特定类型的DataNode（活动、死亡、正在退役、进入维护模式或在维护模式中的节点）。

• [-refreshNodes]: 重新加载配置文件并更新NameNode中的节点列表。

• [-refreshNamenodes datanode_host:ipc_port]: 刷新指定DataNode上的NameNode信息，用于使DataNode意识到新的或修改后的NameNode设置。

• [-getDatanodeInfo <datanode_host:ipc_port>]: 获取并显示指定DataNode的信息。

安全模式管理

• [-safemode <enter | leave | get | wait | forceExit>]: 控制NameNode的安全模式。安全模式是一种保护机制，在此模式下，HDFS不允许进行任何修改操作，直到所有DataNode都已检查完毕。选项包括：

名称空间管理

• [-saveNamespace [-beforeShutdown]]: 强制保存名称空间镜像，并可以选择在关机前执行。这会触发一个检查点过程，创建一个新的fsimage文件。

• [-rollEdits]: 滚动编辑日志文件，这会创建一个新的编辑日志文件并开始使用它，同时将旧的日志归档。

• [-restoreFailedStorage true|false|check]: 设置是否尝试恢复失败的存储设备。选项有：

  • true: 尝试恢复。
  • false: 不尝试恢复。
  • check: 只检查而不实际恢复。

• [-finalizeUpgrade]: 最终化升级过程，清除旧版本的数据结构和元数据。

• [-upgrade <query | finalize>]: 查询或完成一次HDFS升级。选项有：

  • query: 查询当前升级状态。
  • finalize: 完成升级过程。

• [-rollingUpgrade [<query|prepare|finalize>]]: 执行滚动升级的相关操作，允许在不停止服务的情况下逐步升级集群。选项有：

  • query: 查询当前滚动升级状态。
  • prepare: 准备开始滚动升级。
  • finalize: 完成滚动升级。

配额设置

• [-setQuota <quota> <dirname>...<dirname>]: 为目录设置文件数量配额，限制该目录下的最大文件数。

• [-clrQuota <dirname>...<dirname>]: 清除目录的文件数量配额。

• [-setSpaceQuota <quota> [-storageType <storagetype>] <dirname>...<dirname>]: 为目录设置磁盘空间配额，可选地针对特定存储类型（如SSD、DISK等）。

• [-clrSpaceQuota [-storageType <storagetype>] <dirname>...<dirname>]: 清除目录的磁盘空间配额。

ACL与权限管理

• [-refreshServiceAcl]: 重新加载服务ACL配置，确保最新的访问控制列表生效。

• [-refreshUserToGroupsMappings]: 重新加载用户到组映射配置，以反映最新的用户和组关系。

• [-refreshSuperUserGroupsConfiguration]: 重新加载超级用户组配置，确保只有授权用户能够执行特权操作。

• [-refreshCallQueue]: 重新加载调用队列配置，影响NameNode如何处理客户端请求。

其他管理任务

• [-reconfig <namenode|datanode> <host:ipc_port> <start|status|properties>]: 对NameNode或DataNode进行在线重配置，允许动态更改某些配置属性而无需重启服务。

• [-printTopology]: 打印网络拓扑结构，帮助理解集群中各个节点的位置关系。

• [-getVolumeReport datanode_host:ipc_port]: 获取指定DataNode的卷报告，提供关于存储容量和健康状况的信息。

• [-deleteBlockPool datanode_host:ipc_port blockpoolId [force]]: 删除指定DataNode上的块池，通常用于清理不再需要的数据。

• [-setBalancerBandwidth <bandwidth in bytes per second>]: 设置平衡器带宽限制，控制DataNode之间复制数据的速度。

• [-getBalancerBandwidth <datanode_host:ipc_port>]: 获取指定DataNode上的平衡器带宽设置。

• [-fetchImage <local directory>]: 下载fsimage到本地目录，用于备份或分析目的。

• [-allowSnapshot <snapshotDir>]: 允许在指定目录创建快照，以便于数据恢复和版本控制。

• [-disallowSnapshot <snapshotDir>]: 禁止在指定目录创建快照。

• [-shutdownDatanode <datanode_host:ipc_port> [upgrade]]: 关闭指定DataNode，可选参数指示是否为升级目的。

• [-evictWriters <datanode_host:ipc_port>]: 强制驱逐写入者客户端，有助于解决长时间占用资源的问题。

• [-metasave filename]: 将当前元数据保存到指定文件中，便于故障排除或审计。

• [-triggerBlockReport [-incremental] <datanode_host:ipc_port> [-namenode <namenode_host:ipc_port>]]: 触发DataNode发送块报告给NameNode，可选择增量报告，以减少传输的数据量。

• [-listOpenFiles [-blockingDecommission] [-path <path>]]: 列出打开的文件，可选择阻止退役操作以及指定路径过滤，帮助管理员了解哪些文件正在被访问。

• [-help [cmd]]: 显示所有可用命令的帮助信息，或者如果指定了cmd，则只显示该命令的帮助信息。

3. 命令

3.1 生成HDFS集群的状态报告

3.1.1 语法及解释

hdfs dfsadmin -report [-live] [-dead] [-decommissioning] [-enteringmaintenance] [-inmaintenance]

• [-live]: 仅列出当前活动（在线）的DataNode。这些节点正在正常工作并与NameNode保持通信。

• [-dead]: 仅列出被认为已经死亡（离线）的DataNode。这些节点可能由于网络问题、硬件故障或其他原因未能与NameNode保持联系。

• [-decommissioning]: 仅列出正处于退役过程中的DataNode。当管理员希望从集群中移除某些节点时，会先将它们标记为退役，以确保数据被复制到其他节点后再进行物理移除。

• [-enteringmaintenance]: 仅列出正在进入维护模式的DataNode。在维护模式下，节点上的读写操作会被限制，但不会立即切断与集群的连接，允许逐步减少其负载。

• [-inmaintenance]: 仅列出已经在维护模式中的DataNode。这些节点通常处于一种受限的操作状态，以便于执行维护任务而不影响集群的整体性能。

3.1.2 示例

获取所有类型DataNode的综合报告。

hdfs dfsadmin -report

仅列出活动的DataNode。

hdfs dfsadmin -report -live

仅列出死亡的DataNode。

hdfs dfsadmin -report -dead

仅列出正在退役的DataNode。

hdfs dfsadmin -report -decommissioning

仅列出正在进入维护模式的DataNode。

hdfs dfsadmin -report -enteringmaintenance

仅列出已在维护模式中的DataNode。

hdfs dfsadmin -report -inmaintenance

3.2 重新加载配置文件并更新NameNode中的节点列表

hdfs dfsadmin -refreshNodes

3.3 刷新指定DataNode上的NameNode信息

3.3.1 语法

hdfs dfsadmin -refreshNamenodes datanode_host:ipc_port

3.4 获取并显示指定DataNode的信息

3.4.1 语法

hdfs dfsadmin -getDatanodeInfo <datanode_host:ipc_port>

3.5 控制NameNode的安全模式

3.5.1 语法及解释

hdfs dfsadmin -safemode <enter | leave | get | wait | forceExit>

• enter: 进入安全模式。
• leave: 离开安全模式。
• get: 获取当前安全模式状态。
• wait: 等待离开安全模式。
• forceExit: 强制退出安全模式。

3.5.2 示例

获取当前安全模式状态。

hdfs dfsadmin -safemode get

3.6 保存名称空间镜像

3.6.1 语法及解释

hdfs dfsadmin -saveNamespace [-beforeShutdown]

• -beforeShutdown: 在关机前执行。

3.6.2 示例

进入安全模式状态。

hdfs dfsadmin -safemode enter

保存名称空间镜像。

hdfs dfsadmin -saveNamespace -beforeShutdown

离开安全模式状态。

hdfs dfsadmin -safemode leave

3.7 滚动edits日志文件

滚动edits日志文件，会创建一个新的编辑日志文件并开始使用它，同时将旧的日志归档。

hdfs dfsadmin -rollEdits

3.8 设置是否尝试恢复失败的存储设备

3.8.1 语法及解释

hdfs dfsadmin -restoreFailedStorage true|false|check

• true: 尝试恢复。
• false: 不尝试恢复。
• check: 只检查而不实际恢复。

3.8.2 示例

hdfs dfsadmin -restoreFailedStorage check

3.9 最终化升级

最终化升级过程，清除旧版本的数据结构和元数据。

hdfs dfsadmin -finalizeUpgrade

3.10 查询或完成一次HDFS升级

3.10.1 语法及解释

hdfs dfsadmin -upgrade <query | finalize>

• query: 查询当前升级状态。
• finalize: 完成升级过程。

3.11 滚动升级

执行滚动升级的相关操作，允许在不停止服务的情况下逐步升级集群。

3.11.1 语法及解释

hdfs dfsadmin -rollingUpgrade prepare[<query|prepare|finalize>]

• query: 查询当前滚动升级状态。
• prepare: 准备开始滚动升级。
• finalize: 完成滚动升级。

3.12 设置配额

为目录设置文件数量配额，限制该目录下的最大文件数。

3.12.1 语法及解释

hdfs dfsadmin -setQuota <quota> <dirname>...<dirname>

3.12.2 示例

设置目录/test下最多只能存60个文件。

hdfs dfsadmin -setQuota 60 /test

3.13 清除配额

3.13.1 语法及解释

清除目录的文件数量配额。

hdfs dfsadmin -clrQuota <dirname>...<dirname>

3.13.2 示例

清除目录/test下的文件数量配额。

hdfs dfsadmin -clrQuota /test

3.14 设置目录的磁盘空间配额

3.14.1 语法及解释

hdfs dfsadmin -setSpaceQuota <quota> [-storageType <storagetype>] <dirname>...<dirname>

• <quota>: 指定空间配额的大小，单位为字节（B）。你也可以使用K（KB）、M（MB）、G（GB）、T（TB）、P（PB）来表示更大的单位。

• [-storageType <storagetype>]: 这是一个可选参数，允许您针对特定类型的存储设置空间配额。HDFS支持多种存储类型，包括：

  • ALL: 默认值，适用于所有类型的存储。
  • DISK: 普通硬盘。
  • SSD: 固态硬盘。
  • ARCHIVE: 归档存储，通常用于冷数据。

3.14.2 示例

设置目录/test的空间配额为100MB。

hdfs dfsadmin -setSpaceQuota 100M /test

3.15 清除目录的磁盘空间配额

3.15.1 语法及解释

hdfs dfsadmin -clrSpaceQuota [-storageType <storagetype>] <dirname>...<dirname>

3.15.2 示例

hdfs dfsadmin -clrSpaceQuota /test

3.16 重新加载服务ACL配置

hdfs dfsadmin -refreshServiceAcl

3.17 重新加载用户到组映射配置

hdfs dfsadmin -refreshUserToGroupsMappings

3.18 重新加载超级用户组配置

hdfs dfsadmin -refreshSuperUserGroupsConfiguration

3.19 重新加载调用队列配置

重新加载调用队列配置，影响NameNode如何处理客户端请求。

hdfs dfsadmin -refreshCallQueue

3.20 重配置

对NameNode或DataNode进行在线重配置，允许动态更改某些配置属性而无需重启服务。

hdfs dfsadmin -reconfig <namenode|datanode> <host:ipc_port> <start|status|properties>

3.21 打印网络拓扑结构

打印网络拓扑结构，帮助理解集群中各个节点的位置关系。

hdfs dfsadmin -printTopology

3.22 获取指定DataNode的卷报告

获取指定DataNode的卷报告，提供关于存储容量和健康状况的信息。

hdfs dfsadmin -getVolumeReport datanode_host:ipc_port

3.23 删除指定DataNode上的块池

删除指定DataNode上的块池，通常用于清理不再需要的数据。

hdfs dfsadmin -deleteBlockPool datanode_host:ipc_port blockpoolId [force]

• [force]：强制执行块池的删除操作。

3.24 设置平衡器带宽限制

设置平衡器带宽限制，控制DataNode之间复制数据的速度。

hdfs dfsadmin -setBalancerBandwidth <bandwidth in bytes per second>

<bandwidth in bytes per second>：指定Balancer在执行平衡操作时使用的最大带宽，单位为字节每秒（bytes/s）。

3.25 获取指定DataNode上的平衡器带宽设置

hdfs dfsadmin -getBalancerBandwidth <datanode_host:ipc_port>

3.26 下载fsimage到本地目录

下载fsimage到本地目录，用于备份或分析目的。

hdfs dfsadmin -fetchImage <local directory>

3.27 允许在指定目录创建快照

允许在指定目录创建快照，以便于数据恢复和版本控制。

hdfs dfsadmin -allowSnapshot <snapshotDir>

3.28 禁止在指定目录创建快照

禁止在指定目录创建快照。

hdfs dfsadmin -disallowSnapshot <snapshotDir>

3.29 关闭指定DataNode

关闭指定DataNode，可选参数指示是否为升级目的。

hdfs dfsadmin -shutdownDatanode <datanode_host:ipc_port> [upgrade]

3.30 强制驱逐写入者客户端

强制驱逐写入者客户端，有助于解决长时间占用资源的问题。

hdfs dfsadmin -evictWriters <datanode_host:ipc_port>

3.31 将当前元数据保存到指定文件中

将当前元数据保存到指定文件中，便于故障排除或审计。

hdfs dfsadmin -metasave filename

3.32 触发DataNode发送块报告给NameNode

触发DataNode发送块报告给NameNode，可选择增量报告，以减少传输的数据量。

hdfs dfsadmin -triggerBlockReport [-incremental] <datanode_host:ipc_port> [-namenode <namenode_host:ipc_port>]

3.33 列出打开的文件

列出打开的文件，可选择阻止退役操作以及指定路径过滤，帮助管理员了解哪些文件正在被访问。

hdfs dfsadmin -listOpenFiles [-blockingDecommission] [-path <path>]