# 安全围栏与语义审计

来源: https://platform.lyrouter.com/ai_gateway/docs/guardrails
更新日期: 2026-10-22

安全围栏是工作空间级的调用策略：网关按策略检查每次调用的配额、模型、客户端和请求内容，命中后告警、掩码、剥离、阻断或封禁，并在 **安全事件** 页留下记录。配额管理、模型访问控制、客户端访问控制从团队版起可用；敏感信息检测、提示词注入检测、意图安全检测需要企业版。策略和事件都由当前账号管理员在工作空间的 **安全围栏**、**安全事件** 页管理，普通成员看不到这两个页面。

## 策略类型与版本

| 策略类型 | 检查什么 | 可选动作 | 拦截时的 `error.code` | 最低版本 |
| --- | --- | --- | --- | --- |
| 配额管理 | 统计周期内的信用点或 Token 用量，可另设 RPM、TPM | 阻断、告警 | 返回 429，见[预算、配额与限流](https://platform.lyrouter.com/ai_gateway/docs/quota) | 团队版 |
| 模型访问控制 | 实际调用的模型 | 阻断 | `guardrail_model` | 团队版 |
| 客户端访问控制 | 来源 IP、请求声明的工具名、`User-Agent` | 阻断、告警 | `guardrail_client` | 团队版 |
| 敏感信息检测 | 请求或回答中的个人信息、凭证和敏感关键词 | 请求侧：阻断、告警、掩码；响应侧：阻断、告警 | `guardrail_sensitive` | 企业版 |
| 提示词注入检测 | 用户输入中试图改写模型指令的内容 | 阻断、告警、剥离 | `guardrail_injection` | 企业版 |
| 意图安全检测 | 请求意图是否属于高风险类型 | 封禁、阻断、告警 | `guardrail_context` | 企业版 |

- **版本按订阅判断**：没有有效订阅的组织按个人版处理。个人版能看到两个菜单，但页面显示「当前版本不支持使用此功能」；个人账户不能直接订阅，需要先创建团队或企业组织，再在 **订阅充值** 页开通。
- **降级后存量策略继续生效**：当前版本不包含某类策略时（例如从企业版降到团队版），已创建的这类策略仍会在网关上拦截或掩码请求。页面会提示这一点，你可以停用或删除它们，但不能新建或修改。
- **事件保留期**：安全事件默认在团队版保留 30 天、企业版保留 180 天，超过保留期后无法在列表或详情中查到。

（截图：当前订阅版本不包含安全事件时，页面显示「当前版本不支持使用此功能」和升级入口。）

## 新建策略

在 **安全围栏** 切到对应类型的页签，点右上角的新建按钮（例如「新建配额管理策略」），按三步完成：

1. **生效对象**：「对象类型」选「工作空间」「部门」「组织成员」或「API Key」，并选择具体对象。模型访问控制不能选「工作空间」。
2. **策略规则**：填写「策略名称」（至少 2 个字符）和该类型的规则，再选「执行动作」。策略类型由所在页签决定，保存后不能更改。
3. **生效时间**：选「立即生效」或「定时生效」，以及「永久有效」或「指定失效时间」。最后点「保存草稿」（不生效）、「保存并启用」或「保存并设置定时生效」。

只有状态为「已启用」且处在生效时间内的策略才会执行。列表中可以随时停用、启用、编辑或删除策略。

| 生效对象 | 覆盖哪些调用 |
| --- | --- |
| 工作空间 | 本工作空间的全部调用 |
| 部门 | 创建人的主部门恰好是所选部门的 API Key，不含子部门 |
| 组织成员 | 所选成员创建的全部 API Key |
| API Key | 所选的 API Key |

同一次调用适用多条策略时，所有策略同时执行，不是只取最具体的一条。例如工作空间级和某个 API Key 上的敏感信息策略都会检查；工作空间配额和成员配额是两个独立上限，任一触顶都会拒绝。

（截图：编辑策略的第一步「生效对象」：选择对象类型和具体部门，配额策略还要选择配额模式。）

## 各类策略的规则

**配额管理** 与 **模型访问控制** 分别见[预算、配额与限流](https://platform.lyrouter.com/ai_gateway/docs/quota)和[模型授权](https://platform.lyrouter.com/ai_gateway/docs/authorization)。

### 客户端访问控制

每条策略选一种「控制对象」，再选「允许名单」或「拒绝名单」：

| 控制对象 | 匹配什么 | 写法 |
| --- | --- | --- |
| IP / CIDR | 网关识别到的请求来源 IP | IPv4、IPv6 或网段，例如 `10.0.0.0/8` |
| 工具 / function | 请求体 `tools`（或 `functions`）中声明的函数名 | 支持 `*` 通配；请求没有声明工具时不检查 |
| 客户端 / SDK | 请求头 `User-Agent` | 支持 `*` 通配，整串匹配，区分大小写，例如 `company-agent/*` |

工具名使用允许名单时，请求声明的每一个工具都必须在名单内；使用拒绝名单时，任意一个工具命中即违规。

### 敏感信息检测

- **检测类别**：身份证号、手机号、银行卡号、护照号、电子邮箱、家庭住址、车牌号、统一社会信用代码、内部凭证，以及按关键词识别的财务数据、健康数据、商业秘密。新建时默认勾选身份证号、手机号、银行卡号和内部凭证。身份证号、银行卡号和统一社会信用代码会校验校验位。
- **自定义规则**：「自定义信息类别与脱敏规则」中每条填写类别名称、正则表达式和可选的脱敏风格，最多 50 条。
- **检测方向**：「请求」「响应」或「请求与响应」。响应侧只做规则检测，动作只能是阻断或告警。
- **检测引擎**：「规则」或「混合」。「混合」还会用语义模型识别套取敏感数据的意图；语义命中没有可定位的文字，动作为掩码时会改为阻断。
- **检测范围**：默认「仅用户输入」，只检查用户消息；「整段对话（含助手回复与工具返回）」检查得更全，误报也明显更多，建议先用「告警」观察。
- **脱敏风格**：「整体替换」（默认，替换为 `[REDACTED]`）、「保留部分位」（如手机号 `138****5678`）、「哈希化」（替换为 `[SHA256:…]`，同一个值结果相同）。财务数据、健康数据、商业秘密匹配的是关键词而不是具体数值，不能选掩码，否则保存失败。

### 提示词注入检测

- **检测类别**：直接指令覆盖、直接注入、系统提示词泄露、角色扮演越狱、分隔符与格式逃逸、编码混淆、多语言绕过、载荷拆分、间接注入、对抗性后缀、越权指令、工具劫持。
- **检测引擎**：「规则」「语义」或「混合」。
- **灵敏度**：「低」「中」「高」，越高越严格：「高」拦截最多，误报也最多；「低」只拦截把握最大的请求。新建时默认「高」。
- **剥离**：把命中的片段替换为 `[REMOVED]` 后继续转发；只有语义命中、没有可定位片段时改为阻断。注入检测只检查请求，不检查回答。

### 意图安全检测

- **高风险意图类型**：敏感数据泄露、破坏性操作、欺诈、系统越权、恶意代码植入。
- **置信度阈值**：0.5～1，默认 0.9，风险概率达到或超过阈值才算命中。
- **封禁**：动作选「封禁」时还要填「自动解封时间（小时）」，范围 1～8760，默认 24。
- 保存前必须勾选「开启并同意用于跨会话安全分析」。

**适用接口**：敏感信息、提示词注入和意图安全检测只作用于 `/v1/chat/completions`、`/v1/messages` 和 `/v1/responses`。向量、图像、音频、视频和重排序接口只执行封禁、模型访问控制和客户端访问控制检查。语义检测服务暂时不可用时，语义部分不会拦截请求，规则检测照常执行。

## 调用方看到什么

| 执行动作 | 网关行为 | 调用方看到 |
| --- | --- | --- |
| 告警 | 放行请求，记录安全事件并发送通知 | 正常响应 |
| 掩码 | 把命中内容替换后再转发给模型 | 正常响应，模型收到的是掩码后的内容 |
| 剥离 | 把命中的注入片段替换为 `[REMOVED]` 后转发 | 正常响应 |
| 阻断（请求侧） | 不调用模型 | 403 `Request blocked by guardrail policy`，`error.code` 为 `guardrail_<类型>` |
| 阻断（响应侧，非流式） | 丢弃模型的回答 | 403 `Response blocked by guardrail policy`，`error.code` 为 `guardrail_sensitive`。上游已经生成回答，这次调用照常计费 |
| 阻断（响应侧，流式） | 响应已经开始输出，无法再返回 403，改为掩码 | 回答照常输出，命中内容被掩码 |
| 封禁 | 拒绝本次请求，并封禁这把 API Key | 本次 403 `Request blocked by guardrail policy`（`guardrail_context`）；之后 403 `Subject is blocked by an active security ban`（`guardrail_subject_banned`） |

- 报错原文不包含策略名称和命中内容，同样的请求重试会得到同样的结果。各报错的处理方法见[401 / 403：鉴权与权限](https://platform.lyrouter.com/ai_gateway/docs/auth-errors)。
- 开启响应侧检测后，流式回答每段末尾约 64 字节会稍晚发出，用于识别被拆在两段之间的号码。
- 封禁在这条安全事件入库后建立，作用于这把 Key 在本工作空间的全部请求，期间每次被拒绝都会记一条「主体处于封禁状态」事件。到达「自动解封时间（小时）」后自动解除，也可以提前手动解除，见下文。

## 查看和处置安全事件

**安全事件** 页顶部的「今日事件」「今日阻断」「待处置」「当前封禁」可以一键筛选；列表支持按事件、请求、链路或主体搜索，并按事件类型、严重级别、处置状态和时间筛选，「导出」按当前筛选条件下载。

打开一条事件，详情包括：

| 区块 | 看什么 |
| --- | --- |
| 基本信息 | 发生时间、事件类型、触发策略、触发主体、执行动作、严重级别、处置状态、模型、客户端。「触发主体」显示 API Key 名称和创建人，创建人是 Key 的创建者，不一定是实际调用者 |
| 触发时间线 | 「请求到达」→「围栏命中」（请求侧或响应侧，规则命中、语义命中及分数，或配额触顶）→「执行动作」。实际动作与配置不同时会写明原因，例如「响应已开始流式输出，阻断无法执行」「语义命中无字符位置，掩码降级为阻断」 |
| 匹配详情 | 命中规则、触发阈值、置信度、检测器和请求 ID |
| 取证原文 · 已脱敏 | 敏感信息和注入检测在请求侧命中时，显示命中位置附近的原文，敏感值已脱敏，查看行为会写入审计；配额、模型、客户端类事件不采集请求内容 |
| 处置时间线 | 每次处置的动作、状态、备注、操作人和时间 |

点「查看关联访问日志」可以直接打开这次请求的[日志](https://platform.lyrouter.com/ai_gateway/docs/logs)详情。

**处置**：在「处置备注」中写明结论后，点「确认事件」（变为「已确认」）、「标记误报」（「误报」）或「完成处置」（「已解决」）。封禁类事件还有「解除主体封禁」，执行后状态变为「已解决」，几秒内撤销这把 Key 在本工作空间的封禁。在列表中勾选多条事件可以批量处置，单次最多 500 条，超出部分需要再执行一次。处置只改变事件状态，不修改策略；误报较多时请回到安全围栏调整策略。

## 常见问题

### 同一个问题为什么只生成了一条事件？

**答：** 为避免列表被刷屏，敏感信息和提示词注入检测在 5 分钟内对同一策略、同一 Key、同一类别的命中合并为一条事件；配额触顶按统计周期合并。合并只影响事件记录，每次请求的拦截或掩码照常执行，每个被拦截的请求在[日志](https://platform.lyrouter.com/ai_gateway/docs/logs)中都有记录。

### 成员报告请求被拦截，账号管理员怎么找到对应事件？

**答：** 请成员提供调用时间、API Key 名称和报错中的 `error.code`，账号管理员在安全事件中按时间范围和事件类型筛选。能在日志中找到这次请求时，把日志详情顶部的 Request ID 粘贴到安全事件的搜索框，即可定位到对应事件。