Hadoop 3.2.4 伪分布式部署实战：从 JDK 配对到配置调优

简介：Hadoop 3.2.4安装包，面向需要部署Apache Hadoop分布式计算环境的开发者与运维人员，适用于搭建集群、学习大数据组件及离线实践。压缩包共2000个文件，以html帮助文档和css样式为主，另有shell脚本、SQL、XML配置及properties、txt等文件，涵盖启动控制、配置模板、数据库脚本与说明文档；其中HTML文档对应Hadoop各模块的API与使用指南，CSS负责页面样式，Shell脚本用于服务启停，SQL与XML提供元数据及配置示例，便于使用者按需查阅和修改。包体约505.9MB，内容完整，适合作为离线安装介质或环境备份，免去在线下载与版本核对流程。已有225人学习下载，可参考他人使用经验。解压后可按目录快速定位HDFS、YARN、MapReduce等组件文件，完成安装部署并对照内置文档理解配置项，为后续性能调优与二次开发打下基础。

1. 拿到 hadoop-3.2.4 安装包：先别急着解压，环境配对才是第一道坎

只要同时满足两个条件，hadoop-3.2.4 安装包的部署就会变得很顺利：一是 JDK 版本没选错，二是配置文件的端口和目录没踩到 3.x 的改名坑。我见过不少项目卡在这里，解压半小时、调配置一整天，最后在格式化环节崩溃。这份安装包本身是完整的，问题几乎都出在环境配对、配置参数和启动顺序上。如果你是第一次跑这套流程，或者之前部署过 2.x 想迁到 3.2.4，这篇笔记按实际工程顺序写，每一处参数都给了落地理由。适合准备搭单机伪分布式、小规模测试集群，以及后续要接 Hive、Spark 这类计算插件的开发者和运维。

2. 安装前准备：JDK 版本配对、安装包校验与目录规范

2.1 JDK 必须选 8 或 11，不要用 17 跑 3.2.4

Hadoop 3.2.4 的编译目标适配的是 JDK 8 和 JDK 11，官方发布说明里也明确列出这两个 LTS 版本。装完系统自带的最新版 JDK 直接跑，很容易在hdfs namenode -format时报Unsupported class file major version 61，这是编译字节码版本和 JVM 版本不匹配的典型特征。JDK 17 引入的模块化限制还会影响 Hadoop 依赖的某些 Native 库加载，排查起来非常费时间。

# Debian/Ubuntu 系发行版，安装 OpenJDK 8 sudo apt install openjdk-8-jdk-headless # RHEL/CentOS 系发行版，安装 OpenJDK 8 sudo yum install java-1.8.0-openjdk-devel # 验证版本，确认是 1.8 或 11，而不是 17 java -version # 把 JAVA_HOME 写入 /etc/profile 或 ~/.bashrc export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64 export PATH=$JAVA_HOME/bin:$PATH

注意JAVA_HOME必须指向 JDK 根目录，不要指到 JRE 目录，Hadoop 的某些工具会读取$JAVA_HOME/lib下的包去加载运行库。设置完成后执行source ~/.bashrc再echo $JAVA_HOME确认一下。如果机器上已经装了多个版本，建议在/etc/profile里固定JAVA_HOME，避免其他用户 shell 拉到另一个 JDK。

这里有个常被忽略的细节：JAVA_HOME 写错只会在启动脚本时报错，但是在格式化 NameNode 时并不会提示，它直到写元数据阶段才失败。所以每次部署前先跑一句java -version和which java，确认当前 shell 实际用的是哪一个 JDK，比什么都重要。

2.2 用 sha512 校验安装包完整性

从各处渠道下载的 hadoop-3.2.4.tar.gz，文件长度一样不代表内容一致。公共网络下载过程中静默损坏的概率虽然不高，但一旦发生，解压时往往只报一个莫名其妙的gzip: invalid compressed data。与其解压后对着报错发呆，不如下载后先做一次哈希校验。

cd /opt/packages # 计算本地文件的哈希值 sha512sum hadoop-3.2.4.tar.gz # 将官方发布的哈希值写入 expected.txt echo '官方哈希值 hadoop-3.2.4.tar.gz' > expected.txt # 通过 -c 参数让命令自动比对 sha512sum -c expected.txt

