---
title: "共享数据目录配置"
date: 2026-02-09
lastmod: 2026-02-09
description: "path.shared_data 配置项用于指定使用自定义数据路径的索引的共享存储根目录。"
tags: ["Path", "数据目录", "自定义路径", "索引隔离"]
summary: "配置项作用 #  path.shared_data 配置项用于指定使用自定义数据路径的索引的共享存储根目录。
当索引使用 index.data_path 设置自定义数据路径时，该路径必须是 path.shared_data 的子路径。这允许将特定索引存储在不同的物理位置，实现数据隔离和灵活存储管理。
配置项属性 #   配置路径: path.shared_data 数据类型: String（目录路径） 默认值: 无（不配置则不允许使用自定义数据路径） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效）  配置项详解 #  工作机制 #  共享数据目录工作机制 不配置 path.shared_data: ├── 不允许使用 index.data_path ├── 所有索引存储在 path.data └── 标准存储模式 ✅ 配置 path.shared_data: path.shared_data: /shared/easysearch │ ├── 允许使用 index.data_path ├── 自定义路径必须是子路径 ├── 验证路径安全性 └── 灵活存储模式 ✅ 路径解析: index.data_path: /hot_storage/logs │ └── 实际存储路径: /shared/easysearch/hot_storage/logs/ ├── node-{nodeId}/ │ └── {indexUUID}/ │ └── {shardId}/ └── 数据文件 验证规则: ├── 自定义路径必须存在 ├── 必须是 shared_data 的子路径 ├── 防止路径遍历攻击 └── 不符合则拒绝创建索引 目录结构 #  目录结构示例 配置: path: data: /var/lib/easysearch # 默认数据目录 shared_data: /shared/easysearch # 共享数据目录 目录布局: /var/lib/easysearch/ # path."
---


## 配置项作用

`path.shared_data` 配置项用于指定**使用自定义数据路径的索引的共享存储根目录**。

当索引使用 `index.data_path` 设置自定义数据路径时，该路径必须是 `path.shared_data` 的子路径。这允许将特定索引存储在不同的物理位置，实现数据隔离和灵活存储管理。

## 配置项属性

- **配置路径**: `path.shared_data`
- **数据类型**: `String`（目录路径）
- **默认值**: 无（不配置则不允许使用自定义数据路径）
- **是否可选**: 是
- **作用域**: NodeScope（节点级别）
- **动态更新**: 否（需要重启节点生效）

## 配置项详解

## 工作机制

```
共享数据目录工作机制

不配置 path.shared_data:
├── 不允许使用 index.data_path
├── 所有索引存储在 path.data
└── 标准存储模式 ✅


配置 path.shared_data:
path.shared_data: /shared/easysearch
    │
    ├── 允许使用 index.data_path
    ├── 自定义路径必须是子路径
    ├── 验证路径安全性
    └── 灵活存储模式 ✅


路径解析:
index.data_path: /hot_storage/logs
    │
    └── 实际存储路径:
        /shared/easysearch/hot_storage/logs/
        ├── node-{nodeId}/
        │   └── {indexUUID}/
        │       └── {shardId}/
        └── 数据文件


验证规则:
├── 自定义路径必须存在
├── 必须是 shared_data 的子路径
├── 防止路径遍历攻击
└── 不符合则拒绝创建索引
```

## 目录结构

```
目录结构示例

配置:
path:
  data: /var/lib/easysearch       # 默认数据目录
  shared_data: /shared/easysearch # 共享数据目录


目录布局:
/var/lib/easysearch/             # path.data
└── nodes/
    └── 0/
        ├── indices/             # 标准索引
        │   ├── index-abc/
        │   └── index-def/
        └── ...


/shared/easysearch/              # path.shared_data
├── hot_storage/                 # 自定义路径 1
│   └── logs/
│       └── node-0/
│           └── index-xyz/       # 自定义路径索引
├── cold_storage/                # 自定义路径 2
│   └── archive/
│       └── node-0/
│           └── index-old/
└── ssd_storage/                 # 自定义路径 3
    └── realtime/
        └── node-0/
            └── index-hot/
```

