尧图网站建设 
不用多说能把这套东西跑起来的人多半已经在“自己存东西”这件事上被各种网盘折磨过。限速、和谐、会员到期空间不够随便一条就够让人头疼。自己搭一个个人网盘管理系统不只是为了“有个地方放文件”更核心的价值在于数据完全在自己手里目录结构自己说了算想怎么分类就怎么分类想要什么功能自己加。这篇博文就围绕一个基于 Java Vue 的个人网盘管理系统来拆包含源码结构、数据库设计、前后端实现思路、部署落地、踩坑记录全流程走一遍。标题里虽然写了“源码数据库文档”但光有这三样不会用等于白拿真正要搞懂的是它背后的设计逻辑和运行机制。我默认你是有一定 Java 基础的开发者至少熟悉 Spring Boot 的基本用法懂一点 Vue 的项目结构。如果你是刚学完 SSM 或 Spring Boot 的学生这篇也能让你搞明白一个完整项目到底是怎么串起来的。1. 项目整体设计与技术选型1.1 为什么是 Java Vue而不是其他方案个人网盘这种系统本质上就是“文件管理 用户系统 分享功能”的组合。市面上的实现方案五花八门有 Python 的 FastAPI 方案有 Node.js 的 NextCloud 二次开发甚至有人直接拿 PHP 的 h5ai 凑合。但 Java Vue 这个组合能成为大多数教学项目和企业内部工具的首选原因很实在Java 生态对文件处理的支持非常成熟。Spring Boot 封装了文件上传下载的标准流程MultipartFile 接口配合 CommonsMultipartResolver 或者标准 Servlet 容器就能处理绝大多数场景如果你要接 OSS、S3 或者 FastDFSJava 的 SDK 也是最全的。Vue 的组件化开发适合做这种工具型前端。文件列表、上传进度条、文件夹树、分享弹窗这些都是天然独立的组件切分清楚后代码维护成本很低。部署环境友好。一台 2G 内存的小服务器就能跑起来后端打成 jar 包前端 build 完丢到 Nginx 里单体架构搞定一个个人网盘绰绰有余。这个项目采用典型的单体应用架构Spring Boot 做后端 APIVue 做前端页面MySQL 存元数据文件本体存储在服务器磁盘目录中。没有引入消息队列也没有上微服务对个人网盘这种量级的项目来说那些东西纯粹是给自己找麻烦。1.2 项目模块划分我在梳理这套源码的时候习惯先把项目结构在脑子里画一张图再去看代码就快很多。这个个人网盘系统的后端结构大致是这样src/main/java/com/example/disk/ ├── config/ // 配置类跨域、拦截器、WebMVC ├── controller/ // 接口层文件、用户、分享、回收站 ├── service/ // 业务逻辑层 ├── mapper/ // MyBatis 数据访问层 ├── entity/ // 实体类对应数据库表 ├── common/ // 通用返回结果、异常处理 └── util/ // 工具类MD5、JWT、文件名处理等前端结构上Vue 项目走的是标准 Vue CLI 工程路径src/ ├── api/ // 接口请求封装 ├── assets/ // 静态资源 ├── components/ // 通用组件上传组件、文件列表组件 ├── router/ // 路由配置 ├── store/ // Vuex 状态管理 └── views/ // 页面我的网盘、分享页面、登录注册这套结构没什么高深的但它很标准。标准的价值在于出了问题你知道去哪里找。Controller 出问题就看接口层数据不对就看 Mapper 的 SQL页面交互不对就看对应 view 组件排查效率高很多。1.3 核心功能清单从源码里可以提炼出这个系统完整的功能矩阵也是我做技术拆解的主线功能模块核心能力技术要点用户系统注册、登录、JWT 鉴权Spring Security JWT文件管理上传、下载、删除、重命名、移动MultipartFile、文件流目录管理新建文件夹、目录树展示、路径追踪parent_id 层级结构文件预览图片/视频/文档在线预览前端 blob 流、对象 URL分享功能生成分享链接、提取码、过期时间短码生成、定时清理回收站软删除、恢复、彻底删除is_delete 字段标记搜索功能按文件名模糊搜索MySQL LIKE 查询每个功能单独拉出来都不难但合在一起要考虑的细节就多了。比如重名文件的命名策略、文件夹递归删除的实现、分享码的唯一性保证、大文件上传时内存溢出的规避——这些才是项目里真正值钱的地方。2. 数据库设计与核心表结构2.1 表结构设计思路个人网盘的数据库设计核心就三张表用户表、文件信息表、分享表。别看业务功能不少只要文件信息表设计得足够灵活其他表都是围绕它转的。先看用户表这个最常规CREATE TABLE user ( id int(11) NOT NULL AUTO_INCREMENT, username varchar(64) NOT NULL UNIQUE, password varchar(128) NOT NULL, salt varchar(32) DEFAULT NULL, email varchar(128) DEFAULT NULL, register_time datetime DEFAULT CURRENT_TIMESTAMP, status tinyint(4) DEFAULT 1, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;密码字段必须存密文这里用了 salt 哈希的方式。有人可能会问为什么不直接用 BCrypt 或 MD5这取决于源码的原始实现。如果项目用的是 MD5 Salt 方式也够用只要不存明文就行。但要是我自己重构这个项目我会换成 BCrypt因为 Java 的 jBCrypt 库用起来也不复杂而且抗彩虹表能力更强。文件表是整个系统的灵魂CREATE TABLE file_info ( id bigint(20) NOT NULL AUTO_INCREMENT, user_id int(11) NOT NULL COMMENT 所属用户, file_name varchar(255) NOT NULL COMMENT 文件名, file_path varchar(512) DEFAULT NULL COMMENT 存储路径相对路径, file_size bigint(20) DEFAULT 0 COMMENT 文件大小字节, file_type varchar(50) DEFAULT NULL COMMENT 文件类型, is_folder tinyint(1) DEFAULT 0 COMMENT 是否文件夹, parent_id bigint(20) DEFAULT 0 COMMENT 父目录ID0为根目录, is_delete tinyint(1) DEFAULT 0 COMMENT 是否删除回收站, create_time datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_user_parent (user_id, parent_id), KEY idx_parent_delete (parent_id, is_delete) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这里最关键的设计是parent_id 自关联。文件夹和文件放在同一张表里通过 parent_id 指向父文件夹的 id根目录的 parent_id 为 0。这种设计的好处是统一的表结构简化了查询逻辑新增文件和新增文件夹走同一个接口前端渲染目录树也只需根据 parent_id 递归组装即可。把权限字段放一边单看这个表的索引设计就能发现作者是有意识的idx_user_parent保证了“当前用户的某目录下有哪些文件”这种高频查询走联合索引idx_parent_delete则对应回收站场景中“某目录下的非删除文件列表”的查询。这在数据量不大的时候感觉不到差别但表里堆到几十万行的时候有没有这两个索引就是天壤之别。2.2 分享表和回收站的实现细节分享表的设计也值得一提CREATE TABLE share_info ( id int(11) NOT NULL AUTO_INCREMENT, user_id int(11) NOT NULL, file_id bigint(20) NOT NULL, share_code varchar(16) NOT NULL COMMENT 提取码, share_url varchar(255) DEFAULT NULL COMMENT 分享链接, expire_time datetime DEFAULT NULL COMMENT 过期时间, visit_count int(11) DEFAULT 0 COMMENT 访问次数, create_time datetime DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY uk_share_code (share_code) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;share_code 这个字段有唯一约束这是为了避免多个分享链接撞码。生成提取码的地方一般会用随机字符串比如 UUID 截取前 6 位或者自己写一个短码生成器。为了确保唯一性插入前先查一下再决定是否重新生成或者直接靠数据库的唯一索引兜底插入失败就重试这是常见的两种思路。回收站的实现不走单独建表而是用 file_info 里的is_delete字段做软删除。好处很明显恢复文件时只需要把 is_delete 改回 0目录结构就自动还原了不需要折腾数据迁移。代价是每次正常的文件列表查询都要带is_delete 0条件这是一点性能上的小牺牲但换来的业务逻辑简便性完全值得。2.3 源码里的 SQL 脚本能直接用吗大多数这类项目的源码包里都会带一个.sql文件这个项目的初始化脚本同样如此。导入数据库的时候有几点要注意第一MySQL 的版本差异。现在很多项目已经写了utf8mb4和InnoDB如果你本地还是 MySQL 5.5 或更早的版本DATETIME DEFAULT CURRENT_TIMESTAMP这种语法可能直接报错需要调整成 TIMESTAMP 类型或者去掉默认值。第二数据库连接配置要改。Spring Boot 的application.yml里通常默认写的是 root / 123456连的库名是 disk 之类。如果你本地的密码不同启动后端之前先改掉不然报连接失败的错误会让你误以为是代码问题。第三注意时区参数。serverTimezoneAsia/Shanghai这个参数不加上高版本的 MySQL 驱动在连接时会因为时区问题抛异常。这是非常经典的坑我第一次跑类似项目的时候这个报错卡了我一个多小时。3. 后端核心功能实现解析3.1 登录鉴权JWT 的完整接入方式现在的 Java 项目Spring Security 全家桶 JWT 基本是标配。不过很多源码项目为了降低复杂度会直接引入一个叫做jwt的工具类配合 Spring Boot 拦截器实现鉴权。这个项目的鉴权流程大概是用户登录成功后后端生成一个 JWT token 串返回给前端。前端拿到 token 后存到 localStorage 或者 Vuex 里每次请求时在请求头带上Authorization: Bearer token后端通过拦截器统一解析 header 里的 token验证通过就把用户信息塞到当前线程上下文中业务代码直接取当前登录用户即可。关键代码大致长这样Component public class JwtInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { String token request.getHeader(Authorization); if (token ! null token.startsWith(Bearer )) { token token.substring(7); String username JwtUtil.parseToken(token); if (username ! null) { UserContext.set(username); return true; } } response.setStatus(401); return false; } }然后注册拦截器并在配置里排除掉登录、注册、分享访问等公开接口Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(jwtInterceptor) .addPathPatterns(/api/**) .excludePathPatterns(/api/user/login, /api/user/register, /api/share/view/**); }这套逻辑最核心的价值在于拦截器把鉴权逻辑从业务代码里剥离出来Controller 里不需要每写一个接口都去判断用户是否登录。你只要在需要用户上下文的地方调用 UserContext 获取当前用户 — 代码清爽很多。3.2 文件上传MultipartFile 与存储路径策略文件上传是网盘系统的核心接口实现方式直接决定了系统的可靠性。这个项目的上传接口用的是 Spring MVC 标准的MultipartFile方式PostMapping(/upload) public Result upload(RequestParam(file) MultipartFile file, RequestParam(parentId) Long parentId) { String fileName file.getOriginalFilename(); // 生成存储路径 String dateDir LocalDate.now().toString().replace(-, ); String storagePath /data/disk/ dateDir / UUID.randomUUID().toString().replace(-, ) _ fileName; File dest new File(storagePath); if (!dest.getParentFile().exists()) { dest.getParentFile().mkdirs(); } file.transferTo(dest); // 将文件元数据写入数据库 FileInfo fileInfo new FileInfo(); fileInfo.setUserId(currentUserId()); fileInfo.setFileName(fileName); fileInfo.setFilePath(storagePath); fileInfo.setFileSize(file.getSize()); fileInfo.setIsFolder(0); fileInfo.setParentId(parentId); fileMapper.insert(fileInfo); return Result.success(fileInfo); }这个实现有几个值得学习的细节。存储路径按日期分目录这样每天上传的文件落在一批独立的目录里即便某个时间段的文件出了问题也不影响其他日期的数据。文件名加了 UUID 前缀防止不同用户上传同名文件时互相覆盖实际展示给用户的名字存在数据库的 file_name 字段里物理文件用什么名字都无所谓。如果你拿到的源码没做这些处理直接拿原始文件名存磁盘那就要小心了两个用户各传一个报告.pdf后上传的会把先上传的覆盖掉而且一旦发生连恢复的机会都没有。这是一个非常隐蔽但后果严重的问题。3.3 文件下载的 IO 流处理方式下载接口要处理的是文件流输出。这里有一个常见的性能问题如果一次性把整个文件读进内存再输出遇到几个 G 的大文件JVM 直接 OutOfMemoryError。完整的写法应该是用缓冲流边读边写GetMapping(/download/{fileId}) public void download(PathVariable(fileId) Long fileId, HttpServletResponse response) throws IOException { FileInfo info fileMapper.selectById(fileId); File file new File(info.getFilePath()); response.setContentType(application/octet-stream); String encodedFileName URLEncoder.encode(info.getFileName(), UTF-8); response.setHeader(Content-Disposition, attachment; filename\ encodedFileName \); try (InputStream is new FileInputStream(file); OutputStream os response.getOutputStream()) { byte[] buffer new byte[8192]; int len; while ((len is.read(buffer)) ! -1) { os.write(buffer, 0, len); } } }这段代码的核心就是 8KB 的 byte 数组做缓冲循环读写。8KB 是经验值太小会导致 IO 次数太多性能差太大会占用过多内存。用 8KB 到 64KB 之间的缓冲区间在绝大多数场景下都是合理的。另外注意文件名做了 URLEncoder.encode不然浏览器拿到中文文件名可能乱码。这个小细节如果你在原版代码里找不到建议在重构时自己加上别问问就是坑过。3.4 文件重命名与移动的目录树联动逻辑文件重命名和移动这两个功能的本质都是 UPDATE file_info 表的记录看似简单但涉及到文件夹的时候要小心。重命名接口PutMapping(/rename) public Result rename(RequestParam(fileId) Long fileId, RequestParam(newName) String newName) { FileInfo fileInfo fileMapper.selectById(fileId); if (fileInfo.getIsFolder() 1) { // 文件夹重命名只改数据库记录 fileInfo.setFileName(newName); fileMapper.updateById(fileInfo); } else { // 文件重命名需要同步物理文件名 File oldFile new File(fileInfo.getFilePath()); String newPath oldFile.getParent() File.separator newName; boolean ok oldFile.renameTo(new File(newPath)); if (ok) { fileInfo.setFileName(newName); fileInfo.setFilePath(newPath); fileMapper.updateById(fileInfo); } } return Result.success(); }这里有个容易被忽略的点当重命名对象是文件夹时只更新数据库记录即可不用去动物理目录名。因为物理路径中的目录名通常带有 UUID 前缀与用户可见的文件夹名并没有强关联动了反而导致数据库里所有子文件的 file_path 全部失效。移动文件就更简单了本质就是修改 parent_id 字段PutMapping(/move) public Result move(RequestParam(fileId) Long fileId, RequestParam(targetParentId) Long targetParentId) { FileInfo fileInfo fileMapper.selectById(fileId); fileInfo.setParentId(targetParentId); fileMapper.updateById(fileInfo); return Result.success(); }但移动接口里有一个不能忽略的校验目标目录不能是自身或自身的子目录。不然就会出现文件夹把自己移动到自己里面的逻辑死循环。严谨点的实现要先查目标目录的完整父级链路确保 fileId 不在其中。4. 前端 Vue 的核心实现思路4.1 前端页面结构与路由设计Vue 前端这一块我拿到源码后第一步是看路由配置。这个个人网盘的路由设计大概分四个层面路径页面说明/login登录页公开路由无需鉴权/register注册页公开路由无需鉴权/home网盘主界面需登录展示文件列表/share/:code分享页公开路由通过提取码访问路由守卫是前端鉴权的关键。Vue Router 的全局前置守卫里会判断如果要去/home 这种需要登录的页面检查 localStorage 里有没有 token没有就跳转 /loginrouter.beforeEach((to, from, next) { const token localStorage.getItem(token); if (to.path ! /login to.path ! /register !token) { next(/login); } else { next(); } });4.2 文件列表渲染树形目录的下钻与面包屑主界面的文件列表是整个前端最核心的组件。它的核心逻辑其实是围绕“当前目录 ID”的状态管理。用户点击进入某个文件夹前端把当前目录 ID 传给后端接口/api/file/list?parentIdxxx拿到当前目录下的所有文件和子文件夹后重新渲染列表。为了让路径可回溯前端会维护一个路径栈data() { return { currentParentId: 0, pathStack: [{ id: 0, name: 我的网盘 }] } }, methods: { enterFolder(folder) { this.currentParentId folder.id; this.pathStack.push({ id: folder.id, name: folder.fileName }); this.loadFileList(); }, backToIndex(index) { this.pathStack this.pathStack.slice(0, index 1); this.currentParentId this.pathStack[index].id; this.loadFileList(); } }这个做法很直观注意在返回上一级时把 pathStack 截断保证状态和数据的一致性。4.3 上传组件的优化思路Vue 端的上传组件一般直接用 Element UI 的 el-upload 组件封装。如果你拿到的源码里上传体验比较粗糙比如没有进度条、没有拖拽上传可以自己优化el-upload :actionuploadUrl :headersuploadHeaders :data{ parentId: currentParentId } :on-successhandleUploadSuccess :on-progresshandleProgress multiple drag i classel-icon-upload/i div classel-upload__text将文件拖到此处或em点击上传/em/div /el-upload注意点在于上传成功后的回调里一定要重新加载文件列表否则前端界面不会刷新出新上传的文件。另外如果需要限制文件类型或大小用:before-upload钩子做前置校验前端校验不过就不要发起请求了省流量。4.4 音视频预览的实现如何处理 m3u8这个标题对应的项目实际上网盘系统里做一个视频预览功能很常见而视频预览里最麻烦的格式就是 m3u8。m3u8 本质上是 HLS 协议的视频索引文件浏览器不能直接播放需要专门的播放器解析。Vue 生态里处理 m3u8 播放常见方案是 video.js 配合 videojs-contrib-hls 插件或者用 hls.js 库。在网盘系统里集成 m3u8 播放的核心逻辑是这样import Hls from hls.js; playM3u8(url) { const video this.$refs.videoPlayer; if (Hls.isSupported()) { const hls new Hls(); hls.loadSource(url); hls.attachMedia(video); hls.on(Hls.Events.MANIFEST_PARSED, () { video.play(); }); } else if (video.canPlayType(application/vnd.apple.mpegurl)) { // Safari 原生支持 video.src url; } }这里有个后端配合的问题后端返回 m3u8 视频流接口时响应头不能直接断掉要支持 Range 请求否则视频拖动进度条会失效。Spring Boot 的 Resource 下载方式和自定义 Range 处理的代码在源码里需要重点看一下有没有做这一步。5. 部署与运行全流程5.1 环境准备清单把源码在本地跑起来你需要准备好下面这些东西环境版本建议用途JDK1.8 或 11运行后端Maven3.6构建后端MySQL5.7存储元数据Node.js12构建前端IDEIDEA 或 VSCode开发调试这里特别强调一下 JDK 版本。如果你拿到的源码是基于 Spring Boot 2.x 的JDK 8 完全没问题如果源码用了 Spring Boot 3.x那必须 JDK 17 以上。版本不匹配的典型报错是UnsupportedClassVersionError看到这个错误先检查 JDK 版本。5.2 数据库初始化步骤第一步创建数据库。打开 MySQL 命令行或者使用 Navicat 执行CREATE DATABASE IF NOT EXISTS disk DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; USE disk; SOURCE /你的目录/disk.sql;第二步修改后端配置文件。找到src/main/resources/application.ymlspring: datasource: url: jdbc:mysql://localhost:3306/disk?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver配置完数据源后端启动前最好先确认一下数据库连接工具的驱动兼容性有些老的源码还在用com.mysql.jdbc.Driver换成 MySQL 8.x 驱动时这个类名已经废弃了要改成com.mysql.cj.jdbc.Driver。5.3 后端启动与常见异常在 IDEA 里打开后端项目等待 Maven 依赖下载完毕然后直接运行主类。如果一切正常控制台会看到 Spring Boot 的启动日志端口默认 8080。启动过程中最常见的两个问题端口被占用。Port 8080 was already in use这种报错很好解决。Windows 命令查占用进程netstat -ano | findstr 8080 taskkill /PID 具体PID /FMapper 扫描不到。如果启动时报Invalid bound statement (not found)那是 MyBatis 的 Mapper 接口和 XML 文件没有对应上。检查 Mapper 接口是否加了Mapper注解或者启动类上有没有MapperScan(com.example.mapper)。5.4 前端启动与代理配置前端项目打开后先安装依赖npm install如果因为网络原因安装太慢换成淘宝镜像源npm config set registry https://registry.npmmirror.com然后启动开发服务器npm run serve前端默认端口一般是 8081 或 3000要访问后端 8080必须配置代理否则跨域问题会让你怀疑人生。开发环境在vue.config.js里加module.exports { devServer: { port: 8081, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } };这个代理的作用是浏览器请求/api/xxx时Vue 开发服务器会把这个请求转发给后端的 8080 端口从而绕开浏览器的同源策略限制。5.5 生产环境部署组合拳开发环境跑通之后如果要把这套系统部署到服务器上推荐的组合是Spring Boot 后端 jar 包 Nginx 托管前端静态文件 Nginx 反向代理 API 请求。后端打包mvn clean package -DskipTests打完包在target/目录下有个xxx.jar上传到服务器后运行nohup java -jar disk.jar --spring.profiles.activeprod disk.log 21 前端打包npm run build打包产物在dist/目录把它整个上传到服务器的 Nginx HTML 目录。Nginx 配置核心部分server { listen 80; server_name your-domain.com; root /usr/share/nginx/html/dist; index index.html; location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location / { try_files $uri $uri/ /index.html; } }try_files这行很关键它解决的是前端路由刷新 404 的问题。Vue Router 如果用的是 history 模式直接刷新/home页面时 Nginx 找不到对应文件会被 404加上这行配置后刷新时会把请求回退到 index.html由前端路由接管页面就正常了。6. 常见问题与排查技巧实录6.1 上传大文件报 OutOfMemoryError这是个人网盘项目最容易踩的坑。Spring Boot 默认的spring.servlet.multipart.max-file-size是 1MBmax-request-size是 10MB。超过这个限制上传请求直接失败。就算你调大了限制上传一个大文件时如果直接file.getBytes()读取JVM 内存也会被瞬间打爆。解决方案分两层第一层调大配置只适合中文件场景spring: servlet: multipart: max-file-size: 1024MB max-request-size: 1024MB第二层再大就得上分片上传。把前端文件按 5MB 或 10MB 切成小片一片一片上传后端每片落一个临时文件全部传完后合并。这个方案在源码里不一定有但如果你确实要存超过 4GB 的文件分片几乎是唯一选择。6.2 中文文件名乱码问题上传一个毕业论文终版.pdf下载下来变成_____终版.pdf或者干脆乱码这个问题来源通常是两个一是后端存储时编码不对。Spring Boot 的server.tomcat.uri-encoding默认是 UTF-8但如果你在 Windows 环境用application.yml没显式配置部分老项目里会有问题。建议加上server: tomcat: uri-encoding: UTF-8二是下载响应头的编码处理。前面已经提到下载时用URLEncoder.encode(fileName, UTF-8)处理文件名前端拿到后浏览器会自动解码不会乱码。6.3 分享链接访问 404如果点击分享链接后页面打不开优先排查两点。第一检查分享接口是不是被 JWT 拦截器拦了。很多源码的拦截器会把所有/api/**都拦掉如果分享接口路径没有加白名单前端拿到分享链接但后端直接返回 401。处理方式就是回到 3.1 节那种拦截器配置把公开展示类接口加到excludePathPatterns里。第二检查提取码的拼写。有些前端在生成分享链接时把分享 ID 和提取码拼错了导致分享页拿到错误的 code 去请求后端自然查不到数据。这个看浏览器 Network 面板直接看请求参数就行。6.4 前端页面白屏Vue 项目白屏有两种常见原因第一种是路由模式问题。开发环境下一切正常部署到服务器后刷新页面白屏这大概率是 Nginx 没配try_files导致刷新时找不到路由对应的文件。按 5.5 节的配置加上那一行就解决了。第二种是资源路径问题。打包后的静态资源如果是绝对路径/js/app.js部署在子目录下就会 404。解决方法是修改vue.config.jsmodule.exports { publicPath: ./ };改成相对路径后资源就能适配任何部署目录。6.5 数据初始化提示表不存在有同学拿到源码先导入了 .sql 文件但启动时报Table disk.file_info doesnt exist。大概率是导错了库。有些 .sql 文件里没有USE database_name;语句你在 MySQL 里直接执行时会导到默认的数据库里跑完发现目标库里啥都没有。排查方法很直接USE disk; SHOW TABLES;如果显示是空的重新导入一次导入前先确认在正确的数据库上下文里mysql -u root -p disk disk.sql7. 项目优化的进阶方向源码能跑通只是第一步。如果你想拿这个项目做毕业设计、面试项目或者真的长期自用有几个优化方向值得投入时间。文件秒传与断点续传基于文件内容的 MD5 判断文件是否已存在如果存在就不重复上传物理文件直接建立记录关联。这能极大提升用户体验。断点续传则需要前端记录上传位置后端提供合并接口技术上比秒传复杂一些但思路并不难。接入对象存储本地磁盘存储毕竟是单机方案文件量大了之后磁盘空间、备份、数据安全都是问题。把存储层抽象出来接阿里云 OSS、腾讯云 COS 或者搭建 MinIO是最接近生产环境的改造方向。核心原理就是上传接口不再把文件写本地磁盘而是调用云存储 SDK 上传并把返回的 URL 存到数据库。操作日志与审计加上用户操作日志表记录上传、下载、删除、分享等关键行为。对个人使用来说这个功能可以帮你追溯“这个文件什么时候被我删了”这类问题对面试项目来说这是展示你没学过“生产意识”的加分项。文件类型图标与预览能力扩展前端根据 file_type 字段渲染对应的文件图标图片图标、文档图标、视频图标同时接入 more 类型的预览。图片直接通过 blob 流显示PDF 可以直接用浏览器内置的 PDF 查看器Word 文档可以用 docx-preview 库渲染。这些改进会让项目的完成度明显提升。8. 最后的实操建议这套基于 Java Vue 的个人网盘系统整体属于典型的前后端分离教学项目代码结构清晰数据库设计规整拿来学习和二次开发都很合适。我个人的建议是不要只满足于把源码跑起来拿着项目去交差。把它当成一个练手对象从改一个小功能开始比如加一个“最近上传”的排序选项或者把上传改成拖拽分区慢慢你就会对整个系统的耦合关系有感觉。我自己见过太多人对着源码不知道从哪下手。我的习惯是先看数据库表再看后端的 Controller 列表然后挑一个最小闭环比如文件重命名捋一遍从前端点击到后端落库的完整链路。走通一个闭环之后整个项目的脉络基本就在你脑子里了接下来想加什么功能都顺理成章。在实际操作过程中我还想多提醒一句不要上来就对着源码改个不停。先原封不动跑通确认环境没问题再开始动手。否则你会分不清是环境问题还是代码问题排查起来特别痛苦。把这套系统搭起来、吃透、再按自己的需求改造一遍这个过程比较费时间但对 Java Web 全栈的能力提升是实打实的。希望这篇拆解能让你少走些弯路。 Java+Vue个人网盘系统全解析：从数据库设计到部署实战
不用多说能把这套东西跑起来的人多半已经在“自己存东西”这件事上被各种网盘折磨过。限速、和谐、会员到期空间不够随便一条就够让人头疼。自己搭一个个人网盘管理系统不只是为了“有个地方放文件”更核心的价值在于数据完全在自己手里目录结构自己说了算想怎么分类就怎么分类想要什么功能自己加。这篇博文就围绕一个基于 Java Vue 的个人网盘管理系统来拆包含源码结构、数据库设计、前后端实现思路、部署落地、踩坑记录全流程走一遍。标题里虽然写了“源码数据库文档”但光有这三样不会用等于白拿真正要搞懂的是它背后的设计逻辑和运行机制。我默认你是有一定 Java 基础的开发者至少熟悉 Spring Boot 的基本用法懂一点 Vue 的项目结构。如果你是刚学完 SSM 或 Spring Boot 的学生这篇也能让你搞明白一个完整项目到底是怎么串起来的。1. 项目整体设计与技术选型1.1 为什么是 Java Vue而不是其他方案个人网盘这种系统本质上就是“文件管理 用户系统 分享功能”的组合。市面上的实现方案五花八门有 Python 的 FastAPI 方案有 Node.js 的 NextCloud 二次开发甚至有人直接拿 PHP 的 h5ai 凑合。但 Java Vue 这个组合能成为大多数教学项目和企业内部工具的首选原因很实在Java 生态对文件处理的支持非常成熟。Spring Boot 封装了文件上传下载的标准流程MultipartFile 接口配合 CommonsMultipartResolver 或者标准 Servlet 容器就能处理绝大多数场景如果你要接 OSS、S3 或者 FastDFSJava 的 SDK 也是最全的。Vue 的组件化开发适合做这种工具型前端。文件列表、上传进度条、文件夹树、分享弹窗这些都是天然独立的组件切分清楚后代码维护成本很低。部署环境友好。一台 2G 内存的小服务器就能跑起来后端打成 jar 包前端 build 完丢到 Nginx 里单体架构搞定一个个人网盘绰绰有余。这个项目采用典型的单体应用架构Spring Boot 做后端 APIVue 做前端页面MySQL 存元数据文件本体存储在服务器磁盘目录中。没有引入消息队列也没有上微服务对个人网盘这种量级的项目来说那些东西纯粹是给自己找麻烦。1.2 项目模块划分我在梳理这套源码的时候习惯先把项目结构在脑子里画一张图再去看代码就快很多。这个个人网盘系统的后端结构大致是这样src/main/java/com/example/disk/ ├── config/ // 配置类跨域、拦截器、WebMVC ├── controller/ // 接口层文件、用户、分享、回收站 ├── service/ // 业务逻辑层 ├── mapper/ // MyBatis 数据访问层 ├── entity/ // 实体类对应数据库表 ├── common/ // 通用返回结果、异常处理 └── util/ // 工具类MD5、JWT、文件名处理等前端结构上Vue 项目走的是标准 Vue CLI 工程路径src/ ├── api/ // 接口请求封装 ├── assets/ // 静态资源 ├── components/ // 通用组件上传组件、文件列表组件 ├── router/ // 路由配置 ├── store/ // Vuex 状态管理 └── views/ // 页面我的网盘、分享页面、登录注册这套结构没什么高深的但它很标准。标准的价值在于出了问题你知道去哪里找。Controller 出问题就看接口层数据不对就看 Mapper 的 SQL页面交互不对就看对应 view 组件排查效率高很多。1.3 核心功能清单从源码里可以提炼出这个系统完整的功能矩阵也是我做技术拆解的主线功能模块核心能力技术要点用户系统注册、登录、JWT 鉴权Spring Security JWT文件管理上传、下载、删除、重命名、移动MultipartFile、文件流目录管理新建文件夹、目录树展示、路径追踪parent_id 层级结构文件预览图片/视频/文档在线预览前端 blob 流、对象 URL分享功能生成分享链接、提取码、过期时间短码生成、定时清理回收站软删除、恢复、彻底删除is_delete 字段标记搜索功能按文件名模糊搜索MySQL LIKE 查询每个功能单独拉出来都不难但合在一起要考虑的细节就多了。比如重名文件的命名策略、文件夹递归删除的实现、分享码的唯一性保证、大文件上传时内存溢出的规避——这些才是项目里真正值钱的地方。2. 数据库设计与核心表结构2.1 表结构设计思路个人网盘的数据库设计核心就三张表用户表、文件信息表、分享表。别看业务功能不少只要文件信息表设计得足够灵活其他表都是围绕它转的。先看用户表这个最常规CREATE TABLE user ( id int(11) NOT NULL AUTO_INCREMENT, username varchar(64) NOT NULL UNIQUE, password varchar(128) NOT NULL, salt varchar(32) DEFAULT NULL, email varchar(128) DEFAULT NULL, register_time datetime DEFAULT CURRENT_TIMESTAMP, status tinyint(4) DEFAULT 1, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;密码字段必须存密文这里用了 salt 哈希的方式。有人可能会问为什么不直接用 BCrypt 或 MD5这取决于源码的原始实现。如果项目用的是 MD5 Salt 方式也够用只要不存明文就行。但要是我自己重构这个项目我会换成 BCrypt因为 Java 的 jBCrypt 库用起来也不复杂而且抗彩虹表能力更强。文件表是整个系统的灵魂CREATE TABLE file_info ( id bigint(20) NOT NULL AUTO_INCREMENT, user_id int(11) NOT NULL COMMENT 所属用户, file_name varchar(255) NOT NULL COMMENT 文件名, file_path varchar(512) DEFAULT NULL COMMENT 存储路径相对路径, file_size bigint(20) DEFAULT 0 COMMENT 文件大小字节, file_type varchar(50) DEFAULT NULL COMMENT 文件类型, is_folder tinyint(1) DEFAULT 0 COMMENT 是否文件夹, parent_id bigint(20) DEFAULT 0 COMMENT 父目录ID0为根目录, is_delete tinyint(1) DEFAULT 0 COMMENT 是否删除回收站, create_time datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_user_parent (user_id, parent_id), KEY idx_parent_delete (parent_id, is_delete) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这里最关键的设计是parent_id 自关联。文件夹和文件放在同一张表里通过 parent_id 指向父文件夹的 id根目录的 parent_id 为 0。这种设计的好处是统一的表结构简化了查询逻辑新增文件和新增文件夹走同一个接口前端渲染目录树也只需根据 parent_id 递归组装即可。把权限字段放一边单看这个表的索引设计就能发现作者是有意识的idx_user_parent保证了“当前用户的某目录下有哪些文件”这种高频查询走联合索引idx_parent_delete则对应回收站场景中“某目录下的非删除文件列表”的查询。这在数据量不大的时候感觉不到差别但表里堆到几十万行的时候有没有这两个索引就是天壤之别。2.2 分享表和回收站的实现细节分享表的设计也值得一提CREATE TABLE share_info ( id int(11) NOT NULL AUTO_INCREMENT, user_id int(11) NOT NULL, file_id bigint(20) NOT NULL, share_code varchar(16) NOT NULL COMMENT 提取码, share_url varchar(255) DEFAULT NULL COMMENT 分享链接, expire_time datetime DEFAULT NULL COMMENT 过期时间, visit_count int(11) DEFAULT 0 COMMENT 访问次数, create_time datetime DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY uk_share_code (share_code) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;share_code 这个字段有唯一约束这是为了避免多个分享链接撞码。生成提取码的地方一般会用随机字符串比如 UUID 截取前 6 位或者自己写一个短码生成器。为了确保唯一性插入前先查一下再决定是否重新生成或者直接靠数据库的唯一索引兜底插入失败就重试这是常见的两种思路。回收站的实现不走单独建表而是用 file_info 里的is_delete字段做软删除。好处很明显恢复文件时只需要把 is_delete 改回 0目录结构就自动还原了不需要折腾数据迁移。代价是每次正常的文件列表查询都要带is_delete 0条件这是一点性能上的小牺牲但换来的业务逻辑简便性完全值得。2.3 源码里的 SQL 脚本能直接用吗大多数这类项目的源码包里都会带一个.sql文件这个项目的初始化脚本同样如此。导入数据库的时候有几点要注意第一MySQL 的版本差异。现在很多项目已经写了utf8mb4和InnoDB如果你本地还是 MySQL 5.5 或更早的版本DATETIME DEFAULT CURRENT_TIMESTAMP这种语法可能直接报错需要调整成 TIMESTAMP 类型或者去掉默认值。第二数据库连接配置要改。Spring Boot 的application.yml里通常默认写的是 root / 123456连的库名是 disk 之类。如果你本地的密码不同启动后端之前先改掉不然报连接失败的错误会让你误以为是代码问题。第三注意时区参数。serverTimezoneAsia/Shanghai这个参数不加上高版本的 MySQL 驱动在连接时会因为时区问题抛异常。这是非常经典的坑我第一次跑类似项目的时候这个报错卡了我一个多小时。3. 后端核心功能实现解析3.1 登录鉴权JWT 的完整接入方式现在的 Java 项目Spring Security 全家桶 JWT 基本是标配。不过很多源码项目为了降低复杂度会直接引入一个叫做jwt的工具类配合 Spring Boot 拦截器实现鉴权。这个项目的鉴权流程大概是用户登录成功后后端生成一个 JWT token 串返回给前端。前端拿到 token 后存到 localStorage 或者 Vuex 里每次请求时在请求头带上Authorization: Bearer token后端通过拦截器统一解析 header 里的 token验证通过就把用户信息塞到当前线程上下文中业务代码直接取当前登录用户即可。关键代码大致长这样Component public class JwtInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { String token request.getHeader(Authorization); if (token ! null token.startsWith(Bearer )) { token token.substring(7); String username JwtUtil.parseToken(token); if (username ! null) { UserContext.set(username); return true; } } response.setStatus(401); return false; } }然后注册拦截器并在配置里排除掉登录、注册、分享访问等公开接口Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(jwtInterceptor) .addPathPatterns(/api/**) .excludePathPatterns(/api/user/login, /api/user/register, /api/share/view/**); }这套逻辑最核心的价值在于拦截器把鉴权逻辑从业务代码里剥离出来Controller 里不需要每写一个接口都去判断用户是否登录。你只要在需要用户上下文的地方调用 UserContext 获取当前用户 — 代码清爽很多。3.2 文件上传MultipartFile 与存储路径策略文件上传是网盘系统的核心接口实现方式直接决定了系统的可靠性。这个项目的上传接口用的是 Spring MVC 标准的MultipartFile方式PostMapping(/upload) public Result upload(RequestParam(file) MultipartFile file, RequestParam(parentId) Long parentId) { String fileName file.getOriginalFilename(); // 生成存储路径 String dateDir LocalDate.now().toString().replace(-, ); String storagePath /data/disk/ dateDir / UUID.randomUUID().toString().replace(-, ) _ fileName; File dest new File(storagePath); if (!dest.getParentFile().exists()) { dest.getParentFile().mkdirs(); } file.transferTo(dest); // 将文件元数据写入数据库 FileInfo fileInfo new FileInfo(); fileInfo.setUserId(currentUserId()); fileInfo.setFileName(fileName); fileInfo.setFilePath(storagePath); fileInfo.setFileSize(file.getSize()); fileInfo.setIsFolder(0); fileInfo.setParentId(parentId); fileMapper.insert(fileInfo); return Result.success(fileInfo); }这个实现有几个值得学习的细节。存储路径按日期分目录这样每天上传的文件落在一批独立的目录里即便某个时间段的文件出了问题也不影响其他日期的数据。文件名加了 UUID 前缀防止不同用户上传同名文件时互相覆盖实际展示给用户的名字存在数据库的 file_name 字段里物理文件用什么名字都无所谓。如果你拿到的源码没做这些处理直接拿原始文件名存磁盘那就要小心了两个用户各传一个报告.pdf后上传的会把先上传的覆盖掉而且一旦发生连恢复的机会都没有。这是一个非常隐蔽但后果严重的问题。3.3 文件下载的 IO 流处理方式下载接口要处理的是文件流输出。这里有一个常见的性能问题如果一次性把整个文件读进内存再输出遇到几个 G 的大文件JVM 直接 OutOfMemoryError。完整的写法应该是用缓冲流边读边写GetMapping(/download/{fileId}) public void download(PathVariable(fileId) Long fileId, HttpServletResponse response) throws IOException { FileInfo info fileMapper.selectById(fileId); File file new File(info.getFilePath()); response.setContentType(application/octet-stream); String encodedFileName URLEncoder.encode(info.getFileName(), UTF-8); response.setHeader(Content-Disposition, attachment; filename\ encodedFileName \); try (InputStream is new FileInputStream(file); OutputStream os response.getOutputStream()) { byte[] buffer new byte[8192]; int len; while ((len is.read(buffer)) ! -1) { os.write(buffer, 0, len); } } }这段代码的核心就是 8KB 的 byte 数组做缓冲循环读写。8KB 是经验值太小会导致 IO 次数太多性能差太大会占用过多内存。用 8KB 到 64KB 之间的缓冲区间在绝大多数场景下都是合理的。另外注意文件名做了 URLEncoder.encode不然浏览器拿到中文文件名可能乱码。这个小细节如果你在原版代码里找不到建议在重构时自己加上别问问就是坑过。3.4 文件重命名与移动的目录树联动逻辑文件重命名和移动这两个功能的本质都是 UPDATE file_info 表的记录看似简单但涉及到文件夹的时候要小心。重命名接口PutMapping(/rename) public Result rename(RequestParam(fileId) Long fileId, RequestParam(newName) String newName) { FileInfo fileInfo fileMapper.selectById(fileId); if (fileInfo.getIsFolder() 1) { // 文件夹重命名只改数据库记录 fileInfo.setFileName(newName); fileMapper.updateById(fileInfo); } else { // 文件重命名需要同步物理文件名 File oldFile new File(fileInfo.getFilePath()); String newPath oldFile.getParent() File.separator newName; boolean ok oldFile.renameTo(new File(newPath)); if (ok) { fileInfo.setFileName(newName); fileInfo.setFilePath(newPath); fileMapper.updateById(fileInfo); } } return Result.success(); }这里有个容易被忽略的点当重命名对象是文件夹时只更新数据库记录即可不用去动物理目录名。因为物理路径中的目录名通常带有 UUID 前缀与用户可见的文件夹名并没有强关联动了反而导致数据库里所有子文件的 file_path 全部失效。移动文件就更简单了本质就是修改 parent_id 字段PutMapping(/move) public Result move(RequestParam(fileId) Long fileId, RequestParam(targetParentId) Long targetParentId) { FileInfo fileInfo fileMapper.selectById(fileId); fileInfo.setParentId(targetParentId); fileMapper.updateById(fileInfo); return Result.success(); }但移动接口里有一个不能忽略的校验目标目录不能是自身或自身的子目录。不然就会出现文件夹把自己移动到自己里面的逻辑死循环。严谨点的实现要先查目标目录的完整父级链路确保 fileId 不在其中。4. 前端 Vue 的核心实现思路4.1 前端页面结构与路由设计Vue 前端这一块我拿到源码后第一步是看路由配置。这个个人网盘的路由设计大概分四个层面路径页面说明/login登录页公开路由无需鉴权/register注册页公开路由无需鉴权/home网盘主界面需登录展示文件列表/share/:code分享页公开路由通过提取码访问路由守卫是前端鉴权的关键。Vue Router 的全局前置守卫里会判断如果要去/home 这种需要登录的页面检查 localStorage 里有没有 token没有就跳转 /loginrouter.beforeEach((to, from, next) { const token localStorage.getItem(token); if (to.path ! /login to.path ! /register !token) { next(/login); } else { next(); } });4.2 文件列表渲染树形目录的下钻与面包屑主界面的文件列表是整个前端最核心的组件。它的核心逻辑其实是围绕“当前目录 ID”的状态管理。用户点击进入某个文件夹前端把当前目录 ID 传给后端接口/api/file/list?parentIdxxx拿到当前目录下的所有文件和子文件夹后重新渲染列表。为了让路径可回溯前端会维护一个路径栈data() { return { currentParentId: 0, pathStack: [{ id: 0, name: 我的网盘 }] } }, methods: { enterFolder(folder) { this.currentParentId folder.id; this.pathStack.push({ id: folder.id, name: folder.fileName }); this.loadFileList(); }, backToIndex(index) { this.pathStack this.pathStack.slice(0, index 1); this.currentParentId this.pathStack[index].id; this.loadFileList(); } }这个做法很直观注意在返回上一级时把 pathStack 截断保证状态和数据的一致性。4.3 上传组件的优化思路Vue 端的上传组件一般直接用 Element UI 的 el-upload 组件封装。如果你拿到的源码里上传体验比较粗糙比如没有进度条、没有拖拽上传可以自己优化el-upload :actionuploadUrl :headersuploadHeaders :data{ parentId: currentParentId } :on-successhandleUploadSuccess :on-progresshandleProgress multiple drag i classel-icon-upload/i div classel-upload__text将文件拖到此处或em点击上传/em/div /el-upload注意点在于上传成功后的回调里一定要重新加载文件列表否则前端界面不会刷新出新上传的文件。另外如果需要限制文件类型或大小用:before-upload钩子做前置校验前端校验不过就不要发起请求了省流量。4.4 音视频预览的实现如何处理 m3u8这个标题对应的项目实际上网盘系统里做一个视频预览功能很常见而视频预览里最麻烦的格式就是 m3u8。m3u8 本质上是 HLS 协议的视频索引文件浏览器不能直接播放需要专门的播放器解析。Vue 生态里处理 m3u8 播放常见方案是 video.js 配合 videojs-contrib-hls 插件或者用 hls.js 库。在网盘系统里集成 m3u8 播放的核心逻辑是这样import Hls from hls.js; playM3u8(url) { const video this.$refs.videoPlayer; if (Hls.isSupported()) { const hls new Hls(); hls.loadSource(url); hls.attachMedia(video); hls.on(Hls.Events.MANIFEST_PARSED, () { video.play(); }); } else if (video.canPlayType(application/vnd.apple.mpegurl)) { // Safari 原生支持 video.src url; } }这里有个后端配合的问题后端返回 m3u8 视频流接口时响应头不能直接断掉要支持 Range 请求否则视频拖动进度条会失效。Spring Boot 的 Resource 下载方式和自定义 Range 处理的代码在源码里需要重点看一下有没有做这一步。5. 部署与运行全流程5.1 环境准备清单把源码在本地跑起来你需要准备好下面这些东西环境版本建议用途JDK1.8 或 11运行后端Maven3.6构建后端MySQL5.7存储元数据Node.js12构建前端IDEIDEA 或 VSCode开发调试这里特别强调一下 JDK 版本。如果你拿到的源码是基于 Spring Boot 2.x 的JDK 8 完全没问题如果源码用了 Spring Boot 3.x那必须 JDK 17 以上。版本不匹配的典型报错是UnsupportedClassVersionError看到这个错误先检查 JDK 版本。5.2 数据库初始化步骤第一步创建数据库。打开 MySQL 命令行或者使用 Navicat 执行CREATE DATABASE IF NOT EXISTS disk DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; USE disk; SOURCE /你的目录/disk.sql;第二步修改后端配置文件。找到src/main/resources/application.ymlspring: datasource: url: jdbc:mysql://localhost:3306/disk?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver配置完数据源后端启动前最好先确认一下数据库连接工具的驱动兼容性有些老的源码还在用com.mysql.jdbc.Driver换成 MySQL 8.x 驱动时这个类名已经废弃了要改成com.mysql.cj.jdbc.Driver。5.3 后端启动与常见异常在 IDEA 里打开后端项目等待 Maven 依赖下载完毕然后直接运行主类。如果一切正常控制台会看到 Spring Boot 的启动日志端口默认 8080。启动过程中最常见的两个问题端口被占用。Port 8080 was already in use这种报错很好解决。Windows 命令查占用进程netstat -ano | findstr 8080 taskkill /PID 具体PID /FMapper 扫描不到。如果启动时报Invalid bound statement (not found)那是 MyBatis 的 Mapper 接口和 XML 文件没有对应上。检查 Mapper 接口是否加了Mapper注解或者启动类上有没有MapperScan(com.example.mapper)。5.4 前端启动与代理配置前端项目打开后先安装依赖npm install如果因为网络原因安装太慢换成淘宝镜像源npm config set registry https://registry.npmmirror.com然后启动开发服务器npm run serve前端默认端口一般是 8081 或 3000要访问后端 8080必须配置代理否则跨域问题会让你怀疑人生。开发环境在vue.config.js里加module.exports { devServer: { port: 8081, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } };这个代理的作用是浏览器请求/api/xxx时Vue 开发服务器会把这个请求转发给后端的 8080 端口从而绕开浏览器的同源策略限制。5.5 生产环境部署组合拳开发环境跑通之后如果要把这套系统部署到服务器上推荐的组合是Spring Boot 后端 jar 包 Nginx 托管前端静态文件 Nginx 反向代理 API 请求。后端打包mvn clean package -DskipTests打完包在target/目录下有个xxx.jar上传到服务器后运行nohup java -jar disk.jar --spring.profiles.activeprod disk.log 21 前端打包npm run build打包产物在dist/目录把它整个上传到服务器的 Nginx HTML 目录。Nginx 配置核心部分server { listen 80; server_name your-domain.com; root /usr/share/nginx/html/dist; index index.html; location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location / { try_files $uri $uri/ /index.html; } }try_files这行很关键它解决的是前端路由刷新 404 的问题。Vue Router 如果用的是 history 模式直接刷新/home页面时 Nginx 找不到对应文件会被 404加上这行配置后刷新时会把请求回退到 index.html由前端路由接管页面就正常了。6. 常见问题与排查技巧实录6.1 上传大文件报 OutOfMemoryError这是个人网盘项目最容易踩的坑。Spring Boot 默认的spring.servlet.multipart.max-file-size是 1MBmax-request-size是 10MB。超过这个限制上传请求直接失败。就算你调大了限制上传一个大文件时如果直接file.getBytes()读取JVM 内存也会被瞬间打爆。解决方案分两层第一层调大配置只适合中文件场景spring: servlet: multipart: max-file-size: 1024MB max-request-size: 1024MB第二层再大就得上分片上传。把前端文件按 5MB 或 10MB 切成小片一片一片上传后端每片落一个临时文件全部传完后合并。这个方案在源码里不一定有但如果你确实要存超过 4GB 的文件分片几乎是唯一选择。6.2 中文文件名乱码问题上传一个毕业论文终版.pdf下载下来变成_____终版.pdf或者干脆乱码这个问题来源通常是两个一是后端存储时编码不对。Spring Boot 的server.tomcat.uri-encoding默认是 UTF-8但如果你在 Windows 环境用application.yml没显式配置部分老项目里会有问题。建议加上server: tomcat: uri-encoding: UTF-8二是下载响应头的编码处理。前面已经提到下载时用URLEncoder.encode(fileName, UTF-8)处理文件名前端拿到后浏览器会自动解码不会乱码。6.3 分享链接访问 404如果点击分享链接后页面打不开优先排查两点。第一检查分享接口是不是被 JWT 拦截器拦了。很多源码的拦截器会把所有/api/**都拦掉如果分享接口路径没有加白名单前端拿到分享链接但后端直接返回 401。处理方式就是回到 3.1 节那种拦截器配置把公开展示类接口加到excludePathPatterns里。第二检查提取码的拼写。有些前端在生成分享链接时把分享 ID 和提取码拼错了导致分享页拿到错误的 code 去请求后端自然查不到数据。这个看浏览器 Network 面板直接看请求参数就行。6.4 前端页面白屏Vue 项目白屏有两种常见原因第一种是路由模式问题。开发环境下一切正常部署到服务器后刷新页面白屏这大概率是 Nginx 没配try_files导致刷新时找不到路由对应的文件。按 5.5 节的配置加上那一行就解决了。第二种是资源路径问题。打包后的静态资源如果是绝对路径/js/app.js部署在子目录下就会 404。解决方法是修改vue.config.jsmodule.exports { publicPath: ./ };改成相对路径后资源就能适配任何部署目录。6.5 数据初始化提示表不存在有同学拿到源码先导入了 .sql 文件但启动时报Table disk.file_info doesnt exist。大概率是导错了库。有些 .sql 文件里没有USE database_name;语句你在 MySQL 里直接执行时会导到默认的数据库里跑完发现目标库里啥都没有。排查方法很直接USE disk; SHOW TABLES;如果显示是空的重新导入一次导入前先确认在正确的数据库上下文里mysql -u root -p disk disk.sql7. 项目优化的进阶方向源码能跑通只是第一步。如果你想拿这个项目做毕业设计、面试项目或者真的长期自用有几个优化方向值得投入时间。文件秒传与断点续传基于文件内容的 MD5 判断文件是否已存在如果存在就不重复上传物理文件直接建立记录关联。这能极大提升用户体验。断点续传则需要前端记录上传位置后端提供合并接口技术上比秒传复杂一些但思路并不难。接入对象存储本地磁盘存储毕竟是单机方案文件量大了之后磁盘空间、备份、数据安全都是问题。把存储层抽象出来接阿里云 OSS、腾讯云 COS 或者搭建 MinIO是最接近生产环境的改造方向。核心原理就是上传接口不再把文件写本地磁盘而是调用云存储 SDK 上传并把返回的 URL 存到数据库。操作日志与审计加上用户操作日志表记录上传、下载、删除、分享等关键行为。对个人使用来说这个功能可以帮你追溯“这个文件什么时候被我删了”这类问题对面试项目来说这是展示你没学过“生产意识”的加分项。文件类型图标与预览能力扩展前端根据 file_type 字段渲染对应的文件图标图片图标、文档图标、视频图标同时接入 more 类型的预览。图片直接通过 blob 流显示PDF 可以直接用浏览器内置的 PDF 查看器Word 文档可以用 docx-preview 库渲染。这些改进会让项目的完成度明显提升。8. 最后的实操建议这套基于 Java Vue 的个人网盘系统整体属于典型的前后端分离教学项目代码结构清晰数据库设计规整拿来学习和二次开发都很合适。我个人的建议是不要只满足于把源码跑起来拿着项目去交差。把它当成一个练手对象从改一个小功能开始比如加一个“最近上传”的排序选项或者把上传改成拖拽分区慢慢你就会对整个系统的耦合关系有感觉。我自己见过太多人对着源码不知道从哪下手。我的习惯是先看数据库表再看后端的 Controller 列表然后挑一个最小闭环比如文件重命名捋一遍从前端点击到后端落库的完整链路。走通一个闭环之后整个项目的脉络基本就在你脑子里了接下来想加什么功能都顺理成章。在实际操作过程中我还想多提醒一句不要上来就对着源码改个不停。先原封不动跑通确认环境没问题再开始动手。否则你会分不清是环境问题还是代码问题排查起来特别痛苦。把这套系统搭起来、吃透、再按自己的需求改造一遍这个过程比较费时间但对 Java Web 全栈的能力提升是实打实的。希望这篇拆解能让你少走些弯路。