# 配置数据脱敏

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

本指南介绍常见脱敏工作流。有关完整插件字段参考、支持的组合和更多示例，请参阅 [`data-mask`](https://docs.apiseven.com/hub/data-mask.md)。

备注

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

## 前置条件[​](#前置条件 "前置条件的直接链接")

* API7 企业版实例正在运行。
* 已创建网关组且网关实例正在运行。
* 已[从控制台获取 Token](https://docs.apiseven.com/api7-gateway/reference/obtain-dashboard-token.md)。

## 配置数据脱敏[​](#配置数据脱敏 "配置数据脱敏的直接链接")

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

### 第 1 步：创建具有上游的服务[​](#第-1-步创建具有上游的服务 "第 1 步：创建具有上游的服务的直接链接")

* Admin API
* ADC

```
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

        }

      ]

    }

  }'
```

adc.yaml

```
services:

  - name: data-mask-httpbin-service

    upstream:

      name: default

      scheme: http

      nodes:

        - host: httpbin.org

          port: 80

          weight: 100

    routes:

      - name: data-mask-route

        uris:

          - /anything/data-mask

        methods:

          - POST

        plugins:

          data-mask:

            request:

              - action: remove

                body_format: urlencoded

                name: password

                type: body

              - action: replace

                body_format: urlencoded

                name: token

                type: body

                value: "*****"

              - action: regex

                body_format: urlencoded

                name: card

                regex: "(\\d+)\\-\\d+\\-\\d+\\-(\\d+)"

                type: body

                value: "$1-****-****-$2"

          file-logger:

            include_req_body: true

            path: /tmp/mask-urlencoded-body.log

    labels:

      docs-example: data-mask-httpbin-service
```

预览本示例管理的资源变更，确认没有非预期的更新或删除：

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=data-mask-httpbin-service
```

审查变更后同步配置：

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=data-mask-httpbin-service
```

### 第 2 步：创建路由并启用 `data-mask`[​](#第-2-步创建路由并启用-data-mask "第-2-步创建路由并启用-data-mask的直接链接")

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

* Admin API
* ADC

```
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"

      }

    }

  }'
```

该路由已包含在前面的 `adc.yaml` 示例中。

## 验证配置[​](#验证配置 "验证配置的直接链接")

向路由发送请求：

```
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`，请等待几秒，让最新配置下发到网关后重试。

## 后续步骤[​](#后续步骤 "后续步骤的直接链接")

* [配置集中式日志记录](https://docs.apiseven.com/api7-gateway/observability/logging.md)——挂载其他日志插件以捕获脱敏后的请求数据。
* [配置限流](https://docs.apiseven.com/api7-gateway/how-to-guides/traffic-management/rate-limiting.md)——保护 API 免受滥用。
* [安全凭证管理](https://docs.apiseven.com/api7-gateway/security-and-compliance/secure-credentials.md)——保护敏感配置数据。
