本地启动 Hadoop 卡在 starting namenodes 主要是 SSH 免密登录未配置成功，导致 start-dfs.sh 等脚本阻塞等待密码输入；需执行 ssh localhost 验证，失败则用 ssh-keygen 和 ssh-copy-id 重配密钥。
为什么本地启动 Hadoop 会卡在 starting namenodes 不动
绝大多数 Java 开发者第一次搭 Hadoop 分布式环境，不是败在配置文件上，而是败在 SSH 本身没跑通。Hadoop 启动脚本（比如 start-dfs.sh）默认会用 SSH 连自己（localhost 或主机名），如果没配好免密登录，它就卡住等密码输入——而你根本看不到提示。
- 检查
ssh localhost能否直接连上不输密码；不行就重做密钥：ssh-keygen -t rsa -P ''→ssh-copy-id localhost - 确保
hdfs-site.xml中的dfs.namenode.http-address和dfs.datanode.http.address没写成127.0.0.1，得用机器真实 IP 或可解析的主机名（否则 DataNode 注册失败） - Java 版本必须是 8 或 11（Hadoop 3.x 不支持 Java 17+），运行
java -version确认，别信 IDE 里选的 JDK 就是系统实际用的
ClassNotFoundException: org.apache.hadoop.fs.FileSystem 怎么加对依赖
这是 Maven 项目里最常踩的坑：只加了 hadoop-client，却漏掉 HDFS 的核心实现模块。Hadoop 的 JAR 包拆得很碎，hadoop-client 只是门面，真正读写 HDFS 需要 hadoop-hdfs 和它的 transitive 依赖（比如 hadoop-common）。
- Maven 中至少要显式声明：
hadoop-client、hadoop-hdfs、hadoop-common，版本必须严格一致（如3.3.6） - 避免用
providedscope——本地测试时这些包必须打进 fat jar 或出现在 classpath，否则运行时找不到FileSystem子类 - 如果用 Spring Boot，别让
spring-boot-maven-plugin自动 exclude Hadoop 的slf4j-log4j12，否则可能引发日志冲突报错
Java 代码里怎么连上远程 HDFS 而不是本地伪分布
连错集群是开发期高频问题。默认情况下，FileSystem.get(new Configuration()) 会读取 classpath 下的 core-site.xml 和 hdfs-site.xml，如果这些文件没放对位置，或者内容指向了 file:/// 或 hdfs://localhost:9000，那你的 Java 程序就根本没连上真正的分布式集群。
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
- 确认
core-site.xml中fs.defaultFS值是形如hdfs://mycluster:9000的地址，且该 host 能被 DNS 或/etc/hosts解析 - Java 里不要硬编码配置，优先用
new Configuration(true)加载默认资源，再用conf.set("fs.defaultFS", "...")覆盖 - 测试连通性先用命令行：
hadoop fs -ls hdfs://mycluster:9000/，成功了再写 Java 代码；别跳过这步
为什么 DataNode 启不来，日志里只有 Failed to add storage directory
这不是权限问题，也不是磁盘满，而是 Hadoop 对 DataNode 的存储目录有“干净启动”要求：如果上次异常退出，它会在目录下留一个 in_use.lock 文件，下次启动时发现这个文件还在，就拒绝加载该目录——哪怕里面数据是完好的。
立即学习“Java免费学习笔记（深入）”；
- 进到
dfs.datanode.data.dir配置的路径（比如/usr/local/hadoop/data），手动删掉所有in_use.lock - 别直接删整个
data目录！除非你确定不需要旧数据；删了会导致 NameNode 认为所有块丢失，触发大量冗余复制 - 更稳妥的做法是在
hdfs-site.xml中加配置：dfs.datanode.directory.scan.interval调小（如 30s），让 DataNode 更快感知目录状态变化
分布式环境里，每个节点的配置一致性、时间同步（NTP）、防火墙端口（9000、9870、9864 等）才是比语法更难 debug 的地方。别急着写业务逻辑，先让 hdfs dfsadmin -report 显示出全部 Live DataNode。
