---
title: "查询恢复状态"
date: 2026-03-24
lastmod: 2026-03-24
description: "介绍如何使用 Cat API 查询 Easysearch 集群中分片的恢复状态和进度。"
tags: ["Cat API", "分片", "恢复", "监控"]
summary: "此 API 用于显示集群中分片恢复的状态信息和进度。
API #  GET /_cat/recovery GET /_cat/recovery/{index} API 的作用 #  返回集群中分片恢复的详细信息，包括：
 恢复进度：文件和字节的恢复百分比 恢复速度：已恢复的文件数和字节数 恢复类型：节点间复制或从快照恢复 源和目标节点：恢复的源节点和目标节点信息 时间信息：恢复的开始时间、结束时间和耗时  此 API 对于监控副本分片创建、节点故障恢复、快照恢复等场景非常有用。
API 的参数 #  路由参数 #     参数 类型 是否必需 描述     index string 可选 索引名称
支持逗号分隔多个索引
支持通配符 *    查询字符串参数 #     参数 类型 是否必需 默认值 描述     active_only boolean 可选 false 是否只显示正在进行中的恢复操作   bytes string 可选 自动 字节显示单位"
---


此 API 用于显示集群中分片恢复的状态信息和进度。

## API

```
GET /_cat/recovery
GET /_cat/recovery/{index}
```

## API 的作用

返回集群中分片恢复的详细信息，包括：

- **恢复进度**：文件和字节的恢复百分比
- **恢复速度**：已恢复的文件数和字节数
- **恢复类型**：节点间复制或从快照恢复
- **源和目标节点**：恢复的源节点和目标节点信息
- **时间信息**：恢复的开始时间、结束时间和耗时

此 API 对于监控副本分片创建、节点故障恢复、快照恢复等场景非常有用。

## API 的参数

### 路由参数

| 参数 | 类型 | 是否必需 | 描述 |
|------|------|----------|------|
| `index` | string | 可选 | 索引名称<br>支持逗号分隔多个索引<br>支持通配符 `*` |

### 查询字符串参数

| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `active_only` | boolean | 可选 | false | 是否只显示正在进行中的恢复操作 |
| `bytes` | string | 可选 | 自动 | 字节显示单位<br>可选值：`b`, `kb`, `mb`, `gb`, `tb`, `pb` |
| `detailed` | boolean | 可选 | false | 是否显示更详细的恢复信息，包括物理文件列表 |
| `format` | string | 可选 | text | 响应格式<br>可选值：`json`, `yaml`, `text` |
| `h` | string | 可选 | 默认列 | 指定显示的列，逗号分隔 |
| `help` | boolean | 可选 | false | 显示帮助信息 |
| `index` | string | 可选 | 所有索引 | 限制恢复信息到特定索引 |
| `master_timeout` | time | 可选 | 30s | 等待主节点响应的超时时间 |
| `s` | string | 可选 | - | 排序列<br>支持 `:asc` 和 `:desc` |
| `time` | string | 可选 | 自动 | 时间显示单位<br>可选值：`d`, `h`, `m`, `s`, `ms`, `micros`, `nanos` |
| `v` | boolean | 可选 | false | 详细模式，显示列头 |

## 返回的字段信息

| 列名 | 别名 | 描述 |
|------|------|------|
| `index` | `i`, `idx` | 索引名称 |
| `shard` | `s`, `sh` | 分片 ID |
| `start_time` | `start`, `start_millis` | 恢复开始时间 |
| `stop_time` | `stop`, `stop_millis` | 恢复结束时间 |
| `time` | `t`, `ti` | 恢复耗时 |
| `type` | `ty` | 恢复类型（如 STORE、SNAPSHOT、PEER） |
| `stage` | `st` | 恢复阶段 |
| `source_host` | `shost` | 源主机名 |
| `source_node` | `snode` | 源节点名称 |
| `target_host` | `thost` | 目标主机名 |
| `target_node` | `tnode` | 目标节点名称 |
| `repository` | `rep` | 仓库名称（仅快照恢复） |
| `snapshot` | `snap` | 快照名称（仅快照恢复） |
| `files` | `f` | 需要恢复的文件数 |
| `files_recovered` | `fr` | 已恢复的文件数 |
| `files_percent` | `fp` | 文件恢复百分比 |
| `files_total` | `tf` | 总文件数 |
| `bytes` | `b` | 需要恢复的字节数 |
| `bytes_recovered` | `br` | 已恢复的字节数 |
| `bytes_percent` | `bp` | 字节恢复百分比 |
| `bytes_total` | `tb` | 总字节数 |
| `translog_ops` | `to` | 需要恢复的事务日志操作数 |
| `translog_ops_recovered` | `tor` | 已恢复的事务日志操作数 |
| `translog_ops_percent` | `top` | 事务日志操作恢复百分比 |

