架构 on WYF 的技术博客

模型安全检测 03：JoySafety 技术架构与业务模块分析

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

前置阅读：安全编排框架-4（Mac 本地部署实操笔记）——部署视角的容器清单和两个时期划分日期：2026-09-13 素材来源：JoySafety 源码通读（safety/ 目录全模块） 读者定位：已部署成功、想理解"它到底是怎么跑起来的"的读者；后续要写自定义策略、自定义能力的读者

〇、一张图看懂全局

 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


 ┌─────────────────────────────────────────┐
 │ 配置期（写配置） │
 │ quickstart 脚本 / 运维人员 │
 │ │ │
 │ ▼ │
 │ safety-admin (8006, Java/SpringBoot) │
 │ 原子能力/业务/DAG策略/敏感词/知识库 │
 │ │ 写入（版本化状态机） │
 │ ▼ │
 │ MySQL ──────────┐ │
 └──────────────────────┼──────────────────┘
 │ ① api 每 60s HTTP 轮询 admin
 │ 拉取 online 配置（不直连 MySQL！）
┌──────────────────────────────────────────────┼──────────────────┐
│ 执行期（跑审核） ▼ │
│ 业务方 ──HTTP/HMAC-SHA1──► safety-api (8007, Java/SpringBoot) │
│ │ DAG 引擎逐节点执行 │
│ ┌───────────┬─────┴──────┬───────────────┐ │
│ ▼ ▼ ▼ ▼ │
│ safety-keywords safety-bert safety-knowledge (fasttext)│
│ AC自动机敏感词 BERT分类 知识库/RAG代答/多轮 默认未启用 │
│ │ │ │
│ ▼ ▼ │
│ MySQL Vearch向量库 + 本地bge embedding │
│ + OpenAI兼容LLM │
│ Redis: 会话历史 / free_taxi任务队列 / 分布式锁 / 结果缓存 │
└─────────────────────────────────────────────────────────────────┘

三条最重要的架构认知（后面所有细节都围绕这三条）：

admin 不在请求链路上。它只负责"配置期"写库和下发配置，挂了对线上审核零影响。
api 不直连 MySQL。safety-api 通过 HTTP 轮询 admin 的 /config/defense/api/conf 接口拿全量 online 配置（默认 60s 一次），这是"改配置不生效、重启 api 才行"（笔记-4 坑 5）的根因。
skill 服务全部无状态、HTTP 解耦。bert/keywords/knowledge 只是"会干活的工具人"，编排逻辑全在 safety-api 的 DAG 引擎里。

一、模块全景表

模块	语言/框架	角色	一句话职责
safety-basic	纯 Java 库（无 Spring）	核心 jar	DAG 引擎抽象（Function/Router/Node）、会话上下文、签名工具，被 api/admin 依赖
safety-api	Java / Spring Boot 2.0.9	执行层	对外审核接口、DAG 构建与执行、free_taxi 异步任务体系、配置动态加载
safety-admin	Java / Spring Boot + MyBatis	管理层	配置 CRUD + 版本化状态机 + 配置下发 API
safety-keywords	Java / Spring Boot	能力层	敏感词检测（AC 自动机 + 正则倒排加速）
safety-bert	Python / Tornado 多进程	能力层	BERT 分类模型推理（HF transformers）
safety-fasttext	Python / Flask+gunicorn	能力层	FastText 分类（默认不启用，不在根 compose 里）
safety-knowledge	Python / Tornado（20 进程）	能力层	知识库向量检索、RAG 代答、多轮对话检测
safety-demo	Python/Go/Java	示例	三种语言调 Defense API 的签名示例
example/	Python 脚本	初始化	一次性灌演示数据（建向量库→知识入库→注册能力→建业务→配策略）

批注：Java 侧用的是 Spring Boot 2.0.9（2018 年的版本）+ Jedis 2.5.2 + fastjson 混用，技术栈偏老旧，二开时依赖升级是个工程量。Python 侧反而现代：Tornado 多进程、onnxruntime、HF transformers。

二、safety-basic：DAG 引擎的抽象层

包根 com.jd.security.llmsec.core，是整个框架的"定义层"：

子包	关键类	职责
`engine`	`Function` 接口、`AbstractFunction`（模板方法）、`Node`、`Router` 接口	DAG 的三要素抽象
`engine.routers`	7 种 Router 实现	groovy / stupid_end / simple_next / keyword / risk_end / user_end / robot_end
`session`	`SessionContext`、`ResponseMode`、`CheckConf`	一次审核的会话上下文（groovy 脚本里的 `ctx` 就是它）
`check`	`RiskCheckType` 枚举 + 各 `RiskCheckResult` 子类	检测结果类型体系（keyword/single_label_pred/rag_answer/parallel…）
`conf`	`NodeConfig`、`FunctionConfig`、`RouterConfig`	DAG 节点的配置 POJO（YAML 反序列化目标）
`auth`	`AuthRequest.basicCheck()`、`AuthControlConf`	鉴权模型
`util`	`SignUtil`（HMAC-SHA1）、`GroovyHelper`	签名、groovy 引擎工厂

核心抽象就三个：

1
2
3


Function.run(SessionContext) → RiskCheckResult // 干活：调模型/查词库/问知识库
Router.next(SessionContext) → 下一个 Node 或 null（null = 链路结束）
Node = NodeConfig + Function + Router // 节点 = 配置 + 能力 + 路由

关键认知：它名义上叫 DAG，实际是"链式逐跳"。节点之间没有 Edge 实体类——边由 Router 返回的下一个 nodeId 隐式表达；执行就是 while (curNode != null) { curNode.run(ctx); curNode = curNode.next(ctx); }。真正的并行只存在于 parallel 虚拟节点内部（一个节点里并发跑多个 Function 再归约），不存在图上并发分支的汇合调度。理解这点对写策略很重要：分支逻辑全靠 groovy 脚本里的 if-else 返回不同 nodeId。

三、safety-api：请求链路与执行引擎

3.1 入口与处理链

