SpringBoot中IP白名单控制实现限制接口访问

2025-07-31 10:37 开发作者： Clf丶忆笙

一、IP白名单控制概述

1.1 什么是IP白名单

IP白名单(IP Whitelist)是一种网络安全机制，它通过预先定义一组被允许访问系统资源的IP地址列表，实现对网络请求来源的精确控制。只有来自白名单中IP地址的请求才会被系统接受和处理，其他所有来源的请求都将被拒绝。

在Spring Boot应用中实现IP白名单控制具有以下核心价值：

增强安全性：有效防止未授权访问，降低恶意攻击风险
访问控制：精确管理可访问系统的客户端范围
资源保护：避免非预期流量消耗服务器资源
合规要求：满足某些行业对访问控制的监管要求

1.2 IP白名单 vs 黑名单

特性	IP白名单	IP黑名单
控制逻辑	默认拒绝，明确允许	默认允许，明确拒绝
安全性	更高，仅已知安全IP可访问	较低，新型攻击源可能不在名单中
维护成本	较高，需要持续更新合法IP	较低，只需添加已知恶意IP
适用场景	内部系统、高安全要求接口	公开服务、需要阻止特定恶意源
误杀可能性	可能误拒绝合法但未登记的IP	可能漏过未登记的恶意IP

1.3 IP白名单的应用场景

内部管理系统：限制只有公司内网或VPN IP可以访问
支付接口：确保只有支付网关的服务器IP可以调用
数据同步接口：仅允许合作伙伴的指定服务器IP访问
管理后台：防止未授权的管理员访问
第三方服务集成：限定合作方的调用来源

二、Spring Boot中实现IP白名单的技术选型

2.1 实现方案对比

在 Spring Boot 中实现 IP 白名单功能时，可以选择多种技术方案。以下是常见的 技术选型 及其适用场景、优缺点分析：

1. 自定义 Filter 实现

实现方式

通过实现 Javax.servlet.Filter 接口，在 doFilter 方法中检查请求的 IP 是否在白名单中。
配合 @Component 注解注册为 Spring Bean，并配置拦截路径。

优点

简单直接：无需依赖额外框架，代码实现灵活。
低耦合：与 Spring Security 无关，适合轻量级需求。
可扩展性强：支持动态更新白名单（如从数据库加载）。

缺点

需要手动处理 IP 获取逻辑：需注意代理服务器（如 Nginx）后的真实 IP 获取。
缺乏安全框架集成：无法与 Spring Security 的权限控制无缝结合。

适用场景

简单项目或对安全要求不高的场景。
需要完全自定义逻辑（如动态加载白名单）。

2. Spring Security 集成

实现方式

使用 Spring Security 提供的 hasIpAddress 方法，配置白名单。
对于多 IP 白名单，需结合自定义表达式或策略。

优点

与安全框架无缝集成：可与其他安全规则（如角色权限）结合。
配置灵活：支持基于路径的细粒度控制。

缺点

配置复杂度较高：需要编写自定义表达式或策略类。
不支持通配符：直接配置时仅支持精确匹配。

适用场景

已使用 Spring Security 的项目。
需要将 IP 白名单与其他安全规则（如 JWT、OAuth）结合。

3. AOP（面向切面编程）

实现方式

使用 @ASPect 定义切面，在方法执行前检查 IP 是否在白名单中。
适用于对特定方法或类的访问控制。

优点

细粒度控制：可针对具体方法或类实现 IP 拦截。
解耦业务逻辑：安全逻辑与业务代码分离。

缺点

性能开销：AOP 会增加方法调用的额外开销。
IP 获取复杂：需在切面中获取 HttpServletRequest 对象。

适用场景

需要对特定方法（如敏感接口）进行 IP 校验。
与业务逻辑解耦需求较高的场景。

4. 动态白名单（结合数据库）

实现方式

将白名单存储在数据库中，通过定时任务或缓存刷新机制动态加载。
可结合 Redis 缓存提高性能。

优点

灵活性高：无需重启服务即可更新白名单。
适合生产环境：支持动态管理 IP 列表。

缺点

实现复杂度较高：需处理数据库连接、缓存更新等逻辑。
性能依赖数据库：频繁查询数据库可能影响性能。

适用场景

白名单需要频繁更新的场景。
多租户系统或需要动态权限管理的系统。

5. 使用 Linux 防火墙（iptables/nftables）

实现方式

