网站导航
> 技术文档 > 【Elasticsearch】Elasticsearch 快照恢复 API 参数详解_elasticsearch 快照还原的时候,过滤索引

【Elasticsearch】Elasticsearch 快照恢复 API 参数详解_elasticsearch 快照还原的时候,过滤索引

网友: 技术文档 2025-07-30 13:34:55

《Elasticsearch 集群》系列，共包含以下文章：

  • 1️⃣ 冷热集群架构
  • 2️⃣ 合适的锅炒合适的菜：性能与成本平衡原理公式解析
  • 3️⃣ ILM（Index Lifecycle Management）策略详解
  • 4️⃣ Elasticsearch 跨机房部署
  • 5️⃣ 快照与恢复功能详解
  • 6️⃣ Elasticsearch 快照恢复 API 参数详解
  • 7️⃣ 安全地删除快照仓库、快照
  • 8️⃣ 快照生命周期管理 SLM（理论篇）
  • 9️⃣ 快照生命周期管理 SLM（实战篇）
  • 🔟 跨集群检索（Cross-Cluster Search）

😊 如果您觉得这篇文章有用 ✔️ 的话，请给博主一个一键三连 🚀🚀🚀 吧 （点赞 🧡、关注 💛、收藏 💚）！！！您的支持 💖💖💖 将激励 🔥 博主输出更多优质内容！！！

Elasticsearch 快照恢复 API 参数详解

  • 1.三个核心参数说明
    • 1.1 indices
    • 1.2 rename_pattern
    • 1.3 rename_replacement
  • 2.实际测试组合案例
    • 📌 组合用例 1：恢复特定索引
    • 📌 组合用例 2：使用通配符恢复
    • 📌 组合用例 3：排除特定索引
    • 📌 组合用例 4：复杂重命名
    • 📌 组合用例 5：恢复并添加前缀
    • 📌 组合用例 6：恢复并添加环境前缀
    • 📌 组合用例 7：恢复并移除日期后缀
    • 📌 组合用例 8：恢复并交换索引名结构
    • 📌 组合用例 9：恢复并只保留部分索引
    • 📌 组合用例 10：恢复并合并多个索引
    • 📌 组合用例 11：恢复并排除某些索引
    • 📌 组合用例 12：恢复并替换索引名中的特定字符串
    • 📌 组合用例 13：恢复并仅保留索引的最后一部分
    • 📌 组合用例 14：恢复并转换为小写
    • 📌 组合用例 15：恢复并添加时间戳
    • 📌 总结
  • 3.注意事项
  • 4.命名规范
    • 4.1 索引命名规范的强制性要求
    • 4.2 防止正则表达式滥用
    • 4.3 跨平台兼容性
    • 4.4 安全性与注入防御
    • 4.5 用户体验与调试友好性
    • 4.6 实际案例：违反限制的后果
    • 4.7 总结

1.三个核心参数说明

1.1 indices

作用：指定要从快照中恢复哪些索引

输入限制：

  • 支持逗号分隔的索引名称列表
  • 可以使用通配符（*）匹配多个索引
  • 可以排除特定索引（使用减号前缀，如 -index_name）
  • 如果未指定，默认恢复快照中的所有索引

1.2 rename_pattern

作用：定义用于匹配要重命名索引的正则表达式模式

输入限制：

  • 必须是与索引名称匹配的有效正则表达式
  • 使用 Java 正则表达式语法
  • 只有当同时设置了 rename_replacement 时才有效

1.3 rename_replacement

作用：定义如何重命名与 rename_pattern 匹配的索引

输入限制：

  • 可以包含对正则表达式捕获组的引用（如$1，$2等）
  • 必须与 rename_pattern 配对使用
  • 不能为空

2.实际测试组合案例

📌 组合用例 1：恢复特定索引