校验通过后输出一般是hadoop-3.2.4.tar.gz: OK。这一步只能确认文件没损坏，不能替代安全审计。实际生产环境里，我一般还会顺手看一眼文件属主和修改时间，确认不是从某个内部存储复制时被截断的文件。

2.3 目录规划：把数据盘独立出来

很多新手图省事，直接把hadoop.tmp.dir指到系统默认的/tmp下。这么做的风险是：系统重启后/tmp可能被清理，NameNode 的元数据目录一旦被清空，整个集群的数据就彻底找不回来了。正确做法是把程序、元数据、数据块、日志分开，至少要把数据类目录放到独立的数据盘上。

# 创建数据目录 sudo mkdir -p /data/hdfs/name /data/hdfs/data /data/yarn/logs # 授权给当前启动用户 sudo chown -R $USER:$USER /data/hdfs /data/yarn # 解压安装包到 /opt 下 sudo tar -zxvf hadoop-3.2.4.tar.gz -C /opt sudo ln -s /opt/hadoop-3.2.4 /opt/hadoop

目录属主是一个非常容易翻车的点。Hadoop 的启动脚本start-dfs.sh默认用当前用户身份通过 SSH 登录目标机执行进程拉启，目录属主不一致时，DataNode 进程根本写不进数据目录，日志里只会反复出现Permission denied。所以安装包解压完，第一件事就是确认/data/hdfs的属主是当前用户，不是 root。

2.4 免密 SSH：伪分布式也会用到 start-dfs.sh

单机伪分布式看似只有一台机器，但start-dfs.sh脚本仍然会尝试通过 SSH 连接 localhost 去启动 NameNode 和 DataNode 进程。如果不配免密登录，脚本会在中途停下来输密码，而且每次都停在看起来很莫名的地方。先配好本机免密，后面多节点扩展时这套配置也一样复用。

# 生成 RSA 密钥对，-N '' 表示空口令 ssh-keygen -t rsa -b 4096 -N '' -f ~/.ssh/id_rsa # 把公钥写入本机 authorized_keys cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys # 设置目录权限，必须严格控制 chmod 700 ~/.ssh chmod 600 ~/.ssh/authorized_keys # 验证免密是否生效 ssh localhost hostname

如果最后一条ssh localhost hostname能直接返回主机名而不要求输密码，免密就配好了。注意.ssh目录权限必须是 700，authorized_keys必须是 600，权限太宽松时 SSH 会忽略这个文件。这一步在后续启动脚本排错时会被反复检查，建议配置完立即验证而不是再次启动时才验证。

3. 伪分布式部署：三份 XML 决定 NameNode 与 YARN 的命

3.1 先改 core-site.xml

core-site.xml是 Hadoop 的全局配置，至少包含两个关键项：fs.defaultFS决定客户端和集群组件访问 HDFS 时用的默认地址；hadoop.tmp.dir决定 HDFS 缓存和临时文件根目录。这里有一个 3.x 的显著变化：默认 RPC 端口从 2.x 的9000改成了9820。老教程里的 9000 在 3.2.4 中不会自动生效，如果照抄，客户端连不上 NameNode，而jps又看到进程都在跑，排查起来很痛苦。

<configuration> <property> <name>fs.defaultFS</name> <value>hdfs://localhost:9820</value> </property> <property> <name>hadoop.tmp.dir</name> <value>/data/hdfs/tmp</value> </property> </configuration>

fs.defaultFS的地址必须和机器主机名能解析对应。如果你改了/etc/hostname，记得同步修改/etc/hosts，否则启动脚本用主机名去连时可能走到 IPv6 的::1，导致连接超时。hadoop.tmp.dir写/data/hdfs/tmp而不是/tmp，因为/tmp重启即清空，NameNode 和 DataNode 默认会把元数据、数据块信息往这个目录下放，起完进程再改目录属于给自己找事。

3.2 再改 hdfs-site.xml

