---
title: "节点本地存储配置"
date: 2026-02-02
lastmod: 2026-02-02
description: "node.local_storage 配置项用于控制节点是否可以将元数据等数据持久化到本地磁盘。"
tags: ["Node", "存储", "协调节点", "本地存储"]
summary: "配置项作用 #  node.local_storage 配置项用于控制节点是否允许将元数据等数据持久化到本地磁盘。
此设置不影响节点是否存储实际的索引数据（由 node.data 控制），但如果 node.local_storage 设置为 false，则 node.data 和 node.master 也必须为 false。
注意：此配置项已被废弃，推荐使用 node.roles 配置来替代。
配置项属性 #   配置路径: node.local_storage 数据类型: Boolean（布尔值） 默认值: true 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 废弃状态: 已废弃，使用 node.roles 替代  配置项详解 #  工作机制 #  节点本地存储机制 启用本地存储 (node.local_storage: true): ├── 可以持久化元数据 ├── 可以存储集群状态 ├── 可以存储索引数据 (如果 node.data: true) ├── 可以参与主节点选举 (如果 node.master: true) └── 正常节点模式 ✅ 禁用本地存储 (node.local_storage: false): ├── 不持久化元数据 ├── 不存储集群状态 ├── 不能存储索引数据 (node."
---


## 配置项作用

`node.local_storage` 配置项用于控制**节点是否允许将元数据等数据持久化到本地磁盘**。

此设置不影响节点是否存储实际的索引数据（由 `node.data` 控制），但如果 `node.local_storage` 设置为 `false`，则 `node.data` 和 `node.master` 也必须为 `false`。

**注意**：此配置项已被废弃，推荐使用 `node.roles` 配置来替代。

## 配置项属性

- **配置路径**: `node.local_storage`
- **数据类型**: `Boolean`（布尔值）
- **默认值**: `true`
- **是否可选**: 是
- **作用域**: NodeScope（节点级别）
- **动态更新**: 否（需要重启节点生效）
- **废弃状态**: 已废弃，使用 `node.roles` 替代

## 配置项详解

## 工作机制

```
节点本地存储机制

启用本地存储 (node.local_storage: true):
├── 可以持久化元数据
├── 可以存储集群状态
├── 可以存储索引数据 (如果 node.data: true)
├── 可以参与主节点选举 (如果 node.master: true)
└── 正常节点模式 ✅


禁用本地存储 (node.local_storage: false):
├── 不持久化元数据
├── 不存储集群状态
├── 不能存储索引数据 (node.data 必须为 false)
├── 不能参与主节点选举 (node.master 必须为 false)
├── 仅作为协调节点运行
└── 轻量级节点模式 ✅
```

## 存储内容说明

```
本地存储的内容

启用时持久化的内容:
├── 集群元数据
│   ├── 索引配置
│   ├── 映射定义
│   ├── 别名信息
│   └── 设置信息
├── 节点状态
│   ├── 节点 ID
│   ├── 节点属性
│   └── 发现信息
├── 索引数据
│   ├── 分片数据
│   ├── 事务日志
│   └── 段文件
└── 快照信息


禁用后的行为:
├── 元数据存储: 内存中 ❌
├── 集群状态: 不持久化 ❌
├── 索引数据: 不存储 ❌
└── 重启后: 重新获取
```

## 角色限制验证

```
配置验证规则

规则 1: local_storage = false 且 data = true
├── 配置冲突 ❌
├── 启动失败
└── 错误: 不能在没有本地存储时存储数据


规则 2: local_storage = false 且 master = true
├── 配置冲突 ❌
├── 启动失败
└── 错误: 不能在没有本地存储时作为主节点


规则 3: local_storage = false 且其他角色
├── data = false ✅
├── master = false ✅
├── ingest = true/false ✅
└── 正常运行


正确配置示例:
# 协调节点
node.local_storage: false
node.data: false
node.master: false
node.ingest: false
```

## 与 path.data 的关系

```
path.data 配置关系

启用本地存储:
node.local_storage: true
path.data: /data/easysearch
    │
    ├── 使用指定路径
    ├── 存储元数据
    ├── 存储索引数据
    └── 正常工作 ✅


禁用本地存储但有 path.data:
node.local_storage: false
path.data: /data/easysearch
    │
    ├── 配置冲突 ❌
    ├── 启动失败
    └── 不应配置数据路径


禁用本地存储且无 path.data:
node.local_storage: false
# 不设置 path.data
    │
    ├── 使用空路径数组
    ├── 仅作为协调节点
    └── 正常工作 ✅
```

## 配置建议

## 生产环境（默认）

```yaml
node:
  local_storage: true  # 默认值
```

**建议**: 保持默认值 `true`。大多数节点需要本地存储。

## 协调节点

```yaml
node:
  local_storage: false  # 禁用本地存储
  data: false
  master: false
```

**建议**: 协调节点禁用本地存储，减少资源占用。

## 数据节点

```yaml
node:
  local_storage: true  # 必须启用
  data: true
```

**建议**: 数据节点必须启用本地存储。

## 主节点

```yaml
node:
  local_storage: true  # 必须启用
  master: true
```

**建议**: 主节点必须启用本地存储以存储集群元数据。

## 推荐配置（使用新角色）

```yaml
# 协调节点（无本地存储）
node.roles: []

# 数据/主节点（有本地存储）
node.roles: [ "data", "master" ]
```

**建议**: 使用 `node.roles` 替代废弃的配置。

