Spring Boot 集成华为云 OBS 实现文件上传与预览功能

Spring Boot 集成华为云 OBS 实现文件上传与预览功能 | 极客日志

Spring Boot 集成华为云 OBS 实现文件上传与预览功能

一、背景与需求

在现代 Web 应用中，文件上传与访问是常见需求。出于安全性考虑，我们通常将文件存储在私有桶（Private Bucket）中，禁止直接公开访问。此时，需要通过预签名 URL（Presigned URL）机制临时授权用户访问特定文件。

本文将演示如何：

配置华为云 OBS 连接
限制上传文件类型
将文件上传至 OBS 并记录元数据
生成 1 小时有效的预签名 URL 用于前端预览或下载
提供后端代理式文件预览接口（解决跨域、权限控制等问题）

二、项目结构概览

com.hrm.rmhr
├── config
│   └── ObsConfig.java // OBS 配置类
├── controller
│   └── FileController.java // 文件上传、预览、删除接口
├── service
│   ├── ObsService.java // OBS 操作接口
│   └── impl/ObsServiceImpl.java // OBS 服务实现
├── entity
│   └── FileMetadata.java // 文件元数据实体
└── mapper
    └── FileMetadataMapper.java // 数据库操作

三、项目依赖（Maven）

<dependency>
    <groupId>com.huaweicloud</groupId>
    <artifactId>esdk-obs-java</artifactId>
    <version>3.22.8</version>
</dependency>

四、配置文件：application.yml

file:
  obs:
    endpoint: https://obs.cn-north-4.myhuaweicloud.com # 替换为你所在区域的 Endpoint
    ak: YOUR_ACCESS_KEY_ID # 华为云 AK（生产环境请用环境变量）
    sk: YOUR_SECRET_ACCESS_KEY # 华为云 SK
    bucket-name: your-bucket-name # OBS 桶名称
    storage-root-directory: /files/ # 存储根路径，结尾带斜杠

五、核心配置：ObsConfig

/**
 * OBS 对象存储配置
 */
@Configuration
@ConfigurationProperties(prefix = "file.obs")
@Data
public class ObsConfig {
    /**
     * OBS endpoint
     */
    private String endpoint;
    /**
     * Access Key
     */
    private String ak;
    /**
     * Secret Key
     */
    private String sk;
    /**
     * Bucket 名称
     */
    private String bucketName;
    /**
     * 存储根目录
     */
    private String storageRootDirectory;
}

注意：安全提示：AK/SK 属于敏感信息，建议通过配置中心或环境变量注入，避免硬编码。推荐使用 ${OBS_AK} 和 ${OBS_SK}。

六、文件上传逻辑

1. 安全校验

检查文件是否为空
校验文件扩展名（仅允许常见办公/图片格式）

private static final Set<String> ALLOWED_EXTENSIONS = new HashSet<>(Arrays.asList("xls", "xlsx", "doc", "docx", "pdf", "jpg", "jpeg", "png", "gif", "bmp", "txt", "csv"));

2. 调用 OBS 服务上传

使用 MultipartFile 获取输入流
构建唯一文件名（UUID + 原始名清洗）
按年月 + 分类组织存储路径（如 resume/2025/12/xxx.pdf）
保存元数据到数据库（含原始名、大小、类型、上传人、租户等）

3. 返回预签名 URL

上传成功后，立即生成一个 1 小时有效的预签名 URL，供前端直接预览或下载：

{
  "code": 200,
  "msg": "success",
  "data": {
    "url": "https://bucket.obs.cn-north-4.myhuaweicloud.com/files/resume/2025/12/xxxx?Expires=...&AccessKeyId=...&Signature=...",
    "fileId": "123"
  }
}

七、预签名 URL 生成

提供独立接口，支持按需生成不同有效期的访问链接：

@PostMapping("/generatePresignedUrl")
public Result<String> generatePresignedUrl(@RequestParam("fileId") Integer fileId, @RequestParam(value = "expirationSeconds", defaultValue = "3600") int expirationSeconds)

用途：前端在需要时动态获取新链接（如刷新过期链接），避免长期暴露 URL。

八、安全预览接口

虽然前端可直接使用预签名 URL 访问文件，但存在以下问题：

跨域问题（CORS）
无法统一添加鉴权逻辑
浏览器对某些 Content-Type 处理不一致（如 PDF 强制下载而非预览）

因此，我们提供后端代理式预览接口：

@GetMapping("/preview/{fileId}")
public void previewFile(@PathVariable Integer fileId, HttpServletRequest request, HttpServletResponse response) throws IOException

关键实现细节：

