Debian 上 HDFS 配置失败的定位与修复指南
一 快速自检清单
- 检查进程是否起来：运行 jps，应看到 NameNode、DataNode、SecondaryNameNode（伪分布式）。若缺失，说明 HDFS 未启动或启动失败。
- 核对基础连通与端口：
- 本地连通性：执行 hdfs dfs -ls /，若报连接异常，多半是 NameNode 未启动或 fs.defaultFS 配置错误。
- 端口连通性：执行 nc -vz 127.0.0.1 9000，应能连通；若不通，检查 core-site.xml 的 fs.defaultFS=hdfs://localhost:9000 是否配置正确。
- 查看日志定位根因：到 $HADOOP_HOME/logs/ 查看最新的 hadoop--namenode-*.log 与 hadoop--datanode-*.log。
- 环境与健康：确认 JAVA_HOME 已设置（如 /usr/lib/jvm/java-11-openjdk-amd64），系统资源充足（CPU/内存/磁盘）。
- 伪分布式必做：确保 SSH 免密登录 localhost 正常（Hadoop 脚本依赖 SSH 启停进程）。
二 常见故障与修复对照表
| 症状 |
快速检查 |
修复建议 |
| jps 没有 NameNode/DataNode |
查看 $HADOOP_HOME/logs 报错 |
先用 stop-dfs.sh 停止残留进程，再 start-dfs.sh；若仍失败，依据日志逐项修复配置/权限/目录问题 |
| Call to localhost/127.0.0.1:9000 失败 |
nc -vz 127.0.0.1 9000 不通；jps 无 NameNode |
确认 core-site.xml 的 fs.defaultFS 为 hdfs://localhost:9000；启动 NameNode；必要时重启集群 |
| Retrying connect to server: localhost/127.0.0.1:9000 |
端口不通或进程未起 |
同上；若端口被占用，kill 占用进程或更换端口后重启 |
| localhost Name or service not known |
/etc/hosts 未正确映射 localhost |
在 /etc/hosts 确保存在 127.0.0.1 localhost 且未被注释 |
| Cannot lock storage … The directory is already locked |
上次异常退出残留锁文件 |
删除 /tmp/hadoop-/dfs/ 下相关锁目录（如 name、data），再启动 |
| DataNode 与 NameNode namespaceID 不一致 |
多次格式化导致 VERSION 中 namespaceID 不匹配 |
清空 dfs.name.dir/dfs.data.dir 对应目录，重新 hdfs namenode -format 后启动 |
| SSH 连接被拒绝（port 22） |
service ssh status 未运行或无密钥 |
安装并启动 openssh-server；配置 ssh-keygen 与 authorized_keys 实现免密登录 |
| ls: Cannot access .: No such file or directory |
首次进入 HDFS 当前目录为空 |
这是正常现象；先创建或使用 /user/，如 hdfs dfs -mkdir -p /user/ |
三 关键配置与目录检查
- 核心配置示例
- core-site.xml：
- fs.defaultFS=hdfs://localhost:9000（单机/伪分布式）
- hdfs-site.xml：
- dfs.replication=1（单机/伪分布式）
- dfs.namenode.name.dir=file:///opt/hadoop/hdfs/namenode
- dfs.datanode.data.dir=file:///opt/hadoop/hdfs/datanode
- 环境变量与目录权限
- 设置 JAVA_HOME 与 HADOOP_HOME，并确保 dfs.namenode.name.dir/dfs.datanode.data.dir 的父目录对运行用户可写。
- 避免临时目录被清理
- 若使用默认 /tmp，系统重启会丢失元数据与锁文件，建议在 core-site.xml 设置 hadoop.tmp.dir（如 /home//hadoop_tmp），然后重新格式化并启动。
- 主机名解析
- 在 /etc/hosts 正确映射 127.0.0.1 localhost，避免 “localhost Name or service not known”。
四 标准恢复流程
- 停止残留进程：stop-dfs.sh；必要时用 jps 确认并 kill 异常进程。
- 备份并校正配置：核对 core-site.xml/hdfs-site.xml 的 fs.defaultFS、dfs.replication、dfs.namenode.name.dir、dfs.datanode.data.dir 等关键项。
- 修复 SSH：确保 SSH 服务运行 且 localhost 免密登录 正常。
- 清理锁与旧数据：删除 /tmp/hadoop-/ 或自定义的 hadoop.tmp.dir 下 dfs/name、dfs/data 的锁与内容（⚠️ 会丢失 HDFS 数据）。
- 重新格式化：hdfs namenode -format（仅在确认数据可丢弃时执行）。
- 启动并验证：start-dfs.sh → jps 检查进程 → hdfs dfs -ls / 验证访问 → 查看 $HADOOP_HOME/logs/ 确认无新错误。
五 仍未恢复时的建议
- 贴出以下关键信息以便精确定位：
- $HADOOP_HOME/etc/hadoop/ 下 core-site.xml/hdfs-site.xml 的相关片段；
- jps 输出；
- $HADOOP_HOME/logs/ 中最新 namenode 与 datanode 的日志尾部（至少 50 行）；
- 执行 hdfs dfsadmin -report 与 nc -vz 127.0.0.1 9000 的结果。
- 若环境复杂（多节点/启用安全/Kerberos/防火墙），同步检查 防火墙/安全组、主机名与 /etc/hosts、以及 Kerberos 票据/keytab 是否有效。
