---
title: "Easysearch 规则引擎详解"
date: 2026-01-30
lastmod: 2026-01-30
description: "深度解析 Easysearch 规则引擎架构与实现原理，介绍核心组件、规则定义语法、编译流程、多节点同步机制，详细讲解 AC 自动机高性能匹配算法、ThreadLocal 优化、Ingest Pipeline 集成等性能优化方案，适用于内容安全审核、舆情分析、数据分类等实际应用场景。"
tags: ["规则引擎", "Ingest Pipeline", "内容安全"]
summary: "概述 #  Easysearch 规则引擎是一个高性能的文本规则匹配系统，通过 Ingest Pipeline 集成，可以对文档进行实时规则匹配和标签标注。它支持复杂的规则表达式语法，使用 AC 自动机算法实现高效匹配，并支持多节点集群环境下的规则同步。
核心架构 #  规则引擎采用插件化架构，主要组件包括：
 规则编译服务：将规则文本编译为高效的数据结构 索引管理服务：管理规则库的元数据和状态 同步服务：负责多节点集群间的规则同步 Ingest处理器：在文档流入时执行规则匹配 数据库访问层：提供底层规则库的访问接口  规则定义 #  规则以文本形式存储，每行一条规则，格式为：
规则表达式<TAB>#序号#标签描述 规则表达式支持以下语法：
   类型 示例 说明     简单 OR 中国 or 人民 匹配任一关键词   简单 AND 中国 and 人民 同时匹配两个关键词   字段限定 title(中国) and content(发展) 限定字段匹配   正则表达式 [{{[0-9]{4}}} . "-" . {{[0-9]{2}}}] 日期格式匹配   邻近查询 商品 near/3 (手机 or 笔记本) 词间距离限制   手机号匹配 [(1[3-9][0-9]{9})] 正则匹配手机号    规则示例："
---


## 概述

Easysearch 规则引擎是一个高性能的文本规则匹配系统，通过 Ingest Pipeline 集成，可以对文档进行实时规则匹配和标签标注。它支持复杂的规则表达式语法，使用 AC 自动机算法实现高效匹配，并支持多节点集群环境下的规则同步。

## 核心架构

规则引擎采用插件化架构，主要组件包括：

- **规则编译服务**：将规则文本编译为高效的数据结构
- **索引管理服务**：管理规则库的元数据和状态
- **同步服务**：负责多节点集群间的规则同步
- **Ingest处理器**：在文档流入时执行规则匹配
- **数据库访问层**：提供底层规则库的访问接口

## 规则定义

规则以文本形式存储，每行一条规则，格式为：

```plain
规则表达式<TAB>#序号#标签描述
```

**规则表达式支持以下语法**：

| 类型       | 示例                                  | 说明               |
| ---------- | ------------------------------------- | ------------------ |
| 简单 OR    | `中国 or 人民`                        | 匹配任一关键词     |
| 简单 AND   | `中国 and 人民`                       | 同时匹配两个关键词 |
| 字段限定   | `title(中国) and content(发展)`       | 限定字段匹配       |
| 正则表达式 | `[{{[0-9]{4}}} . "-" . {{[0-9]{2}}}]` | 日期格式匹配       |
| 邻近查询   | `商品 near/3 (手机 or 笔记本)`        | 词间距离限制       |
| 手机号匹配 | `[(1[3-9][0-9]{9})]`                  | 正则匹配手机号     |

**规则示例**：

```latex
枪 or 手枪 or 步枪 or 猎枪	gun_weapon
(枪 or 手枪 or 步枪) and (出售 or 销售 or 买卖 or 交易)	gun_trade
(枪 or 手枪 or 步枪) near/10 [{{(1[3-9][0-9]{9})|(8[0-9]{10})}}]	gun_trade_contact
```

## 规则存储

规则在 Easysearch 中的存储分为两层：

1. **规则索引** (`.match_rules`)：存储规则元数据和源文本
2. **编译产物**：存储编译后的规则数据库文件

规则库文档包含以下字段：

| 字段             | 说明                                      |
| ---------------- | ----------------------------------------- |
| `name`           | 规则库名称                                |
| `description`    | 规则库描述                                |
| `tags`           | 规则库标签                                |
| `rules`          | 规则文本（多行）                          |
| `status`         | 编译状态：pending/compiled/partial/failed |
| `total_rules`    | 规则总数                                  |
| `fields`         | 声明的匹配字段                            |
| `composite`      | 复合字段                                  |
| `compiled_nodes` | 已编译的节点列表                          |

## 编译流程

规则使用前需要先编译为高效的数据结构：

```http
# 1. 导入规则到索引
POST /_match_rules/{repo_id}/_import
{
  "name": "安全事件规则库",
  "description": "涉枪、涉毒、涉恐检测规则",
  "rules": ["枪 or 手枪 or 步枪"]
}

# 2. 编译规则
POST /_match_rules/{repo_id}/_compile
{
  "fields": ["title", "content"],
  "composite": ["combined_field"]
}
```

**多节点编译**：在集群环境中，编译请求会广播到所有 Ingest 节点，各节点并行编译后聚合结果。

## 规则匹配

规则匹配通过 Ingest Pipeline 配置实现：

```http
PUT _ingest/pipeline/security-pipeline
{
  "processors": [
    {
      "check_match_rules": {
        "id": "security_v1",
        "fields": ["title", "content"],
        "target_field": "tags"
      }
    }
  ]
}
```

**配置参数**：

| 参数                  | 默认值    | 说明                     |
| --------------------- | --------- | ------------------------ |
| `id`                  | (必需)    | 规则库ID                 |
| `ignore_missing`      | false     | 是否忽略错误             |
| `regex_start_at_word` | true      | 正则从词边界开始         |
| `fields`              | []        | 指定匹配的字段列表       |
| `default_match_field` | "content" | 未指定字段的默认匹配字段 |
| `target_field`        | "tags"    | 匹配结果写入的字段       |

文档经过 Pipeline 时，规则引擎会：

1. 提取文档字段内容
2. 使用 AC 自动机进行快速匹配
3. 将匹配的规则标签写入目标字段

## 性能优化

- **ThreadLocal 匹配器**：每个线程维护独立实例，避免同步开销
- **规则ID数组映射**：使用数组代替 HashMap，查找速度提升 14 倍，内存减少 87%
- **字段集合优化**：使用 Set 实现 O(1) 字段查找

## 多节点同步

节点启动时，同步服务会自动检查并同步规则库：

1. 等待集群恢复
2. 查询 `.match_rules` 索引中已编译的规则库
3. 检查本地是否存在对应的编译产物
4. 缺失则进行本地编译
5. 更新 `compiled_nodes` 列表

同步期间会添加集群阻塞，防止写入操作，确保数据一致性。

## 许可证控制

规则引擎需要许可证启用 `rule-engine` 功能。许可证验证包括：

- 许可证存在性检查
- 签名验证
- 过期时间检查
- `rule-engine` 功能启用检查

## 总结

Easysearch 规则引擎是一个功能完整、性能优异的规则匹配系统，具有以下特点：

1. **高性能匹配**：基于 AC 自动机算法，支持大规模规则库
2. **灵活的表达式**：支持 OR、AND、字段限定、正则、邻近查询等
3. **多节点支持**：自动同步，确保集群一致性
4. **无缝集成**：与 Ingest Pipeline 完美配合
5. **完善的许可证控制**：保障商业合规性

该系统适用于内容安全审核、舆情分析、数据分类等多种场景。