唯一对外接口：DefenseApiV2Controller（safety-api/.../contoller/DefenseApiV2Controller.java:33）

1
2


POST /llmsec/api/defense/v2/{accessKey}
POST /llmsec/api/defenseResult/v2/{accessKey} ← 主动拉异步结果

一次请求的处理链：

1
2
3
4
5


checkParams（参数校验）
 → rateLimited（Guava RateLimiter，按 accessKey+accessTarget 内存级限流）
 → verify（HMAC-SHA1 验签）
 → preProcess（OpenAI 格式解析、7000 字截断）
 → 按 responseMode 分派：sync / free_taxi / http / mq

3.2 鉴权：HMAC-SHA1

签名字符串：accessKey=..&accessTarget=..&requestId=..&timestamp=..&plainText=..，用业务的 secretKey 做 HmacSHA1 → Base64（safety-basic/.../core/util/SignUtil.java:36）
secretKey 存在 admin 的 business_info.secret_key，api 通过配置轮询拿到
timestamp 超过业务配置的 expireSeconds 直接拒绝（防重放）
特赦：accessKey 以 test 开头跳过验签（DefenseApiV2Controller.java:74）——这就是演示业务能免签名调通的原因

3.3 DAG 的构建与执行

构建（FunctionChainBuilderImpl.java:73）：

1
2
3
4
5


YAML 节点数组 → 先建全部 Node → 逐个节点：
 ① FunctionUtil.doMerge() 合并 ref 引用的原子能力模板（map 递归深合并）
 ② 反射实例化 Function（查 FunctionRegistry.FUNC_MAP）
 ③ 按 Router.ROUTER_MAP 反射构造 Router（注入 nodeMap）
→ root 节点存 rootMap，按业务名索引

执行（FunctionExecutorImpl.doExecute():289）：就是从 root 开始的 while 循环逐跳，每轮先检查整体超时，节点异常按 ignoreError 决定抛出或跳过，router 返回 null 即结束。router 脚本通常直接改写 ctx.curResult 后 return null 终结链路。

parallel 并行节点（ParallelFunction.java:41）：

静态线程池：200 线程 / 队列 1 / CallerRunsPolicy（满了让调用线程自己跑，变相背压）
doRun() 把各子 Function submit 后，按各自的 timeoutMilliseconds 逐个 Future.get(timeout) 收取，剩余预算递减——这就是笔记-4 坑 4"两层超时"里第①层的实现位置
归约策略三选一：no_reduce / first_risk / groovy_script（脚本 bindings：ctx/conf/retMap）

3.4 三层超时体系（笔记-4 坑 4 的完整答案）

层	位置	默认值	超时后果
整体 DAG	业务配置的 `userCheckConf/robotCheckConf.timeoutMilliseconds`，主循环每节点前检查	1000ms	抛 exec_timeout
单 Function HTTP	function 配置 `timeoutMilliseconds` → OkHttp callTimeout	注册时定（2000）	该节点结果丢弃
parallel 内部	`Future.get(剩余预算)`	同上	该子项结果丢弃

Mac 上 BERT 推理 ~1.7s（并行争抢 CPU 时 3.3s），三层默认值全部不够——所以坑 4 要同时改两层。

3.5 四种 responseMode 与 free_taxi 详解

模式	行为	适用
`sync`	同步跑完整 DAG 返回结果	输入审核（发出去之前拦）
`free_taxi`	投递异步任务后立即返回该会话之前累积的检测结果（“搭便车”）	流式输出审核（不阻塞 token 输出）
`http`	只投递不返回，客户端调 defenseResult 接口拉结果	异步批量
`mq`	预留，开源版是空实现 stub（`MessageQueueServiceImpl.java:32`）	需自行实现

free_taxi 的完整机制（代码与 docs/ABOUT_FREE_TAXI.md 一致）：

1
2
3
4
5
6
7


1. 投递：lpush 全局任务队列(sessionId) + lpush 该会话新消息队列(请求JSON) [Redis pipeline 原子执行]
2. 分发：单分发线程 rpop 任务队列 → 提交到 200 线程池
3. 抢占：对该 sessionId 抢 Redis 分布式锁（setnx+expire 10s）
 - 抢到：循环批量 rpopN 取新消息（batch=checkNum，即"滑动窗口"）→ 每批跑完整 DAG → 结果 lpush 进会话结果队列
 - 没抢到：直接放弃（等客户端下次请求再触发）→ 天然的多实例互斥
4. 取结果：下一次请求进来时 fetchResult() rpopN 取走之前的结果；
 会话结束发 sync 请求（content='$'）收尾，等 200ms 取全量剩余结果

设计精髓：把"检测"从请求的同步路径上摘掉，用下一次请求顺带带回上一次的检测结果。代价是结果滞后一条消息，靠收尾请求兜底。会话历史同时写 Redis list，供 multi_turn_detect 取上下文。

3.6 配置加载与缓存（坑 5 的完整答案）

1
2
3
4
5
6
7
8


admin 侧：只有调 online/upgrade 接口才更新 lastChangeTimestamp
 │
 │ api 侧 DynamicConfigService：
 │ @PostConstruct 首载 + @Scheduled(fixedRate=60000) 每分钟轮询
 │ /config/defense/api/conf → 按 lastChangeTimestamp 判断变更
 ▼
变更后：全量替换 volatile 配置 Map → 回调 listener 重建所有业务的 DAG
 （重新编译 groovy 脚本、重建 OkHttp client、重新注册 warmup）

所以配置变更最长滞后约 60s；实践中原子能力超时这类变更重建不彻底，需要 docker restart safety-api（笔记-4 坑 5 的经验结论与此机制吻合）。

Redis 在 api 侧的四个用途：会话历史、free_taxi 任务/结果队列、分布式锁、识别结果缓存（user 且单条时按业务+内容MD5 缓存 15 分钟——这就是笔记-4 说"重试要改动一两个字"的原因）。

四、safety-admin：配置中心与版本化状态机

4.1 管理域与接口