hdfs-site.xml管理 HDFS 的副本数、元数据存储位置和数据块存储位置。单机伪分布式最关键的设置是dfs.replication必须为 1。如果保持默认的 3，单一 DataNode 永远凑不够副本，健康状态里数据块会一直显示Under-replicated，看着像坏了，其实只是副本数设置问题。

<configuration> <property> <name>dfs.replication</name> <value>1</value> </property> <property> <name>dfs.namenode.name.dir</name> <value>file:///data/hdfs/name</value> </property> <property> <name>dfs.datanode.data.dir</name> <value>file:///data/hdfs/data</value> </property> </configuration>

dfs.namenode.name.dir存储元数据镜像和编辑日志，丢失后集群无法恢复。dfs.datanode.data.dir存储实际数据块，可以填多个路径用逗号分隔，比如file:///data/hdfs/data1,file:///data/hdfs/data2，这样多块磁盘并发写，数据块分布更均匀。路径必须带file://前缀，这是 Hadoop 解析本地路径的标准写法，漏掉会出现Path is not absolute之类的报错。

还有一个很多人忽略的边界：dfs.namenode.name.dir和dfs.datanode.data.dir不能指到同一个父目录。NameNode 格式化时会清空 name 目录内容，如果 data 目录也挂在那里，数据块会跟着被清掉。我在实际项目里见过一次，某次重新格式化后整个 DataNode 数据目录全没了，想恢复只能靠块校验和扫描。

3.3 YARN 的内存参数怎么定

yarn-site.xml管理计算资源。最容易出的问题是yarn.nodemanager.resource.memory-mb设置过大，把系统内存吃干抹净，NodeManager 启动后宿主机开始频繁 swap，容器任务秒挂。这个参数表示单台节点上 YARN 能使用的物理内存总量，而不是你机器的总内存。给出一个 16G 内存机器上的典型配置：

<configuration> <property> <name>yarn.nodemanager.resource.memory-mb</name> <value>12288</value> </property> <property> <name>yarn.scheduler.maximum-allocation-mb</name> <value>4096</value> </property> <property> <name>yarn.nodemanager.pmem-check-enabled</name> <value>true</value> </property> </configuration>

12288是从 16G 里扣掉操作系统、HDFS 常驻内存后剩下的 12G。maximum-allocation-mb是单个容器最多可以请求的内存，默认是 8192，但设成 4096 可以防止单个作业把整台机器的资源独占。pmem-check-enabled控制物理内存超限检查，开发环境可以关掉，生产环境千万别关，否则一个容器写爆内存会牵连同节点所有作业。

3.4 格式化 NameNode 与时序

配置全部改完后，部署顺序是固定的：先格式化 NameNode，再启动 HDFS，再启动 YARN。顺序反了会怎样？你是先启动的 NameNode 进程，它找不到格式化后的元数据目录，会直接失败退出，日志里说NameNode is not formatted。那格式化什么时候执行？只在新集群初始化或元数据全部清空时执行。

# 进入 Hadoop 根目录 cd /opt/hadoop # 生成 NameNode 元数据，同时生成 cluster ID hdfs namenode -format # 启动 HDFS，脚本会按 workers 文件里的地址逐个 SSH 启动 start-dfs.sh # 启动 YARN start-yarn.sh # 查看当前机器上的 Java 进程 jps

正常时jps能看到NameNode、DataNode、SecondaryNameNode、ResourceManager、NodeManager五个进程。少任何一个，去对应的日志目录看日志，而不是反复重启。之后访问http://localhost:9870查看 NameNode 页面，访问http://localhost:8088查看 YARN 集群页面。9870 是 3.x 的默认 Web UI 端口，老教程里的 50070 同样已经不适用。

4. 部署排查手记：格式化丢数据、容器被杀与 Native 库告警

4.1 格式化时报 Unsupported class file major version 61

现象：执行hdfs namenode -format时直接抛出Unsupported class file major version 61，进程退出，格式化失败。

原因：61 对应 JDK 17，Hadoop 3.2.4 的 class 文件是用 JDK 8 目标编译的，主版本是 52。JVM 版本高于编译目标时通常可以运行，但 Hadoop 启动脚本里显式读取了某些内部包的字节码，版本跨度太大会直接拒绝。

