1. 为什么要在Linux上折腾Hadoop开发环境
刚接触大数据那会儿，我也觉得搭个Hadoop环境能有多难，不就是解压几个压缩包、改几个配置文件的事。结果第一次动手就卡了整整两天，从虚拟机网络配不通，到NameNode死活起不来，再到DataNode莫名其妙掉线，每一步都是坑。后来带过几个新人，发现大家踩的坑几乎一模一样，所以干脆把这套流程完整梳理一遍，把那些文档里不会写的细节全抖出来。
Hadoop这套东西，本质上是一个分布式存储加分布式计算的框架。它的核心设计思想特别朴素：用一堆普通机器堆出超强的存储和计算能力。HDFS负责把文件切成块分散存到不同机器上，MapReduce负责把计算任务拆开跑在不同机器上。听起来简单，但真要在本地搭一套能跑起来的开发环境，涉及的东西一点不少——Java环境、SSH免密、核心配置文件、目录结构、启动脚本，每一环出问题都会让你卡住。
这篇文章面向的是准备在Linux上搭建Hadoop开发环境的朋友，不管你是刚入门大数据的学生，还是从后端转过来的开发者，只要跟着走，基本能避开我当年踩过的那些坑。我会从零开始，把每一步的操作、背后的原因、可能遇到的问题和排查方法都讲清楚。环境搭好之后，你就能在本地跑MapReduce任务、调试HDFS操作，为后续学习Hive、HBase、Spark这些上层组件打好地基。
需要提前说明的是，我用的方案是单机伪分布式模式。也就是说，在一台Linux机器上模拟出多节点的效果，NameNode、DataNode、ResourceManager、NodeManager都跑在同一台机器上，但各自是独立的Java进程。这种模式最适合开发调试，资源占用可控，配置逻辑和真正的分布式集群几乎一致，学会了之后扩展到多台机器只是改几个地址的事。
2. 搭建前的整体规划与方案选型
2.1 为什么选伪分布式而不是单机模式
Hadoop的运行模式有三种：本地模式、伪分布式、完全分布式。本地模式压根不用HDFS，直接读写本地文件系统，拿来跑个WordCount测试还行，但根本体会不到分布式的任何特性。完全分布式需要至少三台机器，对个人开发者来说成本太高，调试也麻烦。伪分布式是折中方案，所有守护进程跑在一台机器上，但用的是真实的HDFS和YARN机制，你能看到NameNode的Web界面、能观察DataNode的块存储、能提交任务到YARN上调度。开发阶段用这个模式，性价比最高。
2.2 版本选择的考量
Hadoop版本迭代挺快，目前主流稳定版是3.x系列。2.x和3.x在架构上有一些差异，比如3.x引入了YARN的更多调度特性、支持Erasure Coding、默认端口也有调整。我建议直接用3.3.x或3.4.x的稳定版，避免用太老的2.7、2.8，那些版本在新版Linux上兼容性会有问题。JDK方面，Hadoop 3.x官方推荐JDK 8，虽然JDK 11也能跑，但某些脚本里的反射调用会报警告，新手容易被吓到，所以稳妥起见用JDK 8。
2.3 操作系统与硬件要求
Linux发行版选CentOS 7或者Ubuntu 20.04以上都行，我用的是CentOS 7.9，主要是资料多、踩坑记录全。内存建议至少4GB，因为NameNode、DataNode、ResourceManager、NodeManager四个进程加起来差不多要占2GB左右，再加上系统本身的开销，2GB的机器会非常卡。磁盘留出20GB以上，HDFS的存储目录、临时目录、日志目录都需要空间。CPU双核就够了，伪分布式对计算能力要求不高。
2.4 网络与主机名配置
这一步很多人会忽略，但特别重要。Hadoop的配置文件里到处都要写主机名，如果主机名解析有问题，启动时就会报UnknownHostException。我的做法是：先给机器设一个固定的主机名，比如hadoop-dev，然后在/etc/hosts里加上127.0.0.1 hadoop-dev的映射。这样不管网络怎么变，本机解析都不会出问题。如果你用的是虚拟机，记得把网络模式设成NAT或者桥接，确保虚拟机有独立的IP地址，不要用动态分配，否则每次重启IP变了，配置也得跟着改。
3. 基础环境准备与系统调优
3.1 JDK安装与环境变量配置
Hadoop是用Java写的，没有JDK什么都跑不起来。我习惯用tar包手动安装，不用yum，因为yum装的JDK路径太深，配置起来麻烦。具体操作是：把JDK压缩包解压到/usr/local/目录下，然后重命名成jdk8，这样路径就是/usr/local/jdk8，干净利落。
配置环境变量的时候，我建议在/etc/profile.d/目录下单独建一个hadoop-env.sh文件，而不是直接改/etc/profile。这样做的好处是配置模块化，以后要删要改都方便。文件内容大概是这样：
export JAVA_HOME=/usr/local/jdk8 export HADOOP_HOME=/usr/local/hadoop export PATH=$PATH:$JAVA_HOME/bin:$HADOOP_HOME/bin:$HADOOP_HOME/sbin写完记得source一下让它生效，然后用java -version验证。这里有个小细节：java -version的输出是打到标准错误流里的，如果你用脚本去抓取版本号，得用2>&1重定向，不然抓不到。
3.2 SSH免密登录配置
Hadoop的启动脚本依赖SSH来批量启动各个节点上的守护进程，即使是伪分布式，它也会通过SSH连到本机来启动进程。如果不配免密，每次启动都要输密码，脚本会卡住。配置方法是：先用ssh-keygen -t rsa生成密钥对，一路回车就行，然后ssh-copy-id localhost把公钥拷到本机的授权文件里。做完之后ssh localhost应该能直接进去，不需要密码。
注意：有些系统的SSH配置默认不允许空密码登录，如果
ssh localhost还是要密码，检查/etc/ssh/sshd_config里的PermitEmptyPasswords和PubkeyAuthentication两个参数，确保公钥认证是开启的。
3.3 防火墙与SELinux处理
开发环境里，防火墙和SELinux经常是罪魁祸首。Hadoop的各个组件之间要通过网络端口通信，NameNode默认用9870（Web）和8020（RPC），DataNode用9864（Web）和9866（数据传输），YARN的ResourceManager用8088（Web）和8032（调度）。如果防火墙拦了这些端口，进程能起来但互相连不上，表现就是Web界面打不开、DataNode注册不上。
我的做法是开发阶段直接关掉防火墙和SELinux，省得折腾。命令是systemctl stop firewalld和setenforce 0。生产环境当然不能这么干，但开发环境以跑通为目标，安全策略可以后面再补。如果你不想关防火墙，那就得用firewall-cmd逐个放行端口，麻烦不说，还容易漏。
3.4 主机名与hosts文件
前面提过主机名的重要性，这里再强调一下操作细节。用hostnamectl set-hostname hadoop-dev设置主机名，然后编辑/etc/hosts，加上一行127.0.0.1 hadoop-dev。改完之后用hostname命令确认一下，再用ping hadoop-dev测试解析是否正常。这一步做完，后面配置文件里所有用到主机名的地方都写hadoop-dev，不要写localhost，因为Hadoop在某些场景下对localhost的处理会有歧义。
4. Hadoop核心配置文件逐项拆解
4.1 配置文件概览与优先级
Hadoop的配置文件全在$HADOOP_HOME/etc/hadoop/目录下，核心的有四个：core-site.xml、hdfs-site.xml、mapred-site.xml、yarn-site.xml。另外还有几个环境脚本：hadoop-env.sh、yarn-env.sh、mapred-env.sh。这些XML文件的配置项有优先级：代码里硬编码的最高，然后是*-site.xml，最后是*-default.xml。我们改的都是*-site.xml，因为*-default.xml是只读的默认值，改了也不生效。
4.2 core-site.xml：全局基础配置
这个文件定义的是Hadoop运行的基础参数，最关键的三个配置项是：
fs.defaultFS：指定HDFS的访问地址，伪分布式下写hdfs://hadoop-dev:8020。这个地址是NameNode的RPC端口，客户端和DataNode都通过它跟NameNode通信。hadoop.tmp.dir：Hadoop的临时目录，默认是/tmp/hadoop-${user.name}，但/tmp目录重启会被清空，所以一定要改到一个持久化的路径，比如/usr/local/hadoop/tmp。io.file.buffer.size：读写缓冲区大小，默认4KB，可以调到128KB或256KB，提升大文件读写性能。
配置示例：
<configuration> <property> <name>fs.defaultFS</name> <value>hdfs://hadoop-dev:8020</value> </property> <property> <name>hadoop.tmp.dir</name> <value>/usr/local/hadoop/tmp</value> </property> <property> <name>io.file.buffer.size</name> <value>131072</value> </property> </configuration>提示：
hadoop.tmp.dir这个目录一定要提前创建好，并且确保运行Hadoop的用户有读写权限。我见过有人配置写了但目录没建，启动时报FileNotFoundException，排查半天才发现是目录不存在。
4.3 hdfs-site.xml：HDFS专属配置
这个文件管的是HDFS的行为，伪分布式下重点配这几个：
dfs.replication：副本数，伪分布式下只能设1，因为只有一台DataNode，设成3会一直报副本不足的警告。dfs.namenode.name.dir：NameNode的元数据存储路径，存的是文件系统的命名空间和编辑日志。dfs.datanode.data.dir：DataNode的数据块存储路径，实际的文件内容存这里。dfs.namenode.http-address：NameNode的Web界面地址，默认0.0.0.0:9870。dfs.datanode.http-address：DataNode的Web界面地址，默认0.0.0.0:9864。
配置示例：
<configuration> <property> <name>dfs.replication</name> <value>1</value> </property> <property> <name>dfs.namenode.name.dir</name> <value>/usr/local/hadoop/data/namenode</value> </property> <property> <name>dfs.datanode.data.dir</name> <value>/usr/local/hadoop/data/datanode</value> </property> </configuration>这两个数据目录也要提前创建，而且不要放在hadoop.tmp.dir下面，分开管理更清晰，出问题的时候也好定位。
4.4 mapred-site.xml：MapReduce运行框架指定
Hadoop 3.x里MapReduce默认跑在YARN上，所以这个文件主要就配一个参数：
<configuration> <property> <name>mapreduce.framework.name</name> <value>yarn</value> </property> </configuration>如果不配这个，MapReduce会跑在本地模式，你提交的任务根本不会经过YARN，也就看不到资源调度的过程。另外还有一个mapreduce.application.classpath，通常不用手动配，YARN会自动处理，但如果遇到类路径问题，可以在这里显式指定。
4.5 yarn-site.xml：资源调度配置
YARN是资源管理层，这个文件配的是ResourceManager和NodeManager的行为：
yarn.resourcemanager.hostname：ResourceManager所在的主机名，写hadoop-dev。yarn.nodemanager.aux-services：NodeManager的辅助服务，必须配mapreduce_shuffle，否则MapReduce任务跑不起来。yarn.nodemanager.resource.memory-mb：NodeManager可用的总内存，根据机器实际内存来设，4GB的机器可以设2048。yarn.scheduler.maximum-allocation-mb：单个容器能申请的最大内存，设成和上面一样或者略小。
配置示例：
<configuration> <property> <name>yarn.resourcemanager.hostname</name> <value>hadoop-dev</value> </property> <property> <name>yarn.nodemanager.aux-services</name> <value>mapreduce_shuffle</value> </property> <property> <name>yarn.nodemanager.resource.memory-mb</name> <value>2048</value> </property> <property> <name>yarn.scheduler.maximum-allocation-mb</name> <value>2048</value> </property> </configuration>4.6 hadoop-env.sh：环境变量微调
这个脚本里最重要的是指定JAVA_HOME。虽然系统环境变量里已经配了，但Hadoop的启动脚本有时候读不到，所以在这个文件里再显式写一遍最保险：
export JAVA_HOME=/usr/local/jdk8 export HADOOP_LOG_DIR=/usr/local/hadoop/logs export HADOOP_PID_DIR=/usr/local/hadoop/pids日志目录和PID目录也建议显式指定，默认是在/tmp下面，重启就没了，排查问题的时候找不到日志会很抓狂。
5. 格式化与启动全流程实操
5.1 NameNode格式化操作
配置全部改完之后，第一步是格式化NameNode。命令是：
hdfs namenode -format这个操作会在dfs.namenode.name.dir指定的目录下创建初始的元数据文件，包括fsimage和edits。格式化只能做一次，如果重复格式化，会导致NameNode和DataNode的集群ID不一致，DataNode启动后会报ClusterId mismatch然后自动关闭。
注意：如果你确实需要重新格式化，必须先把
dfs.namenode.name.dir和dfs.datanode.data.dir两个目录清空，然后再执行格式化命令。只清一个目录是不行的，集群ID对不上照样起不来。
格式化成功的标志是看到Storage directory ... has been successfully formatted这行输出。如果报权限错误，检查一下当前用户对数据目录有没有写权限。
5.2 启动HDFS集群
启动HDFS用start-dfs.sh脚本，它会依次启动NameNode、DataNode和SecondaryNameNode。执行完之后用jps命令查看进程，应该能看到：
NameNodeDataNodeSecondaryNameNodeJps（这个是jps命令本身的进程）
如果少了某个进程，去$HADOOP_HOME/logs/目录下找对应的日志文件，通常错误信息都在里面。NameNode起不来最常见的原因是端口被占用或者目录权限不对，DataNode起不来多半是集群ID不匹配或者磁盘空间不足。
5.3 启动YARN集群
HDFS起来之后，再启动YARN：
start-yarn.sh这个脚本会启动ResourceManager和NodeManager。再用jps看，应该多出：
ResourceManagerNodeManager
到这一步，整个伪分布式集群就算跑起来了。你可以通过Web界面验证：NameNode的界面是http://hadoop-dev:9870，ResourceManager的界面是http://hadoop-dev:8088。打开NameNode界面，在Datanodes标签页里应该能看到一个活跃的DataNode，容量和已用空间都有显示。
5.4 验证HDFS基本操作
集群起来之后，做几个基本操作验证一下。先在HDFS上建个目录：
hdfs dfs -mkdir -p /user/hadoop/test然后传个文件上去：
hdfs dfs -put /etc/hosts /user/hadoop/test/查看文件列表：
hdfs dfs -ls /user/hadoop/test/如果这些命令都能正常执行，说明HDFS工作正常。你还可以去NameNode的Web界面里浏览文件系统，能看到刚才创建的目录和上传的文件。
5.5 运行WordCount测试任务
最后跑一个MapReduce任务验证YARN。Hadoop自带了一个WordCount的示例jar包，在$HADOOP_HOME/share/hadoop/mapreduce/目录下。执行命令：
hadoop jar $HADOOP_HOME/share/hadoop/mapreduce/hadoop-mapreduce-examples-3.3.6.jar wordcount /user/hadoop/test/hosts /user/hadoop/test/output任务提交后，去ResourceManager的Web界面能看到一个正在运行的应用。等任务跑完，用hdfs dfs -cat /user/hadoop/test/output/part-r-00000查看结果，应该能看到每个单词出现的次数。这一步跑通，说明整个Hadoop开发环境完全就绪了。
6. 常见故障排查与避坑经验
6.1 启动脚本报“JAVA_HOME is not set”
这个错误很常见，明明系统环境变量里配了JAVA_HOME，但start-dfs.sh就是读不到。原因是Hadoop的启动脚本在某些情况下不会加载/etc/profile，所以得在hadoop-env.sh里再配一遍。另外注意hadoop-env.sh里配置JAVA_HOME的时候不要加引号，有些版本的脚本对引号处理有问题。
6.2 NameNode启动后立即退出
去日志里找java.lang.RuntimeException或者java.io.IOException。常见原因有三个：一是dfs.namenode.name.dir目录不存在或没权限；二是端口8020被其他进程占用，用netstat -tlnp | grep 8020查一下；三是格式化的时候集群ID生成失败，通常是hadoop.tmp.dir指向的目录有问题。
6.3 DataNode无法注册到NameNode
DataNode进程起来了，但NameNode的Web界面里看不到活跃的DataNode。先检查两个节点的集群ID是否一致，分别查看dfs.namenode.name.dir/current/VERSION和dfs.datanode.data.dir/current/VERSION文件里的clusterID字段。如果不一致，说明格式化之后又动过数据目录，需要清空重新格式化。如果集群ID一致但还是注册不上，检查网络连通性和防火墙设置。
6.4 YARN任务一直处于ACCEPTED状态
任务提交到YARN后一直不跑，状态卡在ACCEPTED。这通常是资源不够，NodeManager报告的可分配内存小于任务需要的内存。去ResourceManager界面看Cluster Metrics里的Memory Total和Memory Used，如果可用内存不足，要么调大yarn.nodemanager.resource.memory-mb，要么调小任务的内存请求。还有一个可能是yarn.nodemanager.aux-services没配mapreduce_shuffle，导致NodeManager无法处理MapReduce的Shuffle请求。
6.5 常见问题速查表
| 问题现象 | 可能原因 | 排查方法 |
|---|---|---|
| NameNode起不来 | 端口占用、目录权限、集群ID问题 | 查NameNode日志、netstat查端口、检查VERSION文件 |
| DataNode起不来 | 集群ID不匹配、磁盘满 | 对比NameNode和DataNode的clusterID、df -h查磁盘 |
| Web界面打不开 | 防火墙拦截、进程没起来 | 关防火墙、jps查进程、curl测端口 |
| 任务卡在ACCEPTED | 资源不足、aux-services没配 | 看RM界面资源、检查yarn-site.xml |
| SSH免密不生效 | 公钥没拷对、权限太开放 | 检查~/.ssh/authorized_keys权限是否为600 |
| 格式化报权限错误 | 当前用户对数据目录无写权限 | chown改目录属主、chmod改权限 |
6.6 几个容易忽略的细节
第一，hadoop.tmp.dir、dfs.namenode.name.dir、dfs.datanode.data.dir这三个目录一定要在格式化之前创建好，并且确保运行Hadoop的用户有读写权限。我习惯用mkdir -p一次性建好，然后用chown -R把属主改成当前用户。
第二，如果你在虚拟机里搭环境，快照是个好东西。配置改到一半不确定对不对的时候，先打个快照，搞砸了直接回滚，比一点点排查快得多。
第三，日志是你的朋友。遇到任何问题，第一反应应该是去看日志，而不是瞎猜。NameNode的日志在logs/hadoop-<user>-namenode-<hostname>.log，DataNode的日志在logs/hadoop-<user>-datanode-<hostname>.log，YARN的日志在logs/yarn-<user>-resourcemanager-<hostname>.log。日志里的错误堆栈会直接告诉你问题出在哪一行。
第四，不要随便改默认端口。Hadoop 3.x的默认端口和2.x不一样，网上很多教程还是2.x的端口，照着改反而会出问题。比如NameNode的Web端口在3.x是9870，2.x是50070，如果你看到教程里写50070，那说明教程太老了，配置项的名字可能也变了。
7. 环境搭建后的扩展方向
环境跑通只是第一步，接下来你可以基于这个伪分布式集群做很多事情。比如学习Hive，它可以把SQL翻译成MapReduce任务跑在YARN上；学习HBase，它依赖HDFS做底层存储；学习Spark，它可以跑在YARN上也可以独立运行。这些组件的安装配置都会依赖你刚搭好的Hadoop环境，所以把基础打牢，后面学什么都快。
另外，如果你想把伪分布式扩展到完全分布式，核心改动就几个：把fs.defaultFS指向真正的NameNode主机，把yarn.resourcemanager.hostname指向真正的ResourceManager主机，然后在每个节点上配好SSH免密和hosts文件。配置逻辑完全一样，只是地址从本机变成了远程主机。
我个人在实际操作中的体会是，搭环境这件事，第一次最难，因为什么都不知道，每一步都在试错。但搭完一次之后，你会发现所有分布式系统的配置逻辑都差不多：指定主节点地址、指定数据存储路径、指定通信端口、配好网络和权限。把这套东西吃透，以后遇到任何分布式组件，你都能快速上手。