## 自定义数据路径

```
索引自定义数据路径

1. 配置共享数据目录:
path:
  shared_data: /shared/easysearch


2. 创建索引时指定路径:
PUT /logs-2026
{
  "settings": {
    "index.data_path": "/hot_storage/logs"
  }
}


3. 实际存储位置:
/shared/easysearch/hot_storage/logs/
├── node-0/
│   └── {indexUUID}/
│       ├── 0/
│       │   ├── index/
│       │   └── translog/
│       └── 1/


4. 路径验证:
├── /hot_storage/logs 是
├── /shared/easysearch 的子路径
├── 验证通过 ✅
└── 索引创建成功


错误示例:
index.data_path: /other/storage
    │
    ├── 不是 /shared/easysearch 的子路径
    ├── 验证失败 ❌
    └── 拒绝创建索引
```

## 配置建议

## 生产环境（不配置）

```yaml
# 不配置，使用标准数据目录
path:
  data: /var/lib/easysearch
```

**建议**: 大多数情况下不需要配置，使用标准数据目录。

## 多存储层级

```yaml
path:
  data: /var/lib/easysearch
  shared_data: /shared/easysearch
```

**建议**: 需要分层存储时配置，如热数据/冷数据分离。

## 自定义隔离

```yaml
path:
  data: /var/lib/easysearch
  shared_data: /mnt/custom-storage
```

**建议**: 特殊隔离需求时使用。

## 代码示例

## easysearch.yml 基础配置

```yaml
path:
  shared_data: /shared/easysearch
```

## 完整路径配置

```yaml
path:
  home: /usr/share/easysearch
  data: /var/lib/easysearch
  logs: /var/log/easysearch
  shared_data: /shared/easysearch
```

## 多存储配置

```yaml
# 用于不同存储层级的共享目录
path:
  shared_data: /data/easysearch

# 热数据使用 SSD
# 冷数据使用 HDD
# 通过 index.data_path 指定
```

## 创建自定义路径索引

```yaml
# 配置共享数据目录
path:
  shared_data: /shared/easysearch

# 创建索引时指定自定义路径
PUT /hot-index
{
  "settings": {
    "index.data_path": "/ssd/hot"
  }
}

PUT /cold-index
{
  "settings": {
    "index.data_path": "/hdd/cold"
  }
}
```

## 索引模板配置

```json
PUT _index_template/hot-data-template
{
  "index_patterns": ["hot-*"],
  "template": {
    "settings": {
      "index.data_path": "/ssd/hot"
    }
  }
}

PUT _index_template/cold-data-template
{
  "index_patterns": ["cold-*"],
  "template": {
    "settings": {
      "index.data_path": "/hdd/cold"
    }
  }
}
```

## 相关配置

| 配置项 | 作用 | 默认值 |
|--------|------|--------|
| `path.shared_data` | 共享数据目录根路径 | 无 |
| `path.data` | 默认数据目录 | - |
| `index.data_path` | 索引级别的自定义路径 | - |

## 使用场景

## 热数据分离

```
热数据分离场景

配置:
path.shared_data: /data/easysearch


创建热数据索引:
PUT /realtime-logs
{
  "settings": {
    "index.data_path": "/nvme/hot"
  }
}
# 存储到: /data/easysearch/nvme/hot/...


创建冷数据索引:
PUT /archive-logs
{
  "settings": {
    "index.data_path": "/hdd/cold"
  }
}
# 存储到: /data/easysearch/hdd/cold/...


优势:
├── 热数据使用快速存储
├── 冷数据使用经济存储
├── 性能优化
└── 成本优化
```

## 多租户隔离

