Go Gateway

外观

关键字拦截器 🚫 ​

概述 ​

关键字拦截器是一个强大的安全过滤器，用于检测和拦截请求中的敏感词汇、恶意脚本和不当内容。它支持多种匹配模式和智能变体检测，能够有效防护XSS攻击、SQL注入、敏感词汇等安全威胁。

支持的请求格式 ​

  • ✅ application/json - JSON数据
  • ✅ application/x-www-form-urlencoded - 表单数据​
  • ✅ url地址 - URL参数传递
  • ❌ multipart/form-data - 不支持附件表单数据提交

功能特性 ​

基础功能 ​

  • 多维度检测：支持检测URL、请求头、请求体中的关键字
  • 多种匹配模式：精确匹配、包含匹配、正则表达式匹配
  • 灵活配置：支持路径包含/排除、大小写敏感控制
  • 多种处理动作：阻止请求或仅记录日志

高级功能 ​

  • 智能变体检测：检测拼音、简繁体、形近字、leetspeak等变体
  • 第三方库支持：使用专业的拼音转换、简繁体转换、相似度算法库
  • 详细日志记录：记录匹配的规则名称、关键字、匹配类型和位置

配置说明 ​

基础配置结构 ​

yaml
gateway:
  filter:
    keyword:
      enabled: true  # 是否启用关键字拦截器
      rules:         # 拦截规则列表
        - name: "规则名称"                 # 规则名称，用于日志记录
          urls:                           # 需要检查的URL路径列表
            - "/api/**"
            - "/chat/**"
          forbid-urls:                    # 排除的URL路径列表（可选）
            - "/api/health"
          keywords:                       # 关键字列表
            - "敏感词1"
            - "敏感词2"
          match-type: "contains"          # 匹配类型: exact/contains/regex
          case-sensitive: false           # 是否区分大小写
          action: "block"                 # 处理动作: block(阻止)/log(仅记录)
          # 变体检测配置（可选）
          enable-variant-detection: true  # 是否启用变体检测
          variant-types:                  # 变体检测类型列表
            - "pinyin"                    # 拼音检测
            - "traditional"               # 简繁体检测
            - "similar"                   # 相似度检测
            - "leetspeak"                 # 字符替换检测
          pinyin-mode: "full"             # 拼音模式: full/initial/fuzzy
          similarity-threshold: 0.8       # 相似度阈值(0.0-1.0)

配置参数详解 ​

基础参数 ​

参数类型必填默认值说明
namestring是-规则名称，用于日志记录和问题排查
urls[]string是-需要检查的URL路径，支持ant-path匹配模式
forbid-urls[]string否[]排除的URL路径，优先级高于urls
keywords[]string是-关键字列表，不能为空
match-typestring否contains匹配类型：exact/contains/regex
case-sensitivebool否false是否区分大小写
actionstring否block处理动作：block(阻止)/log(仅记录)

变体检测参数 ​

参数类型必填默认值说明
enable-variant-detectionbool否false是否启用变体检测
variant-types[]string否[]变体检测类型列表
pinyin-modestring否full拼音检测模式
similarity-thresholdfloat64否0.8相似度阈值(0.0-1.0)

匹配类型说明 ​

exact（精确匹配） ​

完全匹配关键字，适用于精确的词汇检测。

yaml
match-type: "exact"
keywords: ["admin", "root"]
# 匹配：admin, root
# 不匹配：administrator, rooted

contains（包含匹配） ​

检查文本是否包含关键字，最常用的匹配模式。

yaml
match-type: "contains"
keywords: ["script", "alert"]
# 匹配：<script>, javascript:alert(), scriptlet

regex（正则表达式匹配） ​

使用正则表达式进行复杂模式匹配。

yaml
match-type: "regex"
keywords: ["<script[^>]*>", "javascript:\\s*alert"]
# 匹配：<script>, <script type="text/javascript">, javascript: alert()

变体检测类型 ​

pinyin（拼音检测） ​

检测中文字符的拼音表示，使用 mozillazg/go-pinyin 库。

yaml
variant-types: ["pinyin"]
pinyin-mode: "full"  # full/initial/fuzzy
keywords: ["操"]
# 检测：cao, c, 操

拼音模式说明：

  • full：全拼模式，检测完整拼音
  • initial：首字母模式，检测拼音首字母
  • fuzzy：模糊模式，支持多音字检测

