---
title: "写入悬空索引信息配置"
date: 2026-02-07
lastmod: 2026-02-07
description: "gateway.write_dangling_indices_info 配置项用于控制是否将悬空索引信息写入磁盘，帮助识别和处理孤立索引。"
tags: ["Gateway", "悬空索引", "索引元数据", "持久化"]
summary: "配置项作用 #  gateway.write_dangling_indices_info 配置项用于控制节点是否将悬空索引信息写入磁盘。
悬空索引信息是索引元数据的持久化记录，用于帮助节点识别那些存在于磁盘上但不在当前集群元数据中的索引。
配置项属性 #   配置路径: gateway.write_dangling_indices_info 数据类型: boolean 默认值: true 是否可选: 是  配置项详解 #  工作机制 #  索引创建流程 创建索引 │ ↓ 写入索引元数据 │ ├──────── write_dangling_indices_info = true（默认） │ │ │ ↓ │ 写入悬空索引信息到磁盘 │ │ │ ↓ │ [异步] 更新 dangling indices 信息 │ │ │ ↓ │ 索引可被识别和恢复 │ └──────── write_dangling_indices_info = false │ ↓ 不写入悬空索引信息 │ ↓ 删除任何现有的悬空索引信息 悬空索引信息的作用 #  场景：集群故障后重启 集群元数据 ────────→ 索引 A, C 磁盘数据 ──────────→ 索引 A, B, C 如果没有悬空索引信息: → 索引 B 无法被识别 → 需要手动处理 如果有悬空索引信息: → 索引 B 可以被自动识别 → 可以使用 _dangling API 导入 线程池管理 #  当配置启用时："
---


## 配置项作用

`gateway.write_dangling_indices_info` 配置项用于控制节点是否将**悬空索引信息**写入磁盘。

悬空索引信息是索引元数据的持久化记录，用于帮助节点识别那些存在于磁盘上但不在当前集群元数据中的索引。

## 配置项属性

- **配置路径**: `gateway.write_dangling_indices_info`
- **数据类型**: `boolean`
- **默认值**: `true`
- **是否可选**: 是

## 配置项详解

## 工作机制

```
索引创建流程

创建索引
    │
    ↓
写入索引元数据
    │
    ├──────── write_dangling_indices_info = true（默认）
    │              │
    │              ↓
    │         写入悬空索引信息到磁盘
    │              │
    │              ↓
    │         [异步] 更新 dangling indices 信息
    │              │
    │              ↓
    │         索引可被识别和恢复
    │
    └──────── write_dangling_indices_info = false
                   │
                   ↓
              不写入悬空索引信息
                   │
                   ↓
              删除任何现有的悬空索引信息
```

## 悬空索引信息的作用

```
场景：集群故障后重启

集群元数据 ────────→ 索引 A, C
磁盘数据 ──────────→ 索引 A, B, C

如果没有悬空索引信息:
    → 索引 B 无法被识别
    → 需要手动处理

如果有悬空索引信息:
    → 索引 B 可以被自动识别
    → 可以使用 _dangling API 导入
```

## 线程池管理

当配置启用时：

```java
// 创建专用线程池处理悬空索引写入
danglingIndicesThreadPoolExecutor = EsExecutors.newScaling(
    "DanglingIndices#updateTask",
    1,      // 最小线程数
    1,      // 最大线程数
    0,      // 空闲存活时间
    TimeUnit.MILLISECONDS,
    daemonThreadFactory
);
```

## 配置建议

## 生产环境（推荐）

```yaml
gateway.write_dangling_indices_info: true
```

**建议**: 保持默认值 `true`。这有助于：
- 正确处理索引元数据持久化
- 故障后自动识别孤立索引
- 提高集群的容错能力

## 特殊优化场景

```yaml
gateway.write_dangling_indices_info: false
```

**建议**: 仅在特殊情况下禁用，例如：
- 不需要悬空索引识别功能
- 使用外部元数据管理
- 特定的性能优化需求

## 代码示例

## easysearch.yml 配置

```yaml
gateway:
  # 默认配置，推荐保持
  write_dangling_indices_info: true
```

## 禁用悬空索引信息写入

```yaml
gateway:
  # 不写入悬空索引信息
  write_dangling_indices_info: false
```

## 配合自动导入使用（不推荐）

```yaml
gateway:
  # 两个配置配合使用
  write_dangling_indices_info: true
  auto_import_dangling_indices: false  # 使用 API 手动管理
```

## 相关配置

| 配置项 | 作用 | 默认值 |
|--------|------|--------|
| `gateway.auto_import_dangling_indices` | 自动导入悬空索引 | false（已弃用） |
| `gateway.write_dangling_indices_info` | 写入悬空索引信息 | true |

## 配置配合

```
write_dangling_indices_info = true
    ↓
悬空索引信息被写入磁盘
    ↓
可以使用 _dangling API 管理
    ↓
- GET _dangling（列出悬空索引）
- POST _dangling/{uuid}（导入）
- DELETE _dangling/{uuid}（删除）
```

## 悬空索引处理流程

## 1. 信息写入

```
索引创建时
    ↓
元数据写入磁盘
    ↓
悬空索引信息更新（异步）
    ↓
记录索引 UUID 和位置
```

## 2. 故障后识别

```
集群重启
    ↓
扫描磁盘索引
    ↓
对比集群元数据
    ↓
发现悬空索引
    ↓
使用 _dangling API 处理
```

## 使用场景

## 推荐启用的场景

- **生产环境**: 需要容错和数据恢复能力
- **多节点集群**: 防止节点故障导致索引丢失
- **重要数据**: 确保索引可被识别和恢复

## 可以禁用的场景

- **临时测试**: 短期测试环境
- **外部管理**: 使用其他元数据管理方案
- **特殊优化**: 特定的性能需求

## 注意事项

1. **默认启用**: 默认值为 `true`，这是推荐的设置。

2. **异步操作**: 悬空索引信息的写入是异步的，不会阻塞索引创建。

3. **线程池**: 启用时会创建专用的线程池处理写入操作。

4. **与 auto_import 的关系**:
   - `write_dangling_indices_info`: 控制信息写入
   - `auto_import_dangling_indices`: 控制自动导入（已弃用）

5. **磁盘空间**: 悬空索引信息占用少量磁盘空间。

6. **API 管理**: 启用后可以使用 `_dangling` API 管理悬空索引。

7. **删除信息**: 禁用时会删除现有的悬空索引信息。