## 代码示例

## easysearch.yml 基础配置

```yaml
node:
  local_storage: true
```

## 协调节点配置

```yaml
node:
  name: "coordinating-node"
  local_storage: false
  data: false
  master: false
  ingest: false
```

## 数据节点配置

```yaml
node:
  name: "data-node-1"
  local_storage: true
  data: true
  master: false
```

## 主节点配置

```yaml
node:
  name: "master-node-1"
  local_storage: true
  master: true
  data: false
```

## 推荐使用角色配置

```yaml
# 协调节点（无本地存储）
node.roles: []
node.name: "coordinating-node"

# 数据节点（有本地存储）
node.roles: [ "data" ]
path.data: /data/easysearch

# 主节点（有本地存储）
node.roles: [ "master" ]
path.data: /data/easysearch
```

## 相关配置

| 配置项 | 作用 | 默认值 |
|--------|------|--------|
| `node.local_storage` | 本地存储开关 | true |
| `node.data` | 数据节点角色 | true |
| `node.master` | 主节点角色 | true |
| `path.data` | 数据路径 | - |
| `node.roles` | 节点角色列表（推荐） | - |

## 角色映射关系

```
废弃配置与新角色映射

协调节点 (无本地存储):
旧配置:
node.local_storage: false
node.data: false
node.master: false
node.ingest: false


新配置 (推荐):
node.roles: []  (空列表)


全功能节点 (有本地存储):
旧配置:
node.local_storage: true
node.data: true
node.master: true
node.ingest: true


新配置 (推荐):
node.roles: [ "master", "data", "ingest" ]


数据节点 (有本地存储):
旧配置:
node.local_storage: true
node.data: true
node.master: false


新配置 (推荐):
node.roles: [ "data" ]
```

## 性能影响分析

| node.local_storage 设置 | 优点 | 缺点 |
|------------------------|------|------|
| true | 持久化数据、完整功能 | 磁盘 I/O 开销 |
| false | 无磁盘开销、轻量 | 无状态、需重新加载数据 |

## 资源消耗对比

```
资源消耗分析

启用本地存储:
├── 磁盘使用
│   ├── 元数据存储
│   ├── 集群状态
│   ├── 索引数据
│   └── 事务日志
├── 磁盘 I/O
│   ├── 读取操作
│   ├── 写入操作
│   └── 持久化开销
└── 故障恢复
    ├── 快速恢复
    └── 数据保留


禁用本地存储:
├── 磁盘使用: 无 ✅
├── 磁盘 I/O: 无 ✅
├── 内存使用: 较少 ✅
├── 启动速度: 快 ✅
└── 故障恢复: 无需恢复 ✅
```

## 使用场景

## 推荐启用 local_storage 的场景

- **数据节点**: 需要存储索引数据
- **主节点**: 需要持久化集群元数据
- **摄取节点**: 可能需要存储管道信息
- **持久化需求**: 数据必须持久化

## 推荐禁用 local_storage 的场景

- **协调节点**: 仅处理查询分发
- **轻量网关**: 作为查询网关
- **资源受限**: 无可用磁盘
- **无状态部署**: 云环境无状态节点

## 集群规划建议

```
集群存储规划

小型集群:
├── 所有节点启用 local_storage
├── 简化配置
└── 足够应对需求


中型集群:
├── 数据节点: local_storage: true
├── 主节点: local_storage: true
├── 协调节点: local_storage: false
└── 分层架构


大型集群:
├── 协调节点层: local_storage: false
├── 数据节点层: local_storage: true
├── 主节点层: local_storage: true
└── 清晰分离


云环境:
├── 有状态节点: local_storage: true
├── 无状态节点: local_storage: false
├── 弹性伸缩
└── 成本优化
```

## 注意事项

1. **已废弃**: 此配置项已被废弃，推荐使用 `node.roles`。

2. **需要重启**: 修改此配置需要重启节点。

3. **角色限制**: 禁用后 data 和 master 必须为 false。

4. **数据路径**: 禁用后不应配置 path.data。

5. **元数据丢失**: 重启后需要重新获取元数据。

6. **状态依赖**: 依赖其他节点的持久化能力。

7. **集群稳定**: 确保有足够的持久化节点。

8. **监控建议**: 监控协调节点的内存使用。

9. **网络依赖**: 所有数据都需要从其他节点获取。

10. **迁移建议**: 新配置使用 `node.roles`。

## 部署模式

```
节点部署模式

有状态节点:
├── local_storage: true
├── 持久化数据
├── 完整功能
└── 推荐: 数据节点、主节点


无状态节点:
├── local_storage: false
├── 无持久化
├── 轻量级
└── 推荐: 协调节点


混合部署:
├── 有状态层: 数据和主节点
├── 无状态层: 协调节点
├── 弹性扩展
└── 成本优化
```

## 废弃说明

```
配置迁移指南

从废弃配置迁移到新配置

协调节点:
旧配置:
node.local_storage: false
node.data: false
node.master: false
node.ingest: false


新配置 (推荐):
node.roles: []


数据节点:
旧配置:
node.local_storage: true
node.data: true
node.master: false


新配置 (推荐):
node.roles: [ "data" ]


主节点:
旧配置:
node.local_storage: true
node.master: true
node.data: false


新配置 (推荐):
node.roles: [ "master" ]


迁移步骤:
1. 备份当前配置
2. 确定所需角色
3. 更新配置文件
4. 滚动重启节点
5. 验证集群状态
```