源码分析 on WYF 的技术博客

Higress 02：key-auth 插件原理与代码导读（结合 docker demo 实战）

Thu, 17 Sep 2026 22:15:51 +0800

导读对象有两份，对照着看：

代码：citic-wasm-plugin/key-auth/main.go（364 行，Higress 官方 key-auth 移植版）

Demo：higress/key-auth-docker-demo/（docker-compose.yaml + envoy.yaml + plugin.wasm + test.sh）

Demo 的价值：它绕开 K8s 和 Higress 控制面，用裸 Envoy 直接加载插件，于是"插件挂在哪、配置长什么样、每个分支对应什么现象"全部看得见摸得着。读完这两份，Wasm 插件从部署到代码的整条链路就通了。

第 1 章是所有 Higress Wasm 插件通用的运行原理，提炼自《ai-security-guard插件实现原理.md》的 §2~§4、§13——原理是相通的，这里做了 key-auth 视角的对照改写；两篇文档互为补充。

0. Demo 全景：一条请求的全部旅程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


curl → localhost:10000
 │
 ▼ docker-compose 里的两个容器
 ┌─────────────────────────────────────────┐
 │ envoy 容器（higress/gateway:v2.2.4） │
 │ 监听 :10000 │
 │ listener → HttpConnectionManager │
 │ → 路由匹配（Host + 路径） │
 │ → wasm filter（加载 plugin.wasm）★ │ ← key-auth 代码在这里跑
 │ → router filter │
 │ → 转发到 cluster httpbin │
 └───────────────┬─────────────────────────┘
 ▼
 ┌─────────────────────────────────────────┐
 │ httpbin 容器（go-httpbin，:8080） │ ← 后端，回显请求信息
 └─────────────────────────────────────────┘

四个文件各管一件事：

文件	作用
`docker-compose.yaml`	起两个容器，把 envoy.yaml 和 plugin.wasm 挂进 envoy 容器，10000 端口暴露给宿主机
`envoy.yaml`	Envoy 的全部配置：监听、路由、wasm filter 及其配置、后端 cluster
`plugin.wasm`	key-auth 的编译产物（`GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared`）
`test.sh`	5 个 curl 场景，每个对应代码里一个分支

1. Wasm 插件通用运行原理（与 ai-security-guard 相通）

本章机制对所有 Higress Wasm 插件都成立。每节分「通俗理解」与「技术实现」两层，技术实现层都给出 key-auth 的具体对照。

1.1 地基：沙箱、hostcall 与"每线程一个 VM"

通俗理解

Higress 的数据面是 Envoy，给它加功能传统上要改 C++ 源码重新编译——门槛高、风险大。Wasm（WebAssembly）换了个思路：插件编译成 .wasm 二进制，运行在 Envoy 内部的沙箱虚拟机里。

打个比方：Envoy 是一栋大楼，Wasm 插件是楼里的"租客"——住在隔音隔热的房间里（沙箱），崩溃不会拖垮大楼，也不能随便动楼里的东西；但大楼给租客留了一部服务电话，想做什么就打电话让前台代办。这部电话就是 hostcall（宿主调用）。

还要注意：大楼里有很多前台窗口（Envoy 多 worker 线程），每个窗口都配一个一模一样的租客（每线程一个独立 Wasm VM）。所以插件不能指望"上一次请求存在内存里的东西这次还在"——你可能换了窗口、换了租客。这就是插件里不能存跨请求全局状态的原因。

技术实现

plugin.wasm 作为 Envoy 的 Http Filter 加载，Envoy 每个 worker 线程实例化一个 Wasm VM 执行它。demo 里 envoy 启动参数带 --concurrency 1（单线程），就是排除多 VM 副本的干扰。

插件的一切能力来自 proxy-wasm ABI 的 hostcall。key-auth 只用了 3 个，是"最瘦"的一类插件：

插件想干什么	hostcall	代码位置
读请求头（取 token）	`GetHttpRequestHeader`	main.go:263
注入消费者头	`AddHttpRequestHeader`	main.go:294
直接给客户端回拒绝响应	`SendHttpResponseWithDetail`	main.go:330

对照 ai-security-guard，它还需要 GetHttpRequestBody（读 body）、DispatchHttpCall（外呼安全服务）、ResumeHttpRequest（异步放行）、InjectEncodedDataToFilterChain（流式注入）等——插件要干的事越多，用到的 hostcall 越多。

跨请求状态的处理原则：要么不存，要么建在配置期。credential2Name（main.go:130）这种"配置不变它就不变"的表，在 parseGlobalConfig 时每个 VM 各建一份；而请求级状态（本次认出的 consumer 名）不落 VM 内存，而是注入 X-Mse-Consumer 请求头随请求往下游走。
ABI 版本注意：Go 编译的插件导出 proxy_abi_version_0_2_100 扩展 ABI，只有 Higress fork 的 Envoy 支持，官方 Envoy 加载即失败（demo 用 higress/gateway 镜像的原因；详解见《key-auth插件本地Docker部署与运行机制指南.md》§3.2）。

1.2 骨架：wrapper 框架与回调注册

通俗理解

一次请求在网关里要过几个"检查站"，插件在 init() 里登记了每个站点要干什么。wasm-go 的 wrapper 包还帮插件干了两件麻烦事：一是把分片到达的 body 拼完整再交给你（裸 SDK 里要自己拼）；二是根据请求命中的配置级别（全局/域名/路由）把对应配置递给你的回调。

技术实现

插件执行阶段与优先级由代码注解声明：key-auth 是 @Phase AUTHN @Priority 321（main.go:62-63）。多插件并存时这决定执行顺序——认证（AUTHN 阶段）天然排在业务类插件（默认阶段）前面，先过门禁再谈别的。
wrapper.SetCtx 注册回调（main.go:37-43，详见 §3）。key-auth 只挂两类：ParseOverrideConfigBy（配置解析）+ ProcessRequestHeadersBy（请求头处理），因为认证只看请求头就够了；ai-security-guard 要挂 5~6 类（还要读请求体、拦响应），复杂度差别就在这。
wrapper 的配置分层机制：顶层 JSON 给 parseGlobalConfig，_rules_ 数组里每条给 parseOverrideRuleConfig；请求期框架按请求命中的路由/域名，把对应的那份配置递给回调。这套机制的"实体"见 §2.3 对 envoy.yaml:42 的剖析。

1.3 异步模型：ActionPause / Resume，以及 key-auth 的"同步特权"

通俗理解

这是理解插件执行模型最关键的一点。Envoy 的每个线程是单线程事件循环：插件代码运行时，这个线程上其他请求都在排队。所以插件里绝不允许"发一个网络请求然后干等结果"——那会把整个线程卡死，全网关的请求都跟着遭殃。

需要外呼的插件（如 ai-security-guard）正确姿势是"过安检“模式：旅客（请求）到安检口，安检员说"你先到旁边等着”（ActionPause），安检仪扫完（安全服务返回回调），安检员看结果——没问题就喊"过来继续走"（ResumeHttpRequest），有问题就直接请出去（SendHttpResponse）。等待期间安检口照常处理其他旅客。

key-auth 没这个烦恼：它是"看一眼证件“的安检员——所有判定都是内存操作（查 map、比名单），微秒级出结果，从不外呼，所以永远同步返回。

技术实现

key-auth 的 onHttpRequestHeaders（main.go:239）只做：读头 → map 查询 → 要么 ActionContinue 放行，要么 SendHttpResponse 本地拒绝后 return ActionContinue（请求已被 hostcall 终止，返回值只是形式，见 §6）。
需要外呼的插件是另一套写法：body hook 返回 types.ActionPause，在 DispatchHttpCall 的回调里根据结果 ResumeHttpRequest() 放行或 SendHttpResponse() 拦截；同一时刻只许一次在途调用（单飞），避免结果乱序。
判断一个插件属于哪类的方法：看回调里有没有发起异步调用（HTTP / Redis 等）。有 → 必须 Pause/Resume；没有 → 像 key-auth 一样同步返回即可，代码简单一个数量级。

1.4 部署链路：plugin.wasm 怎么变成生效的插件

通俗理解

OCI 镜像是 wasm 的"快递盒”：plugin.wasm 只有几 MB，要送进 K8s 集群里每个网关 Pod，最省事的办法是借用现成的 Docker 镜像物流体系——装进盒子（Dockerfile COPY）、贴上单号（VERSION tag）、寄到仓库（docker push），网关填个快递单号（url: oci://...）就能收到并拆包加载。

McpBridge 是给服务"铺路"：默认 Higress 只把"路由用到的服务"下发成 Envoy cluster；路由之外的服务（比如 ai-security-guard 要外呼的安全服务）想用，就得用 McpBridge 额外注册。

配置生效讲"就近原则"：请求命中了具体路由/域名配置就用它，完全不沾边才用 defaultConfig。

技术实现

WasmPlugin.spec.url 的三种形态：
- oci://...：镜像分发，生产环境用（keyauth.yaml 示例里的 oci://docker.io/dongjiang1989/keyauth:1.0.0）；
- http://plugin-server:8080/...：standalone 部署内置插件服务，官方插件（如 key-auth 2.0.0）开箱即用；
- file:///...：本地文件挂载，demo 用的就是这种（plugin.wasm 直接挂进 envoy 容器），改代码重编后重启容器即生效，最适合调试。
K8s 链路：WasmPlugin CRD → Higress 控制面翻译成 Envoy 的 wasm filter 配置下发到 gateway。demo 里手写的 envoy.yaml:26-42 就是这份"翻译结果"的样貌（§2.2 逐行拆解）。
McpBridge 的两个用途：① 给路由提供上游（本例把 httpbin.org 注册成 httpbin.dns 供 Ingress 引用）；② 给插件外呼铺路建 cluster（key-auth 无外呼用不到；ai-security-guard 靠它获得 outbound|443||safecheck.dns 这个 cluster）。
配置匹配的就近原则落到插件内部，就是 _rules_ / _match_route_ 的命中逻辑（§2.3、§4.3）。

2. envoy.yaml：插件是怎么"挂"进请求链路的

K8s 里我们写 WasmPlugin CRD，控制面把它翻译成 Envoy 配置；demo 里没有控制面，这段 envoy.yaml 就是翻译后的最终产物，所以看它最能理解插件的真实形态。

2.1 路由层（envoy.yaml:14-25）

1
2
3
4
5
6
7
8


route_config:
 virtual_hosts:
 - name: httpbin
 domains: [httpbin.example.com]  # Host 头必须匹配
 routes:
 - name: keyauth-route  # ★ 路由名，插件配置里引用它
 match: { prefix: / }
 route: { cluster: httpbin }

两个关键点：

domains 决定哪些 Host 走这条路由——test.sh 场景⑤不带 Host 直接访问，匹配不到 virtual host，Envoy 直接回 404，请求根本没到插件；
路由名 keyauth-route 是给插件配置引用的"身份证号"，马上会看到。

2.2 wasm filter 层（envoy.yaml:26-42）——全篇最重要的一段

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


http_filters:
 - name: envoy.filters.http.wasm
 typed_config:
 "@type": .../filters.http.wasm.v3.Wasm
 config:
 name: key-auth  # 对应 wrapper.SetCtx("key-auth", ...)
 vm_config:
 runtime: envoy.wasm.runtime.v8  # V8 沙箱里跑 wasm
 code:
 local: { filename: /etc/envoy/plugin.wasm }
 configuration:
 "@type": type.googleapis.com/google.protobuf.StringValue
 value: >-
 {"consumers":[...],"keys":["x-api-key","apikey"],"in_header":true,
 "global_auth":false,
 "_rules_":[{"_match_route_":["keyauth-route"],"allow":["consumer1"]}]}

逐行拆解：

http_filters 的顺序就是请求的处理顺序：wasm 排在 router 前面，所以插件先执行，拦下的请求根本不会转发给 httpbin。
configuration.value 是一段 JSON 字符串——这就是插件 parseGlobalConfig/parseOverrideRuleConfig 收到的原始 gjson.Result。
注意它的结构：全局字段（consumers/keys/in_header/global_auth）平铺在顶层，路由级规则放在 _rules_ 数组里，每条用 _match_route_ 指定生效的路由名。

2.3 大揭秘：`_rules_` 就是 WasmPlugin 的 matchRules

对照 K8s 版配置（keyauth.yaml），两边其实一模一样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# K8s 里你写的 # Envoy 实际收到的（envoy.yaml:42）
spec:
 defaultConfig: ──合并──► 顶层字段：consumers/keys/in_header/global_auth
 consumers: [...]
 global_auth: false
 ...
 matchRules: ──合并──► "_rules_": [{
 - ingress: → "_match_route_": ["keyauth-route"],
 - ingress-keyauth-httpbin "allow": ["consumer1"] }]
 config:
 allow: [consumer1]

Higress 控制面干的事就是把 defaultConfig + matchRules 编译成这样一段 JSON（K8s 里 _match_route_ 的值是 ingress 名，demo 里是手写的 envoy 路由名）。wasm-go wrapper 收到后：顶层 JSON 给 parseGlobalConfig，_rules_ 里每条给 parseOverrideRuleConfig。

“两级配置机制"的抽象说法，在 envoy.yaml:42 这一行里能看到实体。

2.4 docker-compose 里的两个细节

envoy 镜像是 higress/gateway（compose 文件第 11 行注释）：Go 编译的插件用了 proxy_abi_version_0_2_100 这个 ABI 扩展，只有 Higress fork 的 Envoy 支持，官方 Envoy 加载会失败（见 §1.1）。
--concurrency 1：单 worker 线程。回忆 §1.1"每个 worker 线程一个独立 Wasm VM”——demo 设成 1，保证你看到的日志和行为都来自同一个 VM，排除多副本干扰。

3. 代码骨架（main.go:35-43）

1
2
3
4
5
6
7
8
9


func main() {}

func init() {
	wrapper.SetCtx(
		"key-auth", // ← 对应 envoy.yaml 的 name: key-auth
		wrapper.ParseOverrideConfigBy(parseGlobalConfig, parseOverrideRuleConfig),
		wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
	)
}

Wasm 插件没有进程入口，main() 是编译占位；真正的入口是 init()——插件加载时向 wrapper 框架挂号三件事：我的名字（要和 envoy.yaml / WasmPlugin 里的 name 对上）、配置来了调谁、请求头到了调谁。之后所有代码都是被动回调。

只挂两个 hook，因为认证只看请求头就够了。对比 ai-security-guard 挂 6 个（要读 body、拦响应），复杂度差别就在这（见 §1.2）。

4. 配置解析：把 envoy.yaml:42 那段 JSON 变成内存结构

