Tomcat环境下文件上传失败的常见根因与排查路径
一、常见根因分类
- 临时目录无效或缺失：上传依赖的临时目录被清理、权限不足或磁盘已满，典型异常包含关键字“The temporary upload location […] is not valid”“No space left on device”。在 Linux 上，系统或容器可能定期清理 /tmp，导致 Tomcat 启动创建的临时目录被删除；在 Windows 上常见为临时目录被清理或不可写。若使用 Undertow 作为嵌入式容器，也会在 /tmp 下创建临时上传目录，遇到清理或空间不足同样会失败。
- 请求体或单个文件大小超限：超出 Spring Boot multipart 限制（如 max-file-size、max-request-size），或超出 Tomcat Connector 的 maxPostSize，或上层 反向代理（如 Nginx） 的 client_max_body_size，都会在解析 multipart 前被拒绝。
- 网络与安全设备中断连接：上传大文件或特定内容时，内网防火墙/IPS/负载均衡等可能触发策略，导致 Connection reset by peer 或连接中断，表现为解析 multipart 失败。
- 应用代码与配置问题：未正确配置 Multipart（如未注册过滤器/解析器）、上传目录不可写、超时设置不合理等。
二、日志特征与快速定位
- 出现“The temporary upload location […] is not valid”或“NoSuchFileException”时，优先检查上传临时目录是否存在、是否可写、磁盘是否已满；必要时为 Tomcat/应用指定稳定的临时目录（如 server.tomcat.basedir 或 spring.servlet.multipart.location）。
- 出现“MaxUploadSizeExceededException”或“the request was rejected because its size (…) exceeds the configured maximum”时，说明大小超限，需同时核对应用层（Spring）、容器层（Tomcat Connector）、以及可能存在的代理层（Nginx）的上限配置。
- 出现“Connection reset by peer”“broken pipe”等网络异常时，重点排查上传链路中的防火墙/IPS/代理策略，必要时用抓包定位中断点。
- 出现“No space left on device”时，清理磁盘或扩容，并迁移临时目录到空间充足的位置。
三、关键配置与建议值
- Spring Boot 应用层（application.yml/properties）：设置单个文件与总请求大小，例如
spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=50MB
版本差异注意：Spring Boot 1.4/1.5 使用 spring.http.multipart.*，Spring Boot 2.x 使用 spring.servlet.multipart.*。
- Tomcat 容器层（server.xml Connector）：设置 POST 数据上限，例如
（约 20MB）。
- 反向代理层（Nginx）：设置请求体上限，例如
client_max_body_size 20m;（可按 location 细化）。
- 临时目录（避免被系统清理）：
- Spring Boot：server.tomcat.basedir=/data/app/tmp 或 spring.servlet.multipart.location=/data/app/tmp
- 通用 Java：启动参数 -Djava.io.tmpdir=/data/app/tmp
同时确保目录存在且 Tomcat/应用有写权限。
四、最小可行排查清单
- 在应用日志中定位异常栈顶关键词（临时目录、大小超限、连接重置），确定属于哪一层限制。
- 检查并修复临时目录：确认目录存在、权限正确、磁盘未满；必要时迁移到持久化路径并更新配置。
- 校验三层上限是否一致：Spring Boot multipart、Tomcat Connector maxPostSize、Nginx client_max_body_size，调整为统一且合理的阈值。
- 复现并抓包（如 Wireshark/tcpdump）：若仅特定文件或较大文件失败，重点排查防火墙/IPS/代理策略导致的连接中断。
- 回归验证：使用不同大小与类型的文件，逐步增大验证阈值稳定性，并观察 Tomcat 与代理日志是否一致报错。
