简介一个仿百度网盘的小型云盘系统完整工程包基于Java Web技术栈实现面向Java后端初学者或需要快速搭建在线存储场景的开发者。系统覆盖文件上传、下载、分享、管理等核心功能采用Spring MVC/Servlet/JSP分层设计包含Controller、Service、数据访问与数据库脚本等完整目录结构。资源共204个文件以Java源码、编译后的class文件及第三方jar依赖为主兼有png/js/css前端资源、jsp页面和sql数据库脚本压缩包仅4.55MB轻量便于下载后直接导入IDE查看。目前已有346人浏览学习。通过学习可掌握Java Web项目从请求处理、业务逻辑到数据持久化的完整链路同时理解用户认证、权限控制与文件I/O等常见实战问题并可直接复用上传下载模块代码适合作为课程设计或入门练手的参考。1. 这个JavaWeb小型云盘系统到底在解决什么问题如果你带过团队或做过课程设计一定遇到过这种场景一份作业文档在教室电脑、宿舍笔记本、手机三个地方各存了一个版本最后交上去的却是最旧的那个。所谓“仿百度网盘的小型云盘系统”其实解决的就是这个痛点——用一个浏览器能访问的Web系统把文件集中存到一台服务器上按用户隔离随时上传、下载、分享给自己的另一个设备。它不是什么高深架构就是用JavaWeb那一套Servlet、JSP、MySQL把“文件上传下载”这件事做成一个完整可用的产品。这套项目最典型的读者是刚学完JavaWeb、准备做课设或毕设的学生以及想自己搭一个私有网盘、又不想上SpringBoot全家桶的开发者。它和网上下载那些“管理系统”最大的不同是文件是真正的二进制实体不是一行字符串你能实实在在看到文件被存进磁盘、被下载回来这种成就感比增删改查强得多。同时它也是一个少有的、能把JavaWeb几乎全部知识点串起来的项目请求转发、文件IO、数据库设计、前端交互、部署配置全都要碰一遍。2. 先设计存储模型四张表怎么拆文件实体和用户文件为什么必须分开2.1 用户表、文件表、用户文件表、文件夹表缺哪张都会踩坑动手写代码之前先把数据库表想清楚。云盘和普通管理系统的本质区别在于同一个文件可能被多个用户各自保存一份但服务器上不能真存两份否则磁盘很快就满了。所以表结构必须把“文件实体”和“用户与文件的关系”拆开。第一张是用户表user字段就是id、username、password、register_time登录注册用。第二张是文件实体表file核心字段是file_md5文件指纹、file_path实际存储路径、file_size、upload_time。第三张是用户文件表user_file记录某个用户拥有哪个文件字段是id、user_id、file_id、folder_id、file_name用户在网盘里显示的名字、upload_time、is_delete。最后一张是文件夹表folder实现网盘目录树字段是id、user_id、parent_id、folder_name。为什么file表和user_file表必须拆开因为百度网盘的“秒传”就是靠这个设计实现的。两个用户上传同一个文件MD5一致file表里只有一条记录第二个用户只是在user_file表里加了一条关联。如果不拆用户传一次文件就写一行磁盘路径一个100MB的文件传10次就占1GB空间这就是典型的垃圾数据。CREATE TABLE user ( id INT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) UNIQUE NOT NULL, password VARCHAR(255) NOT NULL, register_time DATETIME DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE file ( id INT PRIMARY KEY AUTO_INCREMENT, file_md5 CHAR(32) UNIQUE NOT NULL, file_path VARCHAR(255) NOT NULL, file_size BIGINT NOT NULL, upload_time DATETIME DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE user_file ( id INT PRIMARY KEY AUTO_INCREMENT, user_id INT NOT NULL, file_id INT NOT NULL, folder_id INT DEFAULT 0, file_name VARCHAR(255) NOT NULL, upload_time DATETIME DEFAULT CURRENT_TIMESTAMP, is_delete TINYINT DEFAULT 0, KEY idx_user_folder (user_id, folder_id, is_delete) ); CREATE TABLE folder ( id INT PRIMARY KEY AUTO_INCREMENT, user_id INT NOT NULL, parent_id INT DEFAULT 0, folder_name VARCHAR(255) NOT NULL, create_time DATETIME DEFAULT CURRENT_TIMESTAMP );这段DDL里file_md5设了UNIQUE约束这是秒传能落地的前提。user_file里的folder_id默认0代表根目录和folder表的id对应查询某目录下的文件列表时SQL是SELECT * FROM user_file WHERE user_id ? AND folder_id ? AND is_delete 0简单又高效。注意我特意没在file表里放user_id因为文件实体是全局共享的不属于任何单一用户。2.2 文件真正存在哪里项目目录还是绝对路径这决定项目能不能重启表结构定了下一个问题就是文件往磁盘上放哪。新手最常见的做法是写道String path upload/相对路径结果在IDEA里跑得好好的一打包部署就报FileNotFoundException——因为相对路径是相对于Tomcat进程的启动目录而不一定是你项目的根目录。更麻烦的是很多人在IDEA里运行项目时当前目录在target下往upload/写文件实际上写到了target/classes/的兄弟目录下次clean一下文件全没了像没传过一样。我一般会在配置文件里写一个绝对路径前缀用properties文件或web.xml里的context-param读取。比如// 在 web.xml 中配置 context-param param-nameupload.storage.path/param-name param-valueD:/clouddisk//param-value /context-param // 在 Servlet 中读取 String basePath getServletContext().getInitParameter(upload.storage.path); File dir new File(basePath); if (!dir.exists()) { dir.mkdirs(); }这里有一个生产环境必须处理的细节不能直接把用户上传的全部文件堆在一个目录里否则超过几千个文件后文件系统的检索速度会明显变慢而且Windows下一个目录的文件数太多还会报错。常见做法是按日期分桶D:/clouddisk/2025/06/01/uuid.file。这样每个目录下文件数量可控也方便按时间清理旧数据。2.3 用户看到的文件名和磁盘文件名必须分离否则重名和乱码同时爆炸还有一处必须提前埋好伏笔用户上传一个项目报告最终版(1).docx你把它存到磁盘时绝不能直接用它原来的文件名。因为另一个用户可能也上传了一个项目报告最终版(1).docx如果直接把文件名写到磁盘两个文件就互相覆盖了。正确做法是磁盘上用一个唯一名字比如UUID.randomUUID().toString() originalExtension而用户看到的显示名只存到user_file.file_name字段里。这样设计下载时从user_file取显示名拼到响应头上传时从磁盘取真实文件名读取流。两条线互不干扰重名覆盖问题从根上消失了。很多在网上下载的烂代码就是直接在磁盘路径上拼原始文件名导致传几个文件后数据就乱了。这一点如果你是要基于别人那份.zip源码做改造的建议先打开源码看一眼它的存储方案如果是用原名存储尽早改成UUID方案再继续往下加功能。3. 用Servlet把上传下载跑通Commons FileUpload和默认servlet的取舍3.1 上传接口multipart/form-data的解析与写入云盘最核心的操作就是上传。JavaWeb层面主流有两种做法一是用Servlet 3.0自带的MultipartConfig加getPart()方法二是用Apache Commons FileUpload组件。前者更简洁、无额外依赖但分片上传时处理起来稍微麻烦一点后者的setSizeMax、setFileSizeMax能精确控制上传大小对做网盘来说更灵活。我这里用Commons FileUpload做示例因为它的回调接口比原生Servlet更适合做进度展示而且网上多数JavaWeb网盘项目源码也是用它。protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // 检查是否真的上传了文件 if (!ServletFileUpload.isMultipartContent(request)) { response.sendError(400, 请求不是multipart/form-data类型); return; } DiskFileItemFactory factory new DiskFileItemFactory(); // 内存缓冲阈值小于这个值的文件直接存内存避免频繁IO factory.setSizeThreshold(1024 * 1024); // 1MB // 临时目录超过阈值的部分先写临时文件防止大文件撑爆内存 factory.setRepository(new File(System.getProperty(java.io.tmpdir))); ServletFileUpload upload new ServletFileUpload(factory); upload.setFileSizeMax(1024 * 1024 * 1024); // 单个文件最大1GB upload.setSizeMax(1024 * 1024 * 1024 * 5); // 整个请求最大5GB try { ListFileItem items upload.parseRequest(request); for (FileItem item : items) { if (!item.isFormField()) { // 非表单字段即文件本体 String originalName item.getName(); // IE/Edge 的 fileName 会带全路径必须截取最后一个反斜杠之后的部分 originalName originalName.substring(originalName.lastIndexOf(\\) 1); String ext originalName.contains(.) ? originalName.substring(originalName.lastIndexOf(.)) : ; // 生成磁盘存储名用户可见名存在DB里 String diskName UUID.randomUUID().toString().replace(-, ) ext; String today new SimpleDateFormat(yyyy/MM/dd).format(new Date()); String savePath basePath today; File dir new File(savePath); if (!dir.exists()) dir.mkdirs(); File savedFile new File(dir, diskName); item.write(savedFile); // 关键写入方法内部处理了内存/临时文件的切换 // 计算MD5为秒传做准备 String md5 MD5Util.getFileMD5(savedFile); long size savedFile.length(); // 写入file表和user_file表见下方注解说明 saveFileRecord(originalName, diskName, md5, size, today.replace(/, -) / diskName); } } response.getWriter().write({\code\:0,\msg\:\上传成功\}); } catch (Exception e) { e.printStackTrace(); response.getWriter().write({\code\:1,\msg\:\上传失败: e.getMessage() \}); } }这段代码有几个参数值得细说。setSizeThreshold(1MB)表示文件小于1MB时全走内存超过1MB才落临时文件这个值不是越大越好太大会导致并发上传时内存直接被打满。setFileSizeMax和setSizeMax必须同时设因为攻击者可以构造一个超大请求体如果只限制单个文件大小绕过约束后内存还是会被拖垮。item.write(savedFile)是FileUpload组件内部帮我们处理了文件“从临时文件/内存复制到目标文件”的过程写完后item.delete()会自动执行清理不用手动删临时文件。MD5计算放在这一步其实是合理的虽然文件已经写盘但磁盘IO省不掉。注意saveFileRecord里file表插入时要以md5做唯一键查重已存在则不再重复插入file表而是直接在user_file表新增关联——这就是“服务端秒传”的第一版。3.2 下载接口文件流响应和文件名的URL编码下载比上传简单多了但坑都藏在响应头里。新手写的下载代码经常是response.setHeader(Content-Disposition, attachment;filename fileName)然后查百度发现“文件名中文全变乱码了”。问题出在HTTP头只认ISO-8859-1编码而Java字符串默认是UTF-8直接拼进去浏览器解码必然乱码。protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { String userFileId request.getParameter(id); // 根据user_file_id查出显示名、磁盘路径 UserFile userFile fileService.getUserFileById(Long.parseLong(userFileId)); File file new File(basePath userFile.getDiskPath()); if (!file.exists()) { response.sendError(404, 文件不存在或已被删除); return; } // 关键文件名按RFC 5987规范编码兼容绝大多数现代浏览器 String encodedName URLEncoder.encode(userFile.getFileName(), UTF-8) .replaceAll(\\, %20); response.setContentType(application/octet-stream); response.setHeader(Content-Disposition, attachment;filename*UTF-8 encodedName); response.setContentLengthLong(file.length()); try (FileInputStream fis new FileInputStream(file); OutputStream os response.getOutputStream()) { byte[] buffer new byte[8192]; int len; while ((len fis.read(buffer)) ! -1) { os.write(buffer, 0, len); } os.flush(); } }下载接口这个id参数看起来简单实际是权限校验的入口。这里不能直接传磁盘路径给前端否则用户把路径改了就能下载任意文件——必须改成传user_file.id后端再校验这个user_file记录的user_id是否等于当前登录用户的id。很多墙外的开源JavaWeb项目没做这一步直接?pathxxx就能下载服务器上任意文件属于比较严重的安全漏洞。文件流必须用try-with-resources写否则连接不关闭高峰期会把Tomcat的连接池耗尽。Content-Disposition用filename*UTF-8这种写法是RFC 5987标准旧浏览器不认但主流的Edge和Chrome都支持。如果还要兼容IE就得同时给filename参数一个ASCII回退。setContentLengthLong不设也能下载但设置了可以让浏览器显示真实的下载进度属于体验优化。3.3 文件列表页不要一次性查全表有了上传下载剩下就是网盘主页的文件列表。这一步不写具体页面代码但有一个必须注意的实践不要用SELECT * FROM user_file WHERE user_id ?把所有记录一次查出来然后渲染到JSP。文件数量一多页面会非常卡。正确做法是分页查询SELECT uf.id, uf.file_name, uf.upload_time, f.file_size FROM user_file uf LEFT JOIN file f ON uf.file_id f.id WHERE uf.user_id ? AND uf.folder_id ? AND uf.is_delete 0 ORDER BY uf.upload_time DESC LIMIT 10 OFFSET ?;LEFT JOIN file是为了拿到file_size因为用户文件表里不冗余存大小避免多个用户共享同一个文件时数据不一致。分页参数一页10条或20条前端翻页时改OFFSET就行。这一条SQL也是后面做“按文件名搜索”功能的基础直接加一个AND uf.file_name LIKE ?就完事。4. 给云盘加网盘级功能MD5秒传接口与前端计算4.1 秒传的正确实现顺序前端算Hash后端只查表真正的网盘秒传不是等服务端收完文件再算MD5——那叫“传完校验”毫无秒传意义。正确顺序是前端把文件读进内存用JavaScript计算整个文件的MD5然后把MD5连同文件名发给后端后端先查这个MD5在不在file表里。在就只给user_file表插一条记录告诉前端“秒传成功”不在才走正常上传流程。这个方案能把秒传的判定时机提前到传输之前。这里有个技术选型细节千万不能用后端算MD5做秒传因为文件还没传上来后端连文件内容都看不到。如果你拿到的那份源码里秒传接口是String md5 request.getParameter(md5)那就对了如果它把文件先写到磁盘再算MD5判断秒传那这个“秒传”只是省了数据库写入没省网络传输是假秒传。前端计算MD5常见用spark-md5库它支持分块读取不会把整个文件一次性载入内存导致浏览器卡死。4.2 秒传接口示例与重复文件判断逻辑后端秒传处理逻辑核心就是把“文件实体”和“用户文件记录”两件事分开处理写出来并不复杂但它牵扯到“要不要做事务”这个关键问题。protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { String fileName request.getParameter(fileName); String md5 request.getParameter(md5); Long folderId Long.parseLong(request.getParameter(folderId)); Long userId getLoginUserId(request); // 第一段查询按MD5在file表里找有没有已存在的文件实体 FileRecord existingFile fileDao.getByMd5(md5); // 第二段判断这个用户自己的目录里是否已经有同名文件重名检测 boolean isDuplicated userFileDao.exists(userId, folderId, fileName); // 事务边界响应结果前先预处理两条分支 response.setContentType(application/json;charsetUTF-8); PrintWriter out response.getWriter(); if (isDuplicated) { out.write({\code\:2,\msg\:\当前目录已存在同名文件\}); return; } if (existingFile ! null) { // 磁盘上有实体则复用物理文件只新增关联记录 userFileDao.insert(userId, folderId, fileName, existingFile.getId()); out.write({\code\:0,\msg\:\秒传成功\}); } else { // 磁盘上没有实体返回标志让前端走真正的分片/整包上传 out.write({\code\:3,\msg\:\file_not_exists\}); } }逻辑看着简单但因为两条insert/select出现在不同分支里如果userFileDao.insert成功后前端网络断开那么这个用户就拥有了一条指向不存在file记录的文件清单下次下载会404。所以严谨一点的实现要在existingFile ! null分支里把“插入file表”和“插入user_file表”包在一个事务里——但这里因为file表已经有那条记录了所以只需保证userFileDao.insert不会因为file_id不存在而外键报错即可。实际开发展中遇到最多的坑是fileDao.getByMd5(md5)把MD5传成大写而存储时是32位小写十六进制导致永远查不到秒传永远不生效。这个问题排错半小时很常见处理方式是统一在DAO层做md5.toLowerCase()。public FileRecord getByMd5(String md5) { String sql SELECT * FROM file WHERE file_md5 ?; // md5参数统一转为小写防止大小写不一致导致秒传失效 return jdbcTemplate.queryForObject(sql, new Object[]{md5.toLowerCase()}, mapper); }4.3 分片上传合并片的顺序由文件名里的索引决定分片上传给用户的体验是“断点续传”但在后端实现上其实比较粗暴前端把文件切块每个块单独用multipart/form-data上传后端把每个块存成一个临时文件等所有块传完后按顺序合并。核心难点只有两个临时文件放哪、合并顺序怎么保证。// 接收单片的上传请求 protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { String uploadId request.getParameter(uploadId); // 前端生成的本次上传会话ID int chunkIndex Integer.parseInt(request.getParameter(chunkIndex)); FileItem fileItem getFileItem(request); // 临时分片目录/temp/upload_uploadId/ File chunkDir new File(tempBasePath, upload_ uploadId); if (!chunkDir.exists()) chunkDir.mkdirs(); File chunkFile new File(chunkDir, chunk_ chunkIndex); fileItem.write(chunkFile); response.getWriter().write({\code\:0,\msg\:\分片接收成功\}); }合并接口则把所有片读出来按顺序写入同一个目标文件// 合并所有分片 protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { String uploadId request.getParameter(uploadId); String originalName request.getParameter(originalName); int totalChunks Integer.parseInt(request.getParameter(totalChunks)); File chunkDir new File(tempBasePath, upload_ uploadId); File finalFile new File(targetBasePath, UUID.randomUUID().toString()); try (FileOutputStream fos new FileOutputStream(finalFile)) { for (int i 0; i totalChunks; i) { File chunk new File(chunkDir, chunk_ i); if (!chunk.exists()) { // 缺失某个分片前端需要重新上传该片 response.getWriter().write({\code\:1,\msg\:\missing chunk i \}); return; } Files.copy(chunk.toPath(), fos); } } // 合并成功后删除整个临时目录 deleteDir(chunkDir); // 后续入库逻辑与秒传失效场景一致查file表、插入user_file表 }这里最容易翻车的是分片序号从0还是从1开始。前端如果从0开始后端循环就得从0开始前端从1开始后端从1开始。前后端不一致时合并出来的文件会整体偏移一个片文件头部可能是一段垃圾数据。设定参数时最好在接口文档里写死“chunkIndex从0开始”前后端都按这个约定来排错成本最低。另一个坑是前端并发上传分片时后端必须保证同一时间多个分片写的是各自独立的文件所以每个分片必须以“uploadId chunkIndex”组成唯一文件名不能用uploadId 临时这种共享名字。5. 常见问题与排查思路从500到文件消失的五类翻车现场5.1 现象上传后文件报404或下载500原因分两层。第一层是IDEA/MyEclipse里运行时项目工作目录与当前模块不一致使用相对路径导致文件写到别的盘去了。第二层是文件确实存在但下载时用了new File(相对路径)去读取而相对路径是相对Tomcat的启动bin目录不是项目根目录。解决的办法是统一收口所有路径拼接必须经过一个PathResolver类从配置读取绝对路径根目录所有Servlet里禁止出现裸的相对路径字符串。这样排查问题时只需看一个类而不是全局搜索路径。血泪经验是千万别把路径散落在JSP的href和Servlet的new File里否则改一处漏一处。提示在IDEA中配置Tomcat时观察到Working directory参数默认是Tomcat的bin目录这一点是很多“重启项目后文件消失”问题的来源之一。5.2 现象下载中文文件名乱码原因是HTTP响应头的filename参数只支持ISO-8859-1编码的字节序列而Java字符串默认UTF-8。直接response.setHeader(Content-Disposition, attachment;filename 中文名.zip)浏览器收到的就是乱码。解决方法是统一走RFC 5987编码filename*UTF-8URLEncoder.encode(fileName, UTF-8)。这里还有一个坑URLEncoder.encode会把空格编码成而在URL里本身就是空格的意思不需要额外反转但如果你把它当成加号原样输出部分浏览器会在文件名里多出一个加号。所以几乎所有踩过这个坑的人都会写上那一句.replaceAll(\\, %20)。这是真正的血泪经验。5.3 现象文件顺利用浏览器路径下载但JSP里点击按钮没反应这几乎都是前端把下载地址拼错了。典型错误是hrefdownload?id${file.id}——file.id对应的是user_file.id而download这个Servlet里查的是file.id两边对不上。排查这种问题直接在浏览器F12里看请求的URL和参数对比后端映射的Servlet路径是否一致比看代码快得多。还有一种情况是JSP里${file.id}没经过URLEncoder处理文件名含特殊字符导致URL解析截断。统一用fn:escapeXml或c:url标签处理是一种防呆做法。5.4 现象上传100MB以上文件时内存溢出或卡死如果用的是Servlet 3.0原生MultipartConfig且没设maxFileSize大文件会被直接读进内存OOM只是时间问题。解决有两种一是改成Commons FileUpload并设置setSizeThreshold(1MB)超过阈值的部分自动写临时文件二是用流式解析比如FileUpload的ProgressListener逐块处理但后者写起来更繁琐。如果项目的目标是小型云盘不建议自己用HttpServletRequest.getInputStream()手动parse工作量太大还不稳定直接用ServletFileUpload就好。5.5 现象端口8080被占用Tomcat一直启动不了这是借黑马JavaWeb笔记或刚配好IDEA运行环境的人最常遇到的一类报错。控制台里会看到Port 8080 required by Tomcat v9.0 Server at localhost is already in use。解决方式是在Windows终端执行netstat -ano | findstr 8080找到监听8080端口的PID然后看这个进程是什么tasklist /fi pid eq 1234是残留的Tomcat进程就taskkill /f /pid 1234是别的程序占用了就改Tomcat的server.xml端口。这个排查思路适用于任何端口冲突问题比在IDEA里反复重启Tomcat高效得多。提示多例Tomcat同时运行时确认一下server.xml里的三个端口HTTP/1.1、AJP、shutdown是否全部改过新手只改了HTTP端口没改AJP端口时报错会更隐蔽。6. 把文件下载地址变成短链对外分享的落地技巧网盘系统做得差不多了最后一个值得加的功能就是分享外链。百度网盘那种“提取码”是产品层面的设计技术实现上最核心的一件事是把“真实文件地址”和“对外展示地址”彻底分离。前面下载接口已经是download?id的形式这就是短链的基础。在此基础上加一张share表字段是id、user_file_id、share_code随机短码、expire_time、create_time。分享时生成share_code UUID.randomUUID().toString().substring(0, 8)对外链接就是http://你的域名:8080/cloud/share?codeabc12345访问时拿code查出user_file_id再跳转到实际的下载逻辑。这里加一个限制分享链接不要直接拼user_file_id因为id是自增的别人把id改小一号就能下载你没公开的文件。分享码必须是随机串而且要设置过期时间定时清理过期记录。如果想让分享地址更短可以在share表里加一个short_url字段用62进制把id编码成短串纯后端做也就几十行代码。但记住一个原则短链服务最怕的是“短”到可以被暴力遍历所以share_code最少8位且大小写混合。发布到公网时还有两件事值得提前验证。第一把basePath从D:/clouddisk/改成Linux风格路径后所有路径拼接代码要有意识地用File.separator而不是手写/。第二Tomcat默认支持的文件上传大小限制是2GB如果云盘需要支持更大文件要在server.xml的Context里加allowCasualMultipartParsingtrue并调大maxPostSize或者直接换用Nginx做上传转发免得Tomcat成为瓶颈。我个人的习惯是在任何项目交付前都会做一次“从零启动测试”删除target目录、清空数据库、用部署包重新解压启动然后上传一个文件、下载回来、比对MD5。只要这个流程顺畅这个系统的基础功能就不会给用户添堵。云盘系统的核心交付物应该是“文件不丢、不乱、访问可控”而不是比拼谁的前端更花哨。希望这份笔记能帮你在改造或重写这份JavaWeb网盘项目时少走几个弯路。本文还有配套的精品资源点击获取