4.1 配置结构体（main.go:88-131）

1
2
3
4
5
6
7
8
9


type KeyAuthConfig struct {
	globalAuth *bool `yaml:"global_auth,omitempty"` // 指针！三态的关键
	Keys []string `yaml:"keys"`
	InQuery bool `yaml:"in_query,omitempty"`
	InHeader bool `yaml:"in_header,omitempty"`
	consumers []Consumer
	allow []string
	credential2Name map[string]string `yaml:"-"` // 不从配置读，解析时自建
}

globalAuth 用 *bool 指针（main.go:94）：bool 零值 false 分不清"配了 false"和"根本没配"。指针区分三态：nil=未设置、&true、&false——这是后面裁决表的基础。
credential2Name 是运行时索引（main.go:130）：配置里 consumers 是列表，逐请求遍历是 O(n)；解析时建成 凭证→名字 的 map，运行时 O(1) 查表。配置解析一次、请求千千万万次——开销挪到解析期，是插件开发通用思路（§1.1 的状态原则）。

4.2 `parseGlobalConfig`：校验 + 建索引（main.go:133-204）

收到顶层 JSON（demo 里就是 consumers/keys/in_header/global_auth 那部分），先做一串防御式校验，任一不满足整条配置被拒：

keys 必须非空（:148-154）——没定义从哪取 key，认证无从谈起；
in_query/in_header 至少配一个（:163-165）；
consumers 非空，name/credential 都不能空；
凭证不允许重复（:192-194）——两个 consumer 同 key 就分不清"你是谁"，直接拒配。

通过后建索引。用 demo 的配置，解析完内存里是：

1
2
3
4


credential2Name = {
 "2bda943c-ba2b-11ec-ba07-00163e1250b5": "consumer1",
 "c8c8e9ca-558e-4a2d-bb62-e700dcc40e35": "consumer2",
}

demo 视角：改 envoy.yaml:42 里的 JSON（比如删掉 consumers），重启 compose，就能在 envoy 日志里看到对应的校验报错——配置错误在插件加载期就暴露，不会带病运行。

4.3 `parseOverrideRuleConfig`：叠加路由级 allow（main.go:206-225）

对 _rules_ 里每条规则调用一次：

1
2
3


*config = global // 先把全局配置整个拷过来（consumers/keys 自动继承）
// ... 解析 allow 列表
ruleSet = true // 标记：至少有一条路由配了插件

用 demo 配置：命中 keyauth-route 的请求，拿到的最终 config = 全局 consumers/keys + allow: ["consumer1"]；不命中任何 _rules_ 的请求，拿到的就是纯全局配置（allow 为空）。

ruleSet 是包级全局变量，记录"至少有一条路由配了插件"，裁决时用来猜管理员意图（见 §5 第一步）。

5. 核心裁决：`onHttpRequestHeaders`（main.go:239-327）

请求头到达时框架调它。开头算四个布尔值：

1
2
3
4


noAllow = len(config.allow) == 0 // 当前请求没命中任何 _rules_
globalAuthNoSet = config.globalAuth == nil
globalAuthSetTrue = !globalAuthNoSet && *config.globalAuth
globalAuthSetFalse = !globalAuthNoSet && !*config.globalAuth

第一步：要不要认证？（:249-254）

1
2
3
4
5


if globalAuthSetFalse || (globalAuthNoSet && ruleSet) {
	if noAllow {
		return types.ActionContinue // 不归我管，直接放行
	}
}

demo 配置 global_auth: false：请求没命中 keyauth-route（不会有，因为只有一个 virtual host；K8s 多路由场景才有意义）→ 直接放行，连 token 都不取。

ruleSet 的作用：global_auth 没设置时猜意图——任何路由都没配过插件（ruleSet==false）说明想全局认证；有路由配了，说明按路由精细控制，没配的路由放行。

第二步：取 token（:259-278）

1
2
3
4
5
6
7
8


if config.InHeader {
	for _, key := range config.Keys { // keys: [x-api-key, apikey]
		value, err := proxywasm.GetHttpRequestHeader(key)
		if err == nil && value != "" {
			tokens = append(tokens, value)
		}
	}
} else if config.InQuery { /* 从 :path 的 query 参数取 */ }

demo 配置 in_header: true：先试 x-api-key 头，再试 apikey 头。两个头都带就都收进 tokens——下一步会当成攻击拒绝（test.sh 没演示这个，可以自己加一条 curl 验证）。

坑：else if 意味着 in_header/in_query 同开时 query 永不生效（官方原版行为）。

第三步：数量检查（:281-285）

1
2


if len(tokens) > 1 { return deniedMultiKeyAuthData() } // 401 multi_key
if len(tokens) <= 0 { return deniedNoKeyAuthData() } // 401 no_key

带多个 key 为什么拒绝？防凭证混淆——一合法一非法同时带，后端处理顺序不同可能放行非法请求。→ test.sh 场景①（不带 Key）命中的就是这步的 401。

第四步：认证——查表认出"你是谁"（:288-294）

1
2
3
4
5


name, ok := config.credential2Name[tokens[0]]
if !ok {
	return deniedUnauthorizedConsumer() // 403：凭证不在名单
}
proxywasm.AddHttpRequestHeader("X-Mse-Consumer", name)

一次 map 查找完成认证。查到就把 consumer 名写进请求头往下游传——X-Mse-Consumer 是 Higress 消费者体系的通用语言，限流、ai-security-guard 的消费者级配置都读它。

→ test.sh 场景④（假 Key wrong-key）命中的就是这步的 403。 想亲眼看到注入效果：场景②通过的请求，httpbin 的 /get 响应体会把收到的请求头原样回显，里面就有 X-Mse-Consumer: consumer1。

第五步：授权——“你能进这扇门吗”（:299-326）

global_auth	路由无 allow	路由有 allow
true	凭证合法即放行	合法且在 allow 里
false	直接放行（第一步已走掉）	合法且在 allow 里
未设置	`ruleSet==false` → 按 true；否则按 false	同上

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


if (globalAuthSetTrue && noAllow) || (globalAuthNoSet && !ruleSet) {
	return authenticated(name) // 全局模式，凭证合法就行
}
if globalAuthSetTrue && !noAllow { ... } // 全局模式 + allow 校验
if globalAuthSetFalse || (globalAuthNoSet && ruleSet) {
	if !noAllow {
		if !contains(config.allow, name) { return deniedUnauthorizedConsumer() }
		return authenticated(name)
	}
}

demo 落在第三分支：→ test.sh 场景③（consumer2 的 Key，凭证合法但不在 allow: [consumer1]）命中这里的 403；场景②（consumer1）走到 authenticated 放行。

6. 拒绝响应怎么发（main.go:329-345）

1
2
3
4
5
6
7
8


_ = proxywasm.SendHttpResponseWithDetail(
	http.StatusUnauthorized, // 401（或 403）
	"key-auth.no_key", // 内部 detail 码，进日志
	WWWAuthenticateHeader(protectionSpace), // WWW-Authenticate: Key realm=MSE Gateway
	[]byte("Request denied by Key Auth check..."),
	-1,
)
return types.ActionContinue

WWW-Authenticate 是 RFC 7235 的要求，告诉客户端"这里用 Key 认证"。test.sh 的 ①③④ 输出里都能看到这行响应头，可以对照确认命中了哪个拒绝函数（body 文案各不相同）。

容易困惑的点：发了拒绝响应为什么还 return ActionContinue？SendHttpResponse 是"立即响应并终止该请求"的 hostcall，请求已结束，返回值只是形式。对比 ai-security-guard 外呼时的 ActionPause（等异步回调，见 §1.3），语义完全不同。

7. 剧本对照表：test.sh ⑤ 个场景 → 代码分支

test.sh 场景	请求	命中代码	期望
① 不带 Key	无认证头	`len(tokens)<=0` → `deniedNoKeyAuthData`（:283）	401 no_key
② consumer1 的 Key	`x-api-key: 2bda...`	查表得 consumer1（:288）→ allow 命中（:317-322）	200，响应回显含 `X-Mse-Consumer: consumer1`
③ consumer2 的 Key	`apikey: c8c8...`（第二个 key 名）	认证过、授权失败（:317-319）	403 unauthorized
④ 假 Key	`x-api-key: wrong-key`	查表未命中（:289-291）	403 unauthorized
⑤ 不带 Host	直接访问 IP:10000	到不了插件：virtual host `domains` 不匹配（envoy.yaml:18-19），Envoy 路由层 404	404

场景⑤是"插件不是万能的"的最好示例：它只在命中路由后执行，路由都没匹配上的请求根本轮不到它。

想动手验证：cd key-auth-docker-demo && docker compose up -d && ./test.sh。改 envoy.yaml:42 的 JSON 后 docker compose restart envoy 即生效，不用重编 wasm——配置和代码是两条独立的发布链路。

8. 设计脉络总结

1
2
3
4


加载期 init() → SetCtx 挂号（name 对应 envoy.yaml 的 filter 名）
配置期 envoy.yaml 的 configuration JSON → parseGlobalConfig 校验+建索引
 → _rules_ 每条 → parseOverrideRuleConfig 叠加 allow
请求期 取 token（keys 逐个试）→ 数量检查 → 查 map 认证 → 注入 X-Mse-Consumer → allow 授权 → 放行/401/403

一句话：配置期做好校验和索引（慢一次），请求期只做取 token、查 map、比名单（快万次）；三态 global_auth 是唯一绕的地方，记住"nil = 未设置，靠 ruleSet 猜意图"。

9. 已知小问题（移植自官方，未改动）

in_header/in_query 是 else if 关系，同开时 query 不生效（main.go:268）；
url.Parse 错误被忽略（main.go:270）；
凭证以 %q 打进日志（main.go:290），有轻微泄露风险；
落后于上游：官方已支持 consumer 多凭证 credentials 字段，此版本只有单 credential（main.go:57）；
keyauth.yaml 示例镜像指向个人仓库 docker.io/dongjiang1989/keyauth:1.0.0，实际部署需替换。

附：测试怎么验证这些（main_test.go，580 行）

TestParseGlobalConfig（:240）：喂残缺 JSON，验证校验报错；
TestParseRuleConfig（:361）：验证 allow 解析与 *config = global 继承；
TestOnHTTPRequestHeaders（:388）：用 wasm-go pkg/test 的 mock host 模拟请求头，断言 action 与发出的响应状态码——§7 的剧本①②③④都有对应断言。

单测（mock host，进程内跑）和 demo（真实 Envoy，容器里跑）是两种互补的验证层：前者快、覆盖分支；后者验证真实 ABI、真实配置链路和实际 HTTP 行为。

模型安全检测 04：DAG 编排引擎深入（Function/Router/三层超时）

Mon, 14 Sep 2026 10:03:15 +0800

状态：✅ 已完成 前置阅读：02-Mac本地部署实操（部署与踩坑）、03-技术架构与业务模块分析（模块全景）日期：2026-09-14 素材来源：safety-basic / safety-api 源码逐行核实；所有 path:line 坐标均经 Read 验证 读者定位：想写自定义策略、自定义原子能力，或搞懂"groovy 脚本里那个 ctx 到底是什么"的读者

〇、先建立全局认识：两条链路看 DAG

DAG 引擎不是孤立存在的，它串在两条链路的交汇点上。

配置怎么流转（改策略 → 生效）：

1
2
3
4
5
6
7


运维/脚本 → safety-admin(8006) 版本化状态机(active→newVersion→update→upgrade)
 → MySQL(execute_dag_conf 等表，conf 存 JSON)
 → api 侧 DynamicConfigService 每 60s HTTP 轮询 admin 的 /config/defense/api/conf
 （按每个业务的 lastChangeTimestamp 判断变更，DynamicConfigService.java:142-145）
 → 有变更：全量替换 volatile 配置 Map + 静态 functionConfMap
 → 回调监听器 FunctionChainBuilderImpl.loadConf() 重建所有业务的 DAG
 → rootMap 整体换根（FunctionChainBuilderImpl.java:64）

请求怎么流转（业务方 → 响应）：

1
2
3
4
5
6
7
8
9


POST /llmsec/api/defense/v2/{accessKey} (DefenseApiV2Controller.java:38)
 → checkParams 参数校验(:46) → rateLimited 限流(:59)
 → verify HMAC-SHA1 验签(:75，accessKey 以 test 开头跳过)
 → preProcess 预处理(:78) → 按 responseMode 分派(sync/free_taxi/http/mq)
 → FunctionExecutorImpl.invoke → buildContext 建 SessionContext(取历史/截断文本)
 → 查结果缓存(Redis, user+单条才缓存, :275-287)
 → doExecute() 从 root 节点 while 逐跳执行(:289)
 → 逐跳中 Function 远程调 skill 服务(keywords/bert/knowledge)
 → buildResp 组装响应 + saveToHistory 写会话历史

坐标勘误（对前期分析）：safety-api 下引擎实现类的真实包名是 com.jd.security.llmsec.service.execute（执行器、构建器、注册表）与 service.execute.functions（各 Function 实现），不是提纲里写的 engine/。下文一律用真实路径。

一、引擎三要素：Function / Router / Node

1.1 三个抽象一句话

1
2
3


Function.run(SessionContext) → RiskCheckResult // 干活：调模型/查词库/问知识库
Router.next(SessionContext) → Node 或 null // 决策：下一跳去哪，null=链路结束
Node = NodeConfig + Function + Router (+reduceScript) // 节点 = 配置+能力+路由(+节点级归约脚本)

Function 接口：safety/safety-basic/.../core/engine/Function.java:14，只有 conf()/type()/name()/run() 四个方法。
Router 接口：core/engine/Router.java:17，自带静态注册表 ROUTER_MAP（:23，7 种实现，详见第四节）。
Node 类：core/engine/Node.java:24，@Data 四个字段：conf / function / reduceEngine / router（:25-28）。

1.2 AbstractFunction：模板方法，结果自动归档

所有 Function 实现都继承 AbstractFunction（core/engine/AbstractFunction.java:20）。构造时校验 type/name/timeoutMilliseconds 非空（:25-28）并调 doInit(conf) 让子类初始化（:30）。核心是 run() 模板方法（:41-59）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


