企业官网建设流程全解析

很多人第一次在 Ubuntu 上搭 Hadoop 集群，最容易踩的坑不是配置文件写错，而是根本不知道每一步为什么要这么做。网上教程一抓一大把，但基本都是照着敲完，start-dfs.sh一执行，要么 NameNode 起不来，要么 DataNode 全没了，然后一脸懵。这篇东西我想换个讲法，把从零到三台机器组成一个最小可用集群的整个过程掰开揉碎，每一步都告诉你背后的逻辑和排查思路，照着做能跑通，出了事也知道去哪儿找原因。

1. 动手之前先砍掉盲目性：版本、节点规划与部署模式

1.1 为什么十个人里有八个搭完就删掉重来

Hadoop 集群搭建是个特别典型的"看似简单、实则琐碎"的活儿。你打开一篇教程，发现步骤就那么几步：装 JDK、配免密、改五个 XML、格式化、启动。于是你觉得这事儿一小时能搞定，结果一动手，先被版本兼容性搞晕了。

Hadoop 的版本选择是第一个坑。目前主流用的是 3.x 系列，但你打开 Apache 官方下载页，会发现有一堆小版本号，比如 3.3.4、3.3.6、3.4.0。千万别顺手拿最新的，一定要先确认两件事：第一，你选的这个版本对应什么 JDK 版本；第二，和你后续要装的其他组件（比如 Spark、Hive）是否兼容。

我自己常用的搭配是 Hadoop 3.3.6 + JDK 8。别用 JDK 17 去跑 Hadoop 3.3.x，虽然能启动，但某些 JVM 参数会报错，比如Unrecognized VM option，到时候排查起来非常烦。Hadoop 3.4 系列理论上支持 JDK 11 和 17，但生态组件的兼容性还没完全跟上，作为学习环境没必要冒险。

下载地址也值得说道说道。Apache 官方的下载页面会把你引导到清华、阿里这些镜像站，选一个离你近的即可。但注意，别下.src.tar.gz源码包，要下hadoop-3.3.6.tar.gz这个二进制包。源码包还需要自己编译，Maven 依赖一堆，纯粹浪费时间。

1.2 单机、伪分布式、真集群到底有什么差别

Hadoop 有三种部署形态，很多人搞不清楚这里面差别有多大。

• 单机模式：默认配置，所有进程跑在一个 JVM 里，不用 HDFS，直接跑本地文件。这是用来跑 MapReduce 调试代码的，不是集群。
• 伪分布式：所有守护进程（NameNode、DataNode、ResourceManager 等）都跑在同一台机器上，但各自是独立 Java 进程，走完整的 HDFS 和 YARN 流程。
• 完全分布式：服务分散在多台机器上，这才是真正的集群。

如果你只是验证配置、跑通流程，伪分布式就够了。但如果你想真正理解集群运维，或者以后要搞真正的多节点环境，那至少要用三台机器做完全分布式。因为三台机器才能完整模拟主节点挂掉、从节点扩容这些真实场景里的操作。

1.3 节点规划表：三台机器怎么分角色

假设我们用三台 Ubuntu 机器，我建议的角色分配如下：

生产环境里 NameNode 和 ResourceManager 一般建议分开，但学习环境放一起完全没问题。SecondaryNameNode 不是 NameNode 的备份，它只是定期拉取 NameNode 的编辑日志做合并，防止日志无限膨胀。很多人以为有了 SecondaryNameNode 就等于有了高可用，这是个非常危险的误解。

内存方面，每台机器至少 2GB 可用内存，主节点建议 4GB。因为 JVM 默认堆设置不小，三个主进程加起来轻松吃掉 1.5GB，内存不够会出现进程反复被杀的情况。硬盘至少留 20GB，HDFS 存储目录挺能吃的。

2. 基础环境：宿主机的 JDK、SSH 与目录规划

2.1 JDK 安装：为什么建议装在固定位置

先在一台机器上把基础环境配好，后面再同步到其他节点。第一步是装 JDK。

Ubuntu 上装 JDK 有几种方式：apt install openjdk-8-jdk、手动解压 Oracle JDK、或者用update-alternatives管理多版本。我推荐手动解压，因为你能精确控制路径，Hadoop 配置文件里要写JAVA_HOME，路径固定会省掉很多后面环境变量相关的破事。

