背景：敏感接口的安全挑战

在微服务架构中，Spring Cloud Gateway 作为系统的统一入口，承担着流量控制、安全防护、路由转发等重要职责。然而，在实际生产环境中，我们经常遇到以下安全挑战：

• 敏感接口暴露：敏感接口（如管理后台、支付接口等）暴露在外网，面临被攻击的风险
• 地域限制需求：某些敏感接口只允许特定地区的用户访问，如仅允许中国大陆用户访问
• IP 封禁困难：传统的 IP 封禁方式需要手动维护，效率低，容易遗漏
• 恶意攻击频发：来自特定地区的恶意攻击，需要快速封禁
• 合规性要求：某些业务需要满足地域合规性要求，如数据不出境

传统的安全防护方式通常采用以下策略：

1. 应用层防护：在应用代码中实现地域校验，实现复杂，容易遗漏
2. Nginx 防护：使用 Nginx 的 GeoIP 模块，需要额外配置，灵活性差
3. 防火墙防护：使用硬件防火墙，成本高，配置复杂
4. CDN 防护：使用 CDN 的地域封禁功能，依赖第三方，成本高

这些方式各有优缺点，但都存在一定的局限性。本文将介绍如何使用 Spring Cloud Gateway 实现 IP 黑白名单和地域封禁，在网关层直接拦截非法请求，保护敏感接口。

核心概念

1. IP 黑白名单

IP 黑白名单是指根据 IP 地址进行访问控制，黑名单中的 IP 被拒绝访问，白名单中的 IP 被允许访问。实现方式通常有：

2. 地域封禁

地域封禁是指根据 IP 地址的地域信息进行访问控制，只允许或禁止特定地区的用户访问。实现方式通常有：

3. 敏感接口保护

敏感接口保护是指对敏感接口进行额外的安全防护，确保只有合法的用户才能访问。防护策略包括：

4. IP 地址解析

IP 地址解析是指从请求中获取真实的客户端 IP 地址。获取方式通常有：

技术实现

1. 核心依赖

<!-- Spring Boot Starter Web -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- Spring Cloud Gateway -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>

<!-- Spring Boot Starter Data Redis -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

<!-- GeoIP2 -->
<dependency>
    <groupId>com.maxmind.geoip2</groupId>
    <artifactId>geoip2</artifactId>
    <version>4.0.1</version>
</dependency>

<!-- Spring Boot Starter Actuator -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

<!-- FastJSON -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.2.83</version>
</dependency>

<!-- Lombok -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>

<!-- Apache Commons Net -->
<dependency>
    <groupId>commons-net</groupId>
    <artifactId>commons-net</artifactId>
    <version>3.9.0</version>
</dependency>

2. 网关配置

server:
  port: 8080

