简介Apache Hadoop 3.3.3 官方发行包hadoop-3.3.3.tar.gz面向大数据初学者、分布式系统开发者与运维人员用于搭建可靠、可扩展的分布式计算与存储环境。该框架以简单编程模型支持跨集群处理海量数据集可从单机平滑扩展至数千节点并在应用层实现故障检测与高可用适合学习 HDFS、MapReduce、YARN 核心组件及本地库调用。压缩包约 615.16MB共 22536 个文件以 18870 个 html 文档、763 个 jpg 与 762 个 gif 图示、488 个 css 样式为主辅以 449 个 jar 依赖、124 个 xml 配置、75 个 sh 脚本及 22 个 gz 归档并包含 libhadoop、libhdfs、libnativetask 等本地库文件覆盖文档、配置、脚本与原生依赖。已有 644 人学习下载适合对照官方文档完成环境部署、组件调试与源码结构梳理。1. Apache Hadoop 3.3.3 单机与伪分布式落地从 tar.gz 到能跑 MapReduce 的最小闭环拿到hadoop-3.3.3.tar.gz这个包的人十有八九卡在同一个地方解压完、配完环境变量、start-dfs.sh一敲要么 NameNode 起不来要么 Web UI 打不开要么跑个 WordCount 报一堆Connection refused。Apache Hadoop 3.3.3 是 3.3.x 线里被大量课程设计和生产测试环境沿用的版本它的目录结构、默认端口、配置文件位置和 2.x 差异不小网上抄来的老教程直接套会翻车。这篇笔记只干一件事把 hadoop-3.3.3.tar.gz 从零解压到跑通第一个 MapReduce 作业的完整路径讲清楚包括伪分布式搭建、参数怎么设、日志去哪看、报错怎么排。适合两类人一是要交 hadoop 课程设计、需要本地跑通集群的学生二是想在 Windows 下用 IDEA 连远程 Hadoop 做开发、但被环境折腾到怀疑人生的工程师。单机和伪分布式是后面一切集群搭建的地基地基没打牢后面整合 ZooKeeper、Tez、上 Docker 都是空中楼阁。2. 先搞清楚 3.3.3 这个包里的东西目录、端口与运行模式2.1 解压后每个目录是干什么的很多人解压完就急着配环境变量其实先花五分钟把目录结构看一遍后面排错能省一半时间。hadoop-3.3.3.tar.gz解压出来的根目录下真正天天打交道的是这几个目录作用排错时的用途bin/客户端命令如hdfs、hadoop、yarn执行命令报错先看这里脚本sbin/集群管理脚本如start-dfs.sh、stop-yarn.sh启停服务用普通用户别乱改etc/hadoop/全部配置文件所在地90% 的启动失败都在这lib/依赖 jar 包缺 jar 报 ClassNotFound 时查logs/运行日志服务起不来第一现场share/hadoop/各模块的 jar 和示例跑官方 example 用关键点bin和sbin是两套东西。hadoop fs -ls /用的是bin/hadoop而start-dfs.sh在sbin里。新手最容易犯的错是把sbin加进 PATH 后以为万事大吉结果hadoop命令找不到因为bin没加。2.2 三个核心配置文件和它们的最小改动Hadoop 3.3.3 的配置全部在etc/hadoop/下伪分布式只需要动三个文件。先说清楚每个文件管什么再给最小配置。core-site.xml管全局最重要的是文件系统入口地址。伪分布式下 NameNode 的 RPC 端口默认是 80202.x 时代是 9000很多老教程还在写 9000这是典型翻车点configuration property namefs.defaultFS/name valuehdfs://localhost:8020/value /property property namehadoop.tmp.dir/name value/opt/hadoop-3.3.3/tmp/value /property /configurationhadoop.tmp.dir必须显式指定。默认它落在/tmp下机器一重启数据全没NameNode 格式化过的元数据丢失再启动就报NameNode is not formatted。这是血泪经验别省这一行。hdfs-site.xml管 HDFS 副本和目录。伪分布式只有一个 DataNode副本数必须改成 1否则永远处于副本不足的告警状态configuration property namedfs.replication/name value1/value /property property namedfs.namenode.name.dir/name value/opt/hadoop-3.3.3/data/namenode/value /property property namedfs.datanode.data.dir/name value/opt/hadoop-3.3.3/data/datanode/value /property /configurationmapred-site.xml和yarn-site.xml决定 MapReduce 跑在什么框架上。3.3.3 默认用 YARN所以两个都要配!-- mapred-site.xml -- configuration property namemapreduce.framework.name/name valueyarn/value /property /configuration !-- yarn-site.xml -- configuration property nameyarn.nodemanager.aux-services/name valuemapreduce_shuffle/value /property /configurationyarn.nodemanager.aux-services的值是mapreduce_shuffle不是mapreduce.shuffle中间是下划线。这个拼写错误会让 NodeManager 起来但作业卡在 ACCEPTED 状态不动日志里能看到 shuffle 服务注册失败。2.3 环境变量和 Java 版本这道坎Hadoop 3.3.3 编译时用的是 Java 8用 Java 11 或 17 跑会出现各种IllegalAccessError和模块反射问题。最稳的做法是装 JDK 8然后在etc/hadoop/hadoop-env.sh里显式指定export JAVA_HOME/usr/lib/jvm/java-8-openjdk-amd64 export HDFS_NAMENODE_USERroot export HDFS_DATANODE_USERroot export HDFS_SECONDARYNAMENODE_USERroot export YARN_RESOURCEMANAGER_USERroot export YARN_NODEMANAGER_USERroot后面那几行*_USER是 3.x 新增的。3.x 的启动脚本会检查这些变量不设的话start-dfs.sh直接报ERROR: Attempting to operate on hdfs namenode as root but there is no HDFS_NAMENODE_USER defined。这是 3.x 和 2.x 最大的启动差异老教程里根本没有。环境变量层面~/.bashrc里加export HADOOP_HOME/opt/hadoop-3.3.3 export PATH$PATH:$HADOOP_HOME/bin:$HADOOP_HOME/sbin export HADOOP_CONF_DIR$HADOOP_HOME/etc/hadoopHADOOP_CONF_DIR在 Windows 下用 IDEA 连远程集群时是必须的本地开发环境靠它找到配置。3. 从格式化到跑通 WordCount伪分布式搭建的完整命令链3.1 格式化 NameNode 与启动顺序配置改完第一步是格式化。注意格式化只能做一次重复格式化会导致 DataNode 的 clusterID 和 NameNode 对不上DataNode 拒绝启动。# 格式化 NameNode生成元数据 hdfs namenode -format # 启动 HDFSNameNode DataNode SecondaryNameNode start-dfs.sh # 启动 YARNResourceManager NodeManager start-yarn.sh启动顺序有讲究先 HDFS 后 YARN。YARN 的 NodeManager 启动时会向 HDFS 写日志聚合目录HDFS 没起来它就一直重试。反过来先启 YARN 再启 HDFS虽然最终也能起来但日志里一堆重试告警看着心慌。启动后用jps验证进程。正常伪分布式应该有 5 个进程jps # 期望输出 # NameNode # DataNode # SecondaryNameNode # ResourceManager # NodeManager少任何一个去logs/下找对应.log文件。比如 NameNode 没起来看logs/hadoop-user-namenode-hostname.log最后 50 行基本能定位问题。3.2 Web UI 端口与验证方法3.3.3 的默认 Web 端口和 2.x 不同这是另一个高频翻车点服务3.3.3 默认端口2.x 旧端口NameNode UI987050070ResourceManager UI80888088DataNode UI986450075SecondaryNameNode UI986850090访问http://localhost:9870能看到 HDFS 的 Overview 页面说明 NameNode 正常。如果浏览器打不开但jps有进程先检查防火墙再确认core-site.xml里fs.defaultFS的端口和实际监听端口一致。用netstat -tlnp | grep 9870看端口有没有真的在听。3.3 跑通第一个 MapReduceWordCount 全流程验证集群能不能干活最直接的就是跑官方自带的 WordCount。整个过程分四步造数据、传 HDFS、跑作业、看结果。# 1. 本地造一个测试文件 echo hello hadoop hello mapreduce hello yarn /tmp/word.txt echo hadoop hdfs namenode datanode /tmp/word.txt # 2. 在 HDFS 建输入目录并上传 hdfs dfs -mkdir -p /input hdfs dfs -put /tmp/word.txt /input/ # 3. 确认上传成功 hdfs dfs -ls /input hdfs dfs -cat /input/word.txt # 4. 跑 WordCount输出到 /output hadoop jar $HADOOP_HOME/share/hadoop/mapreduce/hadoop-mapreduce-examples-3.3.3.jar \ wordcount /input /output # 5. 查看结果 hdfs dfs -cat /output/part-r-00000第 4 步的 jar 包路径是固定的hadoop-mapreduce-examples-3.3.3.jar里的版本号必须和你的包一致。跑的时候终端会刷一堆INFO日志那是正常的真正要看的是最后有没有Job ... completed successfully。如果卡在map 0% reduce 0%超过两分钟八成是 YARN 的容器分配有问题去 ResourceManager UI 的 Applications 页面看作业状态或者翻logs/hadoop-user-nodemanager-hostname.log。结果里每个单词后面跟一个数字hello 3、hadoop 3这种。能跑出这个说明 HDFS 读写、YARN 调度、MapReduce 执行整条链路都通了伪分布式搭建就算成功。4. Windows 下用 IDEA 连远程 Hadoop 开发环境配置与第一个作业4.1 Windows 端必须补的 winutils 和依赖Windows 下用 IDEA 写 MapReduce 有个绕不开的坑Hadoop 的本地库是 Linux 的.soWindows 上跑会报Could not locate executable null\bin\winutils.exe。解决办法是下载对应版本的winutils.exe和hadoop.dll放到一个目录里比如D:\hadoop\bin然后设环境变量# Windows 系统环境变量里加 HADOOP_HOMED:\hadoop PATH%PATH%;%HADOOP_HOME%\bin同时在 IDEA 的 Run Configuration 里加 VM 参数-Dhadoop.home.dirD:\hadoopwinutils.exe的版本要和 Hadoop 3.3.3 对应用 2.x 的 winutils 配 3.3.3 会出现权限相关的诡异报错。这个文件本身不参与计算只是让 Hadoop 在 Windows 上能调用本地文件系统权限接口属于典型的黑匣子依赖。4.2 Maven 依赖与连接远程集群的配置IDEA 里建 Maven 项目pom.xml加这几个依赖版本统一用 3.3.3dependencies dependency groupIdorg.apache.hadoop/groupId artifactIdhadoop-client/artifactId version3.3.3/version /dependency dependency groupIdorg.apache.hadoop/groupId artifactIdhadoop-common/artifactId version3.3.3/version /dependency dependency groupIdorg.apache.hadoop/groupId artifactIdhadoop-hdfs/artifactId version3.3.3/version /dependency /dependencieshadoop-client是个聚合包会把 mapreduce、yarn、common 都拉进来一般够用。如果只做 HDFS 操作可以只引hadoop-common和hadoop-hdfs减少依赖冲突。连接远程集群时把集群的core-site.xml、hdfs-site.xml、mapred-site.xml、yarn-site.xml拷到项目的src/main/resources下代码里不用再new Configuration()手动设它会自动读。但要注意fs.defaultFS里的localhost要改成集群的真实 IP 或主机名否则本地代码会去连本地的 8020连不上。4.3 一个能直接跑的 HDFS 操作示例下面这段代码演示从本地读文件、上传到 HDFS、再读回来是 Windows 下验证环境是否通的最小闭环import org.apache.hadoop.conf.Configuration; import org.apache.hadoop.fs.*; public class HdfsDemo { public static void main(String[] args) throws Exception { // 自动加载 resources 下的配置文件 Configuration conf new Configuration(); // 显式指定避免读到本地默认值 conf.set(fs.defaultFS, hdfs://192.168.1.100:8020); FileSystem fs FileSystem.get(conf); // 上传本地文件到 HDFS Path local new Path(D:/data/test.txt); Path remote new Path(/user/test/test.txt); fs.copyFromLocalFile(local, remote); System.out.println(上传完成); // 读取 HDFS 文件内容 FSDataInputStream in fs.open(remote); byte[] buf new byte[1024]; int len; while ((len in.read(buf)) ! -1) { System.out.print(new String(buf, 0, len)); } in.close(); fs.close(); } }conf.set(fs.defaultFS, ...)这行是关键。即使 resources 下有配置文件显式设一遍能避免被本地core-site.xml覆盖。FileSystem.get(conf)会根据 scheme 返回对应的实现hdfs://返回DistributedFileSystem。跑之前确认远程集群的 8020 端口从 Windows 能通用telnet 192.168.1.100 8020测一下不通就是网络或防火墙问题跟代码无关。5. 避坑与排查伪分布式搭建里最容易翻车的五件事5.1 NameNode 反复格式化导致 DataNode 起不来现象start-dfs.sh后jps只有 NameNode没有 DataNodeDataNode 日志报java.io.IOException: Incompatible clusterIDs。原因每次hdfs namenode -format都会生成新的 clusterID而 DataNode 目录里存的是旧 clusterID两者对不上DataNode 拒绝加入。解决停掉所有进程删掉dfs.namenode.name.dir和dfs.datanode.data.dir指向的目录重新格式化一次再启动。记住格式化只做一次改配置不用重新格式化。5.2 端口 8020 和 9000 混用现象hdfs dfs -ls /报Connection refused但jps里 NameNode 明明在。原因core-site.xml里写的是hdfs://localhost:9000但 3.3.3 的 NameNode 实际监听 8020客户端连 9000 自然被拒。解决确认fs.defaultFS的端口和 NameNode 实际监听端口一致。用netstat -tlnp | grep java看 NameNode 进程监听哪个端口以实际为准。3.x 默认 8020别抄 2.x 的 9000。5.3 YARN 作业卡在 ACCEPTED 不动现象WordCount 提交后一直停在map 0% reduce 0%ResourceManager UI 里作业状态是 ACCEPTED。原因常见有两种。一是yarn.nodemanager.aux-services值写错shuffle 服务没注册二是 NodeManager 的内存资源不够容器申请不下来。解决先检查yarn-site.xml里 aux-services 是不是mapreduce_shuffle。再看 NodeManager 日志有没有Container ... is running beyond physical memory limits。伪分布式下可以在yarn-site.xml里调大yarn.nodemanager.resource.memory-mb比如设成 4096。5.4 Java 版本不匹配引发的反射错误现象启动时报java.lang.IllegalAccessError: class ... cannot access class ...或InaccessibleObjectException。原因Hadoop 3.3.3 编译针对 Java 8用 Java 11/17 跑时模块系统限制了反射访问。解决换 JDK 8。如果非要用高版本得加一堆--add-opens参数不划算。生产环境里 Hadoop 3.3.3 配 JDK 8 是经过验证的组合别给自己找麻烦。5.5 Windows 下路径和权限的坑现象IDEA 里跑作业报Permission denied: userxxx, accessWRITE, inode/output。原因Windows 用户名和 HDFS 上的用户对不上HDFS 默认用当前系统用户名做鉴权。解决两个办法。一是在代码里设System.setProperty(HADOOP_USER_NAME, root)用集群上有权限的用户二是关掉 HDFS 权限检查在hdfs-site.xml里加dfs.permissions.enabled设为false但生产环境别这么干。开发环境用第一种更干净。6. 让这套环境真正好用日志定位技巧与配置调优的取舍伪分布式跑通只是起点真正拉开效率差距的是排错速度和配置调优的判断力。分享几个我踩过坑之后固定下来的习惯。先说日志定位。Hadoop 的日志文件命名是hadoop-用户名-服务名-主机名.log比如hadoop-root-namenode-node1.log。服务起不来时别从头翻直接tail -100看最后一百行错误堆栈基本都在末尾。如果日志里全是INFO没有ERROR但服务就是没起来去看对应的.out文件start-dfs.sh的启动脚本输出重定向在那里能看到更底层的失败原因。我一般会开两个终端一个跑启动命令一个tail -f盯着 NameNode 日志启动过程中哪一步卡住一目了然。再说配置调优的取舍。伪分布式下最值得调的是yarn.nodemanager.resource.memory-mb和yarn.scheduler.maximum-allocation-mb。默认值偏保守跑大一点的作业容易卡在容器分配。我的习惯是把 NodeManager 可用内存设成机器物理内存的 70% 左右比如 8G 内存的机器设 5632单位 MBmaximum-allocation-mb设成 2048 或 4096。但别设太大超过物理内存会导致 NodeManager 被系统 OOM Killer 干掉日志里能看到进程突然消失。还有一个容易被忽略的点dfs.datanode.du.reserved。伪分布式下 DataNode 所在磁盘如果还存着别的东西磁盘写满会导致 DataNode 挂掉。这个参数预留一部分磁盘空间给非 HDFS 使用默认是 0我一般设成 10G 左右避免 DataNode 把盘写爆。最后说一个验证配置是否生效的通用方法改完配置后用hdfs getconf -confKey 参数名查实际生效的值。比如hdfs getconf -confKey dfs.replication返回 1说明副本数配置生效了。这比翻配置文件确认靠谱因为 Hadoop 会合并多个来源的配置最终生效值才是真的。这套环境搭好之后往上的路就宽了可以接着整合 ZooKeeper 做 HA可以换 Tez 引擎加速可以打成 Docker 镜像方便分发。但那些都是后话眼下把 3.3.3 的伪分布式跑稳把日志看熟把每个参数改动的后果摸清楚后面不管搭什么集群都不会慌。我自己到现在还保留着一个干净的 3.3.3 伪分布式快照每次试新东西之前先回滚到这个状态省了无数重装的时间。希望帮到你。本文还有配套的精品资源点击获取