# 以 JDK 8 为例，解压到 /opt/jdk1.8.0_202 sudo mkdir -p /opt/jdk sudo tar -zxf jdk-8u202-linux-x64.tar.gz -C /opt/jdk/ cd /opt/jdk && sudo mv jdk1.8.0_202 jdk8 # 配置环境变量 sudo tee /etc/profile.d/java.sh <<'EOF' export JAVA_HOME=/opt/jdk/jdk8 export PATH=$JAVA_HOME/bin:$PATH EOF source /etc/profile.d/java.sh java -version

为什么要放到/opt而不是/usr/lib/jvm？说实话没强制的理由，但/opt目视上更干净，而且后面给 Hadoop 用的所有第三方软件我都统一放/opt下，找起来一目了然。这个习惯让我在排查环境变量问题时省了不少时间。

2.2 hosts 与机器名：集群内互相认识的唯一方式

Hadoop 集群内部通信靠的是主机名，不是 IP。它会在启动的时候把配置里的主机名解析成 IP，如果解析不对，服务之间根本连不上。

编辑/etc/hostname和/etc/hosts，把三台机器的对应关系写清楚。这一步最容易犯的错误是：只改自己这一台，另外两台没改，然后启动集群的时候发现 DataNode 连不上 NameNode。

# 三台机器都要执行类似的操作，IP 换成你自己的实际地址 sudo tee /etc/hosts <<'EOF' 127.0.0.1 localhost 192.168.1.10 hadoop-master 192.168.1.11 hadoop-node1 192.168.1.12 hadoop-node2 EOF

有个细节：/etc/hosts里的127.0.0.1这一行一定不要加主机名映射。如果你写成127.0.0.1 hadoop-master，那 DataNode 向 NameNode 通信时解析到的是回环地址，从节点永远连不上主节点。这个问题出现的频率比想象中高得多。

2.3 SSH 免密登录：原理和配置一气呵成

Hadoop 的所有守护进程启动时，是通过 SSH 去远程拉起其他节点的进程的。如果每次 SSH 都要输密码，那自动化启动就成了笑话。免密配置的本质，是把你的公钥放到对方的authorized_keys里。

我建议在每台机器上用同一个用户（比如hduser，专门给 Hadoop 用）执行以下操作：

# 创建用户并加入 sudo 组 sudo adduser hduser sudo usermod -aG sudo hduser # 切到 hduser，生成密钥，一路回车即可 su - hduser ssh-keygen -t rsa -b 4096 -N "" -f ~/.ssh/id_rsa # 把公钥复制到三台机器（包括本机） ssh-copy-id hduser@hadoop-master ssh-copy-id hduser@hadoop-node1 ssh-copy-id hduser@hadoop-node2

注意，ssh-copy-id第一次仍然会要求输入密码，这是正常的。完成后测试一下：

ssh hadoop-master hostname ssh hadoop-node1 hostname ssh hadoop-node2 hostname

如果三台都直接返回主机名而不问密码，说明免密已经通了。这里有个容易忽略的点：.ssh目录的权限必须是 700，authorized_keys的权限必须是 600，否则 SSH 出于安全考虑会直接忽略这个文件。我以前就吃过这个亏，配好了免密，结果因为是 644 权限，始终提示要密码。

2.4 Hadoop 目录规划与系统参数

Hadoop 安装目录我放在/opt/hadoop，数据目录单独放/data/hadoop。为什么要单独挂一个数据目录？因为 HDFS 的 NameNode 元数据和 DataNode 数据都是大文件，频繁读写，如果和系统盘混在一起，一方面 IO 会互相干扰，另一方面系统盘满了会导致整个机器卡死。

sudo mkdir -p /opt/hadoop sudo mkdir -p /data/hadoop/namenode sudo mkdir -p /data/hadoop/datanode sudo mkdir -p /data/hadoop/tmp sudo chown -R hduser:hduser /opt/hadoop /data/hadoop

系统参数方面，有一项值得提前改：文件描述符和用户进程数限制。Hadoop 集群跑起来之后，线程数飙升，默认的ulimit -n是 1024，完全不够用。

