简介：Hadoop 3.3.6 二进制安装包（hadoop-3.3.6.tar.gz）是由阿帕奇软件基金会开发的分布式系统基础架构，面向需要进行海量数据存储与分布式计算的技术人员，尤适用于搭建大数据实验环境或生产集群，解压后即可安装配置。整个安装包体积约六百九十六兆字节，共包含约两千个文件，其中网页帮助文档、程序依赖库、页面样式表、配置文件、启动脚本与示例代码占比最高，能够为安装部署、功能查阅与二次开发提供完整支撑。该版本集成分布式文件系统、资源调度模块与并行计算框架等核心组件，同时提供完善的默认配置、管理脚本及示例任务，配合内置的配置模板和示例程序，能够显著降低环境搭建门槛，帮助使用者快速掌握大数据平台的基础运维与任务提交。目前该安装包已有超过一千三百人学习或下载，下载后即可在单机或多节点集群模式下运行，覆盖存储、调度、计算三大环节，既能用于课程实验与技能练习，也能作为生产部署的初始版本，便于结合官方文档进行配置与调优。
1. 拿到 hadoop-3.3.6.tar.gz：这一个包解决什么问题
hadoop-3.3.6.tar.gz 是 Hadoop 3.3.6 的 Linux 二进制发行包，把这个包解压、配好环境变量和四份核心 XML，你就能在本地把 HDFS 和 YARN 拉起来跑真实作业。很多人以为下载解压就等于安装完成，实际上下载是最简单的一步，真正决定成败的是解压之后的 JDK 版本、目录隔离、配置文件的数值和一次格式化。这篇笔记覆盖从下载校验、伪分布式落地、分布式扩展、启动排错到最终验证的完整路径，适合第一次在 Linux 上部署 Hadoop 的开发者，也适合想从单机转三节点集群的运维同学，照着复现大约一小时能把最小可用集群跑通。
2. 安装前四步：JDK 版本锁死、下载校验、目录规划与用户隔离
2.1 JDK 先落位：版本选型与一条命令确认
Hadoop 3.3.6 官方支持 Java 8 和 Java 11，两个版本都能跑。实际部署时我一般建议新环境直接用 OpenJDK 8，原因不是 Java 11 不行，而是存量 Hadoop 生态组件（Hive、Spark、HBase 的某些版本）对 Java 8 的兼容验证更充分，遇到问题更容易在网上找到同类排查记录。如果你后续要跑较新的 Spark 版本，再考虑 Java 11，但同一套 Hadoop 不要混用 JDK 版本，NameNode 和 DataNode 的 Java 版本不一致会引入一些非常难查的 RPC 序列化问题。
先确认当前机器上有没有 JDK，而不是只装了 JRE。Hadoop 的启动脚本在 JDK 8 下会用到tools.jar，只装 JRE 的话 NameNode 会直接报错，这一步很多人踩过。执行下面两条命令：
java -version which javacjava -version输出里带有OpenJDK 64-Bit Server VM并且which javac能打印出路径，说明是完整 JDK。如果只有java没有javac，请先安装 JDK 而不是继续往下走。Debian/Ubuntu 系的安装命令是apt install openjdk-8-jdk-headless，CentOS/RHEL 系是yum install java-1.8.0-openjdk-devel。安装完再执行readlink -f $(which javac)，拿到的真实路径就是要写进配置的JAVA_HOME。
这里有个关键点：很多教程让你在.bashrc里写export JAVA_HOME=/usr/lib/jvm/...，但 Hadoop 的守护进程是独立启动的，不一定会读你的.bashrc。真正可靠的做法是安装完后把JAVA_HOME用绝对路径写进$HADOOP_HOME/etc/hadoop/hadoop-env.sh，这个文件会在启动每个守护进程前被加载，后面第 3 章会写到。现在先把 JDK 装好、版本记牢，不要急着配置 Hadoop。
2.2 下载与校验：让安装包先证明自己是完整的
Hadoop 的官方发行包托管在 Apache 软件基金会的归档站点上，建议直接从archive.apache.org的common目录进入对应版本所在页面下载，不要随便从第三方博客给的链接拉包。下载前确认清楚两件事：文件后缀必须是.tar.gz，版本号是3.3.6。这个体积不小，命令行下载比浏览器稳定，断点续传也更可控：
mkdir -p /opt/src && cd /opt/src DOWNLOAD_BASE=https://archive.apache.org/dist/hadoop/common wget $DOWNLOAD_BASE/hadoop-3.3.6/hadoop-3.3.6.tar.gz wget $DOWNLOAD_BASE/hadoop-3.3.6/hadoop-3.3.6.tar.gz.sha512下载完成后先做 SHA-512 校验，确保包在传输过程中没有损坏。这一步很多人跳过，但 tar 包如果损坏，解压时不一定报错，等到启动阶段出现奇怪的ClassNotFoundException或Segmentation fault再去排查就非常被动了：
sha512sum hadoop-3.3.6.tar.gz cat hadoop-3.3.6.tar.gz.sha512对比两个输出是否一致。sha512sum默认打印的一长串十六进制和.sha512文件里的内容完全相同时再继续。不一致就重下，别心存侥幸。校验通过后把包移动到软件安装目录的父目录，我一般放在/opt下，避免放在/home里因为家目录权限或者磁盘配额问题导致解压失败。
2.3 用户、目录与免密：安装之前先把家收拾好
不要用root账号直接跑 Hadoop 集群，这是一条我踩过硬坑的规则。Hadoop 的 Web 界面和 YARN 的容器执行涉及大量文件权限判断，用 root 跑会出现一些诡异的行为，比如 DataNode 报权限错、NodeManager 本地目录无法清理。生产环境通常的做法是创建一个专用系统账号，名字随意，常见的是hduser或者hadoop：
useradd -m -s /bin/bash hadoop passwd hadoop mkdir -p /opt/hadoop /data/hdfs/name /data/hdfs/data /data/hdfs/tmp chown -R hadoop:hadoop /opt/hadoop /data/hdfs目录规划这里有个容易忽略的设计：软件目录和数据目录要分开，数据目录不要放在系统盘上。NameNode 的name目录存放 fsimage 和 edits 日志，DataNode 的data目录存放实际的文件块，这两类目录最好落在不同磁盘或者不同挂载点，避免元数据和数据同时被一次磁盘故障带走。伪分布式阶段虽然只有一个节点，但目录结构按生产习惯建好，后面扩容集群时不需要推倒重来。
最后配置 SSH 免密。Hadoop 的启动脚本start-dfs.sh会通过 SSH 连接到每一台 worker 机器去拉起 DataNode 进程，即使伪分布式也至少需要能免密登录localhost。用hadoop用户执行：
ssh-keygen -t rsa -b 4096 -N "" -f ~/.ssh/id_rsa cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys ssh localhost能直接出现 shell 提示符而不询问密码，就算通过了。很多新手在解压 Hadoop 之后才去折腾 SSH，结果发现启动脚本一直卡在密码输入上，把这一步放在安装前会省很多事。
3. 伪分布式最小落地：四份配置文件、一次格式化、一列启动命令
3.1 解压与环境变量：把 HADOOP_HOME 写进 .bashrc
切换到hadoop用户，解压安装包到/opt目录。解压后默认目录名是hadoop-3.3.6，我习惯再建一个不带版本的软链，这样以后升级版本时只需要改软链指向，不用改一堆脚本里的路径：
cd /opt tar -zxvf /opt/src/hadoop-3.3.6.tar.gz ln -s /opt/hadoop-3.3.6 /opt/hadoop chown -h hadoop:hadoop /opt/hadoop echo "export HADOOP_HOME=/opt/hadoop" >> ~/.bashrc echo "export HADOOP_CONF_DIR=$HADOOP_HOME/etc/hadoop" >> ~/.bashrc echo "export PATH=$PATH:$HADOOP_HOME/bin:$HADOOP_HOME/sbin" >> ~/.bashrcHADOOP_HOME是 Hadoop 自身定位安装目录的基准，所有脚本都依赖它；HADOOP_CONF_DIR指向配置文件所在目录，单独列出来是为了方便后续用不同配置目录做多环境切换；PATH 里加bin是为了直接用hdfs、yarn这些命令，加sbin是为了用start-dfs.sh这些启停脚本。
执行source ~/.bashrc后跑一下hadoop version，能看到Hadoop 3.3.6字样说明环境变量生效。然后打开$HADOOP_HOME/etc/hadoop/hadoop-env.sh，找到JAVA_HOME那一行，把注释去掉并改成第 2 章确认好的绝对路径。这是整个安装过程中最容易被跳过的文件配置，跳过的后果是启动时 Hadoop 按自己的猜测去找 Java，十次有九次找不到。
3.2 四份 XML 配置：伪分布式的最小可跑参数
伪分布式的核心就是四份配置文件，全部放在$HADOOP_HOME/etc/hadoop/下。先看core-site.xml，它定义的是集群级别的通用属性，最重要的就是 NameNode 的地址：
<configuration> <property> <name>fs.defaultFS</name> <value>hdfs://localhost:9000</value> </property> <property> <name>hadoop.tmp.dir</name> <value>/data/hdfs/tmp</value> </property> </configuration>fs.defaultFS是所有客户端访问 HDFS 的入口，伪分布式写成localhost:9000，9000 是 NameNode 的 RPC 端口。hadoop.tmp.dir如果不显式指定，默认落在/tmp目录下，系统一重启临时文件被清掉，NameNode 再启动时会发现元数据丢了，直接用/data/hdfs/tmp是长久的做法。
然后是hdfs-site.xml，这里配置的是 HDFS 自身的行为：
<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.replication在伪分布式下必须设成 1，因为只有一个 DataNode，副本数设 3 的话文件会一直处于 under-replicated 状态，Web 界面上健康度永远不是 100%。dfs.namenode.name.dir和dfs.datanode.data.dir是数据目录的显式声明，注意前面要加file://前缀，这个写法容易被漏掉，漏掉后配置不生效，DataNode 还是会去默认路径创建数据目录。
接下来两份文件决定计算框架怎么跑。mapred-site.xml指定 MapReduce 运行在 YARN 之上：
<configuration> <property> <name>mapreduce.framework.name</name> <value>yarn</value> </property> </configuration>yarn-site.xml里最关键的是 NodeManager 的辅助服务，MapReduce 的 shuffle 阶段要靠这个服务传输 map 输出数据，少配了作业会一直卡住不动：
<configuration> <property> <name>yarn.nodemanager.aux-services</name> <value>mapreduce_shuffle</value> </property> <property> <name>yarn.nodemanager.aux-services.mapreduce_shuffle.class</name> <value>org.apache.hadoop.mapred.ShuffleHandler</value> </property> </configuration>很多教程只写了第一行，第二行不写，结果作业提交后进度条停在map 100% reduce 0%，日志里报 shuffle 连接失败。aux-services只是启用了服务名字，真正的实现类要靠第二行指定，两者是一对的。这四份文件改完后可以再回头检查一遍，特别是标签闭合和属性名拼写，XML 里拼错属性名 Hadoop 不会报错，只是安静地忽略掉这一项，排查起来非常折磨人。
3.3 格式化与一次启动：验证 HDFS 和 YARN 的关键命令
配置完成后第一步是格式化 NameNode。格式化做的事情是生成集群的唯一标识clusterID和初始的 fsimage 元数据文件，这是所有后续启动的前提：
hdfs namenode -format看到输出里出现Storage directory file:/data/hdfs/name has been successfully formatted才算成功。这里有一个必须记住的铁律：格式化操作只在两种情况下执行——第一次部署，或者你明确要放弃所有数据重来。同一个集群不要重复格式化，重复格式化会让新生成的clusterID和 DataNode 数据目录里的旧clusterID不一致，导致 DataNode 全部启动失败，这个坑在第 5 章会展开讲。
格式化完成后分两步启动进程，先启动 HDFS，再启动 YARN：
start-dfs.sh start-yarn.sh启动脚本会打出一串日志，看到Starting namenodes on [localhost]以及Starting datanodes说明脚本流程正常。不要用start-all.sh，虽然 3.3.6 里这个命令还存在，但它把两套日志混在一起，启动失败时不方便定位是哪一层出的问题。
用jps查看 Java 进程，这是验证启动结果最快的方式：
jps伪分布式正常时能看到 5 个进程：NameNode、SecondaryNameNode、DataNode、ResourceManager、NodeManager。缺哪个就去看$HADOOP_HOME/logs/下面对应的日志文件，比如缺NameNode就看hadoop-hadoop-namenode-主机名.log。少任何一个进程都不要继续，先解决掉再往下走。
启动完成后接着验证 Web 界面。HDFS 的 NameNode UI 在http://localhost:9870，YARN 的 ResourceManager UI 在http://localhost:8088。两个页面能打开后，用一条命令确认 HDFS 真实可写：
hdfs dfs -mkdir -p /user/hadoop hdfs dfs -put /etc/hosts /user/hadoop/ hdfs dfs -ls /user/hadoop/能看到hosts文件出现在输出列表里，伪分布式的最小集群就算真正跑通了。做到这一步，Hadoop 3.3.6 已经从「一个 tar.gz 包」变成了「一套能用的系统」。
4. 从单机到集群：把伪分布式配置改成三节点分布式
4.1 集群规划：角色拆分、主机名与端口约定
伪分布式跑通之后，绝大多数人下一步就是扩成真正的集群。先把角色拆清楚：HDFS 里有 NameNode 负责元数据、DataNode 负责数据块，YARN 里有 ResourceManager 负责全局资源调度、NodeManager 负责单机资源。三节点最小集群的常见分配是：第一个节点部署 NameNode、SecondaryNameNode、ResourceManager，另外两个节点只部署 DataNode 和 NodeManager。
规划时先约定主机名。在/etc/hosts里把三台机器的内网 IP 和主机名对应好，这个文件必须三台完全一致，否则节点之间通过主机名互相访问时会解析出问题。集群规模小的时候不建议用 DNS，直接维护 hosts 更直观，改动也更容易控制。
节点角色对照表：
| 节点 | 角色 | 主要进程 |
|---|---|---|
| node1 | 主节点 | NameNode、SecondaryNameNode、ResourceManager |
| node2 | 工作节点 | DataNode、NodeManager |
| node3 | 工作节点 | DataNode、NodeManager |
HDFS RPC 端口保持 9000，NameNode Web 端口 9870，ResourceManager Web 端口 8088。这三个端口在规划时要确保不和其他服务冲突，特别是机器上如果已经跑了别的 Java 服务，端口复用会导致进程起不来但日志里又看不出明显异常。
4.2 配置改写：从 localhost 到主机名的四处关键变更
从伪分布式改成分布式，四份配置文件里需要改动的地方不多，但每一处都要准确。最重要的变化是fs.defaultFS从localhost:9000改成hdfs://node1:9000，这样所有客户端和 DataNode 都会通过主机名去找 NameNode。如果继续写localhost，每个节点都会去找自己本机的 9000 端口，集群直接分成三个互不相识的独立伪分布式。
yarn-site.xml里需要增加 ResourceManager 的地址声明，让 NodeManager 知道向谁注册：
<configuration> <property> <name>yarn.resourcemanager.hostname</name> <value>node1</value> </property> <property> <name>yarn.nodemanager.aux-services</name> <value>mapreduce_shuffle</value> </property> <property> <name>yarn.nodemanager.aux-services.mapreduce_shuffle.class</name> <value>org.apache.hadoop.mapred.ShuffleHandler</value> </property> <property> <name>yarn.nodemanager.local-dirs</name> <value>/data/hdfs/nm-local</value> </property> </configuration>yarn.nodemanager.local-dirs指定 NodeManager 存放 shuffle 中间数据和容器运行文件的目录，伪分布式阶段可以不写，集群阶段建议显式配置到独立数据盘，避免默认落在/tmp被系统清理。hdfs-site.xml里dfs.replication要改成 3，对应三个数据节点各存一份副本，同时把dfs.namenode.secondary.http.address明确指向node1:9868，这是 SecondaryNameNode 拉取镜像的通道。
还有一个很容易漏掉的文件：etc/hadoop/workers，3.x 版本里叫这个名字，2.x 时代叫slaves。这个文件告诉启动脚本应该去哪些机器上拉起 DataNode 和 NodeManager：
node2 node3如果 node1 也想承担数据节点角色，可以加进去，但生产习惯一般不这么做。NameNode 所在的机器专职负责元数据，数据读写压力全部交给工作节点。
4.3 同步与首次启动：格式化的顺序决定成败
配置文件改完后，把整个 Hadoop 目录同步到工作节点。关键是要排除日志和数据目录，这些必须在各节点本地生成，不能从主节点拷贝：
for host in node2 node3; do rsync -av --exclude 'logs' --exclude '/data/hdfs' /opt/hadoop-3.3.6/ $host:/opt/hadoop-3.3.6/ done三台机器的/opt/hadoop软链也要保持一致。同步完成后，确保每台机器上hadoop version都能正常输出，并且/data/hdfs/目录归属hadoop用户，权限正确。
集群首次启动时，格式化只在 node1 上执行且只执行一次。因为格式化的本质是给整个集群生成身份标识，工作节点的 DataNode 会自动从 NameNode 获取clusterID，不需要也不应该在 node2、node3 上执行格式化。在 node1 上执行完hdfs namenode -format后，直接启动：
start-dfs.sh start-yarn.sh启动脚本会读取workers文件，通过 SSH 依次登录 node2、node3 拉起对应进程。此时去任意一个工作节点上执行jps，应该能看到DataNode和NodeManager。最后回到 node1 执行以下命令确认集群规模：
hdfs dfsadmin -report yarn node -list -alldfsadmin -report输出里会列出活着的 DataNode 数量，yarn node -list能看到注册的 NodeManager 列表。两个命令都显示正常，说明三节点集群已经建立。此时在 Web 界面上看，HDFS 健康度应该接近 100%，因为副本数 3 正好匹配三个数据节点。
5. hadoop 3.3.6 安装避坑：五条高频翻车记录与修复
5.1 NameNode 反复重启却起不来：日志写着 JAVA_HOME is not set
现象：start-dfs.sh执行后没有任何报错，但jps里始终没有NameNode。打开日志文件，开头几行就是Error: JAVA_HOME is not set。
原因：.bashrc里配了JAVA_HOME，但 Hadoop 的守护进程不是交互式的 shell，启动脚本由sbin/hadoop-daemon.sh拉起，这个脚本不会读取用户 shell 的环境变量。
解决：直接编辑$HADOOP_HOME/etc/hadoop/hadoop-env.sh，把文件里的JAVA_HOME行改成绝对路径：
export JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk-amd64改完重新执行start-dfs.sh。这里用绝对路径是关键，不要写export JAVA_HOME=$(readlink -f /usr/bin/java)这种动态推断，每个节点上执行环境不一样，静态路径最稳。
5.2 第二次格式化后 DataNode 全挂：Incompatible clusterIDs
现象：集群运行一段时间后，重新执行了hdfs namenode -format，随后所有 DataNode 启动失败，日志里报Incompatible clusterIDs in /data/hdfs/data。
原因：格式化会为 NameNode 生成新的clusterID，但 DataNode 数据目录里的VERSION文件还保留着旧的clusterID。DataNode 启动时发现两边对不上，直接拒绝注册。
解决：如果数据不重要，清空 DataNode 数据目录后重新格式化即可。如果数据还在，把VERSION文件里的clusterID改成新的一致值再重启，路径在/data/hdfs/data/current/VERSION。以后记住一个习惯：namenode -format只在新集群或者明确要丢掉所有数据时执行，日常运维永远不要碰它。
5.3 浏览器打不开 9870 页面，但本机 curl 是通的
现象：HDFS Web 界面在服务器本机curl http://localhost:9870有返回，但在自己电脑的浏览器里输入服务器 IP 加端口打不开。
原因：服务本身是正常的，问题出在操作系统防火墙。常见的 Linux 发行版默认开启了firewalld或ufw，对外部访问的端口做了拦截。
解决：在服务器上为以下端口放行，然后重新加载防火墙规则：
firewall-cmd --permanent --add-port=9870/tcp firewall-cmd --permanent --add-port=8088/tcp firewall-cmd --permanent --add-port=9000/tcp firewall-cmd --reload需要说明的是，这只适用于内网开发环境。生产集群不要把 9870 和 8088 直接暴露到公网，这两个管理界面没有完整的认证授权机制，暴露出去等于把集群敞开门给别人。
5.4 伪分布式下健康度不是 100%：Under-replicated blocks 一直存在
现象：单节点部署后往 HDFS 里传文件，Web 界面显示Under-replicated blocks数量不为 0，即使等很久副本数也不上升。
原因：dfs.replication默认值是 3，伪分布式只有 1 个 DataNode，系统永远无法凑齐 3 份副本，健康度自然到不了 100%。
解决：伪分布式阶段把dfs.replication改为 1。如果改之前已经传过文件，需要用setrep命令修正已有文件的副本数：
hdfs dfs -setrep -R -w 1 /user/hadoop-R表示递归处理整个目录，-w表示等待副本调整完成。改成 1 之后，界面健康度会恢复。
5.5 ResourceManager 活着，但 YARN 界面看不到 NodeManager
现象：jps显示 ResourceManager 和 NodeManager 都在运行，但 8088 页面里 NodeManager 列表为空，状态一直是连接中。
原因：NodeManager 向 ResourceManager 注册时用的主机名解析出了问题。最常见的是工作节点/etc/hosts把自己的主机名解析到了127.0.0.1，导致 ResourceManager 看到的地址不可路由。
解决：确保三台机器的/etc/hosts里，主机名对应的都是实际内网 IP，而不是127.0.1.1或localhost。修改后重启 YARN 的进程才能生效：
stop-yarn.sh start-yarn.sh这条坑在分布式搭建里出现频率很高，而且日志里不会直接报错，只能靠比对/etc/hosts排查。
6. 启动后验证三步走，并把它用成一门手艺
集群启动后，我习惯用三组命令做最终验收，而不是只靠jps看进程活着就算完。第一步用hdfs dfsadmin -report看集群容量和存活节点，输出里Live datanodes的数量必须和规划一致，同时确认Configured Capacity不等于 0，如果容量显示 0，说明 DataNode 的数据目录权限或者挂载有问题，后面写数据一定失败。
第二步验证 HDFS 真实读写链路。创建一个测试目录，把一个稍大的文件传上去再读下来，单纯put成功不代表数据块分配正确，从 HDFS 读回本地才能确认数据完整性：
hdfs dfs -mkdir -p /tmp/verify hdfs dfs -put /opt/hadoop-3.3.6/README.txt /tmp/verify/ hdfs dfs -cat /tmp/verify/README.txt | head -20 hdfs dfs -rm -r /tmp/verify第三步验证 YARN 的计算链路是否完整，这一步能暴露 shuffle 配置是否生效。用自带示例跑一个 MapReduce 任务，是最省事的压测方式：
hadoop jar $HADOOP_HOME/share/hadoop/mapreduce/hadoop-mapreduce-examples-3.3.6.jar pi 4 100看到作业状态变成Job Completed successfully并输出Estimated value of Pi，说明从资源调度、容器分配到 shuffle 传输全部正常。如果这一步失败，优先查yarn-site.xml的辅助服务配置和 NodeManager 的本地目录，这两个是高频故障点。
我自己的习惯是每次改完配置都先把整个etc/hadoop目录备份一份，启动异常时对照备份快速确认改坏了什么，而不是盯着日志猜。格式化之前再三确认数据目录路径，这是用一次数据找回的代价换回来的教训。希望帮到你。
本文还有配套的精品资源，点击获取
