---
title: "Elasticsearch API 兼容版本配置"
date: 2026-01-23
lastmod: 2026-01-23
description: "指定兼容的 Elasticsearch 版本号的配置说明"
tags: ["API兼容性", "Elasticsearch", "版本配置"]
summary: "配置项概述 #  elasticsearch.api_compatibility_version 配置项指定 Easysearch 兼容的 Elasticsearch 版本号。
   配置项 默认值 说明     elasticsearch.api_compatibility_version 7.10.2 ES API 兼容版本     配置说明 #  elasticsearch.api_compatibility_version #  配置项作用：指定 Easysearch 兼容的 Elasticsearch 版本号。此配置决定了 API 兼容模式下的具体行为。
默认值：7.10.2
配置类型：静态配置
取值范围：有效的 Elasticsearch 版本号（如 7.9.0, 7.10.2, 8.0.0 等）
配置格式：
# 默认配置 elasticsearch.api_compatibility_version: 7.10.2 # 指定其他版本 elasticsearch.api_compatibility_version: 7.9.0 # 指定 8.x 版本 elasticsearch.api_compatibility_version: 8.0.0  使用场景 #  Elasticsearch 7."
---


## 配置项概述

`elasticsearch.api_compatibility_version` 配置项指定 Easysearch 兼容的 Elasticsearch 版本号。

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `elasticsearch.api_compatibility_version` | 7.10.2 | ES API 兼容版本 |

---

## 配置说明

## elasticsearch.api_compatibility_version

**配置项作用**：指定 Easysearch 兼容的 Elasticsearch 版本号。此配置决定了 API 兼容模式下的具体行为。

**默认值**：`7.10.2`

**配置类型**：静态配置

**取值范围**：有效的 Elasticsearch 版本号（如 `7.9.0`, `7.10.2`, `8.0.0` 等）

**配置格式**：
```yaml
# 默认配置
elasticsearch.api_compatibility_version: 7.10.2

# 指定其他版本
elasticsearch.api_compatibility_version: 7.9.0

# 指定 8.x 版本
elasticsearch.api_compatibility_version: 8.0.0
```

---

## 使用场景

## Elasticsearch 7.10.x 兼容

```yaml
# 默认配置，兼容 ES 7.10.2
elasticsearch.api_compatibility: true
elasticsearch.api_compatibility_version: 7.10.2
```

**适用场景**：
- 从 Elasticsearch 7.10.x 迁移
- 使用 Logstash 7.10.x
- 使用 Kibana 7.10.x

## Elasticsearch 7.9.x 兼容

```yaml
elasticsearch.api_compatibility: true
elasticsearch.api_compatibility_version: 7.9.0
```

**适用场景**：
- 从 Elasticsearch 7.9.x 迁移
- 使用特定版本的 ES 客户端

## Elasticsearch 8.x 兼容

```yaml
elasticsearch.api_compatibility: true
elasticsearch.api_compatibility_version: 8.0.0
```

**适用场景**：
- 需要兼容 ES 8.x API
- 使用最新的 ES 客户端

---

## 版本选择建议

## 根据客户端版本选择

| 客户端版本 | 推荐兼容版本 | 说明 |
|-----------|-------------|------|
| ES 7.9.x | 7.9.0 | 完全兼容 7.9.x API |
| ES 7.10.x | 7.10.2 | 默认配置 |
| ES 8.0.x | 8.0.0 | 部分兼容 |

## 根据迁移场景选择

```yaml
# 从 ES 7.10 迁移
elasticsearch.api_compatibility_version: 7.10.2

# 从 ES 7.9 迁移
elasticsearch.api_compatibility_version: 7.9.0

# 测试 ES 8.x 兼容性
elasticsearch.api_compatibility_version: 8.0.0
```

---

## 推荐配置

## 从 Elasticsearch 7.10 迁移

```yaml
elasticsearch.api_compatibility: true
elasticsearch.api_compatibility_version: 7.10.2
```

## 从 Elasticsearch 7.9 迁移

```yaml
elasticsearch.api_compatibility: true
elasticsearch.api_compatibility_version: 7.9.0
```

## 新项目（无需兼容）

```yaml
elasticsearch.api_compatibility: false
# 版本配置无效，无需设置
```

---

## 注意事项

1. **重启生效**：修改此配置需要重启节点
2. **配合使用**：必须与 `elasticsearch.api_compatibility: true` 配合使用
3. **版本匹配**：选择与实际客户端版本匹配的兼容版本
4. **功能差异**：不同版本的 API 行为可能有差异
5. **测试验证**：切换版本后应充分测试