当前位置：首页 > news >正文

Java 全栈 Devs【应用】：用Spring Boot、MinIO 实现文件上传存储，结合 OnlyOffice 实现文件预览

news 2025/11/8 7:46:11

文件的上传、存储和预览是常见的需求。Java Spring Boot 作为一个强大的开发框架，结合 MinIO（高性能对象存储服务）进行文件存储，再搭配 OnlyOffice（强大的在线文档编辑和预览工具）实现文件预览，能为用户提供出色的文件管理体验。下面就为大家详细介绍如何实现这一套完整的功能。

环境准备

Java 开发环境：确保你已经安装了 Java 8 及以上版本，并且配置好了环境变量。如果你对 Java 环境搭建不太熟悉，可以参考 Java 官方安装指南进行操作。
Spring Boot：可以使用 Spring Initializr（https://start.spring.io/ ）来快速创建一个 Spring Boot 项目，添加 Spring Web 和 Spring Boot DevTools 依赖。Spring Initializr 是一个非常便捷的工具，它能帮助我们快速生成项目骨架，你可以在官网详细了解其使用方法。
MinIO：MinIO 是一个高性能的对象存储服务，兼容亚马逊 S3 云存储服务接口，非常适合存储海量的非结构化数据。可以通过 Docker 快速部署 MinIO，使用以下命令：

docker run -p 9000:9000 -p 9001:9001 \--name minio \-e "MINIO_ROOT_USER=minioadmin" \-e "MINIO_ROOT_PASSWORD=minioadmin" \quay.io/minio/minio server /data --console-address ":9001"

关于 MinIO 更详细的部署说明，你可以参考 MinIO 官方文档，里面有各种环境下的部署方式和详细配置说明。

OnlyOffice：OnlyOffice 是一款功能强大的在线文档编辑和预览工具，支持多种文件格式。同样可以使用 Docker 部署，onlyoffice尽量使用9.03后的版本，可以预加载字体，提高第一次预览速度。命令如下：

docker run -i -t -d -p 80:80 --restart=always onlyoffice/documentserver

若你想深入了解 OnlyOffice 的部署和使用，可查阅 OnlyOffice 官方文档，其中包含了不同操作系统和环境下的部署指南。也可以看我之前的几篇文章：Java 全栈 Devs【工具】：文件编辑预览-OnlyOffice的安装及使用

一、实现文件上传到 MinIO

添加 MinIO 依赖 在 pom.xml 中添加 MinIO 依赖：

<dependency><groupId>io.minio</groupId><artifactId>minio</artifactId><version>8.5.4</version>
</dependency>

添加依赖后，Maven 会自动从中央仓库下载 MinIO 的相关库文件，方便我们在项目中使用 MinIO 的功能。

配置 MinIO 客户端 创建一个配置类来初始化 MinIO 客户端：

import io.minio.MinioClient;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class MinioConfig {@Value("${minio.endpoint}")private String endpoint;@Value("${minio.accessKey}")private String accessKey;@Value("${minio.secretKey}")private String secretKey;@Beanpublic MinioClient minioClient() {return MinioClient.builder().endpoint(endpoint).credentials(accessKey, secretKey).build();}
}

在这个配置类中，我们使用 @Value 注解从配置文件中读取 MinIO 的端点、访问密钥和秘密密钥，然后通过 MinioClient.builder() 方法构建 MinIO 客户端实例。这样做的好处是可以将配置信息和代码分离，方便后续的维护和修改。

实现文件上传接口 创建一个控制器来处理文件上传请求：

