HDFS 这套东西刚接触的时候很容易被分布式三个字唬住觉得离自己很远。但真到了要处理几十上百 GB 的日志、要把一堆机器上的数据当成一个整体来读写的时候你就会发现它的命令行和 Java API 其实相当朴素——朴素到有点反直觉。我前后在几个数据平台项目里跟 HDFS 打过交道从最开始只会hadoop fs -ls看目录到后来要写程序批量灌数据、做小文件合并、排查写入卡住的问题踩过的坑不算少。这篇就把 HDFS 的常用操作和编程实践掰开揉碎讲一遍命令行怎么用、Java API 怎么写、哪些参数不能乱调、哪些坑我亲自踩过都写清楚。不管你是刚上手大数据平台的新人还是已经能跑通 Demo 但一遇到真实数据就发怵的开发者应该都能从里面捞到点能直接抄作业的东西。1. 先把 HDFS 的脾气摸清楚再动手很多人一上来就背命令put、get、ls背得滚瓜烂熟结果真往集群里灌数据的时候发现速度慢得离谱或者程序跑着跑着报个Could not obtain block就懵了。问题不在命令本身而在于没搞明白 HDFS 到底是个什么性格的存储系统。它的设计取向和本地文件系统、和对象存储都不一样你顺着它的脾气来操作就顺逆着来处处别扭。1.1 它到底适合存什么、不适合存什么HDFS 的核心假设是一次写入、多次读取、超大文件、顺序访问。这几个词不是口号是直接决定你操作方式的底层约束。它把文件切成固定大小的块默认 128MB老版本是 64MB每块复制若干份默认 3 份散落在不同机器上元数据由 NameNode 统一管理。这个结构决定了它对大文件顺序读极其友好对大量小文件随机读写极其不友好。为什么小文件是灾难因为每个文件、每个块在 NameNode 内存里都要占一份元数据大约 150 字节量级。你存一百万个 10KB 的小文件实际数据才 10GB但 NameNode 要为此扛一百多万条元数据记录内存压力直接上来而且每次读都要跨节点找块延迟叠得吓人。所以我在实际项目里有个铁律进 HDFS 之前先做小文件合并能合成大文件就别散着放。这一点在后面编程实践那节我会给具体的合并思路。反过来什么场景适合它日志归档、离线批处理的数据集、数据仓库的底层存储、机器学习训练样本的集中存放——这些全是写一次、读很多次、文件大、顺序扫的典型。你要是想拿它当数据库做高频随机更新那从一开始就选错工具了。1.2 块、副本、机架感知三个绕不开的概念块Block是 HDFS 读写的最小单位。你写一个 300MB 的文件它会切成 128MB 128MB 44MB 三块。这个切分对使用者是透明的但你在调优和排错时必须心里有数——比如你看到某个文件有 3 个块就知道它至少涉及 3 次块级操作。副本Replication默认 3 份意味着同样 300MB 的数据集群里实际占 900MB。副本数可以在文件级别设置热数据可以调高冷数据可以调低省空间。我见过有人为了省磁盘把副本调成 1结果一台机器宕机数据直接丢这种操作在生产环境是绝对禁止的。机架感知Rack Awareness是副本放置的策略第一份放本地第二份放另一个机架第三份放第二个机架的另一个节点。这样既保证容错整个机架挂了还有副本又兼顾读带宽。你不需要手动管这个但要知道它的存在——当你发现写入速度受限于跨机架网络时就该想到这一层。提示副本数和块大小都是可以在建表/写文件时覆盖的但改之前先想清楚代价。块调大能减少元数据、提升大文件吞吐但会让最后一个块浪费空间、增加单块恢复时间块调小则相反。默认 128MB 是多年实践下来的平衡点没有特殊理由别乱动。1.3 命令行和 Java API 是什么关系HDFS 的操作入口主要有两个hadoop fs或hdfs dfs命令行和 Java 的FileSystemAPI。命令行适合交互式查看、临时搬运、脚本化运维Java API 适合把读写逻辑嵌进程序里做批处理。两者底层走的是同一套 RPC能力基本对等只是封装层次不同。有个细节新手常搞混hadoop fs是个通用文件系统客户端它能操作 HDFS也能操作本地文件系统用file:///前缀甚至其他兼容实现而hdfs dfs是专门针对 HDFS 的。日常用哪个都行我习惯用hadoop fs因为切换本地和 HDFS 路径时不用换命令。下面讲操作时我统一用hadoop fs。2. 命令行操作从看目录到批量搬运命令行是跟 HDFS 打交道的第一层也是最常用的一层。这一节我把高频命令按查看、上传下载、权限管理、空间统计几类拆开讲每条都说说它背后的行为而不是干巴巴列参数。2.1 查看类命令ls、cat、du、count 各有分工最基础的hadoop fs -ls /path列目录加-R递归。这里有个容易忽略的点-ls输出的每一行包含权限、副本数、所有者、组、大小、修改时间、路径其中副本数那一列在排查数据分布时特别有用——如果你发现某个文件副本数是 2 而不是预期的 3说明有副本丢了或者被手动改过得警惕。hadoop fs -cat /path/file直接把文件内容打到标准输出适合看小文件或者配合head、tail用管道截取。但千万别对几百 MB 的文件直接cat终端会被刷爆正确做法是hadoop fs -cat /path/file | head -n 100。hadoop fs -du -h /path看目录占用-h是人类可读单位。注意-du默认显示的是实际占用空间已经算上副本而hadoop fs -dus /path显示的是逻辑大小不含副本。这两个数经常差 3 倍别看到数字对不上就以为出问题了。hadoop fs -count /path更狠一次给你三列目录数、文件数、总逻辑大小。做数据盘点、估算小文件规模时我必用这条比ls -R | wc -l快得多也准得多。命令看什么典型用途hadoop fs -ls -R目录树详情排查文件分布、副本数hadoop fs -cat | head文件内容片段快速抽样看数据格式hadoop fs -du -h实际占用含副本评估磁盘压力hadoop fs -dus逻辑大小不含副本评估数据量本身hadoop fs -count目录数/文件数/大小数据盘点、小文件统计2.2 上传下载put、get、copyFromLocal 的取舍上传用hadoop fs -put localfile /hdfs/path下载用hadoop fs -get /hdfs/path localfile。这两个是最常用的。但还有一组容易混淆的-copyFromLocal和-moveFromLocal。-put和-copyFromLocal行为几乎一样都是复制本地文件保留-moveFromLocal则是移动本地源文件会被删掉。我一般用-put语义最直白。上传时有个高频坑目标路径已存在同名文件会报错。想覆盖得加-f。但覆盖是危险操作我建议在脚本里先判断再决定而不是无脑-f。另外上传大文件时-put是流式分块写的中途断了会留下不完整的块需要重新传所以大文件传输最好在网络稳定的时段做或者用支持断点的工具。下载时如果本地路径是个已存在的目录-get会把文件放进该目录下如果本地路径不存在它会当成文件名创建。这个行为跟cp类似但新手常因为路径写错导致文件散落一地。注意-put上传时如果本地有多个文件目标必须是目录单个文件目标可以是文件也可以是目录。批量上传用hadoop fs -put localdir/* /hdfs/dir/时注意 shell 通配符展开的是本地文件别把 HDFS 路径也写进通配范围。2.3 权限与属主chmod、chown、chgrp 的实际影响HDFS 的权限模型跟 POSIX 类似有 rwx 三组。hadoop fs -chmod 755 /path改权限-chown user:group /path改属主和组-chgrp group /path只改组。这些命令本身不难难的是理解谁在什么身份下执行。HDFS 默认开启权限检查dfs.permissions.enabledtrue你以哪个用户提交操作就以哪个用户身份去校验。在共享集群里如果程序用 A 用户跑、数据目录属主是 B 用户且权限是 700那 A 必然读写失败。我遇到过最典型的一次某同学本地用自己账号跑通了部署到调度平台用服务账号跑就报Permission denied查了半天才发现是目录属主问题。解决办法要么改目录权限要么用服务账号统一管理数据目录。还有个细节HDFS 的超级用户是启动 NameNode 的那个账号通常是hdfs它不受权限限制。所以运维层面常用超级用户做目录初始化和权限修复但业务程序绝不该用超级用户跑权限太大容易误伤。2.4 空间与健康检查df、fsck 怎么读hadoop fs -df -h /看集群整体容量输出已用、可用、使用率。这个数要定期盯使用率超过 80% 就该预警了因为 HDFS 在接近满的时候写入会变慢甚至失败要预留副本复制的空间。hadoop fs -fsck /path是健康检查利器它会扫描块的副本情况。加-files看文件级信息加-blocks看块级加-locations看每个块在哪些节点上。我最常用的是hadoop fs -fsck /path -files -blocks -locations输出里如果看到MISSING或副本数不足就说明有数据风险得尽快处理。-fsck对大目录会比较慢别在业务高峰期全量跑。3. Java API 编程把读写逻辑嵌进程序命令行能解决交互式操作但真正的批处理、数据管道、ETL 任务得靠 Java API 把读写逻辑写进程序。HDFS 的 Java 客户端核心就是org.apache.hadoop.fs.FileSystem这个抽象类围绕它做文章基本就够了。这一节从环境搭建讲到读写实操再到几个必须知道的坑。3.1 环境准备依赖和配置的最小集合用 Maven 的话核心依赖是hadoop-common和hadoop-client。版本要和集群对齐别用 3.x 的客户端连 2.x 的集群协议兼容性会出问题。一个最小依赖大概是这样dependency groupIdorg.apache.hadoop/groupId artifactIdhadoop-client/artifactId version3.3.4/version /dependency拿到FileSystem实例的标准姿势是通过Configuration加 URIConfiguration conf new Configuration(); conf.set(fs.defaultFS, hdfs://namenode-host:8020); FileSystem fs FileSystem.get(conf);这里有个关键点FileSystem.get()返回的是缓存实例同一个 JVM 里相同 URI 和相同用户身份会复用同一个对象。这意味着你不需要每次操作都新建但也要注意别在多线程里随意关闭它——一个线程关了其他线程再用就报错。我的做法是全局持有一个FileSystem程序退出时统一close()。如果集群开了高可用HAfs.defaultFS要配成逻辑名称比如hdfs://mycluster并把hdfs-site.xml和core-site.xml放进 classpath让客户端能读到 NameNode 的 HA 配置。只配一个物理地址在 HA 切换后会失效这是新手常踩的坑。3.2 读文件open 与 IOUtils 的配合读文件的标准流程是fs.open(path)拿到FSDataInputStream然后循环读或者用工具类拷贝到输出流Path path new Path(/data/sample.log); try (FSDataInputStream in fs.open(path); BufferedReader reader new BufferedReader(new InputStreamReader(in))) { String line; while ((line reader.readLine()) ! null) { // 处理每一行 } }FSDataInputStream支持seek()随机定位这对读大文件的某一段很有用但要注意 HDFS 的随机读性能远不如顺序读频繁 seek 会拖慢速度。如果只是逐行处理用BufferedReader包一层做缓冲能显著减少 RPC 次数。读的时候还有个隐藏成本每次open都要跟 NameNode 交互拿块位置。如果你要读成千上万个小文件NameNode 压力会很大。这种场景要么合并文件要么用FileSystem.listStatus批量拿元数据后集中处理减少往返。3.3 写文件create 的覆盖语义和 flush 时机写文件用fs.create(path)拿FSDataOutputStreamPath outPath new Path(/data/output/result.txt); try (FSDataOutputStream out fs.create(outPath, true)) { out.write(hello hdfs\n.getBytes(StandardCharsets.UTF_8)); }create的第二个参数是overwritetrue表示覆盖已存在文件false默认则在文件存在时抛FileAlreadyExistsException。这个默认值是有意为之的——防止误覆盖。我在生产代码里一律显式传参绝不依赖默认值因为读代码的人一眼就能看出意图。关于flushFSDataOutputStream有hflush()和hsync()两个方法。hflush把缓冲数据推到 DataNode 但不等落盘确认hsync则等到数据真正同步到磁盘。区别在于可靠性 vs 性能。普通批处理写完就 close不需要手动 flush但如果你写的是需要写完立即可见的场景比如流式写入后马上要被别的任务读就得用hsync代价是每次调用都有一次同步开销别在循环里频繁调。注意create默认副本数是 3块大小 128MB。要改的话用重载方法fs.create(path, overwrite, bufferSize, replication, blockSize)。副本数调低省空间但降可靠性块大小调大适合超大文件调之前想清楚。3.4 目录遍历与批量处理listStatus 和 globStatus批量处理数据时遍历目录是家常便饭。fs.listStatus(path)返回FileStatus[]每个元素带路径、大小、是否目录、修改时间等信息。递归遍历要自己写递归或者用fs.listFiles(path, true)——后者是递归版本返回RemoteIteratorLocatedFileStatus适合大目录因为它是流式迭代不会一次性把所有元数据拉进内存。RemoteIteratorLocatedFileStatus it fs.listFiles(new Path(/data/input), true); while (it.hasNext()) { LocatedFileStatus status it.next(); if (status.isFile()) { // 处理 status.getPath() } }fs.globStatus(hdfs:///data/2024-*/*.log)支持通配符匹配适合按日期分区取文件。但 glob 是在客户端展开的文件特别多时会有性能问题慎用于超大目录。4. 那些文档里不写、但一定会踩的坑前面讲的是怎么用这一节讲用的时候会怎么翻车。这些坑我基本都亲自踩过写出来是想让你少走弯路。每一条我都会说清楚现象、根因和排查思路而不是只给结论。4.1 小文件太多导致 NameNode 内存告急现象集群整体磁盘还有空间但写入越来越慢NameNode 日志里频繁出现 GC 告警hadoop fs -count显示文件数远超预期。根因前面说过每个文件每个块都占 NameNode 内存。大量小文件把元数据撑爆NameNode 的堆内存成为瓶颈。这不是磁盘问题是内存问题。排查链路先hadoop fs -count /path看文件数如果单个目录下文件数上百万基本可以确诊。再看 NameNode 的堆使用率通过 JMX 或监控面板如果长期高位就是元数据压力。解决思路合并小文件。离线场景可以用 MapReduce 或 Spark 做一次合并把多个小文件读进来写成一个大文件或者在上游就控制别让程序产生碎片。我做过一个日志归档任务原始每天产生几十万个小文件合并成按小时的大文件后文件数降了两个数量级NameNode 压力立刻缓解。4.2 写入卡住DataNode 磁盘满或网络抖动现象程序write调用长时间不返回或者报Slow Write、DataStreamer Exception。根因HDFS 写入是流水线式的——客户端写第一个 DataNode它转发给第二个再转发给第三个。流水线上任何一环慢或挂整条链都卡。常见原因是某个 DataNode 磁盘满了、磁盘 IO 打满或者节点间网络抖动。排查链路先看客户端日志里的异常堆栈通常会指出是哪个 DataNode 出问题。然后去那个节点看磁盘使用率df -h和 DataNode 日志。如果磁盘满清理或扩容如果是网络问题看交换机监控。HDFS 有副本机制单个节点故障通常能自动恢复但写入过程中的卡顿会传导到客户端。经验写入超时参数dfs.client.socket-timeout和dfs.datanode.socket.write.timeout可以调但调大只是掩盖问题不是解决。真正的解法是保证 DataNode 磁盘水位健康留 20% 以上余量和网络稳定。4.3 权限报错不是 chmod 就能解决现象Permission denied: userxxx, accessWRITE, inode/path。根因前面提过HDFS 按提交操作的用户身份校验。程序跑在哪个账号下就用哪个账号的权限。常见于调度平台用服务账号跑任务但数据目录属主是别人。排查链路先确认程序实际运行的用户whoami或日志里的 user 字段再hadoop fs -ls看目标目录的属主和权限两者对不上就是权限问题。解决要么改目录权限/属主-chmod、-chown要么让程序用有权限的账号跑。我倾向于按业务划分目录并统一属主比如每个业务线一个顶层目录属主设成该业务的服务账号避免跨账号乱改权限。4.4 HA 切换后客户端连不上现象集群做了 NameNode 高可用某次主备切换后客户端程序突然连不上报连接超时或StandbyException。根因客户端配置里写死了某个 NameNode 的物理地址切换后那个地址变成 Standby不接收写请求。或者客户端没加载 HA 配置不知道另一个 NameNode 的存在。排查链路看客户端Configuration里fs.defaultFS配的是什么。如果是具体主机名而非逻辑名称基本就是这个问题。再看 classpath 里有没有hdfs-site.xmlHA 配置在里面。解决fs.defaultFS配成逻辑名称确保core-site.xml和hdfs-site.xml在 classpath 里让客户端能自动发现 Active NameNode。这是 HA 环境的标准配置别图省事写死地址。5. 让操作更稳的几个实践习惯讲完坑再聊聊我这些年养成的几个习惯。这些不是什么高深技巧但坚持下来能省很多事。5.1 路径永远用绝对路径别依赖当前目录HDFS 没有当前工作目录的概念虽然客户端有个默认工作目录但很容易变。我在代码和脚本里一律用绝对路径/data/xxx从不写相对路径。原因是相对路径依赖fs.defaultFS和工作目录配置换个环境就可能指到别处排查起来极其费劲。绝对路径虽然长但意图明确、可移植。5.2 大文件操作前先看 fsck 和 count往一个目录灌数据前我习惯先hadoop fs -count看现有规模hadoop fs -fsck看健康度。如果目录里已经有大量小文件或者有副本缺失先处理再灌别让问题叠加。这个习惯帮我避免过好几次灌到一半发现目录本身有问题的尴尬。5.3 程序里给 FileSystem 加生命周期管理FileSystem是重对象创建有开销但也不能永不关闭。我的做法是在应用启动时初始化一个单例注册 JVM 关闭钩子统一close()。这样既避免了频繁创建又保证资源释放。多线程共享时注意FileSystem本身是线程安全的大部分操作但FSDataOutputStream不是别跨线程写同一个流。5.4 批量任务加失败重试和断点记录HDFS 操作偶尔会因为网络抖动失败尤其是跨机房、大批量的时候。我在批量任务里会给每个文件的处理加 try-catch 和重试比如重试 3 次、间隔递增并把已成功的文件路径记录到本地或另一个 HDFS 文件里失败重跑时跳过已完成的。这个断点续跑机制在处理几十万文件的任务时是救命稻草不然一次失败全量重来时间成本扛不住。5.5 副本数和块大小按数据温度调热数据频繁读副本可以保持 3 甚至调高冷数据归档可以降到 2 省空间。块大小对大文件可以适当调大比如 256MB减少元数据但别超过单机磁盘的合理范围。这些调整要在建目录或写文件时定好事后改副本数虽然可以hadoop fs -setrep但会触发大量数据复制挑低峰期做。实践习惯解决的问题代价/注意绝对路径环境切换路径错乱路径较长需规范目录结构操作前 fsck/count问题叠加大目录扫描慢避开高峰FileSystem 单例关闭钩子资源泄漏/频繁创建注意线程安全边界失败重试断点记录批量任务全量重跑需额外存储进度状态按温度调副本/块大小空间与性能平衡事后调整触发数据复制6. 一个完整的读写小例子串起来光讲概念容易散我把前面这些点串成一个能跑的小例子从本地读一个文本文件过滤出含关键字的行写到 HDFS 的目标路径同时打印进度。这个例子虽小但覆盖了FileSystem获取、读、写、异常处理、资源关闭几个关键环节。public class HdfsFilterDemo { public static void main(String[] args) throws Exception { Configuration conf new Configuration(); conf.set(fs.defaultFS, hdfs://namenode-host:8020); FileSystem fs FileSystem.get(conf); Path src new Path(/data/input/raw.log); Path dst new Path(/data/output/filtered.log); String keyword ERROR; long total 0, matched 0; try (FSDataInputStream in fs.open(src); BufferedReader reader new BufferedReader(new InputStreamReader(in, StandardCharsets.UTF_8)); FSDataOutputStream out fs.create(dst, true)) { String line; while ((line reader.readLine()) ! null) { total; if (line.contains(keyword)) { out.write((line \n).getBytes(StandardCharsets.UTF_8)); matched; } } out.hsync(); } finally { fs.close(); } System.out.printf(total%d, matched%d%n, total, matched); } }这段代码里有几个值得说的点。第一try-with-resources同时管理了输入流、Reader 和输出流保证异常时也能关闭。第二fs.create(dst, true)显式覆盖意图清楚。第三循环结束后调了hsync()确保数据落盘再退出——如果这个输出马上要被下游任务读这一步不能省。第四fs.close()放在 finally 里虽然单例场景下更推荐关闭钩子但小 Demo 这样写足够清晰。实际生产里这个例子还要加上输入路径的存在性校验fs.exists、输出目录的自动创建fs.mkdirs、失败重试、以及把total/matched这类统计写到监控。但骨架就是这些把骨架跑通剩下的都是往上面加肉。7. 关于选型和边界的一点个人看法最后聊点偏判断的东西。HDFS 不是万能的什么时候该用它、什么时候该换工具这个判断比会敲命令更重要。我的经验是数据量大、写一次读多次、顺序访问为主、能容忍一定延迟——满足这几条HDFS 就是好选择。反过来需要低延迟随机读写、需要频繁更新单条记录、数据量其实不大几个 GB 以内那用本地文件系统或者别的存储更合适硬上 HDFS 只会增加复杂度。另外现在很多场景其实是在 HDFS 之上套了一层计算引擎比如批处理框架你直接操作 HDFS 的机会可能没那么多。但底层原理和这些操作是绕不开的——计算引擎读写数据最终都落到 HDFS 的块和副本上你理解了put、get、create、open这些底层行为排查上层任务的问题时才有抓手。我见过太多人只会写 SQL 或调 API一遇到数据倾斜导致某节点写入慢就束手无策根子还是没摸清存储层。至于编程实践我的建议是先把FileSystem的读写、遍历、权限这几块练熟再去看计算框架怎么封装它。顺序反了容易只知其然。真到了要优化的时候小文件合并、副本策略、块大小这几个杠杆配合fsck和count的观测基本能解决八成问题。剩下的两成多半是集群层面的资源和网络问题那就得跟运维一起看了。
HDFS 这套东西刚接触的时候很容易被分布式三个字唬住觉得离自己很远。但真到了要处理几十上百 GB 的日志、要把一堆机器上的数据当成一个整体来读写的时候你就会发现它的命令行和 Java API 其实相当朴素——朴素到有点反直觉。我前后在几个数据平台项目里跟 HDFS 打过交道从最开始只会hadoop fs -ls看目录到后来要写程序批量灌数据、做小文件合并、排查写入卡住的问题踩过的坑不算少。这篇就把 HDFS 的常用操作和编程实践掰开揉碎讲一遍命令行怎么用、Java API 怎么写、哪些参数不能乱调、哪些坑我亲自踩过都写清楚。不管你是刚上手大数据平台的新人还是已经能跑通 Demo 但一遇到真实数据就发怵的开发者应该都能从里面捞到点能直接抄作业的东西。1. 先把 HDFS 的脾气摸清楚再动手很多人一上来就背命令put、get、ls背得滚瓜烂熟结果真往集群里灌数据的时候发现速度慢得离谱或者程序跑着跑着报个Could not obtain block就懵了。问题不在命令本身而在于没搞明白 HDFS 到底是个什么性格的存储系统。它的设计取向和本地文件系统、和对象存储都不一样你顺着它的脾气来操作就顺逆着来处处别扭。1.1 它到底适合存什么、不适合存什么HDFS 的核心假设是一次写入、多次读取、超大文件、顺序访问。这几个词不是口号是直接决定你操作方式的底层约束。它把文件切成固定大小的块默认 128MB老版本是 64MB每块复制若干份默认 3 份散落在不同机器上元数据由 NameNode 统一管理。这个结构决定了它对大文件顺序读极其友好对大量小文件随机读写极其不友好。为什么小文件是灾难因为每个文件、每个块在 NameNode 内存里都要占一份元数据大约 150 字节量级。你存一百万个 10KB 的小文件实际数据才 10GB但 NameNode 要为此扛一百多万条元数据记录内存压力直接上来而且每次读都要跨节点找块延迟叠得吓人。所以我在实际项目里有个铁律进 HDFS 之前先做小文件合并能合成大文件就别散着放。这一点在后面编程实践那节我会给具体的合并思路。反过来什么场景适合它日志归档、离线批处理的数据集、数据仓库的底层存储、机器学习训练样本的集中存放——这些全是写一次、读很多次、文件大、顺序扫的典型。你要是想拿它当数据库做高频随机更新那从一开始就选错工具了。1.2 块、副本、机架感知三个绕不开的概念块Block是 HDFS 读写的最小单位。你写一个 300MB 的文件它会切成 128MB 128MB 44MB 三块。这个切分对使用者是透明的但你在调优和排错时必须心里有数——比如你看到某个文件有 3 个块就知道它至少涉及 3 次块级操作。副本Replication默认 3 份意味着同样 300MB 的数据集群里实际占 900MB。副本数可以在文件级别设置热数据可以调高冷数据可以调低省空间。我见过有人为了省磁盘把副本调成 1结果一台机器宕机数据直接丢这种操作在生产环境是绝对禁止的。机架感知Rack Awareness是副本放置的策略第一份放本地第二份放另一个机架第三份放第二个机架的另一个节点。这样既保证容错整个机架挂了还有副本又兼顾读带宽。你不需要手动管这个但要知道它的存在——当你发现写入速度受限于跨机架网络时就该想到这一层。提示副本数和块大小都是可以在建表/写文件时覆盖的但改之前先想清楚代价。块调大能减少元数据、提升大文件吞吐但会让最后一个块浪费空间、增加单块恢复时间块调小则相反。默认 128MB 是多年实践下来的平衡点没有特殊理由别乱动。1.3 命令行和 Java API 是什么关系HDFS 的操作入口主要有两个hadoop fs或hdfs dfs命令行和 Java 的FileSystemAPI。命令行适合交互式查看、临时搬运、脚本化运维Java API 适合把读写逻辑嵌进程序里做批处理。两者底层走的是同一套 RPC能力基本对等只是封装层次不同。有个细节新手常搞混hadoop fs是个通用文件系统客户端它能操作 HDFS也能操作本地文件系统用file:///前缀甚至其他兼容实现而hdfs dfs是专门针对 HDFS 的。日常用哪个都行我习惯用hadoop fs因为切换本地和 HDFS 路径时不用换命令。下面讲操作时我统一用hadoop fs。2. 命令行操作从看目录到批量搬运命令行是跟 HDFS 打交道的第一层也是最常用的一层。这一节我把高频命令按查看、上传下载、权限管理、空间统计几类拆开讲每条都说说它背后的行为而不是干巴巴列参数。2.1 查看类命令ls、cat、du、count 各有分工最基础的hadoop fs -ls /path列目录加-R递归。这里有个容易忽略的点-ls输出的每一行包含权限、副本数、所有者、组、大小、修改时间、路径其中副本数那一列在排查数据分布时特别有用——如果你发现某个文件副本数是 2 而不是预期的 3说明有副本丢了或者被手动改过得警惕。hadoop fs -cat /path/file直接把文件内容打到标准输出适合看小文件或者配合head、tail用管道截取。但千万别对几百 MB 的文件直接cat终端会被刷爆正确做法是hadoop fs -cat /path/file | head -n 100。hadoop fs -du -h /path看目录占用-h是人类可读单位。注意-du默认显示的是实际占用空间已经算上副本而hadoop fs -dus /path显示的是逻辑大小不含副本。这两个数经常差 3 倍别看到数字对不上就以为出问题了。hadoop fs -count /path更狠一次给你三列目录数、文件数、总逻辑大小。做数据盘点、估算小文件规模时我必用这条比ls -R | wc -l快得多也准得多。命令看什么典型用途hadoop fs -ls -R目录树详情排查文件分布、副本数hadoop fs -cat | head文件内容片段快速抽样看数据格式hadoop fs -du -h实际占用含副本评估磁盘压力hadoop fs -dus逻辑大小不含副本评估数据量本身hadoop fs -count目录数/文件数/大小数据盘点、小文件统计2.2 上传下载put、get、copyFromLocal 的取舍上传用hadoop fs -put localfile /hdfs/path下载用hadoop fs -get /hdfs/path localfile。这两个是最常用的。但还有一组容易混淆的-copyFromLocal和-moveFromLocal。-put和-copyFromLocal行为几乎一样都是复制本地文件保留-moveFromLocal则是移动本地源文件会被删掉。我一般用-put语义最直白。上传时有个高频坑目标路径已存在同名文件会报错。想覆盖得加-f。但覆盖是危险操作我建议在脚本里先判断再决定而不是无脑-f。另外上传大文件时-put是流式分块写的中途断了会留下不完整的块需要重新传所以大文件传输最好在网络稳定的时段做或者用支持断点的工具。下载时如果本地路径是个已存在的目录-get会把文件放进该目录下如果本地路径不存在它会当成文件名创建。这个行为跟cp类似但新手常因为路径写错导致文件散落一地。注意-put上传时如果本地有多个文件目标必须是目录单个文件目标可以是文件也可以是目录。批量上传用hadoop fs -put localdir/* /hdfs/dir/时注意 shell 通配符展开的是本地文件别把 HDFS 路径也写进通配范围。2.3 权限与属主chmod、chown、chgrp 的实际影响HDFS 的权限模型跟 POSIX 类似有 rwx 三组。hadoop fs -chmod 755 /path改权限-chown user:group /path改属主和组-chgrp group /path只改组。这些命令本身不难难的是理解谁在什么身份下执行。HDFS 默认开启权限检查dfs.permissions.enabledtrue你以哪个用户提交操作就以哪个用户身份去校验。在共享集群里如果程序用 A 用户跑、数据目录属主是 B 用户且权限是 700那 A 必然读写失败。我遇到过最典型的一次某同学本地用自己账号跑通了部署到调度平台用服务账号跑就报Permission denied查了半天才发现是目录属主问题。解决办法要么改目录权限要么用服务账号统一管理数据目录。还有个细节HDFS 的超级用户是启动 NameNode 的那个账号通常是hdfs它不受权限限制。所以运维层面常用超级用户做目录初始化和权限修复但业务程序绝不该用超级用户跑权限太大容易误伤。2.4 空间与健康检查df、fsck 怎么读hadoop fs -df -h /看集群整体容量输出已用、可用、使用率。这个数要定期盯使用率超过 80% 就该预警了因为 HDFS 在接近满的时候写入会变慢甚至失败要预留副本复制的空间。hadoop fs -fsck /path是健康检查利器它会扫描块的副本情况。加-files看文件级信息加-blocks看块级加-locations看每个块在哪些节点上。我最常用的是hadoop fs -fsck /path -files -blocks -locations输出里如果看到MISSING或副本数不足就说明有数据风险得尽快处理。-fsck对大目录会比较慢别在业务高峰期全量跑。3. Java API 编程把读写逻辑嵌进程序命令行能解决交互式操作但真正的批处理、数据管道、ETL 任务得靠 Java API 把读写逻辑写进程序。HDFS 的 Java 客户端核心就是org.apache.hadoop.fs.FileSystem这个抽象类围绕它做文章基本就够了。这一节从环境搭建讲到读写实操再到几个必须知道的坑。3.1 环境准备依赖和配置的最小集合用 Maven 的话核心依赖是hadoop-common和hadoop-client。版本要和集群对齐别用 3.x 的客户端连 2.x 的集群协议兼容性会出问题。一个最小依赖大概是这样dependency groupIdorg.apache.hadoop/groupId artifactIdhadoop-client/artifactId version3.3.4/version /dependency拿到FileSystem实例的标准姿势是通过Configuration加 URIConfiguration conf new Configuration(); conf.set(fs.defaultFS, hdfs://namenode-host:8020); FileSystem fs FileSystem.get(conf);这里有个关键点FileSystem.get()返回的是缓存实例同一个 JVM 里相同 URI 和相同用户身份会复用同一个对象。这意味着你不需要每次操作都新建但也要注意别在多线程里随意关闭它——一个线程关了其他线程再用就报错。我的做法是全局持有一个FileSystem程序退出时统一close()。如果集群开了高可用HAfs.defaultFS要配成逻辑名称比如hdfs://mycluster并把hdfs-site.xml和core-site.xml放进 classpath让客户端能读到 NameNode 的 HA 配置。只配一个物理地址在 HA 切换后会失效这是新手常踩的坑。3.2 读文件open 与 IOUtils 的配合读文件的标准流程是fs.open(path)拿到FSDataInputStream然后循环读或者用工具类拷贝到输出流Path path new Path(/data/sample.log); try (FSDataInputStream in fs.open(path); BufferedReader reader new BufferedReader(new InputStreamReader(in))) { String line; while ((line reader.readLine()) ! null) { // 处理每一行 } }FSDataInputStream支持seek()随机定位这对读大文件的某一段很有用但要注意 HDFS 的随机读性能远不如顺序读频繁 seek 会拖慢速度。如果只是逐行处理用BufferedReader包一层做缓冲能显著减少 RPC 次数。读的时候还有个隐藏成本每次open都要跟 NameNode 交互拿块位置。如果你要读成千上万个小文件NameNode 压力会很大。这种场景要么合并文件要么用FileSystem.listStatus批量拿元数据后集中处理减少往返。3.3 写文件create 的覆盖语义和 flush 时机写文件用fs.create(path)拿FSDataOutputStreamPath outPath new Path(/data/output/result.txt); try (FSDataOutputStream out fs.create(outPath, true)) { out.write(hello hdfs\n.getBytes(StandardCharsets.UTF_8)); }create的第二个参数是overwritetrue表示覆盖已存在文件false默认则在文件存在时抛FileAlreadyExistsException。这个默认值是有意为之的——防止误覆盖。我在生产代码里一律显式传参绝不依赖默认值因为读代码的人一眼就能看出意图。关于flushFSDataOutputStream有hflush()和hsync()两个方法。hflush把缓冲数据推到 DataNode 但不等落盘确认hsync则等到数据真正同步到磁盘。区别在于可靠性 vs 性能。普通批处理写完就 close不需要手动 flush但如果你写的是需要写完立即可见的场景比如流式写入后马上要被别的任务读就得用hsync代价是每次调用都有一次同步开销别在循环里频繁调。注意create默认副本数是 3块大小 128MB。要改的话用重载方法fs.create(path, overwrite, bufferSize, replication, blockSize)。副本数调低省空间但降可靠性块大小调大适合超大文件调之前想清楚。3.4 目录遍历与批量处理listStatus 和 globStatus批量处理数据时遍历目录是家常便饭。fs.listStatus(path)返回FileStatus[]每个元素带路径、大小、是否目录、修改时间等信息。递归遍历要自己写递归或者用fs.listFiles(path, true)——后者是递归版本返回RemoteIteratorLocatedFileStatus适合大目录因为它是流式迭代不会一次性把所有元数据拉进内存。RemoteIteratorLocatedFileStatus it fs.listFiles(new Path(/data/input), true); while (it.hasNext()) { LocatedFileStatus status it.next(); if (status.isFile()) { // 处理 status.getPath() } }fs.globStatus(hdfs:///data/2024-*/*.log)支持通配符匹配适合按日期分区取文件。但 glob 是在客户端展开的文件特别多时会有性能问题慎用于超大目录。4. 那些文档里不写、但一定会踩的坑前面讲的是怎么用这一节讲用的时候会怎么翻车。这些坑我基本都亲自踩过写出来是想让你少走弯路。每一条我都会说清楚现象、根因和排查思路而不是只给结论。4.1 小文件太多导致 NameNode 内存告急现象集群整体磁盘还有空间但写入越来越慢NameNode 日志里频繁出现 GC 告警hadoop fs -count显示文件数远超预期。根因前面说过每个文件每个块都占 NameNode 内存。大量小文件把元数据撑爆NameNode 的堆内存成为瓶颈。这不是磁盘问题是内存问题。排查链路先hadoop fs -count /path看文件数如果单个目录下文件数上百万基本可以确诊。再看 NameNode 的堆使用率通过 JMX 或监控面板如果长期高位就是元数据压力。解决思路合并小文件。离线场景可以用 MapReduce 或 Spark 做一次合并把多个小文件读进来写成一个大文件或者在上游就控制别让程序产生碎片。我做过一个日志归档任务原始每天产生几十万个小文件合并成按小时的大文件后文件数降了两个数量级NameNode 压力立刻缓解。4.2 写入卡住DataNode 磁盘满或网络抖动现象程序write调用长时间不返回或者报Slow Write、DataStreamer Exception。根因HDFS 写入是流水线式的——客户端写第一个 DataNode它转发给第二个再转发给第三个。流水线上任何一环慢或挂整条链都卡。常见原因是某个 DataNode 磁盘满了、磁盘 IO 打满或者节点间网络抖动。排查链路先看客户端日志里的异常堆栈通常会指出是哪个 DataNode 出问题。然后去那个节点看磁盘使用率df -h和 DataNode 日志。如果磁盘满清理或扩容如果是网络问题看交换机监控。HDFS 有副本机制单个节点故障通常能自动恢复但写入过程中的卡顿会传导到客户端。经验写入超时参数dfs.client.socket-timeout和dfs.datanode.socket.write.timeout可以调但调大只是掩盖问题不是解决。真正的解法是保证 DataNode 磁盘水位健康留 20% 以上余量和网络稳定。4.3 权限报错不是 chmod 就能解决现象Permission denied: userxxx, accessWRITE, inode/path。根因前面提过HDFS 按提交操作的用户身份校验。程序跑在哪个账号下就用哪个账号的权限。常见于调度平台用服务账号跑任务但数据目录属主是别人。排查链路先确认程序实际运行的用户whoami或日志里的 user 字段再hadoop fs -ls看目标目录的属主和权限两者对不上就是权限问题。解决要么改目录权限/属主-chmod、-chown要么让程序用有权限的账号跑。我倾向于按业务划分目录并统一属主比如每个业务线一个顶层目录属主设成该业务的服务账号避免跨账号乱改权限。4.4 HA 切换后客户端连不上现象集群做了 NameNode 高可用某次主备切换后客户端程序突然连不上报连接超时或StandbyException。根因客户端配置里写死了某个 NameNode 的物理地址切换后那个地址变成 Standby不接收写请求。或者客户端没加载 HA 配置不知道另一个 NameNode 的存在。排查链路看客户端Configuration里fs.defaultFS配的是什么。如果是具体主机名而非逻辑名称基本就是这个问题。再看 classpath 里有没有hdfs-site.xmlHA 配置在里面。解决fs.defaultFS配成逻辑名称确保core-site.xml和hdfs-site.xml在 classpath 里让客户端能自动发现 Active NameNode。这是 HA 环境的标准配置别图省事写死地址。5. 让操作更稳的几个实践习惯讲完坑再聊聊我这些年养成的几个习惯。这些不是什么高深技巧但坚持下来能省很多事。5.1 路径永远用绝对路径别依赖当前目录HDFS 没有当前工作目录的概念虽然客户端有个默认工作目录但很容易变。我在代码和脚本里一律用绝对路径/data/xxx从不写相对路径。原因是相对路径依赖fs.defaultFS和工作目录配置换个环境就可能指到别处排查起来极其费劲。绝对路径虽然长但意图明确、可移植。5.2 大文件操作前先看 fsck 和 count往一个目录灌数据前我习惯先hadoop fs -count看现有规模hadoop fs -fsck看健康度。如果目录里已经有大量小文件或者有副本缺失先处理再灌别让问题叠加。这个习惯帮我避免过好几次灌到一半发现目录本身有问题的尴尬。5.3 程序里给 FileSystem 加生命周期管理FileSystem是重对象创建有开销但也不能永不关闭。我的做法是在应用启动时初始化一个单例注册 JVM 关闭钩子统一close()。这样既避免了频繁创建又保证资源释放。多线程共享时注意FileSystem本身是线程安全的大部分操作但FSDataOutputStream不是别跨线程写同一个流。5.4 批量任务加失败重试和断点记录HDFS 操作偶尔会因为网络抖动失败尤其是跨机房、大批量的时候。我在批量任务里会给每个文件的处理加 try-catch 和重试比如重试 3 次、间隔递增并把已成功的文件路径记录到本地或另一个 HDFS 文件里失败重跑时跳过已完成的。这个断点续跑机制在处理几十万文件的任务时是救命稻草不然一次失败全量重来时间成本扛不住。5.5 副本数和块大小按数据温度调热数据频繁读副本可以保持 3 甚至调高冷数据归档可以降到 2 省空间。块大小对大文件可以适当调大比如 256MB减少元数据但别超过单机磁盘的合理范围。这些调整要在建目录或写文件时定好事后改副本数虽然可以hadoop fs -setrep但会触发大量数据复制挑低峰期做。实践习惯解决的问题代价/注意绝对路径环境切换路径错乱路径较长需规范目录结构操作前 fsck/count问题叠加大目录扫描慢避开高峰FileSystem 单例关闭钩子资源泄漏/频繁创建注意线程安全边界失败重试断点记录批量任务全量重跑需额外存储进度状态按温度调副本/块大小空间与性能平衡事后调整触发数据复制6. 一个完整的读写小例子串起来光讲概念容易散我把前面这些点串成一个能跑的小例子从本地读一个文本文件过滤出含关键字的行写到 HDFS 的目标路径同时打印进度。这个例子虽小但覆盖了FileSystem获取、读、写、异常处理、资源关闭几个关键环节。public class HdfsFilterDemo { public static void main(String[] args) throws Exception { Configuration conf new Configuration(); conf.set(fs.defaultFS, hdfs://namenode-host:8020); FileSystem fs FileSystem.get(conf); Path src new Path(/data/input/raw.log); Path dst new Path(/data/output/filtered.log); String keyword ERROR; long total 0, matched 0; try (FSDataInputStream in fs.open(src); BufferedReader reader new BufferedReader(new InputStreamReader(in, StandardCharsets.UTF_8)); FSDataOutputStream out fs.create(dst, true)) { String line; while ((line reader.readLine()) ! null) { total; if (line.contains(keyword)) { out.write((line \n).getBytes(StandardCharsets.UTF_8)); matched; } } out.hsync(); } finally { fs.close(); } System.out.printf(total%d, matched%d%n, total, matched); } }这段代码里有几个值得说的点。第一try-with-resources同时管理了输入流、Reader 和输出流保证异常时也能关闭。第二fs.create(dst, true)显式覆盖意图清楚。第三循环结束后调了hsync()确保数据落盘再退出——如果这个输出马上要被下游任务读这一步不能省。第四fs.close()放在 finally 里虽然单例场景下更推荐关闭钩子但小 Demo 这样写足够清晰。实际生产里这个例子还要加上输入路径的存在性校验fs.exists、输出目录的自动创建fs.mkdirs、失败重试、以及把total/matched这类统计写到监控。但骨架就是这些把骨架跑通剩下的都是往上面加肉。7. 关于选型和边界的一点个人看法最后聊点偏判断的东西。HDFS 不是万能的什么时候该用它、什么时候该换工具这个判断比会敲命令更重要。我的经验是数据量大、写一次读多次、顺序访问为主、能容忍一定延迟——满足这几条HDFS 就是好选择。反过来需要低延迟随机读写、需要频繁更新单条记录、数据量其实不大几个 GB 以内那用本地文件系统或者别的存储更合适硬上 HDFS 只会增加复杂度。另外现在很多场景其实是在 HDFS 之上套了一层计算引擎比如批处理框架你直接操作 HDFS 的机会可能没那么多。但底层原理和这些操作是绕不开的——计算引擎读写数据最终都落到 HDFS 的块和副本上你理解了put、get、create、open这些底层行为排查上层任务的问题时才有抓手。我见过太多人只会写 SQL 或调 API一遇到数据倾斜导致某节点写入慢就束手无策根子还是没摸清存储层。至于编程实践我的建议是先把FileSystem的读写、遍历、权限这几块练熟再去看计算框架怎么封装它。顺序反了容易只知其然。真到了要优化的时候小文件合并、副本策略、块大小这几个杠杆配合fsck和count的观测基本能解决八成问题。剩下的两成多半是集群层面的资源和网络问题那就得跟运维一起看了。
