SpringBoot+Vue3在线文档管理系统：权限、版本与部署实战

说到在线文档管理系统，不少人第一反应是装一个现成的开源 Wiki 完事。但真去企业里做一轮知识库整合之后，你会发现项目最难的地方根本不是“把文档传上去”，而是怎么把权限、版本、分类、检索和在线编辑这些看似零散的能力收进同一套框架里。我这段时间维护的一套源码就是干这个的：Java SpringBoot + Vue3 + MyBatis，MySQL 做存储，前后端完全分离，目录、权限、版本、富文本编辑、附件管理全部走 REST 接口，前端只负责展示和交互，后端只负责业务和数据。

这套源码很适合两个群体。一个是打算做全栈项目练手的人，通过它可以把用户认证、增删改查、文件上传、前端路由守卫这些“面试高频点”串成一条完整链路；另一个是刚接手企业信息化项目、需要快速搭一个文档中心或者知识库的团队，直接把骨架拿过去改业务，能省掉不少从零开始的成本。下面我会从需求设计、数据库结构、后端接口、前端页面的顺序拆解，最后再把部署联调中踩过的高频坑列一遍，希望能让想复现这套系统的人少走弯路。

1. 在线文档管理系统核心需求与整体设计：先搞清楚要做什么

1.1 典型业务场景与需求痛点

所谓在线文档管理系统，本质上解决的是“文件被到处乱放”的问题。企业内部常见的场景很直白：合同、方案、说明书、培训资料散落在个人电脑、即时通讯软件聊天记录、共享网盘各个角落，同事要找一个文件可能得问三个人。更麻烦的是，同一个文档经常出现“最终版”“最终版2”“打死也不再改版”这种重复文件，时间一长根本分不清哪个才是有效版本。

所以一个及格的系统至少要覆盖这些需求：

• 文档统一入库：文档不再以文件流形式散落，而是沉淀成一条条记录，有标题、分类、归属人、状态。
• 分类与检索：支持目录树、标签、关键字搜索，让使用者能按业务线找到文档。
• 版本管理：每次编辑保留历史版本，随时可以对比和回滚，防止改坏了没法恢复。
• 权限控制：不同角色看不同内容，管理员、编辑者、访客各有所能，涉及敏感文档时必须做隔离。
• 在线预览与编辑：把“传文件”变成“写文档”，富文本编辑、自动保存是基本操作。

这个需求列表看起来普通，真正落地时，每一条都会牵扯出前后端各个模块的配合。比如“分类”不是简单的下拉框，而是递归的目录树，要处理父子层级带来的数据查询复杂度；“版本管理”不是存一个 update_time 字段，而是要有独立的历史内容表；“权限”不只是前端隐藏按钮，后端接口也必须做同样校验，否则绕过页面直接调接口就能越权。

1.2 为什么选 SpringBoot+Vue3+MyBatis+MySQL 这套组合

先别急着堆新技术，这套组合能成为很多业务系统的默认选项，原因是它足够“稳”且招聘市场接受度高。Java + Spring Boot 的服务端生态非常成熟，适合做权限、事务、复杂业务逻辑；Vue3 在前端开发效率和组件生态上已经非常完善，配合 Vite 启动又快，写后台管理类页面很顺手；MyBatis 保留手写 SQL 的自由度，项目后期遇到复杂查询不至于被 ORM 的抽象限制住；MySQL 则适合绝大多数中小型系统的数据量，运维成本也低。

有人会问，为什么不直接用 JPA？我的习惯是：如果查询场景比较固定、实体关系简单，JPA 确实省事；但文档管理系统里充满了动态条件搜索、批量插入、多表关联统计这类需求，用 MyBatis 手写 SQL 反而更好控制性能。比如文档列表要做“标题模糊搜索 + 分类过滤 + 发布时间区间 + 分页”，这种动态 SQL 在 MyBatis 里写得很清晰，换 JPA 要么写 Specification，要么拼 JPQL，可读性都要差一些。

再聊前后端分离。很多老项目还在用 Thymeleaf 模板渲染页面，不是不能做，而是当你要做多端复用、页面交互复杂度变高时，服务端和前端被绑在同一个工程里，联调、发布、分工都很别扭。前后端分离之后，后端只提供 JSON 数据接口，前端单独部署到 Nginx，团队可以并行开发，减少大量互相等待的时间。这套系统源码也明确分成了 frontend 和 backend 两个工程，两个端口、两套启动方式，互不依赖。

