WuEasy Gateway

外观

User-Agent 过滤器 🛡️ ​

功能概述 📝 ​

User-Agent 过滤器用于控制客户端访问权限，通过校验 HTTP 请求头中的 User-Agent 信息来提升系统安全性。

Syntax error in textmermaid version 11.5.0

功能特性 ✨ ​

过滤模式 ​

  • 🔍 规则匹配：支持正则表达式匹配 User-Agent
  • 🚫 空值处理：可配置是否允许空 User-Agent
  • 🎯 URL 匹配：支持针对特定 URL 路径配置规则
  • 🔄 动态配置：支持运行时动态修改规则

应用场景 ​

  • ✓ 爬虫访问控制
  • ✓ 特定客户端限制
  • ✓ 移动端访问控制
  • ✓ API 接口保护

配置说明 ⚙️ ​

基础配置参数 ​

参数名类型必填默认值说明
enabledboolean否false是否启用过滤器
itemsarray是-过滤规则列表

规则配置项 (items) ​

参数名类型必填默认值说明
urlsarray是-需要过滤的URL路径列表
emptyboolean否true是否允许空User-Agent
rulesarray否[爬虫检测规则]User-Agent匹配规则列表(正则表达式)

默认爬虫检测规则

如果未配置rules，系统会使用默认的爬虫检测规则来拦截常见的爬虫、自动化工具和恶意请求：

regex
(?i).*(bot|spider|crawl|slurp|wget|curl|fetch|python|scrapy|phantom|selenium|headless|puppeteer|jsdom|axios|request|http-client|webdriver|chromedriver|geckodriver).*

此规则会拦截以下类型的请求：

  • 搜索引擎爬虫 (bot, spider, crawl, slurp)
  • 下载工具 (wget, curl, fetch)
  • 爬虫框架 (python, scrapy)
  • 自动化测试工具 (phantom, selenium, puppeteer)
  • 无头浏览器 (headless)
  • HTTP客户端库 (axios, request, http-client)
  • 浏览器驱动 (webdriver, chromedriver, geckodriver)

配置示例 📝 ​

基础配置（使用默认爬虫检测） ​

yaml
wueasy:
  gateway:
    filter:
      user-agent:
        enabled: true  # 启用过滤器
        items:
          - urls: 
            - /api/**  # 匹配所有API路径
            empty: false  # 不允许空User-Agent
            # 不配置rules，将使用默认爬虫检测规则

自定义规则配置 ​

yaml
wueasy:
  gateway:
    filter:
      user-agent:
        enabled: true
        items:
          # 公开API使用默认爬虫检测
          - urls: 
            - /api/public/**
            empty: false
          
          # 管理API使用自定义规则
          - urls:
            - /api/admin/**
            empty: false
            rules:  # 覆盖默认规则，仅允许特定浏览器
              - "^Mozilla/5\\.0 .*Chrome/\\d+\\.\\d+.*"
              - "^Mozilla/5\\.0 .*Firefox/\\d+\\.\\d+.*"
          
          # 测试API允许特定爬虫工具
          - urls:
            - /api/test/**
            empty: true
            rules:
              - "^PostmanRuntime.*"
              - "^Apache-HttpClient.*"
              - "^curl/.*"

复杂场景配置 ​

yaml
wueasy:
  gateway:
    filter:
      user-agent:
        enabled: true
        items:
          # 移动端API规则
          - urls: 
            - /api/mobile/**
            empty: false
            rules:
              - "^Mozilla/5\\.0 \\(iPhone.*"
              - "^Mozilla/5\\.0 \\(iPad.*"
              - "^Mozilla/5\\.0 \\(Linux; Android.*"
          
          # 后台管理API规则
          - urls:
            - /api/admin/**
            empty: false
            rules:
              - "^Mozilla/5\\.0 .*Chrome/\\d+\\.\\d+.*"  # 仅允许Chrome浏览器
              - "^Mozilla/5\\.0 .*Firefox/\\d+\\.\\d+.*" # 仅允许Firefox浏览器
          
          # 开发测试API规则
          - urls:
            - /api/test/**
            empty: true
            rules:
              - "^PostmanRuntime.*"
              - "^curl/.*"
              - "^Apache-HttpClient.*"

正则表达式示例 🎯 ​

常用浏览器匹配 ​

regex
# Chrome浏览器
^Mozilla/5\.0 \(.*\) AppleWebKit/.* Chrome/.*

# Firefox浏览器
^Mozilla/5\.0 \(.*\) Gecko/.* Firefox/.*

# Safari浏览器
^Mozilla/5\.0 \(.*\) AppleWebKit/.* Safari/.*

移动端匹配 ​

regex
# iOS设备
^Mozilla/5\.0 \(iPhone|iPad|iPod\).*

# Android设备
^Mozilla/5\.0 \(Linux; Android.*

⚠️ 注意事项 ​

  1. 规则优先级

    • 规则按配置顺序从上到下匹配
    • URL匹配成功后，会验证User-Agent是否匹配rules中的任意一个规则
    • 如果未配置rules，将使用默认爬虫检测规则
    • 建议将更具体的规则放在前面

  2. 性能考虑

    • 默认爬虫检测规则已经过优化，性能影响较小
    • 自定义规则时避免过于复杂的正则表达式
    • 合理配置规则数量
    • 建议每个URL路径的rules数量不超过10个

  3. 安全建议

    • 对于公开API建议使用默认爬虫检测规则
    • 对于管理API建议使用更严格的自定义规则
    • 记录被拦截的异常访问日志
    • 定期更新规则列表适应新的爬虫特征

重要提示

  • 正则表达式需要严格测试
  • 建议配合其他安全措施使用
  • 关注性能影响

Copyright © 2017-2025 wueasy.com