traditional（简繁体检测） ​

检测简体字和繁体字的互相转换，使用 liuzl/gocc 库。

yaml
variant-types: ["traditional"]
keywords: ["这个网站有问题"]
# 检测：這個網站有問題

similar（相似度检测） ​

基于编辑距离算法检测相似文本，使用 hbollon/go-edlib 库。

yaml
variant-types: ["similar"]
similarity-threshold: 0.8
keywords: ["hello world"]
# 检测：h3ll0 w0rld, helo world

leetspeak（字符替换检测） ​

检测数字字母替换的变体，使用Jaro-Winkler算法。

yaml
variant-types: ["leetspeak"]
keywords: ["hello"]
# 检测：h3ll0, he110, h@llo

配置示例 ​

示例0：基础配置格式 ​

yaml
gateway:
  filter:
    keyword:
      enabled: true  # 启用关键字拦截器
      rules:
        - name: "敏感词拦截"              # 规则名称
          urls:
            - "/demo/**"
          keywords:
            - "傻逼"
            - "操你妈"
            - "去死"
            - "fuck"
            - "shit"
          match-type: "contains"          # 匹配类型: exact/contains/regex
          case-sensitive: false           # 是否区分大小写
          action: "block"                 # 处理动作: block/log
          enable-variant-detection: true  # 启用变体检测
          variant-types:                  # 变体检测类型
            - "pinyin"                    # 拼音检测
            - "traditional"               # 简繁体检测
            - "similar"                   # 相似度检测
            - "leetspeak"                 # 字符替换检测
          pinyin-mode: "full"             # 拼音模式: full/initial/fuzzy
          similarity-threshold: 0.8       # 相似度阈值(0.0-1.0)

示例1：XSS和SQL注入防护 ​

yaml
gateway:
  filter:
    keyword:
      enabled: true
      rules:
        - name: "XSS和SQL注入防护"
          urls:
            - "/api/**"
            - "/form/**"
          forbid-urls:
            - "/api/health"
          keywords:
            - "script"
            - "alert"
            - "eval"
            - "javascript:"
            - "vbscript:"
            - "onload"
            - "onerror"
            - "onclick"
            - "drop table"
            - "delete from"
            - "union select"
            - "insert into"
            - "update set"
          match-type: "contains"
          case-sensitive: false
          action: "block"
          enable-variant-detection: true
          variant-types:
            - "similar"
            - "leetspeak"
          similarity-threshold: 0.7

示例2：聊天内容敏感词检测 ​

yaml
gateway:
  filter:
    keyword:
      enabled: true
      rules:
        - name: "聊天内容敏感词检测"
          urls:
            - "/chat/**"
            - "/comment/**"
          keywords:
            - "傻逼"
            - "操你妈"
            - "去死"
            - "fuck"
            - "shit"
          match-type: "contains"
          case-sensitive: false
          action: "block"
          enable-variant-detection: true
          variant-types:
            - "pinyin"
            - "traditional"
            - "similar"
            - "leetspeak"
          pinyin-mode: "fuzzy"
          similarity-threshold: 0.8

示例3：API敏感信息检测 ​

yaml
gateway:
  filter:
    keyword:
      enabled: true
      rules:
        - name: "API敏感信息检测"
          urls:
            - "/api/**"
          keywords:
            - "password"
            - "secret"
            - "token"
            - "key"
          match-type: "exact"
          case-sensitive: true
          action: "log"  # 仅记录，不阻止
          enable-variant-detection: false

示例4：正则表达式高级匹配 ​

yaml
gateway:
  filter:
    keyword:
      enabled: true
      rules:
        - name: "高级模式匹配"
          urls:
            - "/**"
          keywords:
            - "<script[^>]*>"
            - "javascript:\\s*alert"
            - "\\b(union|select|insert|delete|update|drop)\\s+"
            - "\\d{15,19}"  # 信用卡号模式
          match-type: "regex"
          case-sensitive: false
          action: "block"

日志输出 ​

关键字拦截器会输出详细的日志信息，包括：

阻止请求日志 ​

[2024-01-01 12:00:00] WARN [request-123] 关键字拦截阻止请求 - 规则: XSS和SQL注入防护, 关键字: script, 匹配类型: contains, 位置: Body, 路径: /api/submit

仅记录日志 ​

