--- title: "强制插件配置" date: 2026-02-03 lastmod: 2026-02-03 description: "plugin.mandatory 配置项用于指定必须存在的插件列表，缺少任何强制插件会导致节点启动失败。" tags: ["Plugin", "插件管理", "安全", "启动验证"] summary: "配置项作用 # 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 在已加载列表中?" --- ## 配置项作用 `plugin.mandatory` 配置项用于指定**必须存在的插件列表**。 如果配置了强制插件列表，节点在启动时会检查所有指定的插件是否都已安装和加载。如果任何强制插件缺失，节点将拒绝启动并抛出异常。这确保了关键插件（如安全插件）始终存在，防止配置错误导致的安全风险。 ## 配置项属性 - **配置路径**: `plugin.mandatory` - **数据类型**: `List`（插件名列表） - **默认值**: 空列表（无强制插件） - **是否可选**: 是 - **作用域**: 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: 缺失 └── 需要安装这两个插件 ``` ## 配置建议 ## 生产环境（安全插件） ```yaml plugin: mandatory: [security] ``` **建议**: 生产环境强制要求安全插件，确保数据安全。 ## 自定义分析插件 ```yaml plugin: mandatory: [security, custom-analysis, custom-tokenizer] ``` **建议**: 如果业务依赖自定义分析插件，应设为强制。 ## 云环境插件 ```yaml plugin: mandatory: [security, discovery-gce, repository-gcs] ``` **建议**: 云环境强制要求相关云服务插件。 ## 开发环境 ```yaml # 不配置，不强制任何插件 plugin: # mandatory 不设置 ``` **建议**: 开发环境可以不配置，保持灵活性。 ## 代码示例 ## easysearch.yml 基础配置 ```yaml plugin: mandatory: [security] ``` ## 多个强制插件 ```yaml plugin: mandatory: - security - discovery-gce - repository-s3 ``` ## 完整安全配置 ```yaml # 开启 xpack 安全 xpack: security: enabled: true # 强制安全插件 plugin: mandatory: [security] # 配置其他必需插件 plugin: mandatory: - security - custom-auth-plugin - custom-audit-plugin ``` ## 自定义插件依赖 ```yaml # 假设业务依赖这些自定义插件 plugin: mandatory: - my-custom-analyzer - my-custom-ingest-processor - my-custom-script-engine ``` ## 相关配置 | 配置项 | 作用 | 默认值 | |--------|------|--------| | `plugin.mandatory` | 强制插件列表 | 空列表 | | `path.plugins` | 插件目录 | `path.home/plugins` | ## 插件管理命令 ``` 插件管理命令 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 └── ... ```