通过 Linux 命令行配置防火墙规则，限制访问 IP。
与 Spring Boot 无关，属于操作系统层面的控制。

优点

高性能：由操作系统直接处理，无需应用层逻辑。
简单高效：适合服务器级别的全局控制。

缺点

不可动态更新：需手动执行命令或脚本。
缺乏灵活性：无法针对具体接口或方法控制。

适用场景

服务器级别的全局访问控制。
与 Spring Boot 应用无关的基础设施防护。

6. 基于Interceptor的IP白名单

优点

与 Spring MVC 集成良好：由于拦截器是 Spring MVC 的一部分，因此它能够很好地集成到现有的 Spring Boot 应用程序中。
适用于控制器级别的过滤：对于那些希望基于控制器或 API 级别进行 IP 访问控制的应用来说，这是一个理想的选择。
灵活性高：可以根据不同的 URL 模式应用不同的拦截规则，使得可以在不同的场景下灵活运用。

缺点

不适合全局过滤：对于不在控制器中的资源（例如静态资源），可能无法有效拦截。如果需要对整个应用程序实施 IP 白名单策略，则可能不是最佳选择。
性能开销：虽然拦截器的性能开销相对较小，但在高并发情况下，仍然需要注意其对系统性能的影响。

适用场景

需要对特定控制器或 API 进行 IP 访问控制的应用：比如某些敏感的操作只能由特定的 IP 地址执行，这时可以使用拦截器来限制访问。
已构建了复杂的 Spring MVC 应用程序的项目：如果您的应用程序已经大量使用了 Spring MVC 的特性，那么使用拦截器将是一个自然且易于维护的选择。
轻量级的 IP 白名单需求：当您只需要简单的 IP 白名单功能而不希望引入如 Spring Security 等较重的安全框架时，拦截器提供了一个轻便的解决方案。

6. 技术选型对比表

技术方案	优点	缺点	适用场景
自定义 Filter	简单直接，灵活性高	需手动处理 IP 获取逻辑	轻量级项目或动态白名单需求
Spring Security	与安全框架集成，配置灵活	配置复杂，不支持通配符	已使用 Spring Security 的项目
AOP	细粒度控制，解耦业务逻辑	性能开销，IP 获取复杂	特定方法或类的访问控制
动态白名单	灵活，适合生产环境	实现复杂，依赖数据库性能	多租户系统或动态管理需求
基于 Interceptor	与 Spring MVC 集成良好，适用于控制器层面的过滤	不适合全局过滤，如静态资源等	控制器级别的 IP 访问控制
Linux 防火墙	高性能，简单高效	不可动态更新，缺乏灵活性	服务器级别全局控制

三、完整实现方案

3.1 自定义 Filter 实现 IP 白名单

1.1 添加依赖

Spring Boot 默认支持 Servlet API，无需额外依赖。

1.2 创建配置文件

在 application.yml 中配置白名单：

ip:
  whitelist: "192.168.1.1, 192.168.1.2"

1.3 创建 Filter 类

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

import javax.servlet.*;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.Arrays;
import java.util.List;

/**
 * 自定义 IP 白名单 Filter
 * 作用：拦截请求，检查客户端 IP 是否在白名单中
 */
@Component
public class IpWhiteListFilter implements Filter {

    @Value("${ip.whitelist}")
    private String whitelistStr;

    // 用于存储白名单的 List
    private List<String> whiteList;

    /**
     * 初始化白名单
     */
    @Override
    public void init(FilterConfig filterConfig) {
        whiteList = Arrays.stream(whitelistStr.split(","))
                .map(String::trim)
                .collect(java.util.stream.Collectors.toList());
    }

    /**
     * 处理请求
     */
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        HttpServletResponse httpResponse = (HttpServletResponse) response;

        String clientIP = getClientIP(httpRequest); // 获取真实 IP
        if (whiteList.contains(clientIP)) {
            chain.doFilter(request, response); // IP 在白名单中，放行
        } else {
            httpResponse.sendError(HttpServletResponse.SC_FORBIDDEN, "IP 未授权访问");
        }
    }

    /**
     * 获取客户端真实 IP（支持代理服务器）
     */
    private String getClientIP(HttpServletRequest request) {
        // 从 X-Forwarded-For 头获取真实 IP
        String ip = request.getHeader("X-Forwarded-Fo编程客栈r");
        if (ip == null || ip.isEmpty() || "unknown".equalsIgnoreCase(ip)) {
            ip = request.getRemoteAddr(); // 如果没有代理，直接获取远程地址
        }
        return ip;
    }

    @Override
    public void destroy() {
        // 清理资源
    }
}

