跳到主要内容

PII 检测与脱敏

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

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_addressIPv4 / IPv6 地址
api_keyAPI Key 和 Token（OpenAI、AWS、GitHub、Slack、Google 签名）
jwtJSON Web Token
private_keyPEM 私钥块

命中动作​

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

  • mask：将命中的文本片段替换为 [EMAIL_REDACTED] 等脱敏占位符，然后继续调用上游模型。
  • 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 会将每个命中替换为脱敏占位符。只有当某个检测器需要不同行为时，才设置检测器级别的 action。

对于响应侧 PII 脱敏，如果遇到流式流量，AISIX 会先保留响应内容，直到可以应用安全护栏。缓冲默认值和溢出行为请参见流式输出。

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

验证脱敏​

发送一个提示词中包含邮箱地址的请求：

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

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

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" \
  --data-binary @- <<EOF
  {
    "model": "${AISIX_MODEL}",
    "messages": [
      {
        "role": "user",
        "content": "my id is 11010519491231002X"
      }
    ]
  }
EOF

被阻断的响应会以 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 会在脱敏占位符和命中计数中使用该名称，并在应用规则前拒绝无效的正则表达式。

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]。

下一步​

你已经配置内置 PII 安全护栏，并验证了脱敏和阻断行为。使用下面的指南继续调整或扩展策略：