spring:
  application:
    name: gateway-geo-service
  
  cloud:
    gateway:
      # 路由配置
      routes:
        # 管理后台路由
        - id: admin-service
          uri: lb://admin-service
          predicates:
            - Path=/api/admin/**
          filters:
            # IP 白名单
            - name: IpWhiteList
              args:
                enabled: true
                ips:
                  - 192.168.1.0/24
                  - 10.0.0.0/8
            # 地域白名单
            - name: GeoWhiteList
              args:
                enabled: true
                countries:
                  - CN
        
        # 支付服务路由
        - id: payment-service
          uri: lb://payment-service
          predicates:
            - Path=/api/payment/**
          filters:
            # 地域白名单
            - name: GeoWhiteList
              args:
                enabled: true
                countries:
                  - CN
                provinces:
                  - 北京
                  - 上海
                  - 广东
        
        # 用户服务路由
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/api/user/**
          filters:
            # IP 黑名单
            - name: IpBlackList
              args:
                enabled: true
                ips:
                  - 192.168.1.100
                  - 10.0.0.50
      
      # 全局CORS配置
      globalcors:
        corsConfigurations:
          '[/**]':
            allowedOrigins: "*"
            allowedMethods:
              - GET
              - POST
              - PUT
              - DELETE
              - OPTIONS
            allowedHeaders: "*"
            allowCredentials: true
            maxAge: 3600
  
  # Redis配置
  redis:
    host: localhost
    port: 6379
    password:
    database: 0
    timeout: 3000
    lettuce:
      pool:
        max-active: 8
        max-wait: -1
        max-idle: 8
        min-idle: 0

# 网关安全配置
gateway:
  security:
    # IP 黑白名单配置
    ip-filter:
      enabled: true
      # 黑名单配置
      blacklist:
        enabled: true
        # 黑名单 IP 列表（支持 CIDR）
        ips:
          - 192.168.1.100
          - 10.0.0.50
          - 172.16.0.0/12
      # 白名单配置
      whitelist:
        enabled: true
        # 白名单 IP 列表（支持 CIDR）
        ips:
          - 192.168.1.0/24
          - 10.0.0.0/8
        # 路由特定白名单
        route-specific:
          admin-service:
            - 192.168.1.0/24
          payment-service:
            - 10.0.0.0/8
    
    # 地域封禁配置
    geo-filter:
      enabled: true
      # GeoIP 数据库路径
      geoip-database-path: classpath:GeoLite2-Country.mmdb
      # 白名单国家
      whitelist-countries:
        - CN
      # 白名单省份（仅支持国内）
      whitelist-provinces:
        - 北京
        - 上海
        - 广东
      # 黑名单国家
      blacklist-countries:
        - KP  # 朝鲜
        - IR  # 伊朗
      # 路由特定地域配置
      route-specific:
        admin-service:
          whitelist-countries:
            - CN
          whitelist-provinces:
            - 北京
        payment-service:
          whitelist-countries:
            - CN
    
    # 敏感接口配置
    sensitive:
      # 敏感接口路径模式
      paths:
        - /api/admin/**
        - /api/payment/**
        - /api/sensitive/**
      # 敏感接口额外防护
      extra-protection:
        enabled: true
        # 是否需要多因素认证
        require-mfa: true
        # 访问频率限制
        rate-limit:
          enabled: true
          requests-per-minute: 10
        # 审计日志
        audit-log:
          enabled: true

# Actuator配置
management:
  endpoints:
    web:
      exposure:
        include: health,info,gateway
  endpoint:
    health:
      show-details: always

# 日志配置
logging:
  level:
    org.springframework.cloud.gateway: info
    org.springframework.web.reactive: warn
    com.example.demo: info

3. IP 工具类

@Component
@Slf4j
public class IpUtils {

    /**
     * 获取客户端真实 IP
     */
    public static String getClientIp(ServerWebExchange exchange) {
        String ip = exchange.getRequest().getHeaders().getFirst("X-Forwarded-For");
        if (isValidIp(ip)) {
            ip = ip.split(",")[0].trim();
        } else {
            ip = exchange.getRequest().getHeaders().getFirst("X-Real-IP");
        }
        
        if (!isValidIp(ip)) {
            ip = exchange.getRequest().getHeaders().getFirst("CF-Connecting-IP");
        }
        
        if (!isValidIp(ip)) {
            ip = exchange.getRequest().getHeaders().getFirst("X-Forwarded");
        }
        
        if (!isValidIp(ip)) {
            ip = exchange.getRequest().getHeaders().getFirst("Forwarded-For");
        }
        
        if (!isValidIp(ip)) {
            ip = exchange.getRequest().getHeaders().getFirst("Forwarded");
        }
        
        if (!isValidIp(ip)) {
            ip = exchange.getRequest().getRemoteAddress() != null ?
                    exchange.getRequest().getRemoteAddress().getAddress().getHostAddress() : "";
        }
        
        return ip;
    }

    /**
     * 验证 IP 是否有效
     */
    public static boolean isValidIp(String ip) {
        return ip != null && !ip.isEmpty() && !"unknown".equalsIgnoreCase(ip);
    }

    /**
     * 检查 IP 是否在 CIDR 范围内
     */
    public static boolean isIpInRange(String ip, String cidr) {
        try {
            String[] parts = cidr.split("/");
            String network = parts[0];
            int prefix = Integer.parseInt(parts[1]);
            
            byte[] ipBytes = InetAddress.getByName(ip).getAddress();
            byte[] networkBytes = InetAddress.getByName(network).getAddress();
            
            int mask = 0xFFFFFFFF << (32 - prefix);
            
            int ipInt = ((ipBytes[0] & 0xFF) << 24) |
                       ((ipBytes[1] & 0xFF) << 16) |
                       ((ipBytes[2] & 0xFF) << 8) |
                       (ipBytes[3] & 0xFF);
            
            int networkInt = ((networkBytes[0] & 0xFF) << 24) |
                            ((networkBytes[1] & 0xFF) << 16) |
                            ((networkBytes[2] & 0xFF) << 8) |
                            (networkBytes[3] & 0xFF);
            
            return (ipInt & mask) == (networkInt & mask);
        } catch (Exception e) {
            log.error("Failed to check IP range: ip={}, cidr={}", ip, cidr, e);
            return false;
        }
    }

    /**
     * 检查 IP 是否匹配规则
     */
    public static boolean isIpMatch(String ip, String rule) {
        if (rule.contains("/")) {
            return isIpInRange(ip, rule);
        } else {
            return ip.equals(rule);
        }
    }

}