1.4 注册 Filter（可选）

如果未使用 @Component 注解，可通过配置类注册：

@Configuration
public class FilterConfig {

    @Bean
    public FilterRegistrationBean<IpWhiteListFilter> ipWhiteListFilter(IpWhiteListFilter filter) {
        FilterRegistrationBean<IpWhiteListFilter> registration = new FilterRegistrationBean<>(filter);
        registration.addUrlPatterns("/*"); // 拦截所有请求
        return registration;
    }
}

3.2 Spring Security 实现 IP 白名单

2.1 添加依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

2.2 配置白名单

在 application.yml 中配置白名单：

ip:
  whitelist: "192.168.1.1, 192.168.1.2"

2.3 创建 Security 配置类

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

import java.util.Arrays;

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Value("${ip.whitelist}")
    private String[] whiteList;

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .antMatchers("/**")
                .Access("hasIpAddress('192.168.1.1') or hasIpAddress('192.168.1.2')") // 支持多个 IP
                .and()
            .csrf().disable(); // 关闭 CSRF 保护
    }
}

3.3 AOP 实现 IP 白名单

3.1 添加依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
</dependency>

3.2 创建自定义注解

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 自定义注解，标记需要 IP 白名单保护的方法
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface IpWhiteList {
}

3.3 创建 AOP 切面类

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;

import javax.servlet.http.HttpServletRequest;
import java.io.IOException;
import java.util.Arrays;
import java.util.List;

/**
 * AOP 切面类：检查 IP 是否在白名单中
 */
@Aspect
@Component
public class IpWhiteListAspect {

    @Value("${ip.whitelist}")
    private String whitelistStr;

    private List<String> whiteList;

    public IpWhiteListAspect() {
        // 初始化白名单
        whiteList = Arrays.stream(whitelistStr.split(","))
                .map(String::trim)
                .collect(java.util.stream.Collectors.toList());
    }

    /**
     * 切面逻辑：在方法执行前检查 IP
     */
    @Around("@annotation(IpWhiteList)")
    public Object checkIp(ProceedingJoinPoint joinPoint) throws Throwable {
        HttpServletRequest request = ((ServletRequestAttributes) RequestContextHolder.currentRequestAttributes()).getRequest();
        String clientIP = getClientIP(request);

        if (whiteList.contains(clientIP)) {
            return joinPoint.proceed(); // IP 在白名单中，继续执行方法
        } else {
            throw new AccessDeniedException("IP 未授权访问");
        }
    }

    /**
     * 获取客户端真实 IP（支持代理服务器）
     */
    private String getClientIP(HttpServletRequest request) {
        String ip = request.getHeader("X-Forwarded-For");
        if (ip == null || ip.isEmpty() || "unknown".equalsIgnoreCase(ip)) {
            ip = request.getRemoteAddr();
        }
        return ip;
    }
}

3.4 在方法上使用注解

@RestController
public class DemoController {

    @IpWhiteList
    @GetMapping("/api/test")
    public String test() {
        return "Access granted";
    }
}

3.4 动态白名单（数据库 + 缓存）

4.1 添加依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

4.2 创建数据库表

CREATE TABLE sys_ip_whitelist (
    id INT PRIMARY KEY AUTO_INCREMENT,
    ip VARCHAR(45) NOT NULL
);

4.3 创建实体类

import jakarta.persistence.*;

@Entity
@Table(name = "sys_ip_whitelist")
public class Syshttp://www.devze.comIpWhitelist {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String ip;

    // Getters and Setters
}

4.4 创建 Mapper 接口

import org.springframework.data.jpa.repository.JpaRepository;

public interface SysIpWhitelistRepository extends JpaRepository<SysIpWhitelist, Long> {
    SysIpWhitelist findByIp(String ip);
}

4.5 创建 Service 类

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;
import java.util.concurrent.TimeUnit;

@Service
public class WhiteListService {

    @Autowired
    private SysIpWhitelistRepository repository;

    // 使用 Redis 缓存白名单（示例代码）
    @Autowired
   www.devze.com private RedisTemplate<String, Object> redisTemplate;

    private static final String WHITE_LIST_KEY = "ip:white_list";