管理域	路径前缀	动作
原子能力 function	`/config/defense/manage/function`	new / get / newVersion / update / online / offline / upgrade / active / allActive
业务 business	`/config/defense/manage/business`	同上
DAG 策略	`/config/defense/manage/dag`	同上 + `newDagWithYaml / dagUpdateYaml / activeYaml`（YAML 导入）
配置下发	`/config/defense/api/conf`	给 api 轮询的全量 online 配置
敏感词	`/data/sensitive_words`	upsert / queryByWord / online / offline
红线知识库	`/data/redline_knowledge`	CRUD
平台字典	`/platform/dict`	CRUD

4.2 版本化状态机（所有配置通用）

状态枚举 NormalStatus：init → edit → (audit / rejected 预留未用) → online ⇄ offline

核心规则（FunctionConfigServiceImpl.java 为代表）：

唯一键 (name, group, version)，newVersion 基于当前 online 版本复制、版本号 +1
online 状态的记录禁止 update——只能复制出新版本改，保证线上配置不可变
upgrade = 旧版本置 offline + 新版本置 online，原子切换

这就是笔记-4 附录 C 那条流水线的代码实现：active → newVersion → update → upgrade。

4.3 数据表（6 张，`safety-admin/docs/tables.sql`）

表	要点字段
`function_conf`	conf 为 JSON（url、超时、模型参数都在里面）
`business_info`	`secret_key`、`access_targets`、`qps_limit`、user/robot 检测配置
`execute_dag_conf`	`root_id` + conf JSON 节点数组
`sensitive_words`	`match_type`: contain/equal/regex/compound；`handle_strategy`: black/white/gray/exclude
`red_line_knowledge`	question/answer/metadata
`platform_dict`	字典

每张表都带 version + status + editor/auditor/release 审计字段。

五、safety-skills：四个原子能力服务

5.1 safety-keywords（Java，8005）——敏感词

匹配算法：AC 自动机（org.ahocorasick.trie.Trie），不是 DFA
数据源：MySQL sensitive_words 表（只取 online），每 60s 轮询，先查 max(update_time) 判断有无变更再全量重建
双引擎（线程池并行，150ms 总预算）：
- contain/equal 词 → 直接进 AC Trie；命中后按业务场景过滤、按优先级排序；black 短路返回、exclude 忽略（白名单机制）
- regex 词 → 正则倒排加速：正则按元字符切 token 建 Trie + token→规则倒排索引，query 先 AC 粗筛出候选正则再精匹配，避免全量正则扫文本（这个设计很值得单独写一篇）
all 业务下的敏感词对所有业务生效

5.2 safety-bert（Python/Tornado，8003）

Tornado bind_sockets + multiprocessing 多进程（进程数可配）
模型加载：HuggingFace BertForSequenceClassification.from_pretrained()，CPU/GPU 可配，max_length=512，softmax argmax
接口：POST /v1/bert/{model_name}，body text_list，返回每条 riskCode/probability/全标签分布
模型即配置：每个模型一个目录（config 声明 name/路径/labels 的 riskCode↔风险文案映射），现有三个：
- bert_20250916：14 类内容风险（涉政/暴恐/涉黄/辱骂…）
- bert_prompt_injection_20250828：提示词注入二分类
- bert_prompt_injection_20251118：注入三分类（正常/明确攻击/疑似），红蓝军对抗训练的新版

5.3 safety-knowledge（Python/Tornado，8004，默认 fork 20 进程）——功能最重

路由：/knowledge/upsert|delete|search、/knowledge/answer、/dialog

知识库检索：Vearch Python SDK（连 router :9001）+ 本地 bge-small-zh-v1.5 ONNX 模型生成 512 维向量（onnxruntime CPU，启动预热 10 次）；_id=md5(text)；支持标量 IN 过滤 + min_score 阈值
RAG 代答：检索 Top1 分数 ≥ same_threshold → 直接返回知识库 safeChat 字段；否则拼 prompt（参考答案+输入）调 OpenAI 兼容 LLM API，生成后再用 bge 余弦相似度校验答案与参考知识一致性（阈值 0.7），不一致则答案置空、进 backup——双保险防代答胡说
multi_turn_detect 多轮检测：把 history 拼进审核细则 prompt 发给 LLM，要求返回 {label, reason} JSON，正则抽取解析
依赖：Vearch + OpenAI 兼容 LLM + 本地 ONNX embedding；不依赖 Redis

5.4 safety-fasttext（Flask+gunicorn，8002）

默认不在根 compose 里、初始化脚本也没注册它。定位是"轻量预筛"（对应 ABOUT_DAG.md 纵深防御里的第一层：keyword+fasttext 粗筛 → BERT 精检）。

六、example 初始化脚本：演示环境的装配线

safety-example-init 容器按序执行（对应笔记-4 的启动时序图）：

脚本	动作
`vearch_manage.py`	建库 db0、建 space（HNSW 512 维 InnerProduct 向量索引 + 标量索引），自测 upsert/search
`index_all.py`	直连 MySQL 分批读 `red_line_knowledge` → POST 到 knowledge `/knowledge/upsert` 向量化入库
`skills_init.py`	注册 6 个原子能力（keyword、2 个 bert、kb_search、rag_answer、multi_turn_detect）并 online
`business_init.py`	建 test 业务（secretKey=123456、qpsLimit=20）并 online
`strategy_init.py`	strategy_example.yml → dagUpdateYaml → online

演示 DAG 逐节点解读（strategy_example.yml，纵深防御教科书案例）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


start（dummy 节点，groovy router）
 │ 按 ctx.curReq[0].fromRobot() 分流
 ├─ 机器人输出 → from_robot_test1：keyword → stupid_end（机器人侧只查敏感词）
 └─ 用户输入 → from_user_test1：parallel(keyword)
 │ groovy router：命中黑(bwgLabel=1)直接出风险；命中白(2)直接放行
 ▼
 from_user_test_bert2：parallel(bert_20250916, bert_prompt_injection_20250828)
 │ groovy router：按 riskCode 差异化概率阈值表判定
 │ （如 1003涉黄 0.85、1004涉赌 0.996、201注入 0.99）
 ▼
 都不达标 → MixedCheck.noRisk()

