1. 从一次数据搬迁聊起HDFS上传下载到底在干什么刚接触分布式存储那会儿我最困惑的一件事就是明明本地磁盘写文件就是几毫秒的事为什么往HDFS上传一个几百兆的文件有时候要等好几秒甚至更久后来把整个链路的原理捋了一遍才明白HDFS的上传和下载根本不是复制粘贴这么简单它背后是一套分块、流水线、多副本的协同机制。这一节我就把HDFS上传与下载的原理、HdfsAPI的使用、以及用IO流直接操作HDFS这三块内容按我自己的理解顺序完整拆一遍。先说清楚这篇内容适合谁看。如果你已经会写几句Java能看懂基本的文件读写但对分布式文件系统还停留在概念层面那这篇正好。如果你已经在用Hadoop做离线计算但每次调API都是复制粘贴、出了问题不知道怎么排查那这篇里的原理部分和排查技巧会帮你补上短板。核心关键词就三个HDFS上传下载原理、HdfsAPI、IO操作HDFS。这三个词其实是一条线——原理是为什么HdfsAPI是官方封装好的怎么做IO操作是底层手动怎么做。把这三层打通你才算真正会用HDFS。我个人的习惯是学任何一个组件先搞懂它的数据流向再去用它的API最后再回头看底层。因为API是别人封装好的你只会调API一旦报错就只能靠猜而懂了原理报错信息里的每一个词你都能对应到具体环节。下面我就按这个思路展开。2. HDFS上传与下载的核心原理拆解2.1 为什么HDFS要把文件切成Block要理解上传下载先得理解HDFS最基础的设计文件被切成固定大小的数据块Block存储。在Hadoop 2.x及以后的版本里默认块大小是128MB早期1.x是64MB。这个数字不是随便定的它背后是寻址时间和传输时间的权衡。打个比方你搬一箱书如果每本书都单独跑一趟路上花的时间比搬书本身还多如果一次搬一大箱路上时间占比就低了。磁盘读写也是这个道理寻址找到数据位置耗时相对固定而连续传输耗时和数据量成正比。块设得太小寻址开销占比高设得太大单个块的处理会拖慢并行度而且最后一个块可能浪费大量空间。128MB是业界在机械硬盘时代反复权衡后的经验值。块带来的直接好处有三个第一一个文件可以大于任何单台机器的磁盘容量因为它是分散存储的第二便于并行处理多个块可以同时被不同节点读取第三便于副本管理副本是以块为单位复制的而不是整个文件。注意块大小是可以在建表时按文件级别配置的不一定非要用默认值。大文件顺序读场景可以调大小文件多的场景要另想办法比如合并这个后面会讲。2.2 上传时NameNode和DataNode各自干了什么HDFS是典型的主从架构NameNode管元数据文件叫什么、切成几个块、每个块在哪些节点上DataNode管实际数据真正存块的地方。上传一个文件客户端并不是直接找NameNode要空间然后自己写而是走了一套申请-分配-流水线写入的流程。完整流程我拆成几步客户端调用FileSystem.create()向NameNode发起创建文件的请求。NameNode检查权限、路径是否存在然后在元数据里创建一条记录但此时不分配任何DataNode只是标记文件已创建。客户端开始写第一个块时向NameNode请求给我几个能存这个块的DataNode。NameNode根据副本策略默认3副本和机架感知返回一组DataNode列表并按网络距离排好序。客户端和列表里第一个DataNode建立连接第一个DataNode再和第二个建连接第二个和第三个建连接形成一条写入流水线Pipeline。数据以Packet默认64KB为单位沿着流水线一路传下去每个节点写完后再往下传同时反向回传ACK确认。一个块写完后客户端再申请下一个块的DataNode重复上述过程。所有块写完客户端通知NameNode关闭文件元数据落盘。这里有个关键点很多人忽略副本不是客户端分别写给三个节点的而是流水线传递的。客户端只跟第一个节点打交道这样能极大节省客户端的出口带宽。这也是为什么上传大文件时客户端机器的网卡不会成为瓶颈。2.3 下载时为什么优先读最近的副本下载流程相对简单但同样有讲究客户端调用FileSystem.open()向NameNode请求打开文件。NameNode返回该文件所有块的位置信息每个块对应一组DataNode按离客户端的网络距离排序。客户端拿到这些信息后对每个块从最近的DataNode读取。如果读取过程中某个DataNode故障客户端会自动切换到下一个副本对上层完全透明。最近不是指物理距离而是网络拓扑距离。如果客户端本身就在某个DataNode所在的机架上那读本机架的数据几乎不跨交换机速度最快。这就是机架感知Rack Awareness的价值。我实测过同机架读取和跨机架读取在千兆网络下吞吐能差出30%以上。提示下载时如果发现某个块读得特别慢八成是那个DataNode负载高或者磁盘有问题客户端虽然会自动重试其他副本但重试本身也有开销。生产环境要监控DataNode的读写延迟。2.4 副本策略与机架感知的实际影响默认3副本的放置策略是这样的第一个副本放在客户端所在节点如果客户端在集群外就随机选一个不太满的节点第二个副本放在不同机架的某个节点第三个副本放在第二个副本所在机架的另一个节点。这个策略的核心目标是兼顾可靠性和带宽。不同机架保证了即使整个机架断电数据还在同机架放两个副本是为了让读取时能利用机架内带宽。你可以把它理解成不要把鸡蛋放在同一个篮子里但也不要每个篮子只放一个因为拿起来太麻烦。副本数是可以调整的dfs.replication参数控制默认值。但要注意调大副本数会增加写入的网络开销和存储成本调小则降低可靠性。我见过有团队为了省空间把副本调成1结果一台机器磁盘坏了直接丢数据这个教训很深刻。3. HdfsAPI实操用Java代码完成上传下载3.1 环境准备与依赖配置用Java操作HDFS核心依赖是hadoop-client。如果你用Mavenpom里加这么一段版本按你集群的实际版本对齐这里以3.3.x为例dependency groupIdorg.apache.hadoop/groupId artifactIdhadoop-client/artifactId version3.3.4/version /dependency这里有个坑我必须提前说客户端依赖的版本最好和集群服务端版本一致或兼容。我试过用3.3的客户端连2.7的集群大部分功能能用但某些API会报NoSuchMethodError。如果实在无法统一至少保证大版本一致。连接HDFS有两种方式。一种是直接在Configuration里指定fs.defaultFS另一种是把集群的core-site.xml和hdfs-site.xml放到classpath下。我推荐后者因为配置集中管理换环境不用改代码。但如果是多集群切换的场景前者更灵活。Configuration conf new Configuration(); conf.set(fs.defaultFS, hdfs://namenode-host:8020); FileSystem fs FileSystem.get(conf);注意FileSystem.get()拿到的是个重量级对象内部维护了连接池。不要每次操作都new一个应该复用。我见过有人在循环里反复get结果连接数暴涨把NameNode拖垮。3.2 上传文件的三种写法与取舍上传文件HdfsAPI提供了好几个方法我按使用频率排一下。第一种最简单的一行流fs.copyFromLocalFile(new Path(/local/data.txt), new Path(/hdfs/data.txt));这个方法内部帮你处理了流的打开、关闭、缓冲区适合快速脚本。但它有个问题不能自定义覆盖策略。如果目标已存在默认会抛异常。要覆盖得先删或者用带overwrite参数的重载。第二种手动控制输入输出流try (InputStream in new FileInputStream(/local/data.txt); OutputStream out fs.create(new Path(/hdfs/data.txt), true)) { IOUtils.copyBytes(in, out, 4096, false); }这里的true就是overwrite标志。IOUtils.copyBytes的第三个参数是缓冲区大小第四个false表示不自动关闭流由try-with-resources负责。这种写法灵活可以在中间加进度统计、加解密、压缩等逻辑。第三种用FSDataOutputStream配合Progressable回调FSDataOutputStream out fs.create(new Path(/hdfs/data.txt), new Progressable() { Override public void progress() { System.out.print(.); } });这个Progressable每写完一个Packet64KB就会被回调一次是做进度条的关键。如果你要写个带进度显示的上传工具就得用这种方式。三种写法怎么选我的经验是一次性脚本用第一种需要加工数据用第二种需要给用户看进度用第三种。别为了炫技硬上第三种代码复杂度上去了收益不一定值。3.3 下载文件的正确姿势下载和上传是对称的同样有几种写法。最省事的是fs.copyToLocalFile(new Path(/hdfs/data.txt), new Path(/local/data.txt));手动流的方式try (FSDataInputStream in fs.open(new Path(/hdfs/data.txt)); OutputStream out new FileOutputStream(/local/data.txt)) { IOUtils.copyBytes(in, out, 4096, false); }这里有个细节值得说FSDataInputStream支持seek也就是随机读取。如果你只想读文件的某一段可以in.seek(offset)然后读指定长度不用把整个文件拉下来。这个特性在做大文件抽样、断点续传时特别有用。提示下载大文件时如果本地磁盘写入速度跟不上网络读取速度copyBytes会阻塞在网络读上整体吞吐受限于慢的那一端。可以适当调大缓冲区但别超过8MB否则GC压力大。3.4 元数据操作列出、删除、重命名除了读写日常用得最多的就是元数据操作。列目录FileStatus[] statuses fs.listStatus(new Path(/hdfs)); for (FileStatus s : statuses) { System.out.println(s.getPath() s.getLen() s.isDirectory()); }FileStatus里包含路径、长度、是否是目录、副本数、块大小、修改时间等信息够用了。如果要递归列用fs.listFiles(path, true)返回的是RemoteIterator比递归listStatus更省内存。删除fs.delete(new Path(/hdfs/data.txt), true); // 第二个参数是是否递归重命名fs.rename(new Path(/hdfs/a.txt), new Path(/hdfs/b.txt));这些操作看着简单但有个共同点它们都是元数据操作走的是NameNode。NameNode是单点元数据操作频繁会成瓶颈。所以别在循环里疯狂listStatus能批量就批量。4. IO流直接操作HDFS底层手动挡4.1 为什么有了API还要用IO流有人会问HdfsAPI都封装好了为什么还要用IO流我的答案是API是自动挡IO流是手动挡。自动挡日常够用但遇到特殊路况手动挡才能精确控制。举几个必须用IO流的场景第一你要在传输过程中做实时压缩或加密API的copyFromLocalFile不给你插入的机会第二你要做断点续传需要精确控制从哪个offset开始读写第三你要把HDFS的数据直接对接另一个系统比如消息队列、对象存储中间不想落地成本地文件。这些场景IO流是唯一选择。4.2 用IO流实现带缓冲的上传下面这段是我常用的一个上传模板加了缓冲和异常处理public void uploadWithStream(FileSystem fs, String local, String remote) { Path remotePath new Path(remote); try (InputStream in new BufferedInputStream(new FileInputStream(local)); FSDataOutputStream out fs.create(remotePath, true)) { byte[] buffer new byte[8192]; int len; long total 0; while ((len in.read(buffer)) ! -1) { out.write(buffer, 0, len); total len; } out.hflush(); // 强制刷出确保数据到达DataNode System.out.println(uploaded total bytes); } catch (IOException e) { // 失败时清理半成品文件 fs.delete(remotePath, false); throw new RuntimeException(upload failed, e); } }这里有几个点值得展开。第一缓冲区大小。8KB是个保守值实际可以调到64KB甚至128KB和HDFS的Packet大小对齐减少系统调用次数。第二hflush()和hsync()的区别。hflush保证数据到了DataNode的内存hsync保证落盘。前者快后者慢看你对持久性的要求。第三失败清理。上传中断会在HDFS上留个不完整的文件如果不删下次同名上传可能出问题。4.3 用IO流实现断点续传断点续传的核心是记录已传输的offset下次从那里继续。HDFS的FSDataOutputStream支持append但要注意append的语义是追加不是覆盖。所以断点续传的正确做法是先检查目标文件已存在多少字节然后本地文件seek到对应位置用append模式续写。Path remotePath new Path(remote); long existLen 0; if (fs.exists(remotePath)) { existLen fs.getFileStatus(remotePath).getLen(); } try (RandomAccessFile local new RandomAccessFile(localFile, r); FSDataOutputStream out existLen 0 ? fs.append(remotePath) : fs.create(remotePath)) { local.seek(existLen); byte[] buffer new byte[65536]; int len; while ((len local.read(buffer)) ! -1) { out.write(buffer, 0, len); } }注意HDFS的append在早期版本有并发问题多个客户端同时append同一个文件会出乱子。生产环境做断点续传最好保证同一时刻只有一个写入者或者用临时文件rename的方式。4.4 用IO流做流式下载与边读边处理下载时用IO流最大的价值是边读边处理不落地。比如你要统计HDFS上一个大日志文件的行数完全没必要先下载到本地再读try (FSDataInputStream in fs.open(new Path(/hdfs/big.log)); BufferedReader reader new BufferedReader(new InputStreamReader(in))) { String line; long count 0; while ((line reader.readLine()) ! null) { count; // 这里可以做任意处理过滤、聚合、写库 } System.out.println(lines: count); }这种写法在数据量大的时候优势明显省了本地磁盘IO也省了等待下载的时间。我做过对比同样统计一个10GB文件的行数流式读取比先下载再统计快了将近一倍因为省掉了写本地磁盘那一步。5. 常见问题与排查技巧实录5.1 上传卡住不动是怎么回事这是我最常被问到的问题。上传卡住通常有三个原因。第一DataNode磁盘满了或者坏了。流水线里某个节点写不进去整个流水线就卡住。排查方法是看DataNode日志找DiskOutOfSpace或IOException。解决要么清理磁盘要么把坏节点下线。第二网络抖动导致ACK丢失。客户端等不到下游的ACK会一直重试。这种情况看客户端的dfs.client.socket-timeout配置默认60秒可以适当调小让它快速失败切换。第三NameNode响应慢。如果卡在create阶段说明NameNode元数据操作慢可能是元数据太多、内存不足。看NameNode的RPC队列长度和GC日志。我整理了一个速查表现象可能原因排查方向create阶段卡住NameNode元数据慢NameNode GC、RPC队列写入中途卡住DataNode磁盘/网络问题DataNode日志、磁盘使用率一直重试不失败超时配置过大dfs.client.socket-timeout上传完文件不完整未hflush或异常未处理检查close流程5.2 小文件上传的性能陷阱HDFS最怕小文件。每个文件不管多小NameNode都要维护一条元数据默认每个文件约占150字节内存。如果你上传100万个1KB的小文件实际数据才1GB但NameNode要吃掉150MB内存而且读取时每个文件都要单独一次RPC性能极差。我的建议是能合并就合并。如果业务允许把大量小文件打包成SequenceFile或者HAR归档。如果非要存小文件考虑用HBase或者对象存储。我见过一个团队往HDFS塞了几千万个小文件最后NameNode启动要半小时这个坑太深了。5.3 权限与用户身份的那些坑用Java API连HDFS经常遇到Permission denied。这通常是因为客户端提交的用户身份不对。HDFS的权限模型和Linux类似如果你在Windows上跑代码默认用户可能是当前登录名而HDFS上没这个用户。解决办法有两个一是设置HADOOP_USER_NAME环境变量或者System.setProperty(HADOOP_USER_NAME, hadoop)二是在FileSystem.get()时传入UserGroupInformation。我一般用第一种简单直接。提示生产环境不要图省事用超级用户跑所有任务权限该配就配。我见过因为用root跑任务误删了整个目录的事故。5.4 副本数与块大小的调优经验最后聊聊调优。副本数默认3大多数场景够用。如果是临时数据、可重算的数据可以降到2甚至1省空间。如果是核心数据可以升到4或5但要注意写入放大。块大小默认128MB。如果是大文件顺序读比如日志分析可以调到256MB减少块数量降低NameNode压力。如果是随机读为主块小一点反而好因为一次读的数据量小。但块太小会增加寻址开销一般不建议低于64MB。我个人的经验值是离线批处理场景块大小256MB、副本3实时查询场景块大小128MB、副本3归档冷数据块大小512MB、副本2。当然这要结合你的集群规模和网络带宽来定没有万能公式。6. 我踩过的几个真实坑与收尾建议说几个我实际踩过的坑都是文档里不会写的。第一个坑用copyFromLocalFile上传时如果本地路径是个目录它会递归上传整个目录。我有次想传一个文件结果路径写错成了父目录把整个文件夹传上去了还覆盖了HDFS上的同名目录。后来我养成了习惯上传前先fs.exists()检查一下目标。第二个坑FSDataOutputStream不close数据可能丢。HDFS的写入是缓冲的你不close最后一部分数据可能还在客户端缓冲区里没发出去。我见过有人写完不close结果文件少了最后几KB排查了半天。记住流一定要在finally里close或者用try-with-resources。第三个坑并发写同一个文件。HDFS不支持多客户端同时写同一个文件除非用append且串行化。我有次两个任务同时往一个路径写结果一个成功一个报AlreadyBeingCreatedException。后来改成写不同临时文件最后rename合并。第四个坑客户端和集群时间不同步。HDFS的某些操作依赖时间戳如果客户端时间比集群快很多可能出现文件来自未来的诡异问题。建议所有节点开NTP同步。最后分享一个小技巧调试HDFS读写问题时把客户端的日志级别调到DEBUG能看到Packet级别的传输细节很多问题一看日志就明白了。具体是在log4j里把org.apache.hadoop.hdfs设为DEBUG。这个技巧帮我省了无数排查时间。HDFS的上传下载表面看是几个API调用底层却是一整套分布式协同机制。把原理、API、IO流这三层都摸透你遇到问题时就不会慌因为你知道数据在哪个环节、以什么形式流动。这套思路不光适用于HDFS换成其他分布式存储分析路径也是类似的。