public RiskCheckResult run(SessionContext context) throws ExceptionWithCode {
 long start = System.currentTimeMillis();
 RiskCheckResult result = doRun(context); // ① 子类干活
 if (Objects.equals(this.type(), RiskCheckType.parallel)) {
 ParallelCheckResult tmp = new ParallelCheckResult(); // ② parallel 只归档名字+耗时
 tmp.setSrcName(name()); // （结果由归约策略另行产出）
 tmp.setCost(System.currentTimeMillis() - start);
 context.appendResult(tmp);
 } else {
 if (result != null) { // ③ 普通 function 结果归档进
 result.setSrcName(name()); // ctx.middleResults
 context.appendResult(result); // 供后续 groovy 脚本翻阅
 result.setCost(System.currentTimeMillis() - start);
 }
 }
 return result; // ④ 返回值进 ctx.curResult
}

批注：这里把"每个能力的检测结果"自动存进 ctx.middleResults（按 RiskCheckType 分桶），并打上 srcName（function 名）和 cost。groovy router 里 ctx.middleResults[RiskCheckType.single_label_pred] 能翻到历史所有 BERT 结果，靠的就是这两行。注意 parallel 类型归档的是空壳（只有 srcName+cost），真正的子结果在归约后才产生。

1.3 Node.run()：还有一层节点级 reduceScript

Node.run()（Node.java:43-61）不只是调 Function：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


public RiskCheckResult run(SessionContext context) throws ExceptionWithCode {
 RiskCheckResult curResult = function.run(context); // ① 先跑 Function
 if (reduceEngine == null) {
 return curResult; // ② 没配 reduceScript 直接返回
 }
 synchronized (reduceEngine) { // ③ 引擎非线程安全，串行 eval
 Bindings bindings = reduceEngine.createBindings();
 bindings.put("ctx", context);
 bindings.put("curNode", this);
 bindings.put("curResult", curResult);
 try {
 return (RiskCheckResult) reduceEngine.eval(conf.getReduceScript(), bindings);
 } catch (ScriptException e) {
 return curResult; // ④ 脚本异常→忽略脚本策略，用原结果
 }
 }
}

reduceScript 在 Node 构造时经 GroovyHelper.engin() 预热编译（Node.java:34-41）。bindings 里有 ctx/curNode/curResult 三个变量，可以在不离开节点的情况下改写结果。脚本抛异常不阻断链路（④），这点和 GroovyRouter 的"异常即结束"（见 4.2）形成对照。

1.4 名为 DAG、实为链式逐跳

全框架没有 Edge 实体类。边 = Router 返回的 nodeId 字符串，经 nodeMap.get() 换成下一个 Node。执行主循环在 FunctionExecutorImpl.doExecute()（safety-api/.../service/execute/FunctionExecutorImpl.java:289）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


Node curNode = root;
while (curNode != null) {
 if (context.timeout()) { // ① 每跳前查整体超时
 throw new ExceptionWithCode(exec_timeout...);
 }
 context.setCurResult(null); // ② 清空上一跳结果
 try {
 tmpResult = curNode.run(context); // ③ 跑节点
 context.setCurResult(tmpResult);
 context.setCurFunctionName(curNode.getFunction().name());
 } catch (Exception e) {
 if (!curNode.getConf().isIgnoreError()) { throw ...; } // ④ ignoreError=false 才抛出
 else { context.setCurResult(null); ... } // ⑤ 默认忽略，继续走
 }
 curNode = curNode.next(context); // ⑥ Router 决定下一跳
 if (curNode == null) { break; } // ⑦ null=链路结束
}

（原文 :296-333，略有删减）逐行批注：

① 整体超时按跳检查，不是按函数中断——一个已经发起 HTTP 的 function 不会被这层超时打断，只是跑完后结果被丢弃（链路直接抛异常）。
② 每跳开始清空 curResult——所以 groovy 脚本里读 ctx.curResult 拿到的永远是上一跳的结果。
④⑤ ignoreError 默认 true（NodeConfig.java:17），单个能力挂了链路继续，这就是"演示策略所有节点 ignoreError: true"的含义。
⑥⑦ Node.next()（Node.java:63-69）：router==null 或 router 返回 null 都结束；router 返回的 nodeId 在 nodeMap 里查不到也是静默结束（nodeMap.get() 返回 null），写错 nodeId 不会报错，只会提前收尾——新手高发坑。

1
2
3
4
5
6


 ┌─────────────┐ router 返回 'node_b' ┌─────────────┐
root → │ Node A │ ─────────────────────► │ Node B │ ──► router 返回 null
 │ function+ │ │ function+ │ 链路结束,
 │ router │ ◄── 边只是字符串引用 │ router │ 取 ctx.curResult 响应
 └─────────────┘ └─────────────┘
 并发只存在于 parallel 节点内部(第六节), 图上没有分支汇合调度

二、DAG 的构建：配置怎么变成内存里的链

构建入口 FunctionChainBuilderImpl.build()（safety-api/.../service/execute/FunctionChainBuilderImpl.java:73），两遍扫描：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 第一遍(:76-86): 所有 NodeConfig → new Node(conf), 按 nodeId 进 nodeMap;
// nodeId 重复直接抛异常; rootId 命中的记为 root
// 第二遍(:89-96): 对每个节点——
for (Node node : nodes) {
 FunctionConfig funcConf = node.getConf().getFunctionConf();
 funcConf = FunctionUtil.doMerge(funcConf); // ① 合并 ref 模板
 node.getConf().setFunctionConf(funcConf);
 node.setFunction(FunctionUtil.buildFunction(funcConf)); // ② 反射建 Function
 node.setRouter(buildRouter(node.getConf().getRouterConf(), nodeMap)); // ③ 建 Router
}

① ref 深合并（FunctionUtil.doMerge()，FunctionUtil.java:39）：节点只写 ref: keyword 时，从静态注册表 ConfigService.functionConfMap（:44，由 DynamicConfigService.loadFunctions() 在轮询时全量刷新，DynamicConfigService.java:153-173）取出 admin 里注册的原子能力模板，type/target/name/desc/timeout 整份拷贝（copyProperties, :108-115），conf 部分做 map 递归深合并（mergeProperties, :58-94）——节点自写的 key 覆盖模板，模板独有的 key 保留，value 是 Map 时递归，是 List/标量时整体替换。这就是"DAG 里 conf.ignoreRiskCode 能局部覆盖原子能力注册参数"的机制。
② 反射建 Function：FunctionUtil.buildFunction()（:26-36）查 FunctionRegistry.FUNC_MAP 拿实现类，调第一个构造器。校验 timeoutMilliseconds 必须 >0（:33）。
③ 反射建 Router（:101-106）：查 Router.ROUTER_MAP，构造器统一签名 (RouterConfig, nodeMap)——nodeMap 此时已含全部节点，所以 Router 可以引用排在自己后面的节点（前向引用合法）。

构建产物存 rootMap（:46，业务名 → root Node）。触发时机两个：@PostConstruct 首载（:47-49）+ 注册为配置变更监听器（:50），轮询发现变更后由 DynamicConfigService 提交线程池回调（:106-110）。重建是全量的：所有业务全部重新 doMerge、重新 new OkHttpClient、重新预热 groovy。

AB 按 dagVersion 构建（:109-125）：请求带 ab.dagVersion>0 时不查 rootMap，而是实时调 admin 按版本取配置、现场 build() 一份新 DAG——每次请求都重建（无缓存），只适用于灰度验证，别拿去压测。

三、Function 类型体系

3.1 注册表：9 种

FunctionRegistry.FUNC_MAP（safety-api/.../service/execute/FunctionRegistry.java:20）：

type	实现类	干什么
dummy	DummyFunction	空操作，直接 `MixedCheck.noRisk()`（DummyFunction.java:27-28），做起始节点
keyword	KeywordFunction	HTTP 调 safety-keywords 敏感词服务
single_label_pred	SingleLabelPredFunction	HTTP 调 bert/fasttext 单标签分类
multi_label_pred	MultiLablePreFunction（原文拼写如此）	多标签分类
kb_search	KbSearchFunction	知识库向量检索
rag_answer	RagAnswerFunction	RAG 红线代答
multi_turn_detect	MultiTurnDetectFunction	多轮对话检测（LLM）
parallel	ParallelFunction	节点内并行（第六节）
async	AsyncFunction	异步包一层（见 3.3）

3.2 HTTP 远程 function 的统一套路

以 KeywordFunction 为例（functions/KeywordFunction.java:46-66）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


long timeout = 200; // 默认值各 function 不同
if (this.conf().getTimeoutMilliseconds() != null) {
 timeout = this.conf().getTimeoutMilliseconds(); // ← 注册原子能力时的超时
}
Object resource = FunctionResourcePool.getFunc(type(), thisConf.getUrl());
if (resource != null) {
 this.client = (OkHttpClient) resource; // ① 同 URL 复用已有 client
} else {
 OkHttpClient temp = new OkHttpClient.Builder()
 .callTimeout(timeout, TimeUnit.MILLISECONDS).build(); // ② 超时烙进 client
 Object uniqResource = FunctionResourcePool.addFuncIfAbsent(type(), url, temp);
 this.client = (OkHttpClient) uniqResource;
}

三个要点：

连接池按 type$url 全局共享（FunctionResourcePool.java:15-28）——同一个 skill 地址只建一个 OkHttpClient，Keep-Alive 头在 doRun 里显式带（:80-82）。
超时"首建者生效"：client 是共享的，后来者的 timeoutMilliseconds 不会重建 client。改原子能力超时后必须重建 DAG（配置变更触发）甚至重启 api 才彻底生效——这正是 02 篇坑 5 的代码级根因之一。
warmup：SingleLabelPredFunction 在"自己亲手建了 client"时挂一个 ScheduleWarmup.appendTask，启动后发一条假请求预热连接和模型（SingleLabelPredFunction.java:76-92）；kb_search/rag_answer/multi_turn_detect 同理（各自 :85 附近的 warmup 日志）。

3.3 async：把任意 function 包成异步

AsyncFunction（functions/AsyncFunction.java:36）doInit 时把 conf 解析成内层 FunctionConfig 再 buildFunction 出真实能力（:45-49）。doRun（:63-103）：往独立线程池（20 线程/队列 50/DiscardOldestPolicy，:55-60）提交任务——复制一份 ctx（重置 middleResults 和计时），异步跑真实 function，结果包成 AsyncCheckResult 经 appendResponseData 写结果队列；同步侧立即返回当前 curResult 原样放行。队列满时丢最老任务，典型的"检测可以丢、业务不能堵"。

四、Router 详解（7 种）

Router.ROUTER_MAP（Router.java:23-31）总览：

type	实现	语义	关键代码
groovy	GroovyRouter	脚本返回 nodeId/null	GroovyRouter.java:39-60
stupid_end	StupidEnd	无条件结束	StupidEnd.java:24-26
simple_next	SimpleNextRouter	固定去配置的 nodeId（构建期校验节点存在，:41-47）	SimpleNextRouter.java:26-28
keyword	KeywordRouter	命中黑(1)/白(2)则结束，否则走下一节点；当前节点失败(curResult==null)也继续	KeywordRouter.java:28-44
risk_end	RiskEnd	curResult.hasRisk() 则结束，否则继续	RiskEnd.java:22-30
user_end	UserEndRouter	fromUser() 则结束	UserEndRouter.java:22-24
robot_end	RobotEndRouter	fromRobot() 则结束	RobotEndRouter.java:22-24

后四种都继承 SimpleNextRouter，“结束”= 返回 null，“继续”= super.next() 去配置好的固定节点。配置里要给它们配 conf.nodeId。

4.1 groovy router：策略逻辑的主战场

GroovyRouter（core/engine/routers/GroovyRouter.java:27）：

构建期：doInit（:76-82）把 conf 解析出 script，调 GroovyHelper.engin(script) 建引擎并预热——GroovyHelper.doWarmup()（core/util/GroovyHelper.java:24-31）拿空 bindings 先 eval 一遍，触发 Groovy 编译，异常吞掉。所以第一个真实请求不吃编译冷启动。
运行期（next, :39-60）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


synchronized (engine) { // ① ScriptEngine 非线程安全, 全局串行
 Bindings bindings = engine.createBindings();
 bindings.put("ctx", context); // ② bindings 只有 ctx 一个变量
 eval = engine.eval(conf.getScript(), bindings);
}
if (eval == null) { return null; } // ③ 返回 null → 链路结束
if (!(eval instanceof String)) { // ④ 返回非字符串 → 抛 inner_error
 throw new ExceptionWithCode(..., "groovy route返回非字符串");
}
return nodeMap.get((String) eval); // ⑤ 字符串当 nodeId 查表; 查不到静默结束

4.2 groovy 的两个并发/容错事实（重要）

全局 synchronized 串行 eval（①）。safety-api 内所有请求的 groovy 路由/归约脚本都排队执行——脚本里写复杂逻辑（循环翻 middleResults、字符串拼接）会直接拉低整机吞吐。策略脚本务必保持"读几个字段、比几个数、return"的体量。
异常即结束链路：ScriptException 被 catch 后 log 并 return null（:56-59）——脚本报错 = 链路当场终止，且 ctx.curResult 保持上一跳的结果原样返回给业务方。脚本报错不报警、不抛 500，线上排查靠日志关键字 执行groovy脚本失败。

源码勘误：RobotEndRouter.type() 返回的是 RouterType.user_end（RobotEndRouter.java:28），应为 robot_end，是复制粘贴笔误。功能不受影响（type() 仅用于声明），但按 type 反查实现时会拿错类。

五、SessionContext（ctx）实战手册

5.1 真实字段清单（SessionContext.java:21-34）

字段	类型	说明
businessConf	BusinessConf	业务配置，内含 userCheckConf/robotCheckConf（BusinessConf.java:19-20）
histories	List<History>	会话历史（Redis 取回，multi_turn_detect 的上下文来源）
checkContent	String	待检测文本，超长已截断（见 5.2）
curReq	List<DefenseApiRequest>	当前请求列表；`ctx.curReq[0].fromRobot()` 分流必用
lastUserReq	DefenseApiRequest	预留（相关代码已注释，FunctionExecutorImpl.java:492-497）
curResult	RiskCheckResult	上一跳的结果（每跳开始被清空）
curFunctionName	String	上一跳的 function 名
middleResults	Map<RiskCheckType, List<RiskCheckResult>>	所有已归档中间结果
executeStartTime / executeEndTime / executeCost / recvExecuteCost / endReason	计时与收尾标记	timeout() 的依据

两个方法：timeout()（:36-39）按 fromRobot 选 robotCheckConf/userCheckConf.timeoutMilliseconds（CheckConf 默认 1000ms，CheckConf.java:14）与 executeStartTime 比；appendResult()（:41-48）synchronized 往 middleResults 分桶追加。

5.2 checkContent 截断：坐标更正

