简介这份资源是一套基于Hadoop的云盘系统完整项目源码面向大数据与Java Web方向的学习者及开发者帮助理解分布式存储与网络云盘的结合实现。项目依托HDFS分布式文件系统、MapReduce计算框架与YARN资源调度构建了包含云盘服务层和用户管理模块的存储管理平台可用于企业数据存储、在线资料库等场景的学习与二次开发。压缩包共284个文件约1.16MB以105个Java源文件为核心配合32个JavaScript、30个HTML与13个CSS文件搭建前端交互界面另有GIF、JPG等图片素材及少量配置文件与依赖库结构完整。目前已有100人学习下载。通过研读源码读者可掌握HDFS数据块存储、MapReduce任务编写、用户权限控制等关键实现并借鉴其分层架构与目录组织方式为大数据项目实践提供可复用的参考方案。1. 基于 Hadoop 的云盘系统从伪分布式到可演示的最小闭环很多人第一次看到“基于 Hadoop 的云盘系统”这个题目脑子里冒出来的第一个念头是这不就是把文件传到 HDFS 上吗真动手才发现文件上传只是入口真正决定这套系统能不能跑起来、能不能演示、能不能写进课程设计报告的是元数据怎么存、小文件怎么合并、上传下载怎么和 NameNode 打交道、Web 端怎么把 HDFS 的流式读写包装成用户能点的按钮。我见过太多人卡在hadoop fs -put能跑通、但一接 Java API 就报Connection refused的阶段。这篇笔记面向的是要在一到两周内把“基于 Hadoop 的云盘系统”从零搭出来、并且能讲清楚每一层在干什么的人。核心结论先放这里这套系统的技术骨架是 HDFS 做文件存储、MySQL 做元数据索引、Spring Boot 做服务层、前端做文件列表和上传下载交互Hadoop 伪分布式足够支撑演示和课程设计不需要一上来就上集群。下面按“环境怎么搭 → 存储层怎么写 → 元数据怎么设计 → 坑在哪 → 怎么验证”的顺序展开每一步都给可复现的命令和代码。2. Hadoop 伪分布式搭建与云盘存储层选型2.1 为什么云盘系统选 HDFS 而不是本地磁盘或对象存储先把这个选型问题说清楚不然后面写代码时容易动摇。云盘系统的本质需求是多用户上传文件、文件要能持久化、要能通过 Web 访问、最好还能体现“分布式”这个关键词。本地磁盘能存文件但没法体现 Hadoop 生态对象存储比如 MinIO更贴近真实云盘但和“基于 Hadoop”这个标题就脱节了。HDFS 的优势在于它本身就是为大规模文件存储设计的有副本机制、有块存储概念、有完整的 Java API而且课程设计里“基于 Hadoop”这个前缀天然要求你用 HDFS。它的劣势也很明显不适合存大量小文件因为每个文件、每个块在 NameNode 里都要占内存。一个 1KB 的文件和一个 128MB 的文件在 NameNode 看来占用的元数据空间差不多。所以云盘系统里必须做小文件合并或者至少做上传大小限制这是后面避坑章节要重点讲的。选型结论HDFS 做文件内容存储MySQL 做文件元数据文件名、大小、上传时间、HDFS 路径、所属用户两者通过文件 ID 关联。这个组合是这类课程设计里最常见、也最稳的方案。2.2 伪分布式环境搭建从零到能跑的最小命令集假设你用的是 Ubuntu 20.04 或 CentOS 7JDK 用 8Hadoop 3.x 对 JDK 8 兼容最好。下面是从零开始的命令序列每一步都说明在干什么。# 1. 安装 JDK 8验证版本 sudo apt update sudo apt install openjdk-8-jdk -y java -version # 输出应包含 openjdk version 1.8.0_xxx # 2. 下载 Hadoop 3.3.6这个版本稳定和 JDK 8 兼容好 cd /opt sudo wget https://archive.apache.org/dist/hadoop/common/hadoop-3.3.6/hadoop-3.3.6.tar.gz sudo tar -xzf hadoop-3.3.6.tar.gz sudo mv hadoop-3.3.6 hadoop # 3. 配置环境变量写入 ~/.bashrc echo export HADOOP_HOME/opt/hadoop ~/.bashrc echo export PATH$PATH:$HADOOP_HOME/bin:$HADOOP_HOME/sbin ~/.bashrc echo export JAVA_HOME/usr/lib/jvm/java-8-openjdk-amd64 ~/.bashrc source ~/.bashrc上面三步做完hadoop version应该能输出版本号。接下来改配置文件这是伪分布式最关键的部分。需要改的文件在$HADOOP_HOME/etc/hadoop/下。# core-site.xml指定 HDFS 的默认文件系统地址 # 伪分布式下 NameNode 跑在本机 9000 端口 cat $HADOOP_HOME/etc/hadoop/core-site.xml EOF configuration property namefs.defaultFS/name valuehdfs://localhost:9000/value /property property namehadoop.tmp.dir/name value/opt/hadoop/data/tmp/value /property /configuration EOF # hdfs-site.xml设置副本数为 1伪分布式只有一台机器 cat $HADOOP_HOME/etc/hadoop/hdfs-site.xml EOF configuration property namedfs.replication/name value1/value /property property namedfs.namenode.name.dir/name value/opt/hadoop/data/namenode/value /property property namedfs.datanode.data.dir/name value/opt/hadoop/data/datanode/value /property /configuration EOF参数说明fs.defaultFS是客户端连 HDFS 的入口Java 代码里FileSystem.get()默认读这个值dfs.replication设成 1 是因为伪分布式只有一个 DataNode设成 3 会一直报副本不足hadoop.tmp.dir建议改到非/tmp目录否则重启后数据可能丢。配置 SSH 免密登录和格式化 NameNode# 生成密钥并授权本机免密 ssh-keygen -t rsa -P -f ~/.ssh/id_rsa cat ~/.ssh/id_rsa.pub ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys # 格式化 NameNode只执行一次重复执行会清空数据 hdfs namenode -format # 启动 HDFS start-dfs.sh # 验证进程 jps # 应看到 NameNode、DataNode、SecondaryNameNode 三个进程启动后用hdfs dfs -mkdir /clouddisk建一个云盘根目录再用hdfs dfs -ls /确认。到这里HDFS 存储层就通了。Web 界面在http://localhost:9870可以看文件系统状态和 DataNode 信息。3. 云盘核心功能实现上传、下载与元数据管理3.1 Java API 连接 HDFS 的三种方式和选型云盘系统里服务层要用 Java 操作 HDFS常见有三种方式直接用FileSystemAPI、用hadoop-client依赖、用 WebHDFS REST API。课程设计里最稳的是第二种在 Maven 里引入hadoop-client然后用FileSystem.get()拿实例。!-- pom.xml 里加 Hadoop 客户端依赖 -- dependency groupIdorg.apache.hadoop/groupId artifactIdhadoop-client/artifactId version3.3.6/version /dependency// HDFS 工具类初始化连接、上传、下载 import org.apache.hadoop.conf.Configuration; import org.apache.hadoop.fs.*; import java.io.*; public class HdfsUtil { private static FileSystem fs; // 初始化 FileSystem整个应用共用一个实例 static { try { Configuration conf new Configuration(); // 显式指定 NameNode 地址避免依赖环境变量 conf.set(fs.defaultFS, hdfs://localhost:9000); // 用当前系统用户作为 HDFS 用户避免权限拒绝 System.setProperty(HADOOP_USER_NAME, root); fs FileSystem.get(conf); } catch (IOException e) { throw new RuntimeException(HDFS 初始化失败, e); } } // 上传文件本地路径 - HDFS 路径 public static void upload(String localPath, String hdfsPath) throws IOException { Path src new Path(localPath); Path dst new Path(hdfsPath); // 第三个参数 true 表示目标存在时覆盖 fs.copyFromLocalFile(false, true, src, dst); } // 下载文件HDFS 路径 - 本地输出流 public static void download(String hdfsPath, OutputStream out) throws IOException { Path src new Path(hdfsPath); FSDataInputStream in fs.open(src); byte[] buffer new byte[4096]; int len; while ((len in.read(buffer)) ! -1) { out.write(buffer, 0, len); } in.close(); } }逻辑说明FileSystem.get(conf)会读core-site.xml或代码里设置的fs.defaultFS拿到 NameNode 的 RPC 地址copyFromLocalFile的第二个参数控制是否覆盖云盘场景里同名文件一般要覆盖或改名HADOOP_USER_NAME这个系统属性很关键不设的话在 Windows 开发、Linux 跑 HDFS 的场景下会报Permission denied。参数说明fs.defaultFS必须和core-site.xml里一致HADOOP_USER_NAME设成 HDFS 上有写权限的用户伪分布式下通常是启动 Hadoop 的那个用户。3.2 元数据表设计MySQL 里存什么、怎么和 HDFS 路径对应HDFS 只存文件内容文件名、大小、上传者这些信息要放在 MySQL 里。表结构设计如下CREATE TABLE file_meta ( id BIGINT AUTO_INCREMENT PRIMARY KEY, file_name VARCHAR(255) NOT NULL COMMENT 原始文件名, hdfs_path VARCHAR(512) NOT NULL COMMENT HDFS 上的完整路径, file_size BIGINT NOT NULL COMMENT 文件字节数, content_type VARCHAR(128) COMMENT MIME 类型, user_id BIGINT NOT NULL COMMENT 上传用户 ID, upload_time DATETIME DEFAULT CURRENT_TIMESTAMP, is_deleted TINYINT DEFAULT 0 COMMENT 软删除标记, INDEX idx_user (user_id), INDEX idx_path (hdfs_path(255)) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;设计要点hdfs_path用/clouddisk/{userId}/{uuid}_{fileName}这种格式避免不同用户上传同名文件互相覆盖is_deleted做软删除因为 HDFS 删除是异步的直接删元数据会导致文件变成孤儿file_size存字节数前端展示时再格式化成 KB/MB。上传流程的完整逻辑是前端传文件 → 服务端生成 UUID → 拼接 HDFS 路径 → 调HdfsUtil.upload写入 HDFS → 写入 MySQL 元数据 → 返回文件 ID。下载流程反过来根据文件 ID 查元数据 → 拿hdfs_path→ 调HdfsUtil.download写回响应流。3.3 小文件合并为什么你的 NameNode 内存会爆HDFS 设计目标是存大文件默认块大小 128MB。如果云盘系统里用户上传大量几 KB 的文本文件每个文件都会在 NameNode 内存里占约 150 字节元数据。一万个小文件就是 1.5MB十万个就是 15MB看起来不多但 NameNode 内存还要存块信息、副本状态实际占用会翻几倍。更严重的是每个小文件都会产生一个 Map 任务后续如果要做分析性能会急剧下降。常见做法是上传时如果文件小于 1MB先写到本地临时目录累积到一定数量或大小后用FileUtil.copyMerge或自己写合并逻辑打包成一个大文件再上传元数据里记录偏移量。课程设计里如果不想做这么复杂至少要在上传接口加大小限制比如小于 1KB 的文件拒绝上传或者提示用户打包后再传。// 小文件合并的简化实现把多个小文件合并成一个 SequenceFile import org.apache.hadoop.io.*; import org.apache.hadoop.fs.*; import java.util.List; public static void mergeSmallFiles(ListString hdfsPaths, String mergedPath) throws IOException { Path merged new Path(mergedPath); SequenceFile.Writer writer SequenceFile.createWriter( fs.getConf(), SequenceFile.Writer.file(merged), SequenceFile.Writer.keyClass(Text.class), SequenceFile.Writer.valueClass(BytesWritable.class) ); for (String path : hdfsPaths) { FSDataInputStream in fs.open(new Path(path)); byte[] data new byte[(int) fs.getFileStatus(new Path(path)).getLen()]; in.readFully(data); // key 用原文件路径value 用文件内容 writer.append(new Text(path), new BytesWritable(data)); in.close(); } writer.close(); }这段代码把多个小文件写成一个 SequenceFilekey 是原路径value 是内容。读取时按 key 查找即可。参数上注意BytesWritable会复制字节数组大文件合并时内存占用高实际生产里会用FSDataOutputStream流式写。4. 避坑与排查云盘系统跑不起来时先看这几条4.1 上传报 Connection refusedNameNode 地址和端口对不上现象Java 代码里FileSystem.get()抛java.net.ConnectException: Call From xxx to localhost:9000 failed on connection exception。原因core-site.xml里fs.defaultFS写的是hdfs://localhost:9000但代码里没加载到这个配置或者 Hadoop 根本没启动。伪分布式下 NameNode 的 RPC 端口默认是 9000Web 端口是 9870两个别搞混。解决先jps确认 NameNode 进程在再netstat -tlnp | grep 9000确认端口监听代码里显式conf.set(fs.defaultFS, hdfs://localhost:9000)不要依赖环境变量。4.2 上传报 Permission deniedHADOOP_USER_NAME 没设现象org.apache.hadoop.security.AccessControlException: Permission denied: userAdministrator, accessWRITE, inode/clouddisk。原因Windows 下用 IDEA 开发时Hadoop 客户端默认用当前系统用户名比如 Administrator去连 HDFS而 HDFS 上只有启动 Hadoop 的那个用户有写权限。解决在代码最前面加System.setProperty(HADOOP_USER_NAME, root)或者在 IDEA 的 VM options 里加-DHADOOP_USER_NAMEroot。这个坑在 Windows 下用 IDEA 搭建 Hadoop 开发环境时几乎必踩。4.3 下载大文件内存溢出没有用流式读写现象下载 500MB 以上文件时服务端 OOM日志里java.lang.OutOfMemoryError: Java heap space。原因很多示例代码用fs.open()拿到流后直接readAllBytes()或把整个文件读进byte[]文件一大就爆。解决用固定大小 buffer 循环读写比如 8KB 或 16KB边读边写响应流。上面HdfsUtil.download里用的就是 4096 字节 buffer实际可以调到 8192 或 16384减少系统调用次数。4.4 重启后文件丢失hadoop.tmp.dir 指向了 /tmp现象机器重启后hdfs dfs -ls /发现之前上传的文件全没了NameNode 重新格式化过一样。原因core-site.xml里hadoop.tmp.dir默认是/tmp/hadoop-${user.name}很多系统重启会清空/tmp。解决把hadoop.tmp.dir改到/opt/hadoop/data/tmp这种持久化目录并且确保dfs.namenode.name.dir和dfs.datanode.data.dir也在持久化路径下。改完要重新格式化并重启。4.5 前端上传超时没配 multipart 大小限制现象上传超过 1MB 的文件时前端报 413 或连接重置后端日志没有收到请求。原因Spring Boot 默认的spring.servlet.multipart.max-file-size是 1MBmax-request-size是 10MB云盘场景肯定不够。解决在application.yml里改成max-file-size: 500MB、max-request-size: 500MB同时 Nginx 如果做了反向代理client_max_body_size也要同步改大。5. 验证与进阶怎么确认这套云盘系统真的能演示5.1 用命令行和 Web 端交叉验证文件一致性系统跑起来后不要只看页面上传成功就完事。要交叉验证Web 端上传一个文件 → 记下返回的文件 ID → 去 MySQL 里SELECT hdfs_path FROM file_meta WHERE idxxx→ 用hdfs dfs -ls /clouddisk/...看 HDFS 上有没有这个文件 → 用hdfs dfs -cat看内容是否一致。反过来用hdfs dfs -put手动传一个文件到 HDFS看 Web 端文件列表能不能通过元数据扫描发现它如果做了扫描功能的话。这个验证过程能帮你发现很多隐藏问题比如元数据写入了但 HDFS 写入失败、HDFS 路径拼接时多了或少了斜杠、文件大小记录的是本地临时文件大小而不是实际写入大小。5.2 从伪分布式到集群什么时候需要加机器伪分布式够用但如果你要演示“分布式”特性可以加一台 DataNode。步骤是在新机器上装好 Hadoop改core-site.xml指向 NameNode 的地址改hdfs-site.xml的dfs.replication为 2然后在 NameNode 的workers文件里加上新机器的主机名重启 HDFS。用hdfs dfsadmin -report能看到两个 DataNode。但要注意课程设计里加机器不是必须的伪分布式 清晰的架构图 代码里体现 HDFS API 调用已经能说明问题。把时间花在元数据设计、小文件处理、上传下载的异常处理上比折腾多节点集群更划算。5.3 一个我踩过的坑HDFS 路径里的中文和空格最后说一个血泪经验。用户上传的文件名里带中文或空格时如果直接拼到 HDFS 路径里Path对象在某些 Hadoop 版本下会编码异常导致文件写进去但读不出来。我一般的做法是HDFS 路径里只用 UUID 和用户 ID原始文件名只存在 MySQL 的file_name字段里下载时从元数据取原始文件名设置到Content-Disposition响应头。这样 HDFS 路径永远是 ASCII 安全的中文和空格问题在元数据层解决。这套方案从伪分布式搭建到上传下载闭环再到小文件合并和避坑基本覆盖了“基于 Hadoop 的云盘系统”这个题目在课程设计和入门实战里的核心内容。先把单机跑通再考虑扩展别一上来就纠结集群和性能。希望帮到你。本文还有配套的精品资源点击获取