跳到主要内容
版本：3.10.x

配置数据脱敏

data-mask 插件会清理记录到访问日志和日志插件输出中的请求数据。它可以移除或遮盖查询参数、请求头和请求体中的敏感值，避免个人身份信息（PII）、凭据和其他受监管数据进入日志流水线。

本指南介绍常见脱敏工作流。有关完整插件字段参考、支持的组合和更多示例，请参阅 data-mask。

备注

data-mask 在网关的日志阶段运行。它会改变日志插件和访问日志看到的内容，但不会改变上游服务收到的内容或返回给客户端的内容。

前置条件​

  • API7 企业版实例正在运行。
  • 已创建网关组且网关实例正在运行。
  • 一个 Dashboard Token。

配置数据脱敏​

以下示例对 URL 编码请求体中的敏感字段进行脱敏，并使用 file-logger 将脱敏后的请求体写入本地日志文件。

第 1 步：创建具有上游的服务​

curl -k "https://localhost:7443/apisix/admin/services/data-mask-httpbin-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-mask-httpbin-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

第 2 步：创建路由并启用 data-mask​

创建同时启用 data-mask 和 file-logger 的路由。

curl -k "https://localhost:7443/apisix/admin/routes/data-mask-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-mask-route",
    "paths": ["/anything/data-mask"],
    "methods": ["POST"],
    "service_id": "data-mask-httpbin-service",
    "plugins": {
      "data-mask": {
        "request": [
          {
            "type": "body",
            "body_format": "urlencoded",
            "name": "password",
            "action": "remove"
          },
          {
            "type": "body",
            "body_format": "urlencoded",
            "name": "token",
            "action": "replace",
            "value": "*****"
          },
          {
            "type": "body",
            "body_format": "urlencoded",
            "name": "card",
            "action": "regex",
            "regex": "(\\d+)\\-\\d+\\-\\d+\\-(\\d+)",
            "value": "$1-****-****-$2"
          }
        ]
      },
      "file-logger": {
        "include_req_body": true,
        "path": "/tmp/mask-urlencoded-body.log"
      }
    }
  }'

验证配置​

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything/data-mask" \
  --data-urlencode "password=abc" \
  --data-urlencode "token=xyz" \
  --data-urlencode "card=1234-1234-1234-1234"

应收到 200 OK。上游仍会收到原始值。

然后检查网关日志文件。如果网关在 Docker 中运行，请先查找容器名称：

docker ps --format '{{.Names}}'

再从网关容器中读取日志文件：

docker exec <gateway-container-name> sh -lc 'cat /tmp/mask-urlencoded-body.log'

应看到类似以下的脱敏日志条目：

{
  "request": {
    "uri": "/anything/data-mask",
    "body": "token=*****&card=1234-****-****-1234",
    "method": "POST",
    "url": "http://127.0.0.1:9080/anything/data-mask"
  }
}

日志输出中会移除 password 字段、替换 token，并遮盖 card 中间的数字。如果应用配置后路由立即返回 404，请等待几秒，让最新配置下发到网关后重试。

后续步骤​

  • 配置日志——挂载其他日志插件以捕获脱敏后的请求数据。
  • 限流——保护 API 免受滥用。
  • 保护凭证——保护敏感配置数据。