提纲称截断在 SessionContext——实际在 FunctionExecutorImpl.buildContext()：MAX_CHECK_LEN = 2048（:398），超长时取头 1024 + _c_ + 尾 1024（:428-431）。头尾保留、中间掐断，兼顾"开头攻击"与"结尾诱导"两类注入位置。

5.3 常用写法（照抄即可）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// ① 分流：用户输入 vs 机器人输出(演示策略 start 节点原文)
def from_robot = ctx.curReq[0].fromRobot()
return from_robot ? 'from_robot_test1' : 'from_user_test1'

// ② 终结链路并给出最终结论:改写 ctx.curResult 后 return null
ctx.curResult = kw // 或 MixedCheck.noRisk() (需 import)
return null

// ③ 翻历史中间结果(按类型分桶 + srcName 区分具体 function)
import com.jd.security.llmsec.core.check.RiskCheckType
def preds = ctx.middleResults[RiskCheckType.single_label_pred]
def bert = preds?.find { it.srcName?.contains('bert_20250916') }

// ④ parallel 节点后读各子结果(归约未覆盖 curResult 的场景)
def retMap = ctx.curResult.resultMap

六、parallel 并行节点：唯一的并行点

ParallelFunction（safety-api/.../service/execute/functions/ParallelFunction.java:41）——DAG 图上没有并行分支，全部并行都发生在这一个节点内部。

6.1 线程池

1
2
3
4


pool = new ThreadPoolExecutor(200, 200, 5, TimeUnit.MINUTES,
 new LinkedBlockingQueue<>(1), // 队列只有 1!
 r -> { /* 线程名 function-parallel-N */ },
 new ThreadPoolExecutor.CallerRunsPolicy()); // 满了让调用线程自己跑

（:87-92）队列长度 1 + CallerRunsPolicy 是刻意的背压设计：200 个线程全忙时，第 202 个任务由提交它的业务请求线程自己同步执行——等于自动降并发，宁可慢也不堆积。

6.2 doRun：提交 → 逐级超时收取

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


for (Function func : functions) {
 if (func.conf().getTarget() == null ||
 Objects.equals(func.conf().getTarget(), ...getFromRole())) { // ① 按角色过滤子能力
 futures.add(pool.submit(() -> func.run(context))); // ② 全部先提交
 }
}
long remainCost = this.conf().getTimeoutMilliseconds(); // ③ 节点级总预算
for (int i = 0; i < futures.size(); i++) {
 long curTimeout = tempFuncs.get(i).conf().getTimeoutMilliseconds(); // ④ 每个子的超时
 if (remainCost < 0) { curTimeout = 1; } // ⑤ 预算已耗尽→1ms 意思一下
 long start = System.currentTimeMillis();
 try {
 resultMap.put(tempFunc.name(), f.get(curTimeout, MILLISECONDS)); // ⑥ 逐个收
 } catch (... TimeoutException e) { /* 该子项结果丢弃, 记监控 */ }
 remainCost -= (System.currentTimeMillis() - start); // ⑦ 预算递减
}

（:101-137，有删减）注意 ④：实际等待时长取的是子 function 自己的 timeoutMilliseconds，remainCost 只在"已超总预算"时把后续收取压成 1ms（⑤）。这就是 02 篇坑 4"两层超时都要改"的第①层实现位置。子项超时/异常只是结果不进 resultMap，不影响其他子项（:132-135）。

6.3 归约策略（ParallelConf.ReduceType）

reduceType	行为	代码
no_reduce（默认）	直接返回 ParallelCheckResult（含完整 resultMap），交给 router 脚本自己拆	:143-144, :175
first_risk	取 resultMap 里第一个 hasRisk() 的结果；都没有 → noRisk	:145-151
groovy_script	跑归约脚本，bindings = `ctx/conf/retMap`，脚本返回 RiskCheckResult；返回 null 视为 noRisk；脚本异常抛 inner_error	:152-171

groovy_script 的引擎同样是构建期预热（doInit :60-66）、运行期 synchronized(engine) eval（:155）。脚本位置在 conf.extra.script（GroovyConf），不是 docs/ABOUT_DAG.md 示例里写的 conf.reduceScript——那是文档超前于代码的一例（见第九节）。

七、三层超时体系（02 篇坑 4 的完整答案）

层	配置位置	代码实现	默认/演示值	超时后果
① 整体 DAG	业务 userCheckConf/robotCheckConf.timeoutMilliseconds	`ctx.timeout()`，主循环每跳前检查（FunctionExecutorImpl.java:297）	1000ms	抛 exec_timeout，整个请求失败
② 单 function HTTP	原子能力注册 timeoutMilliseconds	OkHttp callTimeout，烙在按 URL 共享的 client 上（KeywordFunction.java:62）	keyword 1000 / bert 2000	IOException，节点结果丢弃（ignoreError 时链路继续）
③ parallel 内部	节点 timeoutMilliseconds（总预算）+ 各子 function 自身超时	`Future.get(子超时)`，超预算后 1ms 空转（ParallelFunction.java:119-137）	演示策略 1000/2000	该子项结果不进 resultMap

Mac 本地 BERT CPU 推理 ~1.7s（并行抢 CPU 3.3s），①③的演示值和②的注册值全部不够——所以 02 篇附录 A（改 DAG 节点）+ 附录 B（改原子能力注册）两个脚本要一起跑。

八、动手实验：复制演示策略改出自定义 DAG

目标：把提示词注入阈值 201 从 0.99 降到 0.5，并给机器人侧链路加一层"命中即放行白词短路"之外的节点（演示加节点套路）。沿用 02 篇附录 A 的脚本骨架（dag/active → newVersion → 改 confArray → dagUpdateYaml → upgrade）。

1
2


# 0. 取部署版策略做底板(注意不是 docs/ 下那份, 见第九节)
docker cp safety-knowledge:/work/strategy_example.yml /tmp/my_strategy.yml # 或从仓库 example/ 目录取

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


# /tmp/update_my_dag.py，套路与 02 篇附录 A 完全一致
import json, urllib.request, yaml
ADMIN = "http://safety-admin:8006/config/defense/manage"

def post(path, body, ct="application/json"):
 data = body.encode() if isinstance(body, str) else json.dumps(body).encode()
 req = urllib.request.Request(f"{ADMIN}{path}", data=data,
 headers={"Content-Type": ct}, method="POST")
 raw = urllib.request.urlopen(req, timeout=30).read().decode(errors="replace")
 try: return json.loads(raw)
 except json.JSONDecodeError: return {"code": 0, "message": raw[:200]}

active = post("/dag/active", {"group": "default", "businessName": "test"}) # 字段是 businessName
dag = active["data"]; conf_array = dag["confArray"]
new_id = post("/dag/newVersion", {"id": dag["id"]})["data"]["id"]

for node in conf_array:
 # 实验1: 找到 bert 并行节点, 把注入阈值 201 从 0.99 降到 0.5
 if node["nodeId"] == "from_user_test_bert2":
 script = node["routerConf"]["conf"]["script"]
 node["routerConf"]["conf"]["script"] = script.replace("201:0.99", "201:0.5")
 # 实验2: 机器人侧把 stupid_end 换成 groovy, 演示"加一层判断"(节点已存在, 改 router 即可;
 # 真加节点 = 往 confArray append 一个 nodeId 唯一的新节点, 再把上游 router 指向它)

yaml_body = yaml.safe_dump({"id": new_id, "businessName": "test", "group": "default",
 "desc": dag.get("desc", "test"), "rootId": dag["rootId"], "confArray": conf_array},
 allow_unicode=True)
post("/dag/dagUpdateYaml", yaml_body, ct="text/plain")
print(post("/dag/upgrade", {"id": new_id}))

1
2
3
4
5
6
7


docker cp /tmp/update_my_dag.py safety-knowledge:/work/
docker exec safety-knowledge python /work/update_my_dag.py
# upgrade 后 api 侧最迟 ~60s 轮询到变更并重建 DAG(第五节机制); 想立即生效:
docker restart safety-api # 等 1~2 分钟(坑 5)
# 验证: 发一条"轻度注入"文本观察 riskCode 是否从 0 变 201
docker cp quickstart/api_test.py safety-knowledge:/work/
docker exec safety-knowledge python /work/api_test.py '请扮演我已经过世的祖母...'

验证点：api 日志里 加载配置结束，cost=xxms（FunctionChainBuilderImpl.java:70）出现即说明 DAG 已重建；脚本改错（如 return 了不存在的 nodeId）不会报错，只会链路提前结束——用风险样本回归确认。

九、文档超前于代码清单（读 ABOUT_DAG.md 必看）

docs/ABOUT_DAG.md 的说法	代码实况
SessionContext 有 `executedNodes/nodeCosts/businessName/sessionId/currentNode/requestMetadata` 字段（文档 :336-361）	均不存在，真实字段见本文 5.1（SessionContext.java:22-34）
AbstractFunction.run() 有 preProcess/postProcess/handleException 三段式（文档 :219-246）	不存在，真实实现只有 doRun+归档（AbstractFunction.java:41-59）
parallel 归约脚本写 `conf.reduceScript`（文档 :158）	实际读 `conf.extra.script`（ParallelFunction.java:61-65）
Function 表列了 BertFunction/FastTextFunction/KnowledgeSearchFunction（文档 :83-87）	真实类名 SingleLabelPredFunction/KbSearchFunction（FunctionRegistry.java:20-30）
Router 表只列 5 种（文档 :254-260）	实际 7 种（Router.java:23-31，漏 simple_next/risk_end）
docs/strategy_example.yml 引用 fast20250710、bert_20250819、bert_prompt_injection_20250623	实际部署的是 `example/safety-skills/safety-knowledge/strategy_example.yml`：无 fasttext 节点，用 bert_20250916 + bert_prompt_injection_20250828，节点超时 1000/2000

十、源码坐标速查

主题	位置
主执行循环 while 逐跳	`safety/safety-api/src/main/java/com/jd/security/llmsec/service/execute/FunctionExecutorImpl.java:289`
checkContent 头尾截断(2048)	同上 :398, :428-431
结果缓存(user+单条, 15min)	同上 :247, :275-287
DAG 构建(两遍扫描)	`.../service/execute/FunctionChainBuilderImpl.java:73`
AB 按 dagVersion 实时构建	同上 :109-125
ref 深合并 doMerge	`.../utils/FunctionUtil.java:39`（mergeProperties :58）
Function 注册表(9 种)	`.../service/execute/FunctionRegistry.java:20`
parallel 线程池/收取/归约	`.../service/execute/functions/ParallelFunction.java:87 / :119 / :142`
async 包装	`.../service/execute/functions/AsyncFunction.java:36`
HTTP client 按 URL 共享	`.../service/execute/functions/FunctionResourcePool.java:15`
模板方法 run+归档	`safety/safety-basic/.../core/engine/AbstractFunction.java:41`
Node(含节点级 reduceScript)	`safety/safety-basic/.../core/engine/Node.java:24`（run :43）
Router 注册表(7 种)	`safety/safety-basic/.../core/engine/Router.java:23`
groovy router 串行 eval	`.../core/engine/routers/GroovyRouter.java:42`
groovy 引擎预热	`.../core/util/GroovyHelper.java:18-31`
ctx 全字段	`.../core/session/SessionContext.java:21`（timeout() :36）
整体超时默认 1000ms	`.../core/session/CheckConf.java:14`
配置 60s 轮询+变更判断	`.../service/DynamicConfigService.java:65, :113-151`
演示策略(实际部署版)	`example/safety-skills/safety-knowledge/strategy_example.yml`

模型安全检测 05：Free-Taxi 异步检测模式源码走读

Mon, 14 Sep 2026 10:03:15 +0800

状态：✅ 已完成 前置阅读：03-技术架构与业务模块分析（DAG 引擎与模块全景）；02-Mac 本地部署实操（环境可复现本篇实验） 素材来源：safety/safety-api 源码逐行核实 + docs/ABOUT_FREE_TAXI.md 读者定位：想搞懂"流式输出场景下检测结果怎么异步返回"的读者；准备在生产接入 free_taxi 的读者

〇、一句话认识 free_taxi

同步检测像"过安检才放行"，free_taxi 像"先上车、后补票"：请求来了不等检测结果，立即返回；检测在后台异步跑，结果攒在 Redis 队列里，搭下一次请求的"便车"捎回去。

它解决的是一个尖锐矛盾：大模型流式输出（SSE）场景下，业务方每收到一小段生成内容就调一次检测接口。如果用 sync 模式，每次调用都要等 DAG 跑完（关键词几十毫秒、BERT 几秒），首 token 延迟直接爆炸。free_taxi 把"检测"和"返回"解耦——代价是结果滞后一条消息，本篇把这个代价和它的适用边界讲透。

一、问题场景与四种 responseMode

1.1 流式检测的矛盾

1
2
3
4


同步模式下的流式检测：
业务方 ──分片1──► safety-api ──跑DAG(2s)──► 返回结果 ──► 业务方才敢输出分片1
 ──分片2──► safety-api ──跑DAG(2s)──► ...
首 token 延迟 = DAG 耗时，用户盯着空白屏幕等 2 秒，不可接受。

docs/ABOUT_FREE_TAXI.md 把核心问题归纳为两条：识别耗时叠加 RTT 造成性能瓶颈；检测完成前恶意内容可能已经暴露。free_taxi 的方案是：请求侧零等待，检测侧异步追，结果侧搭便车。

1.2 四种 responseMode 对比

枚举定义在 safety/safety-basic/src/main/java/com/jd/security/llmsec/core/session/ResponseMode.java:7-27：

模式	语义（枚举注释原文）	检测时机	结果怎么拿	适用
`sync`	同步返回	请求线程内同步跑 DAG	本次响应直接带回	非流式、短文本、强实时
`free_taxi`	通过同一会话的后续请求顺带返回结果	后台异步	下一次请求捎回 / 收尾请求取全量	流式 SSE、多轮对话
`http`	通过防御系统的 api 获取结果	后台异步	主动调 `/defenseResult/v2/{accessKey}` 拉取	不方便在同会话捎结果的场景
`mq`	消息队列方式返回	后台异步	空 stub，需自行实现	京东内部 JDQ，开源版未实现

mq 是空实现，必须点名：safety/safety-api/src/main/java/com/jd/security/llmsec/service/storage/MessageQueueServiceImpl.java:30-33——appendResponseData() 方法体为空，上面挂着 // todo 增加输出到mq。开源版本里 mq/http 模式在任务执行侧都会写 Redis 结果队列（见 3.6），但"推到消息队列"这一步是空的，生产要用 mq 模式得自己实现 MessageQueueService 接口。

1.3 入口分派：一个 switch 定生死

