简介：一份基于Hadoop实现的百度云盘项目，完整提供源代码与文档说明，主要面向大数据、计算机相关专业的学生、毕业设计者以及初入Hadoop生态的开发者。项目以分布式文件存储为核心，涉及文件上传、下载、目录管理等功能，通过Java、JSP及前端脚本展示了从业务逻辑到页面交互的完整实现路径，对Hadoop分布式文件系统的应用有较完整的示例。压缩包内共包含2000个文件，体积约77.11MB，构成以PNG图片、JavaScript、HTML、CSS、JSP、Java源码和Jar依赖包为主，GIF动图与截图便于查看系统运行界面，目录结构清晰，便于按模块阅读。目前已有534人浏览学习。借助源码、说明文档和演示图片，读者可快速掌握系统分层与调用关系；若将其用于课设、毕设或Hadoop入门实践，可作为直接参考并在此基础上做二次功能扩展，对文件上传下载的实现一目了然。
1. “基于Hadoop的百度云盘”到底在做一个什么系统
如果你在求职或课设答辩现场听到这个题目，第一反应多半是：把百度网盘重新实现一遍，太难了。实际上这类“基于Hadoop的百度云盘”是分布式系统课程里最经典的综合实践题目，它要求你用 Hadoop 生态中的 HDFS 做底层对象存储，再叠一个文件管理服务，能够完成文件上传、下载、列表、删除、秒传等基础功能。整个系统的技术含量不在“像不像百度网盘”，而在于你是否吃透了 NameNode 和 DataNode 的分工、副本机制、块存储的原理，以及怎么把业务元数据和真实文件数据分开管理。准备环境、调试源码、写文档通常比写业务逻辑更花时间，这也是这个项目标题里“源代码 + 文档说明”比重那么大的原因。适合的人群是准备大数据方向面试的工程师、做课程设计的本科生，以及公司内部要做私有网盘快速验证的团队。
2. 先盘清楚：HDFS 架构与云盘功能映射，块、副本、元数据都怎么摆
2.1 一个 128MB 的块，为什么云盘也要把文件切成块来存
HDFS 默认的块大小是 128MB，和本地文件系统 4KB 的磁盘块逻辑一样：文件写入时被拆成固定大小的块，分布式地存储在多个 DataNode 上。百度云盘的“分片上传”逻辑表面上是为了断点续传，底层和 HDFS 的块机制天然契合——你把一个 512MB 的文件拆成 4 个 128MB 的块写入 HDFS，每个块对应一个独立的 Block 副本组，读取时按偏移量拼接即可。做课程设计时最容易犯的错是“一个文件一个 HDFS 文件”，完全不利用块机制，导致 NameNode 上产生大量元数据记录，集群还没存多少数据，内存先报警了。
块大小也不能盲目调小。HDFS 设计大块是为了减少磁盘寻址时间，128MB 的块意味着客户端一次 seek 可以连续读完很大一段数据。把它调成 1MB 反而会让客户端频繁和 NameNode 通信拿块位置，吞吐量断崖式下跌。云盘系统里，块大小最好和 HDFS 块对齐：小于 128MB 的小文件直接写一个块，大于 128MB 的大文件在业务层按固定大小切片，再把切片映射到 HDFS 的不同文件上。很多开源实现会把切片大小设为 64MB，留一半余量给 HDFS 做校验和冗余。
| 存储系统 | 默认块大小 | 设计目标 |
|---|---|---|
| 本地磁盘（ext4） | 4KB | 减少小文件碎片 |
| HDFS | 128MB | 减少寻址开销，适合大文件顺序读 |
| 云盘业务切片 | 64MB 或 128MB | 配合 HDFS 块，同时支持断点续传 |
2.2 三副本放置策略：机架感知不是玄学，是可用性设计
HDFS 默认保存 3 个副本，但三个副本不是随机放的。常见策略是：第一个副本放在客户端所在节点的本地磁盘，第二个副本放在另一个机架上的随机节点，第三个副本放在第二个副本所在机架的另一个节点。这样设计能同时容忍“单节点宕机”和“整个机架断电”，像 Hadoop 官网文档里写的“机架感知”机制，按网络拓扑计算写入距离。
在课程设计或内部演示环境里，很多人在伪分布式下根本没机会看到三副本的效果，因为只有一台机器，所有 block 都在同一个 DataNode 上。如果你部署的是 3 节点集群，跑一个hdfs fsck /user/data -files -blocks -locations，能明显看到每个 file 对应 3 个 block 位置，分布在不同的 hostname 上。云盘系统的数据可靠性就建立在这层机制之上，业务代码不需要自己实现多副本备份。
dfs.replication参数可以调整副本数，但我不建议在业务项目里把这个值设成 1，哪怕只是测试环境。副本数少了，后续做滚动升级或节点下线时，数据容易进入“under replicated”状态，读写性能也会波动。真需要省磁盘，优先考虑对不重要的临时目录单独设置副本数。
2.3 业务元数据和 HDFS 文件是两个世界，目录树属于谁
云盘上看到的目录树和 HDFS 的目录树是两个概念。百度网盘的“我的网盘 - 图片 - 2024”，这是业务层在 MySQL 或自研元数据库里维护的树形结构，每个节点记录父目录 ID、文件所有者、文件大小、MD5、存储位置。HDFS 那边只负责存文件内容，一般推荐把用户 ID 映射成一个顶层目录，比如/user/webdisk/10001/，下面再按业务类型拍平，而不是把完整的目录树一层层建到 HDFS 里。
原因很直接：HDFS 的目录是 NameNode 内存里的一个对象，几百万个目录就会吃掉几 GB JVM 堆外内存。业务目录树存数据库，N 层嵌套也只是普通记录；HDFS 目录保持浅层级，NameNode 压力小，备份恢复也快。上传文件时，业务层记录逻辑路径/photos/2024/vacation.jpg，底层物理路径存/user/webdisk/10001/vacation.jpg，回源时按物理路径读。这样做还有一个好处：重命名目录只需改数据库记录，HDFS 文件不用动，也就不用扫描整棵目录树。
这个映射关系要写进“文档说明”里，特别是表结构设计部分。很多源码包答辩被问倒，就是评委问“你删了业务文件，HDFS 上怎么清理”时答不上来，因为没有做物理路径和逻辑路径的清晰映射。
3. 从伪分布式到三节点集群，环境配置的顺序不能乱
3.1 版本选择与 Linux 准备：JDK 1.8 还是 JDK 17
Hadoop 生态对 JDK 版本非常敏感。Apache Hadoop 3.3.x 官方支持 JDK 8 和 JDK 11，但大部分企业生产环境仍然跑在 JDK 8 上，因为 Hive、Spark、Flink 这些周边组件对 JDK 8 的兼容性最稳。选版本时不要追新，也不要选已经停止维护的老版本。我一般建议课程设计和内部验证用 Apache Hadoop 3.3.4 以上版本，配 JDK 8。虽然 Oracle JDK 已经不再免费商用，但 OpenJDK 8 的java-1.8.0-openjdk在 CentOS 7 / Ubuntu 20.04 上都有现成 yum/apt 包，装上就能用。
Linux 侧需要准备的东西不多：静态 IP、主机名映射、SSH 免密、防火墙放行端口。伪分布式的端口是 9870（NameNode Web UI）和 9000（RPC 通信），三节点集群还要放行 9864（DataNode 通信）和 9866（DataNode 数据传输）。用systemctl stop firewalld直接关防火墙也可以，但生产环境最好按端口开放。
3.2 三节点主机规划与四个核心 XML 配置
以 3 台 CentOS 7 节点为例，规划如下表。配置里最关键的是core-site.xml中fs.defaultFS必须指向 NameNode 的主机名，不要写localhost，因为 DataNode 启动时会根据这个地址去注册，写错会直接注册失败。
| 主机名 | IP | 角色 | 内存建议 |
|---|---|---|---|
| hadoop-master | 192.168.10.10 | NameNode / ResourceManager | 4GB+ |
| hadoop-worker1 | 192.168.10.11 | DataNode / NodeManager | 2GB+ |
| hadoop-worker2 | 192.168.10.12 | DataNode / NodeManager | 2GB+ |
hdfs-site.xml里重点调三个参数：dfs.replication设为 2 或 3，测试集群磁盘不够可以设 2；dfs.namenode.name.dir和dfs.datanode.data.dir指向独立数据盘，分布式部署时数据盘和系统盘分离是基本操作；dfs.namenode.handler.count根据集群并发数从默认 10 调大，云盘这种高并发文件访问场景建议调成 64。yarn-site.xml的资源调度参数不直接影响 HDFS 读写，但跑 MapReduce 任务做离线分析时需要配置。
3.3 启动命令与验证基线：format 只许一次
先格式化 NameNode，然后一键启动，按顺序验证。这是所有 Hadoop 项目里最容易被坑的环节，格式化命令不能重复执行，否则 NameNode 的 clusterID 会变，DataNode 用旧 clusterID 来注册会被拒之门外，日志里反复刷Incompatible clusterIDs。具体命令如下。
# 只在主节点执行一次 hdfs namenode -format # 启动 HDFS start-dfs.sh # 启动 YARN（如需要跑 MapReduce） start-yarn.sh # 验证 Java 进程是否齐全 jps正常情况下主节点能看到NameNode、SecondaryNameNode、ResourceManager，从节点能看到DataNode、NodeManager。jps只是看进程存在，还要用hdfs dfsadmin -report查看 DataNode 是否进入了In Service状态，Live Nodes 数量是否为 3。若 Live 数量不对，优先级最高的排查路径是：先看logs/hadoop-hadoop-datanode-主机名.log，重点搜All datanodes are in service或Incompatible clusterIDs。
4. 云盘核心代码：上传、下载、秒传要写在哪个业务层
4.1 数据表设计：一张用户表加一张文件分块表，别把文件内容存数据库
云盘系统的元数据表不建议设计得太复杂，三张表足够起步。t_user存用户信息；t_file存文件的逻辑路径、物理路径、大小、MD5、创建时间；t_file_chunk存分块信息，包括每个分片的序号、大小、HDFS 绝对路径和 MD5。如果要做分享功能，再加一张t_share表记录提取码和过期时间。MySQL DDL 里注意给user_id和parent_id建联合索引，文件列表查询按目录拉取时才不会全表扫描。
CREATE TABLE `t_file` ( `id` bigint NOT NULL AUTO_INCREMENT, `user_id` bigint NOT NULL, `parent_id` bigint NOT NULL DEFAULT 0, `file_name` varchar(255) NOT NULL, `file_size` bigint NOT NULL, `file_md5` char(32) NOT NULL, `hdfs_path` varchar(512) NOT NULL, `status` tinyint NOT NULL DEFAULT 1, `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`id`), KEY `idx_user_parent` (`user_id`, `parent_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;hdfs_path存的是物理路径，逻辑目录树完全靠parent_id表达。文件从“可用”改成“已删除”只改status字段，HDFS 文件不立即删除，这个软删除设计让后续做回收站功能非常简单，也避免用户手滑误删数据后无法找回。
4.2 Java API 读写 HDFS 的最小实现：FileSystem 类是入口
Hadoop 客户端访问 HDFS 的标准方式是org.apache.hadoop.fs.FileSystem，传入一个Configuration对象即可获取文件系统实例。上传文件的代码核心是拿到FSDataOutputStream，然后从本地文件流里循环读数据往里写。千万不要一次性把整个文件读进byte[]，超过 2GB 的文件直接 OOM。按 64KB 的缓冲区循环读写是最稳妥的做法。
public void uploadFile(String localPath, String remotePath) throws IOException { Configuration conf = new Configuration(); conf.set("fs.defaultFS", "hdfs://hadoop-master:9000"); FileSystem fs = FileSystem.get(conf); Path outputPath = new Path(remotePath); if (fs.exists(outputPath)) { throw new IOException("目标文件已存在: " + remotePath); } try (FSDataOutputStream out = fs.create(outputPath); FileInputStream in = new FileInputStream(localPath)) { byte[] buffer = new byte[65536]; int len; while ((len = in.read(buffer)) > 0) { out.write(buffer, 0, len); } } catch (IOException e) { fs.delete(outputPath, true); throw e; } finally { fs.close(); } }这个实现里两个点要说明。第一，fs.create返回的FSDataOutputStream在写入一定数据量后才会真正把 block 刷到 DataNode，大文件写完后资源释放顺序很关键：先刷 close 再关闭文件输入流，否则可能出现数据丢失。第二，如果中途异常，用fs.delete(outputPath, true)把残块清掉，否则下次重试时会因为文件已存在而报错。true表示递归删除，写false则只能删空文件。
4.3 别重复造轮子，Python 的 hdfs 库可以当快速验证工具
如果你的云盘后端不是 Java 而是 Node.js 或 Python，可以用hdfs这个 Python 库走 WebHDFS 协议访问 HDFS，不用引入 Hadoop Java SDK。它的写文件操作更简洁，适合做功能验证、数据灌库，或者写自动化测试脚本。需要先确认hdfs-site.xml里把dfs.webhdfs.enabled设为true，否则会返回 403 错误。
from hdfs import InsecureClient client = InsecureClient('http://hadoop-master:9870', user='root') # 上传本地文件到 HDFS client.upload('/user/webdisk/10001/photos/a.jpg', './a.jpg', overwrite=False) # 读取 HDFS 文件内容 with client.read('/user/webdisk/10001/photos/a.jpg') as reader: data = reader.read() print(len(data)) # 列出目录下所有文件 for item in client.list('/user/webdisk/10001/photos', status=False): print(item)InsecureClient适合测试环境和内网部署，生产环境要走 Kerberos 认证就换成KerberosClient。list方法默认返回列表，加上status=True参数能拿到每个文件的权限、大小和修改时间，对应到云盘里的文件列表接口，刚好不用额外调fs.FileStatusAPI。
4.4 秒传与分块续传：先算 MD5 再决定要不要写 HDFS
秒传的实现原理极简：上传文件时先计算文件 MD5，然后查t_file表里是否已存在相同 MD5 且属于相应用户的记录。存在则直接返回上传成功，并把新的文件记录指向已存在的hdfs_path，HDFS 层完全不需要发生任何写入。跨用户秒传要额外做权限判断，否则 A 用户上传的文件，B 用户就能通过猜路径的方式直接引用。
分块续传的逻辑则依赖于t_file_chunk表。客户端把文件切成 16MB 的块，逐块上传前先查该块是否已有记录，已有则跳过，没有才调 HDFS 写入接口。上传完成后业务层校验所有块齐全且 size 之和等于总大小，再合并元数据记录。这样设计的好处是：一个块上传失败只需要重传那个块，不需要整个大文件重新传，也比在应用层拼接成一个大文件再写 HDFS 更灵活。
5. 最容易踩的 4 个坑，集群和伪分布式通用
5.1 格式化两次导致 clusterID 冲突，DataNode 起不来
格式化 NameNode 会重新生成一个 clusterID，而已经初始化的 DataNode 磁盘上保存着旧的 clusterID。第二次hdfs namenode -format后再启动集群，DataNode 启动时发现自己的 clusterID 和 NameNode 不一致，会自动进入废弃状态，dfsadmin -report里看到的 Live Nodes 数量永远是 0。排查时先看logs/hadoop-hadoop-datanode-xxx.log，里面有Incompatible clusterIDs字样。
解决办法不是去手改配置文件，而是清理 DataNode 的数据目录。在每台 DataNode 上执行rm -rf /data/hdfs/datanode/*，然后重启hdfs datanode，让它重新向 NameNode 注册并初始化。NameNode 那边的current/VERSION文件不要动。伪分布式环境里最容易触发这个问题，因为经常有人反复练习搭环境，格式化了三次还在继续启动。
5.2 主机名写错比 IP 配错更难排查
Hadoop 内部大量使用主机名而不是 IP 做通信，core-site.xml里写了hdfs://hadoop-master:9000，客户端所在机器的/etc/hosts必须能解析这个主机名，否则报UnknownHostException，日志里看着像是网络不通，实际是解析失败。搭建三节点集群时，建议把所有节点的主机名映射写进每台机器的/etc/hosts，并检查hostnamectl set-hostname是否生效。
# 在所有节点上执行，IP 换成实际地址 echo "192.168.10.10 hadoop-master" >> /etc/hosts echo "192.168.10.11 hadoop-worker1" >> /etc/hosts echo "192.168.10.12 hadoop-worker2" >> /etc/hosts # 验证互相能解析 ping hadoop-worker1 -c 35.3 把fs.defaultFS写死在代码里，换集群就翻车
课程设计源码包里最常见的坏味道是Configuration conf = new Configuration();之后硬编码fs.defaultFS=hdfs://localhost:9000。这导致你的云盘代码永远只能在搭好的那台机器上跑，换一台服务器或者从伪分布式迁移到三节点集群就必须改代码重新编译。正确做法是使用core-site.xml里动态获取配置，或者通过外部配置中心传入连接地址。
Configuration conf = new Configuration(); // 从项目配置文件读取，不要硬编码 conf.set("fs.defaultFS", PropertyUtil.get("hdfs.namenode.address"));我一般会建一个PropertyUtil工具类读取application.properties，把 HDFS 连接地址、副本数、用户信息全部放到外部配置里。交付文档里明确写清楚这些参数分别对应生产环境哪个值，这样评审核对或交接给运维时不用逐行翻代码。
5.4 上万个小文件把 NameNode 内存吃光
这个坑在课程设计里不容易暴露，因为测试数据太少，但放到真实场景必炸。每个文件、每个目录在 NameNode 内存里都是一个对象占 150~200 字节，上万个小文件累积下来就是几百 MB JVM 堆外内存。云盘这种场景最容易制造小文件：用户上传了几千张 5KB 的图片，每次都往 HDFS 新建一个文件路径，NameNode 很快吃不消。
定位问题优先看 NameNode Web UI 的“Startup Progress”和 JVM Heap 使用率。处理方案可以考虑“归档”：每小时把多个小文件合并写成一个SequenceFile或HAR文件，业务元数据里记录文件和归档包的映射关系。也可以按用户维度分桶，一个用户的小文件写入同一个 HDFS 目录下，配合 HDFS 的hdfs balancer保持数据均衡。开源云盘系统里普遍采用“先攒后写”的策略，应用层做个 30 秒的缓冲窗口，把一批小文件合并为一次 HDFS 写入，和数据库批量插入的思路一致。
6. 最后给项目收尾的两个实用技巧：软删除与文档清单
6.1 用状态位做回收站，HDFS 文件延迟清理
删除功能不要直接调fs.delete()，而是把t_file.status改成 0。这样前端删除 100 个文件，数据库只是批量 update，毫秒级完成，HDFS 没有任何 IO 压力。清理动作放到后台线程，每天凌晨 3 点把status=0且update_time超过 7 天的记录找出来，再逐个调 HDFS 删除。好处是用户误删能在 7 天内恢复，恢复操作也简单：把status改回 1 即可。恢复时如果发现 HDFS 文件已经被清理，就提示“文件已过期，无法恢复”。
6.2 交付文档必须涵盖版本清单、启动顺序、常见错误对照表
源码和文档是一起交付的，文档不是简单的 README，要有版本矩阵、启动步骤、验证命令和排错对照。版本不一致是 Hadoop 项目最常见的交付事故：代码是用 CDH 编译的，部署环境是 Apache Hadoop，直接运行大概率报NoSuchMethodError。文档里列清 JDK 版本、Hadoop 版本、Maven 或 Gradle 依赖版本，能让接手的人少踩一半的坑。
# 部署后整体验证，一套命令跑完 jps hdfs dfsadmin -report hdfs dfs -ls /user/webdisk curl http://hadoop-master:9870/dfshealth.html#tab-overview最后控制台里能看到 NameNode 状态为Active，DataNode 数量为期望值，即表示系统已经正常对外服务。剩下要做的是对你的t_file_chunk表的自增主键加一个索引，然后找一个超过 1GB 的文件测试分块上传的完整性，确认 MD5 和原始文件一致后再提交文档。
本文还有配套的精品资源，点击获取