## 恢复类型说明

| 类型 | 描述 |
|------|------|
| `STORE` | 从本地存储恢复（如节点重启后） |
| `SNAPSHOT` | 从快照恢复 |
| `PEER` | 从其他节点恢复（节点间复制） |

## 恢复阶段说明

| 阶段 | 描述 |
|------|------|
| `INIT` | 初始化 |
| `INDEX` | 索引文件恢复 |
| `VERIFY_INDEX` | 验证索引 |
| `TRANSLOG` | 事务日志恢复 |
| `FINALIZE` | 完成恢复 |
| `DONE` | 恢复完成 |

## 请求示例

```bash
# 查询所有分片的恢复状态
GET /_cat/recovery

# 显示列头
GET /_cat/recovery?v

# 查询指定索引的恢复状态
GET /_cat/recovery/my-index

# 只显示正在进行中的恢复
GET /_cat/recovery?active_only=true

# 使用 JSON 格式
GET /_cat/recovery?format=json

# 只显示特定列
GET /_cat/recovery?h=index,shard,type,bytes_percent

# 按恢复百分比排序
GET /_cat/recovery?s=bytes_percent:desc

# 显示详细恢复信息
GET /_cat/recovery?detailed=true

# 设置字节单位为 GB
GET /_cat/recovery?bytes=gb
```

## 响应示例

### 文本格式（默认）

```
index shard start_time    stop_time     time type stage source_host source_node target_host target_node bytes_recovered bytes_percent
logs  0     10:30:00      10:32:15     2m15s PEER  DONE    10.0.1.10   node-1      10.0.1.11   node-2      5.2gb          100.0%
logs  1     10:31:00      -             -     PEER  INDEX   10.0.1.10   node-1      10.0.1.12   node-3      2.8gb           54.3%
```

### JSON 格式

```json
[
  {
    "index": "logs",
    "shard": "0",
    "start_time": "10:30:00",
    "stop_time": "10:32:15",
    "time": "2m15s",
    "type": "PEER",
    "stage": "DONE",
    "source_host": "10.0.1.10",
    "source_node": "node-1",
    "target_host": "10.0.1.11",
    "target_node": "node-2",
    "bytes_recovered": "5.2gb",
    "bytes_percent": "100.0%"
  }
]
```

### 快照恢复示例

```
index    shard start_time    stop_time     time   type     stage repository  snapshot  bytes_recovered bytes_percent
backup-idx 0    09:00:00      09:15:30     15m30s SNAPSHOT DONE   backup_repo snap1     50gb            100.0%
```

## 使用场景

1. **副本恢复监控**：监控副本分片的创建进度
2. **节点故障恢复**：查看故障节点分片的恢复状态
3. **快照恢复**：监控从快照恢复数据的进度
4. **性能分析**：分析恢复速度，识别瓶颈
5. **问题排查**：诊断分片无法恢复的问题

## 恢复场景

### 1. 副本分片创建
当增加副本数时，从主分片恢复到新节点：
```
type: PEER
stage: DONE -> INDEX -> TRANSLOG -> FINALIZE -> DONE
```

### 2. 节点故障恢复
节点故障后，分片恢复到其他节点：
```
type: PEER
stage: INIT -> INDEX -> VERIFY_INDEX -> TRANSLOG -> FINALIZE -> DONE
```

### 3. 从快照恢复
从备份快照恢复索引：
```
type: SNAPSHOT
repository: backup_repo
snapshot: snapshot_name
```

## 注意事项

1. 此 API 只支持 GET 方法
2. 已完成的恢复操作默认也会显示，使用 `active_only=true` 只查看进行中的
3. 恢复操作可能对集群性能产生影响，建议在低峰期进行
4. 大规模恢复时建议监控网络和磁盘 I/O
5. `detailed=true` 会返回更多详细信息，但响应时间更长

## 恢复性能优化

1. **调整恢复速度**：通过 `indices.recovery.max_bytes_per_sec` 限制恢复带宽
2. **并发控制**：通过 `cluster.routing.allocation.node_concurrent_recoveries` 控制并发恢复数
3. **分片大小**：合理规划分片大小，避免单个分片过大导致恢复时间过长
4. **网络带宽**：确保节点间有足够的网络带宽

## 最佳实践

1. **监控进度**：定期检查恢复进度，确保按预期完成
2. **设置告警**：对恢复时间超过预期的情况设置告警
3. **选择低峰期**：在大规模恢复操作时选择业务低峰期
4. **验证完成**：恢复完成后验证数据完整性
5. **备份策略**：制定合理的快照备份策略

## 相关文档

- [查询分片](./get-shard.md)
- [查询分片分配](./get-shard-allocation.md)
- [创建快照](./create-snapshot.md)
- [恢复快照](./restore-snapshot.md)