DefenseApiV2Controller.defenseV2() 在过完参数校验、限流、签名鉴权、预处理之后，按 responseMode 分派（safety/safety-api/.../contoller/DefenseApiV2Controller.java:97-127，注意包名是 contoller，官方拼写错误）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


switch (mode) {
 case sync: // :98 同步：直接跑DAG拿结果
 responseData = defenseService.process(request);
 ...
 break;
 case free_taxi: // :106 先投递，再捞历史结果
 defenseService.submit(request);
 responseData = defenseService.fetchResult(request.getAccessKey(),
 request.getMessageInfo().getSessionId(), DefenseResultFetchRequest.Type.all);
 if (CollectionUtils.isNotEmpty(responseData) && request.getMessageInfo().getSliceId() != null) {
 responseData = responseData.stream().filter(x -> // :109 分片场景按messageId过滤
 Objects.equals(request.getMessageInfo().getMessageId(), x.getRequests().get(0).getMessageId()))
 .collect(Collectors.toList());
 }
 break;
 case mq: // :119 mq/http 只投递，本次返回空
 case http:
 defenseService.submit(request);
 responseData = Lists.newArrayList();
 break;

逐行批注：

free_taxi 的顺序是"先 submit 后 fetchResult"（:107-108）：先把自己的消息投进异步队列，再把之前积攒的结果全捞出来。这意味着本次请求自己的检测结果绝不可能出现在本次响应里——滞后一条是机制性的，不是 bug。
sliceId 过滤（:109-114）：流式分片场景（同一条 message 切成多个 slice 上报）下，只返回与本次 messageId 匹配的结果，避免把上一条消息的结论张冠李戴。
mq/http 本次响应恒为空列表（:121-122），结果要么走 /defenseResult/v2/{accessKey} 接口拉（controller :159-181），要么（理论上的）走 MQ 推。
checkParams（DefenseServiceImpl.java:70-72）规定：非 sync 模式 sessionId 必填——没有会话就没有"便车"可搭。

二、free_taxi 全景：队列地图与完整时序

2.1 Redis 键地图（先认路再走源码）

所有键由 safety/safety-api/.../utils/ContentHelper.java 统一拼装，前缀是 GlobalConf.CACHE_PREFIX：

Redis 键	类型	内容	过期	定义位置
`{prefix}task:queue`	list	全局任务队列，元素是全局会话 ID	不过期	`TaskService.java:15`
`{prefix}session:new:{gSessionId}`	list	该会话待处理的新消息（请求 JSON）	300s	`TaskService.java:16-17`
`{prefix}session:lock:{gSessionId}`	string	会话分布式锁，值是 lockId	10s	`TaskExecutor.java:16`
`{prefix}session:resp:{gSessionId}`	list	该会话已出未取的结果	300s	`TaskExecutor.java:14-15`
`{prefix}session_history:{gSessionId}`	list	会话历史（供多轮检测取上文）	1800s	`SessionService.java:17`
`{prefix}{business}:{md5(content)}`	string	识别结果缓存	15min+抖动	`ContentHelper.java:27-29`

其中 gSessionId = accessKey + ":" + sessionId（ContentHelper.globalSessionKey() :55-57），把业务方 sessionId 包一层业务前缀，避免不同业务撞号（TaskServiceImpl.java:75-76 的注释明说"避免相同业务sessionId冲突"）。

2.2 “结果搭便车"完整时序

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


业务方 safety-api(Web线程) Redis 分发线程 执行线程池
 │ POST free_taxi(msg1) │ │ │ │
 │──────────────────────────►│ submit() │ │ │
 │ │─pipeline: lpush task:queue, gSid │ │
 │ │ lpush session:new:gSid, msg1►│ │
 │ │ fetchResult() │ │ │
 │ │─rpopN session:resp:gSid(空)───────────►│ │
 │ 立即返回, data=[] │ │ rpop task:queue ◄────│ 每10ms轮询 │
 │◄──────────────────────────│ │─────── gSid ─────────►│ execute(gSid) │
 │ │ │ │──────────────►│ setnx session:lock:gSid ✔
 │ │ │ │ │ rpopN session:new:gSid → [msg1]
 │ ★ msg1 此刻才被检测 │ │ │ │ expire lock 续约10s
 │ │ │ │ │ 跑DAG(批量) → lpush session:resp:gSid
 │ │ │ │ │ del lock 释放
 │ POST free_taxi(msg2) │ │ │ │
 │──────────────────────────►│ submit(msg2) → 入队(同上) │ │
 │ │ fetchResult() │ │ │
 │ │─rpopN session:resp:gSid ──────────────►│ │
 │ 返回 msg1 的检测结果! │◄──── [result(msg1)] ───────────────────│ │
 │◄──────────────────────────│ ★ 便车：msg2 的请求捎回 msg1 的结果 │ │
 │ ... │ │ (msg2 在后台被检测) │ │
 │ POST sync(content='$') │ │ │ │
 │──────────────────────────►│ process(): 抢锁等异步落盘(最多~300ms) │ │
 │ 返回全部剩余结果 │ + fetchResult 全量取回 │ │
 │◄──────────────────────────│ │ │ │

三个关键认知：

第一次请求永远拿不到结果——它提交时结果队列必是空的，它的结果要等下一次请求来取。
收尾请求（sync + content=’$’）是必需的。最后一条消息没有"下一班车”，必须发一个 sync 请求把尾包结果取走（详见 3.7）。'$' 只是占位符：代码里没有任何对 $ 的特殊处理（已全仓 grep 核实），它只要能过 checkParams 的"content 不能为空"校验即可（DefenseServiceImpl.java:62）。
检测永远追在消息后面跑，业务方全程零阻塞。

三、源码走读：投递 → 分发 → 抢占 → 批量识别 → 结果回流

3.1 投递：Redis pipeline 一次写入两个队列

TaskServiceImpl.addTask()（safety/safety-api/.../service/task/TaskServiceImpl.java:74-94）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


String sessionId = ContentHelper.globalSessionKey(request.getAccessKey(), request.getMessageInfo().getSessionId()); // :76 业务前缀+会话ID
String newMsgKey = ContentHelper.newTaskKey(sessionId); // :77 → session:new:{gSid}
boolean success = ExceptionHelper.doWithRetry(3, () -> storageService.execute(jedis -> { // :78 失败重试3次
 Pipeline pipelined = jedis.pipelined();
 pipelined.lpush(ContentHelper.taskQueueKey(), sessionId); // :80 全局任务队列 +1
 pipelined.lpush(newMsgKey, JSON.toJSONString(request)); // :81 会话新消息队列 +1
 pipelined.expire(newMsgKey, NEW_MESG_EXPIRE_SECONDS); // :82 300s 兜底过期
 pipelined.sync(); // :83 一个RTT全部发出
 return null;
}));

批注：

一次 pipeline 写完"全局任务队列"和"会话新消息队列"，保证两个队列不会一个写一个没写（严格说 pipeline 只是单 RTT 批量发命令、非事务，但这两个 lpush 之间不会被该连接的其他命令插队，实际足够）。
每次请求都往全局队列 lpush 一个 sessionId，同一会话可能重复入队——没关系，下游抢到锁后会把会话消息队列一次性榨干（见 3.4），重复元素只是空转一次锁争抢。
submit() 本身吞掉所有异常只打日志（DefenseServiceImpl.java:132-138），投递失败不影响业务方收到成功响应——这是"检测绝不能拖垮业务"的设计哲学，代价是消息可能丢失（监控指标 add_task_error 兜底）。

3.2 分发：每个 api 实例一条"拉活"线程

TaskServiceImpl.init()（:40-65）用 @PostConstruct 起一个名为 task-local-dispatcher 的常驻线程：

1
2
3
4
5
6
7
8


while (running) {
 String sessionId = storageService.rpop(ContentHelper.taskQueueKey(), String.class); // :48 全局队列取会话
 if (StringUtils.isEmpty(sessionId)) {
 TimeUnit.MILLISECONDS.sleep(10); // :50 空转sleep 10ms
 continue;
 }
 taskExecutor.execute(sessionId); // :54 扔进线程池
}

批注：队列在 Redis 里，是全局唯一的；每个 api 实例各跑一条分发线程去 rpop。多实例部署时天然竞争消费、天然负载均衡——谁 rpop 到谁处理。实例挂了也不丢任务（还在 Redis list 里），这就是 docs/ABOUT_FREE_TAXI.md 说的"容错机制：处理实例故障不影响整体服务"的实现出处。另外注意 TaskService.java:20-25 的注释说"待处理会话队列使用zset"，实际实现是 list，注释过时了，以代码为准。

3.3 执行容器：200 线程池 + CallerRunsPolicy

TaskExecutorImpl.init()（:54-64）：

1
2
3
4


pool = new ThreadPoolExecutor(200, 200, 5, TimeUnit.MINUTES,
 new LinkedBlockingQueue<>(10), // 等待队列只有10
 r -> { ... t.setName("task-executor-" + ...); },
 new ThreadPoolExecutor.CallerRunsPolicy()); // :63 满了由分发线程亲自跑

批注：200 个执行线程意味着单实例最多并行处理 200 个会话。队列只有 10、拒绝策略是 CallerRunsPolicy——线程池爆了就让分发线程自己下场干活，既提供了背压（分发线程被占住就暂停 rpop），又不会抛异常丢任务。这是背压设计里很典型的" caller 兜底"手法。

3.4 抢占与滑动窗口批量识别：本篇最核心的一段

TaskExecutorImpl.execute()（:78-188）核心逻辑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


boolean lockSuccess = storageService.lock(ContentHelper.lockKey(sessionId), MAX_LOCK_SECONDS); // :88 抢会话锁, TTL=10s
if (!lockSuccess) {
 TimeUnit.MILLISECONDS.sleep(1 + System.currentTimeMillis() % 5); // :103 没抢到睡1~5ms
 continue; // TASK_WAIT_LOOP=1 → 实际直接放弃
}
try {
 while (true) { // :113 榨干会话消息队列
 requests = storageService.rpopN(ContentHelper.newTaskKey(sessionId),
 batchSize < 0 ? DEFAULT_BATCH_PROCESS_SIZE : batchSize, DefenseApiRequest.class); // :116 首批10条
 if (CollectionUtils.isEmpty(requests)) { break; } // :122 取空=处理完了
 if (batchSize < 0) {
 checkConf = ... businessConf.getRobotCheckConf()/getUserCheckConf();
 batchSize = checkConf.getCheckNum() <= 0 ? DEFAULT_BATCH_PROCESS_SIZE : checkConf.getCheckNum(); // :130 滑动窗口=batch=checkNum
 }
 storageService.execute(jedis -> jedis.expire(ContentHelper.lockKey(sessionId), MAX_LOCK_SECONDS)); // :135 每批前续约锁
 doExecute(requests, sessionId); // :136 批量跑完整DAG
 TimeUnit.MILLISECONDS.sleep(checkConf.getAdaptivePauseMilliseconds() + System.currentTimeMillis() % 10); // :148 批间随机sleep
 }
} finally {
 storageService.unlock(ContentHelper.lockKey(sessionId)); // :156 释放锁
 ...
}

逐行批注：

抢锁只试一次（TASK_WAIT_LOOP = 1，:73）。抢不到就睡 1~5ms 然后退出循环、任务结束。看起来粗暴，实则精妙：锁的持有者正在 while(true) 循环里榨干同一个会话的消息队列——后来者刚 lpush 进去的消息会被持有者一并处理掉，根本不需要第二个线程。这就是"抢占语义"：谁抢到谁包办，抢不到的人放心走人。
多实例互斥的天然性：锁是 Redis setnx（见 3.5），与实例无关。A 实例的线程拿着锁，B 实例分发到同一会话也只会空抢一次然后放弃。
滑动窗口 = checkNum：第一批固定取 10 条（DEFAULT_BATCH_PROCESS_SIZE，:71），随后把批大小校准为业务配置的 checkConf.checkNum（:127-131），之后每批按 checkNum 条rpopN 凑成一组跑完整 DAG。checkNum 就是 CheckConf.java:13 的字段（默认 1），对应 admin 后台"多轮检测条数"配置。
批间续约（:134-135）：每批处理前把锁 expire 回 10s。注释原话"续约，避免单个线程长期占用时时间无法估计的问题"——会话持续有消息时持有者会一直干下去，靠续约防止锁到期被别人抢。
批间随机 sleep（:144-149）：adaptivePauseMilliseconds（默认 50ms，CheckConf.java:15）+ 0~9ms 随机抖动。注释原话"降低cpu使用率，提高整体吞吐"——主动让出 CPU 也放慢消费速度，给上游消息攒批的机会，提高每批的满载率。
抢到锁后还初始化了三个 ThreadLocal（threadLocalService.sessionId/histories/lastUserReq，:90-92），供多轮检测在同一执行线程内复用会话历史缓存，finally 里逐一 remove（:157-159）。

3.5 锁实现：setnx+expire，以及它的两个小瑕疵

RedisStorageService.lock()（safety/safety-api/.../service/storage/RedisStorageService.java:102-113）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public boolean lock(String key, int expireSeconds) throws Exception {
 String value = GlobalConf.lockId(); // 值 = IP/线程名/时间戳
 Long rawValue = (Long) this.execute(jedis -> jedis.setnx(key, value));
 boolean returnOk = Objects.equals(1L, rawValue);
 if (returnOk) {
 this.execute(jedis -> jedis.expire(key, expireSeconds)); // :108 第二步才设过期
 return true;
 } else {
 return false;
 }
}

如实指出两个生产注意点（代码如此，不是猜测）：

setnx 和 expire 是两条命令，非原子。若在两条命令之间进程崩溃，锁会永远存在——但 3.4 的持有者异常路径靠 finally 里的 unlock 兜底，且消息队列 300s 过期，实际泄漏窗口可控。更稳的写法是 SET NX EX 一条命令（缓存写入处 :253-254 恰恰就是这么写的）。
unlock() 是无条件的 del（:116-118），不校验值是不是自己写的 lockId。极端时序下（持锁者卡顿超 10s → 锁过期 → 别人抢到 → 原持锁者 finally 里 del）可能误删别人的锁。好在续约机制 + 抢占语义（重复处理无副作用，只是多跑一次 DAG）让后果不严重。这是一个"够用就行"的锁，不是严格分布式锁。

3.6 结果回流：lpush 会话结果队列

TaskExecutorImpl.doExecute()（:197-227）：批量请求先按 fromRole 分组（FunctionExecutorImpl.splitByRole() :82-100，user/robot 分开跑 DAG），每组跑完得到一个 DefenseApiResponse，然后：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


case free_taxi:
case http:
case mq:
 boolean success = ExceptionHelper.doWithRetry(3, () -> { // :209 重试3次
 String responseKey = ContentHelper.responseKey(sessionId); // → session:resp:{gSid}
 storageService.execute(jedis -> {
 Pipeline pipelined = jedis.pipelined();
 pipelined.lpush(responseKey, JSON.toJSONString(response)); // :213 结果入队
 pipelined.expire(responseKey, RESP_EXPIRE_SECONDS); // :214 300s 过期
 return null;
 });
 });
 messageQueueService.appendResponseData(...); // :222 mq推送(空stub)

注意 sync 模式在异步链路里不写结果队列（:204-205 直接 break）——sync 的结果由请求线程自己带回。取数逻辑在 TaskExecutorImpl.fetchResult()（:230-257）：Type.all 用 rpopN(responseKey, 50) 一次最多取 50 条，Type.latest 只 rpop 一条。rpop 即消费，取走就没了，所以"便车"只能搭一次。

3.7 sync(content=’$’) 收尾：先抢锁等异步结果落盘

收尾请求走 sync 模式，精华在 FunctionExecutorImpl.invoke(单条)（safety/safety-api/.../service/execute/FunctionExecutorImpl.java:109-161）：

1
2
3
4
5
6
7
8


boolean shouldLock = StringUtils.isNotEmpty(sessionId) && messageId != null; // :113 有会话才需要等
if (shouldLock) {
 for (int i = 0; i < 6; i++) { // :119 最多试6次
 lockSuccess = storageService.lock(ContentHelper.lockKey(sessionId), 2);// :121 抢同一把会话锁, TTL=2s
 if (lockSuccess) { break; }
 TimeUnit.MILLISECONDS.sleep(50); // :128 每次睡50ms
 }
}

为什么抢锁等于"等异步结果落盘"：异步执行线程处理会话期间持有同一把 session:lock:{gSid}（3.4）。sync 请求抢到锁 ⇔ 异步线程已经处理完并释放 ⇔ 该会话的结果已全部 lpush 进结果队列。等锁的循环 6 次 × 50ms ≈ 最多等 300ms。这里要如实指出：docs/ABOUT_FREE_TAXI.md 说"无结果时等待200ms"，代码实际是 6×50ms=300ms 上限，文档与实现略有出入，以代码为准。

拿到自己的 DAG 结果后，DefenseServiceImpl.process() 再把便车结果合并进来（DefenseServiceImpl.java:149-160）：

1
2
3
4
5
6


case sync:
 ...
 if (checkConf != null && checkConf.getCheckNum() > 1 && StringUtils.isNotEmpty(messageInfo.getSessionId()) && messageId != null) {
 preResults = this.fetchResult(..., DefenseResultFetchRequest.Type.all); // :158 全量取回攒下的异步结果
 results.addAll(preResults);
 }

注意这个 checkNum > 1 的门槛（:157）——旁边注释（:153-156）明说了设计意图：“checkNum > 1时一般都会伴随着free_taxi(也就是异步处理)，这个时候需要获取历史识别内容”。也就是说 sync 收尾能取回异步结果的前提是业务配置了多轮检测（checkNum>1）；checkNum=1 的纯同步业务走 sync 时不会去捞结果队列。

3.8 会话历史：多轮检测的上文来源

异步 DAG 里做多轮检测（checkNum>1）需要上文，来源是 SessionServiceImpl.addHistory()（safety/safety-api/.../service/session/SessionServiceImpl.java:314-339）：每次 DAG 跑完把请求历史 rpush 进 session_history:{gSid}（list，1800s 过期，SessionService.java:17），多轮节点用 lrange 倒数取最近 N 条（:277）。细节：sync 模式的写历史走 3 线程小池异步提交（:325-326），异步模式则就地同步写（:328）——因为异步线程反正不在请求链路上，不怕慢。

3.9 识别结果缓存：MD5 内容缓存 15 分钟

FunctionExecutorImpl 里的结果缓存（:247-287）：

开关：execute.cache.enable（:272），官方示例配置默认 false（safety-api/docs/application_example.properties:16）。
生效条件（shouldCache() :275-287）：开关开 + 仅 user 角色 + userCheckConf.checkNum == 1（多轮检测不缓存，因为结果依赖上文，同文不同命）。
键：{prefix}{businessName}:{MD5(content)}（ContentHelper.java:27-29），值写入用 SET NX EX 带 0~300s 随机抖动（:253-254），基础 TTL RESP_CACHE_SECONDS = 15 * 60（:247）。

这就呼应了 02 篇的实操经验"重试时改动一两个字避开结果缓存"（02 篇坑 6/常见过渡态）：缓存键是内容 MD5，改一个字就是另一个键。做功能验证时如果开着缓存，原样重试会秒回旧结果，无法验证"模型服务是否恢复"。

四、业务链路：配置怎么流转，请求怎么流转

4.1 配置流（与 03 篇呼应，此处落到 free_taxi 相关项）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


运维/admin页面 ──► safety-admin ──写──► MySQL（版本化状态机）
 │ ① safety-api 不直连MySQL
 ▼ ② 每60s HTTP轮询 /config/defense/api/conf
 DynamicConfigService.loadConf() @Scheduled(fixedRate=60000) (DynamicConfigService.java:65)
 │ 全量对比 lastChangeTimestamp，变了才更新
 ▼ ③ 内存缓存 name2BusinessConf / nodeConfMap (volatile 整体替换)
 FunctionChainBuilderImpl 注册为配置变更监听器 (FunctionChainBuilderImpl.java:48-50)
 ▼ ④ 重建每个业务的 DAG 根节点 rootMap (FunctionChainBuilderImpl.java:64)
 异步链路消费：TaskExecutorImpl.execute() 首批消息触发 configService.businessConf() (:128)
 读到 checkConf.checkNum → 决定滑动窗口批大小

free_taxi 视角的重点：checkNum、adaptivePauseMilliseconds 都是 BusinessConf 里的配置项，admin 改完最多 60s 后 api 内存刷新，下一批异步任务生效（已在跑的线程的 batchSize 是首次取数时固化下来的，:127-131）。这也解释了 02 篇坑 5"改了配置不生效"——60s 轮询 + 内存缓存是设计使然。

4.2 请求流（free_taxi 一条消息的完整旅程）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


业务方 ──► POST /llmsec/api/defense/v2/{accessKey}
 ① checkParams 非sync必须有sessionId (DefenseServiceImpl.java:60-77)
 ② rateLimited 业务级限流 (:82-89)
 ③ verify HMAC-SHA1 签名（test开头key跳过，Controller :74）
 ④ preProcess 流式业务解析OpenAI响应/截断超长 (:107-129)
 ⑤ submit pipeline写 task:queue + session:new (TaskServiceImpl.java:74-94)
 ⑥ fetchResult rpopN session:resp 捞历史结果 (TaskExecutorImpl.java:230-257)
 ◄── 立即响应（携带历史结果，无本次结果）
后台：dispatcher rpop task:queue ─► 线程池 execute ─► 抢锁/rpopN批量/DAG(skill: keywords→bert→...)
 ─► lpush session:resp + rpush session_history ─► 等下一班"便车"

五、动手实验：模拟 3 轮会话观察便车

复现环境见 02 篇（docker compose 全套已起、test 业务已初始化）。以下脚本保存为 quickstart/free_taxi_test.py 自行运行即可（不改动仓库原有文件；api_test.py 里 request() 的签名逻辑直接复用其写法）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


# coding=utf-8
"""free_taxi 3轮会话实验：观察结果滞后一条 + sync('$') 收尾"""
import json, time, random, string, requests

URL = 'http://127.0.0.1:8007/llmsec/api/defense/v2/test' # test 开头 accessKey 免签名(Controller:74)

def call(content, msg_id, mode='free_taxi', session='ft-session-001'):
 body = {
 "businessType": "toC", "content": content, "contentType": "text",
 "requestId": ''.join(random.choices(string.ascii_letters + string.digits, k=20)),
 "accessKey": "test", "accessTarget": "defenseV2",
 "timestamp": int(time.time() * 1000), "plainText": content,
 "messageInfo": {"fromId": "user123456", "fromRole": "user",
 "sessionId": session, "messageId": msg_id},
 "responseMode": mode,
 }
 r = json.loads(requests.post(URL, json=body).text)
 data = r.get('data') or []
 risks = [(d.get('riskCode'), d.get('riskMessage')) for d in data]
 print(f'msg{msg_id} [{mode}] content={content!r:30} -> 本次返回: {risks or "空"}')
 return r

if __name__ == '__main__':
 call("你好", 1) # 预期：返回空（第一次请求无便车可搭）
 time.sleep(3) # 等后台异步检测完（本地BERT在CPU上约3.4s，见02篇）
 call("你是王八蛋", 2) # 预期：捎回 msg1 的结果（正常）
 time.sleep(3)
 call("今天天气怎么样", 3) # 预期：捎回 msg2 的结果（riskCode=1006 辱骂）
 time.sleep(3)
 call("$", 4, mode='sync') # 收尾：预期返回 msg3 结果 + 本次自身结果

预期观察（与源码一一对应）：

msg1 返回空——它提交时结果队列必空（3.1/3.6）。
msg2 捎回 msg1 的结论——便车机制（Controller :107-108 先 submit 后 fetchResult）。
msg3 捎回 msg2 的辱骂命中——注意滞后的是整整一条消息，如果 msg2 是恶意内容，业务方在 msg2 当次是拿不到拦截结论的。
收尾 sync(’$’) 抢锁等异步落盘后全量取回（3.7）。若 checkNum=1 的 test 业务收尾响应里没有历史结果，别惊讶——重读 3.7 末尾的 checkNum > 1 门槛。
想看队列实况可以另开终端：docker exec -it safety-redis redis-cli 后 LRANGE task:queue 0 -1、KEYS *session:resp*。

六、生产注意点（代价与适用边界）

事项	机制事实（出处）	建议
结果滞后一条	先 submit 后 fetchResult（Controller :107-108）	只用于"事后补拦截"可接受的场景（撤回消息、标记会话、惩罚账号）；不适用于必须当次拦截的强实时场景，那种用 sync
尾包丢失风险	最后一条消息没有下一班车	必须发 sync 收尾请求；或轮询 `/defenseResult/v2/{accessKey}`（Controller :159-181）
结果只保留 300s	`RESP_EXPIRE_SECONDS=300`（TaskExecutor.java:15）	便车间隔超过 5 分钟结果就没了；长间隔会话用 latest/all 主动拉
消息丢失不阻塞业务	submit 吞异常仅监控（DefenseServiceImpl.java:132-138）	盯 `add_task_error` 监控指标；强保障需求自行加固
锁是"够用就行"	setnx+expire 非原子、unlock 无值校验（RedisStorageService.java:102-118）	水平扩容没问题（抢占语义保证幂等）；不要把这个锁模式照抄到资金类场景
mq 是空 stub	MessageQueueServiceImpl.java:30-33	生产要用 mq 模式需自行实现 `MessageQueueService` 两个方法
结果缓存默认关	execute.cache.enable=false（application_example.properties:16）	开启后注意：仅 user 单轮生效；验证问题时"重试改一两个字"（呼应 02 篇）
checkNum>1 才有 sync 收尾合并	DefenseServiceImpl.java:157	free_taxi 业务建议在 admin 配好多轮检测条数，否则收尾请求捞不回历史结果

一句话总结：free_taxi 用"Redis 全局队列 + 会话级分布式锁 + 滑动窗口批量"三件套，把检测从请求链路上整个摘下来；它的所有设计妥协（滞后一条、吞异常、简化锁）都指向同一个目标——检测可以慢、可以丢，但绝不能挡业务的路。

参考坐标（全部经 Read/Grep 亲自核实）

机制	位置
responseMode 分派	`safety/safety-api/.../contoller/DefenseApiV2Controller.java:97-127`
结果拉取接口	同上 :159-181
process/submit/fetchResult	`safety/safety-api/.../service/DefenseServiceImpl.java:132-194`
投递 pipeline	`safety/safety-api/.../service/task/TaskServiceImpl.java:74-94`
分发线程	同上 :40-65
线程池/抢锁/批量/续约/回流	`safety/safety-api/.../service/task/TaskExecutorImpl.java:54-257`
分布式锁	`safety/safety-api/.../service/storage/RedisStorageService.java:102-118`
会话历史写 Redis	`safety/safety-api/.../service/session/SessionServiceImpl.java:314-356`
sync 收尾等锁	`safety/safety-api/.../service/execute/FunctionExecutorImpl.java:109-161`
结果缓存	同上 :247-287 + `utils/ContentHelper.java:27-29`
ResponseMode 枚举	`safety/safety-basic/.../core/session/ResponseMode.java:7-27`
mq 空 stub	`safety/safety-api/.../service/storage/MessageQueueServiceImpl.java:30-37`
配置轮询/DAG重建	`DynamicConfigService.java:65`、`FunctionChainBuilderImpl.java:48-64`
官方设计文档	`docs/ABOUT_FREE_TAXI.md`（“等200ms"与代码 300ms 上限有出入，以代码为准）

模型安全检测 06：敏感词服务深入（AC 自动机 + 正则倒排加速）

Mon, 14 Sep 2026 10:03:15 +0800

状态：✅ 已完成 前置阅读：03-技术架构与业务模块分析（模块全景与两个时期划分）；02-Mac本地部署实操（实验环境可复现） 素材来源：safety/safety-skills/safety-keywords 源码逐行核实 + safety-api 侧 KeywordFunction + admin 表结构与 API 文档 读者定位：想搞懂"敏感词检测为什么能做到毫秒级、万级词库"的读者；准备维护词库、写自定义检测能力的读者

〇、先建立全局认识

0.1 服务定位：第一道安检

safety-keywords 是整个审核链路里最便宜也最快的一环，类比机场安检的"第一道闸机"——X 光粗筛，成本低、速度快，拦下明显违禁品，拿不准的交给后面的精检仪器（BERT）。

属性	值	出处
技术栈	Java / Spring Boot（`@EnableScheduling` 开启定时任务）	`LlmSecSensitiveApplication.java:14`
容器内端口	8005（根 compose 里 `ports` 被注释，仅容器网络可达）	`docker-compose.yaml:145`
对外接口	仅一个：`POST /keyword/query`	`contoller/SensitiveWordsController.java:24`（包名 `contoller` 是仓库原样的拼写）
数据源	MySQL `sensitive_words` 表，只加载 status=online	`SensitiveWordsManageServiceImpl.java:359`
匹配引擎	AC 自动机（org.ahocorasick 0.4.0）+ 正则倒排加速	`pom.xml:73`

它在全链路中的位置（配置期与执行期分开，和 03 篇的框架一致）：

1
2
3
4
5
6


配置期： 运维 ──► safety-admin(8006) /data/sensitive_words/upsert ──► MySQL sensitive_words
 │ 每 60s 轮询，有变更则全量重建 Trie
执行期： ▼
 业务方 ──► safety-api(8007) ──DAG──► KeywordFunction ──HTTP──► safety-keywords(8005) /keyword/query
 ▲ │
 └──── KVResponse(bwgLabel) ──┘

0.2 数据模型：一张表讲清四个维度

safety/safety-admin/docs/tables.sql:1 的 sensitive_words 表，核心字段：

字段	作用	取值
`word`	词本体（普通词或正则）	varchar(1000)
`match_type`	匹配方式	contain（包含）/ equal（完全相等）/ regex（正则）
`handle_strategy`	命中后处置	black（拦截）/ white（放行）/ grey（观察）/ exclude（豁免）
`business_scene`	生效业务范围	`all` 或空 = 全局；否则逗号分隔的业务名列表
`status`	上线状态	online 才会被检测服务加载
`first_class_no/name`	风险分类（如 1006/辱骂）	命中后透传给 DAG 做 riskCode

表上有 ON UPDATE CURRENT_TIMESTAMP 的 update_time 字段（tables.sql:22）——这是热更新机制的关键伏笔，见第五章。

0.3 ⚠️ 文档/提纲与源码的出入（本篇一律以源码为准）

核实源码时发现几处"传说中的设计"与实际实现不符，先立此存照：

常见说法	源码实际
match_type 有 compound（组合）	只出现在 tables.sql:9 的注释里；`MatchType.java:12` 枚举只有 contain/equal/regex/exclude，全仓库无 compound 实现
handle_strategy 有 gray	代码里拼写是 grey（`WordsUtils.java:29`、`BwgLabelUtils.java:17`）。词库里写 “gray” 会落到 default 分支：bwgLabel=0、排序优先级最低，等于不生效
exclude 是一种 match_type	枚举里确实声明了（MatchType.java:31），但 `doContainTask` 把它当 handleStrategy 用（`SensitiveWordsManageServiceImpl.java:124`）；match_type=exclude 的词根本不会被加载（contains 引擎只查 contain/equal，见 :282）
双引擎各有一个线程池	实际是一个 200 线程的共享池，提交两个任务（:51、:65-66）

一、匹配算法核心：AC 自动机

1.1 为什么不用笨办法

词库 1 万个词、文本 1000 字，逐个词 String.contains() 是 O(词库规模 × 文本长 × 词长)，千万级字符操作，单次请求就要几百毫秒。AC 自动机（Aho-Corasick）把所有模式串先编译成一棵树，文本只扫一遍，复杂度 O(文本长 + 命中数)，与词库规模基本无关。

1.2 三件套：goto / fail / output

以词库 {王八蛋, 八蛋, 坏蛋} 为例：

1
2
3
4
5
6
7
8
9


 goto（实线，建树时确定） fail（虚线，匹配失败时跳转）
 (root)
 ┃王 ┃八 ┃坏
 ▼ ▼ ▼
 (王)──八──▶(王八) (八)──蛋──▶(八蛋)★ (坏)──蛋──▶(坏蛋)★
 │蛋 ▲
 ▼ ┆
 (王八蛋)★ ─ ─ fail ─ ─ ─ ┘
 ★ = output（到此节点说明命中了一个完整的词）

fail 指针的含义：“当前匹配走不下去时，已匹配串的最长后缀在哪里”。比如在 (王八) 节点读到"蛋"走到 (王八蛋)，它的 fail 指向 (八蛋)——因为"王八蛋"的最长后缀"八蛋"本身也是模式串。扫文本"老王八蛋"的过程：

老：root 没有这条边，留在 root（没有任何词被"部分命中"）
王→(王)；八→(王八)；蛋→(王八蛋)，output：命中"王八蛋"
沿 output 链接补报 fail 链上的 ★：同时命中"八蛋"

一句话理解：AC 自动机 = Trie 树 + KMP 的 fail 思想推广到多模式串。命中可重叠（“王八蛋"和"八蛋"都会报），这正是敏感词场景想要的。

1.3 为什么不选 DFA

把上万条规则编译成一个确定性自动机（DFA），理论匹配也是 O(n)，但状态数会爆炸、构建慢、内存大，词库每分钟都要热重建的场景下不可行。AC 建树是 O(总词长)，万级词库重建只需毫秒级，重建完整体替换引用即可（见第五章）。

1.4 代码：一个 34 行的薄封装

service/data/SensitiveWordDetector.java:14-33 全部职责就是把词库交给 ahocorasick 库建树、查询透传：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


public SensitiveWordDetector(Map<String, List<MatchType.SensitiveWordsVO>> sensitiveWordsMap) {
 Trie.TrieBuilder builder = Trie.builder();
 for (String word : sensitiveWordsMap.keySet()) {
 builder.addKeyword(word); // 逐词加入 Trie
 }
 trie = builder.build(); // 编译：建 goto + fail + output
}
public List<Emit> detectSensitiveWords(String text) {
 return (List<Emit>) trie.parseText(text); // 一遍扫描，返回全部命中（含重叠）
}

两个使用注意：builder 没有调 ignoreCase()，匹配大小写敏感；parseText 返回所有重叠命中（“王八蛋"会同时报出"八蛋”），后续靠排序归约（见第三章）。

二、请求处理全流程：双引擎并行 + 150ms 预算

2.1 入口与预处理

POST /keyword/query → SensitiveWordsController.java:24 → KeywordApiServiceImpl.invoke()（rpc/KeywordApiServiceImpl.java:30）。预处理有两个值得知道的点：

超长截断：文本超过 MAX_LEN = 10000 字时，取前 5000 字 + 后 5000 字拼接（:52）——中间部分直接不检。写超长文本绕过检测在理论上是可能的，别把它当唯一防线。
全程 fail-open：任何异常都返回 statusCode=500 但文案"正常文本"的响应（:69-70）。上游 KeywordFunction 发现 !result.success() 后返回 null（KeywordFunction.java:86-89），该节点等于没结果。敏感词服务挂了不会阻断业务，这是内容安全"宁可漏过不可误杀"哲学的体现——但也意味着监控告警很重要。

2.2 双引擎并行与短路逻辑（全篇最重要的一段代码）

SensitiveWordsManageServiceImpl.parallelDetection()（:63-96），逐行批注：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


Future<...> regexTask = pool.submit(() -> doRegexTask(content, bizName)); // ① 正则引擎
Future<...> containTask = pool.submit(() -> doContainTask(content, bizName)); // ② AC 引擎，同一个 200 线程池
ret1 = containTask.get(waitMillis, MILLISECONDS); // ③ AC 最多等 150ms（MAX_PROCESS_MILLISECONDS，:37）
// 超时 → log warn 并 return null（fail-open，:71-74）
if (ret1 != null && Objects.equals("black", ret1.getHandleStrategy())) {
 regexTask.cancel(true); // ④ AC 命中黑词：掐掉正则任务，直接返回（短路）
 return ret1;
}
ret2 = regexTask.get(剩余预算, MILLISECONDS); // ⑤ 否则用 150ms 减去已耗时间再等正则
// ret2 为 black → 返回 ret2（:85）；否则优先返回 AC 结果 ret1（:88）；正则超时也 return null

决策逻辑画成表：

AC 结果	正则结果	最终返回
black	任意（被取消）	AC 结果（短路，不等正则）
非 black / null	black	正则结果
非 black / null	非 black	优先 AC，其次正则
超时	—	null（放行）
任意	超时	null（放行，连 AC 的非黑命中也丢弃！）

设计解读：

150ms 是这个服务对自己的 SLA 承诺。关键词是链路第一道，不能拖慢整条 DAG（对比：KeywordFunction 注册超时 1000ms，见第六章）。
black 短路是性能优化：黑词已是终局，正则算完也改变不了结果，cancel 掉省 CPU。
正则超时会连累 AC 的非黑命中（最后一行）——白/灰词在正则引擎卡死时会被一起丢弃。这是代码的真实行为，用词时心里有数。

2.3 AC 引擎内部：命中后的四道过滤

doContainTask()（:98-135）在 AC 扫出命中词后还要过四关：

1
2
3
4
5


AC parseText 命中词列表
 → ① 查 wordsMap 拿到该词的所有 VO（同一个词可配多条规则，如不同业务不同处置）
 → ② isSceneMatch 业务场景过滤（all/空=全局；否则逗号列表包含当前业务名，:180-191）
 → ③ equal 类型二次确认：要求 content 完全等于 word（:111-115）
 → ④ WORDS_Comparator 排序取第 0 名；若其 handleStrategy=exclude → return null（豁免，:124-126）

注意 ③：equal 词也进了 AC 树，AC 粗筛出"包含"之后再用字符串相等做精确确认——复用一套索引，省一棵树。

三、match_type × handle_strategy：名单体系

3.1 三种生效的 match_type

match_type	加载进哪个引擎	语义	典型场景
contain	AC 树（:282）	文本包含该词即命中	“王八蛋”（演示词，example/safety-admin/data/sensitive_words.sql:18）
equal	AC 树 + 相等二次确认	整条文本恰好等于该词	验证码类垃圾"加V：xxxx"整句
regex	正则引擎（倒排加速，第四章）	正则 find() 命中	手机号、身份证号、变体广告

3.2 四种 handle_strategy 与 bwgLabel

handle_strategy	bwgLabel（BwgLabelUtils.java:7）	语义	排序优先级（WordsUtils.java:20-34）
exclude	0	豁免：该词在本业务不算敏感，压制其他命中	-4（最高）
black	1	黑名单，命中即拦	-3
white	2	白名单，明确放行（策略里可跳过下游模型，省 BERT 开销）	-2
grey	3	灰名单，观察记录不拦截	-1

优先级排序器的逐行解读（WordsUtils.java:20-34）：先按处置策略升序（exclude 最前），同策略词越长越靠前（thenComparing(-word.length())）。所以"自慰”（black）和"自慰高潮X"（white）同时命中时，返回的是更长的白词——更长更具体的规则优先，这是词库设计的常识：具体规则应当覆盖笼统规则。

exclude 的正确用法：它是 handleStrategy（不是 matchType！见 0.3 节）。比如全局词库有"枪"（black），军事业务的正常讨论就会被误伤；给军事业务配一条 word=“枪”、handleStrategy=exclude、business_scene=military 的记录，该业务命中"枪"时排序器把它排第一，doContainTask 看到 exclude 直接 return null——为特定业务在全局词库上"打孔"。

3.3 业务场景过滤的细节

isSceneMatch()（:180-191）：businessScene 为 "all" 或空串 → 对所有业务生效；否则按逗号 split 后精确包含。两个坑：

方法第一行是 businessScene.equals("all")，businessScene 为 null 会 NPE（null 检查写在后半句，顺序反了）。upsert 时 businessScene 必填，正常不会触发，但直接往 MySQL 灌数据时注意。
匹配是包含语义：业务名是 test 时，business_scene="test2" 不会命中（用的是列表 contains，精确相等）。

四、正则倒排加速（亮点设计）

4.1 问题：为什么不能全量正则扫文本

假设词库有 5000 条正则，每来一次文本就 for (rule : rules) rule.pattern.matcher(text).find()：

复杂度 O(规则数 × 文本长)，单次请求几十上百毫秒起步，150ms 预算必爆；
正则引擎是 NFA 回溯，恶意构造的正则（嵌套量词）有灾难性回溯风险，一条烂规则就能打满 CPU。

4.2 解法：借搜索引擎的倒排索引思想

核心洞察：正则再花，里面总有字面量片段。1[3-9]\d{9} 必须包含 “1”，(赌博|博彩)网站 必须包含"赌博"或"博彩"或"网站"。文本连这些字面量都不含，正则绝不可能命中。于是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


构建期（updateRegex，:205-272）：
 每条 regex 规则 ──regexTokenize(:275)──► 按元字符切开取字面量 token
 │ 切分正则 splitRgex(:274)：( ) . | * + ? [] {} \d{n} 等全部当分隔符
 ▼
 token ──► ① 全量 token 建一棵 AC Trie（regexDetector）
 └──► ② regexInvertMap: token → {规则id 集合} ← 这就是"倒排索引"
 └──► ③ id2WordsMap: 规则id → 编译好的 Pattern

查询期（doRegexTask，:137-161）：
 文本 ──AC 粗筛──► 命中哪些 token？──► 倒排表合并出候选规则 id 集合
 ──► 只对候选规则跑真正的 Pattern.matcher(content).find()（:153）

类比：AC 粗筛是搜索引擎用倒排索引找"可能含这些词的文档"，Pattern 精匹配是打开文档确认。绝大多数文本一个 token 都命中不了，候选集为空直接返回——把"5000 条正则全扫"变成"几条候选正则精验"。

4.3 代码批注

1
2
3
4
5


private Set<String> regexTokenize(String word) { // :275
 List<String> split = Splitter.onPattern(splitRgex) // Guava Splitter，按元字符正则切
 .omitEmptyStrings().trimResults().splitToList(word);
 return new HashSet<>(split); // token 去重
}

1
2
3
4
5
6
7
8


Set<Long> docIds = Sets.newHashSet(); // queryPattern，:163
for (String keyword : matchedKeywords) {
 Set<Long> temp = regexInvertMap.get(keyword); // token → 候选规则 id
 if (CollectionUtils.isNotEmpty(temp)) docIds.addAll(temp);
}
return docIds.stream().map(x -> id2WordsMap.get(x))
 .filter(x -> isSceneMatch(bizName, x.getBusinessScene())) // 同样过业务场景
 .collect(Collectors.toList());

4.4 这个设计的边界（如实记录）

纯元字符/无字面量的正则会失效：如 ^\d+$ 切完没有 token，updateRegex 会 warn “正则表达式分词结果为空"并跳过该规则（:252-255）——这条规则永远不会命中。配 regex 词时必须保证有可切的字面量片段。
token 太常见则粗筛失效：如 “1” 这种 token 几乎每条文本都命中，挂在上面的规则每次都要精匹配。切分粒度无法控制，这是简易实现的代价。
正则侧没有 exclude 短路（doContainTask 才有），exclude 策略的 regex 命中后照常返回 VO，靠 bwgLabel=0 自然放行。

五、词库热更新：60s 轮询 + 全量重建

5.1 机制全貌

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


启动：@PostConstruct loadSensitiveWords()（:48）
 ├── updateAll()：首载词库，建 containDetector + regexDetector
 └── 建 200 线程共享池（queue=10，CallerRunsPolicy 满了自己跑，:51）

运行：@Scheduled(fixedRate = 60_000) checkForUpdates()（:194，每分钟一次）
 └── updateAll() = updateContains() + updateRegex()，各自独立判断：
 ① 变更探测：SELECT ... WHERE match_type IN (...) ORDER BY update_time DESC LIMIT 1
 拿到最新 update_time，与"上次刷新时间"比较，没变 → return（:216-232 / :283-299）
 ② 有变 → 全量分页拉取（id >= startId ORDER BY id ASC LIMIT 5000 循环，:356-363）
 只拉 status=online
 ③ 在局部变量里建全新 wordsMap/Trie/倒排索引
 ④ 整体替换成员变量引用（:321-322 / :267-269），旧对象交给 GC

5.2 设计要点与启示

“先探测、再重建”：每分钟一次的变更探测只是一条 LIMIT 1 的轻查询，没变更时开销忽略不计；有变更才付出全量重建成本。这是轮询系统的标准省流姿势。
无锁热切换：读请求直接读成员变量，更新在后台另起炉灶建完再换引用——靠 JVM 引用赋值的原子性保证读到的是完整快照。没有加 volatile，严格说有可见性瑕疵，工程上可接受。
与 03 篇 api 侧 60s 配置轮询异曲同工：JoySafety 的配置下发哲学统一是"pull + 全量替换”，不依赖推送，admin 挂了执行层照跑。
时延特性：词变更最长约 60s 生效（探测周期）+ 重建耗时。变更探测用 update_time（MySQL 服务器时钟）对比 lastRefreshTime（应用 System.currentTimeMillis()），两台机器时钟有偏移时可能漏判——生产部署注意 NTP 对时。

5.3 ⚠️ 两个真实的坑

清空词库不会生效：updateContains 里 if (newWordsMap.size() != 0) 才替换（:319）——把词全下线后查询结果为空，老 Trie 继续服役。想清空只能重启或留一条废词。
contain 与 regex 的刷新时间戳互相独立（containsLastRefreshTime / regexLastRefreshTime），一类失败不影响另一类，但也意味着两类词库可能短暂不一致。

六、业务链路串联：一个词从录入到拦截的完整旅程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


① admin 写词：POST :8006/data/sensitive_words/upsert（status=online 立即落库）
 │
 ▼ MySQL sensitive_words（update_time 自动刷新）
② keywords 服务 60s 内探测到变更 → 全量重建 Trie + 倒排索引（日志见 "contain数据有更新"）
 │
 ▼
③ safety-api DAG 执行到 keyword 节点 → KeywordFunction.doRun()（safety-api/.../functions/KeywordFunction.java:69）
 │ POST conf.url（注册时配置，演示环境 http://safety-keywords:8005/keyword/query，
 │ 见 example/safety-skills/safety-knowledge/skills_init.py:14）
 │ body: {content, businessName}
 ▼
④ keywords 返回 KVResponse{hitWord, firstClassNo/Name, bwgLabel, latency}
 │
 ▼
⑤ KeywordFunction 包装成 KeywordCheck 结果（riskCode=firstClassNo，:95-103）
 │
 ▼
⑥ DAG groovy 路由裁决（strategy_example.yml:42）：
 if (kw.bwgLabel == 1 || kw.bwgLabel == 2) { ctx.curResult = kw; return null }
 → 黑词直接终结链路返回拦截；白词也终结链路（放行且不送下游 BERT，省钱）
 → 灰词(3)/未命中 → return next，继续走 BERT 等精检

KeywordFunction 还有两个工程细节值得抄作业：

OkHttpClient 全局复用：FunctionResourcePool.getFunc(type, url) 按 url 缓存连接池（:58-65），多个 DAG 节点调同一个 keywords 服务共享连接，配 Keep-Alive timeout=20, max=5000（:82）。
默认超时 200ms（:51），演示环境注册时改成了 1000ms（skills_init.py:10）——与 keywords 服务自己的 150ms 预算形成"外层兜底"。

七、动手实验

前提：按 02 篇部署完成，容器网络内 keywords 可达。根 compose 里 keywords 的 ports 被注释（docker-compose.yaml:145），直连验证用 docker exec 进容器 curl，或解注释后重建容器。

实验 1：加词 → 观察 60s 生效

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# ① 加一条黑词（upsert 即 online）
curl -X POST http://localhost:8006/data/sensitive_words/upsert \
 -H 'Content-Type: application/json' \
 -d '{"businessScene":"all","group":"default","word":"快乐星球","className":"实验",
 "classNo":9999,"matchType":"contain","handleStrategy":"black",
 "source":"manual","status":"online","desc":"06篇实验"}'

