Spring Boot Multipart文件上传REST端点偶发MultipartException(设备无剩余空间)问题排查方案咨询

嘿，针对你遇到的这个偶发无空间问题，我有几个具体方案帮你定位根因，咱们一步步来：

一、增强日志记录，看清Multipart处理全流程 #

首先咱们可以把Multipart相关组件的日志拉满，就能看到临时文件创建、处理的每一步细节：

1. 调整Spring Boot与Undertow的日志配置
   在你的application.properties或application.yml里添加：

# 开启Spring Multipart模块的DEBUG日志
logging.level.org.springframework.web.multipart=DEBUG
# 开启Undertow Multipart处理的DEBUG日志
logging.level.io.undertow.servlet.handlers.Multipart=DEBUG

这些日志会帮你看到Multipart请求的边界解析、临时文件的创建路径与大小、请求处理的阶段，甚至能发现是不是有超出预期的大文件在上传。

2. 关键：记录inode使用情况
   你目前只检查了/tmp的磁盘空间，但Linux系统中，inode耗尽也会触发"No space left on device"错误，哪怕磁盘空间还有剩余。这是很多人忽略的点，一定要在异常发生时记录inode状态。

二、添加异常捕获与实时诊断逻辑 #

因为异常发生在Spring的Multipart解析阶段（早于你的Controller方法），咱们可以通过自定义组件捕获异常并记录诊断信息：

1. 自定义MultipartResolver，异常时自动诊断 #

继承Spring默认的StandardServletMultipartResolver，重写解析方法，在捕获到MultipartException时立即输出/tmp的空间、inode、请求详情：

import jakarta.servlet.http.HttpServletRequest;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.multipart.MultipartException;
import org.springframework.web.multipart.MultipartHttpServletRequest;
import org.springframework.web.multipart.support.StandardServletMultipartResolver;
import org.springframework.stereotype.Component;
import java.io.IOException;
import java.nio.charset.StandardCharsets;

@Component
public class DiagnosingMultipartResolver extends StandardServletMultipartResolver {

    private static final Logger logger = LoggerFactory.getLogger(DiagnosingMultipartResolver.class);

    @Override
    public MultipartHttpServletRequest resolveMultipart(HttpServletRequest request) throws MultipartException {
        try {
            return super.resolveMultipart(request);
        } catch (MultipartException e) {
            // 异常发生时强制记录诊断信息
            logTmpDiagnostics();
            logRequestMetadata(request);
            throw e; // 重新抛出异常，不破坏原有业务流程
        }
    }

    private void logTmpDiagnostics() {
        // 记录磁盘空间、inode、临时文件数量
        try {
            Process dfSpace = new ProcessBuilder("df", "-H", "/tmp").start();
            String spaceOutput = new String(dfSpace.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
            
            Process dfInode = new ProcessBuilder("df", "-i", "/tmp").start();
            String inodeOutput = new String(dfInode.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
            
            Process fileCount = new ProcessBuilder("sh", "-c", "ls -la /tmp | wc -l").start();
            String countOutput = new String(fileCount.getInputStream().readAllBytes(), StandardCharsets.UTF_8);

            logger.error("=== /tmp 诊断信息 ===");
            logger.error("磁盘空间状态:\n{}", spaceOutput);
            logger.error("Inode使用状态:\n{}", inodeOutput);
            logger.error("临时文件总数: {}", countOutput.trim());
        } catch (IOException ex) {
            logger.error("获取/tmp诊断信息失败", ex);
        }
    }

    private void logRequestMetadata(HttpServletRequest request) {
        logger.error("=== 异常请求元数据 ===");
        logger.error("请求URI: {}", request.getRequestURI());
        logger.error("Content-Length头: {}", request.getHeader("Content-Length"));
        logger.error("Content-Type头: {}", request.getHeader("Content-Type"));
        logger.error("客户端IP: {}", request.getRemoteAddr());
    }
}

这个自定义Resolver会自动替换Spring Boot默认的MultipartResolver，不用修改业务代码就能自动输出诊断日志。

2. 全局异常处理器兜底 #

再加上全局异常处理器，确保哪怕Resolver没捕获到的Multipart异常也能被记录：

import jakarta.servlet.http.HttpServletRequest;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.multipart.MultipartException;

@RestControllerAdvice
public class MultipartExceptionHandler {

    private static final Logger logger = LoggerFactory.getLogger(MultipartExceptionHandler.class);

    @ExceptionHandler(MultipartException.class)
    public ResponseEntity<String> handleMultipartSpaceError(MultipartException e, HttpServletRequest request) {
        if (e.getCause() != null && e.getCause().getMessage() != null && 
            e.getCause().getMessage().contains("No space left on device")) {
            logTmpDiagnostics();
            logRequestMetadata(request);
        }
        return ResponseEntity.status(500).body("文件上传失败，请稍后重试");
    }

    // 复制DiagnosingMultipartResolver里的logTmpDiagnostics和logRequestMetadata方法即可
}

三、结合Undertow与Heroku的特定优化 #

1. 调整Undertow的Multipart清理策略
   Undertow默认会在请求结束后删除临时文件，但异常中断时可能有残留。在application.yml里添加配置强制清理：

spring:
  undertow:
    servlet:
      multipart:
        cleanup-on-error: true # 异常时自动清理临时文件
        max-file-size: 100KB # 严格限制文件大小，和预期一致
        max-request-size: 100KB

2. Heroku Dyno的临时目录特性
   Heroku的/tmp虽然总空间充足，但Dyno会定期重启（通常24小时），重启时/tmp会被清空，这可能解释了“重试几次就成功”的现象——重启后临时文件被清掉了。

四、重点验证方向 #

等配置好后，下次异常发生时重点看：

• /tmp的inode是不是耗尽了（看df -i的Use%）
• 临时文件总数是不是瞬间暴涨
• 请求的Content-Length是不是远大于100KB（客户端可能发了异常大的文件）

这些信息就能帮你定位根因：是临时文件清理不及时、inode耗尽，还是有异常大的请求，甚至是Heroku临时目录的突发配额限制。

内容来源于stack exchange