解决：卸载或绕过新 JDK，重新装 OpenJDK 8 或 11，修正JAVA_HOME后重新执行格式化。如果系统里已经存在多个 JDK，执行update-alternatives --config java把默认 java 切回 8。这里有个容易迷糊的点：光改JAVA_HOME不够，PATH里的java必须也指向同一版本，否则脚本会按 PATH 顺序找到另一个 JDK 的java命令。

4.2 DataNode 一直不在线

现象：start-dfs.sh执行完后，jps能看到 DataNode 进程，但 9870 页面里Live Nodes为 0，DataNode 日志里反复出现向 NameNode 注册失败的超时记录。

原因：最常见的情况是dfs.datanode.data.dir里的VERSION文件记录的clusterID和 NameNode 元数据里的一致性问题。这个 ID 是在格式化时生成的，如果 data 目录是复制过来的，或者格式化后又清空重建过，ID 就对不上了。

解决：先停掉 HDFS 进程，把/data/hdfs/name和/data/hdfs/data目录里已有的内容清掉，重新执行hdfs namenode -format，再启动。这种情况下不要试图保留原数据，直接重来。生产环境遇到同样的报错，正确做法是把 NameNode 元数据里的clusterID写到 DataNode 的 VERSION 文件里，而不是格式化重来。开发环境数据不重要，格式化最省事。

4.3 YARN 容器被 NodeManager 杀掉

现象：提交一个简单的测试作业，跑了几秒后失败，日志显示Container killed by AppMaster，后面跟着Physical memory usage ... exceeds physical memory limit。

原因：yarn.nodemanager.resource.memory-mb设置得太满，比如 16G 机器设成 16G，系统自身和其他进程没有预留内存。容器实际使用的物理内存加上页缓存，很容易撞到限制，一旦超过pmem-check-enabled就会主动 kill 容器。

解决：把yarn.nodemanager.resource.memory-mb调低，至少留出 2G 给操作系统，同时确认yarn.scheduler.maximum-allocation-mb不大于resource.memory-mb。另外检查/var/log/messages或dmesg，如果存在 OOM Killer 记录，说明宿主机内存真的不够了，需要给节点加内存，而不是继续调参。

4.4 Native 库告警不等于启动失败

现象：每次启动都有WARN util.NativeCodeLoader: Unable to load native-hadoop library for your platform，但 HDFS 和 YARN 都正常起来，任务也能跑。

原因：Hadoop 默认尝试加载本地压缩库，比如 snappy、zstd。系统缺少对应 so 库时，Hadoop 会退回到 Java 实现，功能不缺失但压缩效率下降。

解决：在多数 Linux 发行版上安装libsnappy-dev和libzstd-dev后重启生效。如果还是告警，检查一下 CPU 架构和编译平台的架构是否一致，正好碰到一套 x86 上编出来的包被装到 ARM 机器上时，也会出现完全相同的告警，属于架构不匹配。

5. 多节点扩展：workers 文件、配置同步与一致性检查

5.1 slaves 文件变成了 workers

Hadoop 3.x 起，slaves文件改名成workers，文件位置在etc/hadoop/workers。start-dfs.sh和start-yarn.sh都会读取这个文件来决定在哪些节点上启动 DataNode 和 NodeManager。如果你是按老教程把节点写进slaves，3.2.4 会完全无视它，导致配置了半天就只有本机一个节点上线。

# 在 NameNode 所在机器的 /opt/hadoop/etc/hadoop/workers 里写入 node02 node03

文件内容每行一个主机名，不许有空格和多余回车。主机名必须都能在/etc/hosts或 DNS 里解析，否则 SSH 连接会直接失败。注意workers里不要写本机，脚本会单独处理 NameNode 所在节点，写进去可能导致重复启动 DataNode 进程。

5.2 把配置同步到所有节点

多节点部署时，配置文件必须完全一致。常见做法是先在 NameNode 机器上把三份 XML 和workers文件全部调好，然后逐台分发到其他节点。分发用的是scp，不是重新解压安装包。

