---
title: "导入规则库（自动ID覆盖）"
date: 2026-02-25
lastmod: 2026-02-25
description: "自动生成ID并导入规则库（覆盖模式）"
tags: ["规则库", "导入", "覆盖"]
summary: "自动生成规则库 ID 并导入规则，使用覆盖模式。如果同 ID 的规则库已存在，将完全替换原有规则。
API 格式 #  POST /_match_rules/_import API 作用 #  该 API 用于自动生成规则库 ID 并导入规则：
 自动生成 ID：系统自动生成格式为 repo_<timestamp> 的规则库 ID 覆盖模式：如果规则库已存在，完全替换原有规则；否则创建新规则库 支持批量导入多条规则 自动管理规则库版本号  API 参数 #  请求体参数 #     参数 类型 是否必填 默认值 描述     name String 是 - 规则库名称   description String 否 "" 规则库描述   tags String[] 否 [] 用于分类的标签数组   rules Array 是 - 规则对象数组（至少包含一条规则）    rules 数组元素结构 #     字段 类型 是否必填 描述     expression String 是 规则表达式（匹配条件）   description String 是 规则描述（匹配时作为标签使用）    请求示例 #  创建新规则库 #  POST /_match_rules/_import { "name": "安全规则库", "description": "用于安全事件分类的规则库", "tags": ["security", "content-filter"], "rules": [ { "expression": "枪 or 手枪 or 步步枪", "description": "涉枪武器关键词" }, { "expression": "AK47 or AK-47 or M16 or M4A1", "description": "枪支型号" }, { "expression": "爆炸物 or 炸弹 or 雷管", "description": "爆炸物品关键词" } ] } 覆盖已存在的规则库 #  POST /_match_rules/_import { "name": "安全规则库", "description": "更新后的安全规则库", "tags": ["security", "weapon"], "rules": [ { "expression": "刀 or 匕首 or 三棱刮刀", "description": "管制刀具关键词" }, { "expression": "毒性化学品 or 氰化物", "description": "危险化学品关键词" } ] } 响应示例 #  创建新规则库成功 #  { "success": true, "message": "Successfully imported 3 rules to repo_id 'repo_1704123456789' (version: 1)", "repo_id": "repo_1704123456789", "version": "1", "rule_count": 3 } 覆盖现有规则库成功 #  { "success": true, "message": "Successfully imported 2 rules to repo_id 'repo_1704123456789' (version: 2)", "repo_id": "repo_1704123456789", "version": "2", "rule_count": 2 } 错误响应 #  { "success": false, "message": "Rules array cannot be empty" } 响应字段说明 #     字段 类型 描述     success Boolean 操作是否成功   message String 详细结果消息   repo_id String 自动生成的规则库 ID（格式：repo_<timestamp>）   version String 规则库版本号   rule_count Integer 规则库中的规则总数    ID 生成规则 #  规则库 ID 按以下格式自动生成："
---


自动生成规则库 ID 并导入规则，使用覆盖模式。如果同 ID 的规则库已存在，将完全替换原有规则。

## API 格式

```
POST /_match_rules/_import
```

## API 作用

该 API 用于自动生成规则库 ID 并导入规则：
- **自动生成 ID**：系统自动生成格式为 `repo_<timestamp>` 的规则库 ID
- **覆盖模式**：如果规则库已存在，完全替换原有规则；否则创建新规则库
- 支持批量导入多条规则
- 自动管理规则库版本号

## API 参数

### 请求体参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `name` | String | **是** | - | 规则库名称 |
| `description` | String | 否 | `""` | 规则库描述 |
| `tags` | String[] | 否 | `[]` | 用于分类的标签数组 |
| `rules` | Array | **是** | - | 规则对象数组（至少包含一条规则） |

### rules 数组元素结构

| 字段 | 类型 | 是否必填 | 描述 |
|------|------|----------|------|
| `expression` | String | **是** | 规则表达式（匹配条件） |
| `description` | String | **是** | 规则描述（匹配时作为标签使用） |

## 请求示例

### 创建新规则库

```json
POST /_match_rules/_import
{
  "name": "安全规则库",
  "description": "用于安全事件分类的规则库",
  "tags": ["security", "content-filter"],
  "rules": [
    {
      "expression": "枪 or 手枪 or 步步枪",
      "description": "涉枪武器关键词"
    },
    {
      "expression": "AK47 or AK-47 or M16 or M4A1",
      "description": "枪支型号"
    },
    {
      "expression": "爆炸物 or 炸弹 or 雷管",
      "description": "爆炸物品关键词"
    }
  ]
}
```

