1
2
3
4
5
6
7
8
9

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

 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='$') 收尾，取走剩余检测结果        │                          │

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）

 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 顺带取回历史结果

 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 节）

 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 红队评测（待写）