---
title: "升级索引"
date: 2026-01-10
lastmod: 2026-01-10
description: "升级索引的 Lucene 段到当前版本"
tags: ["集群", "索引", "升级", "Lucene"]
summary: "升级 Easysearch 索引中的 Lucene 段到当前版本。在升级 Easysearch 版本后，旧索引可能包含旧版本的 Lucene 段，需要升级以确保兼容性和性能。
API 格式 #  POST /_upgrade POST /{index}/_upgrade API 作用 #  该 API 用于将索引中的 Lucene 段升级到当前版本。升级过程会重写 Lucene 段，使其与当前版本兼容。
API 参数 #  路径参数 #     参数 类型 是否必填 默认值 描述     {index} String 否 - 逗号分隔的索引名称列表。如未指定，则升级所有索引    查询参数 #     参数 类型 是否必填 默认值 描述     only_ancient_segments Boolean 否 false 是否只升级旧版本（ancient）的 Lucene 段。"
---


升级 Easysearch 索引中的 Lucene 段到当前版本。在升级 Easysearch 版本后，旧索引可能包含旧版本的 Lucene 段，需要升级以确保兼容性和性能。

## API 格式

```
POST /_upgrade
POST /{index}/_upgrade
```

## API 作用

该 API 用于将索引中的 Lucene 段升级到当前版本。升级过程会重写 Lucene 段，使其与当前版本兼容。

## API 参数

### 路径参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `{index}` | String | 否 | - | 逗号分隔的索引名称列表。如未指定，则升级所有索引 |

### 查询参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `only_ancient_segments` | Boolean | 否 | `false` | 是否只升级旧版本（ancient）的 Lucene 段。<br>- `false`（默认）：升级所有段<br>- `true`：仅升级来自旧版本 Lucene 的段 |

## 响应示例

```json
{
  "acknowledged": true,
  "total_shards": 10,
  "successful_shards": 10,
  "failed_shards": 0,
  "upgraded_indices": {
    "my_index": {
      "upgrade_version": "7.10.0",
      "oldest_lucene_segment_version": "8.0.0"
    },
    "another_index": {
      "upgrade_version": "7.10.0",
      "oldest_lucene_segment_version": "8.0.0"
    }
  }
}
```

## 响应字段说明

| 字段 | 类型 | 描述 |
|------|------|------|
| `acknowledged` | Boolean | 升级请求是否被确认 |
| `total_shards` | Integer | 处理的分片总数 |
| `successful_shards` | Integer | 成功升级的分片数量 |
| `failed_shards` | Integer | 升级失败的分片数量 |
| `upgraded_indices` | Object | 包含每个已升级索引信息的对象 |
| `upgraded_indices.{index_name}.upgrade_version` | String | 执行升级的 Easysearch 版本 |
| `upgraded_indices.{index_name}.oldest_lucene_segment_version` | String | 升级后最旧的 Lucene 段版本 |

## 执行要求

1. **所有主分片必须可用**：升级开始前，API 会检查所有主分片是否可用
2. **无写阻塞**：集群不能有全局或元数据写阻塞
3. 如果任何主分片缺失，API 将抛出 `PrimaryMissingActionException`

## 升级过程

1. **验证**：检查所有主分片是否可用
2. **分片级操作**：在每个分片上单独执行升级
3. **强制合并**：对每个分片调用 `forceMerge`，参数包括：
   - `forceMerge(true)`：合并后强制刷新
   - `maxNumSegments = Integer.MAX_VALUE`：合并段但不一定创建单个段
   - `expungeDeletes = false`：不删除已删除的文档
   - `upgradeOnlyAncientSegments`：根据请求参数决定是否只升级旧版本段
4. **元数据更新**：成功升级分片后，更新索引元数据中的版本信息

## 使用场景

- 升级 Easysearch 版本后，确保旧索引与当前版本兼容
- 优化使用旧 Lucene 版本创建的索引性能
- 确保所有索引使用当前 Lucene 版本以获得最佳性能和兼容性

## 注意事项

1. 升级操作会消耗较多资源，建议在低峰期执行
2. 升级过程中索引仍然可用，但性能可能受影响
3. 升级大型索引可能需要较长时间
4. 可以使用 GET /_upgrade API 监控升级进度