Ubuntu HDFS故障排查指南

1. 检查HDFS集群整体状态

使用hdfs dfsadmin -report命令获取集群健康状况，包括NameNode状态、DataNode数量、各节点存储容量使用率、副本数等关键信息。若DataNode数量为0或副本数低于配置值（如dfs.replication默认3），需进一步排查节点连接或数据块分布问题。

2. 查看NameNode与DataNode日志

日志是故障定位的核心依据，路径通常为$HADOOP_HOME/logs/（如/usr/local/hadoop/logs/）。

• NameNode日志：hadoop-<username>-namenode-<hostname>.log，重点关注启动错误（如元数据损坏）、RPC通信失败（如端口被占用）；
• DataNode日志：hadoop-<username>-datanode-<hostname>.log，常见错误包括磁盘空间不足（No space left on device）、权限拒绝（Permission denied）、网络连接失败（Connection refused）。
  使用tail -f命令实时跟踪日志，快速定位错误关键词。

3. 验证配置文件正确性

HDFS核心配置文件（$HADOOP_HOME/etc/hadoop/）的错误会导致集群无法启动或运行异常，需重点检查：

• core-site.xml：fs.defaultFS（NameNode RPC地址，如hdfs://localhost:9000）是否正确；
• hdfs-site.xml：dfs.namenode.name.dir（NameNode元数据存储路径）、dfs.datanode.data.dir（DataNode数据存储路径）是否存在且具备读写权限；
• yarn-site.xml（若使用YARN）：yarn.resourcemanager.hostname（ResourceManager地址）是否配置正确。
  确保配置项无多余空格、标签闭合完整，修改后执行source ~/.bashrc使环境变量生效。

4. 处理NameNode常见故障

4.1 NameNode进程未运行

使用jps命令检查进程是否存在（应显示NameNode）。若未运行，查看NameNode日志定位原因：

• 若日志提示“not formatted”，需格式化NameNode（注意：格式化会清除原有元数据，需提前备份）：

  hdfs namenode -format
  

• 若日志提示“port already in use”（如9000端口被占用），使用netstat -tuln | grep 9000或ss -tuln | grep 9000查找占用进程，终止后重启NameNode：

  stop-dfs.sh && start-dfs.sh
  

4.2 NameNode进入安全模式

若NameNode因数据块副本不足（如dfs.replication设置为3，但某文件仅有1个副本）进入安全模式，无法进行写操作，可使用以下命令退出：

hdfs dfsadmin -safemode leave

若无法自动退出，需检查DataNode是否正常运行（hdfs dfsadmin -report），补充缺失的副本（hdfs dfs -setrep 3 /path/to/file）。

5. 处理DataNode常见故障

5.1 DataNode宕机或未注册

使用jps命令检查DataNode进程是否存在。若未运行，执行hadoop-daemon.sh start datanode启动；若仍无法启动，查看DataNode日志：

• 磁盘空间不足：使用df -h检查dfs.datanode.data.dir所在磁盘的可用空间（建议保留20%以上），清理旧数据或扩展存储；
• 权限问题：确保HDFS数据目录权限正确（如hdfs:hadoop），执行：

  chown -R hdfs:hadoop $HADOOP_HOME/data/datanode
  chmod -R 755 $HADOOP_HOME/data/datanode
  

• 主机名解析失败：检查/etc/hosts文件，确保集群节点IP与主机名映射正确（如192.168.1.100 master、192.168.1.101 slave1）。

5.2 DataNode数据块损坏

使用hdfs fsck命令检查文件系统一致性，定位损坏的数据块：

hdfs fsck / -files -blocks -locations

若发现损坏块，可尝试自动修复（-move将损坏块移动到/lost+found，-delete删除损坏块）：

hdfs fsck / -delete

若自动修复无效，需从其他DataNode的副本中恢复数据（hdfs dfs -cp /path/to/source /path/to/destination）。

6. 解决启动失败问题

若HDFS无法启动，需逐一排查以下常见原因：

• 端口冲突：使用netstat -tuln | grep <port>（如9000、50070）检查所需端口是否被占用，终止冲突进程；
• 环境变量未设置：确保JAVA_HOME（如export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64）、HADOOP_HOME（如export HADOOP_HOME=/usr/local/hadoop）已正确配置并生效；
• 权限问题：确保当前用户对HDFS目录（如dfs.namenode.name.dir、dfs.datanode.data.dir）有读写权限，必要时使用sudo chown修改所有权；
• 元数据损坏：若NameNode元数据损坏，需从SecondaryNameNode或备份中恢复fsimage和edits文件（位于dfs.namenode.name.dir目录下），或重新格式化NameNode。

7. 数据写入错误排查

若数据写入过程中出现错误（如DFSOutputStream失败），需检查：

• DataNode状态：使用hdfs dfsadmin -report确认所有DataNode均处于“Live”状态；
• 副本数设置：若dfs.replication设置为3，但集群中只有2个DataNode，需增加DataNode数量或降低副本数（hdfs dfs -setrep 2 /path/to/file）；
• 网络问题：使用ping、telnet测试节点间网络连通性，确保防火墙未阻止HDFS端口（如9000、50010）；
• 磁盘空间：使用df -h检查DataNode存储目录的可用空间，确保有足够空间接收数据。

8. 使用快照与备份恢复数据

• 快照恢复：若文件系统支持快照（需提前创建），可使用hdfs dfsadmin -allowSnapshot /path允许目录创建快照，再通过hdfs dfs -cp /path/.snapshot/snapshot_name /path/to/restore恢复数据；
• 备份恢复：定期使用hadoop distcp命令跨集群备份数据（如hadoop distcp hdfs://master:9000/path hdfs://slave1:9000/backup），或使用HDFS快照功能备份关键目录。