--- title: "页面缓存堆内存限制配置" date: 2026-01-15 lastmod: 2026-01-15 description: "控制页面缓存回收器可使用的最大堆内存量配置说明" tags: ["缓存配置", "内存管理", "性能优化"] summary: "配置项作用 # cache.recycler.page.limit.heap 配置项用于控制页面缓存回收器（Page Cache Recycler）可以使用的最大堆内存量。该回收器负责缓存和重用固定大小的内存页（16KB），包括 byte[]、int[]、long[] 和 Object[] 四种类型，以减少频繁的内存分配和垃圾回收开销。 通过合理设置此配置，可以在内存使用效率和性能之间取得平衡。 配置项类型 # 该配置项为静态配置，需要在 easysearch.yml 配置文件中设置，修改后需要重启节点才能生效。 默认值 # 10% (JVM 堆内存的 10%) 是否必需 # 可选配置项（有默认值） 取值格式 # <百分比>% 或 <字节值> 百分比：基于 JVM 堆内存大小计算，如 5%、10% 字节值：指定具体的字节数，如 100mb、1gb 配置格式 # # easysearch.yml # 默认配置 cache.recycler.page.limit.heap: 10% # 增加缓存大小 cache.recycler.page.limit.heap: 20% # 禁用页面缓存 cache.recycler.page.limit.heap: 0% # 指定具体大小 cache.recycler.page.limit.heap: 200mb 工作原理 # ┌─────────────────────────────────────────────────────────────────┐ │ 页面缓存内存分配机制 │ └─────────────────────────────────────────────────────────────────┘ JVM 堆内存 │ ├── cache." --- ## 配置项作用 `cache.recycler.page.limit.heap` 配置项用于控制页面缓存回收器（Page Cache Recycler）可以使用的最大堆内存量。该回收器负责缓存和重用固定大小的内存页（16KB），包括 `byte[]`、`int[]`、`long[]` 和 `Object[]` 四种类型，以减少频繁的内存分配和垃圾回收开销。 通过合理设置此配置，可以在内存使用效率和性能之间取得平衡。 ## 配置项类型 该配置项为**静态配置**，需要在 `easysearch.yml` 配置文件中设置，修改后需要重启节点才能生效。 ## 默认值 ``` 10% (JVM 堆内存的 10%) ``` ## 是否必需 **可选配置项**（有默认值） ## 取值格式 ``` <百分比>% 或 <字节值> ``` - 百分比：基于 JVM 堆内存大小计算，如 `5%`、`10%` - 字节值：指定具体的字节数，如 `100mb`、`1gb` ## 配置格式 ```yaml # easysearch.yml # 默认配置 cache.recycler.page.limit.heap: 10% # 增加缓存大小 cache.recycler.page.limit.heap: 20% # 禁用页面缓存 cache.recycler.page.limit.heap: 0% # 指定具体大小 cache.recycler.page.limit.heap: 200mb ``` ## 工作原理 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 页面缓存内存分配机制 │ └─────────────────────────────────────────────────────────────────┘ JVM 堆内存 │ ├── cache.recycler.page.limit.heap (如 10%) │ │ │ ├── 根据 weight 分配给不同类型 │ │ │ │ │ ├── byte[] pages (weight: 1.0) │ │ ├── int[] pages (weight: 1.0) │ │ ├── long[] pages (weight: 1.0) │ │ └── Object[] pages (weight: 0.1) │ └── 其他用途（索引、查询缓存等） ``` **页面规格：** - 页面大小固定：16KB (16384 字节) - byte[] 页面：16KB / 1 = 16,384 字节 - int[] 页面：16KB / 4 = 4,096 个 int - long[] 页面：16KB / 8 = 2,048 个 long - Object[] 页面：16KB / 8（引用大小）= 2,048 个引用 ## 内存分配计算 假设堆内存为 4GB，`cache.recycler.page.limit.heap: 10%`： ``` 总缓存大小 = 4GB × 10% = 400MB 最大页面数 = 400MB / 16KB ≈ 25,600 页 各类型分配（默认权重）： - byte[]: 1.0 / 3.1 × 25,600 ≈ 8,258 页 - int[]: 1.0 / 3.1 × 25,600 ≈ 8,258 页 - long[]: 1.0 / 3.1 × 25,600 ≈ 8,258 页 - Object[]: 0.1 / 3.1 × 25,600 ≈ 826 页 ``` ## 使用场景 ### 1. 默认配置（推荐） ```yaml cache.recycler.page.limit.heap: 10% ``` 适用于大多数场景，平衡了内存使用和性能。 ### 2. 大内存节点 ```yaml cache.recycler.page.limit.heap: 20% ``` 对于堆内存较大（如 32GB+）的节点，可适当增加缓存大小。 ### 3. 内存受限环境 ```yaml cache.recycler.page.limit.heap: 5% ``` 对于内存紧张的环境，减少缓存以节省内存。 ### 4. 禁用缓存 ```yaml cache.recycler.page.limit.heap: 0% ``` 完全禁用页面缓存，每次都新建对象。仅用于特殊调试场景。 ## 相关配置 页面缓存的内存分配还受以下权重配置影响： ```yaml # 各类型页面的权重（相对重要性） cache.recycler.page.weight.bytes: 1.0 # byte[] 页面权重 cache.recycler.page.weight.ints: 1.0 # int[] 页面权重 cache.recycler.page.weight.longs: 1.0 # long[] 页面权重 cache.recycler.page.weight.objects: 0.1 # Object[] 页面权重（默认较低） # 回收器类型 cache.recycler.page.type: CONCURRENT # 可选: QUEUE, CONCURRENT, NONE ``` ## 推荐设置建议 | 堆内存大小 | 推荐值 | 缓存大小 | 说明 | |-----------|--------|----------|------| | ≤ 4GB | 10% | ≤ 400MB | 默认配置即可 | | 4-16GB | 10-15% | 400MB-2.4GB | 可适当增加 | | 16-32GB | 15-20% | 2.4GB-6.4GB | 内存充足时可增加 | | ≥ 32GB | 20% | ≥ 6.4GB | 大内存节点可提高 | | SSD 存储 | 可提高 | - | SSD 支持更激进的缓存 | | 内存受限 | 5-10% | - | 优先保证索引和查询内存 | ## 监控与调优 ```bash # 查看当前配置 GET /_nodes/settings?filter_path=nodes.*.cache.recycler # 监控内存使用 GET /_nodes/stats/jvm?filter_path=nodes.*.jvm.mem # 查看节点信息 GET /_nodes/stats ``` ## 调优指南 1. **监控 GC 行为**：如果 GC 频率过高，可尝试增加缓存 2. **监控内存使用**：确保缓存不会挤占索引和查询内存 3. **按需调整**：根据实际工作负载特点调整各类型权重 4. **分阶段调优**：先调整整体限制，再调整各类型权重 ## 注意事项 1. **静态配置**：修改此配置需要重启节点 2. **内存总量**：缓存来自堆内存，需与索引缓冲区、查询缓存等协调 3. **权重平衡**：调整某类型权重会影响其他类型的分配 4. **页面粒度**：内存按 16KB 页面分配，实际使用可能有少量偏差 5. **GC 影响**：合理的缓存可减少 GC，但过大可能增加 GC 压力 6. **所有节点一致**：集群中各节点配置应保持一致