跳到主要内容

安全护栏行为

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

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

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

检查位置​

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

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

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

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

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

安全护栏匹配​

选择钩子点后，使用作用范围控制哪些请求可以到达安全护栏。在自托管部署中，通过 Admin API 创建的安全护栏会应用于整个环境。AISIX 托管控制面则可以将安全护栏附加到环境，或附加到选定的模型别名、调用方 API Key 或团队。

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

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

执行模式​

安全护栏的 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"
}

如需调整缓冲上限或溢出行为，请在安全护栏资源中添加这些字段。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放行未扫描的响应。阻断响应。

Admin API 和控制面载荷中可能出现 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_guardrail_latency_seconds Prometheus 直方图记录一次观测，并带有安全护栏名称、种类、阶段和结果标签，其中包括监控模式下的 would_block/would_mask 结果，以及带失败原因的 fail-open bypassed 结果。可使用该指标跟踪各安全护栏增加的延迟（P50/P95/P99）、比较本地检测与远程检测，并观察阻断率和绕过率。有关标签和 PromQL 示例，请参阅测量安全护栏延迟和结果。

下一步​

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