jeecgboot/JeecgBoot · error · JeecgBootException

上传业务路径深度超出限制！

Error message

上传业务路径深度超出限制！

What it means

Thrown by validatePathSecurity when the normalized customPath has more than 5 segments after split('/'). This caps folder nesting for uploaded files to prevent excessively deep (or DoS-inducing) paths and to keep uploaded content within a predictable tree.

Source

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

     * 路径安全校验
     */
    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 文件路径
     */
    public static void checkPathTraversal(String filePath) {
        if (StringUtils.isBlank(filePath)) {
            return;
        }
        // 1. 防止路径遍历：不允许 ..
        if (filePath.contains("..")) {

View on GitHub (pinned to 96fb33f5ec)

Solutions

1. Reduce customPath to <= 5 segments, e.g. 'tenant/module/category'.
2. Trim leading/trailing slashes before counting: customPath.replaceAll('^/+|/+$','').
3. Move deep nesting into the server's storage logic, not the client-supplied customPath.
4. If deeper paths are genuinely needed, raise the cap and review the storage layout.

Example fix

// before
customPath = "/a/b/c/d/e/f/"; // 8 segments after split

// after
customPath = "a/b/c";

String n = customPath.replaceAll("^/+|/+$","");
if (n.split("/").length > 5) throw new IllegalArgumentException("too deep");

public static boolean pathDepthOk(String p){
    String n = p == null ? "" : p.replaceAll("^/+|/+$","");
    return n.split("/").length <= 5;
}

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

When it happens

Trigger: An upload request whose customPath is something like 'a/b/c/d/e/f/file' (6+ segments), or a path with leading/trailing slashes that inflate the split count, or a generated path stacking tenant/year/month/category/subcat/subsub.

Common situations: A path generator concatenates too many hierarchy levels; trailing slash makes split produce an empty first element raising the count; migration from a system that used deep folder structures.

Related errors

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

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