强制插件配置

配置项作用 #

plugin.mandatory 配置项用于指定必须存在的插件列表。

如果配置了强制插件列表，节点在启动时会检查所有指定的插件是否都已安装和加载。如果任何强制插件缺失，节点将拒绝启动并抛出异常。这确保了关键插件（如安全插件）始终存在，防止配置错误导致的安全风险。

配置项属性 #

• 配置路径: plugin.mandatory
• 数据类型: List<String>（插件名列表）
• 默认值: 空列表（无强制插件）
• 是否可选: 是
• 作用域: NodeScope（节点级别）
• 动态更新: 否（启动时检查）

配置项详解 #

工作机制 #

强制插件检查机制

启动流程:
1. 加载插件
   ├── 扫描 plugins 目录
   ├── 加载所有可用插件
   └── 获取插件列表


2. 检查强制插件
   plugin.mandatory: [security, custom-analysis]
       │
       ├── security 在已加载列表中? ✅
       ├── custom-analysis 在已加载列表中? ✅
       └── 全部存在 → 继续启动


3. 发现缺失插件
   plugin.mandatory: [security, custom-plugin]
       │
       ├── security 在已加载列表中? ✅
       ├── custom-plugin 在已加载列表中? ❌
       └── 缺失 → 启动失败


4. 启动失败
   抛出异常:
   IllegalStateException: missing mandatory plugins [custom-plugin],
   found plugins [analysis-icu, ingest-geoip, ...]

插件加载顺序 #

插件加载和检查流程

节点启动:
    │
    ├── 1. 初始化环境
    │   └── 读取配置
    │
    ├── 2. 扫描插件目录
    │   ├── plugins/
    │   │   ├── analysis-icu/
    │   │   ├── custom-plugin/
    │   │   └── security/
    │   └── 加载所有插件
    │
    ├── 3. 读取 plugin.mandatory 配置
    │   └── 获取强制插件列表
    │
    ├── 4. 验证强制插件
    │   ├── 遍历强制插件列表
    │   ├── 检查是否已加载
    │   └── 记录缺失插件
    │
    ├── 5. 决策
    │   ├── 全部存在 → 继续启动 ✅
    │   └── 有缺失 → 抛出异常 ❌
    │
    └── 6. 完成启动
        └── 节点运行

错误信息 #

启动失败错误信息

配置:
plugin.mandatory: [security, discovery-gce, custom-plugin]


实际插件:
├── analysis-icu ✅
├── ingest-geoip ✅
├── security ✅
└── discovery-gce ❌ (未安装)


错误输出:
java.lang.IllegalStateException: missing mandatory plugins
[discovery-gce, custom-plugin], found plugins [analysis-icu,
ingest-geoip, security, ...]


分析:
├── discovery-gce: 缺失
├── custom-plugin: 缺失
└── 需要安装这两个插件

配置建议 #

生产环境（安全插件） #

plugin:
  mandatory: [security]

建议: 生产环境强制要求安全插件，确保数据安全。

自定义分析插件 #

plugin:
  mandatory: [security, custom-analysis, custom-tokenizer]

建议: 如果业务依赖自定义分析插件，应设为强制。

云环境插件 #

plugin:
  mandatory: [security, discovery-gce, repository-gcs]

建议: 云环境强制要求相关云服务插件。

开发环境 #

# 不配置，不强制任何插件
plugin:
  # mandatory 不设置

建议: 开发环境可以不配置，保持灵活性。

代码示例 #

easysearch.yml 基础配置 #

plugin:
  mandatory: [security]

多个强制插件 #

plugin:
  mandatory:
    - security
    - discovery-gce
    - repository-s3

完整安全配置 #

# 开启 xpack 安全
xpack:
  security:
    enabled: true

# 强制安全插件
plugin:
  mandatory: [security]

# 配置其他必需插件
plugin:
  mandatory:
    - security
    - custom-auth-plugin
    - custom-audit-plugin

自定义插件依赖 #

# 假设业务依赖这些自定义插件
plugin:
  mandatory:
    - my-custom-analyzer
    - my-custom-ingest-processor
    - my-custom-script-engine

相关配置 #

插件管理命令 #

插件管理命令

1. 列出已安装插件:
bin/easysearch-plugin list


2. 安装插件:
bin/easysearch-plugin install analysis-icu


3. 删除插件:
bin/easysearch-plugin remove analysis-icu


4. 查看插件信息:
bin/easysearch-plugin list --verbose


5. 验证插件:
bin/easysearch-plugin install file:///path/to/plugin.zip

使用场景 #

