CentOS 上部署 HDFS 的常见错误与排查要点
一 环境与配置类错误
- Java 或 Hadoop 环境变量未设置或路径错误：未正确配置 JAVA_HOME/HADOOP_HOME，或未执行 source /etc/profile 使配置生效，导致命令不可用或启动失败。建议在 /etc/profile 或 ~/.bashrc 中正确导出变量并生效。
- 关键配置项缺失或错误：如 core-site.xml 的 fs.defaultFS、hdfs-site.xml 的 dfs.namenode.name.dir/dfs.datanode.data.dir/dfs.replication/dfs.namenode.http-address 等，参数错误或路径不可写都会引发启动或访问异常。
- 配置文件未同步到所有节点：集群多机部署时，各节点 core-site.xml/hdfs-site.xml 不一致，导致节点行为不统一、服务异常。
- 目录权限与属主不正确：Hadoop 数据目录、日志目录未赋予运行用户（如 hdfs）读写权限，易出现 Permission denied。
- SSH 免密未配置：启动脚本在多机间分发与启停依赖 SSH 免密登录，未配置会导致 start-dfs.sh 失败或卡住。
二 网络与主机名解析类错误
- /etc/hosts 主机名解析错误：出现 UnknownHostException 或节点间无法互通，多因 /etc/hosts 未正确映射 IP↔主机名。
- 防火墙阻断通信：未放行 HDFS 端口（如 50070 等 Web UI 端口及数据端口），导致 Web UI 无法访问 或节点间通信失败。
- 网络不通或端口占用：节点间 ping 不通、端口被占用（如 netstat -tulpen | grep 端口），会造成启动失败或频繁超时。
三 启动与存储初始化类错误
- 未格式化 NameNode 或多次格式化导致不一致：首次启动前未执行 hdfs namenode -format，或多次格式化后 VERSION/元数据 不一致，易出现 IncorrectVersionException、启动异常、数据目录不匹配等问题。
- 存储目录未清空或权限不足：格式化前未清理 {HADOOP_HOME}/data、{HADOOP_HOME}/logs，或目录属主/权限错误，导致 NameNode/DataNode 无法写入元数据或日志。
- DataNode 未注册或反复掉线：常见于 dfs.datanode.data.dir 配置错误、磁盘不可写、或 clusterID/namespaceID 不匹配（例如多次格式化后未统一）。
- 复制因子与节点数不匹配：dfs.replication 大于实际 DataNode 数量，会导致副本创建失败或长期处于 Under-Replicated 状态。
四 高可用 HA 特有错误
- 缺少或错误配置 JournalNode：未设置 dfs.journalnode.edits.dir、journalnode 未启动或数量不足（通常 2N+1），导致 edits log 无法共享，Active/Standby 无法同步。
- ZooKeeper 与自动故障转移未就绪：未配置 ha.zookeeper.quorum、未初始化 ZooKeeper znode、ZKFC 未启动，导致 不会自动故障转移。
- Fencing 隔离策略缺失或失效：未配置 sshfence/shellfence，主备切换时可能发生 脑裂（双主），造成数据损坏风险。
- 版本或配置不兼容：Hadoop 版本与配置文件参数不一致（不同版本参数名/默认值可能变化），引发 启动失败 或 HA 行为异常。
五 快速排查清单与常用命令
- 环境与配置：
- 检查版本与变量：
java -version、hadoop version、echo $JAVA_HOME $HADOOP_HOME；必要时 source /etc/profile。
- 校验关键配置：
core-site.xml 的 fs.defaultFS；hdfs-site.xml 的 dfs.namenode.name.dir/dfs.datanode.data.dir/dfs.replication/dfs.namenode.http-address。
- 网络与解析：
- 解析与连通：
cat /etc/hosts、ping <主机名/IP>、telnet <IP> <端口>。
- 防火墙放行：
firewall-cmd --list-ports；必要时 firewall-cmd --add-port=<端口>/tcp --permanent && firewall-cmd --reload（或临时 systemctl stop firewalld 仅用于排查）。
- 启动与存储：
- 初始化与启停：
hdfs namenode -format（首次且确认无重要数据）、start-dfs.sh、stop-dfs.sh。
- 日志与进程：
tail -n 200 $HADOOP_HOME/logs/hadoop-*-namenode-*.log、jps 检查 NameNode/DataNode/JournalNode/ZKFC。
- 目录与权限：
ls -ld <数据目录>，必要时 chown -R hdfs:hadoop <目录> && chmod -R 755 <目录>。
- HA 专项：
- 启动顺序：先启动 ZooKeeper 集群 → 启动各节点 JournalNode → 初始化 ZooKeeper znode（如
hdfs zkfc -formatZK）→ 启动 NameNode/DataNode/ZKFC。
- 验证与转移：
hdfs haadmin -getServiceState nn1、hdfs haadmin -failover --forcefence --forceactive nn1 nn2。