sudo tee -a /etc/security/limits.conf <<'EOF' hduser soft nofile 65536 hduser hard nofile 65536 hduser soft nproc 65536 hduser hard nproc 65536 EOF

这个配置需要重新登录才生效，验证方法：ulimit -n，看到 65536 就对了。

3. 五个配置文件改完就能跑的完整解读

3.1 core-site.xml：指名门牌号

解压 Hadoop 到/opt/hadoop后，所有配置都在etc/hadoop目录下。先看core-site.xml，这里配的是集群层面的通用属性，最关键的是fs.defaultFS，告诉客户端 HDFS 的入口在哪里。

<?xml version="1.0" encoding="UTF-8"?> <configuration> <property> <name>fs.defaultFS</name> <value>hdfs://hadoop-master:9000</value> </property> <property> <name>hadoop.tmp.dir</name> <value>/data/hadoop/tmp</value> </property> </configuration>

hadoop.tmp.dir一定要改掉默认值。默认它指向/tmp/hadoop-${user}，系统一重启/tmp被清空，NameNode 的元数据就没了，你会看到"NameNode 起不来"的经典故障。这个属性我遇到太多次有人问，每次都是清了/tmp导致的。

3.2 hdfs-site.xml：副本数、元数据路径和 NameNode Web 端口

这个文件里最核心的是三个配置，一个是副本数，一个是 NameNode 元数据的存储位置，还有 NameNode 的 HTTP 访问端口。

<configuration> <property> <name>dfs.replication</name> <value>2</value> </property> <property> <name>dfs.namenode.name.dir</name> <value>file:///data/hadoop/namenode</value> </property> <property> <name>dfs.datanode.data.dir</name> <value>file:///data/hadoop/datanode</value> </property> <property> <name>dfs.namenode.http-address</name> <value>hadoop-master:9870</value> </property> </configuration>

副本数为什么设 2 而不是 3？三台机器，设 3 的话理论上是安全的，但在学习环境里，客户端写入也可能因为机架感知策略出问题，加上每块数据都要写三份，浪费空间。设成 2 已经能容错一台机器挂掉，对于学习足够了。生产环境要根据你的节点数量和数据可靠性要求来，一般建议不低于 2。

dfs.namenode.http-address是 Hadoop 3.x 才有的配置。2.x 时代默认端口是 50070，3.x 改成了 9870。很多人看旧教程，访问 50070 发现什么都没有，就以为是没启动成功，其实是端口变了。

3.3 mapred-site.xml：让 MapReduce 跑在 YARN 上

在 Hadoop 2.x 之前，MapReduce 有自己的一套资源调度机制，叫 MapReduce 1.0。现在肯定全跑在 YARN 上，配置方式是指定一个framework.name。