```
多租户隔离场景

配置:
path.shared_data: /shared/easysearch


租户 A:
PUT /tenant-a-logs
{
  "settings": {
    "index.data_path": "/tenants/a"
  }
}


租户 B:
PUT /tenant-b-logs
{
  "settings": {
    "index.data_path": "/tenants/b"
  }
}


目录结构:
/shared/easysearch/
├── /tenants/a/
│   └── node-0/tenant-a-indices/
└── /tenants/b/
    └── node-0/tenant-b-indices/


优势:
├── 物理隔离
├── 便于管理
├── 安全性高
└── 计费清晰
```

## 存储生命周期

```
存储生命周期管理

1. 新数据 (SSD)
   index.data_path: "/ssd/new"


2. 成熟数据 (SATA SSD)
   → 迁移到 "/sata/mature"


3. 归档数据 (HDD)
   → 迁移到 "/hdd/archive"


4. 删除
   → 释放存储


使用:
├── ILM 策略配合
├── 自动迁移
├── 优化成本
└── 满足性能要求
```

## 性能考虑

```
性能考虑因素

1. 存储类型
   ├── NVMe SSD: 最高性能
   ├── SATA SSD: 高性能
   ├── HDD: 低成本
   └── 混合: 平衡


2. 数据访问模式
   ├── 热数据 → 快速存储
   ├── 温数据 → 标准存储
   └── 冷数据 → 经济存储


3. 分片分配
   ├── 感知存储位置
   ├── 路由到合适节点
   └── 避免跨存储查询


4. 集群规划
   ├── 分离存储层
   ├── 专用数据节点
   └── 优化分配策略
```

## 注意事项

1. **必须配置**: 使用 `index.data_path` 前必须配置此选项。

2. **子路径限制**: 自定义路径必须是 `shared_data` 的子路径。

3. **路径验证**: 创建索引时会验证路径合法性。

4. **目录权限**: 确保运行用户有权限访问共享目录。

5. **磁盘管理**: 需要监控各个存储位置的空间使用。

6. **数据迁移**: 修改路径需要重新索引数据。

7. **备份策略**: 不同路径的索引需要分别备份。

8. **快照恢复**: 恢复时需要考虑自定义路径。

9. **故障排查**: 路径错误会导致索引创建失败。

10. **规划建议**: 提前规划存储层级和路径结构。

## 故障排查

```
常见问题排查

问题 1: 创建索引失败

错误:
"path.shared_data must be set in order to use custom data paths"


原因:
├── 未配置 path.shared_data
├── 尝试使用 index.data_path
└── 验证失败


解决:
├── 配置 path.shared_data
├── 或不使用 index.data_path
└── 重启节点


问题 2: 路径验证失败

错误:
"custom data path must be a child of path.shared_data"


原因:
├── 自定义路径不是子路径
├── 路径包含 ..
└── 安全验证失败


解决:
├── 使用相对路径
├── 确保是 shared_data 子路径
└── 验证路径格式


问题 3: 权限错误

错误:
"Permission denied"


原因:
├── 目录权限不足
├── 用户无访问权限
└── SELinux/AppArmor 限制


解决:
├── 检查目录权限
├── 修改所有者
├── 设置正确权限
└── 检查安全策略
```

## 最佳实践

```
path.shared_data 最佳实践

1. 标准部署
   ├── 不配置 shared_data
   ├── 使用 path.data
   ├── 简化维护
   └── 推荐 ✅


2. 分层存储
   ├── 规划存储层级
   ├── 明确路径结构
   ├── 配置共享根目录
   └── 使用 ILM 自动迁移


3. 多租户
   ├── 按租户划分路径
   ├── 物理隔离
   ├── 独立配额
   └── 便于管理


4. 存储规划
   ├── 提前规划容量
   ├── 预留扩展空间
   ├── 监控使用率
   └── 及时扩容


5. 安全配置
   ├── 正确设置权限
   ├── 限制访问范围
   ├── 定期审计
   └── 保护数据安全
```