### 覆盖已存在的规则库

```json
POST /_match_rules/_import
{
  "name": "安全规则库",
  "description": "更新后的安全规则库",
  "tags": ["security", "weapon"],
  "rules": [
    {
      "expression": "刀 or 匕首 or 三棱刮刀",
      "description": "管制刀具关键词"
    },
    {
      "expression": "毒性化学品 or 氰化物",
      "description": "危险化学品关键词"
    }
  ]
}
```

## 响应示例

### 创建新规则库成功

```json
{
  "success": true,
  "message": "Successfully imported 3 rules to repo_id 'repo_1704123456789' (version: 1)",
  "repo_id": "repo_1704123456789",
  "version": "1",
  "rule_count": 3
}
```

### 覆盖现有规则库成功

```json
{
  "success": true,
  "message": "Successfully imported 2 rules to repo_id 'repo_1704123456789' (version: 2)",
  "repo_id": "repo_1704123456789",
  "version": "2",
  "rule_count": 2
}
```

### 错误响应

```json
{
  "success": false,
  "message": "Rules array cannot be empty"
}
```

## 响应字段说明

| 字段 | 类型 | 描述 |
|------|------|------|
| `success` | Boolean | 操作是否成功 |
| `message` | String | 详细结果消息 |
| `repo_id` | String | 自动生成的规则库 ID（格式：`repo_<timestamp>`） |
| `version` | String | 规则库版本号 |
| `rule_count` | Integer | 规则库中的规则总数 |

## ID 生成规则

规则库 ID 按以下格式自动生成：
```
repo_<timestamp>
```

其中 `<timestamp>` 是当前时间的毫秒级时间戳（`System.currentTimeMillis()`）。

## 内部处理逻辑

1. **ID 生成**
   - 使用当前时间戳生成唯一的规则库 ID
   - 格式：`repo_<timestamp>`

2. **覆盖导入**
   - 创建新文档或完全替换现有文档
   - 所有规则从偏移量 0 开始编号

3. **版本管理**
   - 新文档：版本号为 1
   - 替换文档：版本号递增
   - 保留原有的 `created` 时间戳（如果存在）
   - 更新 `updated` 时间戳为当前时间

## 内部存储格式

规则在内部以以下格式存储：
```
expression1\t#0#description1
expression2\t#1#description2
expression3\t#2#description3
```

- 每条规则一行
- `\t` 分隔表达式和描述
- `#<offset>#` 表示规则编号（从 0 开始）

## POST 与 PUT 的区别

| 方法 | ID 处理 | 行为 |
|------|---------|------|
| **POST** | 自动生成 ID | 覆盖模式：替换现有规则 |
| **PUT** | 自动生成 ID | 追加模式：添加新规则 |

## 文档元数据字段

导入后，文档会包含以下字段：

| 字段 | 类型 | 描述 |
|------|------|------|
| `name` | String | 规则库名称 |
| `description` | String | 规则库描述 |
| `tags` | String[] | 分类标签 |
| `rules` | String | 规则文本（内部格式） |
| `version` | String | 版本号 |
| `created` | Date | 创建时间戳 |
| `updated` | Date | 最后更新时间戳 |
| `status` | String | 编译状态（初始为 `pending`） |
| `compiled_at` | Date/null | 编译完成时间 |
| `total_rules` | Integer/null | 规则总数（编译后设置） |
| `compiled_nodes` | String[] | 已编译的节点列表 |
| `error_message` | String/null | 编译失败时的错误信息 |

## 使用场景

1. **快速创建**：无需指定 ID，快速创建新规则库
2. **完全替换**：一次性替换规则库中的所有规则
3. **版本重置**：从零开始构建新的规则集
4. **自动化脚本**：脚本中无需管理 ID 冲突，直接覆盖

## 注意事项

1. **数据丢失**：使用 POST 方法会完全替换现有规则，请谨慎操作
2. **ID 不可预测**：由于 ID 基于时间戳生成，无法提前预测
3. **时间戳冲突**：极短时间内多次调用会替换之前的规则
4. **规则验证**：每条规则必须包含 `expression` 和 `description` 字段
5. **编译状态**：导入后规则库状态为 `pending`，需要编译后才能使用

## API 对比

| API | ID 处理 | 模式 |
|------|---------|------|
| `POST /_match_rules/_import` | 自动生成 | 覆盖 |
| `PUT /_match_rules/_import` | 自动生成 | 追加 |
| `POST /_match_rules/{repo_id}/_import` | 指定 ID | 覆盖 |
| `PUT /_match_rules/{repo_id}/_import` | 指定 ID | 追加 |