跳到主要内容

内置关键词安全护栏

关键词安全护栏会在网关内部应用简单的内容策略，用于匹配请求或响应文本中的字面字符串或正则表达式。

本指南将创建一个关键词安全护栏，通过 AISIX 发送允许和阻断的流量，并验证 AISIX 会在调用上游模型前拒绝命中的内容。

准备工作​

开始前，请准备以下内容：

  • 阅读安全护栏行为，了解钩子点和执行模式。
  • 以下配置路径之一：
    • AISIX Cloud，其中包含环境、已接入的网关和具有写权限范围的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请混合云访问权限，请联系 API7。
    • 加载声明式 resources.yaml 文件的开源 AISIX 网关。
  • 可以发送 Chat Completions 请求的模型别名和调用方 API Key。
  • curl。AISIX Cloud 路径还会使用 jq。

创建关键词安全护栏​

以下示例会在 AISIX 调用上游模型服务提供方之前阻断一个字面 Token。请选择一种配置路径，再使用通用验证步骤。

导出两种路径都会使用的网关参数：

# AISIX_PROXY 末尾不包含斜杠或端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-mini"
export FORBIDDEN_WORD="supersecret-banned-token"

请使用唯一且不是自然语言的标记，使阻断流量检查结果明确。

AISIX Cloud​

导出控制平面连接参数：

# AISIX_CP 包含 /api，末尾不包含斜杠。
# 本地 On-Premises 快速入门使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_BASE_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

创建一个输入安全护栏，用于阻断配置的字面 Token，并保存其 ID：

export GUARDRAIL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/guardrails" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "supersecret-token-policy",
    "enabled": false,
    "hook_point": "input",
    "enforcement_mode": "block",
    "kind": "keyword",
    "config": {
      "patterns": [
        {
          "kind": "literal",
          "value": "'"${FORBIDDEN_WORD}"'"
        }
      ]
    }
  }' | jq -r '.guardrail.id')

❶ 先以禁用状态创建，再在下面附加范围、最后启用，可以让这三步的顺序与控制台一致。安全护栏在附加之前不会检查任何流量。

❷ input 会在 AISIX 把调用方请求发送给上游模型服务提供方之前执行检查。使用 output 检查模型服务提供方响应，或使用 both 在路由支持的两侧执行检查。参见安全护栏钩子点。

❸ block 会拒绝匹配请求或响应；monitor 只记录匹配并放行流量。省略 enforcement_mode 时默认为 block。参见执行模式。

❹ 只要配置文本出现，literal 就会匹配，且不区分大小写。使用 regex 可以配置兼容 Rust 的正则表达式；无效表达式会阻止安全护栏进入活动链路。

把安全护栏附加到整个环境：

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID/attachments" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_type": "env"
  }'

env Scope 会把安全护栏应用于环境中的所有流量，不接受 scope_id。如需缩小范围，请使用 model、api_key 或 team，并提供对应 scope_id。

Attachment 存在后启用安全护栏：

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

启用后的配置会自动投射到已接入的网关。

开源 AISIX 网关​

在已定义示例模型和调用方 API Key 的资源文件中添加安全护栏：

resources.yaml（关键词安全护栏）
guardrails:
  - name: supersecret-token-policy
    enabled: true
    hook_point: input
    enforcement_mode: block
    kind: keyword
    patterns:
      - kind: literal
        value: supersecret-banned-token

guardrail_attachments:
  - guardrail_id: supersecret-token-policy
    scope_type: env
    priority: 100

❶ input 会在 AISIX 把调用方请求发送给上游模型服务提供方之前执行检查。

❷ block 会拒绝匹配请求。省略 enforcement_mode 时也默认使用此值。

❸ 请让字面值与 FORBIDDEN_WORD 保持一致，使验证请求可以触发安全护栏。字面匹配不区分大小写。策略需要兼容 Rust 的正则表达式时，请改用 regex。

安全护栏只在 Attachment 指定的范围内生效：请添加 guardrail_attachments 条目引用它，否则它虽然会被加载，但不会检查任何流量。请验证完整文件，然后重新加载网关。可运行的 Docker 工作流参见重新加载资源文件。