所有节点 ignoreError: true（单个能力挂了不阻断整体）。ABOUT_DAG.md 里还有更进阶的打法：parallel(rag_answer + bert) 红线代答与模型双证（riskCode 一致且概率 > 0.5 才判风险，防误杀）。

七、值得学习的设计点 vs 开源版的坑（博客素材库）

7.1 设计亮点

编排与能力彻底分离：skill 服务无状态、HTTP 解耦，新增能力 = 起一个服务 + admin 注册 + DAG 引用，不动一行 Java 代码
配置版本化 + 不可变线上配置：online 禁改、upgrade 原子切换，天然支持灰度回滚（AB 机制还能按 dagVersion 指定版本实时构建）
free_taxi 模式：把检测从流式输出的同步路径上摘掉，业界少见的工程化解法
纵深防御策略：词库粗筛 → 轻模型 → 重模型 → 知识库双证，每层都有成本和准确率权衡
groovy 脚本做 router：策略逻辑不用发版就能改（虽然要重启 api 才彻底生效）
正则倒排加速、RAG 代答一致性校验：细节处的工程功底

7.2 开源版的坑 / 局限

mq responseMode 是空 stub，要用得自己实现 MessageQueueService
文档超前于代码：ABOUT_DAG.md 里 executedNodes/nodeCosts 等 ctx 字段实际不存在
MySQL/Redis/Vearch 全都没挂数据卷（笔记-4 已踩：docker compose down 即丢全部配置）
DAG 热更新不彻底：60s 轮询 + 部分变更需重启 api，离 README 宣称的"分钟级热更新"有差距
groovy eval 全局 synchronized：ScriptEngine 非线程安全，所有脚本串行执行，高并发下是瓶颈
技术栈老旧：Spring Boot 2.0.9 / Jedis 2.5.2 / fastjson 1.x 2.x 混用
“DAG” 实为链式逐跳：没有真正的图拓扑调度，并行只在 parallel 节点内部
fasttext 默认缺席：README 能力清单里有，compose 和初始化脚本都没有

八、关键源码坐标速查

主题	位置
DAG 主执行循环	`safety/safety-api/src/main/java/com/jd/security/llmsec/engine/FunctionExecutorImpl.java:289`
并行节点	`safety/safety-api/.../engine/functions/ParallelFunction.java:41`
Function 注册表	`safety/safety-api/.../engine/FunctionRegistry.java:20`
groovy router	`safety/safety-basic/.../core/engine/routers/GroovyRouter.java:27`
SessionContext（ctx 结构）	`safety/safety-basic/.../core/session/SessionContext.java:21`
审核入口	`safety/safety-api/.../contoller/DefenseApiV2Controller.java:33`
HMAC-SHA1	`safety/safety-basic/.../core/util/SignUtil.java:36`
free_taxi 任务执行	`safety/safety-api/.../task/TaskExecutorImpl.java:78`
配置轮询	`safety/safety-api/.../service/DynamicConfigService.java:45`
版本化状态机	`safety/safety-admin/.../service/business/FunctionConfigServiceImpl.java:236`
AC 自动机敏感词	`safety/safety-skills/safety-keywords/.../service/data/SensitiveWordDetector.java`
建表 SQL	`safety/safety-admin/docs/tables.sql`
演示策略	`docs/strategy_example.yml`

注：Java 源码里 controller 目录拼写为 contoller（原仓库笔误），检索时注意。

模型安全检测 12：三层防护体系串联（网关 × 脱敏 × JoySafety）

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

状态：✅ 已完成 前置阅读：01~11 全部（尤其 03 架构分析），以及 maas-safe-doc 仓库的三篇网关侧笔记： ../../maas-safe-doc/安全护栏/poc/网关安全插件-1-基础功能验证.md、 网关安全插件-2-高级能力验证以及存在的问题分析.md、 网关脱敏插件实现原理分析-ai-data-masking-脱敏与还原.md 日期：2026-09-14 素材来源：JoySafety 源码核实（路径均逐一 Read/Grep 验证）+ Higress 插件侧引用自上述脱敏原理笔记 读者定位：要把"网关插件 / 脱敏插件 / JoySafety"三条线组装成一套生产方案的读者。本篇以架构图和决策表为主，源码坐标用于支撑每个机制结论

〇、一句话总览

网关插件管"流量"，脱敏插件管"数据"，JoySafety 管"内容"。

1
2
3
4
5
6
7
8
9


 流量层 数据层 内容层
┌──────────────┐ ┌──────────────────┐ ┌──────────────────────────┐
│ 网关安全插件 │ │ ai-data-masking │ │ JoySafety │
│ WAF/IP名单/ │ │ 敏感词拦截 │ │ 敏感词/BERT/知识库/多轮 │
│ QPS/TPM 限流 │ │ PII 脱敏与还原 │ │ DAG 编排 + free_taxi │
│ "谁来、来多少" │ │ "数据出不出域" │ │ "内容合不合规" │
└──────────────┘ └──────────────────┘ └──────────────────────────┘
 微秒~毫秒级 毫秒级（WASM 本地） 毫秒~秒级（模型推理）
 规则匹配 分词+正则 语义理解

类比：机场安检——网关是入口闸机（验票、限流、黑名单），脱敏是行李打包（贵重物品封存、凭条可取回），JoySafety 是安检仪+人工复检（X 光粗筛、开包精检、专家会诊）。

一、三层各自的定位

1.1 定位对照表