    /**
     * 检查 IP 是否在白名单中（支持缓存）
     */
    public boolean isWhiteListed(String ip) {
        // 先查缓存
        List<String> cachedList = (List<String>) redisTemplate.opsForValue().get(WHITE_LIST_KEY);
        if (cachedList != null && cachedList.contains(ip)) {
            return true;
        }

        // 再查数据库
        SysIpWhitelist entity = repository.findByIp(ip);
        if (entity != null) {
            // 更新缓存
            List<String> list = repository.findAll().stream().map(SysIpWhitelist::getIp).collect(Collectors.toList());
            redisTemplate.opsForValue().set(WHITE_LIST_KEY, list, 1, TimeUnit.MINUTES);
            return true;
        }
        return false;
    }
}

4.6 在 Filter 或 AOP 中调用 Service

@Autowired
private WhiteListService whiteListService;

// 在 doFilter 或 checkIp 方法中调用
if (!whiteListService.isWhiteListed(clientIP)) {
    response.sendError(HttpServletResponse.SC_FORBIDDEN, "IP 未授权访问");
}

3.5 Linux 防火墙实现 IP 白名单

5.1 安装 iptables

sudo apt update
sudo apt install iptables

5.2 配置白名单规则

# 允许白名单 IP
sudo iptables -A INPUT -s 192.168.1.1 -j ACCEPT
sudo iptables -A INPUT -s 192.168.1.2 -j ACCEPT

# 拒绝其他所有 IP
sudo iptables -A INPUT -j DROP

5.3 保存规则（可选）

# 安装保存工具
sudo apt install iptables-persistent

# 保存规则
sudo netfilter-persistent save

3.6 基于Interceptor的IP白名单

1. 项目初始化与依赖配置

首先创建一个标准的Spring Boot项目，添加必要依赖：

<dependencies>
    <!-- Spring Boot Starter Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- Lombok简化代码 -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    
    <!-- 配置处理 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-configuration-processor</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

2. IP白名单配置设计

创建配置类IpWhitelistProperties：

@ConfigurationProperties(prefix = "security.ip.whitelist")
@Data
public class IpWhitelistProperties {
    /**
     * 是否启用IP白名单功能
     */
    private boolean enabled = false;
    
    /**
     * 全局IP白名单列表
     */
    private List<String> globalAllowedIps = new ArrayList<>();
    
    /**
     * 监控模式：true-只记录不拦截，false-实际拦截
     */
    private boolean monitorMode = false;
    
    /**
     * 允许的IP段，支持CIDR表示法
     */
    private List<String> allowedIpRanges = new ArrayList<>();
}

对应的application.yml配置示例：

security:
  ip:
    whitelist:
      enabled: true
      global-allowed-ips:
        - 192.168.1.100
        - 172.16.0.50
      allowed-ip-ranges:
        - 10.0.0.0/8
        - 192.168.0.0/16
      monitor-mode: false

3. IP工具类实现

创建IpUtils工具类处理IP相关逻辑：

public class IpUtils {
    private static final String UNKNOWN = "unknown";
    private static final String LOCALHOST_IPV4 = "127.0.0.1";
    private static final String LOCALHOST_IPV6 = "0:0:0:0:0:0:0:1";
    
    /**
     * 获取客户端真实IP地址
     */
    public static String getClientIp(HttpServletRequest request) {
        String ip = request.getHeader("X-Forwarded-For");
        if (StringUtils.isEmpty(ip) || UNKNOWN.equalsIgnoreCase(ip)) {
            ip = request.getHeader("Proxy-Client-IP");
        }
        if (StringUtils.isEmpty(ip) || UNKNOWN.equalsIgnoreCase(ip)) {
            ip = request.getHeader("WL-Proxy-Client-IP");
        }
        if (StringUtils.isEmpty(ip) || UNKNOWN.equalsIgnoreCase(ip)) {
            ip = request.getRemoteAddr();
        }
        // 处理多级代理情况
        if (ip != null && ip.contains(",")) {
            ip = ip.substring(0, ip.indexOf(",")).trim();
        }
        return LOCALHOST_IPV6.equals(ip) ? LOCALHOST_IPV4 : ip;
    }
    
    /**
     * 检查IP是否匹配CIDR表示法的IP段
     */
    public static boolean isIpInRange(String ip, String cidr) {
        // 实现细节...
    }
    
    /**
     * 验证IP地址格式
     */
    public static boolean isValidIp(String ip) {
        // 实现细节...
    }
}

4. 自定义注解设计

