---
title: "导入悬空索引"
date: 2026-01-31
lastmod: 2026-01-31
description: "将悬空索引导入回集群"
tags: ["索引", "集群", "故障恢复"]
summary: "将指定的悬空索引导入回集群，恢复其元数据和可用性。
API 格式 #  POST /_dangling/{index_uuid} 注意：API 路径使用 index_uuid 而非 index_name。
API 作用 #  该 API 用于将悬空索引导入回集群。悬空索引是指在磁盘上存在但未在集群状态中注册的索引。该 API 允许管理员恢复这些索引。
API 参数 #  路径参数 #     参数 类型 是否必填 默认值 描述     {index_uuid} String 是 - 要导入的悬空索引的 UUID    查询参数 #     参数 类型 是否必填 默认值 描述     accept_data_loss Boolean 是 false 必须设置为 true 以确认接受数据丢失风险   timeout Time 否 请求超时 操作的超时时间   master_timeout Time 否 主节点超时 等待主节点响应的超时时间    请求示例 #  导入悬空索引 #  POST /_dangling/abc123-def456-ghi789-jkl012?"
---


将指定的悬空索引导入回集群，恢复其元数据和可用性。

## API 格式

```
POST /_dangling/{index_uuid}
```

**注意**：API 路径使用 `index_uuid` 而非 `index_name`。

## API 作用

该 API 用于将悬空索引导入回集群。悬空索引是指在磁盘上存在但未在集群状态中注册的索引。该 API 允许管理员恢复这些索引。

## API 参数

### 路径参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `{index_uuid}` | String | **是** | - | 要导入的悬空索引的 UUID |

### 查询参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `accept_data_loss` | Boolean | **是** | `false` | 必须设置为 `true` 以确认接受数据丢失风险 |
| `timeout` | Time | 否 | 请求超时 | 操作的超时时间 |
| `master_timeout` | Time | 否 | 主节点超时 | 等待主节点响应的超时时间 |

## 请求示例

### 导入悬空索引

```
POST /_dangling/abc123-def456-ghi789-jkl012?accept_data_loss=true
```

### 设置超时时间

```
POST /_dangling/abc123-def456-ghi789-jkl012?accept_data_loss=true&timeout=60s
```

## 响应示例

### 成功响应

```
200 OK
```

```json
{
  "acknowledged": true
}
```

### 错误响应

```json
{
  "error": {
    "type": "illegal_argument_exception",
    "reason": "accept_data_loss must be set to true"
  }
}
```

### 未找到悬空索引

```json
{
  "error": {
    "type": "illegal_argument_exception",
    "reason": "No dangling index found for UUID [abc123-def456-ghi789-jkl012]"
  }
}
```

## 响应字段说明

| 字段 | 类型 | 描述 |
|------|------|------|
| `acknowledged` | Boolean | 导入操作是否被确认执行 |

## 处理流程

1. **请求验证**：检查提供的索引 UUID 是否对应实际的悬空索引
2. **安全确认**：验证 `accept_data_loss` 标志是否设置为 `true`
3. **元数据选择**：如果多个节点拥有同一索引的元数据，选择版本最高的
4. **索引分配**：`LocalAllocateDangledIndices` 服务执行实际分配
5. **返回确认**：成功后返回 `acknowledged: true`

## 内部处理细节

- **多节点处理**：API 搜索所有节点的悬空索引元数据
- **版本选择**：当多个节点有同一索引的元数据时，自动选择最高版本
- **分配服务**：由 `LocalAllocateDangledIndices` 服务执行实际分配操作

## 错误场景

| 错误 | 原因 | 解决方法 |
|------|------|----------|
| `accept_data_loss must be set to true` | 未设置确认标志 | 在查询参数中添加 `accept_data_loss=true` |
| `No dangling index found for UUID` | 未找到对应的悬空索引 | 使用 `GET /_dangling` 查询可用的悬空索引 |
| `Connection failure` | 节点连接失败 | 检查网络连接和节点状态 |

## 相关操作

- **GET /_dangling**：查询所有悬空索引
- **DELETE /_dangling/{index_uuid}**：删除悬空索引

## 使用场景

1. **故障恢复**：在集群元数据丢失后恢复索引
2. **节点重新加入**：将离线节点的索引重新集成到集群
3. **数据恢复**：从备份的索引文件恢复数据

## 注意事项

1. **数据丢失风险**：导入操作可能导致数据冲突或丢失，需谨慎操作
2. **必须确认**：必须显式设置 `accept_data_loss=true` 作为安全保护
3. **UUID 识别**：使用索引 UUID 而非名称进行导入
4. **版本选择**：多节点元数据时自动选择最高版本
5. **分配时间**：大型索引的分配可能需要较长时间

## API 规范说明

该 API 在 REST API 规范中的定义为：
- 规范文件：`rest-api-spec/api/dangling_indices.import_dangling_index.json`
- 实际端点：`POST /_dangling/{index_uuid}`
- 返回类型：`AcknowledgedResponse`