Debian 环境下 HDFS 配置常见问题与排查
一 环境与权限类问题
- Java 与 Hadoop 版本不匹配或未安装：Hadoop 3.x 建议使用 Java 8 或 11。在 Debian 上常见做法是安装 openjdk-8-jdk 或 openjdk-11-jdk，并正确设置 JAVA_HOME 与 HADOOP_HOME 环境变量（如：/usr/lib/jvm/java-11-openjdk-amd64、/usr/local/hadoop），否则会出现命令不可用或启动异常。
- 以错误用户启动或权限不足：不要以 root 启动 Hadoop；若曾以 root 运行，后续切换到普通用户（如 hadoop）会因目录/文件属主问题报 Permission denied。需将 Hadoop 安装目录与数据目录（如 dfs/name、dfs/data）授权给运行用户，并确保所有节点一致。
- 主机名与 /etc/hosts 解析错误：集群节点必须能互相解析主机名。若自定义了 SSH 端口 或 hostname，需在 /etc/hosts 正确映射，并在必要时设置 HADOOP_SSH_OPTS=“-p <端口>”，否则会出现 UnknownHostException 或 SSH 连接被拒绝。
- workers（或 slaves）配置遗漏：未正确填写 workers 文件会导致只有单个节点有进程，其他节点 DataNode 不启动。应确保该文件列出所有 DataNode 主机名，并与各节点配置一致。
二 配置与启动类问题
- 核心配置文件错误：拼写、标签闭合或属性值错误（如 core-site.xml、hdfs-site.xml）会导致启动失败或 WstxEOFException。建议逐项核对，并使用 IDE/XML 校验器检查。
- 未格式化 NameNode 或集群 ID 不一致：首次启动前必须执行 hdfs namenode -format；若多次格式化而未清理 dfs/name、dfs/data 与 logs，会导致 NameNode 与 DataNode 的集群 ID 不一致，DataNode 无法注册。规范做法是停掉进程、清理数据与日志后再格式化。
- 目录未创建或权限不对：dfs.namenode.name.dir、dfs.datanode.data.dir 指定的目录若不存在或不可写，NameNode/DataNode 将无法持久化元数据/块数据。需提前创建目录并赋权给运行用户。
- 环境变量与路径不一致：若 HADOOP_HOME 指向软链接或不同路径，需确保所有节点的配置文件与实际安装路径一致，避免脚本找不到二进制或配置文件。
三 网络与端口连通性问题
- 节点间网络不通或防火墙阻断：需保证所有节点互通，并开放必要端口（如 HDFS RPC 9000、NameNode HTTP 50070、JournalNode 8485、ZooKeeper 2181 等），否则会出现连接超时或拒绝。
- 主机名解析不一致：客户端与集群节点、或集群节点彼此之间若不能通过 /etc/hosts 或 DNS 正确解析主机名，会在启动或访问时报 UnknownHostException。
- SSH 端口非默认：若 SSH 端口 不是 22，需在 hadoop-env.sh 中设置 HADOOP_SSH_OPTS=“-p <端口>”，否则脚本无法免密登录到各节点启停进程。
- 网络参数与带宽：未优化 Jumbo 帧、网络缓冲区等会影响大数据传输性能。生产环境建议在网络设备支持时启用 Jumbo 帧 并合理调优内核网络参数。
四 高可用与升级类问题
- HA 必要组件缺失或配置不完整：HDFS HA 需要 ZooKeeper、JournalNode、ZKFailoverController（ZKFC）。常见疏漏包括：未部署 ZK、未启动 JournalNode、未在 core-site.xml 配置 ha.zookeeper.quorum、未在 hdfs-site.xml 配置 dfs.nameservices、dfs.ha.namenodes.、dfs.namenode.shared.edits.dir（qjournal://…）、dfs.ha.fencing.methods（如 sshfence） 等，导致无法自动故障转移或脑裂。
- 未初始化 ZK 的 HA 状态：启用自动故障转移前，需执行 hdfs zkfc -formatZK 初始化 ZooKeeper 中的 HA 元数据。
- 多次格式化导致 ID 不一致：在 HA 环境下重复格式化 NameNode 而未清理数据目录，同样会造成 集群 ID 不一致，使 DataNode 无法加入集群。
- 版本与配置差异：不同 Hadoop 小版本在默认端口、参数名或行为与兼容性上存在差异，升级或混布时需逐节点核对配置与版本，并回归关键场景测试。
五 快速排查清单与常用命令
- 前置检查：
- 执行 java -version、hadoop version 确认环境；
- 核对 /etc/hosts 与 workers 文件；
- 确认 JAVA_HOME、HADOOP_HOME、PATH 已正确导出并在各节点一致。
- 目录与权限：
- 确认 dfs.namenode.name.dir、dfs.datanode.data.dir 存在且属主正确；
- 若曾以 root 运行，使用 chown -R hadoop:hadoop <HADOOP_HOME> 修复。
- 启动与格式化：
- 首次部署执行 hdfs namenode -format；
- 异常后先停进程，清理 dfs/name、dfs/data、logs 再格式化；
- 启动命令：start-dfs.sh、start-yarn.sh。
- 验证与定位：
- 执行 hdfs dfsadmin -report 查看 Live/Decommissioning 节点；
- 执行 hdfs dfs -ls / 验证存取；
- 访问 NameNode Web UI：http://:50070；
- 查看 $HADOOP_HOME/logs/ 下对应进程的 .log 与 .out 定位错误；
- 若使用 HA，执行 hdfs haadmin -getServiceState nn1 检查主备状态。