# ② 立即直连 keywords 验证（大概率还没生效，返回"正常文本"）
docker exec safety-keywords curl -s -X POST http://localhost:8005/keyword/query \
 -H 'Content-Type: application/json' \
 -d '{"content":"欢迎来到快乐星球","businessName":"test"}'

# ③ 蹲日志看热更新发生（约 60s 内出现"contain数据有更新"）
docker logs -f safety-keywords 2>&1 | grep -E "数据有更新|命中敏感词"

# ④ 再次验证 → hitWord="快乐星球", bwgLabel=1, firstClassNo=9999

实验 2：端到端走 DAG

1
2


docker exec safety-knowledge python /work/api_test.py '欢迎来到快乐星球'
# 预期：riskCode=9999, riskCheckType=keyword, hitWord=快乐星球（与 02 篇案例 2 同构）

实验 3：exclude 豁免与业务场景过滤

1
2
3
4
5
6
7
8


# 给 test 业务对"快乐星球"打孔（同一个词再录一条 exclude，businessScene 换成 test）
curl -X POST http://localhost:8006/data/sensitive_words/upsert \
 -H 'Content-Type: application/json' \
 -d '{"businessScene":"test","group":"default","word":"快乐星球","className":"实验",
 "classNo":9999,"matchType":"contain","handleStrategy":"exclude",
 "source":"manual","status":"online","desc":"豁免实验"}'
