最近有朋友问我搞一套线上历史馆藏系统信息管理系统要多久。我直接把之前整理好的源码翻了出来SpringBoot后端Vue前端MySQL三件套齐全数据库脚本、初始化数据、部署说明全都配好了拿到就能跑。这套系统不是什么大厂级的复杂平台但对博物馆、档案馆、文化馆这类机构来说日常藏品登记、检索、出入库、借展管理完全够用。这篇文章不打算讲故事就从代码和实操出发把系统里最核心的设计思路、表结构、接口、前端页面、启动步骤和踩坑点全部过一遍适合正在做馆藏类管理系统、或者刚接触前后端分离项目的同学参考。1. 系统整体设计与业务模型1.1 馆藏系统到底要管什么先说业务。线上历史馆藏系统说白了就是把馆里的实物藏品搬到线上管理。核心对象是“藏品”每条藏品记录通常包含藏品编号、名称、时代、类别、材质、尺寸、重量、完残情况、来源、存放位置、入库时间、影像资料、当前状态等。状态要能区分在库、出库、修复中、借展中否则后面统计就会乱。我见过很多半成品系统就是把增删改查套到一张表上看似能跑但真用起来一堆问题。比如藏品编号没有规则、图片和档案没法关联、出入库记录不完整、操作没有日志。这些问题一旦上线就会很被动。所以这套源码在设计时把“台账管理”和“流程记录”拆开藏品表负责当前状态业务流水表负责历史轨迹查询时再关联起来。馆藏系统的用户角色也值得多说一句。管理员负责系统配置、账号管理和数据维护普通工作人员负责日常登记和出入库操作安保或盘点人员可能只需要查询权限。这种情况下如果只做一个admin账号后面审计就会很麻烦。所以这套源码从一开始就规划了用户、角色、权限三层模型而不是把所有功能堆在一个页面上。1.2 技术选型的理由为什么用SpringBoot Vue MySQL我直接说结论这是目前做管理类系统最稳的组合。SpringBoot生态成熟做后端接口效率很高而且打包成jar就能直接部署Vue前端负责交互页面拆成组件后维护成本低MySQL则用来存结构化数据配合关系表很容易管理藏品、用户、日志这些实体之间的关系。有人可能会问为什么不用PHP或者Python不是说不行而是考虑到后续的二次开发和招聘成本。这套系统面向的是博物馆、学校、文化机构开发人员可能换了一茬又一茬SpringBoot无论是社区资料、代码规范还是人才储备都是最稳妥的。Vue同样是这个逻辑。前端选Vue3 Vite Element Plus目录清晰组件化开发后边加页面也快。说到版本我建议后端用SpringBoot 2.7.x不要一上来追最新3.x。3.x虽然新但有些第三方库的兼容性还需要时间沉淀对这类管理项目来说稳定比版本新鲜更重要。前端Vue3搭配Vite开发启动速度比Webpack快很多打包产物也更干净。MySQL选8.0窗口函数和JSON字段以后都可能用到从5.7升级上来的成本也不高。1.3 数据库设计的关键表数据库我拆了7张核心表sys_user 用户表、sys_role 角色表、sys_user_role 用户角色关联表、collection_info 藏品信息表、collection_inout 出入库记录表、collection_repair 修复记录表、operation_log 操作日志表。这里我把角色做成单独的表而不是直接在用户表里写一个role字段原因是权限体系以后会扩展而且“用户-角色”是多对多关系。先看collection_info表。字段大概是这样collection_id主键自增collection_no藏品编号唯一索引我建议用“馆代码类别代码年份序号”生成比如HC-CL-2024-001title藏品名称category藏品类别用字典值如书画、陶瓷、古籍、青铜、杂项dynasty年代如明代、清代、新石器时代material材质size_desc尺寸描述weight重量condition_status完残情况用字典source来源信息location存放位置storage_time入库时间status当前状态0在库、1出库、2修复中、3借展image_url主图路径video_url扩展的视频地址remark备注create_time、update_time这里最关键的是status字段和业务流水的配合。不能只改藏品表的status还必须在collection_inout表里写一条记录记录“谁在什么时间、把哪件藏品、从哪个位置、出库或入库、原因是什么”。这样盘点的时候才能追根溯源。我有一次帮一个单位处理系统他们的状态字段被直接UPDATE现场人员改来改去最后完全说不清楚一件藏品去哪了那就是没有流水表导致的。权限和日志也提一下。sys_user表存username、passwordBCrypt加密、real_name、phone、status。角色表和用户角色关联表用于登录后动态加载菜单和按钮权限。operation_log表存操作人、操作类型、请求URL、请求参数、IP、耗时、操作时间这个表一定要有馆藏系统很多时候需要审计追责没有日志就说不清楚。2. 后端核心模块实现与接口细节2.1 工程结构与分层代码结构上后端包名我用com.history.collection下面分controller、service、mapper、entity、config、common、security这些包。Controller只负责接收参数和返回结果Service处理业务逻辑Mapper是数据访问层。这样分的最大好处是排查问题的时候不用翻遍整个项目接口报错了先看Controller再进Service基本上10分钟内定位到问题。依赖方面核心的就这几个spring-boot-starter-web、mybatis-plus-boot-starter、mysql-connector-java、jjwt、hutool-all、poi-ooxml。MyBatis-Plus做单表CRUD和分页特别方便特别是LambdaQueryWrapper写条件查询比拼SQL字符串舒服太多了。Hutool里面有很多工具类我习惯用它处理日期和字符串省去不少重复代码。POI是用来做Excel导入导出的馆藏清单动不动几百上千条手工录入不现实。pom.xml里的版本号一定要统一。SpringBoot父工程管理了大部分依赖版本但MyBatis-Plus和POI这些还是要显式指定。我一开始吃过亏MyBatis-Plus用3.5.1SpringBoot用2.7.5两者没冲突但如果把MyBatis-Plus升到4.x就可能会出现Mapper代理类创建失败的问题。没必要追新。2.2 接口设计思路接口风格统一走RESTful返回统一结果对象ResultData里面包含code、message、data字段。code为200表示成功401表示未认证403表示无权限500表示服务端异常。所有Controller封装返回时都走ResultData.success(data)或ResultData.error(code,msg)。这样前端在axios拦截器里只要判断code就能决定是否弹出错误提示不用每个页面重复处理异常。藏品模块的接口清单如下接口路径请求方式说明是否需登录/api/auth/loginPOST登录返回token否/api/collection/listGET分页查询藏品是/api/collection/{id}GET获取藏品详情是/api/collection/addPOST新增藏品是管理员/api/collection/updatePUT修改藏品是管理员/api/collection/delete/{id}DELETE删除藏品是管理员/api/collection/exportGET导出Excel是/api/inout/listGET出入库记录是/api/collection/statsGET分类统计是权限这一块用的是JWT 自定义注解。登录成功后通过JWT把用户ID和角色ID带上后续请求在拦截器里校验token合法性解析出用户信息。再结合RequiresRole注解对接口做角色控制。比如新增藏品接口上加RequiresRole(ADMIN)只有管理员可以操作。好处是不用把权限判断写在业务代码里维护的时候只看注解就能明白。2.3 核心代码片段登录接口的标准写法大致是这样PostMapping(/login) public ResultDataLoginResponse login(RequestBody LoginRequest request) { // 1. 根据用户名查询用户 User user userMapper.selectByUsername(request.getUsername()); // 2. 校验密码 if (user null || !BCrypt.checkpw(request.getPassword(), user.getPassword())) { return ResultData.error(401, 用户名或密码错误); } // 3. 校验用户状态 if (user.getStatus() ! 1) { return ResultData.error(403, 账号已被禁用); } // 4. 生成JWT String token JwtUtil.createToken(user.getId(), user.getUsername(), user.getRoleCode()); return ResultData.success(new LoginResponse(token, user)); }这里有几个坑要提醒一下。密码加密必须用BCrypt不要用MD5。MD5现在随便一个在线网站都能撞库破解BCrypt每次生成的哈希都不一样就算是同一条密码也无法反推原文。JWT的密钥不要放在代码里硬编码我一般写到application.yml中部署的时候通过环境变量注入。token过期时间我设的是24小时馆藏系统这种内部系统可以长一点但也要有刷新机制这个看团队习惯。藏品分页查询使用MyBatis-Plus的Page对象public PageCollectionInfo getCollectionPage(int pageNum, int pageSize, String keyword, String category) { LambdaQueryWrapperCollectionInfo wrapper new LambdaQueryWrapper(); if (StringUtils.isNotBlank(keyword)) { wrapper.and(w - w.like(CollectionInfo::getTitle, keyword) .or().like(CollectionInfo::getCollectionNo, keyword)); } if (StringUtils.isNotBlank(category)) { wrapper.eq(CollectionInfo::getCategory, category); } wrapper.orderByDesc(CollectionInfo::getCreateTime); return collectionInfoMapper.selectPage(new Page(pageNum, pageSize), wrapper); }这里的关键是LambdaQueryWrapper的“表字段-实体属性”映射。MyBatis-Plus开启map-underscore-to-camel-case后数据库里的create_time会自动映射到createTime不用写一堆resultMap。分页插件也需要在配置类里加PaginationInnerInterceptor否则selectPage只会返回全部数据不生效。内网数据量不大的时候这个分页足够用了。“直接运行”要能跑数据库配置必须给到位。application.yml里面有几个核心配置后面启动时会详细讲这里先放出来server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/history_collection?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue username: root password: root driver-class-name: com.mysql.cj.jdbc.Driver mybatis-plus: mapper-locations: classpath:mapper/*.xml configuration: map-underscore-to-camel-case: true custom: jwt: secret: your-secret-key-change-me expire-hours: 24 upload-path: D:/history-collection/upload/注意url里必须带serverTimezoneAsia/Shanghai否则MySQL8会出现时区错误。useSSLfalse是因为本地跑不需要加密连接。allowPublicKeyRetrievaltrue如果不加MySQL8连接时可能报Public Key Retrieval is not allowed错误。这些在最后排查部分还会再说。3. 前端Vue页面与交互构建3.1 前端工程结构前端用Vue3 Vite Element Plus Axios Vue Router。目录结构是这样src/api放接口封装src/router放路由配置src/store是Pinia状态管理src/views放页面组件src/components放公共组件src/utils放Axios实例和工具函数。组件化以后新增一个“修复记录管理”页面只需要在views下加一个文件夹再在router里加一条路由就完事不太需要动其他已有代码。路由设计上登录页是/login主布局下挂了一堆子路由/dashboard仪表盘、/collection/list藏品列表、/collection/edit藏品编辑、/inout/record出入库记录、/user/manage用户管理、/log/list日志查询。路由守卫在router.beforeEach里统一判断token是否存在本地没有token就强制跳回登录页。这一步是最容易漏的很多新手做出来的页面直接访问路由也能看到内容那权限等于没做。为什么要用Pinia而不是VuexVuex4虽然也能配合Vue3但写法上还保留着mutations那一套很啰嗦。Pinia的store里可以直接写state和action代码量少很多TypeScript支持也更好。我在这套系统里用了Pinia存用户信息登录成功之后把user对象塞进store再配合localStorage持久化刷新页面也不掉线。3.2 Axios封装与跨域处理Axios实例需要统一配置baseURL和请求拦截器。我的封装思路是请求的时候从localStorage取出token设置到Authorization请求头响应的时候判断HTTP状态码如果是401就清空登录信息并跳转登录页其他错误统一通过ElMessage提示。这样页面上不用每个请求都try-catch一遍非常省事。// src/utils/request.js import axios from axios import { ElMessage } from element-plus import router from /router const request axios.create({ baseURL: /api, timeout: 10000 }) request.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer ${token} } return config }) request.interceptors.response.use( response { const res response.data if (res.code 200) { return res.data } if (res.code 401) { localStorage.removeItem(token) router.push(/login) } ElMessage.error(res.message || 请求失败) return Promise.reject(new Error(res.message)) }, error { ElMessage.error(error.message || 网络异常) return Promise.reject(error) } ) export default requestVite的跨域代理配置在vite.config.js里。前端跑在5173端口后端跑在8080端口开发时直接用axios请求http://localhost:8080必然跨域。最简单的办法是通过Vite代理转发。// vite.config.js export default defineConfig({ server: { port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } })这样前端页面请求/api/collection/listVite会自动转发到后端8080端口。生产部署的时候前端打包成dist目录可以直接放进Nginx再把/api反向代理到后端服务。我建议生产环境就不要再用前端代理而是用Nginx统一转发性能和可维护性都好一些。3.3 核心页面实现要点藏品列表页是重点。表格展示缩略图、编号、名称、年代、类别、状态、存放位置和操作按钮。状态列我会用Element Plus的el-tag按不同状态显示不同颜色在库绿色、出库蓝色、修复中橙色、借展紫色这样一眼就能看出库存情况。表格上方放搜索栏支持藏品名称、编号、类别筛选配合后端分页参数pageNum和pageSize。搜索功能要注意防抖。如果用户每次输入一个字符就触发一次请求数据库压力其实很小但前端渲染会有卡顿感。我习惯在搜索框的change事件里调用接口而不是在input事件里。另外重置搜索时要记得把pageNum设置成1不然当前在第5页搜索完数据变少了接口返回空列表用户一脸懵。新增/编辑藏品页面用的是el-form。这里要注意表单校验藏品编号必填且格式要匹配正则名称必填类别必须从字典下拉框选择。图片上传我用的el-upload上传完成后把返回的URL保存到表单的imageUrl字段。el-upload的action指向后端/api/upload上传接口用的MultipartFile接收文件然后把文件写到upload-path目录返回可访问的相对路径。图片访问要配置静态资源映射不然浏览器会404这个在最后一节专门说。前端访问列表数据时大概流程是页面加载时调用list接口把params传进去拿到返回的记录总数和列表数据set到表格。搜索时重置pageNum为1再重新请求。删除操作必须加二次确认对话框我习惯用ElMessageBox.confirm防止手滑把珍贵藏品记录删了。删除接口返回成功后再刷新列表同时要处理一下当前页数据被删空的场景。4. 本地环境搭建与一键启动指南4.1 环境要求这套系统要跑起来本地需要装的软件其实不多JDK1.8及以上建议8或11、Maven 3.6、Node.js 14Vite需要14以上我用的是16、MySQL 8.0以及一个数据库图形化工具Navicat或者DBeaver都可以。前端包管理我用的npm如果觉得国内网络慢可以把npm镜像切到国内镜像源。这里不展开了就是一行命令的事。版本问题我多提醒一句。JDK如果装了17SpringBoot 2.7也能跑但有些老依赖可能有点小问题。最保险的组合是JDK8 SpringBoot 2.7 MySQL8这套组合我已经验证过很多次属于闭着眼睛都能跑的版本。Node版本千万不要装最新的20Vite4和Element Plus本身没问题但有些npm包在Node20下会报openssl错误我遇到过两次。4.2 数据库初始化步骤数据库初始化是整个启动流程里的第一个坑很多人跳过去直接启动后端结果一直报找不到表。我这边已经把初始化SQL文件整理好了叫history_collection.sql。打开Navicat新建数据库字符集选utf8mb4排序规则选utf8mb4_general_ci然后右键数据库选择“运行SQL文件”把history_collection.sql导进去执行成功后会看到sys_user、collection_info这些表另外有一份初始数据里面包含一个管理员账号admin密码是admin123和测试藏品数据。也可以用命令行导入在终端里执行mysql -u root -p -e CREATE DATABASE history_collection DEFAULT CHARACTER SET utf8mb4; mysql -u root -p history_collection history_collection.sql装MySQL8的时候有两个选择容易搞错一个是root密码别设太复杂否则后面忘了连不上另一个是如果为了省事把密码设为root那application.yml里就用root。这个系统我已经在MySQL 8.0.29上测试过直接跑没问题。MySQL 5.7也能用但驱动建议换成对应的不然可能出现驱动版本不匹配。4.3 后端启动步骤后端项目用IDEA打开等Maven把依赖下载完先在File - Settings - Build Tools - Maven里检查一下JDK版本。然后修改application.yml里的数据库用户名和密码确保和本地一致。确认无误后直接运行主类HistoryCollectionApplication.java启动日志看到“Started ... in 5.24 seconds”就是成功了。如果是命令行启动可以这样mvn clean package -DskipTests java -jar target/history-collection-1.0.0.jar我自己的习惯是先mvn clean package打包成jar再java -jar运行这样能确保代码没有问题。如果启动时报端口被占用可以在application.yml里改server.port或者找到占用端口的进程结束掉。Windows下netstat -ano | findstr 8080Linux下lsof -i:8080都是常用命令。后端启动成功以后可以用浏览器直接访问接口比如打开http://localhost:8080/api/auth/login会返回405因为POST接口用GET访问。如果返回的是统一的ResultData错误信息说明SpringBoot起来了。想更直观地看接口文档可以在pom里集成springdoc然后在浏览器访问swagger-ui但这套基础版本我没默认开启因为生产环境没必要暴露接口文档。4.4 前端启动步骤前端目录打开终端先执行npm install安装依赖。这一步时间会比较长属于正常现象依赖装完后会生成node_modules目录。然后再执行npm run dev看到“VITE ready”和本地访问地址http://localhost:5173就表示前端起来了。浏览器打开该地址用admin/admin123登录就能看到系统的仪表盘和藏品列表。如果npm install报错多半是网络问题或者Node版本太低。网络问题可以设置镜像源。Node版本太低会提示Vite需要升级我建议直接用nvm管理Node版本装一个16.20.2稳妥。生产环境部署的话前端执行npm run build把生成的dist目录放到Nginx的html目录下再配置一个server块把/api请求转发到后端端口。后端jar包可以用java -jar直接跑或者注册成systemd服务实现开机自启。系统规模不大单机部署完全够了。5. 常见问题与排查技巧实录5.1 MySQL连接报错集锦我整理一下最容易遇到的几个MySQL连接报错以及处理方式“Access denied for user rootlocalhost”说明账号密码错误。检查application.yml中username和password特别要注意密码里有特殊字符时不要用中文引号。“Public Key Retrieval is not allowed”这是MySQL8驱动的一个安全策略解决办法是在JDBC连接串末尾加上allowPublicKeyRetrievaltrue。“Connection timed out”一般是MySQL服务没启动或者端口改过。先检查服务状态再看连接串的端口是否和MySQL实际端口一致。“Unknown database history_collection”说明SQL脚本没有导入或者数据库名不对。回到4.2节重新执行导入即可。我之前调试时还遇到过Swagger接口文档能打开但登录接口一直报500后来发现是驱动版本用了旧的5.x而MySQL是8.x。这个问题很隐蔽因为编译期不会报错运行时才暴露。解决方案很简单把mysql-connector-java版本升级到8.0.33。5.2 端口冲突与启动失败SpringBoot默认8080Vite默认5173。这两个端口在开发环境中被占用的概率很高。尤其是8080很多软件比如某些注册中心、终端服务都会默认占用。启动后端时报“Port 8080 was already in use”解决方法有三条杀掉占用进程Windows下输入netstat -ano | findstr 8080拿到PID后在任务管理器结束进程Linux下用kill命令。直接改后端端口把server.port改成8081但前端代理target也要同步改不然请求还是打不进去。前端如果5173端口被占Vite会自动加一变成5174这时页面访问地址是5174而不是原来的5173很多人没注意到这一点还在继续访问老地址。还有一个比较隐蔽的问题后端启动成功但接口访问返回404。这种情况多半是前端请求到了SpringBoot默认的错误页而实际上后端并没有对应的接口映射。检查一下Controller的RequestMapping路径看看是不是少了/api前缀再看前端代理路径是否一致。前后端联调时第一步永远是用Postman直连后端接口确认后端正常再去排查前端。5.3 跨域与代理配置问题前后端分离项目跨域是绕不开的话题。开发阶段用Vite代理解决了但有些项目组直接把前后端代码放到同一个服务下结果前端请求的相对路径和后端映射对不上也会出现404。我建议前端所有接口都统一以/api开头后端Controller统一加上/api前缀这样代理规则只需要一条。如果是生产环境Nginx我贴一段常用的配置server { listen 80; server_name your-domain.com; root /opt/frontend/dist; index index.html; location /api/ { proxy_pass http://127.0.0.1:8080/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }这里最容易踩的坑有两个。一个是proxy_pass的URL末尾带不带斜杠带不带会影响路径拼接我上面写的这种是带/api/的配置要一致。另一个是刷新页面出现404刷新前端路由时Nginx找不到对应的静态文件需要加try_files指令把请求都引到index.html由前端路由接管。5.4 图片上传与访问路径问题馆藏系统的图片多上传功能几乎每天都要用。后端上传接口存储文件到配置路径后前端拿到的是类似/upload/2024/10/xxx.jpg的相对路径。要让浏览器能直接访问这个路径必须在SpringBoot里配置静态资源映射。我习惯加一个WebMvcConfigurer的配置类Configuration public class WebConfig implements WebMvcConfigurer { Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/upload/**) .addResourceHandler(file: uploadPath); } }这个类不复杂但非常关键。很多人上传成功之后页面加载图片还是打不开十有八九是忘记了这行映射。Windows路径要注意正反斜杠Linux路径末尾要带斜杠。我习惯在配置里统一用/分隔Java处理时会自动转换。另外上传目录要提前创建不然后端会抛NoSuchFileException。我一般会在服务启动时检查一次目录是否存在不存在就自动创建。关于视频藏品如果后续有扩展需求可以在藏品表里加video_url字段前端用video标签直接播放mp4格式。如果要播放m3u8流媒体Vue里通常还要借助hls.js或video.js这类库但这套基础系统已经能承载。我的建议是先看实际需求不要一上来就把视频模块做复杂馆藏系统最核心的价值还是档案信息和元数据管理视频属于锦上添花。5.5 权限和登录态踩坑最后提一下权限相关的问题。不少同学跑起来登录成功后过一段时间再操作发现接口全部返回401。原因是JWT默认有过期时间而我前面设置的过期时间是24小时。如果你改了系统时间或者启动时时间与服务器时间不一致JWT的过期判断就会出现偏差。调试阶段可以先把过期时间设长一点上线前再改回合理值。还有一个容易忽略的是前端axios拦截器。登录成功后要把token保存到localStorage里但刷新页面后token还在后端接口校验时token有效这没问题。可是如果你的路由守卫只在本地存了token、没有校验接口是否真的通过那么即使token被篡改前端页面依然能访问而接口会401。所以前端路由守卫只是体验优化真正安全必须靠后端拦截器。我建议后续可以接一个“获取当前用户信息”接口在路由守卫里调用一次失败就直接清除本地信息这样前后端状态就同步了。目前这套源码里我还在两个地方做了小扩展。一个是导入功能支持用Excel模板批量导入藏品字段顺序已经固定大家在模板里按列填就行。另一个是统计功能仪表盘上按类别展示藏品的数量分布用的就是collection_info表的category字段做group by这能直观看出哪类藏品最多管理上很有用。其实代码本身并不复杂最值钱的部分是业务模型能不能贴合实际使用。我见过太多系统功能按钮一大堆但真要查“哪件藏品什么时候借给谁了”却查不出来这就是表结构设计没做好。这套源码把出入库记录独立出来把操作日志留底把权限角色分开从长期运营角度看比单纯写一堆CRUD接口重要得多。你如果接手这套代码我建议第一件事不是改功能而是先把7张表之间的关系画一遍理清了再动手。最后再分享一个小技巧在开发阶段后端打印SQL日志很有用。在application.yml中加上mybatis-plus.configuration.log-implorg.apache.ibatis.logging.stdout.StdOutImpl就能在控制台看到每一条执行的SQL。排查数据问题时效率会高很多。上线前记得把日志级别调成WARN不然数据库操作全暴露在日志里量大也占磁盘。目前这套源码我已经在本地和一台2核4G的云服务器上跑通了MySQL占用内存不算大整个服务加前端Nginx部署完内存还剩不少。如果你预算有限可以先用这套结构支撑几百件藏品的机构后续再按需要扩张。我个人建议先把这套系统跑通然后拿着表结构去套你们单位自己的业务很多时候你会发现只要把字段微调一下再加两个报表就能直接上线。后续要扩展也不难后端加接口、前端加页面骨架都是现成的。有这功夫纠结技术选型不如先把这套源码里涉及的权限、日志和出入库流程吃透这些才是馆藏系统真正值钱的地方。