1. 设置正确的 Content-Type

从数据库读取 contentType（如 application/pdf），确保浏览器正确渲染。

2. 安全设置 Content-Disposition

使用 RFC 5987 标准支持中文文件名，兼容新旧浏览器：

private String encodeFileName(String fileName) {
    String asciiName = fileName.replaceAll("[^\\x20-\\x7e]", "_");
    String utf8Encoded = URLEncoder.encode(fileName, StandardCharsets.UTF_8).replace("+", "%20");
    return "inline; filename=" + asciiName + "; filename*=UTF-8''" + utf8Encoded;
}

inline 表示在浏览器中预览（非强制下载）filename* 支持 UTF-8 编码的文件名

3. 后端下载并转发

通过 new URL(presignedUrl).openStream() 从 OBS 拉取文件，写入 HttpServletResponse 输出流，实现'透明代理'。

九、文件删除

先删除 OBS 中的对象
再标记数据库记录为已删除（软删除）
避免因网络问题导致数据不一致

十、安全与最佳实践

不要暴露 AK/SK：使用 IAM 角色或临时凭证更安全。
预签名 URL 有效期不宜过长：默认 1 小时，敏感文件可缩短至 5~10 分钟。
文件名清洗：防止路径穿越（如 ../../../etc/passwd）。
租户隔离：多租户系统中，storageRootDirectory 可包含 tenantCode。
日志审计：记录上传/删除操作，便于追踪。

十一、总结

本文完整实现了基于华为云 OBS 的文件上传与安全预览方案，兼顾功能性、安全性与用户体验。核心亮点包括：

严格的文件类型校验
按分类 + 时间组织存储结构
支持中文文件名的安全预览
预签名 URL 动态管理
后端代理解决跨域与权限问题

适用场景：HR 系统简历上传、OA 附件管理、医疗影像存储、教育资料分发等。

十二、完整代码示例

以下是完整、可直接运行的 Spring Boot 项目代码，包含 MySQL 表结构适配、MyBatis Mapper 接口 + XML、华为云 OBS 上传/预览/软删除、Controller 支持上传与预览、配置文件完整。

1. 主启动类：CskjApplication.java

package org.cskj;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@MapperScan("org.cskj.mapper")
public class CskjApplication {
    public static void main(String[] args) {
        SpringApplication.run(CskjApplication.class, args);
    }
}

2. OBS 配置类：ObsConfig.java

package org.cskj.config;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "file.obs")
@Data
public class ObsConfig {
    private String endpoint;
    private String ak;
    private String sk;
    private String bucketName;
    private String storageRootDirectory = "/files/";
}

3. 实体类：FileMetadata.java

package org.cskj.entity;
import lombok.Data;
import java.time.LocalDateTime;

@Data
public class FileMetadata {
    private Long id;
    private String originalFilename;
    private String safeFilename;
    private String bucketName;
    private Long fileSize;
    private String contentType;
    private String category;
    private LocalDateTime uploadTime;
    private String uploader;
    private Long tenantCode;
    private Boolean deleted;
}

4. Mapper 接口：FileMetadataMapper.java

package org.cskj.mapper;
import org.apache.ibatis.annotations.Param;
import org.cskj.entity.FileMetadata;

public interface FileMetadataMapper {
    int save(FileMetadata record);
    FileMetadata selectById(@Param("id") Long id);
    void deletedFileMetadata(@Param("id") Long id);
}

注意：id 类型为 Long，匹配 BIGINT