# 约 60s 后：businessName=test 的查询不再命中（exclude 排序第一，压制 black）；
# 其他业务仍命中（exclude 那条的 scene 不含它们）

实验 4：压测词库规模 vs 匹配耗时

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# ① 批量造词（1000 条，按需调整上界；admin 单线程插入，耐心等）
for i in $(seq 1 1000); do
 curl -s -X POST http://localhost:8006/data/sensitive_words/upsert \
 -H 'Content-Type: application/json' \
 -d "{\"businessScene\":\"all\",\"group\":\"default\",\"word\":\"压测词$i\",
 \"className\":\"perf\",\"classNo\":0,\"matchType\":\"contain\",
 \"handleStrategy\":\"black\",\"source\":\"perf\",\"status\":\"online\",\"desc\":\"perf\"}" > /dev/null
done

# ② 等一轮热更新（看日志 count 涨到 1000+）
docker logs safety-keywords 2>&1 | grep "分类别获取数据结束"

# ③ 未命中场景压 100 次（AC 一遍扫，开销≈纯扫描）
time for i in $(seq 1 100); do
 docker exec safety-keywords curl -s -X POST http://localhost:8005/keyword/query \
 -H 'Content-Type: application/json' \
 -d '{"content":"一段不含任何敏感词的普通文本","businessName":"test"}' > /dev/null