维度	网关安全插件（Higress）	脱敏插件（ai-data-masking）	JoySafety
防护对象	流量入口	敏感数据（PII/密钥）	内容语义风险
核心问题	谁来访问、来多少、是不是 Web 攻击	数据出不出域、能不能还原	文本合不合规、有没有注入
技术形态	Envoy/Higress 插件（WAF=ModSecurity+CRS）	Rust 编译 WASM，网关内嵌运行	独立部署的 Java/Python 微服务集群
检测手段	规则匹配（CRS 规则集、IP 名单、计数器）	结巴分词+HashSet、Grok/正则、HMAC-SHA256	AC 自动机、BERT 分类、向量检索、LLM 多轮
单次开销	微秒~毫秒	毫秒（本地 WASM，无网络调用）	词库 ~40ms，BERT 生产 ~200ms（见 02 篇实测）
策略载体	网关控制台 YAML	同左（`replace_roles`/`system_deny`）	MySQL 版本化配置 + DAG YAML
拦截粒度	请求级（403/429）	词级（替换）或请求级（deny）	词/句/会话级，riskCode 细分 14+ 类
失败倾向	拒绝服务（fail-close 基因）	可配（deny/replace 两档）	`ignoreError` 可配，默认容错（fail-open 基因）

1.2 为什么需要三层而不是一层

三道防线对应三种成本—能力曲线，缺一不可：

网关层最便宜也最快，但只能做模式匹配。SQL 注入、XSS、IP 封禁、QPS/TPM 限流在这里拦，一次拦截成本几乎为零——POC 验证 6 项 WAF 用例全部 403 拦截（网关安全插件-1，TC01~TC04）。
脱敏层解决的是"内容合规管不了"的问题。JoySafety 没有脱敏替换能力（网关安全插件-2 第 4.2 节实测确认：“缺少 Higress 脱敏插件的脱敏替换功能”），身份证/手机号/API Key 必须在出域前由脱敏插件替换或哈希。脱敏插件源码证实其三档机制：DenyWord（结巴分词+HashSet 拦截，deny_word.rs:63-70）、replace（正则替换为固定值）、hash（HMAC-SHA256 可逆脱敏，ai_data_masking.rs:431-486）。
JoySafety 解决的是"规则看不懂"的问题。变体辱骂、暗示性暴恐、祖母漏洞式提示词注入，规则引擎无解，必须上模型和知识库。02 篇实测：BERT 对"哪里有卖枪支的"判 riskCode=1002（置信度 0.9989），对祖母漏洞判 riskCode=201（置信度 0.994）——这两类网关层完全拦不住。

1.3 各层在本系列/姊妹篇中的出处

层	深入笔记
网关插件	网关安全插件-1（基础功能 POC）、-2（高级能力与问题分析）
脱敏插件	网关脱敏插件实现原理分析（Rust/WASM 源码级）
JoySafety	本系列 03（架构）、04（DAG）、05（free_taxi）、06（敏感词）、07（知识库）、08（注入攻防）

二、完整请求链路设计

2.1 全链路时序图

一条 LLM 对话请求穿过三层防线的完整旅程（入向审核采用 JoySafety sync 模式，在调用模型之前拦；出向采用 free_taxi 模式，不阻塞流式输出）：

 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


客户端 网关插件层 脱敏插件 JoySafety LLM
 │ ①POST /v1/chat/completions │ │ │
 ├────────────────►│ WAF(CRS规则) │ │ │
 │ │ IP黑名单 │ │ │
 │ │ QPS/TPM限流 │ │ │
 │ │ ──拦截→403/429 │ │ │
 │ ├────────────────►│ ②请求侧脱敏 │ │
 │ │ │ jieba+HashSet拦截 │ │
 │ │ │ ──命中→deny_message │ │
 │ │ │ Grok/正则替换PII │ │
 │ │ │ sk-* → hash(存map) │ │
 │ │ ├────────────────────►│ ③输入审核 sync │
 │ │ │ │ 鉴权HMAC-SHA1 │
 │ │ │ │ DAG: keyword→BERT 并行 │
 │ │ │ │ ──命中→riskCode≠0 拦截 │
 │ │ │ ├─────────────────────────►│
 │ │ │ │ │ ④推理
 │ │ │ │ │ ⑤SSE 流式输出
 │ │ │ │◄─────chunk 累积投递──────┤
 │ │ │ │ ⑥free_taxi 异步检测 │
 │ │ │ │ (不占输出路径，结果搭 │
 │ │ │ │ 下次请求便车带回) │
 │ │ │ ⑦响应侧 │ │
 │ │ │ 流式敏感词检测 │ │
 │ │ │ mask_map 还原hash │ │
 │ ⑧SSE 透传给客户端 │ │ │
 │◄────────────────┴──────────────────┤ │ │
 │ 会话结束发 sync(content='$') 收尾，取走剩余检测结果 │ │

设计说明（与提纲出入处）：提纲原文把"JoySafety 输入审核"放在 LLM 之后。实际方案将其放在 LLM 之前——输入审核的意义就是在token消耗发生前拦截（命中即不再调模型，省钱省延迟），这与 JoySafety sync 模式的定位一致：“同步跑完整 DAG 返回结果，适用输入审核（发出去之前拦）"（03 篇 3.5 节）。提纲中的顺序在"先过模型再回头审输入"的反模式里没有意义，本篇以实际代码语义为准做了修正。

2.2 JoySafety 侧的两个视角回顾（详见 03 篇）

配置流转（配置期）：

1
2
3
4
5
6
7
8
9


运维/admin 控制台 ──► safety-admin(8006) ──写入──► MySQL（版本化状态机：init→edit→online⇄offline）
 │
safety-api 每 60s HTTP 轮询 /config/defense/api/conf ◄─────┘（不直连 MySQL！）
 DynamicConfigService.loadConf() @Scheduled(fixedRate=60000)
 （safety-api/.../service/DynamicConfigService.java:65）
 │ 按 lastChangeTimestamp 判断有无变更（同文件 :142-144）
 │ 无变更 → "配置无变更" 直接返回（:73-76）
 ▼ 有变更
全量替换 volatile Map（:96-97）→ 回调 listener 重建所有业务 DAG（:106-110）

请求流转（执行期），入口 DefenseApiV2Controller（safety/safety-api/src/main/java/com/jd/security/llmsec/contoller/DefenseApiV2Controller.java:31-33）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// DefenseApiV2Controller.java，处理链关键节点（行号为实测）
checkParams(request); // :46 参数校验
defenseService.rateLimited(request)// :59 Guava RateLimiter 内存级限流（按 accessKey）
if (!accessKey.startsWith("test")) // :74 test 开头特赦
 defenseService.verify(request);// :75 HMAC-SHA1 验签（SignUtil.java:36 拼串、:62 加密）
