从零搭建三明档案管理系统：SpringBoot + Vue3 全栈实战指南
一、环境准备与项目初始化
确保你的开发环境满足以下要求，这是项目能正常运行的前提。
1.1 开发环境配置
安装并配置以下软件，版本号必须完全匹配以避免兼容性问题。
- JDK 17.0.8 (Oracle或OpenJDK均可)
- Node.js 18.17.0
- MySQL 8.0.33
- Maven 3.8.6
验证安装是否成功，在命令行中分别执行以下命令：
``` java -version node -v mysql --version mvn -v ```每个命令都应正确返回对应的版本号信息。
1.2 创建数据库
使用MySQL命令行或图形化工具，按顺序执行以下SQL语句。
``` CREATE DATABASE sanming_archive DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE sanming_archive; CREATE TABLE archive_category ( id INT PRIMARY KEY AUTO_INCREMENT, category_name VARCHAR(100) NOT NULL, parent_id INT DEFAULT 0, sort_order INT DEFAULT 0, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, INDEX idx_parent (parent_id) ); CREATE TABLE archive_file ( id INT PRIMARY KEY AUTO_INCREMENT, file_name VARCHAR(255) NOT NULL, original_name VARCHAR(255) NOT NULL, file_path VARCHAR(500) NOT NULL, file_size BIGINT NOT NULL, category_id INT NOT NULL, upload_user VARCHAR(50) NOT NULL, upload_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP, description TEXT, INDEX idx_category (category_id), FOREIGN KEY (category_id) REFERENCES archive_category(id) ON DELETE CASCADE ); ```注意：必须按顺序执行，先创建数据库，再创建表。
二、后端SpringBoot服务开发
使用Spring Initializr快速生成项目骨架。
2.1 创建SpringBoot项目
访问 https://start.spring.io，按以下参数配置：
- Project: Maven
- Language: Java
- Spring Boot: 3.1.3
- Group: com.sanming
- Artifact: archive-system
- Dependencies: Spring Web, Spring Data JPA, MySQL Driver
点击Generate下载项目压缩包，解压后导入到你的IDE中。
2.2 配置数据库连接
打开src/main/resources/application.properties文件，清空原有内容，替换为以下完整配置：
``` server.port=8080 spring.application.name=sanming-archive-system 数据库配置 spring.datasource.url=jdbc:mysql://localhost:3306/sanming_archive?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai spring.datasource.username=root spring.datasource.password=你的数据库密码 spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver JPA配置 spring.jpa.hibernate.ddl-auto=update spring.jpa.show-sql=true spring.jpa.properties.hibernate.format_sql=true spring.jpa.database-platform=org.hibernate.dialect.MySQL8Dialect 文件上传配置 spring.servlet.multipart.max-file-size=100MB spring.servlet.multipart.max-request-size=100MB 跨域配置（开发时使用，生产环境需调整） spring.web.resources.static-locations=classpath:/static/ ```将"你的数据库密码"替换为你MySQL的实际root密码。
2.3 创建实体类和数据访问层
在src/main/java/com/sanming/archive/entity目录下创建ArchiveFile.java：
``` package com.sanming.archive.entity; import jakarta.persistence.; import java.util.Date; @Entity @Table(name = "archive_file") public class ArchiveFile { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Integer id; private String fileName; private String originalName; private String filePath; private Long fileSize; private Integer categoryId; private String uploadUser; @Temporal(TemporalType.TIMESTAMP) private Date uploadTime; private String description; // 省略getter和setter方法（实际开发中必须生成） } ```在相同目录下创建ArchiveCategory.java实体类，结构类似。然后创建对应的Repository接口：
``` package com.sanming.archive.repository; import com.sanming.archive.entity.ArchiveFile; import org.springframework.data.jpa.repository.JpaRepository; import java.util.List; public interface ArchiveFileRepository extends JpaRepository2.4 实现文件上传控制器
创建src/main/java/com/sanming/archive/controller/FileController.java：
``` package com.sanming.archive.controller; import com.sanming.archive.entity.ArchiveFile; import com.sanming.archive.repository.ArchiveFileRepository; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.beans.factory.annotation.Value; import org.springframework.web.bind.annotation.; import org.springframework.web.multipart.MultipartFile; import java.io.File; import java.io.IOException; import java.util.Date; import java.util.UUID; @RestController @RequestMapping("/api/files") @CrossOrigin(origins = "http://localhost:3000") public class FileController { @Value("${file.upload-dir:./uploads}") private String uploadDir; @Autowired private ArchiveFileRepository fileRepository; @PostMapping("/upload") public ArchiveFile uploadFile( @RequestParam("file") MultipartFile file, @RequestParam("categoryId") Integer categoryId, @RequestParam("description") String description) { // 创建上传目录 File dir = new File(uploadDir); if (!dir.exists()) { dir.mkdirs(); } // 生成唯一文件名 String originalName = file.getOriginalFilename(); String fileExt = originalName.substring(originalName.lastIndexOf(".")); String fileName = UUID.randomUUID().toString() + fileExt; // 保存文件 File dest = new File(dir, fileName); try { file.transferTo(dest); } catch (IOException e) { throw new RuntimeException("文件保存失败", e); } // 保存到数据库 ArchiveFile archiveFile = new ArchiveFile(); archiveFile.setOriginalName(originalName); archiveFile.setFileName(fileName); archiveFile.setFilePath(dest.getAbsolutePath()); archiveFile.setFileSize(file.getSize()); archiveFile.setCategoryId(categoryId); archiveFile.setUploadUser("admin"); // 实际应从登录信息获取 archiveFile.setUploadTime(new Date()); archiveFile.setDescription(description); return fileRepository.save(archiveFile); } @GetMapping("/list/{categoryId}") public List三、前端Vue3界面开发
使用Vite创建Vue3项目，这是目前最快的构建工具。
3.1 创建Vue3项目
打开命令行，进入你希望创建项目的目录，执行：
``` npm create vue@latest ```按照提示进行配置：
- Project name: archive-frontend
- TypeScript: No
- JSX: No
- Vue Router: Yes
- Pinia: Yes
- Vitest: No
- Cypress: No
- ESLint: Yes
- Prettier: Yes
创建完成后，进入项目目录并安装依赖：
``` cd archive-frontend npm install npm install axios element-plus ```3.2 配置Element Plus和axios
修改src/main.js文件：
``` import { createApp } from 'vue' import App from './App.vue' import router from './router' import ElementPlus from 'element-plus' import 'element-plus/dist/index.css' import axios from 'axios' // 配置axios基础URL axios.defaults.baseURL = 'http://localhost:8080/api' const app = createApp(App) app.use(router) app.use(ElementPlus) app.config.globalProperties.$axios = axios app.mount('app') ```3.3 实现文件上传组件
创建src/views/Upload.vue文件：
```档案文件上传
将文件拖到此处，或点击上传
3.4 配置路由
修改src/router/index.js文件，添加上传页面的路由：
``` import { createRouter, createWebHistory } from 'vue-router' import Upload from '../views/Upload.vue' const router = createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes: [ { path: '/', redirect: '/upload' }, { path: '/upload', name: 'upload', component: Upload } ] }) export default router ```四、系统部署与测试
完成开发后，需要启动前后端服务进行测试。
4.1 启动后端服务
在SpringBoot项目根目录（包含pom.xml的目录）执行：
``` mvn spring-boot:run ```看到以下日志表示启动成功：
``` Started ArchiveSystemApplication in 3.456 seconds ```4.2 启动前端服务
在Vue项目根目录（包含package.json的目录）执行：
``` npm run dev ```看到以下输出表示启动成功：
``` VITE v4.4.9 ready in 320 ms ➜ Local: http://localhost:5173/ ```4.3 功能测试
打开浏览器访问 http://localhost:5173，按顺序测试：
- 选择文件分类：在下拉框中选择"行政档案"
- 填写描述：在文本框中输入"2023年度工作总结"
- 选择文件：点击上传区域，选择任意PDF或Word文档
- 开始上传：点击"开始上传"按钮，看到成功提示
- 验证数据：登录MySQL查看archive_file表，确认数据已保存
- 验证文件：检查项目根目录下的uploads文件夹，确认文件已保存
4.4 生产环境部署
前后端分别打包，使用Nginx进行部署：
后端打包：
``` mvn clean package -DskipTests ```生成的jar包在target目录下，使用java -jar命令运行。
前端打包：
``` npm run build ```生成的静态文件在dist目录下，配置Nginx指向该目录。
Nginx配置示例（/etc/nginx/conf.d/archive.conf）：
``` server { listen 80; server_name archive.yourdomain.com; location / { root /path/to/archive-frontend/dist; try_files $uri $uri/ /index.html; } location /api { proxy_pass http://localhost:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } ```重启Nginx服务：
``` sudo systemctl reload nginx ```五、常见问题解决
遇到问题时，按以下步骤排查：
5.1 数据库连接失败
检查MySQL服务是否启动：
``` sudo systemctl status mysql ```检查数据库用户权限：
``` mysql -u root -p GRANT ALL PRIVILEGES ON sanming_archive. TO 'root'@'localhost'; FLUSH PRIVILEGES; ```5.2 文件上传失败
检查上传目录权限：
``` chmod 755 ./uploads ```检查磁盘空间：
``` df -h ```5.3 跨域问题
如果前端访问后端API出现跨域错误，确保后端CorsConfig配置正确：
``` @Configuration public class CorsConfig { @Bean public WebMvcConfigurer corsConfigurer() { return new WebMvcConfigurer() { @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/api/") .allowedOrigins("http://localhost:5173") .allowedMethods("GET", "POST", "PUT", "DELETE") .allowCredentials(true); } }; } } ```至此，你已经完成了一个完整的三明档案管理系统的基础版本。这个系统包含了文件上传、分类管理、数据库存储等核心功能。后续可以根据实际需求添加用户管理、权限控制、文件检索、版本管理等功能模块。
相关文章
