简介本资源是一套面向计算机专业本科生的毕业设计实战项目聚焦基于SpringBoot的在线文档管理系统开发解决企业与个人在知识沉淀、文档协同与安全管控中的典型需求。资源包共389个文件涵盖82个核心Java后端代码、36个Vue前端组件、161个SVG图标资源、19张JPG界面截图及11个XML配置文件等完整呈现前后端分离架构其中bat脚本支持一键安装/运行yml与SQL文件提供环境配置与数据库初始化支持整体压缩包大小为31.36MB。项目包含清晰分层架构Controller-Service-Repository、JPA数据持久化、Thymeleaf/Vue双前端适配方案、权限控制与SSL传输安全设计并附带开题报告、演示PPT及详细部署说明文档。目前已有18人学习下载适合需要落地SpringBoot全栈开发、理解文档类系统业务逻辑与工程规范的中级开发者参考实践。1. 在线文档管理系统我到底要做哪些功能之前帮一个团队做内部资料库发现大家的文件散落在微信聊天记录、个人网盘、移动硬盘和共享目录里找一份合同原型有时候要问遍全组。后来接触到“基于SpringBoot的在线文档管理系统”这类题目我索性把之前的经验全部重来了一遍从功能拆解到代码落地做出一版可以直接复现的系统。这篇文章不打算写成从0开始的SpringBoot教程而是聚焦“文档管理系统在真实场景下到底该怎么落地”。1.1 从毕业设计命题到一个能跑起来的系统这个题目看起来套路其实是“管理系统”里最值得深挖的一类。因为文档管理系统的核心不是CRUD而是文件、权限、检索、预览这一整条链路。如果只是把一张表做成增删改查那和通讯录管理没有区别既然要称为“在线文档管理系统设计与实现”至少要回答四个问题文件存哪、怎么授权、如何预览、如何搜索。我最终定的目标是做一个面向中小团队的轻量级系统用户注册登录、文档目录树、文档上传下载、PDF/图片/Office在线预览、全文检索、操作日志、回收站再叠加角色权限控制。技术上使用SpringBoot MyBatis-Plus MySQL Redis Vue前端用Vue 2 ElementUI部署用jar包方式放到Linux服务器。这个方案对毕业设计和原型验证都比较稳妥很多团队内部实际使用的工具也是这个量级。1.2 功能模块清单从用户视角倒推功能设计我习惯先从使用者的视角倒推不要一上来就画架构图。管理员希望知道谁在什么时候下载了哪个文件普通员工希望上传后立刻能预览不用下载到本地部门负责人希望只能看到自己部门范围内的文档运维则希望上传大文件时服务器不会挂掉。最终的模块划分是这样的模块核心功能技术落点用户与角色注册、登录、权限分配JWT RBAC目录管理多级目录树、目录共享自关联表 内存组装文档管理上传、下载、重命名、移动、删除文件流 文档元数据表预览模块PDF、图片、Office文档预览pdf.js、LibreOffice转PDF检索模块文档名、标签、正文搜索HanLP分词 MySQL日志模块登录、上传、下载、删除审计Spring事件异步落库回收站软删除 定时清理逻辑删除标记功能边界一旦确定“有哪些表、哪些接口、哪些页面”基本就出来了。不要贪多把一个闭环做扎实比堆十个半成品模块有价值得多。1.3 非功能需求权限、安全、并发新手容易忽略非功能需求但这个系统的真正难点恰恰在这里。权限上要注意目录权限和文档权限不能割裂否则会出现“目录能看但文件下载不了”这种奇怪状态安全上要注意上传文件的类型校验、下载接口的任意路径读取漏洞、预览页面的XSS问题。这几个问题我在后面会专门展开。并发上不需要做太高要求校园网或小团队内网环境下QPS超过50已经算不错。真正要防的是“大文件上传时Tomcat报错”和“附件扫描任务把数据库连接池打满”这类低并发但高资源占用的问题。2. 数据模型与工程结构设计确定功能后先做数据建模。一个有说服力的文档管理系统数据库至少有五张核心表整套表结构设计要让评审或面试的人感觉到你理解业务而不是在网上复制一段建表SQL。2.1 MySQL表结构从用户到文档审计最简单的设计包括用户表sys_user、角色表sys_role、用户角色关联表、文档目录表doc_category、文档信息表doc_file、操作日志表sys_log。我这里简化为一个用户对应一个角色减少关联复杂度但结构仍然可以扩展成多对多。用户表的关键字段是id、username、password、real_name、dept_id、role_id、status、create_time。密码一定要加密存储我选的BCryptPasswordEncoder不要用MD5网上有大量MD5彩虹表存储MD5等于裸奔。文档目录表用parent_id做自关联加上category_name、order_num、create_by。查整棵目录树时先把所有数据查出来一次性在内存中组装成树不要每查一层都连一次数据库否则目录深了以后接口会明显变慢。文档信息表是核心表字段包括id、file_name、file_path、file_size、file_type、category_id、tags、download_count、create_by、create_time、update_time、deleted。这里有个细节file_path最好不要存完整绝对路径建议存相对路径比如/upload/2025/07/xxx_uuid.pdf。以后系统迁移、换磁盘、上OSS都不会被路径写死。上传时文件名用UUID重命名避免同名文件互相覆盖同时保留file_name作为展示名。日志表字段比较常规user_id、action_type、doc_id、ip、detail、create_time。记录谁在什么时候干了什么这是审计最基础的要求。2.2 SpringBoot工程分层Controller薄、Service厚创建工程时我建议用IDEA的Spring Initializr选SpringBoot 2.7.18、JDK 1.8、MySQL驱动、MyBatis-Plus、Lombok。2.7.x是SpringBoot 3.0之前最稳定的版本无论是后面要适配国产化应用服务器还是接入各种第三方SDK兼容性都更省心。包结构参考如下com.kaic.doc ├── controller // 接口定义只做参数校验和返回 ├── service // 业务逻辑事务、缓存、事件发布 ├── mapper // MyBatis-Plus数据访问 ├── entity // 数据库实体 ├── dto // 请求/响应对象 ├── config // 配置CORS、拦截器、Redis、Knife4j ├── security // JWT、权限拦截、密码加密 ├── common // 统一返回、异常、常量、工具类 └── event // 审计日志事件与监听器Controller层只负责接收请求、调用Service、返回统一结果不要在Controller里写文件保存逻辑。很多项目维护困难就是因为Service不写业务、Controller里写了一大堆最后想加事务注解都没法下手。2.3 统一返回结构与全局异常处理为了让前端少做判断我封装了统一返回值RTData public class RT { private Integer code; private String msg; private T data; public static T RT ok(T data) { RT r new R(); r.setCode(200); r.setMsg(success); r.setData(data); return r; } public static T RT fail(Integer code, String msg) { RT r new R(); r.setCode(code); r.setMsg(msg); return r; } }全局异常处理用RestControllerAdvice把业务异常、参数校验异常、文件异常、兜底异常分别处理。这里有个容易忽略的点不要把异常堆栈返回给前端尤其在生成环境。日志打完整堆栈接口只返回业务可读的message。另外文件下载接口异常时如果响应头已经写入了Content-Disposition就不要再试图重定向或返回JSON否则浏览器会直接把JSON当成文件下载。3. 核心功能实现上传下载、预览与检索这一章是文档管理系统的重点。我把上传下载、在线预览、全文检索分开讲每个方向踩过的坑比CRUD多得多。“上传”看起来简单但真要支持大文件、断点续传和稳定预览前置工作不少。3.1 文件存储策略本地磁盘还是OSS系统刚起步时我对存储方案很纠结。OSS要收费、要配AccessKey本地磁盘则要考虑备份和路径暴露。最终我选择本地磁盘但做了一个存储接口抽象把“本地存储”封装成StorageService接口以后想切OSS只需要新增一个实现类不用改动业务代码。application.yml里这样配置spring: servlet: multipart: max-file-size: 1024MB max-request-size: 2048MB web: resources: static-locations: classpath:/static/,file:${doc.upload-path} doc: upload-path: /data/docmanager/uploadstatic-locations里加file:${doc.upload-path}可以让SpringBoot直接把这个目录作为静态资源目录访问预览时通过/upload/日期/uuid.pdf就能拿到文件。但要注意这会把文件直接暴露出去如果不想所有登录用户都能访问就关闭静态映射走专门的下载接口做权限校验。3.2 支持大文件分片上传、合并与校验在实际后台运维上传几十MB的资料很常见大文件上传必须考虑两个问题网络不稳定导致中断、Tomcat配置限制导致报错。我采用的是前端分片方案前端用ElementUI的Upload组件或Web Uploader把文件按5MB一片切分每片带uploadId和index后端收到分片后先放入临时目录全部完成后触发合并接口。合并接口核心逻辑大致如下PostMapping(/merge) public RString merge(RequestBody MergeVO vo) { String uploadPath env.getProperty(doc.upload-path); File targetDir new File(uploadPath, DateUtil.today()); if (!targetDir.exists()) { targetDir.mkdirs(); } String uuid UUID.randomUUID().toString().replace(-, ); File target new File(targetDir, uuid .pdf); try (BufferedOutputStream out new BufferedOutputStream(new FileOutputStream(target))) { for (int index 0; index vo.getChunks(); index) { File part new File(uploadPath /tmp/ vo.getUploadId() _ index); Files.copy(part.toPath(), out); part.delete(); } } // 保存文档元数据到数据库 return R.ok(/upload/ DateUtil.today() / target.getName()); }合并时读完每片后立刻delete掉避免临时文件堆积。之前我一度没清理分片临时文件线上跑了两个月临时目录塞了好几个GB。这个细节不大但运维见到后会很崩溃。3.3 在线预览PDF、图片与Office的取舍在线预览我分三种情况处理图片直接用img标签展示顶多加个懒加载。PDF用pdf.js渲染解决不同浏览器打开application/pdf时体验差异。如果不想让用户下载PDF可以把预览地址放到一个单独的前端页面里隐藏工具栏。但下载按钮要设法禁用最理想的是后端在下载接口做权限校验不能只依赖前端隐藏。Office文档Word、Excel、PPT直接转PDF再预览。方案是服务器装LibreOffice用libreoffice --headless --convert-to pdf做转换转换结果缓存下来避免每次预览都重新转换。如果服务器资源紧张也可以退而求其次只提供下载功能。在线预览最容易翻车的地方是中文文件名和文件路径。转换后的PDF文件名不要用原名用文档id或uuid否则Content-Disposition里的文件名编码会让人崩溃。下载文件名如果要自定义必须做RFC 5987编码String fileName URLEncoder.encode(realName, StandardCharsets.UTF_8.name()).replace(, %20); response.setHeader(Content-Disposition, attachment; filename*UTF-8 fileName);3.4 全文检索HanLP分词与高亮文档管理系统的检索如果只按文件名模糊搜索太单薄。我在系统里集成了HanLP把上传的文本类文档txt、docx、pdf解析成纯文本存入数据库的full_text字段再对字段分词建立索引。搜索时先用HanLP分词用户关键词再用MySQL的LIKE配合倒排思路做召回。HanLP在SpringBoot里的接入非常简单引入依赖后直接用ListTerm termList HanLP.segment(keyword); ListString keywordList termList.stream().map(t - t.word).collect(Collectors.toList());不过要提醒一下HanLP的词典需要加载时间首次调用会比较慢建议在系统启动时预热。另外词典最好直接放到项目resources目录不要在运行时频繁更新。我做的搜索逻辑是“标题权重最高、标签次之、正文再次之”文档名命中的排前面正文匹配的排后面。不要指望纯MySQL解决超大数据量全文检索文档量超过10万条以后建议上Elasticsearch。但对毕业设计和中小团队MySQL这套方案足够稳定且好解释。4. 权限控制、缓存与审计日志的工程化落地这一章我把三个“看起来每个管理系统都要有但很多人只是应付一下”的功能展开讲。它们的价值不在功能本身而在于让你理解SpringBoot里拦截器、缓存、事件机制是怎么配合的。4.1 JWT RBAC登录态与接口权限认证用JWT这是SpringBoot项目的标准做法。登录成功后签发token前端放到请求头里后端用拦截器校验。加密密钥要配置在外部不要写死在代码里更不要提交到git仓库。权限我这里做了一个简单但够用的设计每个用户有角色每个角色有一组权限码接口上用自定义注解RequirePermission(doc:download)标记拦截器里判断当前用户权限码是否包含即可。这比单纯按角色放行更灵活角色只负责分配权限码集合。拦截器执行顺序容易被忽略。如果同时注册了CORS过滤器、JWT拦截器、静态资源处理器顺序不对会出现“登录接口被校验token的拦截器拦掉”或“跨域预检OPTIONS请求直接401”的问题。我的处理方式是放行所有OPTIONS请求if (OPTIONS.equalsIgnoreCase(request.getMethod())) { chain.doFilter(request, response); return; }4.2 Redis缓存文档列表和热点数据加入Redis不是炫技而是有真实场景。文档目录树、首页最新文档列表、热门下载Top10这些数据变化频率低但读取频率高每次都查数据库很浪费。我用Redis缓存目录树结构上用JSON字符串key为doc:category:tree修改目录时删除缓存。代码最简单也最容易理解。真正的坑是缓存穿透和缓存一致性。如果一个文档ID被恶意访问缓存和数据库都不存在每次请求都会打到数据库哪怕量不大也会让日志刷屏。我在查询文档详情的逻辑里加了一个空值缓存查不到时也缓存一个空对象过期时间设为60秒Object cache redisTemplate.opsForValue().get(buildKey(id)); if (cache null) { DocFile doc getById(id); if (doc null) { redisTemplate.opsForValue().set(buildKey(id), , 60, TimeUnit.SECONDS); throw new BizException(文档不存在); } redisTemplate.opsForValue().set(buildKey(id), JSON.toJSONString(doc), 1, TimeUnit.HOURS); }4.3 审计日志用Spring事件解耦操作日志如果直接写在业务代码里每一个Service方法都要追加一行日志入库逻辑代码会非常啰嗦。我用Spring的事件机制解决业务代码发布一个OperationLogEvent事件监听器异步落库。发布事件public void downloadDoc(Long docId, String username) { // 业务逻辑 applicationEventPublisher.publishEvent(new OperationLogEvent(this, username, DOWNLOAD, docId)); }监听器Async EventListener public void handleOperationLog(OperationLogEvent event) { sysLogService.save(event.toSysLog()); }这里有两个关键点一是监听器类要加上Async否则事件调用还是同步的会影响接口耗时二是在启动类或配置类上必须开启EnableAsync不然Async不生效。我调试时曾经排查了很久才发现是漏了开启异步注解。5. 实测踩坑记录版本、跨域、XSS、大文件上传、部署所有项目做到上线才会体会到“本地能跑”和“线上能跑”是两回事。我把这次开发中真实遇到、查了很长时间的几个问题列出来希望能省掉无谓的排查时间。5.1 SpringBoot版本选择2.7.x还是3.x创建新项目时IDEA默认可能推荐SpringBoot 3.x但我建议如果团队内部所有依赖还在用老版本先别急着上3.x。SpringBoot 3.x基于JDK 17和Jakarta EE很多第三方库如果不兼容就会因为包名javax改成jakarta而启动失败。如果搜到“SpringBoot版本太高”这类问题90%是第三方依赖和SpringBoot 3.x不兼容导致的。我选择SpringBoot 2.7.18并锁定对应版本的MyBatis-Plus 3.5.x、knife4j 4.x。这也是当前“能跑起来又不折腾”的稳妥组合。5.2 前后端分离跨域CORS配置与拦截器顺序本地前后端分离开发Vue跑在8080端口SpringBoot跑在8081端口跨域配置写在WebMvcConfigurer里Configuration public class WebConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/**) .allowedOriginPatterns(*) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .allowCredentials(true) .maxAge(3600); } }如果再加上JWT拦截器容易出现的问题是登录接口没有带token被拦截器拦下并返回未授权浏览器会报跨域错误但实际上是拦截器把预检请求提前拦截了跨域配置没有生效。所以拦截器放行OPTIONS特别重要这是我反复强调的。5.3 PDF上传的XSS攻击文件型XSS的根源与防护“SpringBoot解决PDF XSS攻击”这个热搜词说明很多人遇到过。PDF不是纯文本它内部可以包JavaScript被浏览器打开时执行脚本。如果上传了一个恶意PDF然后有人在线预览小则弹广告大则窃取登录态。我做了四层防护上传时校验扩展名和MIME类型白名单放行pdf、jpg、png、docx等拒绝html、svg、js等可执行文件。保存文件用UUID重命名不让用户控制路径。下载接口设置X-Content-Type-Options: nosniff和Content-Security-Policy防止浏览器猜测类型执行脚本。预览页面单独挂到隔离的路径下不使用主站cookie这样即使PDF里有脚本也拿不到主站的登录态。第一层过滤最容易绕扩展名和MIME类型都可以伪造真正关键的是第二层和第三层。如果对安全要求更高可以用PDFBox打开PDF检查是否有JavaScript action有就拒绝入库。5.4 大文件上传超时Tomcat、Spring、Nginx三层配置大文件上传报Request header is too large或Connection timed out时不要只改Spring配置。我在上传链路里同时处理好三个环节Spring的multipart限制、Tomcat的maxSwallowSize、Nginx的client_max_body_size。Nginx作为前置代理时配置可以这样改client_max_body_size 2048m; proxy_read_timeout 600s; proxy_send_timeout 600s;同时保证JVM内存足够大因为分片上传会涉及文件读写和可能的转换操作测试环境中2GB堆内存是底线。5.5 部署上线jar包、外部配置与资源映射部署我只推荐打jar包不要用war包。开发环境在IDEA直接mvn clean package -DskipTests然后把jar包上传到Linux服务器用nohup后台运行nohup java -jar doc-manager.jar --spring.profiles.activeprod /data/log/doc-manager.log 21 上线前把配置外置比如--spring.config.additional-location/data/docmanager/application-prod.yml这样升级代码时不用重新打包配置文件。还有一个容易被忽略的点上传目录、日志目录、临时目录要提前创建好并授权给运行用户否则第一次上传文件会报FileNotFoundException。如果项目未来要进国产化环境还需要考虑TongWeb这类应用服务器的适配工作主要集中在servlet依赖替换、web.xml描述符、数据源配置这几处提前把数据库连接池和文件路径这类配置独立出来能省很多事。部署自动化方面可以用Jenkins Gitea做CI/CD拉取代码、执行构建、推送jar到服务器、重启服务全程脚本化比手动上传靠谱得多。6. 上线之后的运维与扩展方向系统上线不是终点真正麻烦的是后面。文档数据是越攒越多的如果什么都不做三个月后磁盘可能就满了。6.1 定时备份数据库和上传目录双备份数据库备份用mysqldump上传目录直接定时同步到备份磁盘。我只写了一个简单crontab0 2 * * * mysqldump -uroot -pXXX doc_manager /data/backup/doc_manager_$(date \%Y\%m\%d).sql 0 3 * * * rsync -av /data/docmanager/upload /data/backup/upload/文件系统的备份往往比数据库备份更容易被忽略但文档系统一旦数据盘损坏丢的是全部文件比丢几行数据库记录严重得多。6.2 日志和监控排查问题不能只看控制台。我把SpringBoot的日志切分交给logback按天输出同时用Spring Boot Admin做基础健康检查。个人项目不要求上K8s才算部署但有一份心跳检测和内存监控的意识在面试时很加分。内存、CPU、磁盘占用需要定期看否则大量PDF转换任务会把服务器拖垮。6.3 可以继续扩展的点如果想继续把这个系统做大我建议按以下顺序扩展对接钉钉或企业微信免登录让团队成员用企业账号直接登录加入文档审批流Flowable让合同、报价单都走审批流程文档预览加权限水印防止截图外泄对接AI接口做文档摘要问答。如果是做地方文化展示平台这类题材底层同样是文档资源管理把“文档”泛化成“图片、视频、词条”即可架构不用推翻。最后想说一点个人感受。做完这个系统再回头看最大的收获不是会用SpringBoot写CRUD而是知道“存、管、查、看、控”这条链路上每一环都有工程细节。文档管理系统的价值不在于技术多新而在于权限边界、文件安全、异常处理这些细节是否想透。很多面试官问SpringBoot项目问到最后其实都是在问工程细节把这些内容讲清楚比背一百道SpringBoot面试题更有说服力。本文还有配套的精品资源点击获取
SpringBoot在线文档管理系统：从权限到预览的完整落地实践
简介本资源是一套面向计算机专业本科生的毕业设计实战项目聚焦基于SpringBoot的在线文档管理系统开发解决企业与个人在知识沉淀、文档协同与安全管控中的典型需求。资源包共389个文件涵盖82个核心Java后端代码、36个Vue前端组件、161个SVG图标资源、19张JPG界面截图及11个XML配置文件等完整呈现前后端分离架构其中bat脚本支持一键安装/运行yml与SQL文件提供环境配置与数据库初始化支持整体压缩包大小为31.36MB。项目包含清晰分层架构Controller-Service-Repository、JPA数据持久化、Thymeleaf/Vue双前端适配方案、权限控制与SSL传输安全设计并附带开题报告、演示PPT及详细部署说明文档。目前已有18人学习下载适合需要落地SpringBoot全栈开发、理解文档类系统业务逻辑与工程规范的中级开发者参考实践。1. 在线文档管理系统我到底要做哪些功能之前帮一个团队做内部资料库发现大家的文件散落在微信聊天记录、个人网盘、移动硬盘和共享目录里找一份合同原型有时候要问遍全组。后来接触到“基于SpringBoot的在线文档管理系统”这类题目我索性把之前的经验全部重来了一遍从功能拆解到代码落地做出一版可以直接复现的系统。这篇文章不打算写成从0开始的SpringBoot教程而是聚焦“文档管理系统在真实场景下到底该怎么落地”。1.1 从毕业设计命题到一个能跑起来的系统这个题目看起来套路其实是“管理系统”里最值得深挖的一类。因为文档管理系统的核心不是CRUD而是文件、权限、检索、预览这一整条链路。如果只是把一张表做成增删改查那和通讯录管理没有区别既然要称为“在线文档管理系统设计与实现”至少要回答四个问题文件存哪、怎么授权、如何预览、如何搜索。我最终定的目标是做一个面向中小团队的轻量级系统用户注册登录、文档目录树、文档上传下载、PDF/图片/Office在线预览、全文检索、操作日志、回收站再叠加角色权限控制。技术上使用SpringBoot MyBatis-Plus MySQL Redis Vue前端用Vue 2 ElementUI部署用jar包方式放到Linux服务器。这个方案对毕业设计和原型验证都比较稳妥很多团队内部实际使用的工具也是这个量级。1.2 功能模块清单从用户视角倒推功能设计我习惯先从使用者的视角倒推不要一上来就画架构图。管理员希望知道谁在什么时候下载了哪个文件普通员工希望上传后立刻能预览不用下载到本地部门负责人希望只能看到自己部门范围内的文档运维则希望上传大文件时服务器不会挂掉。最终的模块划分是这样的模块核心功能技术落点用户与角色注册、登录、权限分配JWT RBAC目录管理多级目录树、目录共享自关联表 内存组装文档管理上传、下载、重命名、移动、删除文件流 文档元数据表预览模块PDF、图片、Office文档预览pdf.js、LibreOffice转PDF检索模块文档名、标签、正文搜索HanLP分词 MySQL日志模块登录、上传、下载、删除审计Spring事件异步落库回收站软删除 定时清理逻辑删除标记功能边界一旦确定“有哪些表、哪些接口、哪些页面”基本就出来了。不要贪多把一个闭环做扎实比堆十个半成品模块有价值得多。1.3 非功能需求权限、安全、并发新手容易忽略非功能需求但这个系统的真正难点恰恰在这里。权限上要注意目录权限和文档权限不能割裂否则会出现“目录能看但文件下载不了”这种奇怪状态安全上要注意上传文件的类型校验、下载接口的任意路径读取漏洞、预览页面的XSS问题。这几个问题我在后面会专门展开。并发上不需要做太高要求校园网或小团队内网环境下QPS超过50已经算不错。真正要防的是“大文件上传时Tomcat报错”和“附件扫描任务把数据库连接池打满”这类低并发但高资源占用的问题。2. 数据模型与工程结构设计确定功能后先做数据建模。一个有说服力的文档管理系统数据库至少有五张核心表整套表结构设计要让评审或面试的人感觉到你理解业务而不是在网上复制一段建表SQL。2.1 MySQL表结构从用户到文档审计最简单的设计包括用户表sys_user、角色表sys_role、用户角色关联表、文档目录表doc_category、文档信息表doc_file、操作日志表sys_log。我这里简化为一个用户对应一个角色减少关联复杂度但结构仍然可以扩展成多对多。用户表的关键字段是id、username、password、real_name、dept_id、role_id、status、create_time。密码一定要加密存储我选的BCryptPasswordEncoder不要用MD5网上有大量MD5彩虹表存储MD5等于裸奔。文档目录表用parent_id做自关联加上category_name、order_num、create_by。查整棵目录树时先把所有数据查出来一次性在内存中组装成树不要每查一层都连一次数据库否则目录深了以后接口会明显变慢。文档信息表是核心表字段包括id、file_name、file_path、file_size、file_type、category_id、tags、download_count、create_by、create_time、update_time、deleted。这里有个细节file_path最好不要存完整绝对路径建议存相对路径比如/upload/2025/07/xxx_uuid.pdf。以后系统迁移、换磁盘、上OSS都不会被路径写死。上传时文件名用UUID重命名避免同名文件互相覆盖同时保留file_name作为展示名。日志表字段比较常规user_id、action_type、doc_id、ip、detail、create_time。记录谁在什么时候干了什么这是审计最基础的要求。2.2 SpringBoot工程分层Controller薄、Service厚创建工程时我建议用IDEA的Spring Initializr选SpringBoot 2.7.18、JDK 1.8、MySQL驱动、MyBatis-Plus、Lombok。2.7.x是SpringBoot 3.0之前最稳定的版本无论是后面要适配国产化应用服务器还是接入各种第三方SDK兼容性都更省心。包结构参考如下com.kaic.doc ├── controller // 接口定义只做参数校验和返回 ├── service // 业务逻辑事务、缓存、事件发布 ├── mapper // MyBatis-Plus数据访问 ├── entity // 数据库实体 ├── dto // 请求/响应对象 ├── config // 配置CORS、拦截器、Redis、Knife4j ├── security // JWT、权限拦截、密码加密 ├── common // 统一返回、异常、常量、工具类 └── event // 审计日志事件与监听器Controller层只负责接收请求、调用Service、返回统一结果不要在Controller里写文件保存逻辑。很多项目维护困难就是因为Service不写业务、Controller里写了一大堆最后想加事务注解都没法下手。2.3 统一返回结构与全局异常处理为了让前端少做判断我封装了统一返回值RTData public class RT { private Integer code; private String msg; private T data; public static T RT ok(T data) { RT r new R(); r.setCode(200); r.setMsg(success); r.setData(data); return r; } public static T RT fail(Integer code, String msg) { RT r new R(); r.setCode(code); r.setMsg(msg); return r; } }全局异常处理用RestControllerAdvice把业务异常、参数校验异常、文件异常、兜底异常分别处理。这里有个容易忽略的点不要把异常堆栈返回给前端尤其在生成环境。日志打完整堆栈接口只返回业务可读的message。另外文件下载接口异常时如果响应头已经写入了Content-Disposition就不要再试图重定向或返回JSON否则浏览器会直接把JSON当成文件下载。3. 核心功能实现上传下载、预览与检索这一章是文档管理系统的重点。我把上传下载、在线预览、全文检索分开讲每个方向踩过的坑比CRUD多得多。“上传”看起来简单但真要支持大文件、断点续传和稳定预览前置工作不少。3.1 文件存储策略本地磁盘还是OSS系统刚起步时我对存储方案很纠结。OSS要收费、要配AccessKey本地磁盘则要考虑备份和路径暴露。最终我选择本地磁盘但做了一个存储接口抽象把“本地存储”封装成StorageService接口以后想切OSS只需要新增一个实现类不用改动业务代码。application.yml里这样配置spring: servlet: multipart: max-file-size: 1024MB max-request-size: 2048MB web: resources: static-locations: classpath:/static/,file:${doc.upload-path} doc: upload-path: /data/docmanager/uploadstatic-locations里加file:${doc.upload-path}可以让SpringBoot直接把这个目录作为静态资源目录访问预览时通过/upload/日期/uuid.pdf就能拿到文件。但要注意这会把文件直接暴露出去如果不想所有登录用户都能访问就关闭静态映射走专门的下载接口做权限校验。3.2 支持大文件分片上传、合并与校验在实际后台运维上传几十MB的资料很常见大文件上传必须考虑两个问题网络不稳定导致中断、Tomcat配置限制导致报错。我采用的是前端分片方案前端用ElementUI的Upload组件或Web Uploader把文件按5MB一片切分每片带uploadId和index后端收到分片后先放入临时目录全部完成后触发合并接口。合并接口核心逻辑大致如下PostMapping(/merge) public RString merge(RequestBody MergeVO vo) { String uploadPath env.getProperty(doc.upload-path); File targetDir new File(uploadPath, DateUtil.today()); if (!targetDir.exists()) { targetDir.mkdirs(); } String uuid UUID.randomUUID().toString().replace(-, ); File target new File(targetDir, uuid .pdf); try (BufferedOutputStream out new BufferedOutputStream(new FileOutputStream(target))) { for (int index 0; index vo.getChunks(); index) { File part new File(uploadPath /tmp/ vo.getUploadId() _ index); Files.copy(part.toPath(), out); part.delete(); } } // 保存文档元数据到数据库 return R.ok(/upload/ DateUtil.today() / target.getName()); }合并时读完每片后立刻delete掉避免临时文件堆积。之前我一度没清理分片临时文件线上跑了两个月临时目录塞了好几个GB。这个细节不大但运维见到后会很崩溃。3.3 在线预览PDF、图片与Office的取舍在线预览我分三种情况处理图片直接用img标签展示顶多加个懒加载。PDF用pdf.js渲染解决不同浏览器打开application/pdf时体验差异。如果不想让用户下载PDF可以把预览地址放到一个单独的前端页面里隐藏工具栏。但下载按钮要设法禁用最理想的是后端在下载接口做权限校验不能只依赖前端隐藏。Office文档Word、Excel、PPT直接转PDF再预览。方案是服务器装LibreOffice用libreoffice --headless --convert-to pdf做转换转换结果缓存下来避免每次预览都重新转换。如果服务器资源紧张也可以退而求其次只提供下载功能。在线预览最容易翻车的地方是中文文件名和文件路径。转换后的PDF文件名不要用原名用文档id或uuid否则Content-Disposition里的文件名编码会让人崩溃。下载文件名如果要自定义必须做RFC 5987编码String fileName URLEncoder.encode(realName, StandardCharsets.UTF_8.name()).replace(, %20); response.setHeader(Content-Disposition, attachment; filename*UTF-8 fileName);3.4 全文检索HanLP分词与高亮文档管理系统的检索如果只按文件名模糊搜索太单薄。我在系统里集成了HanLP把上传的文本类文档txt、docx、pdf解析成纯文本存入数据库的full_text字段再对字段分词建立索引。搜索时先用HanLP分词用户关键词再用MySQL的LIKE配合倒排思路做召回。HanLP在SpringBoot里的接入非常简单引入依赖后直接用ListTerm termList HanLP.segment(keyword); ListString keywordList termList.stream().map(t - t.word).collect(Collectors.toList());不过要提醒一下HanLP的词典需要加载时间首次调用会比较慢建议在系统启动时预热。另外词典最好直接放到项目resources目录不要在运行时频繁更新。我做的搜索逻辑是“标题权重最高、标签次之、正文再次之”文档名命中的排前面正文匹配的排后面。不要指望纯MySQL解决超大数据量全文检索文档量超过10万条以后建议上Elasticsearch。但对毕业设计和中小团队MySQL这套方案足够稳定且好解释。4. 权限控制、缓存与审计日志的工程化落地这一章我把三个“看起来每个管理系统都要有但很多人只是应付一下”的功能展开讲。它们的价值不在功能本身而在于让你理解SpringBoot里拦截器、缓存、事件机制是怎么配合的。4.1 JWT RBAC登录态与接口权限认证用JWT这是SpringBoot项目的标准做法。登录成功后签发token前端放到请求头里后端用拦截器校验。加密密钥要配置在外部不要写死在代码里更不要提交到git仓库。权限我这里做了一个简单但够用的设计每个用户有角色每个角色有一组权限码接口上用自定义注解RequirePermission(doc:download)标记拦截器里判断当前用户权限码是否包含即可。这比单纯按角色放行更灵活角色只负责分配权限码集合。拦截器执行顺序容易被忽略。如果同时注册了CORS过滤器、JWT拦截器、静态资源处理器顺序不对会出现“登录接口被校验token的拦截器拦掉”或“跨域预检OPTIONS请求直接401”的问题。我的处理方式是放行所有OPTIONS请求if (OPTIONS.equalsIgnoreCase(request.getMethod())) { chain.doFilter(request, response); return; }4.2 Redis缓存文档列表和热点数据加入Redis不是炫技而是有真实场景。文档目录树、首页最新文档列表、热门下载Top10这些数据变化频率低但读取频率高每次都查数据库很浪费。我用Redis缓存目录树结构上用JSON字符串key为doc:category:tree修改目录时删除缓存。代码最简单也最容易理解。真正的坑是缓存穿透和缓存一致性。如果一个文档ID被恶意访问缓存和数据库都不存在每次请求都会打到数据库哪怕量不大也会让日志刷屏。我在查询文档详情的逻辑里加了一个空值缓存查不到时也缓存一个空对象过期时间设为60秒Object cache redisTemplate.opsForValue().get(buildKey(id)); if (cache null) { DocFile doc getById(id); if (doc null) { redisTemplate.opsForValue().set(buildKey(id), , 60, TimeUnit.SECONDS); throw new BizException(文档不存在); } redisTemplate.opsForValue().set(buildKey(id), JSON.toJSONString(doc), 1, TimeUnit.HOURS); }4.3 审计日志用Spring事件解耦操作日志如果直接写在业务代码里每一个Service方法都要追加一行日志入库逻辑代码会非常啰嗦。我用Spring的事件机制解决业务代码发布一个OperationLogEvent事件监听器异步落库。发布事件public void downloadDoc(Long docId, String username) { // 业务逻辑 applicationEventPublisher.publishEvent(new OperationLogEvent(this, username, DOWNLOAD, docId)); }监听器Async EventListener public void handleOperationLog(OperationLogEvent event) { sysLogService.save(event.toSysLog()); }这里有两个关键点一是监听器类要加上Async否则事件调用还是同步的会影响接口耗时二是在启动类或配置类上必须开启EnableAsync不然Async不生效。我调试时曾经排查了很久才发现是漏了开启异步注解。5. 实测踩坑记录版本、跨域、XSS、大文件上传、部署所有项目做到上线才会体会到“本地能跑”和“线上能跑”是两回事。我把这次开发中真实遇到、查了很长时间的几个问题列出来希望能省掉无谓的排查时间。5.1 SpringBoot版本选择2.7.x还是3.x创建新项目时IDEA默认可能推荐SpringBoot 3.x但我建议如果团队内部所有依赖还在用老版本先别急着上3.x。SpringBoot 3.x基于JDK 17和Jakarta EE很多第三方库如果不兼容就会因为包名javax改成jakarta而启动失败。如果搜到“SpringBoot版本太高”这类问题90%是第三方依赖和SpringBoot 3.x不兼容导致的。我选择SpringBoot 2.7.18并锁定对应版本的MyBatis-Plus 3.5.x、knife4j 4.x。这也是当前“能跑起来又不折腾”的稳妥组合。5.2 前后端分离跨域CORS配置与拦截器顺序本地前后端分离开发Vue跑在8080端口SpringBoot跑在8081端口跨域配置写在WebMvcConfigurer里Configuration public class WebConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/**) .allowedOriginPatterns(*) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .allowCredentials(true) .maxAge(3600); } }如果再加上JWT拦截器容易出现的问题是登录接口没有带token被拦截器拦下并返回未授权浏览器会报跨域错误但实际上是拦截器把预检请求提前拦截了跨域配置没有生效。所以拦截器放行OPTIONS特别重要这是我反复强调的。5.3 PDF上传的XSS攻击文件型XSS的根源与防护“SpringBoot解决PDF XSS攻击”这个热搜词说明很多人遇到过。PDF不是纯文本它内部可以包JavaScript被浏览器打开时执行脚本。如果上传了一个恶意PDF然后有人在线预览小则弹广告大则窃取登录态。我做了四层防护上传时校验扩展名和MIME类型白名单放行pdf、jpg、png、docx等拒绝html、svg、js等可执行文件。保存文件用UUID重命名不让用户控制路径。下载接口设置X-Content-Type-Options: nosniff和Content-Security-Policy防止浏览器猜测类型执行脚本。预览页面单独挂到隔离的路径下不使用主站cookie这样即使PDF里有脚本也拿不到主站的登录态。第一层过滤最容易绕扩展名和MIME类型都可以伪造真正关键的是第二层和第三层。如果对安全要求更高可以用PDFBox打开PDF检查是否有JavaScript action有就拒绝入库。5.4 大文件上传超时Tomcat、Spring、Nginx三层配置大文件上传报Request header is too large或Connection timed out时不要只改Spring配置。我在上传链路里同时处理好三个环节Spring的multipart限制、Tomcat的maxSwallowSize、Nginx的client_max_body_size。Nginx作为前置代理时配置可以这样改client_max_body_size 2048m; proxy_read_timeout 600s; proxy_send_timeout 600s;同时保证JVM内存足够大因为分片上传会涉及文件读写和可能的转换操作测试环境中2GB堆内存是底线。5.5 部署上线jar包、外部配置与资源映射部署我只推荐打jar包不要用war包。开发环境在IDEA直接mvn clean package -DskipTests然后把jar包上传到Linux服务器用nohup后台运行nohup java -jar doc-manager.jar --spring.profiles.activeprod /data/log/doc-manager.log 21 上线前把配置外置比如--spring.config.additional-location/data/docmanager/application-prod.yml这样升级代码时不用重新打包配置文件。还有一个容易被忽略的点上传目录、日志目录、临时目录要提前创建好并授权给运行用户否则第一次上传文件会报FileNotFoundException。如果项目未来要进国产化环境还需要考虑TongWeb这类应用服务器的适配工作主要集中在servlet依赖替换、web.xml描述符、数据源配置这几处提前把数据库连接池和文件路径这类配置独立出来能省很多事。部署自动化方面可以用Jenkins Gitea做CI/CD拉取代码、执行构建、推送jar到服务器、重启服务全程脚本化比手动上传靠谱得多。6. 上线之后的运维与扩展方向系统上线不是终点真正麻烦的是后面。文档数据是越攒越多的如果什么都不做三个月后磁盘可能就满了。6.1 定时备份数据库和上传目录双备份数据库备份用mysqldump上传目录直接定时同步到备份磁盘。我只写了一个简单crontab0 2 * * * mysqldump -uroot -pXXX doc_manager /data/backup/doc_manager_$(date \%Y\%m\%d).sql 0 3 * * * rsync -av /data/docmanager/upload /data/backup/upload/文件系统的备份往往比数据库备份更容易被忽略但文档系统一旦数据盘损坏丢的是全部文件比丢几行数据库记录严重得多。6.2 日志和监控排查问题不能只看控制台。我把SpringBoot的日志切分交给logback按天输出同时用Spring Boot Admin做基础健康检查。个人项目不要求上K8s才算部署但有一份心跳检测和内存监控的意识在面试时很加分。内存、CPU、磁盘占用需要定期看否则大量PDF转换任务会把服务器拖垮。6.3 可以继续扩展的点如果想继续把这个系统做大我建议按以下顺序扩展对接钉钉或企业微信免登录让团队成员用企业账号直接登录加入文档审批流Flowable让合同、报价单都走审批流程文档预览加权限水印防止截图外泄对接AI接口做文档摘要问答。如果是做地方文化展示平台这类题材底层同样是文档资源管理把“文档”泛化成“图片、视频、词条”即可架构不用推翻。最后想说一点个人感受。做完这个系统再回头看最大的收获不是会用SpringBoot写CRUD而是知道“存、管、查、看、控”这条链路上每一环都有工程细节。文档管理系统的价值不在于技术多新而在于权限边界、文件安全、异常处理这些细节是否想透。很多面试官问SpringBoot项目问到最后其实都是在问工程细节把这些内容讲清楚比背一百道SpringBoot面试题更有说服力。本文还有配套的精品资源点击获取