defenseService.preProcess(request);// :78 OpenAI 格式解析 + 7000 字截断（GlobalConf.java:49）
switch (mode) { // :97 按 responseMode 分派
 case sync: process(request); // :100 同步跑 DAG
 case free_taxi: submit(request); // :107 只投递
 fetchResult(...); // :108 顺带取回历史结果

随后进入 DAG 主循环 FunctionExecutorImpl.doExecute()（FunctionExecutorImpl.java:289）——while (curNode != null) 逐跳执行，每轮先查整体超时（:297-299），节点异常按 ignoreError 决定抛出还是跳过（:312-323），router 返回 null 即终结。

2.3 出向为什么必须是 free_taxi

流式输出场景，同步检测意味着"攒完整段再返回”，首 token 延迟直接报废。JoySafety 的解法是 free_taxi（03 篇 3.5 节、TaskExecutorImpl.java:78）：

请求侧只做 submit（Redis lpush 投递）立即返回，检测从同步路径上摘掉；
200 线程池消费（TaskExecutorImpl.java:56-63），按 sessionId 抢 Redis 分布式锁（storageService.lock，:88，锁 10 秒，:75）实现多实例互斥；
检测结果 lpush 进会话结果队列，下一次请求搭便车带回（DefenseApiV2Controller.java:108）；
会话结束发 sync 请求（content='$'）收尾取全量。

代价是结果滞后一条消息，且跨 chunk 的 unsafe 内容识别能力有限（网关安全插件-2 第 4.1 节明确指出该短板，并建议与脱敏插件的滑动窗口机制结合）——这正是三层互补的典型场景：出向的实时底线由脱敏插件的流式敏感词检测（MsgWindow 累积缓冲区检测）兜住，深度语义检测由 free_taxi 异步补齐。

三、职责边界与不重复建设

3.1 放哪层的决策表

检测项	放哪层	理由（成本/准确率/延迟权衡）
SQL 注入/XSS/路径穿越/命令注入	网关 WAF	CRS 规则成熟、微秒级、与 LLM 语义无关。POC 实测 5 类攻击全部 403
Content-Type 校验、空 UA	网关/前置 Nginx	纯协议层检查，不重复建设（POC 明确"不在 WAF 层重复配置"）
IP 黑白名单	网关	连接级信息，越靠前越省资源。注意 POC 发现黑白名单互斥、白名单≠跳过审核
租户 QPS/TPM 限流	网关	需要全局计数（Redis 集群级限流插件），JoySafety 的 RateLimiter 是单实例内存级（03 篇 3.1），只作兜底
PII（身份证/手机/邮箱/IP）脱敏	脱敏插件	JoySafety 无替换能力；正则微秒级，放模型层是纯浪费
API Key/密钥出域	脱敏插件（hash+restore）	可逆需求只有 mask_map 机制能满足
粗粒度敏感词（涉政/赌博黑词）	两层都放（见 3.2）	网关侧拦截成本≈0 先挡一波；JoySafety 词库做黑白灰精细化管理
变体辱骂/暗示性违规	JoySafety BERT	语义问题，规则无解
提示词注入（祖母漏洞等）	JoySafety 注入模型	需要红蓝军对抗训练的专门模型（08 篇）
红线问题代答	JoySafety RAG	需要知识库+一致性校验双保险（07 篇）
多轮上下文风险	JoySafety multi_turn_detect	需要会话历史（Redis），网关无状态做不了
业务级 HMAC 鉴权	JoySafety（审核接口）	网关管租户身份，JoySafety 管业务 accessKey/secretKey，各管一段

3.2 重叠能力的分工：敏感词两层都放，但不重复

三层在"敏感词"上有能力重叠（网关安全插件-2 第五章有完整对比表），分工原则是网关挡子弹、JoySafety 做手术：

维度	脱敏插件内置词库	JoySafety 敏感词服务
匹配方式	结巴分词+HashSet，contains	AC 自动机（`SensitiveWordDetector.java:14-15`，ahocorasick Trie），支持 contain/equal/regex/compound 四种（`safety-admin/docs/tables.sql:9`）
处置策略	拦截（deny）或替换（replace/hash）	黑白灰名单+exclude（`tables.sql:10`），白名单命中直接放行短路
词库运营	静态内置+配置自定义	MySQL 持久化，admin 动态增删，keywords 服务定时轮询重建（`SensitiveWordsManageServiceImpl.java:194` `@Scheduled`）
定位	出域底线（数据不走）	内容风控（语义判定）

实操建议：网关侧只放零容忍、无歧义的短词黑名单（错了代价高的放这里，fail-close）；JoySafety 侧放全量词库+黑白灰策略，承接需要场景过滤、优先级排序的精细判定（06 篇）。

3.3 脱敏与内容审核的数据流衔接

关键决策：先脱敏还是先审核？ 推荐顺序"脱敏请求侧 → JoySafety 输入审核"（即 2.1 图的顺序），理由与代价：

✅ PII 不进 JoySafety 的日志/会话历史/结果缓存——JoySafety 会把会话历史写 Redis、按内容 MD5 缓存结果 15 分钟（03 篇 3.6），明文手机号进去就是二次泄露面；
⚠️ 代价：审核看到的是脱敏后文本（手机号→*****），对"报出自己手机号求回拨"这类语义判定有轻微影响。可接受——PII 本身不是内容风险，语义审核本来就不需要知道号码是多少；
❌ 反序（先审后脱敏）的问题：审核链路成为明文 PII 的新出口，且脱敏替换可能把黑词切成两段逃逸审核（如正则替换恰好切分敏感词），必须在审核之前完成文本改写。

出向衔接：JoySafety free_taxi 检测的是脱敏态的输出流（hash 串不影响语义判定），脱敏插件在最后一个环节做 mask_map 还原——还原发生在审核之后，审核结果不受还原影响。

四、每层故障的兜底策略

4.1 fail-open vs fail-close 决策表

故障场景	默认行为	建议取向	理由
网关 WAF/限流插件异常	网关层故障通常表现为整个入口不可用	fail-close	入口挂了等于服务下线，不存在"放过去"选项；重点是多副本+健康检查
脱敏插件异常（WASM panic/配置错误）	请求中断	fail-close	它的职责是"数据不出域"，放行=明文 PII 直送外部 LLM，宁可误伤不可泄露
JoySafety 单 skill 挂（bert/keywords/knowledge）	fail-open：DAG 节点 `ignoreError: true` 时异常被吞掉继续走（`FunctionExecutorImpl.java:319-323`），演示策略全部节点都是 `ignoreError: true`（`docs/strategy_example.yml:23,65,107,114`）	看节点角色	词库节点挂了fail-open可接受（后面还有模型）；最后一道模型节点挂了必须告警，否则等于裸奔
JoySafety 单 skill 慢（超时）	fail-open：parallel 内 `Future.get(curTimeout)` 超时丢弃该子项结果（`ParallelFunction.java:130-136`）	fail-open + 阈值监控	02 篇坑 4 的教训：超时丢弃是静默的，必须靠耗时分布监控发现（该拦没拦且耗时诡异停在 2s 就是信号）
JoySafety 整体挂（api 不可达）	业务方调审核接口失败	建议 fail-close，配额降级	输入审核 fail-close 拦不了就拒答；出向 free_taxi 本来就是异步，api 挂了影响的是检测结果回流，可短窗 fail-open
admin 挂了	天然 fail-open：admin 不在请求链路上，api 靠内存缓存继续跑（03 篇认知 1）	fail-open（架构自带）	只是不能再改配置；且 `shouldUpdate` 有保底：拉取失败/配置为空时保留旧配置不丢（`DynamicConfigService.java:116-119` 注释"防止出现异常时丢失配置"）
MySQL/Redis/Vearch 挂	api 不直连 MySQL 无影响；Redis 挂=free_taxi/会话历史/结果缓存全瘫；Vearch 挂=知识库能力瘫	Redis 必须高可用	开源版全部没挂数据卷（03 篇 7.2 坑 3），`docker compose down` 即丢全部配置——生产化第一项改造（11 篇）

4.2 兜底策略的三条元规则

数据类故障（脱敏、密钥）一律 fail-close，内容类故障可按业务容忍度选 fail-open——泄露不可逆，误拦可申诉。
fail-open 必须配监控，否则就是"静默裸奔"。JoySafety 的失败全部是静默的：超时丢结果（ParallelFunction.java:132-135 只打 error 日志+计数）、异常忽略（FunctionExecutorImpl.java:320 同样只打日志）。好在框架内置了 MonitorAlarmService 计数（如 parallelIncr、functionIncr、apiPlanIncr），把这些计数接入告警是生产化的必修课。
降级不等于关闭：JoySafety 挂了可以临时降级为"只过网关词库"（网关侧词表保持一份最小黑名单的意义就在这里）；脱敏挂了没有降级方案，只能拒答——所以脱敏插件的规则集要刻意保持小而稳。

五、统一审计与运营

5.1 三层日志汇集

三层各有一套"拦截证据"，格式完全不同，统一审计的第一步是用 requestId 贯穿：

层	拦截证据	关键字段
网关	WAF 审计日志、限流 429 日志	命中规则 id（如 CRS 942/930）、租户、IP
脱敏	网关日志中的 deny_message 返回、替换计数	命中词/规则、是否 restore
JoySafety	审核响应 + `MonitorAlarmService` 计数	`riskCode`（1002 暴恐/1006 辱骂/201 注入…）、`riskCheckType`（keyword/single_label_pred/rag_answer）、`hitWord`、置信度（02 篇实测响应样例）

落地方案：网关和脱敏在入口生成/透传 X-Request-Id，JoySafety 请求体自带 requestId 且参与 HMAC 签名（SignUtil.java:45），三层日志按 requestId join 进同一个 OLAP/ES 索引。

5.2 拦截事件归因

收到一条拦截告警后的归因决策树：

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


拦截事件
 ├─ 状态码 403 + WAF 规则 id？ → 网关层，查 CRS/自定义规则误报率
 ├─ 状态码 429？ → 网关限流，查租户配额是否该扩
 ├─ 返回体是 deny_message？ → 脱敏层词库命中（注意：可能是 PII 规则误伤正常数字串）
 ├─ code=0 且 riskCode≠0？
 │ ├─ riskCheckType=keyword → JoySafety 词库，看 bwgLabel（1黑/2白/3灰）与 hitWord
 │ ├─ riskCheckType=single_label_pred → BERT，看置信度是否贴着阈值线（阈值表见
 │ │ docs/strategy_example.yml:94-95，如 1003涉黄 0.85、1004涉赌 0.996）
 │ └─ riskCheckType=rag_answer/… → 知识库代答/多轮，查知识命中分数
 └─ "该拦没拦"（漏报）？
 ├─ 耗时诡异停在超时值附近 → 超时丢结果（02 篇坑 4，ParallelFunction.java:130）
 └─ 跨 chunk 内容逃逸 → free_taxi/滑动窗口的固有边界（网关安全插件-2 第 3.2/4.1 节）

5.3 策略分层维护节奏

层	策略载体	变更方式	建议节奏	生效延迟
网关 WAF	控制台 YAML	先 `DetectionOnly` 观察 1-3 天再切 `On`（POC 建议）	月级/随 CRS 升级	秒级
网关限流	控制台 YAML	直接改	随业务活动（大促前压测调整）	秒级
脱敏规则	控制台 YAML	新增规则先小流量灰度；规则集刻意保持小（4.2 条 3）	季度级，谨慎	秒级
JoySafety 词库	MySQL（admin API）	upsert→online，走黑白灰策略	周级/舆情驱动	~60s（keywords 轮询，`SensitiveWordsManageServiceImpl.java:194`）
JoySafety DAG/能力	MySQL 版本化状态机	active→newVersion→update→upgrade（03 篇 4.2，online 禁原地改）	按需，灰度可用 AB 按 dagVersion 指定版本	最长 ~60s（api 轮询，`DynamicConfigService.java:65`；原子能力类变更实践上需重启 api，02 篇坑 5）
JoySafety 模型	HuggingFace 模型目录	换模型目录+重建容器	跟随官方模型迭代（如注入模型二分类→三分类）	重启级

六、系列总结与展望

6.1 12 篇知识地图回顾

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


入门篇 01 功能验证 ──────── 跑通四个官方案例，建立"它能干什么"的直觉
 02 Mac 本地部署 ──── 跑起来 + 6 个踩坑（Rosetta/超时/缓存），故障决策树
架构篇 03 技术架构分析 ──── 配置期/执行期分离、admin 不在链路上、api 不直连 MySQL
 04 DAG 编排引擎 ──── Function/Router/Node 三要素，名义 DAG 实为链式逐跳
 05 FreeTaxi 模式 ─── 流式场景的工程化解法：Redis 队列+会话锁+结果搭便车
能力篇 06 敏感词服务 ────── AC 自动机+正则倒排，黑白灰四策略
 07 知识库与 RAG ──── Vearch+bge，代答一致性校验双保险
 08 提示词注入 ────── 二分类→三分类，红蓝军对抗
实战篇 09 自定义原子能力 ── 起服务→注册→DAG 引用，不改一行 Java
 10 业务接入全流程 ── accessKey/secretKey/HMAC-SHA1/QPS
生产篇 11 生产化改造清单 ── 数据卷、mq stub 补实现、热更新、监控
 12 三层防护体系串联（本篇）── JoySafety×网关×脱敏 组装成方案
番外篇 13 方案横评 / 14 模型横评 / 15 红队评测（待写）

一句话收束整个系列：JoySafety 的内核是"配置版本化 + DAG 编排 + 无状态 skill"三板斧，把它放进三层防护体系里，它负责的是最需要智能、也最贵的那一段。

6.2 官方 roadmap 展望（README.md:346-353 “📅计划” 一节，原文摘录转述）

方向	官方表述要点	对三层体系的意义
安全审核大模型	HuggingFace 已开源部分模型 `JSL-joysafety-v1`（README.md:349），后续 JoySafety 集成该系列实现大模型风险合规审计	内容层从"BERT 小模型分类"升级到"审核专用大模型"，语义判定能力质变；对网关/脱敏层无影响，接口层不变
大模型安全评测	覆盖《生成式人工智能服务安全基本要求》5 大类 31 小类风险类型（README.md:351）	给三层体系提供量化验收标准——每层拦哪几小类、漏哪几小类，可以按国标口径出报告（本系列 15 篇红队评测的对接点）
Agent 安全防护	身份与权限管理、数据与记忆防护、工具与执行安全、MCP 代码安全检测、供应链与协议安全（README.md:353）	三层体系的前瞻缺口：Agent 场景下"工具调用参数"和"MCP 协议"既不是纯流量也不是纯文本内容，现有三层都罩不全，是下一个架构演进点

6.3 留给实践的开放问题

free_taxi 的跨 chunk 漏检与脱敏插件滑动窗口如何组合（网关安全插件-2 第 4.1 节的方向），需要一次联合实验；
脱敏插件流式响应"拦截后 finish 时吐出剩余内容"的疑似 Bug（网关安全插件-2 第 3.1 节）需要上游修复或规避，出向兜底策略据此调整；
Agent 安全防护落地时，三层模型的"流量/数据/内容"划分需要扩展第四层"行为/工具"——这是官方 roadmap 给出明确信号、但开源代码尚未覆盖的领域。

附：本篇引用的源码坐标汇总

机制	位置
审核入口/限流/验签/模式分派	`safety/safety-api/src/main/java/com/jd/security/llmsec/contoller/DefenseApiV2Controller.java:31-120`
HMAC-SHA1 签名	`safety/safety-basic/src/main/java/com/jd/security/llmsec/core/util/SignUtil.java:36,62`
Guava RateLimiter 内存级限流	`safety/safety-api/.../service/RateLimitServiceImpl.java:7,30,69`
识别结果缓存 15 分钟（user 且单条）	`safety/safety-api/.../service/execute/FunctionExecutorImpl.java:247,253-254,275-287`
配置 60s 轮询/变更判断/保底不丢配置	`safety/safety-api/.../service/DynamicConfigService.java:65,142-144,116-119`
DAG 主循环/超时检查/ignoreError	`safety/safety-api/.../service/execute/FunctionExecutorImpl.java:289,297-299,312-323`
parallel 超时丢弃/线程池/归约	`safety/safety-api/.../service/execute/functions/ParallelFunction.java:87-92,130-136,142-172`
free_taxi 任务执行/会话锁	`safety/safety-api/.../service/task/TaskExecutorImpl.java:56-63,78-110`
AC 自动机敏感词	`safety/safety-skills/safety-keywords/.../service/data/SensitiveWordDetector.java:14-15`
敏感词定时轮询重建	`safety/safety-skills/safety-keywords/.../service/data/SensitiveWordsManageServiceImpl.java:194`
四种 match_type/黑白灰策略/QPS 字段	`safety/safety-admin/docs/tables.sql:9,10,41`
7000 字截断	`safety/safety-api/.../config/GlobalConf.java:49`
演示 DAG（阈值表/ignoreError）	`docs/strategy_example.yml:23,65,94-95,107,114`
官方 roadmap	`README.md:346-353`
脱敏插件机制（Rust/WASM，源码不在本仓库）	引自 `../../maas-safe-doc/安全护栏/poc/网关脱敏插件实现原理分析-ai-data-masking-脱敏与还原.md`（其中 `ai_data_masking.rs:431-486`、`deny_word.rs:63-70` 等坐标为该笔记核实结果）
网关插件能力与问题清单	引自 `../../maas-safe-doc/安全护栏/poc/网关安全插件-1-基础功能验证.md`、`-2-高级能力验证以及存在的问题分析.md`