此 API 用于显示集群中分片恢复的状态信息和进度。
API #
GET /_cat/recovery
GET /_cat/recovery/{index}
API 的作用 #
返回集群中分片恢复的详细信息，包括：
- 恢复进度：文件和字节的恢复百分比
- 恢复速度：已恢复的文件数和字节数
- 恢复类型：节点间复制或从快照恢复
- 源和目标节点：恢复的源节点和目标节点信息
- 时间信息：恢复的开始时间、结束时间和耗时
此 API 对于监控副本分片创建、节点故障恢复、快照恢复等场景非常有用。
API 的参数 #
路由参数 #
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
index | string | 可选 | 索引名称 支持逗号分隔多个索引 支持通配符 * |
查询字符串参数 #
| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|---|
active_only | boolean | 可选 | false | 是否只显示正在进行中的恢复操作 |
bytes | string | 可选 | 自动 | 字节显示单位 可选值： b, kb, mb, gb, tb, pb |
detailed | boolean | 可选 | false | 是否显示更详细的恢复信息，包括物理文件列表 |
format | string | 可选 | text | 响应格式 可选值： json, yaml, text |
h | string | 可选 | 默认列 | 指定显示的列，逗号分隔 |
help | boolean | 可选 | false | 显示帮助信息 |
index | string | 可选 | 所有索引 | 限制恢复信息到特定索引 |
master_timeout | time | 可选 | 30s | 等待主节点响应的超时时间 |
s | string | 可选 | - | 排序列 支持 :asc 和 :desc |
time | string | 可选 | 自动 | 时间显示单位 可选值： 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 | 恢复完成 |
请求示例 #
# 查询所有分片的恢复状态
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 格式 #
[
{
"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. 副本分片创建 #
当增加副本数时，从主分片恢复到新节点：
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
注意事项 #
- 此 API 只支持 GET 方法
- 已完成的恢复操作默认也会显示，使用
active_only=true只查看进行中的 - 恢复操作可能对集群性能产生影响，建议在低峰期进行
- 大规模恢复时建议监控网络和磁盘 I/O
detailed=true会返回更多详细信息，但响应时间更长
恢复性能优化 #
- 调整恢复速度：通过
indices.recovery.max_bytes_per_sec限制恢复带宽 - 并发控制：通过
cluster.routing.allocation.node_concurrent_recoveries控制并发恢复数 - 分片大小：合理规划分片大小，避免单个分片过大导致恢复时间过长
- 网络带宽：确保节点间有足够的网络带宽
最佳实践 #
- 监控进度：定期检查恢复进度，确保按预期完成
- 设置告警：对恢复时间超过预期的情况设置告警
- 选择低峰期：在大规模恢复操作时选择业务低峰期
- 验证完成：恢复完成后验证数据完整性
- 备份策略：制定合理的快照备份策略
