SpringBoot3+Vue3+AI实战：构建非遗数字化管理系统全栈项目

前几年做文化遗产相关的数字化项目时团队反复在“传统管理功能”和“智能化内容运营”之间摇摆。如果只做一套普通的增删改查后台非遗数据只是被简单存储无法真正形成传播和利用价值可如果一开始就引入复杂的 AI 能力又容易让项目陷入环境配置和接口联调的泥潭。本文围绕“非物质文化遗产系统”这个典型场景完整梳理一条 SpringBoot Vue3 AI 的落地路线。从需求分析、环境准备、后端接口、前端页面到 AI 助手接入、文件上传以及常见问题排查都会给出可复制的代码和配置。适合正在做文化类管理系统、智慧文旅项目或者想用 SpringBoot Vue3 AI 练手完整的全栈开发者。通过本文你可以掌握一套能直接扩展的“非遗数据管理 AI 辅助运营”项目骨架。1. 非遗数字化管理系统背景与选型思考1.1 非遗管理系统要解决什么问题非物质文化遗产涵盖民间文学、传统技艺、传统戏剧、民俗活动等门类这些内容天然具有“资料多、形式杂、地域性强、传承人信息分散”的特点。过去很多地方通过纸质档案或 Excel 管理存在几个比较明显的问题数据格式不统一图片、视频、音频、文档散落在不同电脑里。检索困难想查某个地区有哪些非遗项目需要人工翻档案。缺乏对外展示窗口公众很难方便地了解本地非遗资源。内容运营成本高项目简介、讲解词、多语言介绍需要人工编写。所以非遗系统的核心价值不只是“把数据存进数据库”而是围绕非遗项目的全生命周期提供录入、审核、存储、检索、展示、传播一体化的能力。1.2 为什么选择 SpringBoot Vue3 AI技术选型可以从团队熟悉度、项目规模、长期维护三个角度考虑。后端选择 SpringBoot是因为它在 Java 生态中足够成熟。内置 Tomcat、自动配置、丰富的 Starter让开发者可以把更多精力放在业务代码上。SpringBoot 3.x 基于 Spring Framework 6支持 Jakarta EE 规范适合新项目起步。前端选择 Vue3是因为组合式 APIComposition API让逻辑复用更灵活配合 Vite 的开发体验也确实比传统 Webpack 方案轻快很多。对于后台管理系统、内容展示页这类中后台场景Vue3 Element Plus 基本是社区中资料最全的组合之一。引入 AI主要是为了降低内容运营成本。比如根据非遗项目的名称和标签自动生成一段介绍文案。把项目简介翻译成多语言版本。为管理员提供“非遗知识助手”可以基于项目资料回答问题。AI 不是替代人工审核而是辅助创作者完成初稿、整理摘要、统一文风最终仍需要人工确认后发布。1.3 整体功能规划为了让项目可控本文把系统拆成几个功能模块模块功能说明非遗项目管理非遗项目的增删改查、分类管理、状态审核传承人管理传承人基本信息、所属项目、关联文档资源文件管理图片、视频、音频、PDF 等文件上传与下载内容展示面向公众的项目列表、项目详情页AI 助手基于项目资料的知识问答、介绍文案生成系统管理用户登录、角色权限、日志记录视项目需要扩展实际业务中还可以加入地图展示、申报流程管理本文先聚焦核心链路方便读者在现有骨架上继续扩展。2. 环境准备与项目初始化2.1 后端环境本教程的示例代码以后端 SpringBoot 3.x、前端 Vue3 为基础。版本需要根据你的项目实际情况调整下面给出的是常见的稳定组合环境版本建议JDK17 或 21SpringBoot3.2.x / 3.3.xMySQL8.0 及以上Maven3.8 及以上Node.js18 及以上包管理器npm 或 pnpm如果已经安装 JDK17直接使用 SpringBoot 3.x 就能正常启动。如果项目历史包袱较重还在用 JDK8那建议先升级运行环境或者继续选择 SpringBoot 2.7.x但要注意 2.x 版本已经逐步进入维护末期。2.2 前端环境前端使用 Vite 创建 Vue3 项目需要提前安装 Node.js。国内网络环境下如果 npm 安装依赖较慢可以配置淘宝镜像npm config set registry https://registry.npmmirror.com检查 Node 和 npm 版本node -v npm -v2.3 数据库准备建议在 MySQL 中单独创建非遗系统数据库命名尽量与项目一致。例如CREATE DATABASE IF NOT EXISTS heritagedb DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;使用 utf8mb4 是因为非遗项目名称、简介、传承人故事等字段可能需要存储生僻字或特殊符号utf8mb4 编码支持更完整。3. SpringBoot 后端核心配置3.1 创建 SpringBoot 工程与依赖在 IDEA 中新建 SpringBoot 工程时选择 Spring Web、MySQL Driver、Lombok 等依赖。如果创建工程时网络超时可以检查 IDEA 的 HTTP Proxy 设置或者先通过 Spring Initializr 下载压缩包再导入。核心pom.xml依赖如下重点是 MyBatis-Plus 和文件上传相关支持dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.5/version /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency dependency groupIdcom.github.ulisesbocchio/groupId artifactIdjasypt-spring-boot-starter/artifactId version3.0.5/version /dependency /dependenciesMyBatis-Plus 的目的是简化单表 CRUD避免重复编写 Mapper XML。Jasypt 用于配置文件敏感信息加密后文会单独介绍。3.2 application.yml 配置详解在src/main/resources/application.yml中完成数据源、MyBatis-Plus、文件上传、AI 接口等配置。server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/heritagedb?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalse username: root password: ENC(xxx) # 使用 jasypt 加密后填入 servlet: multipart: max-file-size: 2048MB max-request-size: 2048MB sql: init: mode: always schema-locations: classpath:schema.sql continue-on-error: false mybatis-plus: configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl global-config: db-config: id-type: auto # 文件上传本地存储目录 file: upload-dir: D:/heritage-files/ # AI 大模型接口配置按实际服务商填 ai: base-url: https://api.example.com/v1 api-key: ${AI_API_KEY} model: deepseek-chat timeout: 30这里有几个关键点需要解释spring.sql.init.modealways配合schema-locations可以在应用启动时自动执行建表 SQL。注意生产环境中建议只在首次初始化时开启或者改成never由 DBA 统一维护。server.servlet.multipart配置了上传大小限制非遗项目视频通常较大按需调整。ai.api-key使用${AI_API_KEY}环境变量注入不要把真实密钥写死在 yml 中。map-underscore-to-camel-case开启后数据库下划线字段可以自动映射为 Java 驼峰属性减少大量手工映射。3.3 MyBatis-Plus 自动建表实现网上经常有人问“MyBatis-Plus 能不能像 JPA 那样自动建表”。MyBatis-Plus 本身并没有提供完善的实体类扫描建表功能更稳妥的做法是通过 Spring Boot 的 SQL 初始化机制执行schema.sql使用CREATE TABLE IF NOT EXISTS保证重复启动不会报错。在src/main/resources/schema.sql中定义非遗项目表CREATE TABLE IF NOT EXISTS heritage_project ( id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT 主键ID, project_name VARCHAR(200) NOT NULL COMMENT 项目名称, category VARCHAR(50) COMMENT 项目类别, region VARCHAR(100) COMMENT 所属地区, level VARCHAR(20) COMMENT 级别国家级/省级/市级/县级, inheritance_people VARCHAR(500) COMMENT 传承人, description_text TEXT COMMENT 项目描述, cover_url VARCHAR(500) COMMENT 封面图地址, status TINYINT DEFAULT 0 COMMENT 状态0草稿 1待审核 2已发布 3已下架, create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT 创建时间, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 更新时间, deleted TINYINT DEFAULT 0 COMMENT 逻辑删除 ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT非遗项目表;注意这张表使用了逻辑删除字段deleted配合 MyBatis-Plus 的TableLogic注解可以避免物理删除造成的数据不可恢复。4. Vue3 前端工程搭建4.1 创建 Vue3 项目使用 Vite 创建一个 Vue3 项目npm create vitelatest heritage-web -- --template vue cd heritage-web npm install安装路由、状态管理、UI 组件库和 HTTP 工具npm install vue-router4 pinia element-plus axios4.2 配置 Vite 代理开发环境下前端访问/api路径时希望转发到后端localhost:8080同时避免跨域问题。在vite.config.js中配置代理import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], server: { port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } })这样一来前端请求/api/heritage/list就会自动转发到http://localhost:8080/api/heritage/list。后端接口统一以/api开头既方便代理配置也为后续网关接入做好铺垫。4.3 前端目录结构设计实际项目中建议按功能模块划分目录而不是把所有组件平铺在components下heritage-web/ ├── src/ │ ├── api/ # 接口请求封装 │ │ ├── request.js │ │ ├── heritage.js │ │ └── ai.js │ ├── views/ │ │ ├── heritage/ │ │ │ ├── HeritageList.vue │ │ │ └── HeritageDetail.vue │ │ ├── ai/ │ │ │ └── AiAssistant.vue │ │ └── Dashboard.vue │ ├── router/ │ │ └── index.js │ ├── store/ │ │ └── user.js │ ├── components/ │ └── main.js └── package.json分层思路是页面组件只负责视图渲染业务数据请求放到api目录跨页面共享状态放到 Pinia。5. 非遗核心业务模块实战5.1 非遗项目实体与表结构设计后端实体类与数据库表对应使用 Lombok 简化代码。新建com.example.heritage.entity.HeritageProjectpackage com.example.heritage.entity; import com.baomidou.mybatisplus.annotation.*; import lombok.Data; import java.time.LocalDateTime; Data TableName(heritage_project) public class HeritageProject { TableId(type IdType.AUTO) private Long id; private String projectName; private String category; private String region; private String level; private String inheritancePeople; private String descriptionText; private String coverUrl; private Integer status; TableField(fill FieldFill.INSERT) private LocalDateTime createTime; TableField(fill FieldFill.INSERT_UPDATE) private LocalDateTime updateTime; TableLogic TableField(select false) private Integer deleted; }TableLogic逻辑删除注解非常实用它让 MyBatis-Plus 在执行删除操作时自动改成UPDATE ... SET deleted 1默认查询也会自动带上deleted 0条件。5.2 后端 CRUD 接口实现新建 Mapper 接口package com.example.heritage.mapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.example.heritage.entity.HeritageProject; import org.apache.ibatis.annotations.Mapper; Mapper public interface HeritageProjectMapper extends BaseMapperHeritageProject { }新建 Servicepackage com.example.heritage.service; import com.baomidou.mybatisplus.extension.service.IService; import com.example.heritage.entity.HeritageProject; public interface HeritageProjectService extends IServiceHeritageProject { }实现类package com.example.heritage.service.impl; import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl; import com.example.heritage.entity.HeritageProject; import com.example.heritage.mapper.HeritageProjectMapper; import com.example.heritage.service.HeritageProjectService; import org.springframework.stereotype.Service; Service public class HeritageProjectServiceImpl extends ServiceImplHeritageProjectMapper, HeritageProject implements HeritageProjectService { }Controller 中实现分页查询、新增、修改、删除、详情接口package com.example.heritage.controller; import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.example.heritage.entity.HeritageProject; import com.example.heritage.service.HeritageProjectService; import org.springframework.web.bind.annotation.*; import java.util.HashMap; import java.util.Map; RestController RequestMapping(/api/heritage) public class HeritageProjectController { private final HeritageProjectService heritageProjectService; public HeritageProjectController(HeritageProjectService heritageProjectService) { this.heritageProjectService heritageProjectService; } GetMapping(/list) public MapString, Object list(RequestParam(defaultValue 1) long current, RequestParam(defaultValue 10) long size, RequestParam(required false) String keyword) { PageHeritageProject page new Page(current, size); LambdaQueryWrapperHeritageProject wrapper new LambdaQueryWrapper(); if (keyword ! null !keyword.isEmpty()) { wrapper.like(HeritageProject::getProjectName, keyword) .or().like(HeritageProject::getRegion, keyword); } wrapper.orderByDesc(HeritageProject::getCreateTime); heritageProjectService.page(page, wrapper); MapString, Object result new HashMap(); result.put(total, page.getTotal()); result.put(records, page.getRecords()); return result; } GetMapping(/{id}) public HeritageProject detail(PathVariable Long id) { return heritageProjectService.getById(id); } PostMapping public boolean add(RequestBody HeritageProject heritageProject) { return heritageProjectService.save(heritageProject); } PutMapping(/{id}) public boolean update(PathVariable Long id, RequestBody HeritageProject heritageProject) { heritageProject.setId(id); return heritageProjectService.updateById(heritageProject); } DeleteMapping(/{id}) public boolean delete(PathVariable Long id) { return heritageProjectService.removeById(id); } }这里使用了构造器注入而不是Autowired字段注入目的是让依赖关系更明确也方便单元测试。5.3 前端列表与表单页面前端使用 Element Plus 搭建列表页核心代码在src/views/heritage/HeritageList.vuetemplate div classheritage-list el-card el-form inline el-form-item label关键词 el-input v-modelkeyword placeholder项目名称/地区 clearable / /el-form-item el-form-item el-button typeprimary clickloadList查询/el-button el-button typesuccess clickopenDialog新增项目/el-button /el-form-item /el-form el-table :datarecords border stripe el-table-column propprojectName label项目名称 min-width160 / el-table-column propcategory label类别 width120 / el-table-column propregion label地区 width120 / el-table-column proplevel label级别 width100 / el-table-column propstatus label状态 width100 template #default{ row } el-tag{{ row.status 2 ? 已发布 : 草稿 }}/el-tag /template /el-table-column el-table-column label操作 width180 template #default{ row } el-button sizesmall clickeditRow(row)编辑/el-button el-button sizesmall typedanger clickdeleteRow(row)删除/el-button /template /el-table-column /el-table el-pagination v-model:current-pagecurrent v-model:page-sizesize :totaltotal layouttotal, prev, pager, next current-changeloadList / /el-card /div /template script setup import { ref, onMounted } from vue import { ElMessage, ElMessageBox } from element-plus import { getHeritageList, deleteHeritage } from ../../api/heritage const keyword ref() const records ref([]) const current ref(1) const size ref(10) const total ref(0) async function loadList() { const res await getHeritageList({ current: current.value, size: size.value, keyword: keyword.value }) records.value res.records total.value res.total } async function deleteRow(row) { await ElMessageBox.confirm(确定删除“${row.projectName}”吗, 提示, { type: warning }) await deleteHeritage(row.id) ElMessage.success(删除成功) loadList() } onMounted(loadList) /scriptscript setup是 Vue3 组合式 API 的推荐写法代码更简洁变量和方法直接在模板中使用。接口封装文件src/api/heritage.jsimport request from ./request export function getHeritageList(params) { return request.get(/heritage/list, { params }) } export function deleteHeritage(id) { return request.delete(/heritage/${id}) }request.js基于 Axios 封装统一处理 baseURL、token 和错误提示。至此非遗数据管理模块的最小闭环已经跑通前端列表请求 → 后端接口查询 → 查询结果回显。接下来继续加入 AI 能力让系统不只是“档案管理系统”。6. AI 能力接入非遗智能助手6.1 AI 模块设计思路AI 在非遗系统里可以做什么日常使用最多的三个场景介绍文案生成输入项目名称、类别、地区生成用于公众号或官网展示的简介。知识问答管理员可以直接向 AI 询问“本地有哪些传统技艺类项目”AI 基于项目资料回答。多语言翻译将非遗简介翻译成英文、日文等版本方便对外文化交流。设计上AI 模块应该与业务模块解耦。后端提供一个统一的 AI 代理接口内部封装大模型 HTTP 调用前端只需要与后端通信不直接暴露模型 API Key。6.2 大模型接口封装为了不绑定特定厂商 SDK这里使用 SpringBoot 自带的RestTemplate调用兼容 OpenAI 格式的 HTTP 接口。创建一个AiAssistantServicepackage com.example.heritage.service; import org.springframework.beans.factory.annotation.Value; import org.springframework.http.*; import org.springframework.stereotype.Service; import org.springframework.web.client.RestTemplate; import java.util.*; Service public class AiAssistantService { private final RestTemplate restTemplate; Value(${ai.base-url}) private String baseUrl; Value(${ai.model}) private String model; Value(${ai.api-key}) private String apiKey; public AiAssistantService(RestTemplate restTemplate) { this.restTemplate restTemplate; } public String chat(String systemPrompt, String userContent) { String url baseUrl /chat/completions; MapString, Object body new HashMap(); body.put(model, model); ListMapString, String messages new ArrayList(); messages.add(Map.of(role, system, content, systemPrompt)); messages.add(Map.of(role, user, content, userContent)); body.put(messages, messages); HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); headers.setBearerAuth(apiKey); HttpEntityMapString, Object request new HttpEntity(body, headers); ResponseEntityMap response restTemplate.exchange(url, HttpMethod.POST, request, Map.class); if (response.getBody() ! null) { ListMap choices (ListMap) response.getBody().get(choices); if (choices ! null !choices.isEmpty()) { Map message (Map) choices.get(0).get(message); return String.valueOf(message.get(content)); } } throw new RuntimeException(AI 接口返回异常); } }这段代码虽然看起来长但逻辑很清晰构造请求体、设置鉴权头、发送 POST 请求、解析返回内容。只要大模型服务商提供 OpenAI 兼容接口都可以通过修改ai.base-url、ai.api-key、ai.model来切换。再写一个 Controller 暴露给前端调用RestController RequestMapping(/api/ai) public class AiAssistantController { private final AiAssistantService aiAssistantService; public AiAssistantController(AiAssistantService aiAssistantService) { this.aiAssistantService aiAssistantService; } PostMapping(/generate-intro) public MapString, String generateIntro(RequestBody MapString, String payload) { String projectName payload.get(projectName); String category payload.get(category); String region payload.get(region); String systemPrompt 你是一名非物质文化遗产保护领域的资深编辑擅长撰写客观、准确、有文化底蕴的项目介绍。; String userContent String.format(请为以下非遗项目写一段200字左右的介绍。名称%s类别%s地区%s。要求语言正式突出文化价值。, projectName, category, region); String content aiAssistantService.chat(systemPrompt, userContent); MapString, String result new HashMap(); result.put(content, content); return result; } }6.3 前端 AI 对话组件前端在src/views/ai/AiAssistant.vue中实现一个简单的对话面板template div classai-assistant el-card template #header非遗 AI 助手/template div classchat-box div v-for(msg, index) in messages :keyindex classchat-item div classchat-role{{ msg.role user ? 我 : AI }}/div div classchat-content{{ msg.content }}/div /div /div el-input v-modelinputValue typetextarea :rows3 placeholder请输入你的问题例如帮我生成一个龙泉青瓷的项目介绍 / el-button typeprimary stylemargin-top: 10px clicksendMessage发送/el-button /el-card /div /template script setup import { ref } from vue import { generateIntro } from ../../api/ai const messages ref([]) const inputValue ref() async function sendMessage() { if (!inputValue.value.trim()) return messages.value.push({ role: user, content: inputValue.value }) const payload { projectName: inputValue.value, category: 传统技艺, region: 浙江 } try { const res await generateIntro(payload) messages.value.push({ role: ai, content: res.content }) } catch (e) { messages.value.push({ role: ai, content: AI 服务调用失败请检查配置 }) } inputValue.value } /script style scoped .chat-box { height: 400px; overflow-y: auto; border: 1px solid #eee; border-radius: 6px; padding: 12px; margin-bottom: 10px; } .chat-item { margin-bottom: 12px; } .chat-role { font-weight: bold; font-size: 14px; } /style6.4 AI 能力的安全与合规建议接入大模型后有几件事一定要提前考虑API Key 安全密钥不要放入前端代码也不要提交到 Git 仓库建议使用环境变量或密钥管理服务。内容审核AI 生成内容必须经过管理员审核后才能发布不能直接自动公开。可以在状态字段中增加“AI 待审核”状态。提示词约束系统提示词中应明确要求模型避免生成违法违规、民族歧视、地域歧视内容。限流控制对 AI 接口做调用频率限制避免被恶意刷量导致成本失控。数据脱敏不要把用户手机号、身份证号等敏感个人信息拼接到提示词中。非遗内容涉及传统文化和地域信息尤其要注意介绍的准确性。AI 生成初稿可以降低工作量但最终对外输出前必须由熟悉该非遗项目的人员确认。7. 文件上传与资源管理7.1 本地存储方案非遗项目包含大量图片、视频和音频文件。项目早期可以使用本地磁盘存储减少运维成本等文件量增大后再迁移到云存储或 MinIO。本地存储思路很简单后端接收MultipartFile保存到配置的文件目录同时返回可访问的 URL。7.2 上传下载接口新建FileController.javapackage com.example.heritage.controller; import org.springframework.beans.factory.annotation.Value; import org.springframework.core.io.Resource; import org.springframework.core.io.UrlResource; import org.springframework.http.*; import org.springframework.web.bind.annotation.*; import org.springframework.web.multipart.MultipartFile; import java.io.File; import java.io.IOException; import java.net.MalformedURLException; import java.nio.file.Path; import java.nio.file.Paths; import java.time.LocalDate; import java.time.format.DateTimeFormatter; import java.util.UUID; RestController RequestMapping(/api/file) public class FileController { Value(${file.upload-dir}) private String uploadDir; PostMapping(/upload) public String upload(RequestParam(file) MultipartFile file) throws IOException { File dir new File(uploadDir); if (!dir.exists()) { dir.mkdirs(); } String datePath LocalDate.now().format(DateTimeFormatter.ofPattern(yyyy/MM/dd)); File targetDir new File(uploadDir, datePath); if (!targetDir.exists()) { targetDir.mkdirs(); } String originalFilename file.getOriginalFilename(); String ext originalFilename ! null ? originalFilename.substring(originalFilename.lastIndexOf(.)) : ; String filename UUID.randomUUID() ext; file.transferTo(new File(targetDir, filename)); return /files/ datePath / filename; } GetMapping(/download/{datePath}/{filename}) public ResponseEntityResource download(PathVariable String datePath, PathVariable String filename) throws MalformedURLException { Path filePath Paths.get(uploadDir, datePath, filename).normalize(); Resource resource new UrlResource(filePath.toUri()); if (!resource.exists()) { return ResponseEntity.notFound().build(); } return ResponseEntity.ok() .header(HttpHeaders.CONTENT_DISPOSITION, attachment; filename\ filename \) .contentType(MediaType.APPLICATION_OCTET_STREAM) .body(resource); } }上传接口返回的路径是相对路径实际访问时需要把静态资源目录映射到/files/**。可以在配置类中添加资源映射器package com.example.heritage.config; import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; Configuration public class WebConfig implements WebMvcConfigurer { Value(${file.upload-dir}) private String uploadDir; Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/files/**) .addResourceLocations(file: uploadDir); } }7.3 前端上传组件Element Plus 的el-upload组件可以直接对接后端接口el-upload action/api/file/upload :headersuploadHeaders :on-successhandleUploadSuccess list-typepicture-card el-iconPlus //el-icon /el-upload如果上传超大视频文件本地方案仍然可行但需要关注两点一是调整 Nginx 或 Tomcat 的上传大小限制二是前端增加进度条展示避免用户误以为页面卡死。涉及大文件断点续传、分片上传等更复杂方案后续可以单独用一篇文章深入拆解。8. 常见问题与排查思路8.1 常见问题排查表问题现象常见原因解决思路SpringBoot 项目启动失败提示端口被占用8080端口被其他进程占用使用netstat -ano查找占用进程或修改server.port创建 SpringBoot 项目超时IDEA 无法访问 Spring Initializr使用阿里云镜像或者手动下载工程包前端请求接口报跨域错误前端地址与后端地址不一致使用 Vite 代理解决或后端配置 CORSschema.sql执行报错SQL 语法与 MySQL 版本不匹配检查 MySQL 版本确认 SQL 语句兼容性上传文件提示超出大小限制spring.servlet.multipart配置过小调整配置文件中的max-file-size与max-request-sizeAI 接口报 401API Key 错误或已过期检查环境变量确认密钥有效AI 接口返回超时模型推理较慢或网络原因增加RestTemplate超时时间或使用流式响应8.2 SpringBoot 版本太高导致依赖不兼容不少开发者使用最新版 SpringBoot 时发现某些第三方 Starter 还停留在旧版本会出现自动配置不生效、类找不到等异常。遇到这种情况建议先锁定一个稳定版本组合而不是盲目追求最新版。例如 SpringBoot 3.2.x 搭配 MyBatis-Plus 3.5.x 是经过大量项目验证的。8.3 Vue3 项目在浏览器中的显示问题有读者反馈 Vue3 项目在 Edge 浏览器中偶尔出现按钮无法点击、页面渲染异常的情况。多数时候是浏览器插件或 Service Worker 缓存导致可以先尝试无痕模式验证。如果无痕模式正常则清理浏览器缓存和站点数据如果无痕模式仍异常则需要检查代码中是否存在浏览器兼容性较强的 API。8.4 删除数据失败或被“莫名过滤”使用TableLogic逻辑删除后所有查询都会自动附加deleted 0条件。如果删除了数据但列表中仍然能看到可以检查实体类上deleted字段的映射是否生效。另一个注意点是如果存在自定义 SQL需要手动拼接逻辑删除条件MyBatis-Plus 无法自动处理 XML 中的查询。8.5 配置项太多如何排查当配置不生效时推荐方法是在启动日志中查看自动配置的报告SpringBoot 启动时开启 debug 模式就能看到哪些配置生效、哪些没有生效。也可以在测试类中注入Environment打印具体配置值判断是配置读取失败还是逻辑写错。9. 工程实践与安全建议9.1 命名与分层规范后端建议按controller / service / mapper / entity / dto / config分包Controller 只做参数接收和结果封装Service 层承载业务逻辑避免在 Controller 中堆 SQL 或调用多个 Service。前端组件采用“页面 业务组件 通用组件”的层次。9.2 配置安全SpringBoot yml 密文项目中不可避免地要在配置文件中写入数据库密码、AI API Key、OSS 密钥等敏感信息。直接明文写在 yml 里一旦代码仓库泄露后果会很严重。前面在 pom.xml 中引入了 Jasypt这里演示如何加密配置项。首先在本地生成一个加密后的值。可以通过 Jasypt 提供的命令行工具也可以启动时通过JasyptPBEStringEncryptionOperator生成。更简单的做法是写一个临时测试类package com.example.heritage; import org.jasypt.encryption.pbe.StandardPBEStringEncryptor; import org.junit.jupiter.api.Test; public class JasyptTest { Test public void encrypt() { StandardPBEStringEncryptor encryptor new StandardPBEStringEncryptor(); encryptor.setPassword(your-salt); encryptor.setAlgorithm(PBEWithMD5AndDES); String encrypted encryptor.encrypt(root123456); System.out.println(encrypted); } }把输出的加密串填入application.ymlspring: datasource: password: ENC(加密串)启动时通过环境变量传入盐值java -jar heritage-system.jar -Djasypt.encryptor.passwordyour-salt需要注意的是Jasypt 只是提高了配置泄露的门槛并不能替代密钥管理服务。生产环境更推荐使用 Vault、KMS 或云厂商的密钥管理能力。9.3 日志与性能优化非遗系统涉及大量文件资源性能优化重点在文件处理和数据查询访问量大的项目列表接口建议增加 Redis 缓存减少数据库压力。上传图片时可以在前端或后端生成缩略图列表页展示缩略图而不是原图。AI 接口的响应时间通常较长前端发起请求时提示“正在生成中”后端可以改为异步任务生成完成后通过 WebSocket 或轮询通知前端。日志记录不要只记成功也要记录 AI 调用失败、上传失败等异常场景。建议使用 SLF4J 门面生产环境关闭 SQL 日志输出。9.4 数据备份与生产发布涉及数据库删除、修改的接口生产环境必须遵循最小权限原则。管理员账号不应该拥有 DBA 权限业务账号只授予库表级别必要的增删改查权限。每次发布前至少完成一次数据库备份并准备好回滚方案。对于非遗这样的文化遗产数据珍贵程度远高于普通业务数据我更建议核心数据表开启 binlog 或定期全量备份。文件资源做异地备份。删除操作尽可能使用逻辑删除保存完整链路记录。对外发布的信息增加审核流程避免错误内容造成不良影响。10. 总结与下一步本文从非遗数字化管理系统的实际需求出发构建了一套完整的 SpringBoot Vue3 AI 项目骨架。核心内容包括通过 SpringBoot 3.x 搭建后端服务使用 MyBatis-Plus 简化 CRUD结合 schema.sql 实现启动时自动建表通过 Vue3 Vite Element Plus 搭建管理端页面实现非遗项目列表、新增、删除和 AI 对话通过统一的大模型 HTTP 封装把 AI 能力接入了非遗介绍文案生成场景同时覆盖了文件上传下载、常见问题排查和工程安全建议。下一步可以继续扩展的方向包括引入 Redis 缓存热点数据使用 Elasticsearch 优化全文检索增加基于地图的非遗资源展示开发游客端 H5 页面以及将 AI 模块升级为流式输出并建立非遗专属知识库。业务越复杂越要先把基础分层和配置安全做好再逐步叠加能力。如果你正在规划类似的非遗或文化资源类系统建议先不要急着堆砌功能而是把“一条数据从录入到发布的完整链路”跑通再按优先级扩展。把业务问题拆成可验证的小模块是落地这类系统最有效的方式。