基于SpringBoot和MinIO搭建电子公文管理系统实战

一、技术选型与架构说明

本指南将构建一个具备文件上传、安全存储、元数据管理及在线预览功能的电子公文管理系统。为了确保零门槛落地且具备企业级扩展性，我们采用以下技术栈：

• Spring Boot 2.7+：核心开发框架，提供快速开发能力。
• MinIO：高性能对象存储，用于存储OFD、PDF等公文文件，兼容S3协议。
• kkFileView：基于Java的文件预览服务，支持Office、PDF、OFD等格式在线预览。
• MySQL 8.0：存储公文元数据（如文件名、上传人、存储路径等）。
• MyBatis Plus：简化数据库操作。

二、环境准备与容器启动

在开始编码前，需先准备好基础存储和数据库服务。我们使用Docker快速部署MySQL、MinIO和kkFileView。请确保你的服务器已安装Docker和Docker Compose。

1. 启动MySQL数据库

执行以下命令创建MySQL容器，设置root密码为123456，并创建名为edoc_system的数据库：

```bash docker run -d \ --name mysql-edoc \ -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=123456 \ -e MYSQL_DATABASE=edoc_system \ mysql:8.0 ```

2. 启动MinIO对象存储

MinIO用于存储实际的公文文件。执行以下命令启动MinIO，控制台端口为9001，API端口为9000：

```bash docker run -d \ --name minio-edoc \ -p 9000:9000 \ -p 9001:9001 \ -e "MINIO_ROOT_USER=admin" \ -e "MINIO_ROOT_PASSWORD=admin123456" \ minio/minio server /data --console-address ":9001" ``>

启动后，访问 http://localhost:9001 登录MinIO控制台，手动创建一个名为 official-docs 的Bucket（存储桶），并将访问权限设置为Public或Read。

3. 启动kkFileView预览服务

执行以下命令启动kkFileView，该服务将监听8012端口：

```bash docker run -d \ --name kkfileview \ -p 8012:8012 \ keking/kkfileview:4.1.0 ``>

三、数据库表结构设计

我们需要一张表来记录公文的元数据。请在MySQL的edoc_system数据库中执行以下SQL：

```sql CREATE TABLE `doc_info` ( `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID', `doc_title` varchar(255) NOT NULL COMMENT '公文标题', `original_name` varchar(255) NOT NULL COMMENT '原始文件名', `file_type` varchar(20) NOT NULL COMMENT '文件类型：pdf,ofd,docx', `file_size` bigint(20) DEFAULT NULL COMMENT '文件大小（字节）', `object_name` varchar(500) NOT NULL COMMENT 'MinIO中的对象名称（存储路径）', `bucket_name` varchar(100) DEFAULT 'official-docs' COMMENT '存储桶名称', `uploader` varchar(50) DEFAULT NULL COMMENT '上传人', `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='电子公文信息表'; ```

四、Spring Boot项目构建

创建一个Spring Boot项目，修改pom.xml，引入必要的依赖。请确保版本号兼容。

1. Maven依赖配置

```xml org.springframework.boot spring-boot-starter-web com.baomidou mybatis-plus-boot-starter 3.5.3.1 mysql mysql-connector-java 8.0.33 io.minio minio 8.5.2 org.projectlombok lombok true cn.hutool hutool-all 5.8.20 ```

2. 应用配置文件

在src/main/resources/application.yml中配置数据库连接、MinIO连接信息及预览服务地址：

```yaml server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/edoc_system?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai username: root password: 123456 MinIO配置 minio: endpoint: http://localhost:9000 accessKey: admin secretKey: admin123456 bucketName: official-docs kkFileView配置 preview: baseUrl: http://localhost:8012/onlinePreview ```

五、核心功能代码实现

以下代码包含配置类、实体类、Mapper层、Service层和Controller层，复制即可运行。

1. MinIO配置类

该类用于初始化MinIO客户端实例。

```java package com.edoc.config; import io.minio.MinioClient; import lombok.Data; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Data @Configuration @ConfigurationProperties(prefix = "minio") public class MinioConfig { private String endpoint; private String accessKey; private String secretKey; private String bucketName; @Bean public MinioClient minioClient() { return MinioClient.builder() .endpoint(endpoint) .credentials(accessKey, secretKey) .build(); } } ```

2. 实体类

```java package com.edoc.entity; import com.baomidou.mybatisplus.annotation.IdType; import com.baomidou.mybatisplus.annotation.TableId; import lombok.Data; import java.time.LocalDateTime; @Data public class DocInfo { @TableId(type = IdType.AUTO) private Long id; private String docTitle; private String originalName; private String fileType; private Long fileSize; private String objectName; private String bucketName; private String uploader; private LocalDateTime createTime; } ```

3. Mapper接口

```java package com.edoc.mapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.edoc.entity.DocInfo; import org.apache.ibatis.annotations.Mapper; @Mapper public interface DocInfoMapper extends BaseMapper { } ```

4. 核心业务逻辑

