跳到主要内容

安全护栏行为

安全护栏会在 AISIX 调用上游模型之前、模型返回响应之后，或在两处添加内容策略检查。其共用运行时控制项决定哪些流量会被检查、匹配是否会阻止流量，以及调用方和操作员能够观测到什么。

内置关键词和 PII 安全护栏在网关内部评估内容。远程安全护栏将提取出的内容发送到审核服务，并应用其决策。选择安全护栏服务提供方比较了可用的内置和远程选项。

两类安全护栏都使用本页所述的行为。远程安全护栏还需要为审核服务故障配置明确策略。

检查位置​

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

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

输入安全护栏覆盖标准推理路由中包含文本的部分，包括 Chat Completions、Completions、Responses、Messages、Embeddings、图像和视频生成、音频语音及重排请求。AISIX 还会扫描可选的音频转录和翻译提示词、Realtime 文本帧及 MCP tools/call 参数。相同的输入检查也覆盖 Files、Batch 和 Fine-tuning 请求载荷，以及原始服务提供方透传请求体。

输出安全护栏会扫描 Chat Completions、Completions、Responses、Messages、音频转录和翻译返回的文本。它们还会扫描 Realtime 文本帧、MCP tools/call 结果、Files、Batch 和 Fine-tuning 响应载荷，以及透传响应体。Realtime 二进制帧会直接中继，不执行安全护栏内容检查。

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

安全护栏匹配​

选择钩子点后，需要确定安全护栏的作用范围：

  • 在 AISIX Cloud 中，创建安全护栏并把它附加到环境或选定的模型别名、MCP 服务器、调用方 API Key 或团队。Attachment 允许一个定义以明确优先级应用到多个 Scope。
  • 对于开源 AISIX 网关，在 resources.yaml 中声明安全护栏。该文件没有 Attachment 集合，因此每个已启用安全护栏都会应用于该网关处理的所有请求。
启用前先附加

创建有明确 Scope 的 AISIX Cloud 安全护栏时，请先以禁用状态创建，添加至少一个 Attachment，再将其启用。没有 Attachment 记录的已启用安全护栏会被视为环境 Scope。因此，删除最后一个 Attachment 会使已启用安全护栏应用于整个环境，而不是让它失效；如果不应继续应用，请禁用或删除该安全护栏。

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

模型别名 Scope 和 MCP 服务器 Scope 选择的是单次请求不会同时具备的两个维度：MCP 工具调用不会解析出模型，模型请求也不会路由到 MCP 服务器。因此模型 Scope 的安全护栏永远不会检查 MCP 工具调用，MCP 服务器 Scope 的安全护栏也永远不会检查模型流量。若要同时覆盖两者，请把安全护栏附加到环境 Scope，或者两种 Attachment 各加一条。

如果同一个安全护栏通过 AISIX Cloud 中配置的多个匹配 Scope 附加到请求链路中，AISIX 只保留一份该安全护栏。优先级最高的 Attachment 生效；优先级相同时，Scope 越具体优先级越高，顺序为：调用方 API Key、团队、模型别名或 MCP 服务器、环境。模型别名与 MCP 服务器同级，因为单次请求不可能同时匹配这两者。

执行模式​

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

选择以下两种执行模式之一：

  • block 拒绝匹配内容。如果省略 enforcement_mode，这是默认行为。
  • monitor 允许匹配内容通过，并记录安全护栏本应执行的操作。

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

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

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

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

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

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

流式输出​

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

监控模式下的安全护栏不会使流式输出延迟。当所有输出安全护栏都以监控模式运行时，AISIX 会在流到达时转发。流结束后，AISIX 执行检查并记录所有匹配。

下方缓冲区上限不适用于仅包含监控模式的输出链路。AISIX 会交付并观测超大响应，而不是拒绝它。如果任何强制执行的安全护栏也覆盖输出钩子，AISIX 会保留流，以便强制执行链路在交付前检查。

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

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

对于 AISIX Cloud，请把这些字段添加到安全护栏的 config 对象中。对于开源 AISIX 网关，请直接添加到 resources.yaml 的安全护栏条目中。fail_closed 会阻断过大的输出。fail_open 会释放 AISIX 无法完整检查或改写的输出，因此只有在可用性比严格输出治理更重要时才使用。未暴露这些字段的安全护栏类型使用内置上限，并在溢出时按关闭式失败处理。

处理远程安全护栏故障​

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

分别设置输入和输出失败策略：

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

mandatory 字段可以出现在资源文件条目和控制面载荷中。当 mandatory 为 true 时，即使 fail_open 本来会允许请求通过，远程安全护栏故障也会阻断流量。该外层策略还会将无法访问的监控模式安全护栏视为致命故障，但在监控模式下，内容匹配仍只用于观测。

内置关键词和 PII 安全护栏在网关内部运行，不会调用后端，因此远程故障处理不适用于它们。

当 AISIX 因远程安全护栏无法返回决策而允许流量时，请求或响应会在未经检查的情况下继续。该结果的遥测数据因端点而异，详见调用方响应与遥测。

调用方响应与遥测​

当安全护栏阻断代理流量时，AISIX 会保留所请求端点的错误约定：

  • 兼容 OpenAI 的路由返回 422 和 content_filter。
  • 透传路由返回 422，并使用同样的 OpenAI 风格 content_filter 错误信封。
  • 兼容 Anthropic 的非流式错误返回 422 和 invalid_request_error。
  • 兼容 Anthropic 的流式响应会以 Anthropic SSE 错误帧暴露阻断结果。

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

远程安全护栏 fail-open 时不会阻断请求或响应。对于 Chat Completions 流量，AISIX 会在用量事件中记录服务提供方特定的绕过原因，并递增安全护栏绕过指标。其他端点处理器当前不会填充绕过原因字段，因此请勿将该字段作为所有路由的唯一信号。

AISIX 会把每次计时的安全护栏执行记录到 aisix_guardrail_latency_seconds Prometheus 直方图中。标签标识安全护栏名称、种类、阶段和结果，其中包括监控模式下的 would_block/would_mask 结果，以及带失败原因的 fail-open bypassed 结果。流式窗口模式可以为一条输出响应记录多次执行；同步的逐字段 PII 和关键词脱敏操作不计入该直方图。可使用该指标跟踪各安全护栏的延迟（P50/P95/P99）、比较本地与远程检测，并观察阻断率和绕过率。标签和 PromQL 示例请参见指标参考。

下一步​

接下来，请选择服务提供方或配置网关内策略：