Spring Boot文件上传在Linux Tomcat8服务器运行失败问题咨询

The Scenario #

You've built a Spring Boot web app that handles file uploads and stores files in an upload-dir folder on the server. Your implementation works perfectly on local Windows, but fails when deployed to a Linux-based Tomcat 8 server. Here's your store method code:

public String store(MultipartFile file, String newName) { 
    this.rootLocation = System.getProperty("user.dir") + File.separator + "upload-dir"; 
    try { 
        if (file.isEmpty()) { 
            throw new StorageException("Failed to store empty file " + file.getOriginalFilename()); 
        } 
        if (!Files.exists(this.rootLocation)) 
            Files.createDirectory(this.rootLocation); 
        Files.copy(file.getInputStream(), this.rootLocation.resolve(newName)); 
    } catch (IOException e) { 
        System.console().writer().write(e.getMessage()); 
        throw new StorageException("Failed to store file " + file.getOriginalFilename(), e); 
    } 
    return this.rootLocation.resolve(newName).toString(); 
}

Likely Causes for Linux Deployment Failure #

Let's walk through the most common reasons this happens:

• Permission Problems (Most Probable)
  On Linux, Tomcat runs under a dedicated system user (often tomcat or www-data). This user probably doesn't have write access to the directory returned by System.getProperty("user.dir"). When your code tries to create upload-dir or write files into it, the OS blocks the operation due to strict file system permissions. For example, if user.dir points to Tomcat's bin directory (a common default in Linux service deployments), the Tomcat user typically can't create subdirectories there.

• Unexpected user.dir Value
  On Windows, user.dir usually points to your project root or the folder where you launched the app. But on Linux, when Tomcat runs as a system service, user.dir might default to / (the root directory) or Tomcat's installation path (like /opt/tomcat). This means your code is trying to create upload-dir in a location you didn't intend—one that's likely restricted from write access.

• Missing Parent Directories (or No Permission to Create Them)
  Your code checks if rootLocation exists, but uses Files.createDirectory() which only creates the target directory—it won't create missing parent directories. If the parent path of rootLocation doesn't exist (or the Tomcat user can't write to that parent), this method throws an IOException. Switching to Files.createDirectories() would fix this specific issue, but it doesn't solve underlying permission problems.

• SELinux Restrictions (Enterprise Linux Distros)
  If your server uses SELinux (common on RHEL, CentOS, or Fedora), even if file system permissions are correct, SELinux might block Tomcat from writing to non-standard directories. Tomcat is typically allowed to write to predefined paths like webapps or temp, but a custom upload-dir outside those areas would be denied unless you adjust SELinux policies.

• Invalid File/Path Characters
  While you're using newName, if that string contains characters allowed on Windows but forbidden on Linux (like :, *, or ?), this could cause a failure. This is less likely if you're sanitizing newName, but it's worth verifying.

Quick Troubleshooting Steps #

1. Log the rootLocation value when the app runs on Linux—this will show exactly where it's trying to create the folder.
2. Check directory permissions: Run ls -ld /path/to/parent-directory to see the owner and permission settings of the parent folder.
3. Test manual creation: Try creating upload-dir as the Tomcat user with sudo -u tomcat mkdir /full/path/to/upload-dir—if this fails, permissions are definitely the issue.
4. Check SELinux logs: If SELinux is enabled, look for denials in /var/log/audit/audit.log related to Tomcat writing to the target directory.

内容的提问来源于stack exchange，提问作者Tariq Husein