fix：解决头像无法展示问题

Author: yqz

OpenBlog-business/src/main/java/com/yqz/openblog/common/GlobalExceptionHandler.java

@@ -5,6 +5,8 @@
 import org.springframework.web.bind.MethodArgumentNotValidException;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+import java.io.IOException;
+
 import org.springframework.web.bind.annotation.ExceptionHandler;
 import org.springframework.web.bind.annotation.RestControllerAdvice;
 import org.springframework.security.access.AccessDeniedException;
@@ -45,10 +47,21 @@ public ResponseEntity<ApiResponse<Object>> onAccessDenied(Exception ex) {
         return ResponseEntity.status(HttpStatus.FORBIDDEN).body(ApiResponse.fail(4030, "无权限"));
     }
 
+    /**
+     * IO 异常（MinIO 读写、文件读写等）直接返回原始错误信息，便于排查。
+     */
+    @ExceptionHandler(IOException.class)
+    public ResponseEntity<ApiResponse<Object>> onIO(IOException ex) {
+        log.error("IO exception", ex);
+        String msg = ex.getMessage() != null ? ex.getMessage() : "IO异常";
+        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(ApiResponse.fail(5001, msg));
+    }
+
     @ExceptionHandler(Exception.class)
     public ResponseEntity<ApiResponse<Object>> onOther(Exception ex) {
         log.error("unhandled server error", ex);
-        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(ApiResponse.fail(5001, "服务器异常"));
+        String msg = ex.getMessage() != null ? ex.getMessage() : "服务器异常";
+        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(ApiResponse.fail(5001, msg));
     }
 }
 

OpenBlog-business/src/main/java/com/yqz/openblog/media/controller/MediaController.java

@@ -1,27 +1,34 @@
 package com.yqz.openblog.media.controller;
 
 import com.yqz.openblog.common.ApiResponse;
+import com.yqz.openblog.common.BizException;
 import com.yqz.openblog.media.dto.MediaCategoryResponse;
 import com.yqz.openblog.media.dto.MediaListItemResponse;
 import com.yqz.openblog.media.dto.MediaUploadResponse;
 import com.yqz.openblog.media.dto.ThumbInfoResponse;
 import com.yqz.openblog.media.entity.Media;
 import com.yqz.openblog.media.service.MediaService;
 import com.baomidou.mybatisplus.core.metadata.IPage;
+import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.MediaType;
+import org.springframework.util.StringUtils;
 import org.springframework.web.bind.annotation.*;
 import org.springframework.web.multipart.MultipartFile;
 
 import java.io.IOException;
+import java.net.URLDecoder;
+import java.nio.charset.StandardCharsets;
 import java.util.List;
 
 @RestController
 @RequestMapping("/api/v1/media")
 @CrossOrigin(origins = "*")
 public class MediaController {
 
+    private static final String FILES_PATH_MARKER = "/api/v1/media/files/";
+
     private final MediaService mediaService;
 
     public MediaController(MediaService mediaService) {
@@ -59,14 +66,29 @@ public ApiResponse<ThumbInfoResponse> thumbInfo(@PathVariable("key") String key)
         return ApiResponse.ok(mediaService.thumbInfo(key));
     }
 
-    @GetMapping(value = "/files/{key:.+}/thumb", produces = MediaType.ALL_VALUE)
-    public void serveThumb(@PathVariable("key") String key, HttpServletResponse response) throws IOException {
-        serveFile(key, true, response);
-    }
-
-    @GetMapping(value = "/files/{key:.+}", produces = MediaType.ALL_VALUE)
-    public void serveOriginal(@PathVariable("key") String key, HttpServletResponse response) throws IOException {
-        serveFile(key, false, response);
+  /**
+   * 媒体文件访问（原图 / 缩略图）。storageKey 可能含 {@code /}（如 {@code general/uuid.jpg}），
+   * 须用 {@code /**} 解析路径；Spring Boot 3 默认 PathPattern 下 {@code {key:.+}} 无法跨段匹配。
+   */
+    @GetMapping(value = "/files/**", produces = MediaType.ALL_VALUE)
+    public void serveFile(HttpServletRequest request, HttpServletResponse response) throws IOException {
+        String uri = request.getRequestURI();
+        int idx = uri.indexOf(FILES_PATH_MARKER);
+        if (idx < 0) {
+            throw new BizException(4042, "无效媒体路径");
+        }
+        String path = uri.substring(idx + FILES_PATH_MARKER.length());
+        int q = path.indexOf('?');
+        if (q >= 0) {
+            path = path.substring(0, q);
+        }
+        path = URLDecoder.decode(path, StandardCharsets.UTF_8);
+        boolean thumb = path.endsWith("/thumb");
+        String key = thumb ? path.substring(0, path.length() - "/thumb".length()) : path;
+        if (!StringUtils.hasText(key)) {
+            throw new BizException(4002, "媒体 key 为空");
+        }
+        serveFile(key, thumb, response);
     }
 
     private void serveFile(String key, boolean thumb, HttpServletResponse response) throws IOException {

OpenBlog-business/src/main/java/com/yqz/openblog/media/storage/MinioMediaStorage.java

@@ -102,11 +102,13 @@ private byte[] readObject(String objectName) throws IOException {
             if ("NoSuchKey".equals(e.errorResponse().code())) {
                 throw new BizException(4042, "媒体文件不存在");
             }
-            throw new IOException("读取 MinIO 失败: " + objectName, e);
+            String detail = e.errorResponse().message() != null ? e.errorResponse().message() : e.errorResponse().code();
+            throw new IOException("读取 MinIO 失败: " + objectName + " (" + detail + ")", e);
         } catch (BizException e) {
             throw e;
         } catch (Exception e) {
-            throw new IOException("读取 MinIO 失败: " + objectName, e);
+            String cause = e.getMessage() != null ? e.getMessage() : e.getClass().getSimpleName();
+            throw new IOException("读取 MinIO 失败: " + objectName + " (" + cause + ")", e);
         }
     }