import io.minio.MinioClient;
import io.minio.PutObjectArgs;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;import java.io.InputStream;@RestController
public class FileUploadController {@Autowiredprivate MinioClient minioClient;@PostMapping("/upload")public String uploadFile(@RequestParam("file") MultipartFile file) {try {String bucketName = "my-bucket";String objectName = file.getOriginalFilename();InputStream inputStream = file.getInputStream();long size = file.getSize();// 创建存储桶（如果不存在）if (!minioClient.bucketExists(bucketName)) {minioClient.makeBucket(bucketName);}// 上传文件PutObjectArgs putObjectArgs = PutObjectArgs.builder().bucket(bucketName).object(objectName).stream(inputStream, size, -1).contentType(file.getContentType()).build();minioClient.putObject(putObjectArgs);return "文件上传成功！";} catch (Exception e) {e.printStackTrace();return "文件上传失败！";}}
}

在这个控制器中，我们使用 @PostMapping 注解定义了一个 /upload 的 POST 请求接口，用于接收前端传来的文件。在处理文件上传时，首先检查存储桶是否存在，如果不存在则创建一个新的存储桶，然后使用 PutObjectArgs 构建上传参数，最后调用 minioClient.putObject() 方法将文件上传到 MinIO 中。

二、实现文件预览（结合 OnlyOffice）

获取文件访问链接（推荐） 在 MinIO 中获取文件的访问链接，方便 OnlyOffice 访问：

import io.minio.MinioClient;
import io.minio.GetPresignedObjectUrlArgs;
import io.minio.http.Method;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;import java.util.concurrent.TimeUnit;@RestController
public class FilePreviewController {@Autowiredprivate MinioClient minioClient;@GetMapping("/preview-url")public String getPreviewUrl(@RequestParam("fileName") String fileName) {try {String bucketName = "my-bucket";GetPresignedObjectUrlArgs args = GetPresignedObjectUrlArgs.builder().method(Method.GET).bucket(bucketName).object(fileName).expiry(1, TimeUnit.HOURS).build();return minioClient.getPresignedObjectUrl(args);} catch (Exception e) {e.printStackTrace();return null;}}
}

这里我们使用 @GetMapping 注解定义了一个 /preview-url 的 GET 请求接口，用于获取文件的预签名 URL。预签名 URL 是一种临时的、有有效期的访问链接，通过设置 expiry 参数可以控制链接的有效期，提高文件访问的安全性。

2、使用nginx代理文件路径（推荐）

当然如果你可以使用预访问文件、或者设置桶为共有使用nginx代理、nginx做文件缓存，会更快哦

使用预访问文件
优点：提前对文件进行处理，生成可预览的格式。在用户请求预览时，直接返回处理好的文件，这样可以大大提高预览速度，尤其对于频繁被预览的文件，能显著提升用户体验。
缺点：需要额外的存储空间来存储处理后的文件，增加了存储成本。而且对于实时更新的文件，需要及时更新处理后的文件，否则会出现预览内容与实际文件不一致的情况。
安装部署要点：需要搭建专门的文件处理服务，用于将文件转换为可预览格式。该服务要与 Spring Boot 应用和 MinIO 存储进行集成，确保处理后的文件能正确存储到 MinIO 中，并且在用户请求时能准确返回。
设置桶为共有并通过 nginx 代理文件预览路径
优点：
提高预览效率：将 MinIO 中的存储桶设置为共有，外部可以直接访问桶内的文件。配置 nginx 来代理文件预览路径，当用户发起文件预览请求时，nginx 将请求转发到 MinIO 存储桶中的文件地址，避免了文件的多次传输，减少了网络延迟，从而提高了预览速度。
可靠性高：nginx 的高性能和稳定性也能保证预览服务的可靠性。
缺点：
安全风险：将桶设置为共有会使桶内文件直接暴露在网络中，存在一定的安全风险，需要配合其他安全措施，如 IP 访问限制、访问认证等。
配置复杂度：nginx 的配置需要一定的专业知识，配置不当可能导致预览服务无法正常工作。
安装部署要点：
MinIO 桶设置：在 MinIO 客户端中，通过相应的 API 来修改桶的访问策略，使其变为公开可读。
nginx 配置：以下是一个简单的 nginx 配置示例：

server {listen 80;server_name your-preview-domain.com;location /preview/ {proxy_pass http://your-minio-server:9000/your-bucket-name/;proxy_set_header Host $host;proxy_set_header X-Real-IP $remote_addr;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;}
}

确保 nginx 服务器能正常访问 MinIO 服务器，并且将请求正确转发。

三、前端集成onlyoffice实现步骤

在前端页面中引入 OnlyOffice 的脚本，并使用获取到的文件访问链接进行文件预览：

<!DOCTYPE html>
<html lang="en">
<head><meta charset="UTF-8"><title>文件预览</title><script type="text/javascript" src="http://your-onlyoffice-server/web-apps/apps/api/documents/api.js"></script>
</head>
<body><div id="placeholder"></div><script type="text/javascript">var docEditor = new DocsAPI.DocEditor("placeholder", {"document": {"fileType": "docx","key": "example-key","title": "Example Document","url": "http://your-minio-server/my-bucket/example.docx"},"editorConfig": {"mode": "view","lang": "en"}});</script>
</body>
</html>

在这个前端页面中，我们引入了 OnlyOffice 的 API 脚本，然后通过 DocsAPI.DocEditor 方法创建一个文档编辑器实例。在 document 对象中，我们指定了文件的类型、唯一键、标题和访问 URL，在 editorConfig 对象中，我们设置了预览模式和语言。这样，当页面加载时，OnlyOffice 就会根据提供的 URL 加载文件并进行预览。

通过以上步骤，我们使用 Java Spring Boot 实现了文件上传到 MinIO 的功能，并且结合 OnlyOffice 实现了文件的在线预览。这种方案不仅可以提高文件存储的可靠性和性能，还能为用户提供便捷的文件预览体验。

一起呱唧呱唧下