4. IP 黑白名单过滤器

@Component
@Slf4j
public class IpBlackWhiteListFilter implements GlobalFilter, Ordered {

    @Value("${gateway.security.ip-filter.enabled:true}")
    private boolean enabled;

    @Value("${gateway.security.ip-filter.blacklist.enabled:true}")
    private boolean blacklistEnabled;

    @Value("${gateway.security.ip-filter.blacklist.ips:}")
    private List<String> blacklist;

    @Value("${gateway.security.ip-filter.whitelist.enabled:true}")
    private boolean whitelistEnabled;

    @Value("${gateway.security.ip-filter.whitelist.ips:}")
    private List<String> whitelist;

    @Autowired
    private RedisTemplate<String, String> redisTemplate;

    private static final String IP_BLACKLIST_REDIS_KEY = "gateway:ip:blacklist";
    private static final String IP_WHITELIST_REDIS_KEY = "gateway:ip:whitelist";

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        if (!enabled) {
            return chain.filter(exchange);
        }

        String clientIp = IpUtils.getClientIp(exchange);
        String path = exchange.getRequest().getPath().value();

        log.debug("Checking IP filter for IP: {}, path: {}", clientIp, path);

        // 检查黑名单
        if (blacklistEnabled && isIpInBlacklist(clientIp)) {
            log.warn("IP {} is in blacklist, path: {}", clientIp, path);
            return rejectRequest(exchange, "IP is in blacklist", clientIp);
        }

        // 检查白名单（如果配置了白名单）
        if (whitelistEnabled && !whitelist.isEmpty() && !isIpInWhitelist(clientIp)) {
            log.warn("IP {} is not in whitelist, path: {}", clientIp, path);
            return rejectRequest(exchange, "IP is not in whitelist", clientIp);
        }

        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return Ordered.HIGHEST_PRECEDENCE;
    }

    /**
     * 检查 IP 是否在黑名单中
     */
    private boolean isIpInBlacklist(String ip) {
        // 检查配置文件中的黑名单
        for (String rule : blacklist) {
            if (IpUtils.isIpMatch(ip, rule)) {
                return true;
            }
        }

        // 检查 Redis 中的动态黑名单
        return Boolean.TRUE.equals(redisTemplate.opsForSet().isMember(IP_BLACKLIST_REDIS_KEY, ip));
    }

    /**
     * 检查 IP 是否在白名单中
     */
    private boolean isIpInWhitelist(String ip) {
        // 检查配置文件中的白名单
        for (String rule : whitelist) {
            if (IpUtils.isIpMatch(ip, rule)) {
                return true;
            }
        }

        // 检查 Redis 中的动态白名单
        return Boolean.TRUE.equals(redisTemplate.opsForSet().isMember(IP_WHITELIST_REDIS_KEY, ip));
    }

    /**
     * 拒绝请求
     */
    private Mono<Void> rejectRequest(ServerWebExchange exchange, String message, String ip) {
        exchange.getResponse().setStatusCode(HttpStatus.FORBIDDEN);
        exchange.getResponse().getHeaders().setContentType(MediaType.APPLICATION_JSON);

        Map<String, Object> errorResponse = new HashMap<>();
        errorResponse.put("code", 403);
        errorResponse.put("message", message);
        errorResponse.put("ip", ip);
        errorResponse.put("timestamp", System.currentTimeMillis());

        DataBuffer buffer = exchange.getResponse().bufferFactory()
                .wrap(JSON.toJSONString(errorResponse).getBytes());
        return exchange.getResponse().writeWith(Mono.just(buffer));
    }

    /**
     * 添加 IP 到黑名单（动态）
     */
    public void addToBlacklist(String ip, long expireSeconds) {
        if (expireSeconds > 0) {
            redisTemplate.opsForSet().add(IP_BLACKLIST_REDIS_KEY, ip);
            redisTemplate.expire(IP_BLACKLIST_REDIS_KEY, expireSeconds, TimeUnit.SECONDS);
        } else {
            redisTemplate.opsForSet().add(IP_BLACKLIST_REDIS_KEY, ip);
        }
        log.info("Added IP {} to blacklist", ip);
    }

    /**
     * 从黑名单移除 IP
     */
    public void removeFromBlacklist(String ip) {
        redisTemplate.opsForSet().remove(IP_BLACKLIST_REDIS_KEY, ip);
        log.info("Removed IP {} from blacklist", ip);
    }

    /**
     * 添加 IP 到白名单（动态）
     */
    public void addToWhitelist(String ip, long expireSeconds) {
        if (expireSeconds > 0) {
            redisTemplate.opsForSet().add(IP_WHITELIST_REDIS_KEY, ip);
            redisTemplate.expire(IP_WHITELIST_REDIS_KEY, expireSeconds, TimeUnit.SECONDS);
        } else {
            redisTemplate.opsForSet().add(IP_WHITELIST_REDIS_KEY, ip);
        }
        log.info("Added IP {} to whitelist", ip);
    }

    /**
     * 从白名单移除 IP
     */
    public void removeFromWhitelist(String ip) {
        redisTemplate.opsForSet().remove(IP_WHITELIST_REDIS_KEY, ip);
        log.info("Removed IP {} from whitelist", ip);
    }

}

