---
title: "Painless 正则表达式启用配置"
date: 2026-01-14
lastmod: 2026-01-14
description: "控制 Painless 脚本中正则表达式使用的配置说明"
tags: ["脚本", "Painless", "正则表达式", "安全配置"]
summary: "配置项作用 #  script.painless.regex.enabled 配置项控制是否在 Painless 脚本中启用正则表达式及其复杂度限制。
是否可选 #  是
默认值 #  "limited" (启用但限制复杂度) 配置项类型 #  静态配置 - 需要重启节点才能生效
配置格式 #  # 默认配置（推荐） script.painless.regex.enabled: "limited" # 完全启用（无限制） script.painless.regex.enabled: "true" # 完全禁用 script.painless.regex.enabled: "false" 选项说明 #     选项 说明 复杂度限制 安全性     "limited" 启用但限制复杂度 受 regex.limit-factor 限制 高   "true" 完全启用 无限制 低   "false" 完全禁用 不适用 最高    工作原理 #  ┌─────────────────────────────────────────────────────────┐ │ 正则表达式处理 │ └─────────────────────────────────────────────────────────┘ Painless 脚本执行 │ ▼ 检查 regex."
---


## 配置项作用

`script.painless.regex.enabled` 配置项控制是否在 Painless 脚本中启用正则表达式及其复杂度限制。

## 是否可选

是

## 默认值

```
"limited" (启用但限制复杂度)
```

## 配置项类型

**静态配置** - 需要重启节点才能生效

## 配置格式

```yaml
# 默认配置（推荐）
script.painless.regex.enabled: "limited"

# 完全启用（无限制）
script.painless.regex.enabled: "true"

# 完全禁用
script.painless.regex.enabled: "false"
```

## 选项说明

| 选项 | 说明 | 复杂度限制 | 安全性 |
|------|------|-----------|--------|
| `"limited"` | 启用但限制复杂度 | 受 `regex.limit-factor` 限制 | 高 |
| `"true"` | 完全启用 | 无限制 | 低 |
| `"false"` | 完全禁用 | 不适用 | 最高 |

## 工作原理

```
┌─────────────────────────────────────────────────────────┐
│                   正则表达式处理                          │
└─────────────────────────────────────────────────────────┘

Painless 脚本执行
    │
    ▼
检查 regex.enabled
    │
    ├── "false" → 禁用正则，抛出错误
    │
    ├── "true" → 允许任意复杂度正则
    │
    └── "limited" → 检查复杂度
            │
            ├── 复杂度 <= limit → 执行
            └── 复杂度 > limit → 拒绝
```

## 复杂度计算

当设置为 `"limited"` 时：
- 复杂度 = 输入字符串长度 × limit-factor
- 默认 limit-factor 为 6
- 可通过 `script.painless.regex.limit-factor` 调整

## 推荐设置

| 环境 | 推荐值 | 说明 |
|------|--------|------|
| 默认配置 | "limited" | 平衡功能和安全性 |
| 生产环境 | "limited" | 防止正则 DoS |
| 高安全环境 | "false" | 完全禁用正则 |
| 开发环境 | "true" | 便于测试 |

## 使用示例

**默认配置（推荐）：**

```yaml
script.painless.regex.enabled: "limited"
script.painless.regex.limit-factor: 6
```

**生产环境安全配置：**

```yaml
script.painless.regex.enabled: "limited"
script.painless.regex.limit-factor: 3
```

**高安全环境：**

```yaml
script.painless.regex.enabled: "false"
```

**开发测试环境：**

```yaml
script.painless.regex.enabled: "true"
```

## 安全考虑

**正则表达式 DoS 风险：**

复杂正则可能导致 ReDoS (Regular Expression Denial of Service)：
- 指数级时间复杂度
- 耗尽 CPU 资源
- 导致服务无响应

**风险示例：**

```painless
// 危险：回溯灾难
/a+a+a+a+a+a+/.matcher("aaaaaaaaaaaaaaaaaaaaa")

// 安全：限制复杂度
```

## 配置验证

```bash
# 查看当前配置
GET /_nodes/settings?filter_path=nodes.*.script.painless.regex*

# 测试正则表达式
GET /_search
{
  "query": {
    "script": {
      "source": "doc['text'].value =~ /pattern/"
    }
  }
}
```

## 常见问题

**问题 1：正则被拒绝**

**错误信息：**
```
script_exception: regular expression is too complex
```

**解决方案：**

```yaml
# 增加 limit-factor
script.painless.regex.limit-factor: 10

# 或启用无限制模式（不推荐）
script.painless.regex.enabled: "true"
```

**问题 2：正则功能不可用**

**错误信息：**
```
script_exception: regular expressions are disabled
```

**解决方案：**

```yaml
script.painless.regex.enabled: "limited"
```

## 注意事项

1. **静态配置**：修改需要重启节点
2. **DoS 保护**：limited 模式提供保护
3. **性能影响**：复杂正则影响性能
4. **生产环境**：推荐使用 limited 模式
5. **无限制风险**：true 模式存在安全风险

## 相关配置项

| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| `script.painless.regex.limit-factor` | 6 | 复杂度限制因子 |
| `script.max_compilations_rate` | use-context | 编译速率限制 |

## 完整配置示例

```yaml
# easysearch.yml

# 推荐配置
script.painless.regex.enabled: "limited"
script.painless.regex.limit-factor: 6

# 安全配置
script.painless.regex.enabled: "limited"
script.painless.regex.limit-factor: 3
```