5. Mapper XML：FileMetadataMapper.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="org.cskj.mapper.FileMetadataMapper">
    <resultMap id="FileMetadataResultMap" type="org.cskj.entity.FileMetadata">
        <id column="id" property="id"/>
        <result column="original_filename" property="originalFilename"/>
        <result column="safe_filename" property="safeFilename"/>
        <result column="bucket_name" property="bucketName"/>
        <result column="file_size" property="fileSize"/>
        <result column="content_type" property="contentType"/>
        <result column="category" =/>
        
        
        
        
    
    
        INSERT INTO file_metadata (original_filename, safe_filename, bucket_name, file_size, content_type, category, upload_time, uploader, tenant_code, is_deleted)
        VALUES (#{originalFilename}, #{safeFilename}, #{bucketName}, #{fileSize}, #{contentType}, #{category}, NOW(), #{uploader}, #{tenantCode}, 0)
    
    
        SELECT id, original_filename, safe_filename, bucket_name, file_size, content_type, category, upload_time, uploader, tenant_code, is_deleted
        FROM file_metadata WHERE id = #{id} AND is_deleted = 0
    
    
        UPDATE file_metadata SET is_deleted = 1 WHERE id = #{id} AND is_deleted = 0

6. Service 接口：ObsService.java

package org.cskj.service;
import org.cskj.entity.FileMetadata;
import org.springframework.web.multipart.MultipartFile;

public interface ObsService {
    FileMetadata uploadFile(MultipartFile file, String category, String uploader, Long tenantCode) throws Exception;
    FileMetadata getFileMetadata(Long fileId);
    String generatePresignedUrl(Long fileId, int expirationSeconds) throws Exception;
    boolean deleteFile(Long fileId);
}

7. Service 实现：ObsServiceImpl.java

package org.cskj.service.impl;
import com.obs.services.ObsClient;
import com.obs.services.model.HttpMethodEnum;
import com.obs.services.model.PutObjectResult;
import com.obs.services.model.TemporarySignatureRequest;
import com.obs.services.model.TemporarySignatureResponse;
import org.cskj.config.ObsConfig;
import org.cskj.entity.FileMetadata;
import org.cskj.mapper.FileMetadataMapper;
import org.cskj.service.ObsService;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.web.multipart.MultipartFile;
import javax.annotation.PostConstruct;
import java.io.InputStream;
import java.time.LocalDate;

@Service
public class ObsServiceImpl implements ObsService {
    @Autowired
    private ObsConfig obsConfig;
    @Autowired
    private FileMetadataMapper fileMetadataMapper;
    private ObsClient obsClient;
    private static final Logger log = LoggerFactory.getLogger(ObsServiceImpl.class);

    @PostConstruct
    public void init() {
        this.obsClient = new ObsClient(obsConfig.getAk(), obsConfig.getSk(), obsConfig.getEndpoint());
    }

    
     FileMetadata   Exception {
           file.getOriginalFilename();
         (originalFilename == ) originalFilename = ;
           buildSafeFilename(category, originalFilename);
           obsConfig.getStorageRootDirectory() + safeFilename;
         (   file.getInputStream()) {
               obsClient.putObject(obsConfig.getBucketName(), objectKey, in);
            log.info(, objectKey, file.getSize(), result.getEtag());
        }
            ();
        metadata.setOriginalFilename(originalFilename);
        metadata.setSafeFilename(safeFilename);
        metadata.setBucketName(obsConfig.getBucketName());
        metadata.setFileSize(file.getSize());
        metadata.setContentType(file.getContentType());
        metadata.setCategory(category);
        metadata.setUploader(uploader);
        metadata.setTenantCode(tenantCode);
        metadata.setDeleted();
        fileMetadataMapper.save(metadata);
         metadata;
    }

    
     FileMetadata  {
         fileMetadataMapper.selectById(fileId);
    }

    
     String   Exception {
           getFileMetadata(fileId);
         (meta == ) {
              ();
        }
           obsConfig.getStorageRootDirectory() + meta.getSafeFilename();
            (HttpMethodEnum.GET, expirationSeconds);
        request.setBucketName(meta.getBucketName());
        request.setObjectKey(objectKey);
           obsClient.createTemporarySignature(request);
         response.getSignedUrl();
    }

    
       {
           getFileMetadata(fileId);
         (meta == )  ;
         {
               obsConfig.getStorageRootDirectory() + meta.getSafeFilename();
            obsClient.deleteObject(obsConfig.getBucketName(), objectKey);
            log.info(, objectKey);
        }  (Exception e) {
            log.error(, e);
             ;
        }
        fileMetadataMapper.deletedFileMetadata(fileId);
         ;
    }

     String  {
           originalFilename.replaceAll(, );
           String.valueOf(System.currentTimeMillis());
           timestamp +  + cleanName;
           String.valueOf(LocalDate.now().getYear());
           String.format(, LocalDate.now().getMonthValue());
         (category !=  && !category.trim().isEmpty()) {
             category +  + year +  + month +  + filename;
        }  {
             year +  + month +  + filename;
        }
    }
}

8. Controller：FileController.java

package org.cskj.controller;
import org.cskj.entity.FileMetadata;
import org.cskj.service.ObsService;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import javax.servlet.http.HttpServletResponse;
import java.io.InputStream;
import java.net.URL;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

@RestController
@RequestMapping("/api/file")
public class FileController {
    @Autowired
    private ObsService obsService;
    private static final Logger log = LoggerFactory.getLogger(FileController.class);
    private static final String DEFAULT_UPLOADER = "system";
    private static final Long DEFAULT_TENANT_CODE = 1L;

    @PostMapping("/upload")
    public ResponseEntity<?> upload(@RequestParam("file") MultipartFile file, @RequestParam(value = "category", required = false) String category) {
         (file.isEmpty()) {
             ResponseEntity.badRequest().body();
        }
         {
               obsService.uploadFile(file, category, DEFAULT_UPLOADER, DEFAULT_TENANT_CODE);
               obsService.generatePresignedUrl(meta.getId(), );
             ResponseEntity.ok().header(, meta.getId().toString()).body(url);
        }  (Exception e) {
            log.error(, e);
             ResponseEntity.status().body( + e.getMessage());
        }
    }

    
       {
         {
               obsService.getFileMetadata(fileId);
             (meta == ) {
                response.sendError(HttpServletResponse.SC_NOT_FOUND, );
                ;
            }
               obsService.generatePresignedUrl(fileId, );
               meta.getContentType();
             (contentType ==  || contentType.isEmpty()) {
                contentType = ;
            }
            response.setContentType(contentType);
               URLEncoder.encode(meta.getOriginalFilename(), StandardCharsets.UTF_8.toString()).replace(, );
            response.setHeader(,  + meta.getOriginalFilename() +  + encodedName);
             (    (presignedUrl).openStream()) {
                in.transferTo(response.getOutputStream());
            }
        }  (Exception e) {
            log.error(, e);
             {
                response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, );
            }  (Exception ignored) {
            }
        }
    }

    
        IOException {
           requestBody.get();
         (fileId == ) {
            response.sendError(HttpServletResponse.SC_BAD_REQUEST, );
            ;
        }
           obsService.generatePresignedUrl(fileId, );
           fileMetadataService.selectById(fileId);
         (metadata ==  || metadata.getDeleted()) {
            response.sendError(HttpServletResponse.SC_NOT_FOUND, );
            ;
        }
        response.setContentType(metadata.getContentType());
           encodeFileName(metadata.getOriginalFilename());
        response.setHeader(, contentDisposition);
         (    (presignedUrl).openStream();    response.getOutputStream()) {
            [] buffer =  [];
             bytesRead;
             ((bytesRead = in.read(buffer)) != -) {
                out.write(buffer, , bytesRead);
            }
            out.flush();
        }  (Exception e) {
            log.error(, e);
            response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, );
        }
    }

     String  {
           fileName.replaceAll(, );
           URLEncoder.encode(fileName, StandardCharsets.UTF_8).replace(, );
          + asciiName +  + utf8Encoded;
    }

    
     ResponseEntity<?> delete( Long fileId) {
           obsService.deleteFile(fileId);
         (success) {
             ResponseEntity.ok();
        }  {
             ResponseEntity.status().body();
        }
    }
}

