# Reindex from Remote 注意事项（官方文档要点）

基于 Elasticsearch 官方文档整理的 **Reindex from remote** 要点，用于从远程 ES 集群（如 8.x）迁移数据到本机集群（如 9.x）。

## 官方文档入口

- [Reindex API (current)](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html)
- [Reindex from remote (upgrade)](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/reindex-upgrade-remote.html)
- [REST API: Reindex](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/reindex-indices)

---

## 必须注意的事项

### 1. 目标集群白名单（必须）

> If reindexing from a remote cluster into a cluster using Elastic Stack, you must **explicitly allow the remote host** using the **`reindex.remote.whitelist`** node setting on the **destination** cluster.

- **在目标集群（本机 ES）** 的 `elasticsearch.yml` 中配置，不是源集群。
- 格式：只写 **host:port**，多个用逗号分隔；不写协议。例如：
  ```yaml
  reindex.remote.whitelist: "120.76.41.98:9200"
  ```
- 修改后需重启**执行 reindex 的节点**（通常是协调节点）才能生效。

### 2. 目标索引需事先创建

- Reindex **不会**复制源索引的 **settings / mappings**。
- 目标索引的 mapping、分片数、副本数等需在调用 `_reindex` **之前**在本机创建好。
- 可用本项目的 `mappings/search_products.json` 在本机创建同名索引。

### 3. 权限要求

- **源集群（远程）** 用于认证的用户（如 `source.remote.username`）需要：
  - 集群权限：`monitor`
  - 源索引权限：`read`
- **目标集群（本机）** 执行 reindex 的用户需要：
  - 目标索引：`write`
  - 若需自动创建目标索引：`auto_configure` 或 `create_index` 或 `manage`

### 4. 源文档必须开启 _source

- Reindex 依赖文档的 `_source` 字段；若源索引禁用了 `_source`，无法 reindex。

### 5. 远程 Reindex 不支持 Slicing

- 文档明确说明：**Reindexing from remote clusters does not support manual or automatic slicing.**
- 不能通过 `slices` 或 `slice` 做并行加速，只能单任务拉取。

### 6. 远程拉取时的缓冲区与 batch size

- 从远程 reindex 时，目标集群使用 **on-heap buffer**，默认最大约 **100MB**。
- 若单文档很大，需在 `source` 里调小 **`size`**（每批文档数），例如 `"size": 500` 或 `200`，避免 OOM。
- 默认 `size` 为 1000。

### 7. max_docs 与 conflicts

- 用 **`max_docs`** 可限制只迁移前 N 条（注意：与 scroll 顺序不保证严格一致，但数量正确）。
- 若设置 **`conflicts: "proceed"`**，在遇到版本冲突时仍会继续，但可能从源多读一些文档直到成功写入 `max_docs` 条。

### 8. 建议在源索引为 green 时执行

- 官方建议在源索引状态为 green 时 reindex，否则节点宕机等可能导致失败。
- 若使用 `wait_for_completion=false`，可通过 Task API 查进度；重试时可能需要先删掉目标索引中部分数据或设置 `conflicts=proceed`。

### 9. 超时（可选）

- `source.remote.socket_timeout`、`connect_timeout` 可调大，默认约 30s；大批量或网络慢时可适当增加。

---

## 示例：从远程 tenant_170 同步 10000 条到本机 tenant_0

- **源**：远程 `search_products_tenant_170`（约 39731 条）
- **目标**：本机索引 `search_products_tenant_0`，只同步 **10000 条**

### 步骤 1：在本机 ES 配置白名单

在**本机** ES 的 `elasticsearch.yml` 中添加（或合并到已有 `reindex.remote.whitelist`）：

```yaml
reindex.remote.whitelist: "120.76.41.98:9200"
```

保存后重启本机 ES（或至少重启会执行 reindex 的节点）。

### 步骤 2：在本机创建目标索引

使用本项目 mapping 创建索引 `search_products_tenant_0`（若已存在且结构一致可跳过）。例如用 API：

```bash
# 本机 ES（按需加 -u user:pass）
curl -X PUT 'http://localhost:9200/search_products_tenant_0?pretty' \
  -H 'Content-Type: application/json' \
  -d @mappings/search_products.json
```

或通过项目代码：`create_index_if_not_exists(es_client, "search_products_tenant_0", load_mapping())`。

### 步骤 3：在本机执行 Reindex（请求发往本机 ES）

以下请求是发给**本机 ES**（例如 `http://localhost:9200`），由本机去拉远程数据。

```bash
# 请求发往本机 ES（ES 9.x 将 wait_for_completion 放在 query 参数）
curl -X POST 'http://localhost:9200/_reindex?wait_for_completion=true&pretty' \
  -H 'Content-Type: application/json' \
  -d '{
  "max_docs": 10000,
  "source": {
    "remote": {
      "host": "http://120.76.41.98:9200",
      "username": "essa",
      "password": "4hOaLaf41y2VuI8y"
    },
    "index": "search_products_tenant_170",
    "size": 500
  },
  "dest": {
    "index": "search_products_tenant_0"
  }
}'
```

说明：

- `max_docs: 10000`：最多写入 10000 条到目标。
- `source.remote`：远程 ES 地址与认证（仅本机连远程时使用，不会把密码发到远程）。
- `source.index`：远程索引名。
- `source.size`：每批从远程拉取的文档数，500 可降低大文档时本机内存压力。
- `dest.index`：本机目标索引名。
- `wait_for_completion: true`：同步等待完成；数据量大可改为 `false`，用返回的 `task_id` 查进度：`GET _tasks/<task_id>`。

### 步骤 4：校验条数

```bash
curl -X GET 'http://localhost:9200/search_products_tenant_0/_count?pretty' \
  -H 'Content-Type: application/json' \
  -d '{"query":{"match_all":{}}}'
```

预期约 10000 条（若未设 `max_docs` 则会与源索引条数一致）。

### 一键脚本（可选）

项目内提供了脚本，可自动创建目标索引并执行上述 reindex（默认 10000 条，目标 `search_products_tenant_0`）：

```bash
# 确保本机 .env 中 ES_HOST 指向本机 ES（如 http://localhost:9200）
chmod +x scripts/reindex_from_remote_tenant_170_to_0.sh
./scripts/reindex_from_remote_tenant_170_to_0.sh
```

可通过环境变量覆盖：`REMOTE_ES_HOST`、`REMOTE_ES_USER`、`REMOTE_ES_PASS`、`MAX_DOCS`、`LOCAL_ES_HOST`。详见脚本注释。

---

## 小结

| 项目 | 说明 |
|------|------|
| 白名单 | 在**目标（本机）** ES 的 `elasticsearch.yml` 中配置 `reindex.remote.whitelist` |
| 目标索引 | 事先在本机创建好 mapping/settings |
| 远程权限 | 源集群用户需 `monitor` + 源索引 `read` |
| 限条数 | 使用 `max_docs`，例如 10000 |
| 大批/大文档 | 适当调小 `source.size`（如 500） |
| 并行 | 远程 reindex 不支持 `slices` |