包含上传文件和获取预览URL的逻辑。注意：上传文件时会生成唯一的UUID作为文件名存储到MinIO，防止文件名冲突。

```java package com.edoc.service; import com.edoc.config.MinioConfig; import com.edoc.entity.DocInfo; import com.edoc.mapper.DocInfoMapper; import io.minio.MinioClient; import io.minio.PutObjectArgs; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Service; import org.springframework.web.multipart.MultipartFile; import cn.hutool.core.io.FileUtil; import cn.hutool.core.util.IdUtil; import cn.hutool.core.util.StrUtil; import java.io.InputStream; import java.time.LocalDateTime; @Service public class DocService { @Autowired private MinioClient minioClient; @Autowired private MinioConfig minioConfig; @Autowired private DocInfoMapper docInfoMapper; @Value("${preview.baseUrl}") private String previewBaseUrl; / 上传公文并保存元数据 / public String uploadDoc(MultipartFile file, String docTitle, String uploader) throws Exception { String originalFilename = file.getOriginalFilename(); String suffix = FileUtil.getSuffix(originalFilename); // 生成新的存储文件名 String objectName = IdUtil.simpleUUID() + "." + suffix; // 上传到MinIO try (InputStream inputStream = file.getInputStream()) { minioClient.putObject( PutObjectArgs.builder() .bucket(minioConfig.getBucketName()) .object(objectName) .stream(inputStream, file.getSize(), -1) .contentType(file.getContentType()) .build() ); } // 保存元数据到数据库 DocInfo docInfo = new DocInfo(); docInfo.setDocTitle(docTitle); docInfo.setOriginalName(originalFilename); docInfo.setFileType(suffix); docInfo.setFileSize(file.getSize()); docInfo.setObjectName(objectName); // 拼接完整的文件访问URL，供kkFileView下载使用 String fileUrl = minioConfig.getEndpoint() + "/" + minioConfig.getBucketName() + "/" + objectName; docInfo.setUploader(uploader); docInfo.setCreateTime(LocalDateTime.now()); docInfoMapper.insert(docInfo); return "上传成功，文件ID: " + docInfo.getId(); } / 获取预览URL / public String getPreviewUrl(Long docId) { DocInfo docInfo = docInfoMapper.selectById(docId); if (docInfo == null) { throw new RuntimeException("文档不存在"); } // 构造MinIO文件完整下载地址 String fileUrl = minioConfig.getEndpoint() + "/" + minioConfig.getBucketName() + "/" + docInfo.getObjectName(); // kkFileView通过url参数接收文件地址 return previewBaseUrl + "?url=" + StrUtil.utf8UrlEncode(fileUrl); } } ```

5. 控制器层

```java package com.edoc.controller; import com.edoc.service.DocService; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.; import org.springframework.web.multipart.MultipartFile; @RestController @RequestMapping("/api/doc") public class DocController { @Autowired private DocService docService; / 上传接口 / @PostMapping("/upload") public String upload(@RequestParam("file") MultipartFile file, @RequestParam("docTitle") String docTitle, @RequestParam(value = "uploader", defaultValue = "admin") String uploader) { try { return docService.uploadDoc(file, docTitle, uploader); } catch (Exception e) { e.printStackTrace(); return "上传失败: " + e.getMessage(); } } / 获取预览地址接口 / @GetMapping("/preview/{id}") public String preview(@PathVariable Long id) { return docService.getPreviewUrl(id); } } ```

六、实操测试与验证

项目启动后，我们使用curl命令模拟文件上传和预览请求。准备一个名为test.pdf的测试文件放在当前目录下。

1. 测试文件上传

执行以下命令上传文件，公文标题设为“2023年度技术报告”：

```bash curl -F "file=@test.pdf" \ -F "docTitle=2023年度技术报告" \ -F "uploader=ZhangSan" \ http://localhost:8080/api/doc/upload ``>

成功返回示例：上传成功，文件ID: 1。请记住返回的ID（假设为1）。

2. 测试在线预览

使用上一步获取的ID访问预览接口：

```bash curl http://localhost:8080/api/doc_preview/1 ``>

命令行会返回一长串URL，例如：

http://localhost:8012/onlinePreview?url=http%3A%2F%2Flocalhost%3A9000%2Fofficial-docs%2Fa1b2c3d4.pdf

直接复制该URL到浏览器中访问。 如果一切配置正确，你将看到kkFileView的加载界面，随后显示PDF文件的内容，支持翻页、缩放等操作。

七、常见问题排查

• MinIO连接超时： 检查Docker容器是否正常运行，使用docker logs minio-edoc查看日志，确认application.yml中的端口配置与Docker映射一致。
• kkFileView预览失败（下载失败）： kkFileView服务需要能访问到MinIO的文件地址。如果是本地测试，确保MinIO的Endpoint配置为http://localhost:9000或局域网IP，不要配置为127.0.0.1，因为Docker容器内的127.0.0.1指向容器自身而非宿主机。
• 中文文件名乱码： 代码中已使用StrUtil.utf8UrlEncode对URL进行编码，确保kkFileView能正确解析中文路径。