创建@IpWhitelist注解支持方法级别的控制：

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface IpWhitelist {
    /**
     * 是否启用IP白名单检查
     */
    boolean enabled() default true;
    
    /**
     * 特定于该接口的允许IP列表
     */
    String[] allowedIps() default {};
    
    /**
     * 特定于该接口的允许IP段(CIDR)
     */
    String[] allowedIpRanges() default {};
    
    /**
     * 拒绝时的错误消息
     */
    String message() default "Access denied by IP whitelist";
}

5. 拦截器核心实现

创建IpWhitelistInterceptor拦截器：

@RequiredArgsConstructor
public class IpWhitelistInterceptor implements HandlerInterceptor {
    private final IpWhitelistProperties properties;
    private final ObjectMapper objectMapper;
    
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        if (!properties.isEnabled()) {
            return true;
        }
        
        // 处理HandlerMethod情况
        if (!(handler instanceof HandlerMethod)) {
            return true;
        }
        
        HandlerMethod handlerMethod = (HandlerMethod) handler;
        Method method = handlerMethod.getMethod();
        
        // 检查类和方法上的注解
        IpWhitelist classAnnotation = handlerMethod.getBeanType().getAnnotation(IpWhitelist.class);
        IpWhitelist methodAnnotation = method.getAnnotation(IpWhitelist.class);
        
        // 如果都没有注解，则跳过检查
        if (classAnnotation == null && methodAnnotation == null) {
            return true;
        }
        
        // 合并注解配置
        boolean enabled = methodAnnotation != null ? methodAnnotation.enabled() : 
                         classAnnotation.enabled();
        String[] allowedIps = methodAnnotation != null && methodAnnotation.allowedIps().length > 0 ? 
                             methodAnnotation.allowedIps() : 
                             classAnnotation != null ? classAnnotation.allowedIps() : new String[0];
        String[] allowedIpRanges = methodAnnotation != null && methodAnnotation.allowedIpRanges().length > 0 ? 
                                  methodAnnotation.allowedIpRanges() : 
                                  classAnnotation != null ? classAnnotation.allowedIpRanges() : new String[0];
        String message = methodAnnotation != null ? methodAnnotation.message() : 
                     android   classAnnotation != null ? classAnnotation.message() : "Access denied by IP whitelist";
        
        if (!enabled) {
            return true;
        }
        
        String clientIp = IpUtils.getClientIp(request);
        
        // 检查全局白名单
        boolean isAllowed = properties.getGlobalAllowedIps().contains(clientIp) || 
                           properties.getAllowedIpRanges().stream()
                               .anyMatch(range -> IpUtils.isIpInRange(clientIp, range));
        
        // 检查注解指定的白名单
        if (!isAllowed) {
            isAllowed = Arrays.stream(allowedIps).anyMatch(ip -> ip.equals(clientIp)) || 
                       Arrays.stream(allowedIpRanges)
                           .anyMatch(range -> IpUtils.isIpInRange(clientIp, range));
        }
        
        if (!isAllowed) {
            if (properties.isMonitorMode()) {
                log.warn("IP whitelist monitor mode triggered. Denied IP: {}", clientIp);
                return true;
            }
            
            response.setContentType(MediaType.APPLICATION_jsON_VALUE);
            response.setStatus(HttpStatus.FORBIDDEN.value());
            response.getWriter().write(objectMapper.writeValueAsString(
                Map.of(
                    "code", 403,
                    "message", message,
                    "data", null
                )
            ));
            return false;
        }
        
        return true;
    }
}

6. 拦截器注册配置

创建Web配置类注册拦截器：

@Configuration
@RequiredArgsConstructor
public class WebConfig implements WebMvcConfigurer {
    private final IpWhitelistProperties ipWhitelistProperties;
    private final ObjectMapper objectMapper;
    
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        if (ipWhitelistProperties.isEnabled()) {
            registry.addInterceptor(new IpWhitelistInterceptor(ipWhitelistProperties, objectMapper))
                .addPathPatterns("/**")
                .order(Ordered.HIGHEST_PRECEDENCE); // 设置最高优先级
        }
    }
}

7. 控制器示例

创建测试控制器验证功能：

@RestController
@RequestMapping("/api")
public class TestController {
    
    @GetMapping("/public")
    public String publicApi() {
        return "This is a public API";
    }
    
    @IpWhitelist
    @GetMapping("/secure")
    public String secureApi() {
        return "This is a secure API with IP whitelist";
    }
    