1.3 系统模块拆分与源码结构

我在整理源码时，把后端拆成了标准的三层结构：Controller 负责接收请求、参数校验和响应包装；Service 负责业务逻辑、事务控制和权限校验；Mapper 只管 SQL 映射，不掺杂业务判断。前端则按页面维度组织，文档模块、用户模块、目录模块各自独立，不搞一个“Vue 单文件组件里写几千行”的坏味道。

后端主目录大致是这样：

backend ├── pom.xml ├── src/main/java/com/example/docms │ ├── DocmsApplication.java │ ├── common │ │ ├── Result.java │ │ ├── ResultCode.java │ │ └── GlobalExceptionHandler.java │ ├── config │ │ ├── CorsConfig.java │ │ ├── JwtInterceptor.java │ │ └── MybatisPlusConfig.java │ ├── controller │ │ ├── AuthController.java │ │ ├── DocumentController.java │ │ ├── CategoryController.java │ │ └── UserController.java │ ├── service │ │ ├── impl │ │ └── ... │ ├── mapper │ │ ├── UserMapper.java │ │ ├── DocumentMapper.java │ │ └── ... │ └── entity │ ├── User.java │ ├── Document.java │ └── ... └── src/main/resources ├── application.yml └── mapper ├── UserMapper.xml └── DocumentMapper.xml

前端主目录：

frontend ├── index.html ├── package.json ├── vite.config.js ├── src │ ├── main.js │ ├── App.vue │ ├── api │ │ ├── auth.js │ │ └── document.js │ ├── router │ │ └── index.js │ ├── stores │ │ ├── user.js │ │ └── document.js │ ├── views │ │ ├── Login.vue │ │ ├── Layout.vue │ │ ├── document │ │ └── user │ └── components │ └── CategoryTree.vue └── src/utils ├── axios.js └── auth.js

从目录能看出来，这套代码没有把“系统管理”和“文档管理”混在一起，Controller 分层清晰，改某个模块不会动到其他模块，这也是我强调“源码可以接着改”的原因。

2. 后端实现：SpringBoot + MyBatis + MySQL 的骨架搭建

2.1 数据库表结构：先设计好文档、目录、用户、权限的主表

后端开发最忌讳上来就写代码，数据库设计才是地基。我设计这套系统时，并没有把所有字段堆进一张大表，而是拆出了几张职责明确的表，核心包括：用户表、角色表、目录分类表、文档信息表、文档内容表、附件表，以及用户角色关联表、角色权限关联表。

先看用户和权限相关的基础表：

CREATE TABLE `sys_user` ( `id` bigint NOT NULL AUTO_INCREMENT, `username` varchar(50) NOT NULL, `password` varchar(120) NOT NULL, `nickname` varchar(50) DEFAULT NULL, `status` tinyint DEFAULT 1 COMMENT '1启用 0禁用', `create_time` datetime DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`id`) ); CREATE TABLE `sys_role` ( `id` bigint NOT NULL AUTO_INCREMENT, `role_key` varchar(50) NOT NULL, `role_name` varchar(50) NOT NULL, PRIMARY KEY (`id`) ); CREATE TABLE `sys_user_role` ( `user_id` bigint NOT NULL, `role_id` bigint NOT NULL, PRIMARY KEY (`user_id`, `role_id`) );

用户表和角色表采取标准的多对多关联，因为一个用户可能既是管理员又是某几个业务部门的审核员。密码字段我建议存 BCrypt 加密后的字符串，不要在数据库里出现明文密码，这是底线。

再看文档核心表：