5. 地域过滤器

@Component
@Slf4j
public class GeoFilter implements GlobalFilter, Ordered {

    @Value("${gateway.security.geo-filter.enabled:true}")
    private boolean enabled;

    @Value("${gateway.security.geo-filter.geoip-database-path:}")
    private String geoipDatabasePath;

    @Value("${gateway.security.geo-filter.whitelist-countries:}")
    private List<String> whitelistCountries;

    @Value("${gateway.security.geo-filter.whitelist-provinces:}")
    private List<String> whitelistProvinces;

    @Value("${gateway.security.geo-filter.blacklist-countries:}")
    private List<String> blacklistCountries;

    private DatabaseReader geoIpReader;

    @PostConstruct
    public void init() {
        if (!enabled) {
            return;
        }

        try {
            File database = new File(geoipDatabasePath);
            if (!database.exists()) {
                // 尝试从 classpath 加载
                ClassPathResource resource = new ClassPathResource(geoipDatabasePath);
                if (resource.exists()) {
                    geoIpReader = new DatabaseReader.Builder(resource.getInputStream()).build();
                    log.info("GeoIP database loaded from classpath: {}", geoipDatabasePath);
                } else {
                    log.warn("GeoIP database not found: {}", geoipDatabasePath);
                }
            } else {
                geoIpReader = new DatabaseReader.Builder(database).build();
                log.info("GeoIP database loaded from file: {}", geoipDatabasePath);
            }
        } catch (Exception e) {
            log.error("Failed to load GeoIP database", e);
        }
    }

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        if (!enabled || geoIpReader == null) {
            return chain.filter(exchange);
        }

        String clientIp = IpUtils.getClientIp(exchange);
        String path = exchange.getRequest().getPath().value();

        log.debug("Checking geo filter for IP: {}, path: {}", clientIp, path);