    @IpWhitelist(
        allowedIps = {"192.168.1.100", "172.16.0.50"},
        allowedIpRanges = {"10.0.0.0/8"},
        message = "Custom IP restriction"
    )
    @GetMapping("/custom")
    public String customApi() {
        return "This API has custom IP whitelist rules";
    }
}

3.7 注意事项

IP 获取问题：
- 如果使用 Nginx 等反向代理，需从 X-Forwarded-For 头获取真实 IP。
- 示例代码已处理代理逻辑。
通配符支持：
- 如果需要支持 CIDR 格式（如 192.168.1.0/24），需自行实现 CIDR 匹配逻辑。
性能优化：
- 动态白名单建议使用缓存（如 Redis）减少数据库查询。
- 高并发场景下，Filter 或 AOP 的性能开销需评估。
安全性：
- 确保白名单逻辑不被绕过（如伪造 X-Forwarded-For 头）。
- 结合其他安全措施（如 HTTPS、JWT）增强防护。

四、进阶实现：基于Spring Security的专业方案

4.1 Spring Security集成概述

对于企业级应用，使用Spring Security可以提供更专业的安全控制。我们将基于前面的基础实现，重构为Spring Security方案。

添加Spring Security依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

4.2 自定义AuthenticationFilter

创建IpAuthenticationFilter：

public class IpAuthenticationFilter extends OncePerRequestFilter {
    private final IpWhitelistProperties properties;
    private final ObjectMapper objectMapper;
    
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) 
            throws ServletException, IOException {
        // 获取请求路径对应的HandlerMethod
        HandlerExecutionChain handlerExecutionChain = null;
        try {
            handlerExecutionChain = ((DispatcherServlet) request.getAttribute(DispatcherServlet.class.getName() + ".CONTEXT"))
                .getHandler(request);
        } catch (Exception e) {
            filterChain.doFilter(request, response);
            return;
        }
        
        if (handlerExecutionChain == null || !(handlerExecutionChain.getHandler() instanceof HandlerMethod)) {
            filterChain.doFilter(request, response);
            return;
        }
        
        HandlerMethod handlerMethod = (HandlerMethod) handlerExecutionChain.getHandler();
        // 后续逻辑与Interceptor类似...
    }
}

4.3 安全配置类

创建安全配置类：

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    private final IpWhitelistProperties ipWhitelistProperties;
    private final ObjectMapper objectMapper;
    
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .csrf().disable()
            .addFilterBefore(new IpAuthenticationFilter(ipWhitelistProperties, objectMapper), 
                           UsernamePasswordAuthenticationFilter.class)
            .authorizeRequests()
                .antMatchers("/api/public").permitAll()
                .anyRequest().authenticated()
            .and()
            .formLogin().disable()
            .httpBasic().disable();
    }
}

4.4 基于表达式的安全控制

Spring Security支持使用@PreAuthorize注解实现更灵活的控制：

@RestController
@RequestMapping("/api/v2")
public class SecureController {
    
    @PreAuthorize("@ipSecurityService.isAllowed(#request)")
    @GetMapping("/expression")
    public String expressionBasedApi(HttpServletRequest request) {
        return "This API uses expression-based IP control";
    }
}

@Service
public class IpSecurityService {
    public boolean isAllowed(HttpServletRequest request) {
        // 实现IP检查逻辑
        return true;
    }
}

五、生产级增强功能

5.1 动态IP白名单管理

实现动态更新白名单而不重启应用：

@Service
public class DynamicIpWhitelistService {
    private final List<String> dynamicAllowedIps = new CopyOnWriteArrayList<>();
    private final List<String> dynamicAllowedIpRanges = new CopyOnWriteArrayList<>();
    
    public synchronized void addAllowedIp(String ip) {
        if (IpUtils.isValidIp(ip) && !dynamicAllowedIps.contains(ip)) {
            dynamicAllowedIps.add(ip);
        }
    }
    
    public synchronized void removeAllowedIp(String ip) {
        dynamicAllowedIps.remove(ip);
    }
    
    public synchronized void reloadIps(List<String> ips) {
        dynamicAllowedIps.clear();
        dynamicAllowedIps.addAll(ips.stream()
            .filter(IpUtils::isValidIp)
            .collect(Collectors.toList()));
    }
    
    // 类似方法实现IP段管理...
}

5.2 结合Redis的分布式IP白名单

对于分布式系统，白名单需要集中存储：

