简介这是一份面向大数据初学者的HDFS编程实践实验报告围绕Hadoop分布式文件系统的常用Shell命令与Java API基础操作展开适合正在学习Hadoop生态、需要完成课程实验或想强化HDFS动手能力的读者使用。压缩包内共有1个docx文档大小323KB文档完整收录了实验内容、实验目的、操作过程截图说明、实验总结及个人心得体会。实验过程覆盖了使用hdfs dfs -put、-get、-ls、-rm等命令完成文件导入导出、列表查看与删除操作以及通过touchz、mkdir、appendToFile等命令管理文件和目录Java API部分基于Maven项目配置Hadoop依赖使用org.apache.hadoop.fs.FileSystem类实现了文件创建、数据写入、信息读取和文件删除等功能并给出完整的代码示例与运行结果说明。资源已有2910人学习结构清晰、步骤完整既可直接参考用于完成同类实验也能帮助读者系统理解HDFS在Hadoop体系中的实际应用与分布式存储设计特点。1. HDFS编程实践到底在练什么一门实验课一座绕不过去的桥在接触大数据课程之前我一度以为分布式文件系统离自己很远。直到第一次坐在实验机前面对黑漆漆的终端和一行hadoop fs -ls才发现这门HDFS编程实践课真正要解决的不是「会不会敲命令」而是「文件分散在多台机器上时你要怎么跟它打交道」。它的核心价值很简单HDFS是大数据存储的地基MapReduce、Spark、Hive、Flink 全都要踩在它上面跑。把读写流程、权限模型、Java API 和命令行调通后续的每一门课都会轻松很多。这门实验课适合两类人第一类是刚把 Linux 和 Java 学完、准备进入大数据技术栈的学生第二类是工作中需要维护 Hadoop 集群、却只会在 Web UI 上点按钮的工程师。它会逼你自己写代码、自己处理权限和端口冲突而不是让它停留在「能跑就行」的层面。只要跟着本文把伪分布式环境搭起来、把读写删查都过一遍你就拿到了后面所有大数据组件实验的门票。2. HDFS编程实践前必须搞清的读写流程与权限模型2.1 HDFS读写流程为什么NameNode只管元数据DataNode才管数据HDFS 采用主从架构一个集群里有一个 NameNode 和若干个 DataNode。NameNode 只负责元数据——文件路径、目录树、文件分成了哪些块、每个块在哪些 DataNode 上真正的数据块存放在 DataNode 本地磁盘上。这个分工直接决定了你写代码时的调用方式所有 API 的请求都会先打给 NameNode再由它协调数据流向。写入一条文件的完整流程是这样的客户端调用DistributedFileSystem.create()向 NameNode 发起创建请求NameNode 检查路径是否存在、用户是否有权限、能否创建新文件然后返回一个带版本信息的数据流对象客户端开始往 DataNode 写第一个块这个块会按序号形成一个 DataNode 流水线把数据依次复制到副本节点上。默认副本数是 3意味着同一份数据会在三个节点上各存一份实验环境里通常改成 1 或 2节省磁盘也减少同步开销。读流程则是反向的客户端调用open()拿到文件的状态信息包括文件包含哪些块、每个块的存放位置然后按就近原则选择 DataNode 读取数据。HDFS 的块默认是 128MB 或 64MB大块的设计减少了寻址开销也意味着读取一个大文件只需要发起很少的块请求。记住一点写入需要 NameNode 全程参与协调而读取时 NameNode 只在最开始分配块位置之后客户端和 DataNode 直接通信不再经过它。这也是为什么 HDFS 适合大文件顺序读写、不适合大量小文件随机读的原因。写流程: Client - NameNode(创建/校验) - DataNode1 - DataNode2 - DataNode3 读流程: Client - NameNode(获取块位置) - 就近的DataNode - 本地合并数据这个流程图不用背但要在心里有数。实验课里最常见的失败就是「写不进去」和「读不到数据」根因往往都在流程的第一步NameNode 拒绝了你可能是权限问题也可能是路径不存在。2.2 权限与认证实验中最先翻车的三个细节HDFS 的权限模型沿用了 POSIX 风格的 owner、group、other 三元组每个文件或目录有读、写、执行三种权限。但和本地 Linux 文件系统有一个关键区别HDFS 的权限检查是「软检查」它不负责拦截所有非法操作只能防止正常客户端路径下的误操作。如果客户端通过底层协议直接访问 DataNode权限模型是拦不住的。实验里踩得最狠的第一个坑是你在 Linux 上用root用户启动了集群然后用hdfs用户或当前登录用户去执行 Java API。客户端发起请求时RPC 协议会把发起方的用户名带过去NameNode 拿这个用户名跟文件 owner 做比对。不一致时直接抛出Permission denied。解决方式有两种一是给目标目录授权比如hdfs dfs -chmod -R 777 /user二是在代码里显式指定用户身份Hadoop 的UserGroupInformation可以伪装成特定用户访问。第二个坑是supergroup。HDFS 里有一个超级用户的概念在简单认证模式下启动 NameNode 的本机用户自动成为超级用户。如果你用root启动了集群root就拥有所有权限如果你用hadoop用户启动那么root账号不一定能直接读写 HDFS需要在配置里把hadoop用户加入supergroup。实验里经常出现「直接在终端用 hdfs 命令能访问Java 代码一跑就权限不足」的怪象基本都跟这个有关。第三个坑是目录不存在。hdfs dfs -put上传文件时目标目录的父级目录不会自动创建。很多第一次做实验的人直接写/user/root/input结果/user/root根本不存在上传直接失败。记住先mkdir -p再put。这个习惯可以避免一半以上的操作失败。2.3 实验环境选择伪分布式、Docker还是云主机做 HDFS 编程实践环境选型很关键它直接决定你是把时间花在理解原理上还是花在修环境上。最常见的实验环境有三种。第一种是单机伪分布式。在一台 Linux 机器上把 NameNode、DataNode、SecondaryNameNode 全部跑起来通过start-dfs.sh一键启动。这个方案最适合课程实验因为配置简单、排错路径短所有日志都在本地出问题直接看logs目录就行。我一般会建议第一次学 HDFS 的人用这种方式它能把读写流程里涉及的角色都跑在真实进程里而不是抽象的理解。第二种是 Docker 容器编排。用 docker-compose 起一个 NameNode 和两三个 DataNode模拟真正的分布式环境。好处是贴近生产架构可以通过docker exec进入任意容器查看数据块分布缺点是网络配置和端口映射会消耗不少时间。对只想完成实验作业的同学这个方案有点重。第三种是云主机或实验室现成集群。很多学校的实验平台已经预装了 Hadoop学生只需要远程连接、上传代码就能跑。好处是省去搭建时间坏处是你对环境的掌控感会差很多遇到权限、端口问题没法直接改配置只能被平台规则卡住。如果你在实训平台上做完实验后总觉得心里没底我的建议是回到伪分布式环境里从头到尾自己跑一遍这才是真正的编程实践。3. 用HDFS常用命令筑基把实验要求的文件操作跑一遍3.1 启动集群与基础状态检查写 Java API 之前先把 HDFS 的命令行操作练熟。命令行的结果可以作为后续验证 API 代码的基准两边输出对得上才能说你的程序真的对了。假设你已经在 Linux 上装好了 Hadoop 并配置了HADOOP_HOME第一步是格式化文件系统。只有首次安装时需要格式化生成了 NameNode 的元数据目录之后不要反复执行否则 NameNode 和 DataNode 的集群 ID 不一致DataNode 会起不来。hdfs namenode -format start-dfs.sh jpsjps是 Java 虚拟机进程查看工具。格式化完成后执行start-dfs.sh再用jps查看进程你应该看到至少四个进程NameNode、DataNode、SecondaryNameNode和Jps本身。如果少了DataNode多半是格式化时遗留的集群 ID 冲突解决办法是删除数据目录/tmp/hadoop-*和logs里的残留文件重新格式化。这一步是后面所有操作的入口很多人的实验卡在第一步就是这个原因。3.2 常用文件操作命令put、get、mkdir、rm、catHDFS 命令行的调用方式和 Linux 本地命令几乎一一对应区别在于前缀从ls变成了hdfs dfs -ls。下面是实验里最常用的一组命令建议逐个在集群里跑一遍观察输出格式。# 创建用户目录-p 表示自动创建父目录 hdfs dfs -mkdir -p /user/experiment # 从本地文件系统上传文件到 HDFS hdfs dfs -put /home/student/data.txt /user/experiment/ # 查看 HDFS 上的文件列表-R 支持递归 hdfs dfs -ls -R /user/experiment # 查看文件内容仅适合小文件 hdfs dfs -cat /user/experiment/data.txt # 从 HDFS 下载文件到本地 hdfs dfs -get /user/experiment/data.txt /home/student/download/ # 删除文件或目录-rm 只删文件-rm -r 删目录 hdfs dfs -rm -r /user/experiment/data.txt-put命令的完整参数是hdfs dfs -put 本地路径 HDFS路径HDFS 路径的/user/experiment看起来像本地路径实际是在 HDFS 根目录下的user目录中创建的。注意-mkdir -p里的-p参数和 Linux 行为一致父目录不存在时自动创建。-cat只适合查看小文件对大文件会直接刷屏并且吃满网络带宽实验里可以用-head或者-tail看首尾。这一组命令跑完你基本就掌握了 HDFS 命令行操作的全貌。观察一下输出中每个文件的权限位、副本数和大小这列信息在下一节会用上-rw-r--r--是文件权限后面的数字是副本数文件名前的日期是修改时间。3.3 fsck与元数据检查文件块健康度怎么看文件上传之后怎么确认它真的按 HDFS 的方式被切块和复制了答案是hdfs fsck。这个命令扫描文件的数据块与副本分布输出块的健康状况。它在实验报告里是很好的佐证材料也是排查数据丢失问题的第一步。hdfs fsck /user/experiment/data.txt -files -blocks -locations-files输出文件的基本信息-blocks输出文件包含的每个块 ID-locations进一步列出每个块所在的 DataNode 主机名或 IP。跑完你会看到一个关键指标Healthy所有块都健康时显示HEALTHY存在缺失块时提示CORRUPT或MISSING。副本数据也会以类似Replicas: 3的形式展示如果实际副本数少于期望值说明有 DataNode 掉线或数据写入失败。fsck 不会修改任何数据它只做巡检。实验里可以故意删掉某个 DataNode 上的块文件再跑一次 fsck 看它怎么报错这是理解副本机制最直观的办法。不过要提醒一句不要在未授权或公用电脑上随便跑 fsck 并抓取全路径信息块位置会暴露节点内网拓扑这类巡检输出属于敏感信息做完实验记得保存到自己的实验报告里不要上传到公开代码仓库。生产集群的巡检一般由运维统一做轮不到实验客户端随便直连。4. 用Java API实现HDFS编程实践最小可运行代码4.1 项目结构与依赖Maven工程里要引什么命令行只是开胃菜实验课的核心是用 Java 代码操作 HDFS。这里我给出一个标准的 Maven 工程结构直接用dependency引入 Hadoop 客户端依赖不需要手动下载 jar 包。dependencies dependency groupIdorg.apache.hadoop/groupId artifactIdhadoop-client/artifactId version3.3.6/version /dependency /dependencieshadoop-client是一个聚合依赖会把hadoop-common、hadoop-hdfs、hadoop-mapreduce-client-core等核心模块一起带进来实验阶段不需要再单独引别的包。如果在 Windows 本地调试还需要额外处理winutils.exe和hadoop.dll最常见的做法是下载一个对应版本的hadoop-winutils放到HADOOP_HOME/bin下否则会抛出Failed to locate the winutils binary异常。我一般建议实验代码先在 Linux 上跑通再考虑 Windows 本地调试省去环境兼容的折腾。4.2 上传、下载、删除的完整示例从配置到运行下面这段代码是实验里最常用的「增删查」三件套覆盖了 Configuration、FileSystem 初始化、文件复制和删除。注释里标明了每个关键点的作用。import org.apache.hadoop.conf.Configuration; import org.apache.hadoop.fs.FileSystem; import org.apache.hadoop.fs.Path; import org.apache.hadoop.fs.FSDataInputStream; import org.apache.hadoop.fs.FSDataOutputStream; import java.io.BufferedReader; import java.io.InputStreamReader; import java.net.URI; public class HdfsClientDemo { public static void main(String[] args) throws Exception { // 1. 加载配置 Configuration conf new Configuration(); // 设置 HDFS 访问地址对应 core-site.xml 里的 fs.defaultFS conf.set(fs.defaultFS, hdfs://localhost:9000); // 指定客户端用户身份避免与集群启动用户不一致导致权限失败 FileSystem fs FileSystem.get(new URI(hdfs://localhost:9000), conf, root); // 2. 创建目录 Path dir new Path(/user/experiment/java-api); if (!fs.exists(dir)) { fs.mkdirs(dir); System.out.println(目录创建成功: dir); } // 3. 上传本地文件到 HDFS Path localFile new Path(/home/student/hello.txt); Path hdfsFile new Path(/user/experiment/java-api/hello.txt); fs.copyFromLocalFile(localFile, hdfsFile); System.out.println(上传完成: hdfsFile); // 4. 读取文件内容并打印 try (FSDataInputStream in fs.open(hdfsFile); BufferedReader reader new BufferedReader(new InputStreamReader(in))) { String line; while ((line reader.readLine()) ! null) { System.out.println(读取内容: line); } } // 5. 重命名文件 Path newName new Path(/user/experiment/java-api/hello-renamed.txt); boolean renamed fs.rename(hdfsFile, newName); System.out.println(重命名结果: renamed); // 6. 删除文件 boolean deleted fs.delete(newName, false); System.out.println(删除结果: deleted); // 7. 释放资源 fs.close(); } }这段代码的逻辑分三步先通过FileSystem.get()拿到文件系统实例这一步会建立到 NameNode 的 RPC 连接然后执行各种操作最后关闭资源。FileSystem.get()的三个参数分别指定 HDFS 地址、配置对象和用户名第三个参数解决了实验中最常见的权限问题——本地用户和集群启动用户不一致。copyFromLocalFile第一个参数是本地路径第二个是 HDFS 路径它内部完成的是「读本地文件 写 HDFS」两个动作对应命令行里的-put。fs.rename的返回值是布尔值失败时返回false但不会抛异常所以用返回值做确认比默认不检查更可靠。delete方法的第二个参数false表示只删除文件本身如果传true且目标是目录会递归删除整个目录。生产代码要谨慎使用true实验里无所谓但建议养成明确指定false的习惯避免误删。4.3 目录遍历与文件追加实验加分项基础三件套跑通后实验里还有两个加分操作遍历目录、追加写数据。目录遍历在实验报告中可以展示「代码能够读取 HDFS 目录树」追加写则对应 HDFS 的 append 特性。// 遍历目录 Path dir new Path(/user/experiment); FileStatus[] statuses fs.listStatus(dir); for (FileStatus status : statuses) { System.out.println(路径: status.getPath()); System.out.println(大小: status.getLen() bytes); System.out.println(副本数: status.getReplication()); System.out.println(是否为目录: status.isDirectory()); } // 追加写文件 Path appendFile new Path(/user/experiment/java-api/append.txt); try (FSDataOutputStream out fs.append(appendFile)) { out.writeBytes(这是一行追加的数据\n); out.hflush(); System.out.println(追加完成); }listStatus返回FileStatus数组每个对象记录了文件或目录的长度、副本数、块大小、修改时间等元数据。注意 HDFS 的append有前提条件文件必须已经存在且没有被其他客户端以写模式打开。如果文件不存在fs.append会直接抛FileNotFoundException所以追加前先create一次。hflush的作用是把缓冲区数据强制刷到 DataNode 的管道中但不等同于落盘实验里用它保证在进程退出前数据已发送到 HDFS。生产上高频 append 会导致文件块碎片化影响读取性能所以 append 适合日志聚合类场景不适合常规业务数据写入。5. HDFS编程实践避坑排查路径与5个高频翻车点5.1 本地Windows跑Java API连不上集群现象代码在 Linux 上能跑通把同一份工程搬到 Windows 本地运行时报Failed to connect to /127.0.0.1:9000或Connection refused。原因有两种可能。一是 Hadoop 客户端在本机找不到hadoop.dll和winutils.exe连接逻辑没有真正初始化二是 Windows 防火墙拦住了到虚拟机或远程服务器的 9000 端口。实验里 90% 的情况是前者。解决下载与 Hadoop 版本匹配的hadoop-winutils把bin目录解压到HADOOP_HOME下同时把hadoop.dll复制到C:\Windows\System32。然后在代码里手动设置System.setProperty(hadoop.home.dir, D:\\hadoop)。如果不行再检查core-site.xml里fs.defaultFS的 IP 是否和你的集群地址一致不要写localhost改成实际 IP。5.2 Cannot create directory /user/xxx. Name node is in safe mode现象执行mkdir或put时抛出Name node is in safe mode。原因NameNode 启动后会自动进入安全模式此时只接受读操作不接受写操作。安全模式是为了让 NameNode 先获取 DataNode 上报的块信息确认数据完整后再开放读写。实验环境里通常几秒钟就退出但如果 DataNode 启动慢或元数据异常会一直卡在安全模式。解决先等待 30 秒再用hdfs dfsadmin -safemode leave强制退出。更稳的做法是检查jps里 DataNode 是否正常如果 DataNode 进程不存在安全模式退出后很快会再次进入。检查logs/hadoop-hadoop-datanode-*.log常见原因是集群 ID 不一致或磁盘空间不足。5.3 访问 Web UI 端口9870 还是 50070现象浏览器打开http://localhost:50070显示连接失败但命令行操作正常。原因Hadoop 2.x 的 NameNode Web UI 默认端口是 50070Hadoop 3.x 改成了 9870。很多实验教程还在用旧端口照着敲必然打不开。解决打开http://localhost:9870。顺便记一下相关端口NameNode RPC 通信端口默认 9000 或 8020DataNode 通信端口默认 9866。实验里如果改了core-site.xml的fs.defaultFS不要只改 HTTP 端口RPC 端口不一致会直接导致客户端连不上。在实验报告里写明你用的 Hadoop 主版本端口参数就有据可查不用靠猜。5.4 代码里用 root 写一次换用户就读不到了现象上午用root用户跑put上传了文件下午换student用户写 Java API 去读抛Permission denied。原因HDFS 的权限是跟随文件 owner 的文件创建人是rootstudent属于 other 组而目录默认是 755 权限文件默认是 644other 组只有读权限不能写。如果做的是删除或重命名操作被拒就更明显。解决实验环境最简单的做法是在代码里用FileSystem.get(uri, conf, root)显式指定用户身份这样所有操作都落在root名下。更接近生产的方式是设置目录为hdfs dfs -chmod -R 777 /user/experiment但知道这个命令的人容易忽略一个细节chmod只对当前已存在的文件生效之后新建的文件还是默认权限。如果文件是反复变化的每次写代码前先授权或者干脆让代码统一指定用户省心得多。5.5 追加写抛 Append is not supported or file already closed现象fs.append()抛出FileAlreadyExistsException或Not a file。原因两种情况。一是文件根本不存在append 不会自动创建文件二是文件路径指向的是一个目录HDFS 不允许对目录执行追加写。还有一种隐蔽场景上一次create后没有调用close()文件句柄还处于打开状态二次追加时被集群拒绝。解决追加前强制检查文件存在性不存在时先create再追加。代码里每次写完都保证finally { out.close(); }不要依赖自动回收。调试时可以用hdfs dfs -ls确认目标路径类型写操作前先跑一次hdfs fsck看文件状态能省去大量猜测时间。6. 用命令行结果验证Java API一个能写进实验报告的对照方法最后一章不写新功能写一个验证技巧把第四章的 Java API 输出和第三章的 HDFS 命令行结果做交叉对照。这个习惯能帮你在提交实验报告前确认代码真正操作了 HDFS而不是只跑通了自己的逻辑。具体做法分三步。第一步用hdfs dfs -ls记录操作前/user/experiment/java-api目录下的文件清单第二步运行 Java 程序让它打印每一步的操作结果第三步操作后再执行hdfs dfs -ls -R和hdfs fsck /user/experiment/java-api -files -blocks对比文件是否创建、块数量是否合理、副本数是否符合配置。这个对比表直接放进实验报告比贴十行运行日志更有说服力。还有一个常用的小技巧在 Java 代码里显式打印FileStatus.getReplication()和getBlockSize()这两个值和fsck输出对得上就说明你的代码确实走了一遍 HDFS 的分布式写入流程而不是本地模拟。检查副本数时注意伪分布式环境下只有一个 DataNode即使fs.defaultFS里配置了 3 副本实际副本数也是 1这不是代码问题是环境限制实验报告里要写清楚这一点。我自己的习惯是把命令行的输出存成 log 文件和 Java 程序的输出一起归档每次实验后做一次双向核对。经历过一次「代码显示上传成功、数据实际没落到 HDFS」的翻车之后我就把这个对照检查养成了惯例。这份对照过程不需要额外的工具一条命令、一段输出就是你的实验结论。希望这套从读写流程到 Java API 再到验证方法的路径能帮你顺利走出机房也对 HDFS 真正建立起手感。本文还有配套的精品资源点击获取