        try {
            GeoInfo geoInfo = getGeoInfo(clientIp);
            
            if (geoInfo == null) {
                log.warn("Failed to get geo info for IP: {}", clientIp);
                return rejectRequest(exchange, "Unable to determine location", clientIp);
            }

            // 检查黑名单国家
            if (!blacklistCountries.isEmpty() && blacklistCountries.contains(geoInfo.getCountry())) {
                log.warn("Country {} is in blacklist, IP: {}, path: {}", 
                        geoInfo.getCountry(), clientIp, path);
                return rejectRequest(exchange, "Access denied from your location", clientIp, geoInfo);
            }

            // 检查白名单国家
            if (!whitelistCountries.isEmpty() && !whitelistCountries.contains(geoInfo.getCountry())) {
                log.warn("Country {} is not in whitelist, IP: {}, path: {}", 
                        geoInfo.getCountry(), clientIp, path);
                return rejectRequest(exchange, "Access restricted to specific regions", clientIp, geoInfo);
            }

            // 检查白名单省份（仅对中国）
            if ("CN".equals(geoInfo.getCountry()) && !whitelistProvinces.isEmpty()) {
                if (!whitelistProvinces.contains(geoInfo.getProvince())) {
                    log.warn("Province {} is not in whitelist, IP: {}, path: {}", 
                            geoInfo.getProvince(), clientIp, path);
                    return rejectRequest(exchange, "Access restricted to specific provinces", clientIp, geoInfo);
                }
            }

            // 将地域信息添加到请求头，供后续使用
            ServerHttpRequest request = exchange.getRequest().mutate()
                    .header("X-Country", geoInfo.getCountry())
                    .header("X-Province", geoInfo.getProvince() != null ? geoInfo.getProvince() : "")
                    .header("X-City", geoInfo.getCity() != null ? geoInfo.getCity() : "")
                    .build();

            return chain.filter(exchange.mutate().request(request).build());

        } catch (Exception e) {
            log.error("Failed to check geo filter for IP: {}", clientIp, e);
            return rejectRequest(exchange, "Geo filter error", clientIp);
        }
    }

    @Override
    public int getOrder() {
        return Ordered.HIGHEST_PRECEDENCE + 1;
    }

    /**
     * 获取地域信息
     */
    private GeoInfo getGeoInfo(String ip) {
        try {
            InetAddress ipAddress = InetAddress.getByName(ip);
            CountryResponse countryResponse = geoIpReader.country(ipAddress);
            
            GeoInfo geoInfo = new GeoInfo();
            geoInfo.setCountry(countryResponse.getCountry().getIsoCode());
            geoInfo.setCountryName(countryResponse.getCountry().getName());
            
            // 尝试获取城市信息（需要 GeoLite2-City 数据库）
            try {
                CityResponse cityResponse = geoIpReader.city(ipAddress);
                geoInfo.setCity(cityResponse.getCity().getName());
                
                // 获取省份信息
                if (!cityResponse.getSubdivisions().isEmpty()) {
                    geoInfo.setProvince(cityResponse.getSubdivisions().get(0).getName());
                }
            } catch (Exception e) {
                log.debug("City info not available for IP: {}", ip);
            }
            
            return geoInfo;
        } catch (Exception e) {
            log.error("Failed to get geo info for IP: {}", ip, e);
            return null;
        }
    }

    /**
     * 拒绝请求
     */
    private Mono<Void> rejectRequest(ServerWebExchange exchange, String message, 
                                     String ip, GeoInfo geoInfo) {
        exchange.getResponse().setStatusCode(HttpStatus.FORBIDDEN);
        exchange.getResponse().getHeaders().setContentType(MediaType.APPLICATION_JSON);

        Map<String, Object> errorResponse = new HashMap<>();
        errorResponse.put("code", 403);
        errorResponse.put("message", message);
        errorResponse.put("ip", ip);
        if (geoInfo != null) {
            errorResponse.put("country", geoInfo.getCountry());
            errorResponse.put("countryName", geoInfo.getCountryName());
        }
        errorResponse.put("timestamp", System.currentTimeMillis());

        DataBuffer buffer = exchange.getResponse().bufferFactory()
                .wrap(JSON.toJSONString(errorResponse).getBytes());
        return exchange.getResponse().writeWith(Mono.just(buffer));
    }

    private Mono<Void> rejectRequest(ServerWebExchange exchange, String message, String ip) {
        return rejectRequest(exchange, message, ip, null);
    }

    /**
     * 地域信息
     */
    @Data
    public static class GeoInfo {
        private String country;
        private String countryName;
        private String province;
        private String city;
    }

}

6. 敏感接口过滤器

@Component
@Slf4j
public class SensitiveInterfaceFilter implements GlobalFilter, Ordered {

    @Value("${gateway.security.sensitive.paths:}")
    private List<String> sensitivePaths;

    @Value("${gateway.security.sensitive.extra-protection.enabled:true}")
    private boolean extraProtectionEnabled;

    @Value("${gateway.security.sensitive.extra-protection.require-mfa:true}")
    private boolean requireMfa;