@Configuration
public class RedisIpWhitelistConfig {
    
    @Bean
    public RedisTemplate<String, String> ipWhitelistRedisTemplate(RedisConnectionFactory factory) {
        RedisTemplate<String, String> template = new RedisTemplate<>();
        template.setConnectionFactory(factory);
        template.setKeySerializer(new StringRedisSerializer());
        template.setValueSerializer(new StringRedisSerializer());
        return template;
    }
}

@Service
@RequiredArgsConstructor
public class RedisIpWhitelistService {
    private static final String WHITELIST_KEY = "ip:whitelist";
    private static final String WHITELIST_RANGES_KEY = "ip:whitelist:ranges";
    
    private final RedisTemplate<String, String> redisTemplate;
    
    public boolean isAllowed(String ip) {
        // 检查精确IP
        Boolean isMember = redisTemplate.opsForSet().isMember(WHITELIST_KEY, ip);
        if (Boolean.TRUE.equals(isMember)) {
            return true;
        }
        
        // 检查IP段
        Set<String> ranges = redisTemplate.opsForSet().members(WHITELIST_RANGES_KEY);
        if (ranges != null) {
            return ranges.stream().anyMatch(range -> IpUtils.isIpInRange(ip, range));
        }
        
        return false;
    }
    
    // 其他管理方法...
}

5.3 性能优化与缓存

实现本地缓存减少远程调用：

@Service
public class CachedIpWhitelistService {
    private final LoadingCache<String, Boolean> ipCheckCache;
    
    public CachedIpWhitelistService(RedisIpWhitelistService redisService) {
        this.ipCheckCache = Caffeine.newBuilder()
            .maximumSize(10_000)
            .expireAfterWrite(5, TimeUnit.MINUTES编程客栈)
            .build(redisService::isAllowed);
    }
    
    public boolean isAllowed(String ip) {
        return Boolean.TRUE.equals(ipCheckCache.get(ip));
    }
}

六、测试策略与验证

6.1 单元测试

针对核心工具类编写单元测试：

class IpUtilsTest {
    
    @Test
    void testIsIpInRange() {
        assertTrue(IpUtils.isIpInRange("192.168.1.100", "192.168.1.0/24"));
        assertFalse(IpUtils.isIpInRange("10.0.0.5", "192.168.1.0/24"));
    }
    
    @Test
    void testGetClientIp() {
        // 模拟HttpServletRequest测试各种头部情况
    }
}

6.2 集成测试

使用MockMvc测试完整流程：

@SpringBootTest
@AutoConfigureMockMvc
class IpWhitelistIntegrationTest {
    
    @Autowired
    private MockMvc mockMvc;
    
    @Test
    @WithMockUser
    void testPublicApi() throws Exception {
        mockMvc.perform(get("/api/public"))
            .andExpect(status().isOk());
    }
    
    @Test
    @WithMockUser
    void testSecureApiWithAllowedIp() throws Exception {
        mockMvc.perform(get("/api/secure").with(request -> {
                request.setRemoteAddr("192.168.1.100");
                return request;
            }))
            .andExpect(status().isOk());
    }
    
    @Test
    @WithMockUser
    void testSecureApiWithDeniedIp() throws Exception {
        mockMvc.perform(get("/api/secure").with(request -> {
                request.setRemoteAddr("10.1.2.3");
                return request;
            }))
            .andExpect(status().isForbidden());
    }
}

6.3 性能测试

使用JMeter模拟不同负载下的表现：

SpringBoot中IP白名单控制实现限制接口访问

七、生产环境最佳实践

7.1 安全建议

最小权限原则：只添加必要的IP到白名单
定期审计：每月审查白名单，移除不再需要的IP
日志记录：详细记录所有被拒绝的访问尝试
监控告警：对异常访问模式设置告警
备份机制：定期备份白名单配置

7.2 性能调优

缓存策略：对IP检查结果进行适当缓存
异步检查：对于非关键路径可以考虑异步验证
CIDR优化：将IP段检查算法优化为O(1)复杂度
并发控制：使用线程安全的数据结构
预热机制：应用启动时预加载常用IP

7.3 故障排查指南

常见问题及解决方案：

问题现象	可能原因	解决方案
合法IP被拒绝	IP获取不正确	检查X-Forwarded-For等头部配置
白名单修改后不生效	缓存未刷新	实现配置变更通知机制
性能下降	IP检查成为瓶颈	引入缓存、优化算法或水平扩展
分布式环境不一致	各节点白名单不同步	使用集中式存储如Redis
IPv6支持问题	只配置了IPv4	确保同时支持IPv4和IPv6格式

