--- title: "ISM 历史索引最大文档数配置" date: 2026-03-23 lastmod: 2026-03-23 description: "index_state_management.history.max_docs 配置项用于控制历史索引触发滚动前的最大文档数。" tags: ["索引状态管理", "ISM", "历史记录", "索引滚动"] summary: "配置项作用 # index_state_management.history.max_docs 配置项用于控制ISM 历史索引触发滚动操作前的最大文档数量。 当历史索引的文档数达到此配置值时，系统会自动创建新的历史索引并将写入别名指向新索引。 配置项属性 # 配置路径: index_state_management.history.max_docs 数据类型: Long（整数） 默认值: 2500000（250万） 最小值: 0（0 表示不限制） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（支持动态更新） 配置项详解 # 工作机制 # 历史索引滚动流程（基于文档数） 历史索引创建 (.ism-history-000001) │ ↓ 记录 ISM 操作历史 │ ↓ 定期检查文档数 (rollover_check_period) │ ├──────── 文档数 < max_docs ──→ 继续使用 ✅ │ └──────── 文档数 ≥ max_docs ──→ 触发滚动 │ ↓ 创建新历史索引 (.ism-history-000002) │ ↓ 更新别名指向 │ ↓ 旧索引只读 文档计数 # 文档计数示例 假设 max_docs = 2500000 时间推移: 0h ────→ 1h ────→ 5h ────→ 24h │ │ │ │ 0 条 10万 50万 250万 ✅ 条 条 条 (达到上限) │ ↓ 触发滚动 与 max_age 的配合 # 双条件滚动 条件 1: 文档数 文档数 ≥ max_docs (2500000) ↓ 触发滚动 条件 2: 年龄 年龄 ≥ max_age (24h) ↓ 触发滚动 先达到条件的优先触发滚动 配置建议 # 生产环境（默认） # index_state_management: history: max_docs: 2500000 # 默认值（约 25GB） 建议: 保持默认值。适用于大多数场景。" --- ## 配置项作用 `index_state_management.history.max_docs` 配置项用于控制**ISM 历史索引触发滚动操作前的最大文档数量**。 当历史索引的文档数达到此配置值时，系统会自动创建新的历史索引并将写入别名指向新索引。 ## 配置项属性 - **配置路径**: `index_state_management.history.max_docs` - **数据类型**: `Long`（整数） - **默认值**: `2500000`（250万） - **最小值**: `0`（0 表示不限制） - **是否可选**: 是 - **作用域**: NodeScope（节点级别） - **动态更新**: 是（支持动态更新） ## 配置项详解 ## 工作机制 ``` 历史索引滚动流程（基于文档数） 历史索引创建 (.ism-history-000001) │ ↓ 记录 ISM 操作历史 │ ↓ 定期检查文档数 (rollover_check_period) │ ├──────── 文档数 < max_docs ──→ 继续使用 ✅ │ └──────── 文档数 ≥ max_docs ──→ 触发滚动 │ ↓ 创建新历史索引 (.ism-history-000002) │ ↓ 更新别名指向 │ ↓ 旧索引只读 ``` ## 文档计数 ``` 文档计数示例 假设 max_docs = 2500000 时间推移: 0h ────→ 1h ────→ 5h ────→ 24h │ │ │ │ 0 条 10万 50万 250万 ✅ 条 条 条 (达到上限) │ ↓ 触发滚动 ``` ## 与 max_age 的配合 ``` 双条件滚动 条件 1: 文档数 文档数 ≥ max_docs (2500000) ↓ 触发滚动 条件 2: 年龄 年龄 ≥ max_age (24h) ↓ 触发滚动 先达到条件的优先触发滚动 ``` ## 配置建议 ## 生产环境（默认） ```yaml index_state_management: history: max_docs: 2500000 # 默认值（约 25GB） ``` **建议**: 保持默认值。适用于大多数场景。 ## 高频操作环境 ```yaml index_state_management: history: max_docs: 1000000 # 100 万 ``` **建议**: 减少到 `500000-1000000`。ISM 操作非常频繁时使用。 ## 存储受限环境 ```yaml index_state_management: history: max_docs: 500000 # 50 万 ``` **建议**: 减少到 `200000-500000`。存储空间紧张时使用。 ## 不限制文档数 ```yaml index_state_management: history: max_docs: 0 # 不限制 ``` **建议**: 仅依赖 `max_age` 条件时使用。 ## 代码示例 ## easysearch.yml 基础配置 ```yaml index_state_management: history: max_docs: 2500000 ``` ## 配合其他历史配置 ```yaml index_state_management: history: enabled: true max_docs: 2500000 max_age: 24h rollover_check_period: 8h ``` ## 快速滚动配置 ```yaml index_state_management: history: max_docs: 1000000 max_age: 12h ``` ## 动态更新配置 ```json PUT /_cluster/settings { "transient": { "index_state_management.history.max_docs": 5000000 } } ``` ## 相关配置 | 配置项 | 作用 | 默认值 | |--------|------|--------| | `index_state_management.history.enabled` | 是否启用历史记录 | true | | `index_state_management.history.max_age` | 历史索引最大年龄 | 24h | | `index_state_management.history.max_docs` | 历史索引最大文档数 | 2500000 | | `index_state_management.history.rollover_check_period` | 滚动检查周期 | 8h | ## 存储影响分析 ``` 文档数量与存储关系 假设平均每条记录 10KB max_docs = 500000: 存储需求 ≈ 500000 × 10KB ≈ 5GB max_docs = 1000000: 存储需求 ≈ 1000000 × 10KB ≈ 10GB max_docs = 2500000 (默认): 存储需求 ≈ 2500000 × 10KB ≈ 25GB max_docs = 5000000: 存储需求 ≈ 5000000 × 10KB ≈ 50GB 配合保留期 (rollover_retention_period = 30d): 假设每天滚动一次，约 30 个索引 总存储 ≈ 25GB × 30 ≈ 750GB ``` ## 使用场景 ## 推荐使用默认值的场景 - **标准生产**: 正常的 ISM 操作频率 - **中等存储**: 有足够的存储空间 - **平衡需求**: 平衡索引大小和数量 ## 推荐减少 max_docs 的场景 - **高频操作**: ISM 策略执行非常频繁 - **快速检索**: 希望单个索引较小 - **存储受限**: 存储空间有限 ## 推荐增加 max_docs 的场景 - **低频操作**: ISM 操作不频繁 - **简化管理**: 减少索引数量 - **充足存储**: 有足够的存储空间 ## 推荐不限制的场景 - **时间驱动**: 主要依赖 max_age 触发滚动 - **操作不可预测**: 难以预估文档数量 ## 操作频率与滚动关系 ``` 不同操作频率下的滚动时间 场景 1: 低频操作 操作频率: 1000 条/小时 max_docs: 2500000 滚动时间 = 2500000 / 1000 = 2500 小时 ≈ 104 天 场景 2: 中频操作 操作频率: 10000 条/小时 max_docs: 2500000 滚动时间 = 2500000 / 10000 = 250 小时 ≈ 10 天 场景 3: 高频操作 操作频率: 100000 条/小时 max_docs: 2500000 滚动时间 = 2500000 / 100000 = 25 小时 ≈ 1 天 场景 4: 超高频操作 操作频率: 500000 条/小时 max_docs: 2500000 滚动时间 = 2500000 / 500000 = 5 小时 ``` ## 索引命名模式 ``` 历史索引命名规则 .ism-history-000001 (0-250万 条记录) .ism-history-000002 (0-250万 条记录) ← 达到上限后滚动 .ism-history-000003 (0-250万 条记录) ← 再次达到上限后滚动 .ism-history-000004 (0-250万 条记录) 别名始终指向最新索引: .ism-history → .ism-history-000004 ``` ## 配置调优指南 ## 确定合适的 max_docs ``` 步骤 1: 估算操作频率 统计每小时的 ISM 操作数量 包括: 状态变更、操作执行、错误记录 步骤 2: 评估存储容量 单个历史索引的期望大小 例如: 10GB/索引 步骤 3: 计算 max_docs 每条记录约 10KB max_docs = 期望存储 / 10KB 例如: 10GB / 10KB = 1000000 步骤 4: 验证滚动频率 滚动时间 = max_docs / 每小时操作数 确保滚动时间合理（不过于频繁） 步骤 5: 配合 max_age 设置合理的 max_age 作为备用条件 确保两个条件都能正常工作 ``` ## 注意事项 1. **文档大小**: 默认估算每条文档约 10KB。 2. **与 max_age 配合**: 两个条件任一满足都会触发滚动。 3. **存储规划**: 需要根据操作频率规划存储空间。 4. **动态更新**: 支持动态更新，修改后立即生效。 5. **值为 0**: 设置为 `0` 表示不限制文档数。 6. **检查周期**: 实际检查频率由 `rollover_check_period` 控制。 7. **索引数量**: 较小的 max_docs 会产生更多索引。 8. **查询性能**: 单个索引过大可能影响查询性能。 9. **备份策略**: 滚动产生的旧索引需要包含在备份中。 10. **监控建议**: 监控历史索引的文档数和滚动频率。