    @Value("${gateway.security.sensitive.extra-protection.rate-limit.enabled:true}")
    private boolean rateLimitEnabled;

    @Value("${gateway.security.sensitive.extra-protection.rate-limit.requests-per-minute:10}")
    private int requestsPerMinute;

    @Value("${gateway.security.sensitive.extra-protection.audit-log.enabled:true}")
    private boolean auditLogEnabled;

    @Autowired
    private RedisTemplate<String, String> redisTemplate;

    @Autowired
    private AuditLogService auditLogService;

    private static final String RATE_LIMIT_PREFIX = "gateway:sensitive:rate:";

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String path = exchange.getRequest().getPath().value();

        // 检查是否是敏感接口
        if (!isSensitivePath(path)) {
            return chain.filter(exchange);
        }

        String clientIp = IpUtils.getClientIp(exchange);
        String userId = exchange.getRequest().getHeaders().getFirst("X-User-Id");

        log.info("Sensitive interface accessed: path={}, ip={}, userId={}", path, clientIp, userId);

        // 检查多因素认证
        if (requireMfa && !checkMfa(exchange)) {
            log.warn("MFA required but not provided: path={}, ip={}", path, clientIp);
            return rejectRequest(exchange, "Multi-factor authentication required", clientIp);
        }

        // 检查访问频率
        if (rateLimitEnabled && !checkRateLimit(clientIp, path)) {
            log.warn("Rate limit exceeded: path={}, ip={}", path, clientIp);
            return rejectRequest(exchange, "Rate limit exceeded", clientIp);
        }

        // 记录审计日志
        if (auditLogEnabled) {
            auditLogService.logAccess(clientIp, userId, path, exchange.getRequest().getMethodValue());
        }

        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return Ordered.HIGHEST_PRECEDENCE + 2;
    }

    /**
     * 检查是否是敏感路径
     */
    private boolean isSensitivePath(String path) {
        for (String pattern : sensitivePaths) {
            if (pathMatcher.match(pattern, path)) {
                return true;
            }
        }
        return false;
    }

    /**
     * 检查多因素认证
     */
    private boolean checkMfa(ServerWebExchange exchange) {
        String mfaToken = exchange.getRequest().getHeaders().getFirst("X-MFA-Token");
        return mfaToken != null && !mfaToken.isEmpty();
    }

    /**
     * 检查访问频率
     */
    private boolean checkRateLimit(String ip, String path) {
        String key = RATE_LIMIT_PREFIX + ip + ":" + path;
        
        Long count = redisTemplate.opsForValue().increment(key);
        if (count == 1) {
            redisTemplate.expire(key, 1, TimeUnit.MINUTES);
        }
        
        return count <= requestsPerMinute;
    }

    /**
     * 拒绝请求
     */
    private Mono<Void> rejectRequest(ServerWebExchange exchange, String message, String ip) {
        exchange.getResponse().setStatusCode(HttpStatus.FORBIDDEN);
        exchange.getResponse().getHeaders().setContentType(MediaType.APPLICATION_JSON);

        Map<String, Object> errorResponse = new HashMap<>();
        errorResponse.put("code", 403);
        errorResponse.put("message", message);
        errorResponse.put("ip", ip);
        errorResponse.put("timestamp", System.currentTimeMillis());

        DataBuffer buffer = exchange.getResponse().bufferFactory()
                .wrap(JSON.toJSONString(errorResponse).getBytes());
        return exchange.getResponse().writeWith(Mono.just(buffer));
    }

}

7. 审计日志服务

@Service
@Slf4j
public class AuditLogService {

    @Autowired
    private RedisTemplate<String, String> redisTemplate;

    private static final String AUDIT_LOG_KEY = "gateway:audit:log";

    /**
     * 记录访问日志
     */
    public void logAccess(String ip, String userId, String path, String method) {
        AuditLogEntry entry = new AuditLogEntry();
        entry.setIp(ip);
        entry.setUserId(userId);
        entry.setPath(path);
        entry.setMethod(method);
        entry.setTimestamp(System.currentTimeMillis());

        String logEntry = JSON.toJSONString(entry);
        redisTemplate.opsForList().leftPush(AUDIT_LOG_KEY, logEntry);
        
        // 保留最近 10000 条日志
        redisTemplate.opsForList().trim(AUDIT_LOG_KEY, 0, 9999);

        log.info("Audit log: {}", logEntry);
    }

