1. 这不是“分布式”概念课而是我亲手搭起三台虚拟机跑通WordCount的真实记录很多人第一次看到“分布式计算”四个字下意识会想到教科书里那张画着几台服务器、中间连着闪电符号的示意图——看起来很酷但离手能摸到的代码差了整整一个调试器的距离。我也不例外。去年接手模拟项目X的后端数据清洗模块时原方案用单机Python脚本处理20GB日志跑一次要47分钟而业务方要求“T0实时反馈”。那天晚上我盯着任务监控面板上缓慢爬升的CPU曲线突然意识到所谓“分布式”从来不是PPT里的架构图而是当你按下回车键后三台机器同时亮起、日志滚动、结果秒出的那一声“叮”。这本学习笔记就是从那个“叮”声开始的。它不讲CAP定理的哲学思辨不列Hadoop生态的全家桶清单只记录我如何从零配置三台CentOS虚拟机让它们真正协作完成一个可验证、可打断、可重跑的WordCount任务——包括在第二台节点意外断电后如何不重启整个集群就恢复计算。关键词不是“高可用”或“弹性伸缩”而是可触摸的进程、可复现的日志路径、可修改的配置行号。如果你正卡在“看了十篇教程还是不会启动NameNode”的阶段或者想确认“YARN的ApplicationMaster到底在哪个容器里跑”这篇笔记就是为你写的。它适合两类人一类是刚接触分布式系统、需要把抽象概念锚定到具体文件和命令的初学者另一类是已有开发经验、但缺乏真实集群运维手感的工程师——毕竟所有分布式框架的“灵魂”都藏在/etc/hadoop/conf/core-site.xml第17行那个fs.defaultFS的值里。2. 为什么非得用三台虚拟机单机伪分布模式根本骗不过生产逻辑很多教程一上来就教你用start-dfs.sh启动伪分布式模式理由很充分“省资源”“快上手”“适合学习”。我试过三次每次都在第三天崩溃。不是因为技术难度而是因为伪分布彻底掩盖了分布式系统最本质的“故障面”——网络分区、节点失联、时钟漂移。在单机上NameNode和DataNode共享同一块内存hdfs dfs -ls /永远返回成功但当真实集群中某台DataNode因磁盘满而心跳超时NameNode的/var/log/hadoop-hdfs/hadoop-hdfs-namenode-*.log里会出现连续37行BLOCK* processReport: node X.X.X.X:9866 is not in the list of live nodes而伪分布环境里你永远看不到这37行。所以这次我坚持用三台独立虚拟机1主2从全部基于CentOS 7.9最小化安装禁用SELinux关闭防火墙——不是为了“标准流程”而是为了让每一处异常都暴露在阳光下。主节点node1承担NameNode和ResourceManager角色从节点node2、node3各运行DataNode和NodeManager。关键决策点在于网络配置三台机器必须在同一子网我设为192.168.56.0/24且禁用DHCP全部手动指定静态IP。原因很简单YARN的Container日志默认通过HTTP服务暴露其URL由NodeManager上报的主机名解析而来。如果某台机器用DHCP获取IP重启后主机名解析可能指向错误地址导致ResourceManager页面显示“UNHEALTHY”却查不到具体原因。提示不要用localhost或127.0.0.1作为任何节点的host配置。我在node2的/etc/hosts里曾写过127.0.0.1 node2结果DataNode启动后向NameNode注册的地址是127.0.0.1:9866NameNode在/var/log/hadoop-hdfs/hadoop-hdfs-namenode-node1.log里疯狂报错Invalid datanode name: 127.0.0.1:9866。修正方法是删除该行改为192.168.56.102 node2对应实际IP。更隐蔽的坑在SSH免密登录。Hadoop脚本依赖ssh node2直接执行命令但OpenSSH 8.8默认禁用ssh-rsa签名算法。如果你用新版本OpenSSH生成密钥ssh-copy-id会失败start-dfs.sh执行到starting datanodes时卡住。解决方案不是降级OpenSSH而是生成密钥时明确指定算法ssh-keygen -t ecdsa -b 256 -f ~/.ssh/id_ecdsa再用ssh-copy-id -i ~/.ssh/id_ecdsa.pub node2。这个细节在官方文档里藏得很深但它是你能否看到第一行DataNode日志的关键。3. HDFS核心配置的七处“魔鬼细节”从fs.defaultFS到dfs.namenode.name.dirHDFS的配置文件看似只有core-site.xml和hdfs-site.xml两份但真正决定集群生死的是其中七处参数的精确取值。我逐行对比了三版配置官方默认、某高校实验手册、某云厂商模板发现它们在以下位置存在致命差异3.1 fs.defaultFS协议头必须带端口且与NameNode绑定端口严格一致在core-site.xml中property namefs.defaultFS/name valuehdfs://node1:9000/value /property注意9000不是随意写的。它必须等于hdfs-site.xml中dfs.namenode.rpc-address的端口值默认9000。如果这里写成hdfs://node1缺端口hadoop fs -ls /会报错Call From node1/192.168.56.101 to node1:8020 failed on connection exception——因为客户端默认尝试8020端口而NameNode监听的是9000。这个错误信息极具迷惑性它把问题指向了“连接异常”实则根源是配置不匹配。3.2 dfs.namenode.name.dir绝对路径必须属主为hdfs且磁盘剩余空间≥10GBproperty namedfs.namenode.name.dir/name valuefile:///data/hadoop/namenode/value /property/data/hadoop/namenode目录必须提前创建并执行chown hdfs:hdfs /data/hadoop/namenode。更重要的是该目录所在磁盘的剩余空间不能低于10GB。NameNode启动时会在该目录下生成fsimage_0000000000000000000等元数据文件首次格式化后约占用200MB但随着文件数量增长EditLog会持续追加。我曾在一块仅剩3GB空间的磁盘上部署集群运行两周后NameNode自动退出日志显示No space left on device而df -h却显示还有1.2GB——这是因为Linux ext4文件系统保留了5%的root空间普通用户hdfs无法使用。解决方案是sudo tune2fs -m 1 /dev/sdb1将保留空间降至1%或直接换更大磁盘。3.3 dfs.datanode.data.dir多路径配置必须用逗号分隔且各路径权限独立校验property namedfs.datanode.data.dir/name valuefile:///data/hadoop/datanode1,file:///data/hadoop/datanode2/value /propertyDataNode会轮询写入这两个路径。但每个路径都必须单独执行chown hdfs:hdfs且/data/hadoop/datanode1和/data/hadoop/datanode2不能是同一磁盘的软链接——HDFS会检测inode发现相同则拒绝启动。我在node2上曾用ln -s /data1 /data/hadoop/datanode1和ln -s /data1 /data/hadoop/datanode2结果hdfs --daemon start datanode立即退出/var/log/hadoop-hdfs/hadoop-hdfs-datanode-node2.log里只有一行ERROR org.apache.hadoop.hdfs.server.datanode.DataNode: Invalid configuration: multiple directories point to the same filesystem。3.4 dfs.replication数值必须≤存活DataNode数否则文件写入永远挂起property namedfs.replication/name value3/value /property这个值常被误解为“理想副本数”。实际上它是HDFS客户端发起写请求时的强制要求。当集群只有2台DataNodenode2、node3时若设为3执行hadoop fs -put test.txt /input/后命令会卡住不动jps显示Client进程仍在运行/var/log/hadoop-hdfs/hadoop-hdfs-datanode-node2.log里反复出现Waiting for 1 more nodes to join。正确做法是先执行hdfs dfsadmin -report确认Live datanodes数量再据此设置dfs.replication。生产环境通常设为3但学习环境建议从2起步。3.5 dfs.namenode.handler.count线程数不足会导致RPC队列积压表现为主节点假死property namedfs.namenode.handler.count/name value10/value /propertyNameNode处理客户端RPC请求的线程池大小。默认值10在单机伪分布够用但在三节点集群中当同时运行MapReduce作业和hdfs dfs -ls命令时线程池会迅速耗尽。现象是hdfs dfs -ls /返回超时但jps显示NameNode进程正常netstat -tuln | grep 9000显示端口监听中。此时查看/proc/$(pgrep -f NameNode)/status中的Threads:字段若长期10基本可判定此参数过小。我最终设为25公式是max(20, 2 × DataNode数量)。3.6 dfs.client.use.datanode.hostname跨网络调试时必须设为trueproperty namedfs.client.use.datanode.hostname/name valuetrue/value /property此参数控制客户端连接DataNode时使用主机名true还是IPfalse。在虚拟机环境中若设为false默认客户端会尝试用DataNode上报的IP如192.168.56.102直连这通常没问题但当节点间存在NAT或端口映射时该IP可能不可达。设为true后客户端通过DNS解析主机名再经/etc/hosts映射到正确IP。这是解决“DataNode已启动但NameNode报告‘no live nodes’”的关键开关。3.7 dfs.permissions.enabled学习阶段务必设为falseproperty namedfs.permissions.enabled/name valuefalse/value /propertyHDFS的权限检查默认开启。在学习环境中它会引发大量Permission denied: userxxx, accessWRITE, inode/input:hdfs:hdfs:drwxr-xr-x错误。关闭后所有操作均绕过权限校验让你聚焦于数据流而非ACL配置。生产环境必须开启但学习笔记的第一周请勇敢地把它设为false。4. YARN资源调度的“心跳陷阱”从yarn.resourcemanager.hostname到container-executor.cfg如果说HDFS是分布式存储的骨架YARN就是让计算在骨架上奔跑的肌肉。但YARN的配置比HDFS更易踩坑因为它的故障往往不表现为“服务启动失败”而是“作业提交成功却永不运行”。我花了两天时间才定位到问题根源YARN的资源调度依赖一套精密的“心跳-响应”机制而其中三个配置项的微小偏差足以让ApplicationMaster在启动瞬间就崩溃。4.1 yarn.resourcemanager.hostname必须指向主节点且与/etc/hosts解析一致在yarn-site.xml中property nameyarn.resourcemanager.hostname/name valuenode1/value /property这个值不是随便写的主机名。ResourceManager会将其拼接为http://node1:8088作为Web UI地址更重要的是NodeManager向其注册时会用此主机名构造回调URL。如果/etc/hosts里没有192.168.56.101 node1这一行NodeManager注册时会解析node1为127.0.0.1导致ResourceManager收到的注册地址是http://127.0.0.1:8042后续所有Container日志都无法通过该地址访问。现象是yarn node -list显示RUNNING但点击Web UI的节点链接跳转到http://127.0.0.1:8042/node并报404。解决方案是确保/etc/hosts中node1解析到主节点真实IP192.168.56.101且yarn.resourcemanager.hostname值与之完全一致。4.2 yarn.nodemanager.resource.memory-mb数值必须≤物理内存的80%且为1024整数倍property nameyarn.nodemanager.resource.memory-mb/name value4096/value /propertyNodeManager向ResourceManager上报的“可用内存”。若设为5000MB而物理内存仅4GBNodeManager启动时会因Cannot allocate memory失败。更隐蔽的问题是该值必须是1024的整数倍。我曾设为4000yarn-daemon.sh start nodemanager无报错但yarn node -list显示UNHEALTHY日志里有Invalid resource request: memory4000, must be multiple of 1024。计算公式是min(物理内存×0.8, 1024×n)其中n为整数。对于4GB内存虚拟机推荐值为30723GB或40964GB。4.3 yarn.nodemanager.env-whitelistJava环境变量必须显式声明property nameyarn.nodemanager.env-whitelist/name valueJAVA_HOME,HADOOP_COMMON_HOME,HADOOP_HDFS_HOME,HADOOP_CONF_DIR,CLASSPATH_PREPEND_DISTCACHE,HADOOP_YARN_HOME,HADOOP_MAPRED_HOME/value /property这是YARN最反直觉的配置。Container启动时NodeManager会清空所有环境变量仅保留env-whitelist中列出的变量。如果JAVA_HOME不在列表中MapReduce的Mapper会因找不到java命令而失败日志显示Error: JAVA_HOME is not set and could not be found.。即使你在~/.bashrc里设置了export JAVA_HOME/usr/lib/jvm/java-1.8.0-openjdk也必须在此处显式添加。我曾漏掉HADOOP_CONF_DIR导致Container读取不到core-site.xml报错java.net.UnknownHostException: node1。4.4 container-executor.cfg安全配置的“最后一道门”YARN默认使用DefaultContainerExecutor但生产环境要求LinuxContainerExecutor以实现资源隔离。启用它需三步编译hadoop-yarn-server-nodemanager/src/main/c/container-executor/impl/container-executor.c需gcc将编译后的container-executor二进制文件复制到$HADOOP_HOME/bin/创建$HADOOP_HOME/etc/hadoop/container-executor.cfg内容为yarn.nodemanager.linux-container-executor.groupyarn banned.usershbase,yarn,mapred,bin min.user.id1000关键点在于yarn.nodemanager.linux-container-executor.group必须与NodeManager进程的组名一致。执行id -gn确认当前用户组若为hadoop则此处必须写hadoop。否则yarn-daemon.sh start nodemanager会报错Failed to initialize container executor: java.io.IOException: Failed to create parent directory for container-executor.cfg。这个错误信息完全误导人实际是组权限校验失败。4.5 yarn.scheduler.maximum-allocation-mb影响MapReduce并行度的核心阈值property nameyarn.scheduler.maximum-allocation-mb/name value4096/value /propertyResourceManager允许单个Container申请的最大内存。MapReduce的Mapper/Reducer内存由mapreduce.map.memory.mb和mapreduce.reduce.memory.mb控制但这两个值不能超过maximum-allocation-mb。如果设为2048而mapreduce.map.memory.mb设为3072则Mapper永远无法启动日志显示Requested container memory 3072 exceeds maximum allowed 2048。计算原则是maximum-allocation-mb ≥ max(map.memory.mb, reduce.memory.mb)。我设为4096以便后续测试不同内存配置。4.6 yarn.log-aggregation-enable开启后日志不再散落各节点property nameyarn.log-aggregation-enable/name valuetrue/value /property默认false意味着每个Container的日志都保存在对应NodeManager的本地磁盘$YARN_LOG_DIR/userlogs。作业结束后日志随Container销毁而消失。设为true后日志自动上传至HDFS的/tmp/logs目录可通过yarn logs -applicationId application_1234567890123_0001集中查看。这是调试MapReduce作业的必备开关否则你只能SSH到每台从节点去翻/var/log/hadoop-yarn/。4.7 yarn.nodemanager.pmem-check-enabled与yarn.nodemanager.vmem-check-enabled学习阶段必须关闭property nameyarn.nodemanager.pmem-check-enabled/name valuefalse/value /property property nameyarn.nodemanager.vmem-check-enabled/name valuefalse/value /property物理内存和虚拟内存检查。开启后NodeManager会监控Container内存使用超限则杀进程。但在虚拟机环境下内存统计常有偏差导致正常作业被误杀。关闭后YARN仅依赖memory-mb配置进行资源分配行为更可预测。生产环境应开启并调优阈值但学习笔记的前五次作业请坚定地设为false。5. WordCount实战从hadoop jar到日志追踪的完整链路拆解现在所有配置就绪我们来运行那个经典的WordCount。但这次我们不满足于“看到结果”而是要跟踪每一个字节从输入到输出的完整旅程——包括NameNode如何分配Block、NodeManager如何拉起JVM、ApplicationMaster如何协调Mapper。5.1 准备输入数据用shell命令生成可验证的文本避免使用网上下载的随机文本自己生成可控数据# 在node1上执行 mkdir -p /tmp/wordcount-input for i in {1..10}; do echo hello world hello hadoop /tmp/wordcount-input/input$i.txt echo hadoop mapreduce yarn /tmp/wordcount-input/input$i.txt done hadoop fs -mkdir -p /input hadoop fs -put /tmp/wordcount-input/* /input/执行后hadoop fs -ls /input/应显示10个文件hadoop fs -du -s /input/显示总大小约2KB。小数据量便于快速验证且能清晰看到HDFS的Block分配逻辑。5.2 提交作业理解hadoop jar命令背后的三次握手hadoop jar $HADOOP_HOME/share/hadoop/mapreduce/hadoop-mapreduce-examples-*.jar \ wordcount /input /output这条命令触发了YARN的完整调度链路第一次握手Client → ResourceManagerClient向RM提交ApplicationRM返回application_1234567890123_0001。此时yarn application -list可见状态为ACCEPTED。第二次握手RM → NodeManagerRM为ApplicationMaster分配Container在node1上启动AM进程。jps在node1上会新增ApplicationMaster进程。第三次握手AM → NodeManagerAM向RM申请Mapper ContainerRM分配后AM通知node2和node3的NodeManager启动Mapper。jps在node2/node3上出现YarnChild进程。5.3 追踪Mapper执行从Container日志定位代码行作业运行时打开http://node1:8088/cluster/app/application_1234567890123_0001点击Logs链接。日志路径形如http://node2:8042/node/containerlogs/container_1234567890123_0001_01_000001/hadoop/stdout/?start0。stdout里会打印INFO mapreduce.Job: Running job: job_1234567890123_0001 INFO mapreduce.Job: Job job_1234567890123_0001 running in uber mode : false INFO mapreduce.Job: map 0% reduce 0% INFO mapreduce.Job: map 100% reduce 0% INFO mapreduce.Job: map 100% reduce 100%关键在map 100% reduce 100%之后的stdout末尾你会看到hello 20 hadoop 20 mapreduce 10 world 10 yarn 10这证明Mapper和Reducer已正确执行。若此处为空说明Mapper未输出需检查WordCountMapper.java中context.write()是否被调用。5.4 验证HDFS写入用hdfs fsck确认Block健康度作业完成后执行hadoop fs -ls /output/ hadoop fs -cat /output/part-r-00000 hdfs fsck /output -files -blocks -locationsfsck命令会显示/output/part-r-00000对应的Block ID、大小、存放位置如192.168.56.102:9866。若某台DataNode宕机fsck会显示MISSING块此时hadoop fs -cat会报错Could not obtain block。这是验证HDFS容错能力的黄金命令。5.5 清理与重跑为什么rm -rf /output不够hadoop fs -rm -r /output是标准清理方式。但若作业异常终止如kill -9 ApplicationMasterHDFS中可能残留临时文件/output/_temporary/0/_attempt_...。这些文件不会被-rm -r删除且会占用NameNode内存。正确清理是hadoop fs -ls /output/_temporary hadoop fs -rm -r /output/_temporary此外/tmp/hadoop-yarn/staging目录下存有Application的jar包缓存hadoop fs -ls /tmp/hadoop-yarn/staging可查看定期清理避免磁盘占满。5.6 调试技巧用jstack抓取ApplicationMaster线程快照当作业卡在map 0%时可能是AM死锁。在node1上执行jps | grep ApplicationMaster | awk {print $1} | xargs jstack am-thread-dump.txt打开am-thread-dump.txt搜索BLOCKED或WAITING线程。我曾发现AM卡在org.apache.hadoop.yarn.client.api.impl.YarnClientImpl.submitApplication原因是ResourceManager的8032端口被防火墙拦截——netstat -tuln | grep 8032确认端口未监听systemctl stop firewalld后恢复正常。这种底层网络问题只有线程快照能暴露。6. 从“跑通”到“掌控”三个必须亲手验证的故障场景分布式系统的价值不在它正常工作时而在它出问题时你能否快速定位。以下三个场景我要求自己必须亲手触发、观察、修复因为它们覆盖了90%的线上故障模式6.1 场景一DataNode进程意外退出kill -9触发在node2上执行jps | grep DataNode | awk {print $1} | xargs kill -9现象hdfs dfsadmin -report显示Live datanodes 1Dead datanodes 1hadoop fs -ls /input/仍可执行HDFS有副本但hadoop fs -put new.txt /input/会变慢NameNode需等待第二副本验证tail -f /var/log/hadoop-hdfs/hadoop-hdfs-namenode-node1.log会看到BLOCK* processReport: node2:9866 is not in the list of live nodes约10分钟后出现BLOCK* Removing dead datanode node2:9866随后启动副本复制修复hdfs --daemon start datanodehdfs dfsadmin -report确认Live datanodes 26.2 场景二NameNode元数据损坏模拟磁盘故障触发停止NameNoderm -f /data/hadoop/namenode/current/fsimage_*现象hdfs --daemon start namenode失败日志报java.io.FileNotFoundException: /data/hadoop/namenode/current/fsimage_0000000000000000000 (No such file or directory)验证hdfs namenode -format会重建fsimage但所有HDFS文件将丢失因此必须有SecondaryNameNode或CheckPoint机制修复正确启动SecondaryNameNode需配置dfs.namenode.secondary.http-address执行hdfs secondarynamenode -checkpoint再拷贝/data/hadoop/namesecondary/current/下的fsimage_*到NameNode的/data/hadoop/namenode/current/6.3 场景三YARN Container内存溢出OOM Killer介入触发在mapred-site.xml中设mapreduce.map.memory.mb8192而yarn.nodemanager.resource.memory-mb4096现象yarn application -list显示RUNNING但yarn logs -applicationId ...中Mapper日志为空dmesg | grep -i killed process显示Killed process 12345 (java) total-vm:8592128kB, anon-rss:4212345kB验证Linux OOM Killer因Container申请内存超限8GB NodeManager上报的4GB而杀死了JVM进程修复降低mapreduce.map.memory.mb至≤4096或提高yarn.nodemanager.resource.memory-mb这三个场景的共同启示是分布式系统没有“黑盒”。每一次kill、每一次rm、每一次dmesg都是对系统边界的主动探测。真正的掌控感来自你知道hdfs dfsadmin -report的输出里哪一行代表心跳超时哪一行代表副本缺失哪一行代表正在修复。7. 我的配置文件管理心得用git diff代替记忆用ansible脚本代替重复最后分享一个血泪教训别信自己的记忆力。我曾因记错core-site.xml里fs.defaultFS的端口在三台机器上手动改了六次配置每次改完都要stop-dfs.sh start-dfs.sh耗时42分钟。后来我建立了严格的配置管理流程7.1 所有配置文件纳入Git版本控制在node1上初始化仓库mkdir ~/hadoop-config cd ~/hadoop-config git init cp $HADOOP_HOME/etc/hadoop/*.xml . git add . git commit -m init config每次修改前先git status确认无未提交变更修改后git diff清晰显示改动行如- valuehdfs://node1:8020/value→ valuehdfs://node1:9000/value提交时写明原因git commit -m fix port mismatch: core-site.xml fs.defaultFS now matches dfs.namenode.rpc-address。这样任何配置漂移都能在5秒内定位。7.2 用Ansible批量同步配置编写deploy.yml- hosts: hadoop_nodes become: yes tasks: - name: Copy core-site.xml copy: src: ./core-site.xml dest: /opt/hadoop/etc/hadoop/core-site.xml owner: hdfs group: hdfs mode: 0644 - name: Restart HDFS shell: /opt/hadoop/sbin/stop-dfs.sh /opt/hadoop/sbin/start-dfs.sh args: executable: /bin/bash when: inventory_hostname node1执行ansible-playbook -i inventory deploy.yml三台机器配置秒级同步。Inventory文件定义节点分组[hadoop_master] node1 ansible_host192.168.56.101 [hadoop_slaves] node2 ansible_host192.168.56.102 node3 ansible_host192.168.56.103 [hadoop_nodes:children] hadoop_master hadoop_slaves7.3 日志归档策略用logrotate防止磁盘爆满/var/log/hadoop-*日志不压缩会迅速占满磁盘。在/etc/logrotate.d/hadoop中配置/var/log/hadoop-*/hadoop-*.log { daily missingok rotate 30 compress delaycompress notifempty create 644 hdfs hdfs sharedscripts postrotate if [ -f /var/run/hadoop-hdfs-namenode.pid ]; then kill -USR1 cat /var/run/hadoop-hdfs-namenode.pid fi endscript }postrotate段向NameNode发送USR1信号使其重新打开日志文件避免重启服务。这些工具不是炫技而是把“分布式”从玄学拉回工程——当你能用git blame查到某行配置是谁在何时为何修改当你能用ansible --check预演配置变更的影响当你能用logrotate -d /etc/logrotate.d/hadoop调试日志轮转逻辑你就真正拥有了对这个系统的掌控权。它不再是一堆神秘的服务而是一套可审计、可预测、可修复的工程产物。我在实际使用中发现最有效的学习方式不是读完所有文档而是选定一个最小可行目标比如让WordCount在三台机器上跑通然后主动制造故障、阅读日志、修改配置、验证结果。每一次tail -f的等待每一次jps的确认每一次hdfs fsck的扫描都在把抽象的“分布式”概念锻造成指尖可触的操作肌肉。这本笔记里没有终极答案只有我亲手踩过的坑、填过的坑、以及坑边上插的警示牌——愿你在自己的集群里也能听到那声清脆的“叮”。