PII 检测与脱敏

PII 安全护栏会检测请求和响应文本中的敏感数据。它可以将每个命中内容替换为脱敏 token 并继续处理，也可以阻断请求或响应。

PII 检测完全在网关内执行，不会调用外部审核服务。命中的原始值不会写入网关日志、用量记录或错误响应。

本指南将创建一个 PII 安全护栏，用于脱敏内置检测器命中的内容；随后添加自定义模式，并验证脱敏与阻断行为。

准备工作

请先准备以下内容：

阅读安全护栏行为，了解检查位置和执行模式。
一个 Admin 和代理监听器都可用的自托管 AISIX 网关。
网关 config.yaml 中的 Admin Key。
一个可发送 Chat Completions 请求的模型别名和调用方 API Key。

内置检测器

在 detectors 中列出检测器的 type 即可启用。部分检测器会先校验校验和，避免随机数字串被误判并脱敏。

`type`	匹配内容
`email`	邮箱地址
`china_mobile`	中国大陆手机号码
`china_id_card`	中国大陆居民身份证号码（ISO 7064 校验和）
`bank_card`	银行卡号（Luhn 校验和）
`us_ssn`	美国社会安全号码
`ip_address`	IPv4 / IPv6 地址
`api_key`	API Key 和 token（OpenAI、AWS、GitHub、Slack、Google 签名）
`jwt`	JSON Web Token
`private_key`	PEM 私钥块

命中动作

每次命中都会解析为以下动作之一：

mask：将命中的文本片段替换为 [EMAIL_REDACTED] 等 token，然后继续调用上游模型。
block：以 422 Unprocessable Entity 拒绝请求或响应。

default_action 会设置所有检测器和自定义模式的默认动作。也可以在单个检测器或自定义模式上设置 action 覆盖默认动作。

创建 PII 安全护栏

以下示例会在 AISIX 将请求发送到上游服务提供方前，对调用方请求中的邮箱地址和 API Key 进行脱敏。

设置示例请求使用的值：

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-mini"

创建一个输入安全护栏，对 email 和 api_key 检测器执行脱敏：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/guardrails" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pii-redaction-policy",
    "enabled": true,
    "hook_point": "input",
    "kind": "pii",
    "default_action": "mask",
    "detectors": [
      { "type": "email" },
      { "type": "api_key" }
    ]
  }'

❶ input 会在 AISIX 将调用方请求发送到上游前进行脱敏。使用 output 可以脱敏服务提供方响应，使用 both 可以同时覆盖两侧。更多信息请参见检查位置。

❷ default_action 设置列出检测器的动作。mask 会将每个命中替换为脱敏 token。只有当某个检测器需要不同行为时，才设置检测器级别的 action。

如果之后需要查看、更新或删除该安全护栏，请保存返回的 id。

验证脱敏

发送一个 prompt 中包含邮箱地址的请求：

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [
      {
        "role": "user",
        "content": "email me at alice@example.com about the order"
      }
    ]
  }'

请求会以 HTTP/1.1 200 OK 成功返回。AISIX 会先改写 prompt，再调用上游模型，因此服务提供方收到的是：

email me at [EMAIL_REDACTED] about the order

原始值不会到达上游服务提供方、网关日志或用量记录。用量记录只携带每个检测器的命中次数，包括检测器名称，但不包含命中文本。

阻断敏感数据

当某个检测器应拒绝流量而不是脱敏时，请使用 block。以下示例会阻断任何包含中国大陆居民身份证号码的请求：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/guardrails" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "block-id-card",
    "enabled": true,
    "hook_point": "input",
    "kind": "pii",
    "default_action": "block",
    "detectors": [
      { "type": "china_id_card" }
    ]
  }'

如果请求内容包含有效身份证号码，会被拒绝：

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [
      {
        "role": "user",
        "content": "my id is 11010519491231002X"
      }
    ]
  }'

被阻断的响应会以 HTTP/1.1 422 Unprocessable Entity 开头，并包含如下响应体：

{
  "error": {
    "message": "request blocked by content policy (guardrail 'block-id-card')",
    "type": "content_filter"
  }
}

该消息会刻意保持通用，并且不会回显命中的原始值。

添加自定义模式

使用 custom_patterns 可以检测组织内部特有的数据。每个模式都需要 name 和 regex。AISIX 会在脱敏 token 和命中计数中使用该名称，并在应用规则前拒绝无效的正则表达式。

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/guardrails" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pii-custom",
    "enabled": true,
    "hook_point": "both",
    "kind": "pii",
    "default_action": "mask",
    "detectors": [
      { "type": "email" }
    ],
    "custom_patterns": [
      {
        "name": "employee_id",
        "regex": "EMP-[0-9]{6}"
      }
    ]
  }'

命中该自定义模式时，内容会被脱敏为 [EMPLOYEE_ID_REDACTED]。

流式响应

对于 output hook 上的流式响应，AISIX 会先缓冲响应，等待响应完成后再应用脱敏并发送脱敏后的结果。缓冲是必要的，因为命中文本片段可能跨越两个流式数据块。

如果流式响应超过扫描缓冲区大小，on_buffer_exceeded 会控制 AISIX 是释放还是丢弃响应。默认 max_buffer_bytes 为 262144。

fail_closed（默认）：丢弃响应，避免释放未扫描内容。
fail_open：释放未扫描内容。

{
  "kind": "pii",
  "hook_point": "output",
  "default_action": "mask",
  "detectors": [
    { "type": "email" }
  ],
  "max_buffer_bytes": 262144,
  "on_buffer_exceeded": "fail_closed"
}

下一步

你已经配置内置 PII 安全护栏，并验证了脱敏和阻断行为。当需要调整检查位置或执行模式时，请继续阅读安全护栏行为。如需将本地 PII 检测与外部安全护栏服务结合使用，可以添加 AWS Bedrock Guardrails、Azure AI Content Safety 安全护栏或阿里云 AI 安全护栏。

准备工作​

内置检测器​

命中动作​

创建 PII 安全护栏​

验证脱敏​

阻断敏感数据​

添加自定义模式​

流式响应​

下一步​