    /**
     * 获取审计日志
     */
    public List<AuditLogEntry> getAuditLogs(int count) {
        List<String> logs = redisTemplate.opsForList().range(AUDIT_LOG_KEY, 0, count - 1);
        if (logs == null) {
            return Collections.emptyList();
        }

        return logs.stream()
                .map(log -> JSON.parseObject(log, AuditLogEntry.class))
                .collect(Collectors.toList());
    }

    /**
     * 审计日志条目
     */
    @Data
    public static class AuditLogEntry {
        private String ip;
        private String userId;
        private String path;
        private String method;
        private long timestamp;
    }

}

8. 管理控制器

@RestController
@RequestMapping("/api/gateway/admin")
@Slf4j
public class AdminController {

    @Autowired
    private IpBlackWhiteListFilter ipFilter;

    @Autowired
    private AuditLogService auditLogService;

    @Autowired
    private RedisTemplate<String, String> redisTemplate;

    /**
     * 添加 IP 到黑名单
     */
    @PostMapping("/ip/blacklist")
    public Result<String> addToBlacklist(@RequestParam String ip, 
                                          @RequestParam(defaultValue = "0") long expireSeconds) {
        ipFilter.addToBlacklist(ip, expireSeconds);
        return Result.success("IP added to blacklist");
    }

    /**
     * 从黑名单移除 IP
     */
    @DeleteMapping("/ip/blacklist")
    public Result<String> removeFromBlacklist(@RequestParam String ip) {
        ipFilter.removeFromBlacklist(ip);
        return Result.success("IP removed from blacklist");
    }

    /**
     * 添加 IP 到白名单
     */
    @PostMapping("/ip/whitelist")
    public Result<String> addToWhitelist(@RequestParam String ip,
                                          @RequestParam(defaultValue = "0") long expireSeconds) {
        ipFilter.addToWhitelist(ip, expireSeconds);
        return Result.success("IP added to whitelist");
    }

    /**
     * 从白名单移除 IP
     */
    @DeleteMapping("/ip/whitelist")
    public Result<String> removeFromWhitelist(@RequestParam String ip) {
        ipFilter.removeFromWhitelist(ip);
        return Result.success("IP removed from whitelist");
    }

    /**
     * 获取审计日志
     */
    @GetMapping("/audit/logs")
    public Result<List<AuditLogService.AuditLogEntry>> getAuditLogs(
            @RequestParam(defaultValue = "100") int count) {
        List<AuditLogService.AuditLogEntry> logs = auditLogService.getAuditLogs(count);
        return Result.success(logs);
    }

    /**
     * 获取网关状态
     */
    @GetMapping("/status")
    public Result<GatewayStatus> getGatewayStatus() {
        GatewayStatus status = new GatewayStatus();
        status.setStatus("UP");
        status.setTimestamp(System.currentTimeMillis());
        status.setVersion("1.0.0");
        return Result.success(status);
    }

    @Data
    public static class GatewayStatus {
        private String status;
        private long timestamp;
        private String version;
    }

}

核心流程

1. 请求处理流程

1. 请求到达：客户端请求到达网关
2. IP 黑名单检查：检查客户端 IP 是否在黑名单中
3. IP 白名单检查：检查客户端 IP 是否在白名单中
4. 地域检查：检查客户端 IP 的地域是否在允许范围内
5. 敏感接口检查：如果是敏感接口，进行额外的安全检查
6. 路由匹配：匹配到对应的路由
7. 后端服务调用：调用后端服务
8. 响应返回：返回响应给客户端

2. IP 黑白名单检查流程

1. 获取客户端 IP：从请求头或连接中获取真实 IP
2. 检查黑名单：检查 IP 是否在黑名单中
3. 检查白名单：检查 IP 是否在白名单中
4. 返回错误：如果在黑名单或不在白名单，返回 403 错误
5. 继续处理：如果通过检查，继续处理请求

3. 地域检查流程

1. 获取客户端 IP：从请求头或连接中获取真实 IP
2. 查询 GeoIP：使用 GeoIP 库查询 IP 的地域信息
3. 检查黑名单国家：检查国家是否在黑名单中
4. 检查白名单国家：检查国家是否在白名单中
5. 检查白名单省份：如果是中国，检查省份是否在白名单中
6. 添加地域头：将地域信息添加到请求头
7. 返回错误：如果未通过检查，返回 403 错误