推荐设置强制插件的场景 #

• 生产环境: 确保安全插件始终启用
• 合规要求: 必须使用特定审计/监控插件
• 业务依赖: 业务逻辑依赖特定自定义插件
• 多节点集群: 确保所有节点有相同插件
• 云部署: 强制要求云服务集成插件

推荐不设置强制插件的场景 #

• 开发环境: 保持灵活性
• 测试环境: 测试不同插件组合
• 可选功能: 插件提供可选增强功能

安全强化 #

安全强化配置

场景: 高安全要求环境

配置:
plugin:
  mandatory:
    - security
    - custom-auth-plugin
    - audit-log-plugin
    - data-encryption-plugin


效果:
├── 缺少任何安全插件 → 无法启动
├── 防止配置错误
├── 确保合规要求
└── 提高安全水位

注意事项 #

1. 默认值: 默认为空列表，不强制任何插件。

2. 启动检查: 仅在节点启动时检查。

3. 失败原因: 缺失强制插件会导致启动失败。

4. 插件名称: 使用插件的官方名称。

5. 大小写敏感: 插件名称通常区分大小写。

6. 版本兼容: 确保插件版本与 Easysearch 版本兼容。

7. 集群一致性: 集群中所有节点应安装相同的强制插件。

8. 动态更新: 不能动态更新，需要重启。

9. 自定义插件: 自定义插件也可以设为强制。

10. 错误信息: 启动失败时会清楚列出缺失的插件。

故障排查 #

常见问题排查

问题 1: 启动失败 - 缺失强制插件

错误:
missing mandatory plugins [custom-plugin],
found plugins [analysis-icu, ...]


检查:
├── 确认插件名称正确
├── 检查插件是否安装
├── 查看插件列表
└── 验证插件目录权限


解决:
├── 安装缺失的插件
├── 或从强制列表中移除
├── 重启节点
└── 验证启动


问题 2: 插件名称错误

错误:
missing mandatory plugins [Security]


原因:
├── 插件名称大小写错误
├── 实际名称是 security
└── 配置了 Security


解决:
├── 使用正确的插件名
├── 查看插件列表确认
├── 修改配置
└── 重启节点


问题 3: 插件版本不兼容

错误:
Plugin [custom-plugin] requires Easysearch version 7.x


解决:
├── 升级 Easysearch
├── 或降级插件
├── 或获取兼容版本
└── 重新安装

集群一致性 #

集群插件一致性要求

问题:
节点 A: plugin.mandatory: [security, custom]
节点 B: plugin.mandatory: [security]


不一致:
├── 节点要求不同
├── 可能导致问题
└── 应保持一致 ✅


最佳实践:
├── 所有节点使用相同配置
├── 所有节点安装相同插件
├── 使用配置管理工具
└── 定期审计


检查集群插件:
GET /_cat/plugins?v


响应:
name           component        version
node-1         security         8.0.0
node-1         custom-plugin    1.0.0
node-2         security         8.0.0
node-2         custom-plugin    1.0.0

最佳实践 #

强制插件最佳实践

1. 生产安全
   plugin:
     mandatory: [security]

   ├── 确保安全启用
   ├── 防止意外禁用
   └── 合规要求 ✅


2. 业务依赖
   plugin:
     mandatory: [security, custom-analyzer]

   ├── 声明业务依赖
   ├── 启动前验证
   └── 避免运行时错误


3. 集群一致性
   ├── 所有节点相同配置
   ├── 统一插件版本
   ├── 配置管理
   └── 自动化部署


4. 分层配置
   ├── 核心: security (强制)
   ├── 云: discovery-* (云环境)
   ├── 可选: analysis-* (不强制)
   └── 按需配置


5. 变更管理
   ├── 测试插件变更
   ├── 滚动更新集群
   ├── 验证功能
   └── 回滚计划

插件类型参考 #

常见插件类型

核心插件:
├── security: 安全和认证
├── alerting: 告警通知
├── monitoring: 监控
├── ml: 机器学习
└── ...

分析插件:
├── analysis-icu: ICU 分析器
├── analysis-kuromoji: 日语分词
├── analysis-smartcn: 中文分词
└── ...

发现插件:
├── discovery-gce: GCE 发现
├── discovery-ec2: EC2 发现
├── discovery-azure: Azure 发现
└── ...

存储插件:
├── repository-s3: S3 仓库
├── repository-gcs: GCS 仓库
├── repository-azure: Azure 仓库
└── ...

 ingest 插件:
├── ingest-attachment: 附件处理
├── ingest-geoip: 地理 IP
└── ...