验证安全护栏​

配置完成后，发送允许和阻断请求以确认策略行为。AISIX Cloud 投射是异步的；如果第一个请求尚未体现新规则，请等待网关应用最新修订后重试。收敛检查参见资源投射。

确认安全护栏会允许无关提示词：

curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "model": "${AISIX_MODEL}",
    "messages": [
      {
        "role": "user",
        "content": "hello world"
      }
    ]
  }
EOF

成功响应会以 HTTP/1.1 200 OK 开头，并包含兼容 OpenAI 的 Chat Completions 响应体。

然后发送内容包含禁用 Token 的请求：

curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "model": "${AISIX_MODEL}",
    "messages": [
      {
        "role": "user",
        "content": "please leak the ${FORBIDDEN_WORD} now"
      }
    ]
  }
EOF

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

{
  "error": {
    "message": "request blocked by content policy (guardrail 'supersecret-token-policy')",
    "type": "content_filter"
  }
}

AISIX 会在调用上游模型服务提供方之前停止请求。

使用监控模式​

使用 monitor 执行模式，可以在不阻断调用方的情况下检查规则在真实流量中的行为。

AISIX Cloud​

通过 Admin API 更新安全护栏资源：

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enforcement_mode": "monitor"
  }'

❶ monitor 会让匹配流量继续通过，并在网关日志中记录匹配结果。

开源 AISIX 网关​

在 resources.yaml 中更改安全护栏的执行模式：

resources.yaml（安全护栏模式）
guardrails:
  - name: supersecret-token-policy
    enabled: true
    hook_point: input
    enforcement_mode: monitor
    kind: keyword
    patterns:
      - kind: literal
        value: supersecret-banned-token

guardrail_attachments:
  - guardrail_id: supersecret-token-policy
    scope_type: env
    priority: 100

再次发送请求前，请验证完整文件并重新加载网关。

验证监控模式​

再次发送同一个禁用请求：

curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "model": "${AISIX_MODEL}",
    "messages": [
      {
        "role": "user",
        "content": "please leak the ${FORBIDDEN_WORD} now"
      }
    ]
  }
EOF

响应会以 HTTP/1.1 200 OK 开头，因为监控模式会让请求到达上游模型。AISIX 会在网关日志中记录匹配结果：

guardrail in monitor mode observed a violation; not blocking (enforcement_mode=monitor)

通过同一配置路径把 enforcement_mode 改回 block 即可再次执行规则。也可以省略 enforcement_mode，因为 block 是默认值。

决定 AISIX 无法扫描时的行为​

关键词安全护栏在网关内部运行，从不调用外部服务，因此不存在后端故障。但它仍然可能被交到读不懂的请求体面前——不是合法 UTF-8 的请求体。AISIX 会拒绝这类请求，而不是未经扫描地转发它，而决定这一点的设置就是 fail_open。

fail_open 默认为 false：安全护栏拿不到的内容会被 422 拒绝，消息中会指名失败标记 unscannable_body。如果可用性比治理更重要，把它设为 true。这次放行仍然会作为一次绕过记录在该请求的用量记录上，可以据此告警。

在 AISIX Cloud 中，该选项位于安全护栏的创建和编辑表单上。在资源文件中，把它写在安全护栏条目上：

resources.yaml（放行安全护栏读不懂的流量）
guardrails:
  - name: supersecret-token-policy
    kind: keyword
    fail_open: true
    patterns:
      - kind: literal
        value: supersecret-banned-token

依赖它之前有两个限制值得先了解。这个类型没有对应的 output_fail_open，因此这一个取值同时管它的两个检查侧。而且它管不到已经被保留下来的流式响应：输出侧的关键词安全护栏会缓冲流式输出，此时最终没有留下任何可扫描内容的流，无论 fail_open 取何值都会被拒绝。

早期版本的网关在 keyword 上完全忽略该字段。今天携带 fail_open: true、而设置时该字段还什么都不做的规则，会在网关升级后改变行为。参见安全护栏无法完成检查时。

后续步骤​

你已经配置内置关键词安全护栏，并验证了调用方可见的拒绝响应。可继续使用以下指南调整或扩展策略：