八、扩展与演进

8.1 结合微服务架构

在Spring Cloud体系中，可以在网关层统一实现IP白名单：

@Bean
public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("secure-service", r -> r.path("/api/secure/**")
            .filters(f -> f.filter(new IpWhitelistGatewayFilter()))
            .uri("lb://secure-service"))
        .build();
}

8.2 Kubernetes环境适配

在K8s中需要考虑Pod IP动态变化的问题：

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: api-whitelist
spec:
  podSelector:
    matchLabels:
      app: spring-boot-app
  ingress:
  - from:
    - ipblock:
        cidr: 192.168.1.0/24
    ports:
    - protocol: TCP
      port: 8080

8.3 未来演进方向

机器学习分析：自动识别异常IP并动态调整白名单
区块链存证：将白名单变更记录上链确保不可篡改
零信任整合：与零信任架构深度集成
IoT扩展：支持设备指纹等更多维度的认证
量子安全：为后量子时代提前准备加密方案

九、总结与展望

本文详细探讨了在Spring Boot应用中实现IP白名单控制的多种方案，从基础的Interceptor实现到基于Spring Security的专业方案，再到生产级的增强功能和分布式环境适配。通过本教程，您应该能够：

深入理解IP白名单的原理和价值
掌握在Spring Boot中实现IP控制的多种技术
具备构建生产级IP白名单系统的能力
了解相关的最佳实践和优化策略

IP白名单作为网络安全的基础设施之一，在云原生和微服务架构不断演进的今天，仍然发挥着不可替代的作用。未来，随着边缘计算和5G技术的普及，IP白名单技术可能会与更多新兴技术融合，形成更智能、更灵活的访问控制体系。

到此这篇关于SpringBoot中IP白名单控制实现限制接口访问的文章就介绍到这了,更多相关SpringBoot IP白名单内容请搜索编程客栈(www.devze.com)以前的文章或继续浏览下面的相关文章希望大家以后多多支持编程客栈(www.devze.com)！

继续阅读：SpringBoot IP白名单 SpringBoot IP限制接口访问

目录

一、IP白名单控制概述

1.1 什么是IP白名单

1.2 IP白名单 vs 黑名单

1.3 IP白名单的应用场景

二、Spring Boot中实现IP白名单的技术选型

2.1 实现方案对比

1. 自定义 Filter 实现

2. Spring Security 集成

3. AOP（面向切面编程）

4. 动态白名单（结合数据库）

5. 使用 Linux 防火墙（iptables/nftables）

6. 基于Interceptor的IP白名单

6. 技术选型对比表

三、完整实现方案

3.1 自定义 Filter 实现 IP 白名单

3.2 Spring Security 实现 IP 白名单

3.3 AOP 实现 IP 白名单

3.4 动态白名单（数据库 + 缓存）

3.5 Linux 防火墙实现 IP 白名单

3.6 基于Interceptor的IP白名单

3.7 注意事项

四、进阶实现：基于Spring Security的专业方案

4.1 Spring Security集成概述

4.2 自定义AuthenticationFilter

4.3 安全配置类

4.4 基于表达式的安全控制

五、生产级增强功能

5.1 动态IP白名单管理

5.2 结合Redis的分布式IP白名单

5.3 性能优化与缓存

六、测试策略与验证

6.1 单元测试

6.2 集成测试

6.3 性能测试

七、生产环境最佳实践

7.1 安全建议

7.2 性能调优

7.3 故障排查指南

八、扩展与演进

8.1 结合微服务架构

8.2 Kubernetes环境适配

8.3 未来演进方向

九、总结与展望

更多精彩内容

精彩评论

最新开发

Go-Swagger的踩坑记录分享

使用Go语言创建一个简单的HTTP服务器的示例代码

全面解析Golang 中的 Gorilla CORS 中间件正确用法

C++中sizeof运算符全面详解和代码示例

C# System.Net.Dns 使用详解

开发排行榜

springboot后端存储富文本内容的思路与步骤(含图片内容)

PyCharm运行python测试,报错“没有发现测试”/“空套件”的解决

return base64.b64encode(b).decode(

基于C语言实现钻石棋游戏的示例代码

Sublime Text 3解决中文乱码问题（实测可用）