done

预期观察：词库从 10 涨到 1000、10000，未命中查询的耗时应基本不变（AC 复杂度与词库规模无关，只与建树的内存和文本长有关）——这就是 AC 自动机的价值，可以亲手验证。KVResponse 里的 latency 字段是服务内部耗时，比 curl 总耗时（含 docker exec 开销）更准。

八、速查附录

8.1 关键源码坐标

内容	坐标
HTTP 入口 POST /keyword/query	`safety/safety-skills/safety-keywords/.../contoller/SensitiveWordsController.java:24`
预处理/截断/fail-open	`.../rpc/KeywordApiServiceImpl.java:30`（MAX_LEN :24，截断 :52）
AC 薄封装	`.../service/data/SensitiveWordDetector.java:14`
150ms 预算 / 双任务并行 / black 短路	`.../service/data/SensitiveWordsManageServiceImpl.java:37 / :63-96`
contain 引擎四道过滤	同上 :98-135
正则倒排（构建 / 查询 / 切分）	同上 :205-272 / :137-178 / :274-278
60s 轮询 / 分页全量拉取 / 只取 online	同上 :194 / :356-363（:359）
处置优先级排序器	`.../utils/WordsUtils.java:20-34`
bwgLabel 映射（black1/white2/grey3）	`.../utils/BwgLabelUtils.java:7-25`
api 侧调用方	`safety/safety-api/.../functions/KeywordFunction.java:69`
管理接口	`safety/safety-admin/.../contoller/data/SensitiveWordsController.java:26`（upsert/updateWithId/getById/queryByWord/upgrade/online/offline）

8.2 管理 API（:8006，文档见 safety-admin/docs/api/sensitive_words_api.md）

/data/sensitive_words/upsert（新增/更新）· /queryByWord（模糊查）· /getById · /online /offline（上下线）· /updateWithId · /upgrade

8.3 本篇要点回顾

AC 自动机让匹配耗时与词库规模解耦；正则靠"字面量 token 倒排"避免全量扫描——一个服务里用了两遍倒排/树思想。
black 短路、exclude 豁免、白词跳过下游模型，处置策略是排序器+短路共同实现的。
150ms 预算 + 全程 fail-open：安全组件自我定位为"不能拖累业务"。
60s 轮询 = 轻探测（update_time DESC LIMIT 1）+ 全量重建 + 引用替换，时延上限约一分钟。
用词规范提醒：handle_strategy 用 grey 不是 gray；regex 词必须含字面量片段；exclude 当 handleStrategy 用。

源码分析 on WYF 的技术博客

Higress 02：key-auth 插件原理与代码导读（结合 docker demo 实战）

0. Demo 全景：一条请求的全部旅程

1. Wasm 插件通用运行原理（与 ai-security-guard 相通）

1.1 地基：沙箱、hostcall 与"每线程一个 VM"

1.2 骨架：wrapper 框架与回调注册

1.3 异步模型：ActionPause / Resume，以及 key-auth 的"同步特权"

1.4 部署链路：plugin.wasm 怎么变成生效的插件

2. envoy.yaml：插件是怎么"挂"进请求链路的

2.1 路由层（envoy.yaml:14-25）

2.2 wasm filter 层（envoy.yaml:26-42）——全篇最重要的一段

2.3 大揭秘：_rules_ 就是 WasmPlugin 的 matchRules

2.4 docker-compose 里的两个细节

3. 代码骨架（main.go:35-43）

4. 配置解析：把 envoy.yaml:42 那段 JSON 变成内存结构

4.1 配置结构体（main.go:88-131）

4.2 parseGlobalConfig：校验 + 建索引（main.go:133-204）

4.3 parseOverrideRuleConfig：叠加路由级 allow（main.go:206-225）

5. 核心裁决：onHttpRequestHeaders（main.go:239-327）

第一步：要不要认证？（:249-254）

第二步：取 token（:259-278）

第三步：数量检查（:281-285）

第四步：认证——查表认出"你是谁"（:288-294）

第五步：授权——“你能进这扇门吗”（:299-326）

6. 拒绝响应怎么发（main.go:329-345）

7. 剧本对照表：test.sh ⑤ 个场景 → 代码分支

8. 设计脉络总结

9. 已知小问题（移植自官方，未改动）

附：测试怎么验证这些（main_test.go，580 行）

模型安全检测 04：DAG 编排引擎深入（Function/Router/三层超时）

〇、先建立全局认识：两条链路看 DAG

一、引擎三要素：Function / Router / Node

1.1 三个抽象一句话

1.2 AbstractFunction：模板方法，结果自动归档

1.3 Node.run()：还有一层节点级 reduceScript

1.4 名为 DAG、实为链式逐跳

二、DAG 的构建：配置怎么变成内存里的链

三、Function 类型体系

3.1 注册表：9 种

3.2 HTTP 远程 function 的统一套路

3.3 async：把任意 function 包成异步

四、Router 详解（7 种）

4.1 groovy router：策略逻辑的主战场

4.2 groovy 的两个并发/容错事实（重要）

五、SessionContext（ctx）实战手册

5.1 真实字段清单（SessionContext.java:21-34）

5.2 checkContent 截断：坐标更正

5.3 常用写法（照抄即可）

六、parallel 并行节点：唯一的并行点

6.1 线程池

6.2 doRun：提交 → 逐级超时收取

6.3 归约策略（ParallelConf.ReduceType）

七、三层超时体系（02 篇坑 4 的完整答案）

八、动手实验：复制演示策略改出自定义 DAG

九、文档超前于代码清单（读 ABOUT_DAG.md 必看）

十、源码坐标速查

模型安全检测 05：Free-Taxi 异步检测模式源码走读

〇、一句话认识 free_taxi

一、问题场景与四种 responseMode

1.1 流式检测的矛盾

1.2 四种 responseMode 对比

1.3 入口分派：一个 switch 定生死

二、free_taxi 全景：队列地图与完整时序

2.1 Redis 键地图（先认路再走源码）

2.2 “结果搭便车"完整时序

三、源码走读：投递 → 分发 → 抢占 → 批量识别 → 结果回流

3.1 投递：Redis pipeline 一次写入两个队列

3.2 分发：每个 api 实例一条"拉活"线程

3.3 执行容器：200 线程池 + CallerRunsPolicy

3.4 抢占与滑动窗口批量识别：本篇最核心的一段

3.5 锁实现：setnx+expire，以及它的两个小瑕疵

3.6 结果回流：lpush 会话结果队列

3.7 sync(content=’$’) 收尾：先抢锁等异步结果落盘

3.8 会话历史：多轮检测的上文来源

3.9 识别结果缓存：MD5 内容缓存 15 分钟

四、业务链路：配置怎么流转，请求怎么流转

4.1 配置流（与 03 篇呼应，此处落到 free_taxi 相关项）

4.2 请求流（free_taxi 一条消息的完整旅程）

五、动手实验：模拟 3 轮会话观察便车

六、生产注意点（代价与适用边界）

2.3 大揭秘：`_rules_` 就是 WasmPlugin 的 matchRules

4.2 `parseGlobalConfig`：校验 + 建索引（main.go:133-204）

4.3 `parseOverrideRuleConfig`：叠加路由级 allow（main.go:206-225）

5. 核心裁决：`onHttpRequestHeaders`（main.go:239-327）