安全护栏
安全护栏中间件的六类治理能力——输入/输出过滤、查询注入防护、敏感数据脱敏、访问控制、个人信息检测、正反样本调优；入站/出站对称处置、流式逐 chunk、策略配置与能力边界
安全护栏是灵渠平台三类内建治理中间件之一（另两类为路由、缓存检查点，见 中间件管道）。它横切查询链路的入站与出站两端：在请求转发上游之前对入站查询施加过滤、注入防护、脱敏与访问控制，在响应返回客户之前对出站内容施加复核与脱敏。本节面向部署与运维灵渠平台的内部管理员，讲清安全护栏中间件提供的六类能力、它们在请求路径上的处置位次、如何配置启停，以及护栏处置的统一能力边界。
本节定位。 安全护栏是一套可配置的治理中间件骨架：平台内建六类护栏能力，管理员据此配置安全策略，也可经 扩展点 SDK 在护栏节点上叠加自定义护栏逻辑。护栏的所有处置都限于控制面 / 治理面（过滤、拦截、脱敏、清洗），不对结果内容做实质性生成或加工（见 §6）。护栏的拦截统计与能力基线属运营报告，见 API 参考 · 安全防护；个人信息与脱敏的数据留存口径见 数据安全。
1. 六类护栏能力
平台内建六类安全护栏能力，覆盖入站防护、出站治理与策略调优。各能力规则可配置、可独立启停：
| 能力 | 作用端 | 处置 | 平台护栏分类 |
|---|---|---|---|
| 输入 / 输出过滤 | 入站 + 出站 | 按关键词 / 模式匹配规则，过滤或拦截命中风险内容的请求与响应 | 应拒答拦截 |
| 查询注入防护 | 入站 | 检测并拦截常见的提示注入 / 越狱 / 诱导绕过攻击模式 | 注入防护 |
| 敏感数据脱敏 | 入站 + 出站 | 对手机号、身份证号等敏感字段按规则自动脱敏 | 脱敏 |
| 访问控制 | 入站 | 基于调用方身份对查询施加访问鉴权策略 | 访问控制 |
| 个人信息检测 | 入站 | 检测查询输入中是否含个人信息，供据以执行"不纳入训练、不上送上游"策略 | 脱敏 |
| 正反样本调优 | 策略面 | 注入安全策略与正反样本，对护栏判定行为进行训练 / 调优 | （策略面，不直接处置单次请求） |
上表「平台护栏分类」列对应运营侧「安全防护」统计的拦截分类（注入防护 / 脱敏 / 应拒答拦截 / 访问控制，见 API 参考）。前五类在请求路径上逐次处置，第六类「正反样本调优」作用于护栏的判定策略本身，不直接处置单次请求。
1.1 输入 / 输出过滤
按管理员配置的关键词与模式匹配规则，对入站查询与出站响应做内容过滤。命中风险规则的，可按规则动作拒答（入站拦截、不转发上游）或在出站时拦截响应。规则集可分别面向入站与出站维护，支持按风险类型分组。
1.2 查询注入防护
检测并拦截常见的对抗性攻击模式——提示注入、越狱诱导、指令绕过等。注入防护在入站段执行，命中即结构化拒答，不让被污染的查询触达上游模型。内建模式库可由管理员扩充，亦可经扩展点叠加自定义的注入识别逻辑。
1.3 敏感数据脱敏
对查询与响应中的敏感字段（手机号、身份证号、银行卡号等）按规则自动脱敏。脱敏在本实例内就地完成，入站脱敏降低敏感信息上送上游的风险、出站脱敏避免敏感片段随响应回到客户端。脱敏规则（字段类型、匹配模式、替换形态）可配置。脱敏后的留存与数据策略见 数据安全 · 个人信息处理。
1.4 访问控制
基于调用方身份对查询施加访问鉴权策略，作为入站护栏的一道身份闸门。它与 治理与配额 的密钥鉴权、模型访问范围约束相衔接——后者在请求进入管道前先做密钥有效性与模型范围校验（越权模型路由前被拒），护栏访问控制则在治理面对查询内容与操作施加更细的身份相关策略。
1.5 个人信息检测
检测查询输入中是否含个人信息，并据此驱动"含个人信息者不纳入路由小模型训练、不上送上游"的策略执行。检测与处置都在本实例内完成；检测结果用于触发脱敏（§1.3）与数据策略，不构成对查询内容的二次采集。个人信息的留存与不二次利用口径见 数据安全 · 个人信息处理。
1.6 正反样本调优
护栏的判定行为可经正反样本训练 / 调优：管理员注入安全策略与一组正反样本（应拦截样本 + 不应拦截的良性样本），平台据以优化护栏的拦截与放行判定，逐步收敛"应拒答拦截"与"良性误拦"两端。
与路由小模型微调相区分。 本节的正反样本调优作用于安全护栏的判定策略，与 路由小模型微调（训练用于查询复杂度分类的路由小模型）是两套独立机制：前者调优护栏的安全判定、后者改变路由的复杂度研判，互不混同。
2. 入站护栏与出站护栏（对称处置）
安全护栏作为治理中间件挂在 中间件管道 上，按段位对称处置：入站护栏落在前置段、出站护栏落在后置段。
| 护栏能力 | 段位 | 命中 / 检出动作 |
|---|---|---|
| 查询注入防护 | 前置（入站） | 拒答 reject——不转发上游、结构化拒答 |
| 访问控制 | 前置（入站） | 拒答 reject——身份鉴权不过 |
| 输入过滤 | 前置（入站） | 拒答 reject——命中风险规则 |
| 敏感数据脱敏（入站） | 前置（入站） | 改写 rewrite——脱敏后继续 |
| 个人信息检测 | 前置（入站） | 检出驱动策略处置——不纳入训练、不上送上游 |
| 输出过滤 / 应拒答复核 | 后置（出站） | 拦截 block——结构化返回 |
| 敏感数据脱敏（出站） | 后置（出站） | 脱敏 redact——去除敏感片段后放行 |
- 入站护栏在请求转发上游之前完成。命中拦截类规则时请求根本不会触达上游，治理与节流同时达成。
- 出站护栏在上游响应返回之后、回到客户端之前完成，命中即
block（拦截）或redact（脱敏）。入站的reject/rewrite与出站的block/redact四类动作语义与 扩展点 SDK §2 的 Hook 动作一致。 - 流式逐 chunk：流式响应（
stream: true）下，出站护栏对每一个 chunk 逐块施加处置，确保违规内容在生成过程中即被治理，不先于护栏抵达客户端（见 概念与编排 §2.5）。
每次请求的护栏处置结果落入逐条调用记录的 guardrail_result 字段（取值：通过 / 拦截 / 脱敏 / 误拒），可在「安全防护」与「用量明细」页追溯（见 API 参考）。
3. 护栏策略配置
六类护栏能力以一份护栏策略统一配置，可读取与更新：
curl https://your-platform/api/v1/security/policy \
-H "Cookie: <控制台会话凭证>"响应给出各能力的启停与规则集：
{
"guardrails": [
{ "kind": "io_filter", "enabled": true, "scope": ["inbound", "outbound"], "rules": ["<关键词 / 模式规则>"] },
{ "kind": "injection_defense", "enabled": true, "scope": ["inbound"] },
{ "kind": "pii_redaction", "enabled": true, "scope": ["inbound", "outbound"], "fields": ["phone", "id_card", "bank_card"] },
{ "kind": "access_control", "enabled": true, "scope": ["inbound"], "policy_ref": "<访问策略引用>" },
{ "kind": "pii_detection", "enabled": true, "scope": ["inbound"], "on_detect": "exclude_from_training_and_upstream" },
{ "kind": "sample_tuning", "enabled": true }
]
}| 字段 | 含义 |
|---|---|
kind | 护栏能力类型（对应 §1 六类） |
enabled | 是否启用；停用的能力保留配置但执行时跳过 |
scope | 作用端：inbound（入站）/ outbound（出站） |
rules / fields / policy_ref | 该能力的规则集、脱敏字段或访问策略引用 |
on_detect | 个人信息检测的检出处置（如不纳入训练、不上送上游） |
命中动作不在策略中逐条指定。 命中后的动作由「作用端 × 能力类型」决定（见 §2）——入站过滤 / 注入防护 / 访问控制命中
reject、入站脱敏rewrite、出站过滤block、出站脱敏redact；正反样本调优作用于判定策略本身、不直接处置单次请求。
提交更新用同一端点的 PUT：
curl https://your-platform/api/v1/security/policy \
-X PUT \
-H "Content-Type: application/json" \
-H "Cookie: <控制台会话凭证>" \
-d '{ "guardrails": [ { "kind": "pii_redaction", "enabled": true, "fields": ["phone", "id_card"] } ] }'护栏策略变更仅运营控制台可见，即时对后续请求生效；停用某项能力即在执行时跳过，便于灰度与回退。规则集的具体内容、敏感字段清单与访问策略以控制台「安全防护」页配置为准。
4. 正反样本调优接口
向护栏注入安全策略与正反样本，对其判定行为进行训练 / 调优：
curl https://your-platform/api/v1/security/samples \
-X POST \
-H "Content-Type: application/json" \
-H "Cookie: <控制台会话凭证>" \
-d '{
"positive_samples": [ { "query": "<应拦截示例>", "label": "should_block" } ],
"negative_samples": [ { "query": "<不应拦截的良性示例>", "label": "benign" } ],
"policy_note": "<本批样本对应的安全策略说明>"
}'| 字段 | 含义 |
|---|---|
positive_samples | 正样本：应被护栏拦截 / 拒答的示例 |
negative_samples | 负样本：不应被拦截的良性示例（用于压低误拦） |
label | 样本标注（如 should_block / benign） |
policy_note | 本批样本对应的安全策略说明 |
正反样本调优只优化护栏自身的安全判定策略，不触及上游模型、不改变路由的复杂度研判。它的目标是让"应拒答拦截"与"良性误拦"两端协同收敛——拦得住该拦的、放得过正常的。
5. 拦截统计与处置结果
护栏的运行结果以两种形态可观测：逐请求的处置标识、与聚合的拦截统计。
| 形态 | 端点 / 字段 | 用途 |
|---|---|---|
| 逐请求处置结果 | 逐条调用记录的 guardrail_result（通过 / 拦截 / 脱敏 / 误拒） | 单次请求的护栏处置可追溯 |
| 拦截统计聚合 | GET /api/v1/security/overview（拦截总次数 + 分类 + 误拒率） | 按时间段汇总各分类拦截量与误拒率 |
| 能力基线 | GET /api/v1/security/baseline（成对核验指标） | 应拒答拦截率与误拒率、对抗拦阻率与良性误拦率等成对呈现 |
拦截统计与能力基线属运营 / 客户可见的安全防护报告，端点契约见 API 参考 · 安全防护。能力基线以成对指标呈现（拦截类与误拒类成对核验），具体阈值以服务协议与控制台为准；本页只讲护栏中间件的处置能力，不展开基线阈值。
6. 能力边界
安全护栏的所有处置都限于控制面 / 治理面，与 中间件管道的统一能力边界 一致：
护栏只对请求与响应施加治理处置——过滤、注入防护、脱敏、访问鉴权、拦截、安全复核——不对结果内容做实质性的生成、加工或合成。
rewrite与redact都限于治理面改写（去除或替换敏感 / 风险片段），不构成对生成内容的实质性创作；内容生成始终由路由选定的上游模型完成。
这条边界既是护栏的设计原则，也写入护栏节点在「中间件编排」页的能力边界标注。
7. 失败处置
护栏处置过程中的异常按"治理可控、宁严勿松"处置：安全护栏类节点默认 fail-closed——"宁可拒绝，不放行未经复核的内容"，与 扩展点 SDK §5 的失败策略基线一致。
| 情形 | 处置 |
|---|---|
| 入站护栏命中拦截规则 | 结构化拒答，不转发上游；处置结果记为对应拦截类别 |
| 入站护栏执行报错 | 默认 fail-closed（拒绝）；已发生的治理处置照常落账 |
| 出站护栏命中复核未过 | 拦截出站响应、结构化返回；已发生的上游调用与计量按实落账 |
| 出站护栏执行报错 | 默认拦截（护栏类 fail-closed）；不影响已完成的上游调用与计量 |
fail-closed 是护栏类节点的安全基线。经扩展点叠加的自定义护栏逻辑同样默认 fail-closed，可在注册时按需声明（见 扩展点 SDK §5、自定义插件开发 §5）。
相关章节
- 中间件管道与扩展点 SDK：安全护栏作为三类治理中间件之一的执行位次、前置 / 后置 Hook 与流式逐 chunk 处理。
- 扩展点 SDK 参考：在护栏节点上叠加自定义护栏逻辑的 Hook 模型、动作枚举与失败处置。
- 数据安全：脱敏与个人信息处理的数据留存、不二次利用与退出口径。
- 治理与配额：密钥鉴权与模型访问范围约束——护栏访问控制的前置闸门。
- API 参考 · 控制平面：
/api/v1/security/*护栏策略、样本调优与安全防护统计的端点契约。