跳到主要内容

安全护栏行为

安全护栏会在 AISIX 的请求路径中加入内容策略检查，帮助运维人员控制哪些内容可以到达上游模型、哪些响应可以返回给调用方，以及策略调优期间应该采用多严格的执行方式。

AISIX 支持两类安全护栏：

  • 内置安全护栏（关键词和 PII 检测）会在网关内部检查模式。适用于不希望调用外部审核服务的策略。
  • 远程安全护栏会将提取出的内容发送到外部服务，再应用其返回的判定结果：AWS Bedrock Guardrails、Azure AI Content Safety、阿里云 AI 安全护栏、Lakera Guard、OpenAI Moderation，或自托管的 Microsoft Presidio 部署。

选择安全护栏服务提供方对所有类型进行了横向对比。

无论安全护栏在 AISIX 内部执行，还是调用远程审核服务，请求路径上的行为都是一致的。两类安全护栏都使用相同的运行时控制项来定义检查位置、执行模式、作用范围和调用方响应行为。远程安全护栏还会使用外部服务故障处理设置。

检查位置​

安全护栏的检查位置决定 AISIX 在哪里执行检查：

检查位置AISIX 检查内容被阻断时的效果
inputAISIX 发送到服务提供方之前的调用方请求。不会调用服务提供方。
outputAISIX 返回给调用方之前的响应内容。调用方不会收到被阻断的响应。
both请求和响应内容。在路由支持的两侧都应用同一个安全护栏。

输入安全护栏会在 AISIX 能够提取请求文本的代理路由上运行，包括 Chat Completions、Completions、Responses、Messages、Embeddings、图像生成、语音、重排序请求，以及原始服务提供方透传隧道。输出安全护栏会在 AISIX 能够扫描返回文本的路由上运行，包括 Chat Completions、Completions、Responses、Messages 和透传隧道。

在透传隧道上，AISIX 无法解析请求结构，因此会将完整请求体和响应体作为文本交给已附加的安全护栏扫描。任一侧命中都会返回 422，上游响应体不会继续转发。

安全护栏匹配​

安全护栏的作用范围决定了它可以评估哪些请求。在自托管部署中，通过 Admin API 创建的安全护栏会应用到整个环境。AISIX Cloud 还可以将安全护栏限定到选定的模型别名、调用方 API Key 或团队。

当多个安全护栏同时适用于同一个请求时，AISIX 会把它们作为一条链路进行评估。任意一个安全护栏给出阻断判定，都会阻断请求或响应。

如果同一个安全护栏通过多个匹配的 Cloud 作用范围附加到请求链路中，AISIX 只保留一份该安全护栏。优先级最高的附加关系生效；当优先级相同时，作用范围越具体优先级越高，顺序为：调用方 API Key、团队、模型别名、环境。

执行模式​

安全护栏的 enforcement_mode 决定 AISIX 在安全护栏检测到匹配内容后如何处理。

AISIX 支持两种执行模式：

  • block：拒绝命中的内容。如果省略 enforcement_mode，这是默认行为。
  • monitor：放行命中的内容，并记录命中结果。

基于检测的安全护栏，包括 PII 识别器、注入分类器和内容分类审核，都可能产生误报和漏报。当你需要先用真实流量调优策略再强制执行时，可以使用 monitor 模式。

在 block 模式下，输入侧命中会在调用服务提供方前停止请求，输出侧命中会阻止调用方收到响应。

在 monitor 模式下，调用方可见的响应不会发生变化。原本在 block 模式下会以 422 Unprocessable Entity 拒绝的请求，会返回正常的上游结果。本应被脱敏护栏掩码的内容也会原样到达模型或调用方。

每次观察都会作为 monitor hit 记录在该请求的用量记录中。一条命中会携带安全护栏名称、命中的检查位置，以及该安全护栏本应执行的动作：would_block 附带匹配原因，或 would_mask 附带每个检测器的命中次数。AISIX 不会记录命中的请求或响应内容。

这些记录可用于先以 monitor 模式上线新的安全护栏，观察命中率并调优策略，然后再切换到 block。对于 block 类观察，AISIX 还会在网关日志中以 info 级别记录命中：

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

流式输出​

当强制执行的安全护栏覆盖 output hook 时，AISIX 会先保留流式响应内容，直到相关检查可以执行。根据安全护栏类型，AISIX 可能保留完整响应，也可能检查缓冲窗口。这样可以避免被阻断或未脱敏的内容在安全护栏判定前到达调用方，也能检测跨越流式分片的文本片段。

monitor 模式下的安全护栏不会阻塞流式输出。当请求上覆盖 output hook 的所有安全护栏都以 monitor 模式运行时，AISIX 会在流式内容到达时立即转发给调用方，并在流结束后执行检查，记录所有匹配内容的 monitor 命中。流式延迟不会发生变化，下面的缓冲区上限也不适用：超大响应会被交付并观测，而不会被拒绝。如果同一请求上还有覆盖 output hook 的强制执行安全护栏，则会按照上述方式保留流式内容。

暴露流式缓冲设置的安全护栏类型使用以下默认值：

{
  "max_buffer_bytes": 262144,
  "on_buffer_exceeded": "fail_closed"
}

如需调整缓冲上限或溢出行为，请在安全护栏资源中添加这些字段。fail_closed 会阻断过大的输出。fail_open 会释放 AISIX 无法完整检查或改写的输出，因此只有在可用性比严格输出治理更重要时才使用。未暴露这些字段的安全护栏类型使用内置上限，并在溢出时 fail closed。

处理远程安全护栏故障​

会调用外部服务的安全护栏类型可能无法访问其后端服务。这适用于 AWS Bedrock Guardrails、Azure AI Content Safety、阿里云 AI 安全护栏、Lakera Guard、OpenAI Moderation 和 Microsoft Presidio。

以下两个设置决定 AISIX 是放行未扫描流量，还是阻断流量：

设置检查侧默认值当值为 true 时当值为 false 时
fail_open输入侧true放行未扫描的请求。阻断请求。
output_fail_open输出侧false放行未扫描的响应。阻断响应。

Admin API 和控制面 payload 中可能仍会出现 mandatory 字段。当 mandatory 为 true 时，即使输入侧 fail_open 设置本来会允许请求通过，远程安全护栏故障也会阻断流量。内置关键词和 PII 安全护栏在网关内部运行，不会调用后端，因此远程故障处理不适用于它们。

当 AISIX 因远程安全护栏未能返回判定而放行流量时，用量记录会包含特定服务提供方的绕过原因。该原因会区分超时、限流、服务或连接失败，以及配置错误。

调用方响应与遥测​

当安全护栏阻断兼容 OpenAI 或兼容 Anthropic 的代理请求时，AISIX 会返回 422，并使用对应代理协议的错误结构：

  • 兼容 OpenAI 的路由使用 content_filter。
  • 兼容 Anthropic 的非流式错误使用 invalid_request_error。
  • 兼容 Anthropic 的流式响应会以 Anthropic SSE 错误帧暴露阻断结果。

MCP 安全护栏阻断会遵循 MCP 协议形态。AISIX 返回 HTTP 200 和 JSON-RPC 错误结构，MCP 客户端可以把该失败作为协议响应处理。参见 Headers and Error Codes。

远程安全护栏 fail-open 时不会阻断请求或响应。AISIX 会在 usage event 中记录绕过原因。对于 Chat Completions 流量，AISIX 还会递增安全护栏绕过指标。

下一步​

你现在已经了解各类配置指南共用的安全护栏行为。使用下面的指南选择并配置策略：