jeecgboot/JeecgBoot · critical · JeecgBootException

上传业务路径包含非法字符！

Error message

上传业务路径包含非法字符！

What it means

Thrown by SsrfFileTypeFilter.validatePathSecurity when the normalized customPath contains '..' or '~'. This is the path-traversal guard for upload business paths — it blocks directory escapes before the upload is written. The path is normalized (backslashes -> '/') first, so '\\..\\' is also caught.

Source

Thrown at jeecg-boot/jeecg-boot-base-core/src/main/java/org/jeecg/common/util/filter/SsrfFileTypeFilter.java:278

            stringBuilder.append(hv);
        }
        return stringBuilder.toString();
    }

    /**
     * 路径安全校验
     */
    private static void validatePathSecurity(String customPath) throws JeecgBootException {
        if (customPath == null || customPath.trim().isEmpty()) {
            return;
        }

        // 统一分隔符为 /
        String normalized = customPath.replace("\\", "/");

        // 1. 防止路径遍历攻击
        if (normalized.contains("..") || normalized.contains("~")) {
            throw new JeecgBootException("上传业务路径包含非法字符！");
        }

        // 2. 限制路径深度
        int depth = normalized.split("/").length;
        if (depth > 5) {
            throw new JeecgBootException("上传业务路径深度超出限制！");
        }

        // 3. 限制字符集（只允许字母、数字、下划线、横线、斜杠）
        if (!normalized.matches("^[a-zA-Z0-9/_-]+$")) {
            throw new JeecgBootException("上传业务路径包含非法字符！");
        }
    }

    /**
     * 校验文件路径安全性，防止路径遍历攻击
     * @param filePath 文件路径
     */

View on GitHub (pinned to 96fb33f5ec)

Solutions

1. Strip '..' and '~' from customPath on the client before submitting; only use simple relative folder names.
2. Server-side, generate customPath from trusted metadata (tenant id, date) rather than raw user input.
3. Reject any absolute path or path containing path-traversal sequences at the DTO validation layer.
4. Confirm the upload form sends only a flat business category (e.g. 'avatar', 'report').

Example fix

// before
customPath = "../../etc/passwd";
checkUploadFileType(file, customPath); // throws

// after
customPath = "avatar";
checkUploadFileType(file, customPath);

String n = customPath == null ? "" : customPath.replace("\\","/");
if (n.contains("..") || n.contains("~")) throw new IllegalArgumentException("traversal");

public static boolean pathNoTraversal(String p){
    String n = p == null ? "" : p.replace("\\","/");
    return !n.contains("..") && !n.contains("~");
}

try { SsrfFileTypeFilter.checkUploadFileType(file, customPath); }
catch (JeecgBootException e) { if (e.getMessage().contains("非法")) badRequest(e.getMessage()); }

When it happens

Trigger: An upload API call with customPath containing '../', a leading '~' (home reference), or backslash variants like '..\\..\\etc'. Common when the client constructs the path from user input without sanitization.

Common situations: A filename or folder field concatenated into customPath; an attacker probing for arbitrary file write; a misbehaving client that sends absolute paths or Windows-style paths.

Related errors

• 下载失败，存在非法文件类型：{suffix}
• 上传失败，存在非法文件类型：{suffix}
• 上传业务路径深度超出限制！
• 文件路径包含非法字符
• 非法存储路径，路径包含遍历字符: {storePath}

AI-assisted analysis of jeecgboot/JeecgBoot@96fb33f5ec (2026-08-14). Data as JSON: /api/errors/b20dbda9558f7ea1. Report an issue: GitHub.