User-Agent 过滤器 🛡️

功能概述 📝

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

功能特性 ✨

过滤模式

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

应用场景

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

配置说明 ⚙️

基础配置参数

参数名	类型	必填	默认值	说明
enabled	boolean	否	`false`	是否启用过滤器
rules	array[object]	是	-	过滤规则列表

规则配置项 (rules)

参数名	类型	必填	默认值	说明
urls	array[string]	是	-	需要过滤的URL路径列表
empty	boolean	否	`false`	是否允许空User-Agent
datas	array[string]	否	[爬虫检测规则]	User-Agent匹配规则列表(正则表达式)

默认爬虫检测规则

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

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

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

自定义规则配置

yaml

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

复杂场景配置

yaml

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

完整配置示例

yaml

gateway:
  filter:
    user-agent:
      enabled: true
      rules:
        # 严格模式 - 仅允许主流浏览器
        - urls:
            - /api/secure/**
            - /api/payment/**
          empty: false
          datas:
            - "^Mozilla/5\\.0 .*Chrome/\\d+\\.\\d+.*"
            - "^Mozilla/5\\.0 .*Firefox/\\d+\\.\\d+.*"
            - "^Mozilla/5\\.0 .*Safari/\\d+\\.\\d+.*"
            - "^Mozilla/5\\.0 .*Edge/\\d+\\.\\d+.*"
        
        # 移动端应用
        - urls:
            - /api/app/**
          empty: false
          datas:
            - "^MyApp/\\d+\\.\\d+.*"  # 自定义应用标识
            - "^Mozilla/5\\.0 \\(iPhone.*"
            - "^Mozilla/5\\.0 \\(iPad.*"
            - "^Mozilla/5\\.0 \\(Linux; Android.*"
        
        # 开发调试接口
        - urls:
            - /api/debug/**
          empty: true
          datas:
            - "^PostmanRuntime.*"
            - "^curl/.*"
            - "^Apache-HttpClient.*"
            - "^Java/.*"
            - "^Go-http-client.*"
        
        # 公开API - 使用默认爬虫检测
        - urls:
            - /api/public/**
          empty: false

不同业务场景配置

电商平台

yaml

gateway:
  filter:
    user-agent:
      enabled: true
      rules:
        # 用户端API - 仅允许浏览器和移动应用
        - urls:
            - /api/user/**
            - /api/order/**
          empty: false
          datas:
            - "^Mozilla/5\\.0.*"  # 所有浏览器
            - "^MyShopApp/\\d+\\.\\d+.*"  # 自定义移动应用
        
        # 商家后台 - 仅允许桌面浏览器
        - urls:
            - /api/merchant/**
          empty: false
          datas:
            - "^Mozilla/5\\.0 .*Chrome/\\d+\\.\\d+.*"
            - "^Mozilla/5\\.0 .*Firefox/\\d+\\.\\d+.*"
            - "^Mozilla/5\\.0 .*Safari/\\d+\\.\\d+.*"
        
        # 开放API - 允许合法的第三方调用
        - urls:
            - /api/open/**
          empty: false
          datas:
            - "^ThirdPartyApp/\\d+\\.\\d+.*"
            - "^PostmanRuntime.*"

内容管理系统

yaml

gateway:
  filter:
    user-agent:
      enabled: true
      rules:
        # 内容发布接口 - 严格限制
        - urls:
            - /api/content/**
            - /api/publish/**
          empty: false
          datas:
            - "^Mozilla/5\\.0 .*Chrome/\\d+\\.\\d+.*"
            - "^Mozilla/5\\.0 .*Firefox/\\d+\\.\\d+.*"
        
        # 文件上传接口 - 允许编辑器
        - urls:
            - /api/upload/**
          empty: false
          datas:
            - "^Mozilla/5\\.0.*"
            - "^TinyMCE.*"
            - "^CKEditor.*"
        
        # 公开内容API - 默认爬虫检测
        - urls:
            - /api/article/**
          empty: false

金融系统

yaml

gateway:
  filter:
    user-agent:
      enabled: true
      rules:
        # 交易接口 - 最严格限制
        - urls:
            - /api/trade/**
            - /api/transfer/**
          empty: false
          datas:
            - "^Mozilla/5\\.0 .*Chrome/\\d+\\.\\d+.*"
            - "^Mozilla/5\\.0 .*Firefox/\\d+\\.\\d+.*"
            - "^FinanceApp/\\d+\\.\\d+.*"  # 官方金融应用
        
        # 查询接口 - 允许移动端
        - urls:
            - /api/account/**
            - /api/balance/**
          empty: false
          datas:
            - "^Mozilla/5\\.0.*"
            - "^FinanceApp/\\d+\\.\\d+.*"
        
        # 第三方接口 - 白名单模式
        - urls:
            - /api/partner/**
          empty: false
          datas:
            - "^PartnerSystem/\\d+\\.\\d+.*"
            - "^TrustedThirdParty/\\d+\\.\\d+.*"

正则表达式示例 🎯

常用浏览器匹配

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.*

自定义应用匹配

regex

# 自定义移动应用
^MyApp/\d+\.\d+.*

# 第三方系统
^PartnerSystem/\d+\.\d+.*

⚠️ 注意事项

规则优先级
- 规则按配置顺序从上到下匹配
- URL匹配成功后，会验证User-Agent是否匹配datas中的任意一个规则
- 如果未配置datas，将使用默认爬虫检测规则
- 建议将更具体的规则放在前面
性能考虑
- 默认爬虫检测规则已经过优化，性能影响较小
- 自定义规则时避免过于复杂的正则表达式
- 合理配置规则数量
- 建议每个URL路径的datas数量不超过10个
安全建议
- 对于公开API建议使用默认爬虫检测规则
- 对于管理API建议使用更严格的自定义规则
- 记录被拦截的异常访问日志
- 定期更新规则列表适应新的爬虫特征

重要提示

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

User-Agent 过滤器 🛡️ ​

功能概述 📝 ​

功能特性 ✨ ​

过滤模式 ​

应用场景 ​

配置说明 ⚙️ ​

基础配置参数 ​

规则配置项 (rules) ​

配置示例 📝 ​

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

自定义规则配置 ​

复杂场景配置 ​

完整配置示例 ​

不同业务场景配置 ​

电商平台 ​

内容管理系统 ​

金融系统 ​

正则表达式示例 🎯 ​

常用浏览器匹配 ​

移动端匹配 ​

自定义应用匹配 ​

⚠️ 注意事项 ​

User-Agent 过滤器 🛡️

功能概述 📝

功能特性 ✨

过滤模式

应用场景

配置说明 ⚙️

基础配置参数

规则配置项 (rules)

配置示例 📝

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

自定义规则配置

复杂场景配置

完整配置示例

不同业务场景配置

电商平台

内容管理系统

金融系统

正则表达式示例 🎯

常用浏览器匹配

移动端匹配

自定义应用匹配

⚠️ 注意事项