1. 先把命令行啃透再谈写代码很多人上手大数据的第一反应是打开 IDE建个 Maven 工程把FileSystem那一套 API 敲一遍然后跑个mkdir就以为掌握了 HDFS 基础操作。我见过太多这样的同学等到线上真出事——数据写不进去、文件读出来是空的、删了想找回——立刻手足无措。原因很简单命令行才是离 HDFS 内核最近的那层皮它把每一次 RPC 调用、每一个块分配、每一条权限校验都直白地摊在你面前。你先用hdfs dfs -put把一个 1GB 的文件推上去看它怎么切块、怎么挑 DataNode、失败怎么重试再回头看 Java API那些方法签名瞬间就变得顺理成章。这篇内容围绕 HDFS 基础操作展开讲的是从命令行进入、把文件系统操作、权限模型、副本管理、回收站与快照这几条线走通并在每个环节把为什么这么设计讲透。适合三类人刚接触分布式存储、需要把命令背熟能用的新手已经会敲命令但对底层机制一知半解、排查问题时心里没底的中级使用者以及需要给团队做内部培训、想要一份能直接抄的实操清单的负责人。全程用我自己和身边人的踩坑经历做案例命令都是可复现的参数都给出取值理由不做二手转述。先把一个认知放在前面HDFS 的命令行不是文件系统工具那么简单它是一套元数据操作 数据流操作的混合体。ls、stat、du这类只碰 NameNode 的内存毫秒级返回put、get、cat这类要跟 DataNode 建连接搬数据慢几个数量级。搞清楚这条分界线你后面看到为什么 ls 飞快而 cat 卡住就不会慌。提示下文所有命令统一用hdfs dfs前缀它和已弃用的hadoop fs在多数场景等价但新版本里前者支持更多子命令如-storagePolicy、-ec建议从一开始就养成习惯。2. 块、副本、命名空间三条必须先对齐的底层认知2.1 块大小为什么默认是 128MBHDFS 把文件切成固定大小的块默认 128MB老版本 64MB。这个数字不是拍脑袋定的。块是 NameNode 元数据的最小管理单元一个 1TB 的文件在 128MB 块下产生 8192 条块记录而如果块是 1MB就是上百万条记录NameNode 的堆内存直接爆掉。反过来说块越大元数据越省但单个块的传输和恢复时间越长——一个块在千兆网下传完大约需要 1 秒多这被认为是可接受的重试粒度。所以 128MB 是元数据开销与故障恢复时间之间的一条折中线。你在实际操作里会感知到它hdfs dfs -put一个 300MB 的文件-stat %o看到的块数是 312812844最后一个块不满但照样占一条元数据记录。小文件问题就是这么来的——1000 个 1MB 的文件占 1000 条元数据、1000 个块实际数据才 1GBNameNode 压力却相当于 128GB 的大文件。后面第 5 章我会讲怎么治理。计算本身很简单但很多人第一次配dfs.blocksize时会踩坑这个参数单位是字节你在配置文件里写128会被当成 128 字节集群直接不可用。所以正确的是写134217728或者用带单位的128m部分版本支持稳妥起见还是写全字节数。2.2 副本机制与机架感知的真实代价默认 3 副本放置策略是第一个副本放在客户端所在节点客户端不在集群内则随机挑一个不太满的节点第二个放在不同机架的节点第三个放在第二个副本同机架的另一节点。这套策略的目的只有一个——同时扛住节点故障和机架级故障。一个机架断电你还有两份一个节点坏盘你还有两份。但副本不是白来的。3 副本意味着 1TB 原始数据实际占 3TB 磁盘写放大了 3 倍网络流量也放大。我见过某团队把日志类数据也设成 3 副本集群磁盘三个月就报警后来按数据重要度分层明细日志 2 副本核心业务表 3 副本临时中间结果 1 副本并开启纠删码。这是很实际的经验——副本数应该跟着数据的重算成本走能随时从上游重算出来的数据1~2 副本完全够。2.3 NameNode 与 DataNode 的分工边界用生活化类比NameNode 是图书馆的索引卡柜DataNode 是书架。你查书先去卡柜元数据卡上写着书在哪个书架第几层块位置然后你自己走到书架取书数据流。这个类比能解释一大堆现象索引卡柜的空间有限NameNode 内存瓶颈、卡柜挂了整个图书馆就瘫痪NameNode 单点、书架可以无限加DataNode 水平扩展。实操中这条边界决定了你的优化方向元数据操作密集的作业大量小文件ls、海量mkdir压的是 NameNode数据吞吐密集的作业大文件顺序读压的是 DataNode 和网络。两者要用完全不同的手段去调混为一谈只会白费功夫。3. 上传下载put 和 get 背后到底发生了什么3.1 写流程拆解七步走完才算成功hdfs dfs -put local.txt /data/这一行命令底下发生的事远比你想的多。第一步客户端向 NameNode 请求创建文件NameNode 检查路径是否存在、父目录权限够不够、配额是否超限通过则写入 editlog 并返回一个空的文件元数据。第二步客户端开始写第一个块向 NameNode 申请 DataNode 列表NameNode 按机架感知策略返回三个节点并按网络距离排序。第三步客户端只往第一个节点写第一个节点再转发给第二个第二个转发给第三个形成一条 pipeline。第四步数据以 packet默认 64KB为单位流动每个 packet 到下游都会被确认反向传回 ack。第五步一个块写满pipeline 关闭客户端再申请下一个块的节点列表。第六步全部写完客户端通知 NameNode 关闭文件此时文件才真正可见。第七步如果中途某个 DataNode 挂了pipeline 会剔除故障节点重建剩下的副本数由 NameNode 后续异步补齐。这套设计的精髓在于客户端只跟一个节点打交道带宽不会因为副本数增加而消耗在客户端侧。代价是延迟——pipeline 上任何一环慢整条链都慢。我遇到过一次写入卡顿最后定位到三个副本里有一个节点的磁盘快满了写入抖动把整条 pipeline 拖成了龟速。所以集群磁盘使用率最好控制在 75% 以下别等到 95% 才想起来扩容。3.2 读流程与就近读的实际效果hdfs dfs -get /data/big.file ./的读取流程短一些客户端问 NameNode 要块位置列表NameNode 返回按距离排序的 DataNode客户端直接连最近的那个读读完一个块再读下一个。所谓最近是指网络拓扑距离——同节点 同机架 同机房 跨机房。这里有个实操细节值得说如果你的客户端不是集群内节点那就近读基本失效每次都要跨网络拉数据。我见过某分析团队把计算任务跑在一台集群外的跳板机上读 10TB 数据读了一整天后来把任务挪到集群内的一个边缘节点同样的活两小时干完。读性能的第一优化项永远是把计算挪到数据旁边而不是去调什么缓冲区大小。3.3 参数调优与一条实测记录几个真正会影响体感的参数我按重要性排序参数默认值调优建议影响面dfs.blocksize128MB大文件场景可提到 256MB元数据量、单块恢复时间dfs.client-write-packet-size64KB千兆以上网络可到 128KB写吞吐dfs.replication3按数据重要度分层磁盘占用、写放大dfs.datanode.balance.bandwidthPerSec10MB/s空闲时段调到 100MB/s均衡速度实测记录某模拟项目要在集群上落一批约 200GB 的压缩日志最初用默认参数put单文件 2GB 左右平均写速约 45MB/s。把dfs.client-write-packet-size从 64KB 提到 128KB 后写速升到约 70MB/s再把块大小调到 256MB写速基本稳定在 75MB/s 上下。这个提升不算爆炸性因为瓶颈其实在磁盘和网络带宽参数只是把协议开销压下去了。别指望调参能把 45 变成 450那是硬件的事。注意put有-f覆盖、-p保留权限时间戳、-l保留 ACL几个常用开关。不加-p的话上传后文件的属主变成执行命令的用户mtime 变成上传时间很多数据同步场景会因此判断错增量务必显式加上。4. 目录与文件管理那些天天用却容易用错的命令4.1 查看类命令的分工与组合技巧ls、ls -R、du、df、stat、cat、tail这一组是日常最高频的。它们的分工要理清ls看目录条目ls -R递归但输出巨大大目录下能把终端刷死一般配合| head -50用du -s -h /path统计目录总大小它要遍历所有块目录越大越慢我一般只在必要时跑df -h看的是整个 HDFS 的容量不是某个目录——这个误解非常普遍很多人以为df能查目录占用其实那个位置是集群总量。stat是我最推荐的一个输出比ls全得多hdfs dfs -stat 格式: %b %o %r %u %g %y %n /data/sample.log%b是文件大小字节%o是块大小%r是副本数%u/%g是属主属组%y是修改时间ISO8601%n是文件名。这一条命令顶好几条写巡检脚本时特别顺手。cat要慎用。它在客户端把所有块拉回来再打印读一个 10GB 的文件会直接把内存和网络打满。想看开头用head看结尾用tail这两个命令的实现是只读首尾的块快得多。真要全文处理别用cat去写 MapReduce 或者 Spark 作业。4.2 mkdir、rm、mv、cp 的隐藏行为mkdir要加-p才能建多级目录不加会报父目录不存在这跟 Linux 一致但很多人第一次用会愣一下。rm是这里最容易出事的一个。默认情况下rm不加-skipTrash会把文件挪到回收站前提是回收站开启而不是真删。这个机制救过不少人但也坑过不少人——以为删了就腾出空间了结果df一看没变因为数据还在回收站里躺着。真要立即释放空间必须-skipTrash但那一刀下去就没了。mv在同一个文件系统内是纯元数据操作瞬时完成因为只改路径不改块跨文件系统比如 HDFS 到本地就会退化成复制加删除慢得离谱。cp同理HDFS 内部复制同样要真实搬数据1TB 的目录cp一份磁盘和网络都要过一遍别当成 Linux 的cp来用。4.3 权限模型与超级用户的边界HDFS 的权限模型跟 POSIX 很像rwx 三组属主、属组、其他。但它有两个自己的脾气。第一超级用户是启动 NameNode 的那个系统账号不是 root也不是你想改就能改的。第二ACL 支持比 POSIX 更细能给特定用户单独授权用-setfacl和-getfacl操作。hdfs dfs -chmod 750 /data/biz hdfs dfs -chown etl:analysts /data/biz/output hdfs dfs -setfacl -m user:reader01:r-x /data/biz/output hdfs dfs -getfacl /data/biz/output实操心得-chown只有超级用户能执行而且改属主会连带影响属组如果只改属主不改属组要写成-chown newowner:冒号后面留空。这个细节在脚本里漏掉会导致属组被重置成一个默认值权限瞬间崩掉。我见过一次因为这条下游三个作业全部读不到数据排查了半小时才发现是属组被改了。另外HDFS 的权限检查在客户端和服务端都会做但客户端那次只是友好提示真正的裁决在 NameNode。所以别想着绕过客户端就能越权那是白费劲。5. 副本数与块把存储成本压下来的实操5.1 setrep 的异步语义与生效时机调副本数的命令是hdfs dfs -setrephdfs dfs -setrep -w 2 /data/logs/2024 hdfs dfs -setrep -R 3 /data/core-w表示等待副本调整完成再返回-R表示递归。这里有个大坑不带-w时命令立即返回但后台的复制是异步的你可能马上stat一看副本还是 3以为没生效。实际上 NameNode 已经把待复制块排进队列由 DataNode 慢慢搬。一个几十 TB 的目录复制可能要跑好几个小时期间集群网络压力会明显上升。反过来降副本也是一样-setrep 1之后 NameNode 会标记多余的副本待删除但删除是按心跳慢慢通知的不是瞬间完成。所以不要用df的变化来判断 setrep 是否成功要看hdfs fsck /path -files -blocks里每个块的实际副本数。5.2 小文件治理的三条路小文件是 HDFS 的经典痛点。三条治理路径按代价从低到高排第一条入库前合并。上游产出的文件如果是每分钟一个几百 KB 的小文件就在采集端做攒批攒到 128MB 或者攒够 5 分钟再上传。这条最省事效果也最好可惜很多团队是事后才发现问题。第二条用归档工具打包。HAR 文件能把一堆小文件打成一个归档元数据只占一份但读的时候要按归档内路径访问兼容性一般。更现代的做法是容器格式把多个小文件塞进一个大文件里靠索引定位。第三条离线合并作业。写一个定时任务扫出小于阈值的文件读出来合并成大文件再删掉原件。这活儿我用过很多次注意两点合并后要校验行数或大小对得上别合着合着丢数据删除原件前确保下游没有还在依赖原路径的任务否则半夜告警。5.3 存储策略把冷数据赶到便宜盘上HDFS 支持按存储类型分层RAM_DISK、SSD、DISK、ARCHIVE。你可以给目录设策略让热数据落在 SSD冷数据落到大容量机械盘hdfs storagepolicies -setStoragePolicy -path /data/hot -policy HOT hdfs storagepolicies -setStoragePolicy -path /data/cold -policy COLD hdfs storagepolicies -getStoragePolicy -path /data/coldHOT全放 DISKCOLD主要放 ARCHIVEWARM是一部分 DISK 一部分 ARCHIVE。这条能力在实际降本里非常有用——某团队把半年前的明细数据整体设成 COLD三个月后统计磁盘成本下降了三成多而查询频次极低的冷数据性能损失可以忽略。设完策略要跑一次hdfs mover让存量数据真正迁移不然只有新写入的数据遵守新策略。6. 回收站、快照与安全模式三道保险怎么用6.1 回收站不是万能的回收站由fs.trash.interval分钟控制设 0 就是关闭。开启后rm删除的文件进入/user/用户名/.Trash/Current/过了保留时间才真正清掉。想找回就mv或cp出来hdfs dfs -ls /user/etl/.Trash/Current/data/ hdfs dfs -mv /user/etl/.Trash/Current/data/sample.log /data/recovered/几个要点。第一回收站是按用户隔离的超级用户看不到别人的回收站除非显式指定路径。第二-skipTrash删除不进回收站权限够的话一刀毙命。第三回收站本身也占空间保留时间设太长比如 7 天会把集群撑满我一般设 1440 分钟一天核心目录再单独加保护。第四用程序 API 删除时默认不进回收站会直接跳过这是很多人程序删了找不回的根本原因。6.2 快照只读时间点误删后的最后一道门快照要在目录上先开启hdfs dfsadmin -allowSnapshot /data/core hdfs dfs -createSnapshot /data/core backup_20240601 hdfs dfs -ls /data/core/.snapshot/ hdfs dfs -cp /data/core/.snapshot/backup_20240601/lost.file /data/core/快照的妙处在于它几乎不占额外空间——只记录块列表的引用数据块本身共享。只有原文件被修改或删除时旧块才因为被快照引用而保留下来。所以给核心目录开快照成本极低收益极高。但要注意两点快照目录.snapshot是只读的不能往里写快照数量要有上限几百个快照堆着NameNode 内存会吃不消我一般保留最近 7 个用定时任务滚动清理。另外开了快照的目录不能直接rm -r得先disallowSnapshot再删否则会报错。6.3 安全模式启动时的暂停营业集群重启后NameNode 会进入安全模式safemode此时只接受读请求拒绝写入。原因是它要等足够比例的 DataNode 上报块列表确认副本情况才能对外服务。阈值由dfs.namenode.safeslotpct控制默认 0.999意思是 99.9% 的块达到最小副本数才退出。如果你发现集群卡住了、写不进去第一件事就是查安全模式hdfs dfsadmin -safemode get hdfs dfsadmin -safemode waitget返回 ON 就是还在安全模式里。正常情况下等几十秒到几分钟会自动退出。如果一直退不出来通常是大量块副本不足得去看hdfs fsck /的报告找出副本缺失的块。千万不要图省事用-safemode leave强退那等于在数据不完整的情况下开门营业后面写操作大概率出问题。这个命令是应急手段不是常规操作。7. 常见问题排查速查表7.1 高频报错与定位思路报错/现象大概率原因排查动作处理方式Could not obtain blockDataNode 故障或网络不通hdfs fsck /path -files -blocks看块状态等自动补齐或-setrep触发复制写入卡在某个百分比pipeline 上有节点磁盘满hdfs dfsadmin -report看各节点剩余空间清理或下线该节点让 pipeline 重建Permission denied属主属组不对或 ACL 缺权限stat看属主getfacl看 ACLchown/setfacl修正rm后空间没释放数据进了回收站ls .Trash/Current清空回收站或下次加-skipTrashsetrep后副本数没变异步复制还没跑完fsck看真实副本数等待或检查 DataNode 是否满载NameNode 启动卡在 safemode块上报比例不足safemode get看fsck缺失块修复 DataNode禁止强退读大文件内存溢出用了cat全文加载看命令历史改用head/tail或分布式作业目录du极慢遍历海量块ls看条目数改用fsck或分区统计7.2 几条只有踩过才知道的经验第一条先看日志再敲命令。NameNode 和 DataNode 的日志里报错原因往往写得比命令输出清楚十倍。我养成习惯任何异常先tail -200一下对应组件的日志能省掉大量猜测。集群规模稍大时装个日志聚合把各节点日志集中看效率提升非常明显。第二条任何删除操作前先ls一遍目标路径。看起来傻但真能拦住事故。脚本里我一般写成先 ls 计数符合预期再删多花两秒省掉一次灾难。第三条改配置后先小范围验证。调副本数、调块大小、改存储策略别一把梭全集群。挑一个非核心目录试fsck验证结果对了再推全量。某次我在生产上直接对根目录setrep结果整个集群网络跑满业务读写全部抖动被投诉了一晚上——这活儿就该挑低峰期做。第四条给关键目录配好三件套回收站开启、快照定期打、ACL 收到最小权限。这三样配齐绝大多数数据没了的事故都能在半小时内恢复。反过来全靠-skipTrash人为操作出事只是时间问题。我个人在实际操作中的体会是HDFS 这些命令单看每一条都不难难的是脑子里有一张这条命令动的是元数据还是数据流的地图。有了这张图ls快cat慢你不会疑惑mv秒回cp半小时你也不会惊讶没有这张图就只能靠一次次事故去补课。