Elasticsearch 需要复制/迁移索引…

当需要把文档从源索引或数据流复制/迁移到目标索引，并可能改映射、过滤子集或转换数据时，按本地/远程、切片、限流、任务跟踪与计数校验流程执行 Elasticsearch reindex。

适用场景

解决思路

1. 通过 `elastic` CLI 执行所有 Elasticsearch 操作；若未安装 `elastic` CLI，先告知用户它用于执行这些操作，不要直接调用 HTTP API，也不要猜凭据或尝试其他绕过方式。
2. 调用 `elastic es info`（对应 `GET /`）确认连通性，读取 `build_flavor` 与 `version.number`，据此判断 shard、replica、cluster-settings API 是否可用；Serverless 内部管理 shards/replicas 且阻止多数 `_cluster/*` API。若调用失败则停止，不猜端点或凭据。
3. 比较源与目标位置（需知道 source index name(s)、destination index name、是否共享集群）：同一集群用 local reindex，只在请求中设置 `source.index` 和 `dest.index`，不要添加 `source.remote`；不同集群用 reindex from remote，在 `source.remote` 中添加远端集群 URL 和凭据。
4. 若是 remote reindex，确认远端 host 已在 Self-Managed / Elastic Cloud Hosted 上加入白名单（集群配置中的 `reindex.remote.whitelist`）；Serverless 内部管理白名单（仅支持 Elastic Cloud Hosted remotes，Tech Preview）。remote reindex 不支持 slicing，改用基于 query 的分区（如日期范围、term 过滤）跨并行请求补偿。
5. 检查源索引，不要猜字段名或数量：调用 `elastic es indices get-mapping --index '<source>'`（对应 `GET /{source}/_mapping`）获取字段名和类型；调用 `elastic es count --index '<source>'`（对应 `GET /{source}/_count`）或 `elastic es cat count --index '<source>' --h count`（对应 `GET /_cat/count/{source}?h=count`）获取文档数。
6. 根据源检查结果选择复制范围：全量复制时省略 `source.query`（默认 match-all）；过滤子集时添加 `source.query` 并使用 Query DSL。时间范围用 timestamp 字段（常见为 `@timestamp`）上的 `range` 过滤，例如 `gte: '2025-01-01'`、`lt: '2025-02-01'` 表示 2025 年 1 月。用户要求日期范围或其他过滤时，不要运行全索引复制。
7. 复制前准备目标索引：`_reindex` 不会复制 mappings、shard counts 或 analyzers；通过 `elastic es indices create --index '<dest>' --mappings '<json>' --settings '<json>'`（对应 `PUT /{dest}`）用显式 settings 和从源 mapping 派生的 mappings 创建目标。不要依赖自动创建和 dynamic mapping；错误或缺失 mappings 会导致部分失败或静默类型强转。
8. 在 Self-Managed / Elastic Cloud Hosted 上，复制期间在目标索引设置 `number_of_replicas: 0` 和 `refresh_interval: "-1"` 以提升写入吞吐；复制后用 `elastic es indices put-settings --index '<dest>' --settings '<json>'`（对应 `PUT /{dest}/_settings`）恢复生产值。
9. 在 Serverless 上，创建目标索引时省略 `number_of_shards` 和 `number_of_replicas`（由 Elastic 管理）；复制期间可设置 `refresh_interval: "-1"`。
10. 若目标是 data stream：确保存在带 `data_stream: {}` 的 index template，创建 data stream，并在 reindex 请求中设置 `dest.op_type` 为 `"create"`（append-only）。
11. 构建并提交 reindex 请求：对可能超过几秒或大索引的复制，调用 `elastic es reindex --wait-for-completion false --source '<json>' --dest '<json>'`（对应 `POST /_reindex?wait_for_completion=false`），立即获取 task id 而不是阻塞。
12. reindex 请求体要点：正确设置 `source.index`（源索引或 data stream，不要与 `dest.index` 颠倒）；`dest.index` 用已准备的目标；仅在选择过滤子集时包含 `source.query`；重试部分完成的 reindex 时设置 `conflicts: "proceed"`。
13. 可选调优参数：`source.size`（批量大小）、`requests_per_second`（限流）、`slices=auto`（仅 local reindex，按 primary shard 并行，绝不要用于 remote）、`scroll`（慢集群增加 keep-alive）、`max_docs`（测试运行）、`script`（转换）、`dest.pipeline`（ingest 富化）。
14. 过滤子集示例：`{"source":{"index":"eval-reindex-src","query":{"range":{"@timestamp":{"gte":"2025-01-01","lt":"2025-02-01"}}}},"dest":{"index":"eval-reindex-jan"}}`。
15. 当任务是过滤子集复制或直接文档迁移时，不要使用 `_split`、`_shrink` 或 snapshot/restore，这些 API 解决不同问题。
16. 跟踪任务到完成：保存 reindex 响应中的 task id；轮询 `elastic es tasks get --task-id '<task_id>'`（对应 `GET /_tasks/{task_id}`）直到 `completed` 为 `true`；读取 `status.total`、`status.created` 和 `response.failures`。
17. 在 Self-Managed / Elastic Cloud Hosted 上可用 `elastic es tasks list --actions '*reindex' --detailed`（对应 `GET /_tasks?actions=*reindex&detailed`）列出活动 reindex 任务；Serverless 仅能按 task id 查询（不能列出/取消）；取消任务用 `elastic es tasks cancel --task-id '<task_id>'`（对应 `POST /_tasks/{task_id}/_cancel`）。
18. 运行中调整限流：调用 `elastic es reindex-rethrottle --task-id '<task_id>' --requests-per-second <N>`（对应 `POST /_reindex/{task_id}/_rethrottle?requests_per_second=N`），无需取消任务。
19. 验证并报告目标计数：调用 `elastic es count --index '<dest>'`（对应 `GET /{dest}/_count`，适用于所有部署类型）；在 Self-Managed / ECH 也可用 `elastic es cat count --index '<dest>' --h count`（对应 `GET /_cat/count/{dest}?h=count`）。将源过滤预期与目标计数比较，报告目标索引的精确计数，不要估算或猜测。
20. 成功全量复制后，用 `elastic es indices put-settings --index '<dest>' --settings '<json>'`（对应 `PUT /{dest}/_settings`）恢复目标生产设置：Self-Managed / ECH 恢复 replicas 和 refresh interval；Serverless 只恢复 refresh interval。
21. 优先考虑替代方案：当 runtime fields、aliases 或 snapshot/restore 合适时，用它们避免完整 reindex。
22. 大复制并行化：local reindex 用 `slices=auto`，并用 `requests_per_second` 限流保护集群。
23. 大作业异步运行：用 `wait_for_completion=false` 提交并轮询任务，不要阻塞。
24. 按计数验证：比较源过滤预期与目标 `GET /{dest}/_count` 的精确结果，绝不估算。

适用边界 · 注意事项

• 当 runtime fields、aliases 或 snapshot/restore 已能解决问题时，不要做 reindex：字段类型不匹配或需计算字段且存储值无需改变用 runtime fields；只需透明重定向查询用 aliases；Self-Managed / ECH 上无需转换的整索引传输用 snapshot and restore。
• 过滤子集复制或直接文档迁移时，不要用 `_split`、`_shrink` 或 snapshot/restore；remote reindex 不要用 slicing。
• Serverless 上不适用：不要设置 `number_of_shards`/`number_of_replicas`，不要用 `PUT /_cluster/settings`，不要列出/取消 `_tasks`（仅按 task id 查询），不要用 `_split`/`_shrink`；remote reindex 仅为 Tech Preview 且仅支持 ECH remotes。