# 同步配置文件目录到 node02 scp -r /opt/hadoop/etc/hadoop node02:/opt/hadoop/etc/ # 同步环境变量 scp /etc/profile node02:/etc/profile # 在每个节点上执行 source /etc/profile

同步完之后，要在每个节点上检查一下hadoop-env.sh里的JAVA_HOME是否一致。如果 node02 的 JDK 路径和 node01 不一样，运行时会出现同样的配置、不同的行为。分发配置时可以顺便把hadoop-3.2.4.tar.gz分给大家，也可以只在主节点解压后把整个/opt/hadoop-3.2.4目录scp -r过去，这样二进制保持一致。

多节点集群初始化有一个非常容易翻车的顺序：先启动 DataNode，再格式化 NameNode。如果 DataNode 先启动，它会带着空的 cluster ID 去注册，NameNode 格式化完成后两者 ID 对不上，然后你又要重新清数据目录再格式化。正确顺序始终是先hdfs namenode -format，再执行start-dfs.sh。

5.3 配置不一致的排查手段

集群从 1 台扩到 3 台后，最常见的故障就是某一台配置没同步到。可以用三个命令快速定位：

如果Live datanodes数量不对，先看缺失节点的 DataNode 日志，再看那台机器的core-site.xml是否指向了 NameNode 的 9820 端口。我遇到过一次很隐蔽的情况：node03 的hdfs-site.xml里dfs.datanode.data.dir写错，DataNode 进程看着在跑，但连续半个月没写入任何数据块，界面却不报异常。这种玄学问题唯一的排查办法就是逐台比对配置，别靠肉眼扫，直接diff两边的文件。

6. 收尾：验证集群的三个命令与两个调优习惯

6.1 三个命令验证集群健康度

集群启动后，不要只看进程在不在，三个命令能快速确认数据链路是否完整。第一个是hdfs dfsadmin -report，它会列出所有 DataNode 的容量、剩余空间、已用空间和存活状态，重点看Live datanodes数量是否和节点数一致。第二个是hdfs fsck / -files -blocks -locations，它会扫描整个文件系统，检查所有数据块的副本数。文件系统如果有损坏块或 under-replicated 块，这里会直接打印出来，不需要等作业跑起来才发现。第三个是yarn application -list，它列出 YARN 上正在运行和已经结束的作业，能确认 ResourceManager 和 NodeManager 之间的心跳正常。

# 查看 HDFS 节点状态 hdfs dfsadmin -report # 扫描根目录下所有文件的块状态 hdfs fsck / -files -blocks -locations # 列出 YARN 中的应用 yarn application -list

跑完这三个命令，如果全部正常，基本可以确认部署是健康的。值得说明的是，hdfs fsck不会修复任何东西，它只报告状态，修复需要手动操作，所以在每次格式化后跑一次这个命令，可以提前知道数据块副本情况，避免之后突然发现数据丢了。

6.2 堆内存与临时目录的调优习惯

NameNode 的堆内存是集群稳定性的关键。默认值偏保守，元数据量上来之后容易出现 Full GC。调优时在hadoop-env.sh里设置HADOOP_NAMENODE_OPTS，把堆内存固定下来，避免 JVM 动态扩容带来的停顿：

export HADOOP_NAMENODE_OPTS="-Xms4g -Xmx4g -XX:+UseParallelGC"

-Xms和-Xmx设为相同值，避免运行时扩容；UseParallelGC在元数据量大的场景下表现稳定。堆内存大小一般按每百万文件块约 1G 估算，但不要超过宿主机物理内存的 1/4，留给 DataNode 和 YARN 的空间不能省。

另外，我始终把hadoop.tmp.dir和日志目录当作最容易埋雷的位置。每次改配置或升级版本前，先备份/data/hdfs/name目录，再执行格式化。这个习惯救过我不少次——有一次我改完hdfs-site.xml后重新格式化，忘了备份，元数据直接没了，幸好当时只是测试环境，数据不算关键。从那以后，我每次改完配置都强制自己走一遍“先备份元数据目录、再逐个看日志、最后才并发启服务”的流程，自己格式化的次数少了，帮同事定位的时间也短了。希望帮到你。

本文还有配套的精品资源，点击获取