POST /_snapshot/my_repository/my_snapshot_1/_restore{ \"indices\": \"index1,index2\"}

效果：只从快照中恢复 index1 和 index2，其他索引不恢复

📌 组合用例 2：使用通配符恢复

POST /_snapshot/my_repository/my_snapshot_1/_restore{ \"indices\": \"logstash-2023-*\", \"rename_pattern\": \"logstash-(.+)\", \"rename_replacement\": \"restored-$1\"}

效果：

  • 恢复所有以 logstash-2023- 开头的索引
  • 将它们重命名为 restored-2023-... 格式
  • 例如 logstash-2023-01 → restored-2023-01

如果将 rename_replacement 从 \"restored-$1\" 改为 \"$1-restored\"，恢复后的索引名称会将原始匹配的部分放在前面，然后添加 -restored 后缀。下面是一个具体示例：

POST /_snapshot/my_repository/my_snapshot_1/_restore{ \"indices\": \"logstash-2023-*\", \"rename_pattern\": \"logstash-(.+)\", \"rename_replacement\": \"$1-restored\"}

假设快照中包含以下索引：

  • logstash-2023-01
  • logstash-2023-02
  • logstash-2023-03

恢复后的新索引名称：

  • logstash-2023-01 → 2023-01-restored
    • 正则匹配：logstash-(.+) 捕获组 $1 = 2023-01
    • 替换为 $1-restored = 2023-01-restored
  • logstash-2023-02 → 2023-02-restored
  • logstash-2023-03 → 2023-03-restored

关键点解析

  • 正则捕获组 (.+)：
    • 匹配 logstash- 之后的所有字符（如 2023-01），并保存到 $1。
  • 替换逻辑：
    • \"$1-restored\" 表示将捕获的内容放在前面，后接 -restored。
    • 如果原始索引名有更多层级（如 logstash-2023-01-detail），也会被完整捕获到 $1 中，结果类似 2023-01-detail-restored。

注意事项

  • 索引名合法性：
    • 确保 $1 不包含非法字符（如空格、大写字母），否则恢复会失败。
    • 例如，如果原始索引名是 logstash-2023_ERROR，捕获的 $1=2023_ERROR 包含大写字母，重命名后会因非法名称报错。
  • 避免冲突：
    • 如果目标集群已存在同名索引（如 2023-01-restored），恢复操作会失败，除非设置 include_aliases 或强制覆盖。

📌 组合用例 3：排除特定索引

POST /_snapshot/my_repository/my_snapshot_1/_restore{ \"indices\": \"*,-.kibana*\"}

效果：

  • 恢复除 .kibana 开头的系统索引外的所有索引

📌 组合用例 4：复杂重命名

POST /_snapshot/my_repository/my_snapshot_1/_restore{ \"indices\": \"prod-*\", \"rename_pattern\": \"prod-(.*)-(v\\\\d+)\", \"rename_replacement\": \"test-$1-$2\"}

效果：

  • 恢复所有以 prod- 开头的索引
  • 将命名模式从 prod--v 改为 test--v
  • 例如 prod-users-v2 → test-users-v2

📌 组合用例 5：恢复并添加前缀

POST /_snapshot/my_repository/my_snapshot_1/_restore{ \"indices\": \"orders-*\", \"rename_pattern\": \"(.+)\", \"rename_replacement\": \"backup-$1\"}

效果：

  • 恢复所有 orders- 开头的索引
  • 为每个恢复的索引添加 backup- 前缀
  • 例如 orders-2023 → backup-orders-2023

📌 组合用例 6：恢复并添加环境前缀

场景：从生产快照恢复数据到测试环境，并添加 test_ 前缀。

POST /_snapshot/my_repo/my_prod_snapshot/_restore{ \"indices\": \"orders-*,users-*\", \"rename_pattern\": \"(.+)\", \"rename_replacement\": \"test_$1\"}

效果：

  • orders-2023 → test_orders-2023
  • users-2023 → test_users-2023

📌 组合用例 7：恢复并移除日期后缀

场景：恢复日志索引，但去掉日期部分（如 -202301）。

POST /_snapshot/my_repo/my_log_snapshot/_restore{ \"indices\": \"app_logs-*\", \"rename_pattern\": \"app_logs-(\\\\d+)-(.*)\", \"rename_replacement\": \"restored_logs-$2\"}

效果：

  • app_logs-202301-error → restored_logs-error
  • app_logs-202301-info → restored_logs-info

📌 组合用例 8：恢复并交换索引名结构

场景：将 {service}-{env}-{date} 格式的索引改为 {env}-{service}-{date}。

POST /_snapshot/my_repo/my_service_snapshot/_restore{ \"indices\": \"payment-prod-*,order-dev-*\", \"rename_pattern\": \"(.*)-(.*)-(.*)\", \"rename_replacement\": \"$2-$1-$3\"}

效果：

  • payment-prod-202301 → prod-payment-202301
  • order-dev-202301 → dev-order-202301

📌 组合用例 9：恢复并只保留部分索引

场景：只恢复特定索引，并重命名为 backup_{index}。

POST /_snapshot/my_repo/my_full_snapshot/_restore{ \"indices\": \"customer_data,product_catalog\", \"rename_pattern\": \"(.*)\", \"rename_replacement\": \"backup_$1\"}

效果：

  • customer_data → backup_customer_data
  • product_catalog → backup_product_catalog

📌 组合用例 10：恢复并合并多个索引

场景：将多个索引合并成一个新索引（如 logs-202301，logs-202302 → all_logs）。

POST /_snapshot/my_repo/my_logs_snapshot/_restore{ \"indices\": \"logs-*\", \"rename_pattern\": \"logs-.*\", \"rename_replacement\": \"all_logs\"}

效果：

  • logs-202301 → all_logs
  • logs-202302 → all_logs

⚠️ 注意：如果多个索引匹配，Elasticsearch 会依次恢复并覆盖 all_logs，最终只保留最后一个索引的数据。

📌 组合用例 11：恢复并排除某些索引

场景：恢复所有索引，但排除 system_* 和 .kibana*。

POST /_snapshot/my_repo/my_full_snapshot/_restore{ \"indices\": \"*,-system_*,-.kibana*\"}

效果：

  • 恢复所有索引，但跳过 system_* 和 .kibana*（如 .kibana_1 不会被恢复）。

📌 组合用例 12：恢复并替换索引名中的特定字符串

场景：将索引名中的 old_cluster 替换为 new_cluster。

POST /_snapshot/my_repo/my_old_snapshot/_restore{ \"indices\": \"old_cluster-*\", \"rename_pattern\": \"old_cluster-(.*)\", \"rename_replacement\": \"new_cluster-$1\"}

效果：

  • old_cluster-logs → new_cluster-logs
  • old_cluster-metrics → new_cluster-metrics

📌 组合用例 13：恢复并仅保留索引的最后一部分

场景：从 {env}-{service}-{id} 格式的索引中只保留 {service} 部分。

POST /_snapshot/my_repo/my_microservice_snapshot/_restore{ \"indices\": \"prod-*-*\", \"rename_pattern\": \".*-(.*)-.*\", \"rename_replacement\": \"$1\"}

效果：

  • prod-payment-123 → payment
  • prod-order-456 → order

📌 组合用例 14：恢复并转换为小写

场景：某些索引可能有大写字母（如 TempData），恢复时强制转为小写。

POST /_snapshot/my_repo/my_legacy_snapshot/_restore{ \"indices\": \"TempData,UserLogs\", \"rename_pattern\": \"(.*)\", \"rename_replacement\": \"$1\"}

效果：

  • TempData → tempdata（Elasticsearch 自动转小写）
  • UserLogs → userlogs

📌 组合用例 15：恢复并添加时间戳

场景：恢复索引并添加当前日期（如 restored_20230101）。

POST /_snapshot/my_repo/my_backup_snapshot/_restore{ \"indices\": \"important_data\", \"rename_pattern\": \"(.*)\", \"rename_replacement\": \"restored_$1_20230101\"}

效果：

  • important_data → restored_important_data_20230101

📌 总结

场景 indices rename_pattern rename_replacement 效果 添加环境前缀 orders-* (.+) test_$1 orders-2023 → test_orders-2023 移除日期后缀 app_logs-* app_logs-\\\\d+-(.*) restored_logs-$1 app_logs-202301-error → restored_logs-error 交换索引结构 payment-prod-* (.*)-(.*)-(.*) $2-$1-$3 payment-prod-2023 → prod-payment-2023 合并多个索引 logs-* logs-.* all_logs logs-202301 → all_logs 替换字符串 old_cluster-* old_cluster-(.*) new_cluster-$1 old_cluster-logs → new_cluster-logs

🚀 这些组合可以灵活应用于 数据迁移、环境同步、索引重构 等场景。你可以根据自己的需求调整正则表达式和替换规则！

3.注意事项

  • rename_pattern 和 rename_replacement 必须同时使用或同时省略。
  • 重命名操作是在索引恢复后进行的，不影响快照中的原始名称。
  • 确保新索引名称符合 Elasticsearch 的命名规则（不能包含大写字母、空格等特殊字符）。
  • 恢复操作需要目标集群有足够的资源。
  • 重命名时要注意避免与现有索引名称冲突。

这些参数组合提供了灵活的恢复策略，特别适合在不同环境（如从生产环境恢复到测试环境）之间迁移数据时使用。

4.命名规范

在 Elasticsearch 中，对 rename_pattern 和 rename_replacement 参数施加字符长度限制（如 0~1024 个字符）和字符类型限制（禁用空格、大写字母和特殊字符如 \\|?/）是出于多方面的技术考虑和安全设计。

4.1 索引命名规范的强制性要求

Elasticsearch 对索引名称有严格的限制，这些限制直接传递到重命名参数上：

  • 禁止大写字母：Elasticsearch 索引名称强制要求小写（例如 my_index 合法，My_Index 非法）。如果允许 rename_replacement 生成大写字母，会导致索引创建失败。
  • 禁止特殊字符：字符如 \\|?/ 在文件系统、URL 或 Lucene 内部处理中可能有特殊含义（例如 / 是路径分隔符，? 是查询参数标识）。禁止这些字符可避免：
    • 文件系统路径冲突（索引数据需要持久化到磁盘）。
    • REST API 的 URL 解析错误（如 GET /my/_search 会引发语法错误）。
    • Lucene 引擎的潜在解析问题。

4.2 防止正则表达式滥用

  • 长度限制（1024 字符）：过长的正则表达式可能导致：
    • 性能问题：复杂或超长的正则匹配会消耗大量 CPU 资源，尤其在恢复大量索引时。
    • ReDoS（正则拒绝服务）攻击风险：恶意用户可能提交精心构造的正则表达式，触发极端回溯行为，拖慢集群响应。
  • 字符限制：禁用某些特殊字符（如 \\）可以限制正则表达式的复杂度，避免用户使用高危模式（如递归匹配、回溯陷阱等）。

4.3 跨平台兼容性

索引名称可能用于：

  • 文件系统路径（如 Linux / Windows 对文件名合法字符的要求不同）。
  • 网络传输（如 URL 编码、JSON 解析）。
  • 第三方工具集成（如 Kibana、Logstash 等对索引名的假设）。

统一的命名规则可以确保 Elasticsearch 在不同环境中行为一致。

4.4 安全性与注入防御

  • 避免路径遍历攻击：如果允许 / 或 ..，用户可能通过重命名构造恶意路径（如 rename_replacement: \"../../malicious\"），尝试访问或覆盖系统文件。
  • 防止 Shell 注入：如果索引名通过脚本间接使用（如 curl 命令生成），特殊字符可能导致命令注入。

4.5 用户体验与调试友好性

  • 简单的命名规则减少用户因拼写错误（如误输入空格或引号）导致恢复失败。
  • 明确的错误提示（如 “invalid index name” 比 “不明原因的正则匹配失败” 更易排查）。

4.6 实际案例：违反限制的后果

假设允许大写字母和特殊字符：

{ \"rename_pattern\": \"prod_(.*)\", \"rename_replacement\": \"TEST_$1/../\"}

可能的故障：

  • 生成索引名 TEST_DATA/../ 违反文件系统路径规则。
  • 如果通过 API 访问 GET /TEST_DATA/../_search，可能被解析为路径遍历攻击。
  • 集成工具（如 Kibana）可能无法正确显示包含大写字母的索引名。

4.7 总结

这些限制是 Elasticsearch 在 安全性、稳定性 和 跨平台兼容性 之间权衡的结果。虽然可能显得严格，但它们：

  • 预防常见的安全漏洞（如路径遍历、ReDoS）。
  • 确保集群在各类环境下可靠运行。
  • 降低用户因命名不规范导致的操作失败风险。

如果用户需要更灵活的命名规则，通常建议在应用层预处理索引名，而非依赖 Elasticsearch 的动态重命名功能。

网络标签：

相关问题