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) ──┘

1
2
3
4
5
6
7
8
9

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

 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);   // 一遍扫描，返回全部命中（含重叠）
}

 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

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）

 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）

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());

 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

 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 等精检

 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

1
2

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

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 不含它们）

 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