4. 敏感接口检查流程

1. 检查敏感路径：检查请求路径是否是敏感接口
2. 检查 MFA：检查是否提供了多因素认证
3. 检查访问频率：检查访问频率是否超过限制
4. 记录审计日志：记录访问日志
5. 返回错误：如果未通过检查，返回 403 错误

技术要点

1. IP 地址获取

• 多层代理支持：支持 X-Forwarded-For、X-Real-IP、CDN 头等多种方式
• IP 验证：验证 IP 地址的有效性
• 优先级：按照优先级依次尝试获取真实 IP

2. CIDR 匹配

• 支持 CIDR：支持使用 CIDR 表示法匹配 IP 段
• 精确匹配：支持精确匹配单个 IP
• 性能优化：使用位运算提高匹配性能

3. GeoIP 数据库

• MaxMind GeoIP2：使用 MaxMind GeoIP2 数据库
• 自动加载：支持从文件或 classpath 加载
• 错误处理：数据库加载失败时优雅降级

4. 动态配置

• Redis 存储：支持从 Redis 动态加载黑白名单
• 实时生效：配置变更实时生效，无需重启
• 过期时间：支持设置黑白名单的过期时间

5. 审计日志

• Redis 存储：使用 Redis 存储审计日志
• 自动清理：自动清理过期日志，保留最近 10000 条
• 查询接口：提供查询接口，方便审计

最佳实践

1. IP 黑白名单管理

• 定期更新：定期更新黑白名单，及时响应威胁
• 动态管理：使用管理接口动态添加/移除 IP
• 分类管理：对不同类型的 IP 进行分类管理
• 过期时间：为临时封禁的 IP 设置过期时间

2. 地域封禁策略

• 白名单优先：优先使用白名单，明确允许的地区
• 最小权限：只允许必要的地区访问
• 定期审查：定期审查地域封禁策略
• 合规性：确保符合业务合规性要求

3. 敏感接口保护

• 多层防护：结合 IP、地域、MFA 等多种防护手段
• 访问频率限制：限制敏感接口的访问频率
• 审计日志：记录所有敏感接口的访问日志
• 告警机制：异常访问时及时告警

4. 监控告警

• 实时监控：实时监控访问情况
• 异常检测：检测异常访问模式
• 告警机制：异常时及时通知
• 趋势分析：分析访问趋势，优化策略

常见问题

1. IP 获取不准确

问题：获取到的 IP 不是真实客户端 IP

解决方案：

• 检查代理配置，确保正确传递 X-Forwarded-For 头
• 使用 CDN 时，检查 CDN 传递的头信息
• 配置信任的代理 IP 列表

2. GeoIP 数据库过期

问题：GeoIP 数据库过期，地域判断不准确

解决方案：

• 定期更新 GeoIP 数据库
• 使用在线 API 作为备用方案
• 配置数据库自动更新

3. 误判率高

问题：正常用户被误判为恶意用户

解决方案：

• 优化黑白名单规则
• 使用白名单机制，避免误判
• 提供申诉渠道

4. 性能影响

问题：地域查询影响性能

解决方案：

• 使用本地 GeoIP 数据库，减少网络开销
• 缓存地域查询结果
• 异步加载 GeoIP 数据库

5. 配置复杂

问题：配置复杂，容易出错

解决方案：

• 使用配置中心统一管理
• 提供配置校验工具
• 提供默认配置模板

性能测试

测试环境

• 服务器：4核8G，100Mbps带宽
• 测试场景：10000个并发请求

测试结果

测试结论

1. 性能影响小：安全防护对性能影响在可接受范围内
2. 非法请求拦截：成功拦截所有非法请求
3. 稳定性高：系统稳定，没有出现崩溃或卡顿

互动话题

1. 你在实际项目中如何实现 IP 黑白名单和地域封禁？有哪些经验分享？
2. 对于敏感接口保护，你认为哪种防护策略最有效？
3. 你使用过哪些 GeoIP 库？有什么推荐？
4. 在网关层实现访问控制，有哪些优缺点？

欢迎在评论区交流讨论！

公众号：服务端技术精选，关注最新技术动态，分享实用技巧。