9. 配置文件：application.yml

server:
  port: 8080
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/your_db?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver
  mybatis:
    mapper-locations: classpath:mapper/*.xml
    configuration:
      map-underscore-to-camel-case: true
file:
  obs:
    endpoint: https://obs.cn-north-4.myhuaweicloud.com
    ak: YOUR_HUAWEI_CLOUD_ACCESS_KEY
    sk: YOUR_HUAWEI_CLOUD_SECRET_KEY
    bucket-name: your-bucket-name
    storage-root-directory: /files/

10. Maven 依赖（pom.xml）

确保包含以下关键依赖：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.mybatis.spring.boot</groupId>
        <artifactId>mybatis-spring-boot-starter</artifactId>
        <version>2.3.0</version>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</>
    
    
        com.huaweicloud
        esdk-obs-java
        3.22.8

11. 测试

# 上传
curl -F "[email protected]" http://localhost:8080/api/file/upload
# 预览（替换 {id}）
curl http://localhost:8080/api/file/preview/1

启动应用：

mvn spring-boot:run

12. 前端验证 HTML

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>文件预览测试（POST 方式）</title>
    <style>
        body { font-family: Arial, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background-color: #f5f7fa; }
        .container { text-align: center; padding: 30px; border: 1px solid #ddd; border-radius: 8px; background: white; box-shadow: 0 2px 10px rgba(0,0,0,0.1); width: 90%; max-width: ; }
         { : ; : ; }
         { : ; : ; :  ; :  solid ; : ; : border-box; : ; }
         { :  ; : ; : white; : none; : ; : pointer; : ; : ; }
         { : ; }
         { : ; : not-allowed; }
         { : ; : ; : ; }
         { : ; : ; : ; }
    



    文件预览测试（POST 接口）
    请输入文件 ID（fileId）：
    
    🔍 预览文件
    
    后端接口需为 POST /api/file/preview，接收 { "fileId": 69 }，返回文件流（Content-Disposition: inline）

Spring Boot 集成华为云 OBS 实现文件上传与预览功能