1. 实验室教学场景里，资源管理到底卡在哪
先说个我亲历的场景。实验室里设备清单靠 Excel、实验指导书存在网盘、教学视频分散在百度网盘和教师个人电脑上、学生提交实验报告靠微信群里接龙收邮箱、成绩统计靠期末手动逐条对名单。一个学期下来，光是找文件、收作业、催未交这三件事，就能耗掉一大半教学精力。
我做这套实验室教学资源管理系统，核心目标不是写一个好看的管理后台，而是把这几条业务线拧成一股绳：资源归档、在线学习、任务下发、报告提交、成绩反馈。系统面向三类角色——系统管理员、教师、学生。管理员的活是管用户、管权限、管资源分类和运行日志；教师的活是上传实验指导书和教学视频、发布实验任务、批改实验报告并登记成绩；学生的入口则是浏览资源、看视频、下载资料、提交报告、查看自己的成绩。
从这个需求出发，功能模块可以拆成这些：用户认证与角色权限、资源管理（文档、图片、视频三维分类）、视频在线播放、实验任务管理、实验报告提交与批改、成绩汇总、个人中心、系统的参数配置。
这些模块听起来不复杂，但真的动手做之后会发现，难点不在 CRUD 本身，而在文件的存取、视频的流式播放、分权限的路由控制，以及前后端打包部署时那些绕不开的坑。下面我要拆开讲的，就是这些细节。
2. 技术选型：SpringBoot、Vue、MinIO、HLS 这条链路是怎么锁死的
2.1 为什么后端选 SpringBoot 而不是别的
这套系统是典型的信息管理系统，没有高并发、没有分布式事务、没有复杂消息队列，要的是开发效率高、上手难度低、生态成熟。SpringBoot 恰好踩在黄金点上：内嵌 Tomcat、自动装配、起步依赖把配置量压缩到极致。一个实验室管理系统，从创建项目到跑通接口，半小时以内就能完成骨架搭建。
SpringBoot 的自动装配原理没必要展开说，但可以一句话点透：@SpringBootApplication这个组合注解里的@EnableAutoConfiguration会扫描META-INF/spring.factories里的自动配置类，按条件注解决定哪些配置生效。理解了这条链，后面新增自定义 starter、覆盖默认配置时就不会懵。
接口风格我选了 RESTful，全部返回统一 JSON 结构体。这类系统将来大概率要对接实验室预约、设备管理甚至教务系统，RESTful 接口的可扩展性是最好的选择。
2.2 为什么前端必须用 Vue
管理端页面用原生写法维护成本太高，Vue 这类渐进式框架明显更合适。响应式数据绑定让表单交互、列表刷新、状态联动省掉大量 DOM 操作代码。Vue 的生态能满足系统的所有前端需求：vue-router 做路由、Pinia 或 Vuex 做状态管理、Element Plus 做组件库。尤其是上传组件和表格组件，减少的工作量是实打实的。
站点页面是典型的 SPA 形态，Vue 的这种模式对系统类项目开发效率优势明显。在整个系统中，前端不止一个，还包含管理后台，而 Vue 的工程化能力，让它足以应对这些复杂页面场景。
2.3 资源存取顺手选了 MinIO
教学资源里大头是文档和视频，动辄几百 MB 的 PPT、录屏、实验指导书，不能往服务器本地目录扔。直接存磁盘会带来三个问题：磁盘空间难扩容、备份困难、后续迁移成本高。所以引入了 MinIO——开源、兼容 Amazon S3 协议、部署简单，一条命令就能跑起来。文档存 MinIO，数据库里只留文件路径、大小、类型这些元数据，这样资源存取与业务逻辑彻底解耦。
2.4 视频播放为什么改用 m3u8
起初我打算直接用 mp4 文件让浏览器播放。视频上传老师那边很快就暴露问题：单个实验视频动辄 1~2GB，在线播放断断续续。这是因为 MP4 是整段加载，带宽不够时体验极差。后来切换到 HLS 协议，把视频转码切分成多个 ts 分片，生成 m3u8 索引文件。播放器按需拉取分片，拖动进度条时只加载对应区间，兼容性也好。方案确定后，后端用 FFmpeg 做转码，前端用 hls.js 来播，这就把整个链路打通了。
3. 后端落地：工程结构、认证、对象存储一个不落
3.1 工程骨架与包结构设计
项目使用 Maven 构建，这一块我直接给出建议的包结构，方便复现：
edu-lab-resource/ ├── src/main/java/com/lab/resource/ │ ├── config/ # 安全配置、CORS配置、MinIO配置 │ ├── controller/ # 控制层：认证、资源、任务、报告 │ ├── entity/ # 数据库实体 │ ├── mapper/ # MyBatis-Plus Mapper │ ├── service/ # 业务接口与实现 │ │ └── impl/ │ ├── utils/ # JWT工具、MinIO工具、Result包装 │ ├── vo/ # 传给前端的视图对象 │ └── LabResourceApplication.java ├── src/main/resources/ │ ├── mapper/ # MyBatis XML │ ├── application.yml │ └── static/ # 前端打包产物最终放这里包结构的原则是看起来规整、职责清晰。特别注意：vo层和entity层不要混用。entity直接映射表结构，不再把实体直接返回前端，避免把字段全部暴露。比如用户表里有密码字段，直接序列化出去是安全问题。用 VO 做字段裁剪是必须养成的习惯。
3.2 用户认证与三端权限
登录认证用的是 Spring Security + JWT。整体流程：登录验证通过后，后端生成 JWT 返回前端，前端后续请求在Authorization头带上Bearer token，后端在过滤器里解析 token、校验签名、把用户信息放入SecurityContext。
JWT 的最大优势是服务端无状态，不需要查会话表。对于实验室系统这种体量，无状态是省事的。实现要点是密钥要放到配置文件中，过期时间建议 2 小时，前端每次请求时校验，过期后返回 401，前端统一跳转登录页。刷新 token 机制我在项目里没做，用几天后发现体验还行：管理系统使用频率不高，2 小时的有效期足够支撑一轮操作。
角色权限上分了三档：ADMIN、TEACHER、STUDENT。接口层用@PreAuthorize做控制，比如：
@GetMapping("/resources") @PreAuthorize("hasAnyRole('ADMIN', 'TEACHER')") public Result<?> listResources() { // 资源列表 }学生端访问资源上传接口会被直接拦掉，这是第一道闸。页面上还要再控制一次，前端通过动态路由决定用户能看到哪些菜单，详情路由部分再细说。
3.3 MinIO 集成：从上传到预览的完整链路
MinIO 集成到 SpringBoot 的步骤非常固定，跟着下面走一遍基本不会出错。
第一步，引入依赖：
<dependency> <groupId>io.minio</groupId> <artifactId>minio</artifactId> <version>8.5.7</version> </dependency>第二步，写配置类读取 yml 参数：
minio: endpoint: http://192.168.1.100:9000 access-key: labadmin secret-key: labpass123456 bucket: lab-resource@Configuration public class MinioConfig { @Bean public MinioClient minioClient(@Value("${minio.endpoint}") String endpoint, @Value("${minio.access-key}") String accessKey, @Value("${minio.secret-key}") String secretKey) { return MinioClient.builder() .endpoint(endpoint) .credentials(accessKey, secretKey) .build(); } }第三步，封装工具类，主要提供四个方法：判断 bucket 是否存在、上传文件、生成预签名 URL、删除文件。
有一个重点容易被忽略：预签名 URL 的expiry时间设置。教学资源要求学生在一个学期内能反复查看，预签名 URL 默认几小时就过期了，学生第二天打开视频发现播放不了，体验很差。我后来改成桶策略允许匿名读取资源对象，bucket 内只存教学资源，没有敏感数据，所以这种做法安全风险可以接受。如果是内部项目或者文件涉及隐私，就必须用预签名 URL 并配合合理的过期策略。
文件上传时，前端用multipart/form-data传文件，后端接收：
@PostMapping("/upload") public Result<?> upload(@RequestParam("file") MultipartFile file, @RequestParam("bizType") String bizType) { String originalFilename = file.getOriginalFilename(); String suffix = originalFilename.substring(originalFilename.lastIndexOf(".")); String objectName = bizType + "/" + UUID.randomUUID().toString().replace("-", "") + suffix; // 调用 MinIO 工具实现 upload }这里注意，对象名不要用原始文件名直传，很容易造成重名覆盖。我用 UUID 重命名，原始文件名存到数据库的元数据字段，展示的时候用中文原始名，存储层用 UUID 名。这样既避免了文件名冲突，还能防止文件名里带特殊字符导致 URL 解析出问题。
3.4 视频转 m3u8 和 HLS 播放链路
视频模块是这套系统里最复杂的一块。服务端流程是：上传视频 → 后台异步转码 → 生成 m3u8 和 ts 分片 → 更新资源状态 → 前端可播。
转码用的 FFmpeg，在服务器上装好并配置好 PATH。Java 里通过ProcessBuilder调用命令行：
ffmpeg -i input.mp4 -codec copy -start_number 0 -hls_time 10 -hls_list_size 0 -f hls output.m3u8参数含义说一下：-codec copy表示不重新编码，直接复用源视频编码，转码速度最快，几乎不损失质量；-hls_time 10设置每个 ts 分片时长 10 秒；-hls_list_size 0表示生成的 m3u8 索引包含所有分片。用-codec copy有个坏处：如果源文件本身编码不规范，生成的分片可能在兼容性上有问题，我在实践里因为大部分录屏软件生成的视频编码都正常，所以一直没有遇到异常。
转码是耗时操作，必须做异步处理。我在项目里用线程池@Async，上传视频后立即返回"上传成功，转码中"的状态，转码完成后回调更新状态。不用 MQ 的原因很简单——实验室系统规模没有到需要消息队列的程度，线程池足够且运维成本低。
前端拿到 m3u8 地址后，用 hls.js 播放，这个细节前端部分展开讲。容易踩坑的是跨域问题：m3u8 文件和 ts 分片都存储在 MinIO 上，如果播放页面域名和 MinIO 域名不一致，请求会触发浏览器跨域策略。千万记住要给 MinIO 配置 CORS 规则，否则前端播放器会莫名其妙地报网络错误。
4. 前端实践：Vue 环境、动态路由、m3u8 播放器与上传
4.1 Vue 工程初始化：版本和环境是第一步
Vue 项目搭建前，Node.js 版本就得先坑你一把。Vue3 + Vite 构筑，Node 版本至少 16+，推荐 18 LTS。Node 版本太高有时也会出怪问题（比如 OpenSSL 相关的 hash 报错），Node 16 和 18 之间来回切的情况并不少见。做这类项目，我建议直接用 nvm 管理 Node 版本，需要一个项目配一个版本。
初始化命令：
npm create vue@latest选择 Vue 3、Router、Pinia，其余按需。这一步直接把工程骨架建好，省去手动集成 vue-router 和状态库的工作。装完依赖后，先跑一遍npm run dev确认脚手架可用，再动手写业务代码。
4.2 动态路由：让不同角色看到不同菜单
动态路由是管理系统的刚需。管理后台的菜单分三类：管理员全菜单、教师菜单（资源上传、任务发布、报告批改）、学生菜单（资源浏览、任务列表、我的报告）。如果路由是写死的，学生在浏览器地址栏手动输入/admin/users也能进到页面。所以前端路由必须和后端权限配合。
做法分两步。第一步，静态路由只保留/login和/404；第二步，用户登录后，后端根据角色返回菜单权限列表，前端用router.addRoute()动态注册。
// 登录后动态注册路由 const permissionRoutes = generateRoutes(userInfo.roles) // 根据角色生成路由表 permissionRoutes.forEach(route => router.addRoute(route)) router.replace('/')路由参数这块有个小坑：addRoute之后要用router.replace而不是router.push，否则地址栏可能不会刷新。另一个坑：退出登录时，要把动态注册的路由全部移除，否则下一个账号登录时路由就重复了。我的做法是维护一个registeredRouteNames数组，退出时遍历删除。
4.3 m3u8 视频播放：免安装播放器的集成
浏览器原生不支持 m3u8 格式，必须借助 hls.js。它的原理是用 JavaScript 去拉 m3u8 索引，再通过 MSE（Media Source Extensions）把 ts 分片包装成浏览器能播的流。用户不需要安装任何插件，只要浏览器支持 MSE 就能看，主流浏览器都满足。
集成代码很简单：
import Hls from 'hls.js' function createVideoPlayer(videoElement, src) { if (Hls.isSupported()) { const hls = new Hls() hls.loadSource(src) hls.attachMedia(videoElement) } else if (videoElement.canPlayType('application/vnd.apple.mpegurl')) { videoElement.src = src // Safari 原生支持 } }关键判断逻辑是Hls.isSupported()，支持则用 hls.js，不支持则回退原生播放。Safari 上 HLS 是原生支持不依赖 hls.js 的，这个分支一定要保留。
小细节：由于播放器跨域请求 m3u8 容易出问题，MSE 模式下浏览器对跨域请求管理比较严格，服务器端的 CORS 头和Access-Control-Allow-Origin必须配好。
4.4 大文件上传与在线预览方案
教学资源里有 PPT、PDF、图片、压缩包等类型。上传组件我用的是 Element Plus 的el-upload，后端接口就是第 3.3 节写的那个。大文件场景下Multipartfile直接上传容易出现超时，建议前端配合分片上传，逻辑是：将文件按固定大小切片，逐片上传，全部完成后再发起合并请求。后端合并的接口简单但有个细节容易忽略——合并顺序，客户端必须按索引排序切片，后端才能正确拼接。
预览方案是分文件类型处理的：图片直接URL.createObjectURL预览；PDF 用浏览器内置的 iframe 预览；Word/PPT 这类 Office 文档没有办法完全免安装预览，除非引入在线预览服务，不然就做成下载后本地打开。我在系统里实现了图片和 PDF 的在线预览，Office 文档则统一走下载接口，并把文件名改成原始中文名，方便老师拿到手直接用。
4.5 前端构建与资源目录合并
开发阶段前后端分离跑，部署阶段要把前端打包产物塞进 SpringBoot 的static目录，这样只需要部署一个后端服务，省去配 Nginx。做法分三步：
第一步，前端配置，在vite.config.js里设置base: './'，这样构建出来的资源路径是相对路径，避免子路径部署时资源加载 404。
第二步，构建：
npm run build产物在dist目录。第三步，把dist下的文件复制到后端工程的src/main/resources/static/里，重新打包后端 jar。
这个方案的坑在路由：前端是 SPA，刷新页面时请求路径是/resources/list之类的前端路由，后端没有这个 Controller，会返回 404。解决办法是加一个转发规则，把非/api开头的路径全部转发到index.html：
@Controller public class SpaForwardController { @RequestMapping(value = {"/", "/resources/**", "/task/**", "/report/**", "/personal/**"}) public String forward() { return "forward:/index.html"; } }可以直白理解：前端路由涉及的路径都要走这个转发，否则部署后一刷新就白屏。这个坑几乎每个前后端合并部署的项目都会踩一次，我写出来帮读者直接避掉。
5. 部署前必须解决的几个环境与配置问题
5.1 端口和 Context Path 冲突
SpringBoot 默认端口 8080，如果服务器上已经跑着别的 Java 服务，直接冲突。我在application.yml里统一改成：
server: port: 8090 servlet: context-path: /context-path保持根路径，原因是前端资源里的 API 地址写了很多相对路径，加前缀会导致全部请求 404。改端口还好，加前缀是给自己挖坑，所以特地说一句尽量别动context-path。
5.2 跨域配置：开发环境和生产环境分开处理
开发环境前端跑在 5173（Vite 默认），后端跑在 8090，端口不一样就存在跨域问题。解决方案有两种。简单粗暴的方式是后端开启 CORS：
@Configuration public class CorsConfig implements WebMvcConfigurer { @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/api/**") .allowedOriginPatterns("*") .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS") .allowCredentials(true) .maxAge(3600); } }生产环境因为前端资源合并在后端了，不走跨域。但视频播放时 MinIO 域名和系统域名不同，仍然会跨域，所以 MinIO 那边的 CORS 还是要配好。一句话总结：跨域配置不是部署完就一劳永逸的事，要分开发和生产两个场景各自排查。
5.3 自动装配和版本兼容的那些事
网络搜索热度很高的 "springboot 版本太高" 恰恰是新手最容易踩的坑。现在 SpringBoot 3.x 已经很成熟了，但它有几个特性要注意。SpringBoot 3 要求 JDK 17 起步，如果你服务器还是 JDK 8，那就老老实实选 SpringBoot 2.7.x，不要盲目上 3.x。
另一个细节是，SpringBoot 2.x 时代默认 AOP 代理可以切换 JDK 动态代理和 CGLIB；到了新版，默认强制使用 CGLIB，不允许proxyTargetClass=false的配置。如果你在代码里手动实现接口希望用 JDK 动态代理，新版会直接报错。这个变化影响不大，但查 bug 时会非常困惑——你以为是代理配置错了，实际是版本默认行为变了。
还有 MyBatis 的兼容：SpringBoot 3.x 必须用mybatis-plus-spring-boot3-starter，用旧的 2.x starter 会直接启动失败。这类兼容问题排查成本不低，建议建项目时就用一个简洁的骨架项目把所有依赖版本先组合验证通过，再做业务开发。
5.4 MinIO 资源地址的内外网问题
实验室系统经常在校园网内使用，部署的服务器可能有两个 IP：内网 IP 和外网映射地址。MinIO 配置的 endpoint 写内网 IP，那么外网用户访问系统时，视频播放器拿到的 m3u8 地址就是http://内网IP:9000/...，外网用户点开直接超时。
我的处理方式是：通过系统参数保存一个resourceBaseUrl配置，在生成资源访问地址时拼上这个前缀。内网部署时填内网 IP，外网部署时填公网域名。配置跟随环境走，不要把 IP 硬编码在代码里。
6. 上线后复盘的几个关键优化点
6.1 资源搜索与分类：别等资源多了再补
最初版本做资源列表时只做了简单的按分类筛选，结果测试阶段老师上传了两百多条资源后，找一条资料要翻好多页。后来补了关键字搜索，索引了标题、简介、标签三个字段，效果立竿见影。建议初始版本就把全文检索做进去，不要等数据量上来了再补，补的时候还要处理存量数据，更麻烦。
6.2 视频转码队列的状态反馈
线程池做异步转码后，前端只显示"转码中"三个字，但转码失败的视频会一直卡在转码中。做了一个定时任务，每分钟检查一次长时间处于转码中的资源，再结合 FFmpeg 进程的实际退出码，对失败任务进行标记，并给上传教师一个失败原因提示。这算是异步操作里最容易被忽视的部分——异步不等于撒手不管，状态机的闭环必须完整。
6.3 文件命名的前后一致性
上传文件时数据库存的是 UUID 文件名，但前端列表展示的是原始文件名。下载接口里重新拼回原始文件名，需要把原始名也存到数据库。有段时间我没有存原始名，下载接口的统一下载文件命名都是乱码。后来在resource表里加了original_name字段，一次性补齐所有历史数据。凡是涉及文件上传的系统，这个字段在最开始就应该设计进去。
6.4 安全细节：密码与接口防护
密码存储用的 BCrypt 加密，这个没有商量余地。JWT 密钥不要写在代码里，放到application.yml并通过环境变量覆盖。另外所有写操作接口都加了@PreAuthorize校验，只允许 TEACHER 和 ADMIN 角色调用。学生的角色只保留读权限和自身报告提交权限。接口安全设计必须从一开始就做到位，等项目上线后再补权限体系会累得多。
7. 复用与扩展的几条建议
这套系统的设计思路可以非常自然地扩展成其他方向。比如改成实验预约管理系统，只需要在现有用户体系上增加场地和实验项目表，再加上预约状态机；改成课程资源管理系统，把资源分类的维度从"实验"换成"课程"即可。SpringBoot 加 Vue 的优势在这里体现得很明显：业务要扩展时，后端加一张表、一组接口，前端加一个菜单、一套页面，就能完成一个新模块。
如果要继续优化，下一步值得做的事情有三个方向：一是给资源上传增加断点续传能力，老师上传大视频时体验提升明显；二是给实验报告增加在线批注功能，这需要引入富文本编辑器或 PDF 批注插件；三是把成绩统计做可视化报表，前端接 ECharts 就能实现，工作量不大但反馈最好。
最后补充一点个人感受：技术选型和功能设计只是系统开发的一部分，真正决定项目成败的是对真实使用场景的理解。实验室的老师需要的是快速上传、学生需要的是丝滑播放、管理员需要的是稳定省心。做系统时把这几个平衡点抓住，比堆砌再多炫技功能都管用。
