Higress AI 数据脱敏ai-data-masking插件敏感词拦截与替换实战指南【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higressHigress 的ai-data-maskingAI 数据脱敏插件是一款运行在认证阶段优先级 991的 WASM 插件用于对 AI 网关请求/响应中的敏感信息进行拦截与脱敏替换在保证敏感数据不出域的前提下让大模型正常参与业务推理。阅读本文后你将掌握该插件的处理数据范围、全部配置字段与默认值、基于 GROK/正则的替换规则设计以及流式SSE场景下的还原机制与已知限制并能在自己的 Higress 网关上直接复现文中的完整配置示例。该插件源码位于 plugins/wasm-rust/extensions/ai-data-masking核心实现集中在 src/ai_data_masking.rs配套 README.md 与 README_EN.md 提供了中英文配置参考。一、功能说明与处理数据范围插件核心能力只有两件事对请求/返回中的敏感词进行拦截、替换。1.1 处理数据范围三种粒度范围说明openai 协议请求/返回中的对话内容messages[*].content及reasoning_contentjsonpath只处理通过 JSONPath 指定的字段raw处理整个请求/返回 body非 JSON 场景三种模式并非互斥配置项deny_openai、deny_jsonpath、deny_raw可同时开启插件按 openai → jsonpath → raw 的顺序逐级处理。从源码实现看请求体处理逻辑位于 on_http_request_complete_body插件首先尝试将 body 反序列化为 JSON若deny_openai开启且能解析出 OpenAI 协议结构stream字段 messages数组则标记is_openai true并逐条检查content与reasoning_content否则继续尝试 jsonpath 命中字段最后才进入 raw 整包处理。响应方向对应 on_http_response_complete_body同样按 openai 与 raw 两条路径执行拦截与还原。1.2 敏感词拦截在数据处理范围内命中敏感词时直接拦截返回预设错误信息支持系统内置敏感词库与自定义敏感词deny_words两种来源。内置词库通过rust-embed在编译期打包进 WASM 产物数据文件为 res/sensitive_word_dict.txt约 6.4 万行由 src/deny_word.rs 的DenyWord::system()加载。词库数据来源为开源项目 houbb/sensitive-word-data。需要特别注意的是匹配算法DenyWord::check()使用jieba 分词后逐个词在HashSet中精确比对见 deny_word.rs因此deny_words必须配置为单个单词英文多词短语如hello world由于分词粒度问题可能无法匹配。1.3 敏感词替换将请求数据中出现的敏感词替换为脱敏字符串后再传给后端服务保证敏感数据不出域部分脱敏数据在后端服务返回后可自动还原自定义规则支持标准正则与GROK 规则替换字符串支持正则变量如$domain。替换规则由replace_roles数组定义每条规则包含regex支持 GROK 语法、typereplace或hash、restore是否还原、value替换值。其核心实现位于 replace_request_msg纯替换且不还原replacerestorefalse直接对全文做replace_all需要还原或 hash 的场景逐条正则匹配后用HMAC-SHA256对原文计算十六进制摘要hash类型或按规则生成替换值并把「脱敏值 → 原始值」的映射写入请求级mask_map见 ai_data_masking.rs响应阶段遍历mask_map把大模型返回内容中的脱敏值替换回原始值后再转发给用户。由此实现出域前脱敏、回程时还原示例见第五节。二、运行属性插件执行阶段认证阶段Authentication Phase插件执行优先级991这意味着 ai-data-masking 在 Higress 的认证环节即开始生效早于后续路由与转发逻辑保证敏感词在被转发到后端前就已完成拦截或脱敏。插件基于 proxy-wasm 的RootContext/HttpContext模型实现在 ai_data_masking.rs 通过proxy_wasm::main!注册入口并复用了 Higress WASM Rust SDK 的RuleMatcher规则匹配框架支持按路由/域名粒度下发不同配置。三、配置字段详解名称数据类型默认值描述deny_openaibooltrue对 OpenAI 协议进行拦截deny_jsonpathstring[]对指定 jsonpath 字段拦截deny_rawboolfalse对原始 body 拦截system_denyboolfalse开启内置拦截规则deny_codeint200拦截时的 HTTP 状态码deny_messagestring提问或回答中包含敏感词已被屏蔽拦截时 OpenAI 协议返回的 AI 消息deny_raw_messagestring{errmsg:提问或回答中包含敏感词已被屏蔽}非 openai 拦截时返回的内容deny_content_typestringapplication/json非 openai 拦截时返回的 Content-Type 头deny_wordsarray of string[]自定义敏感词列表replace_rolesarray-自定义敏感词正则替换规则replace_roles.regexstring-规则正则支持内置 GROK 规则replace_roles.type[replace, hash]-替换类型replace_roles.restoreboolfalse是否在响应中还原replace_roles.valuestring-替换值支持正则变量上述默认值均与源码中的反序列化逻辑一一对应见 ai_data_masking.rs 的default_deny_*系列函数其中deny_code在源码中被解析为u16类型配置时注意取值范围。配置解析阶段值得一提的细节regex字段由 deserialize_regexp 完成反序列化配置加载时先尝试把内容当作GROK 模式编译失败则回退为标准正则编译两者都不合法时直接报配置错误deny_jsonpath由 deserialize_jsonpath 解析为jsonpath_rust::JsonPath对象非法路径会在配置阶段报错type字段仅接受replace/hash两个取值deserialize_type。四、完整配置示例system_deny: true deny_openai: true deny_jsonpath: - $.messages[*].content deny_raw: true deny_code: 200 deny_message: 提问或回答中包含敏感词已被屏蔽 deny_raw_message: {\errmsg\:\提问或回答中包含敏感词已被屏蔽\} deny_content_type: application/json deny_words: - 自定义敏感词1 - 自定义敏感词2 replace_roles: - regex: %{MOBILE} type: replace value: **** # 手机号 13800138000 - **** - regex: %{EMAILLOCALPART}%{HOSTNAME:domain} type: replace restore: true value: ****$domain # 电子邮箱 admingmail.com - ****gmail.com - regex: %{IP} type: replace restore: true value: ***.***.***.*** # ip 192.168.0.1 - ***.***.***.*** - regex: %{IDCARD} type: replace value: **** # 身份证号 110000000000000000 - **** - regex: sk-[0-9a-zA-Z]* restore: true type: hash # hash sk-12345 - 9cb495455da32f41567dab1d07f1973d # hash后的值提供给大模型从大模型返回的数据中会将hash值还原为原始值4.1 内置 GROK 规则说明示例中出现的%{MOBILE}、%{EMAILLOCALPART}、%{HOSTNAME}、%{IP}、%{IDCARD}均来自 GROK 内置规则。源码在 ai_data_masking.rs 中额外注册了两个系统模式static SYSTEM_PATTERNS: [(str, str)] [ (MOBILE, r#\d{8,11}#), (IDCARD, r#\d{17}[0-9xX]|\d{15}#), ];GROK 模式展开采用迭代替换算法grok_to_pattern先解析%{PATTERN:alias}语法将命名的 GROK 模式逐层展开为最终正则并支持通过:alias给捕获组命名——这正是邮箱规则中%{HOSTNAME:domain}搭配替换值****$domain实现保留域名替换的底层机制。4.2 拦截响应形态命中敏感词后的响应行为在 deny 中实现与is_openai、stream状态相关请求方向拦截直接send_http_response返回deny_code状态码与deny_messageOpenAI 场景会包装为 choices 结构非 openai / raw 拦截返回deny_raw_message内容与deny_content_type头响应方向拦截流式置空响应体并Continue避免向用户输出不完整内容。五、敏感词替换样例还原链路演示5.1 用户请求内容请将curl http://172.20.5.14/api/openai/v1/chat/completions -H Authorization: sk-12345 -H Auth: testgmail.com改成post方式5.2 处理后请求大模型内容curl http://***.***.***.***/api/openai/v1/chat/completions -H Authorization: 48a7e98a91d93896d8dac522c5853948 -H Auth: ****gmail.com改成post方式可以看到三类处理同时生效172.20.5.14IP→***.***.***.***且restore: true会登记还原映射sk-12345API Keyhash类型→48a7e98a91d93896d8dac522c5853948HMAC-SHA256 摘要testgmail.com邮箱→****gmail.com通过 GROK 别名变量保留域名。5.3 大模型返回内容大模型在完全不知晓原始敏感值的情况下完成改写任务curl -X POST \ -H Authorization: 48a7e98a91d93896d8dac522c5853948 \ -H Auth: ****gmail.com \ -H Content-Type: application/json \ -d {key:value} \ http://***.***.***.***/api/openai/v1/chat/completions5.4 处理后返回用户内容插件在响应阶段根据mask_map将脱敏值还原为原始值用户拿到的结果与原始请求完全一致curl -X POST \ -H Authorization: sk-12345 \ -H Auth: testgmail.com \ -H Content-Type: application/json \ -d {key:value} \ http://172.20.5.14/api/openai/v1/chat/completions还原逻辑对应响应处理代码中的mask_map.iter()遍历替换ai_data_masking.rs先检查响应内容是否含敏感词命中则拦截再把脱敏值替换回原始值。六、流式SSE模式下的实现与限制OpenAI 流式响应以data:前缀的 SSE chunk 形式下发脱敏/还原必须跨 chunk 拼接处理。插件通过 msg_win_openai.rs 的MsgWindow实现使用higress_wasm_rust::event_stream::EventStream解析 SSE 事件流按choices[*].index维护独立的MessageWindowOpenAi滑动窗口逐 chunk 累积文本后执行敏感词检查与还原替换并将usage字段通过 number_merge.rs 的NumberMerge做跨 chunk 累加合并保证重写后的流式响应在结构与统计字段上依然完整合法。非 OpenAI 流则退化为 msg_window.rs 的通用字节窗口。该窗口模块自带单元测试msg_win_openai.rs使用 test/raw_message.txt 中的真实流式报文逐行喂入验证content与reasoning_content跨 chunk 替换后能无损还原拼接结果。6.1 相关说明已知限制流模式中如果脱敏后的词被多个 chunk 拆分可能无法进行还原流模式中如果敏感词被多个 chunk 拆分可能会有敏感词的一部分返回给用户的情况GROK 内置规则列表可参考阿里云 SLS 用户指南的 grok-patterns 文档内置敏感词库数据来源为 houbb/sensitive-word-data 项目由于敏感词列表是在文本分词后进行匹配的请将deny_words设置为单个单词英文多单词情况如hello world可能无法匹配。这四点限制均与滑动窗口的实现边界直接相关——窗口重叠区char_window_size * 2/byte_window_size * 2见 on_http_response_body的设计正是为了尽量降低跨 chunk 拆词概率但仍无法覆盖极端拆分场景生产使用时建议将脱敏词设计为不易被截断的形态。七、如何接入与验证该插件为 Higress 的 WASM Rust 插件构建产物为 cdylib见 Cargo.toml当前版本记录在 VERSION2.0.2。完整构建与发布流程可参考 plugins/wasm-rust/Makefile 及 plugins/wasm-rust/README.md在 Higress 中通过 WasmPlugin CRD 将插件挂载到网关或指定域名并将上文配置示例写入defaultConfig即可生效插件声明在认证阶段、优先级 991会先于普通路由规则执行验证时可先开启system_deny: true观察内置词库命中行为再按第四节示例配置替换规则并用第五节样例中的 curl 请求做端到端对比比对发往大模型的请求体应已脱敏与最终返回用户的内容应已还原。通过合理组合deny_openai/deny_jsonpath/deny_raw三种作用域、replace/hash两种替换类型以及restore还原开关ai-data-masking 插件可以在 AI 网关链路上实现敏感数据不出域、业务功能不降级的合规目标是 AI 网关数据安全治理中一个可直接落地的方案。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考