CREATE TABLE `doc_category` ( `id` bigint NOT NULL AUTO_INCREMENT, `parent_id` bigint DEFAULT 0, `name` varchar(100) NOT NULL, `sort_order` int DEFAULT 0, `status` tinyint DEFAULT 1, PRIMARY KEY (`id`) ); CREATE TABLE `doc_info` ( `id` bigint NOT NULL AUTO_INCREMENT, `title` varchar(255) NOT NULL, `category_id` bigint DEFAULT NULL, `owner_id` bigint NOT NULL, `version` int DEFAULT 1, `status` tinyint DEFAULT 1 COMMENT '1正常 0草稿', `view_count` int DEFAULT 0, `create_time` datetime DEFAULT CURRENT_TIMESTAMP, `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`id`) ); CREATE TABLE `doc_content` ( `id` bigint NOT NULL AUTO_INCREMENT, `doc_id` bigint NOT NULL, `version` int NOT NULL, `content_html` longtext, `content_text` longtext, `update_by` bigint DEFAULT NULL, `create_time` datetime DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`id`), KEY `idx_doc_id` (`doc_id`) );

这里的关键设计是doc_info和doc_content拆开，各自分工明确。doc_info只存文档的属性，比如标题、分类、作者、当前版本号，这样列表页查询时就非常快，不会因为加载全文导致接口卡顿。doc_content按版本存正文内容，每次保存会写入一条新记录，旧的正文保留下来，形成可回滚的历史版本。

注意：正文为什么要拆出来而不直接放在doc_info？我实测过，如果文档正文和标题放在同一张表，列表查询会频繁读取大量长文本字段，MySQL 需要加载到内存的数据量翻了十倍不止，同一张表分页查询的响应时间明显变长。拆表之后，列表页根本不查内容表，性能数据稳定很多。

2.2 MyBatis Mapper 与动态 SQL：构造灵活查询的关键

MyBatis 的核心配置在于 Mapper 接口和对应的 XML 文件。这里我以文档分页查询为例，展示动态 SQL 的写法：

@Mapper public interface DocumentMapper { List<DocumentVO> selectDocumentPage(@Param("keyword") String keyword, @Param("categoryId") Long categoryId, @Param("status") Integer status, @Param("offset") int offset, @Param("pageSize") int pageSize); Long countDocumentPage(@Param("keyword") String keyword, @Param("categoryId") Long categoryId, @Param("status") Integer status); }

<select id="selectDocumentPage" resultType="com.example.docms.vo.DocumentVO"> SELECT d.id, d.title, d.version, d.view_count, d.create_time, d.update_time, c.name AS category_name, u.nickname AS owner_name FROM doc_info d LEFT JOIN doc_category c ON d.category_id = c.id LEFT JOIN sys_user u ON d.owner_id = u.id <where> <if test="keyword != null and keyword != ''"> AND d.title LIKE CONCAT('%', #{keyword}, '%') </if> <if test="categoryId != null"> AND d.category_id = #{categoryId} </if> <if test="status != null"> AND d.status = #{status} </if> </where> ORDER BY d.update_time DESC LIMIT #{offset}, #{pageSize} </select>

有人会把分页逻辑写进 Service 层，把当前页码转成 SQL 里的偏移量，这没问题。但更高效的做法是利用现成的分页插件，比如 PageHelper，这样 Controller 和 Service 里只需要写一个 pageNum 和 pageSize，插件会帮我们算好 limit 参数。我在这套源码里两种方式都保留了一版，初学者建议先从手写 LIMIT 理解原理，再切换到插件减少重复代码。

动态 SQL 里最需要注意的是注入问题。关键字搜索时一定要使用#{keyword}，让 MyBatis 帮你生成预编译参数，而不是用${keyword}，否则用户输入一个%或者单引号就可能造成 SQL 注入。这条规矩适用于所有查询条件。

2.3 统一返回结构、全局异常处理与登录认证

前后端分离项目最忌讳前后端各写一套响应格式，前端不知道后端什么时候返回成功、什么时候返回失败。我统一规定后端所有接口返回一个标准结构：

public class Result<T> { private Integer code; private String message; private T data; public static <T> Result<T> success(T data) { Result<T> result = new Result<>(); result.code = 200; result.message = "操作成功"; result.data = data; return result; } public static <T> Result<T> error(String message) { Result<T> result = new Result<>(); result.code = 500; result.message = message; return result; } }

有了统一结构，再做全局异常处理就顺理成章。我在GlobalExceptionHandler里拦截参数校验异常、业务异常、未知异常，分别转成对应错误码和提示信息，前端只要判断code === 200即可，不需要每个接口单独写一段try-catch。

认证部分采用 JWT 令牌。登录接口校验用户名密码成功后生成 token，后续请求在请求头携带Authorization: Bearer xxx，后端通过拦截器统一解析，把当前用户信息放入 ThreadLocal 或者从 Redis 里读取。不建议把用户信息全部塞进 token，因为 token 本身有大小限制，而且一旦用户被禁用，已发放的 token 可能无法立刻失效。如果要做到严格失效控制，最好引入 Redis 做 token 黑名单，这是上线前需要考虑的。

3. Vue3 前端实现：从登录鉴权到在线编辑完整链路

3.1 初始化 Vue3 工程：Vite、Router、Pinia 一条龙

前端工程我选择 Vite 构建，创建项目时直接使用官方脚手架：

npm create vite@latest frontend -- --template vue cd frontend npm install npm install vue-router pinia axios

路由设计上采用经典的前后端分离布局。Layout.vue是最外层框架，左侧放目录树，右侧放内容区，通过嵌套路由挂载文档列表和编辑页面。使用 Vue Router 时，我习惯把目录树和文档列表设计成带参数的动态路由，类似/doc/category/:categoryId，这样刷页面时 URL 还能保持住当前所在分类。

Pinia 负责管理前端全局状态，最典型的是当前登录用户信息。用户刷新页面后，token 还在 localStorage 里，但用户昵称、角色列表这类资料可能已经丢了，这时可以在stores/user.js里定义一个函数，在应用启动时调用后端接口重新拉取用户信息，避免频繁读取后端造成不必要的请求。

3.2 Axios 请求封装与登录态管理

axios 一定不能直接在组件里到处写，否则后面处理 token、错误提示、401 跳转时，你会发现改一处要动几十个文件。我通常封装到src/utils/axios.js，用拦截器统一处理两件事：

import axios from 'axios'; const service = axios.create({ baseURL: '/api', timeout: 15000 }); service.interceptors.request.use(config => { const token = localStorage.getItem('access_token'); if (token) { config.headers.Authorization = `Bearer ${token}`; } return config; }); service.interceptors.response.use( response => { if (response.data.code !== 200) { // 弹窗提示错误，比如“文档标题不能为空” return Promise.reject(new Error(response.data.message)); } return response.data.data; }, error => { if (error.response && error.response.status === 401) { localStorage.removeItem('access_token'); window.location.href = '/login'; } return Promise.reject(error); } );

这样封装完，业务代码里调用接口就非常干净：

import { getDocumentPage } from '@/api/document'; const list = await getDocumentPage({ keyword: '需求', categoryId: 1 });

登录态管理的关键在于路由守卫。没有 token 的人不允许进任何业务页面，统一踢回登录页：

router.beforeEach((to) => { const token = localStorage.getItem('access_token'); if (!token && to.path !== '/login') { return '/login'; } if (token && to.path === '/login') { return '/'; } return true; });

3.3 文档目录树与在线编辑实现

文档目录树的实现不算复杂，但要注意递归组件。CategoryTree.vue接收后端返回的目录数组，每个节点可能包含children，组件内部用v-for循环渲染，遇到子节点继续调用组件本身。后端返回数据时，一般设计成父子嵌套结构比较方便前端渲染。

在线编辑我用的是轻量级富文本编辑器，核心交互是自动保存。自动保存不能每敲一个字符就发一次请求，否则数据库压力很大。我的做法是利用防抖，用户停止输入 3 秒后再触发保存接口，同时显示“正在保存”或“已保存”状态。这样既保证内容不会丢失，也不会产生无意义的接口请求。

在新建文档时我会先在doc_info表插入一条记录拿到文档 ID，然后再把编辑器内容写入doc_content；后续每次保存则是再次插入一条新版本内容，同时更新doc_info.version。不要把每次保存都做成 UPDATE 原记录，否则历史版本就不存在了。

3.4 权限控制落地：路由守卫与按钮级权限

权限控制是文档系统绕不开的环节。前端要做两层：路由级和按钮级。路由级权限通过路由元信息控制，比如：

{ path: '/system/user', component: UserManage, meta: { roles: ['admin'] } }

然后在路由守卫中判断当前用户角色是否包含admin，不满足就跳转 403 页面。按钮级权限更简单，封装一个自定义指令v-permission，指定按钮需要的权限标识，如果没有权限就移除对应 DOM 节点。但必须明确：前端权限只是体验优化，真正安全的后端必须对每个接口做权限校验，否则攻击者直接调 API 就能绕过页面限制，我见过不止一个项目在这里翻车。

4. 部署联调与常见问题：把源码真正跑起来

4.1 本地环境准备与配置

先把环境搞定：JDK 建议用 17 以上版本，Maven 配置阿里云镜像加速依赖下载；Node 建议 18 以上，npm 或者 pnpm 都行；MySQL 建议 8.0 版本，注意默认认证插件和驱动版本，Spring Boot 3.x 需要配置对应的 mysql-connector-j 依赖。

后端配置文件application.yml里最容易出错的是数据库连接部分：

spring: datasource: url: jdbc:mysql://localhost:3306/docms?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai username: root password: yourpassword driver-class-name: com.mysql.cj.jdbc.Driver mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.docms.entity

如果忘记配置serverTimezone，本地连接 MySQL 8 经常会报时区错误。这是一个看似简单但几乎每个人都会踩的坑。

4.2 前端代理与接口联调：一次性解决跨域

前后端分离开发时，前端请求地址一般是http://localhost:5173，后端接口是http://localhost:8080，直接请求必然跨域。我的处理方式是优先使用 Vite 代理，而不是在后端放开跨域：

// vite.config.js export default defineConfig({ server: { port: 5173, proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true, rewrite: path => path.replace(/^\/api/, '') } } } });

这样前端代码里所有请求都写成/api/xxx，代理会把请求转发到后端，同时去掉/api前缀，后端不需要额外处理跨域配置。用代理的好处是正式部署时前端和后端如果在同一台服务器上，可以继续沿用当前地址结构，改造量很小。当然，如果前端和后端域名确实不同，就需要在后端启用 CORS 配置，二选一即可，不用同时配，防止请求头冲突。

4.3 高频问题速查：从后台报错到前端白屏的排障清单

我做一个常见问题速查表，方便对照排错。

我在实际排错时还有个习惯：不要同时怀疑三个地方。先抓后端日志，看接口是否被访问到，再看 SQL 是否执行成功，最后看前端有没有把返回值正确处理。很多问题其实发生在“后端接口正常，但 axios 不小心又包了一层 response.data”，这种低级错误排查起来最费时间。

4.4 上线前安全与性能加固：我常做的几件事

如果这套系统要正式部署，不是“能跑”就完事了。我至少会做这几件事：

• 密码加密统一升级为 BCrypt，并且登录接口增加失败次数限制，防止暴力破解。
• JWT 密钥不要硬编码在代码里，放配置中心或者环境变量；过期时间不要设置太长，生产环境我一般控制在 2 小时左右。
• 所有涉及删除、更新的接口，后端都要校验操作者的创建人身份或角色权限，不能只依赖前端传参数。
• 数据库加慢查询日志，定期排查文档列表、搜索接口有没有出现全表扫描或者大段 text 字段回表。
• 文档正文的查询走 LongText 字段时，尽量只 select 需要的列，不要随手SELECT *。
• 如果要支持全文检索，可以引入 Elasticsearch，或者至少用 MySQL 的全文索引配合ngram分词，而不是靠LIKE %关键词%扛所有流量。

性能层面的另一个重点，是千万不能忽略文档内容表的增长。版本历史越多，longtext字段堆积得越快。上线前建议写一个定时任务，只保留最近 N 个历史版本，或者把 N 天前且未被手动标记为重要的历史记录统一清理，否则数据库会越来越胖。

最后说点个人体会

这套系统从设计到跑通，我最大的感触是“在线文档”没有想象中那么简单，也没有想象中那么难。难在模块之间的耦合，目录、权限、内容、版本、搜索，任何一个功能单独拎出来都不复杂，但合在一起时，如果数据库没设计好、接口职责没分清楚，改一个功能就会牵动一片。简单在只要你把基础分层做扎实，所有功能都是顺着业务逻辑堆出来的。

如果你正在复现这套 SpringBoot + Vue3 + MyBatis 的文档管理系统，我建议先把数据库建好，再写后端接口，最后才动前端页面，顺序不要乱。还有一个非常实用的小技巧：开发前先说好接口文档，哪怕用文本先写一份也行，前后端各自按约定开发，能少吵很多架。等整套系统能跑起来，你再往里面加全文搜索、在线表格、多人协同这类高级功能，都会顺滑很多。