<configuration> <property> <name>mapreduce.framework.name</name> <value>yarn</value> </property> <property> <name>mapreduce.application.classpath</name> <value>$HADOOP_HOME/share/hadoop/mapreduce/*:$HADOOP_HOME/share/hadoop/mapreduce/lib/*</value> </property> </configuration>

这个文件在 Hadoop 3.x 里默认叫mapred-site.xml，但如果不存在，模板文件是mapred-site.xml.template，需要手动复制一份。很多教程没说这一步，结果跑 WordCount 的时候报ClassNotFoundException，其实就是这个文件没配好。

后来我还加了mapreduce.application.classpath这个属性，是因为 Hadoop 3.x 在某些环境下默认的 classpath 不完整，导致 MR 任务执行时找不到第三方 jar。这个属性让任务运行时把 Hadoop 的库都加进去。

3.4 yarn-site.html：资源调度器的核心

YARN 负责给 MapReduce 作业分配资源和调度，核心配置是 ResourceManager 的地址和调度器插件。

<configuration> <property> <name>yarn.nodemanager.aux-services</name> <value>mapreduce_shuffle</value> </property> <property> <name>yarn.resourcemanager.hostname</name> <value>hadoop-master</value> </property> <property> <name>yarn.nodemanager.vmem-check-enabled</name> <value>false</value> </property> </configuration>

这里有个非常重要的配置：yarn.nodemanager.vmem-check-enabled，默认是 true。它会在 NodeManager 启动容器时检查虚拟内存占用，超过设置上限就杀掉进程。但问题在于，有些作业的虚拟内存使用量会虚高（尤其是跑在 JVM 上的），导致任务莫名其妙被杀。你会发现日志里写着Container killed by ApplicationMaster，但不知道为啥。把这个检查关掉能规避大量这种诡异问题。

mapreduce_shuffle这个辅助服务是必须的，没有它，ReduceTask 从 MapTask 拉取数据时会直接失败。

3.5 workers 文件与 hadoop-env.sh：哪些机器是数据节点

在 Hadoop 3.x 里，列举 DataNode 节点的文件叫workers，在 2.x 里它叫slaves。很多人用 3.x 却按老教程改slaves，自然是不生效的。

workers文件里一行一个机器名，我们把两个数据节点写进去：

hadoop-node1 hadoop-node2

注意，不要写localhost，也不要写主节点。主节点如果要当 DataNode 用，可以单独再配，但学习环境我建议让主节点干净一点，只做主角色。

然后打开hadoop-env.sh，找到JAVA_HOME这一行，把它设成实际的路径。这个文件里的变量是给 Hadoop 启动脚本用的，不设置的话，跑start-dfs.sh时会报找不到 Java。

export JAVA_HOME=/opt/jdk/jdk8 export HADOOP_HOME=/opt/hadoop export PATH=$PATH:$HADOOP_HOME/bin:$HADOOP_HOME/sbin

3.6 把这套配置同步到所有节点

最笨但也最不容易出错的方式，是配好主节点之后，把整个/opt/hadoop目录用rsync推送到其他节点：

rsync -avz /opt/hadoop/ hduser@hadoop-node1:/opt/hadoop/ rsync -avz /opt/hadoop/ hduser@hadoop-node2:/opt/hadoop/

同步完记得把所有节点上的目录权限再确认一遍，然后检查每个节点的/etc/hosts和/etc/hostname是否对得上。这一步往往能提前消灭一半的启动故障。

4. 启动链路：格式化、拉起服务与验证方式

4.1 为什么只能格式化一次

NameNode 的元数据目录在没有格式化的情况下是空的，启动会直接失败。所以第一次启动之前必须执行格式化：

hdfs namenode -format

格式化是在生成一个空的元数据文件系统，同时创建一个current/VERSION文件，里面有集群唯一的namespaceID。这个 ID 会让所有后来注册的 DataNode 验证身份。

这就是为什么只能格式化一次。如果哪天数据节点的进程起不来，你去重新格式化 NameNode，它生成一个新的 namespaceID，老的 DataNode 拿着旧 ID 来注册会被拒绝，集群直接废掉。此时要么格式化所有节点（数据全丢），要么得去改 DataNode 的元数据文件里的集群 ID，非常麻烦。

所以，格式化前想清楚，格式化后别乱动。

4.2 启动脚本实际做了什么

Hadoop 的启动脚本分两个：start-dfs.sh和start-yarn.sh。第一个启动 NameNode 和所有 DataNode，第二个启动 ResourceManager 和所有 NodeManager。

执行：

# 首次启动还要手动记录一下日志位置，方便排查 start-dfs.sh start-yarn.sh

启动脚本会通过 SSH 连接到workers文件里列出的每一台机器，远程启动对应的守护进程。这就是前面免密配置的意义所在。启动过程中如果某台机器连不上，脚本会在那个节点输出 SSH 连接错误，然后继续下一个，最后你可能发现jps看到的进程少了一两个，但脚本本身还显示"启动成功"，因为它只统计了能连上的节点。

因此，启动之后的第一件事，一定是jps检查进程数量，而不是看终端输出。

4.3 用 jps 和 Web UI 确认集群真的活了

jps是 JDK 自带的工具，专门用于查看 Java 进程。三台机器正常的进程列表应该是这样的：

主节点 hadoop-master：

$ jps 3456 NameNode 3678 SecondaryNameNode 3890 ResourceManager 4021 NodeManager

从节点 hadoop-node1 / hadoop-node2：

$ jps 2876 DataNode 3012 NodeManager

jps最大的好处是能看到进程的启动类名，一眼就能对应上几个核心角色。不要用ps -ef | grep java去查，那个会列出所有 Java 进程，包含辅助线程，反而更乱。

确认进程都在之后，打开浏览器访问：

• HDFS 管理页面：http://hadoop-master:9870
• YARN 资源管理页面：http://hadoop-master:8088

在 HDFS 页面里，你应该能看到 Live Nodes 的数量（三台机器可能有 2 或 3 个活节点，取决于你是否让主节点也当 DataNode）。看到Live Nodes: 2就基本说明集群活了。

4.4 用 wordcount 跑通一次完整任务

光看到进程还不够，得跑一个真实任务确认资源调度链路也正常。最快的办法是 Hadoop 自带的 wordcount 示例。

# 先创建输入目录，随便丢几个文件进去 hdfs dfs -mkdir -p /user/hduser/input echo "hello hadoop hello world" | hdfs dfs -put - /user/hduser/input/file1.txt echo "hadoop cluster is running" | hdfs dfs -put - /user/hduser/input/file2.txt # 跑 wordcount hadoop jar /opt/hadoop/share/hadoop/mapreduce/hadoop-mapreduce-examples-3.3.6.jar \ wordcount /user/hduser/input /user/hduser/output # 查看结果 hdfs dfs -cat /user/hduser/output/part-r-00000

如果能看到每个单词的统计结果，说明 HDFS 读写、YARN 调度、MapReduce 执行链路都是通的。这一步做完，集群才算真正可用。

5. 启动失败排查：从日志到端口的定位思路

5.1 最常见的"NameNode 起不来"完整排查链路

坦白讲，我见过最多的集群启动失败案例，都是 NameNode 起不来。症状很统一：执行start-dfs.sh后，jps看不到 NameNode 进程，或者看到进程但 Web UI 打不开。

最忌讳的是一上来就格式化重来。正确的排查链路是这样的：

第一步：看日志。HDFS 的日志在$HADOOP_HOME/logs/目录下，关键文件是hadoop-hduser-namenode-hadoop-master.log。单独启动 NameNode 能看到更直接的控制台输出：

hdfs namenode -format # 如果想看完整输出，可先不放进后台 hdfs namenode

第二步：按日志里的报错分类处理。最常见的原因有几种。

• 找不到数据目录。我之前遇到过java.io.FileNotFoundException: /data/hadoop/namenode，就是目录没创建或者权限不对。检查dfs.namenode.name.dir指定的路径是否存在、属主是否正确。
• unknownhost 错误。java.net.UnknownHostException: hadoop-master，说明/etc/hosts里没有对应的解析记录，或者你写的机器名和实际不一样。
• 元数据不一致。日志里会出现EDITS_xxx is not a file之类的提示，通常是之前格式化过不止一次，或者非正常关闭导致 edit log 损坏。此时要检查dfs.namenode.name.dir下的current目录里edits_*文件的状态。

第三步：端口占用。NameNode 默认要监听 9000 和 9870 两个端口，如果机器上之前装过其他用了这些端口的服务，进程也会启动失败。用netstat -tlnp | grep 9000查看。

5.2 SSH 免密失效的隐藏原因

启动脚本显示连接某些节点失败，但前面明明测试过免密是通的，这种情况也很常见。隐藏原因往往是用户环境变了。

比如你是用sudo -s切到 root 再执行start-dfs.sh的，那 SSH 会以 root 用户的身份去连接其他机器，用的也是 root 的~/.ssh，而你没有给 root 配免密。所以启动脚本一定要用你配免密的那个用户（比如hduser）来执行。

还有一种情况是机器重启后/etc/hosts被 DHCP 或 cloud-init 重写了，主机名解析断了。我们实验环境的静态 IP 和 hosts 配置要注意固化，而不是依赖 DHCP。

5.3 磁盘、内存等资源的隐形炸弹

集群进程都起来了，但一跑任务就失败，这种问题往往不在 Hadoop 本身，而在系统资源。

内存方面，每台机器至少 2GB。你可以用free -h看，如果可用内存长期在 200MB 以下，就说明资源紧张。NodeManager 发起的容器进程经常被 OOM killer 杀掉，日志里特性表现为"进程退出码 137"。

磁盘方面，DataNode 数据目录满了也会出问题。HDFS 写入数据时，DataNode 会先落到本地磁盘，磁盘满了块上报就会失败，集群状态里某些节点会变成异常。我建议节点磁盘使用率超过 85% 就要注意清理。

5.4 DataNode 数量为 0 的经典原因

启动完start-dfs.sh，在 9870 端口页面看到 Live Nodes 是 0，这算是新手的第二个经典故障。

除了上面说的 hosts 问题，还有一个隐蔽情况：DataNode 注册时用的机器名和 NameNode 解析的机器名不一致。比如你workers文件里写的是hadoop-node1，但hadoop-node1这台机器的/etc/hosts里没有配置自己的名字到 IP 的映射，HDFS 协议里它会拿着自己的 hostname 去和 NameNode 比对，两边对不上就直接拒绝。

排查方式是看 DataNode 日志：

tail -100 $HADOOP_HOME/logs/hadoop-hduser-datanode-hadoop-node1.log

如果看到Block pool ID needed或者namenode in safemode，那大概率是元数据不一致或 NameNode 还在安全模式里。安全模式时，dfsadmin -safemode leave可以手动退出。但更常见的其实是集群 ID 不一致，比较一下 NameNode 和 DataNode 的current/VERSION文件里的clusterID是否一致，不一致就改成一模一样的再重启 DataNode。

6. 跑通之后一定要做的几件事

集群跑通了不代表万事大吉，有几件事必须在正式使用之前做好，否则后面一定后悔。

6.1 立刻做一次所有权和数据目录的备份记录

第一次格式化生成的 namespaceID 和 clusterID，这些元数据是集群的"身份证"，建议写进一个文本文件存起来。如果真的遇到不可逆的损坏，你可以从记录里找回这些 ID，尝试手工恢复。

6.2 打开 HDFS 的回收站

HDFS 删除文件是直接清掉的，没有回收站概念。误删一个目录，如果副本数不够，数据就彻底没了。好在 Hadoop 3.x 有fs.trash.interval这个配置，可以在core-site.xml里加上：

<property> <name>fs.trash.interval</name> <value>1440</value> </property>

这个值是分钟数，1440 就是保留一天。设完之后，hdfs dfs -rm删除的文件会先进到/user/<用户名>/.Trash/目录里，一天后才会真正清掉。

6.3 理解安全模式，不要乱点

NameNode 启动时会进入安全模式，在这个状态下，HDFS 只接受读操作，不接受写操作。有些人看到 Web UI 上写着 Safemode 就紧张，其实这是正常流程：NameNode 在加载元数据并等待 DataNode 上报数据块，等汇报的块达到阈值后自动退出。

真正要担心的是安全模式卡住不退。那一般是数据块缺失太多，NameNode 认为文件系统损坏。此时不要勉强手动退出，而是先修复缺失的块，否则文件处于"看起来在但读不出来"的状态，风险更大。

6.4 加一个集群启停的小脚本

每次start-dfs.sh和start-yarn.sh分开敲有点烦，我习惯写一个简单的管理脚本丢到/usr/local/bin里：

#!/bin/bash # Hadoop 集群一键启停脚本 start() { su - hduser -c "start-dfs.sh" su - hduser -c "start-yarn.sh" echo "Hadoop cluster started." } stop() { su - hduser -c "stop-yarn.sh" su - hduser -c "stop-dfs.sh" echo "Hadoop cluster stopped." } status() { echo "===== NameNode =====" ssh -o ConnectTimeout=3 hadoop-master "jps | grep NameNode" echo "===== DataNode =====" for h in hadoop-node1 hadoop-node2; do echo "--- $h ---" ssh -o ConnectTimeout=3 $h "jps | grep DataNode" done } case "$1" in start) start ;; stop) stop ;; status) status ;; *) echo "Usage: $0 {start|stop|status}"; exit 1 ;; esac

把这个脚本加进 alias 之后，日常管理集群就是一个命令的事。而且它强制了每次都用正确的用户去执行，避免前面提到的 root 免密问题。

集群搭起来只是大数据学习的第一步，后面还有 HDFS 机制调优、YARN 队列配置、Spark 上跑任务这些更进阶的东西等着去折腾。但只要你把基础理解和排查手段立住了，踩坑的时候就知道往哪看、去哪找原因，这套能力比任何一份配置都值钱。