---
title: "获取升级状态"
date: 2026-01-16
lastmod: 2026-01-16
description: "获取索引的 Lucene 段升级状态"
tags: ["集群", "索引", "升级"]
summary: "获取一个或多个索引的 Lucene 段升级状态，用于监控由 POST /_upgrade API 发起的索引升级进度。
API 格式 #  GET /_upgrade GET /{index}/_upgrade API 作用 #  该 API 用于检查索引中需要升级的 Lucene 段的大小和状态。升级过程会将旧版本的 Lucene 段格式转换为当前版本，以确保兼容性和性能。
API 参数 #  路径参数 #     参数 类型 是否必填 默认值 描述     {index} String 否 - 逗号分隔的索引名称列表。如未指定，则检查所有索引的升级状态    查询参数 #     参数 类型 是否必填 默认值 描述     index String 否 - 逗号分隔的索引名称列表（与路径参数作用相同）   level String 否 indices 响应的详细级别。可选值："
---


获取一个或多个索引的 Lucene 段升级状态，用于监控由 POST /_upgrade API 发起的索引升级进度。

## API 格式

```
GET /_upgrade
GET /{index}/_upgrade
```

## API 作用

该 API 用于检查索引中需要升级的 Lucene 段的大小和状态。升级过程会将旧版本的 Lucene 段格式转换为当前版本，以确保兼容性和性能。

## API 参数

### 路径参数

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

### 查询参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `index` | String | 否 | - | 逗号分隔的索引名称列表（与路径参数作用相同） |
| `level` | String | 否 | `indices` | 响应的详细级别。可选值：<br>- `indices`（默认）：仅返回索引级别信息<br>- `shards`：包含分片级别的详细信息 |

## 响应示例

```json
{
  "size_in_bytes": "10b",
  "size_to_upgrade": "10b",
  "size_to_upgrade_ancient": "0b",
  "indices": {
    "my_index": {
      "size_in_bytes": "10b",
      "size_to_upgrade": "10b",
      "size_to_upgrade_ancient": "0b",
      "shards": {
        "0": [
          {
            "size_in_bytes": "10b",
            "size_to_upgrade": "10b",
            "size_to_upgrade_ancient": "0b",
            "routing": {
              "state": "STARTED",
              "primary": true,
              "node": "node_id",
              "relocating_node": null
            }
          }
        ]
      }
    }
  }
}
```

## 响应字段说明

### 顶层字段

| 字段 | 类型 | 描述 |
|------|------|------|
| `size_in_bytes` | String | 所有索引的总字节大小 |
| `size_to_upgrade` | String | 需要升级的总字节数 |
| `size_to_upgrade_ancient` | String | 来自旧版本（ancient）段的需要升级的总字节数 |

### indices 对象

包含每个索引的信息，键为索引名称：

| 字段 | 类型 | 描述 |
|------|------|------|
| `size_in_bytes` | String | 该索引的字节大小 |
| `size_to_upgrade` | String | 该索引需要升级的字节数 |
| `size_to_upgrade_ancient` | String | 该索引来自旧版本段的需要升级的字节数 |

### shards 对象（当 `level=shards` 时）

包含每个分片的信息：

| 字段 | 类型 | 描述 |
|------|------|------|
| `size_in_bytes` | String | 该分片的字节大小 |
| `size_to_upgrade` | String | 该分片需要升级的字节数 |
| `size_to_upgrade_ancient` | String | 该分片来自旧版本段的需要升级的字节数 |
| `routing.state` | String | 分片当前状态（如 STARTED） |
| `routing.primary` | Boolean | 是否为主分片 |
| `routing.node` | String | 托管该分片的节点 ID |
| `routing.relocating_node` | String/null | 如果分片正在迁移，则为目标节点 ID，否则为 null |

## 注意事项

1. 该 API 为只读监控 API，不会修改任何数据
2. 升级操作由 POST /_upgrade API 发起
3. 响应会同时显示总升级需求和旧版本段的升级需求
4. 旧版本（ancient）段通常指来自主要版本差异较大的 Lucene 版本的段