[2024-01-01 12:00:00] WARN [request-124] 关键字拦截检测到敏感内容，仅记录 - 规则: API敏感信息检测, 关键字: password, 匹配类型: exact, 位置: Body, 路径: /api/user

变体检测日志 ​

[2024-01-01 12:00:00] WARN [request-125] 关键字拦截阻止请求 - 规则: 聊天内容敏感词检测, 关键字: 操, 匹配类型: variant[pinyin[full]], 位置: Body, 路径: /chat/send

性能优化 ​

1. 合理配置检测范围 ​

yaml
# 推荐：针对特定路径配置
gateway:
  filter:
    keyword:
      rules:
        - urls:
            - "/api/submit"
            - "/chat/**"

# 避免：过于宽泛的配置
gateway:
  filter:
    keyword:
      rules:
        - urls:
            - "/**"

2. 选择合适的匹配类型 ​

yaml
# 性能最好：精确匹配
gateway:
  filter:
    keyword:
      rules:
        - match-type: "exact"

# 性能中等：包含匹配
gateway:
  filter:
    keyword:
      rules:
        - match-type: "contains"

# 性能较低：正则表达式
gateway:
  filter:
    keyword:
      rules:
        - match-type: "regex"

3. 谨慎使用变体检测 ​

yaml
# 推荐：仅在必要时启用
gateway:
  filter:
    keyword:
      rules:
        - enable-variant-detection: true
          variant-types:
            - "pinyin"  # 只启用需要的类型

# 避免：启用所有变体检测类型
gateway:
  filter:
    keyword:
      rules:
        - variant-types:
            - "pinyin"
            - "traditional"
            - "similar"
            - "leetspeak"

最佳实践 ​

1. 分层配置策略 ​

yaml
gateway:
  filter:
    keyword:
      enabled: true
      rules:
        # 第一层：基础安全防护（所有路径）
        - name: "基础XSS防护"
          urls:
            - "/**"
          keywords:
            - "<script"
            - "javascript:"
            - "vbscript:"
          match-type: "contains"
          action: "block"
          
        # 第二层：API特定防护
        - name: "API SQL注入防护"
          urls:
            - "/api/**"
          keywords:
            - "union select"
            - "drop table"
          match-type: "contains"
          action: "block"
          
        # 第三层：业务特定防护
        - name: "聊天敏感词"
          urls:
            - "/chat/**"
          keywords:
            - "敏感词1"
            - "敏感词2"
          match-type: "contains"
          enable-variant-detection: true
          variant-types:
            - "pinyin"
            - "traditional"
          action: "block"

2. 关键字管理 ​

  • 定期更新关键字列表
  • 根据业务场景分类管理
  • 避免过于宽泛的关键字
  • 测试关键字的误报率

3. 监控和调优 ​

  • 监控拦截日志，分析拦截效果
  • 根据误报情况调整配置
  • 定期评估性能影响
  • 建立关键字库维护流程

故障排除 ​

常见问题 ​

1. 关键字不生效 ​

检查项：

  • 确认 enabled: true
  • 检查URL路径匹配
  • 验证关键字拼写
  • 确认匹配类型设置

2. 误报过多 ​

解决方案：

  • 调整匹配类型为更精确的模式
  • 添加排除路径 forbid-urls
  • 优化关键字列表
  • 调整相似度阈值

3. 变体检测不工作 ​

检查项：

  • 确认依赖库已正确安装
  • 检查变体类型配置
  • 验证相似度阈值设置
  • 查看错误日志

4. 性能问题 ​

优化方案：

  • 减少检测范围
  • 优化关键字数量
  • 禁用不必要的变体检测
  • 使用更高效的匹配类型

调试技巧 ​

1. 启用详细日志 ​

yaml
# 临时启用仅记录模式进行调试
gateway:
  filter:
    keyword:
      rules:
        - action: "log"

2. 逐步测试 ​

yaml
# 先测试基础匹配
gateway:
  filter:
    keyword:
      rules:
        - enable-variant-detection: false

# 再测试变体检测
gateway:
  filter:
    keyword:
      rules:
        - enable-variant-detection: true
          variant-types:
            - "pinyin"  # 逐个测试

3. 使用测试工具 ​

bash
# 使用curl测试
curl -X POST http://localhost:8080/api/test \
  -H "Content-Type: application/json" \
  -d '{"content": "测试关键字"}'

Copyright © 2017-2025 wueasy.com