{"record":{"id":"a3a288548e0e9fa2","repo":"jeecgboot/JeecgBoot","slug":"ip-ip","errorCode":null,"errorMessage":"IP[{ip}]不在白名单中，禁止访问","messagePattern":"IP\\[(.+?)\\]不在白名单中，禁止访问","errorType":"validation","errorClass":"JeecgBootException","httpStatus":null,"severity":"error","filePath":"jeecg-boot/jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/openapi/filter/ApiAuthFilter.java","lineNumber":106,"sourceCode":"     * @param openApi\n     * @param ip\n     */\n    protected void checkWhiteList(OpenApi openApi, String ip) {\n        if (!StringUtils.hasText(openApi.getWhiteList())) {\n            return;\n        }\n\n        List<String> whiteList = Arrays.stream(openApi.getWhiteList().split(\"[,\\\\n]\"))\n                .map(String::trim)\n                .filter(StringUtils::hasText)\n                .collect(Collectors.toList());\n\n        for (String item : whiteList) {\n            if (isIpMatch(ip, item)) {\n                return;\n            }\n        }\n        throw new JeecgBootException(\"IP[\" + ip + \"]不在白名单中，禁止访问\");\n    }\n\n    /**\n     * IP匹配：支持精确匹配、CIDR网段匹配、通配符匹配\n     * @param ip 客户端IP\n     * @param pattern 白名单条目（IP/CIDR/通配符）\n     * @return 是否匹配\n     */\n    private boolean isIpMatch(String ip, String pattern) {\n        if (!ip.contains(\".\") || !pattern.contains(\".\")) {\n            return ip.equals(pattern);\n        }\n        if (pattern.contains(\"/\")) {\n            return isCidrMatch(ip, pattern);\n        }\n        if (pattern.contains(\"*\")) {\n            return isWildcardMatch(ip, pattern);\n        }","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/jeecgboot/JeecgBoot/blob/96fb33f5ec68516da0b0147da06b2eb0419e063a/jeecg-boot/jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/openapi/filter/ApiAuthFilter.java#L88-L124","documentation":"Thrown by ApiAuthFilter.checkWhiteList when the caller's client IP does not match any entry in the OpenAPI's white_list. The whitelist supports exact IPs, CIDR ranges (e.g. 192.168.1.0/24), and wildcards (e.g. 10.2.3.*), separated by comma or newline. A non-empty whitelist is enforced strictly; an empty whitelist is treated as open.","triggerScenarios":"An OpenAPI call arrives from an IP not in the configured white_list; the white_list was set but the caller is behind a NAT/proxy whose egress IP differs; CIDR/wildcard entry is malformed so it silently fails to match (the matcher returns false on parse errors).","commonSituations":"Production runs behind a load balancer whose source IP is the LB's IP rather than the real client; deploying to a new region with a new egress IP; malformed CIDR like '192.168.1.0/' that parses to a failing match instead of an obvious error.","solutions":["Add the caller's actual egress IP (check the request log / X-Forwarded-For resolution) to the open_api.white_list field.","If the caller spans a subnet, add a CIDR entry (e.g. '10.0.0.0/8') or wildcard ('10.0.0.*').","Verify the white_list syntax: entries are comma- or newline-separated; CIDR must be 'ip/prefix'; wildcards use '*' only at the octet level.","If IP restriction is not desired, clear the white_list field to disable the check."],"exampleFix":"// before: white_list = \"10.2.3.45\"  (caller actually egresses as 10.2.3.99)\n// after:  white_list = \"10.2.3.*\"","handlingStrategy":"validation","validationCode":"// Client-side: confirm egress IP before calling a whitelisted OpenAPI\ntry (java.net.Socket s = new java.net.Socket(\"api.ipify.org\", 80)) {\n    // or use your known egress; ensure it is in the whitelist\n} catch (Exception e) { /* log */ }\n// Operator-side: validate whitelist entries parse\nstatic boolean validEntry(String e) {\n    return e.matches(\"\\\\d+\\\\.\\\\d+\\\\.\\\\d+\\\\.\\\\d+\")\n        || e.matches(\"\\\\d+\\\\.\\\\d+\\\\.\\\\d+\\\\.\\\\d+/\\\\d+\")\n        || e.matches(\"(\\\\d+|\\\\*)\\\\.(\\\\d+|\\\\*)\\\\.(\\\\d+|\\\\*)\\\\.(\\\\d+|\\\\*)\");\n}","typeGuard":null,"tryCatchPattern":"// In a global error handler, map this to a 403 with a hint\ntry {\n    openApiClient.call(...);\n} catch (JeecgBootException e) {\n    if (e.getMessage().contains(\"不在白名单\")) {\n        // surface 'add IP X to whitelist' to ops, do not retry blindly\n    }\n}","preventionTips":["Record the actual egress IP (or CIDR) in the whitelist, not the client's private IP behind NAT.","Use CIDR for ranges rather than enumerating IPs.","Leave white_list empty if IP restriction is not required (empty = open).","Validate whitelist entry syntax in the admin UI."],"tags":["openapi","ip-whitelist","auth","network","security"],"backgroundTag":null,"analyzedSha":"96fb33f5ec68516da0b0147da06b2eb0419e063a","analyzedAt":"2026-08-14T00:04:16.786Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}