What causes "IP[{ip}]不在白名单中，禁止访问" in jeecgboot/JeecgBoot?

Add the caller's actual egress IP (check the request log / X-Forwarded-For resolution) to the open_api.white_list field.

jeecgboot/JeecgBoot · error · JeecgBootException

IP[{ip}]不在白名单中，禁止访问

Error message

IP[{ip}]不在白名单中，禁止访问

What it means

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.

Source

Thrown at jeecg-boot/jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/openapi/filter/ApiAuthFilter.java:106

     * @param openApi
     * @param ip
     */
    protected void checkWhiteList(OpenApi openApi, String ip) {
        if (!StringUtils.hasText(openApi.getWhiteList())) {
            return;
        }

        List<String> whiteList = Arrays.stream(openApi.getWhiteList().split("[,\\n]"))
                .map(String::trim)
                .filter(StringUtils::hasText)
                .collect(Collectors.toList());

        for (String item : whiteList) {
            if (isIpMatch(ip, item)) {
                return;
            }
        }
        throw new JeecgBootException("IP[" + ip + "]不在白名单中，禁止访问");
    }

    /**
     * IP匹配：支持精确匹配、CIDR网段匹配、通配符匹配
     * @param ip 客户端IP
     * @param pattern 白名单条目（IP/CIDR/通配符）
     * @return 是否匹配
     */
    private boolean isIpMatch(String ip, String pattern) {
        if (!ip.contains(".") || !pattern.contains(".")) {
            return ip.equals(pattern);
        }
        if (pattern.contains("/")) {
            return isCidrMatch(ip, pattern);
        }
        if (pattern.contains("*")) {
            return isWildcardMatch(ip, pattern);
        }

View on GitHub (pinned to 96fb33f5ec)

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.

Example fix

// before: white_list = "10.2.3.45"  (caller actually egresses as 10.2.3.99)
// after:  white_list = "10.2.3.*"

Defensive patterns

Strategy: validation

Validate before calling

// Client-side: confirm egress IP before calling a whitelisted OpenAPI
try (java.net.Socket s = new java.net.Socket("api.ipify.org", 80)) {
    // or use your known egress; ensure it is in the whitelist
} catch (Exception e) { /* log */ }
// Operator-side: validate whitelist entries parse
static boolean validEntry(String e) {
    return e.matches("\\d+\\.\\d+\\.\\d+\\.\\d+")
        || e.matches("\\d+\\.\\d+\\.\\d+\\.\\d+/\\d+")
        || e.matches("(\\d+|\\*)\\.(\\d+|\\*)\\.(\\d+|\\*)\\.(\\d+|\\*)");
}

Try / catch

// In a global error handler, map this to a 403 with a hint
try {
    openApiClient.call(...);
} catch (JeecgBootException e) {
    if (e.getMessage().contains("不在白名单")) {
        // surface 'add IP X to whitelist' to ops, do not retry blindly
    }
}

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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.

Related errors

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