Spring Boot集成Elasticsearch实战：版本选型与查询调优避坑指南-代码聚汇网

Spring Boot集成Elasticsearch实战：版本选型与查询调优避坑指南

苏黎世贝勒爷·2026-09-22·阅读 25 GEO检测（免费）

Spring BootElasticsearch版本兼容

|难度：普通|阅读约 46 分钟

我从最开始接触这个组合到现在，前后折腾了不少项目。网上关于 Spring Boot 集成 Elasticsearch 的教程一搜一大把，但大多停留在"能跑通 Demo"的层面，一旦涉及到实际项目里的数据初始化、查询调优、版本兼容问题，就很容易翻车。

这篇博文算是我个人对这套组合的一次完整复盘，从环境准备到项目落地，再到日常运维排查，凡是实操中真正踩过的坑、验证过的方案，我都会尽量写清楚。如果你正在准备把 Elasticsearch 接入 Spring Boot 项目，或者已经接入但遇到了某些诡异问题，这篇文章值得你花几分钟从头过一遍。

1. 版本兼容是第一道坎：为什么我推荐 7.17.x 而不是最新版

很多新手接 ES 的第一反应就是去官网拉最新版，然后 Spring Boot 这边也尽量用最新依赖。这个思路在普通 Java 项目里问题不大，但在 ES 这个场景下特别容易踩雷——ES 的客户端和服务端版本兼容性非常苛刻，小版本不一致都可能引发序列化异常或者字段映射错乱。

1.1 客户端与服务端的版本匹配规则

ES 官方文档里有一句话值得反复读：客户端版本必须与服务端主版本一致，次版本尽量一致。这里的"客户端"既包括 Java High Level REST Client，也包括 Spring Data Elasticsearch 底层封装的那个 transport client。

从 7.x 开始，官方把 transport client 标记为废弃，推荐使用 Java High Level REST Client。到了 8.x，High Level REST Client 也被标记为废弃，官方主推 Elasticsearch Java API Client。这意味着如果你选 8.x 服务端，再配合 Spring Boot 2.x 项目，很容易遇到 Spring Data Elasticsearch 版本跟不上的尴尬局面。

我自己在项目里的选择是服务端 Elasticsearch 7.17.0，Spring Boot 2.7.18，Spring Data Elasticsearch 4.4.x。这套组合是目前为止我认为最稳的搭配：Spring Boot 2.7.x 还在社区维护周期内，Spring Data Elasticsearch 4.4 对 7.17 的支持非常成熟，网上遇到问题时能搜到的解决方案也最多。

1.2 为什么很多人倒在"版本太高"这个坑里

热搜词里频繁出现"springboot版本太高"，这个真实反映了用户痛点。我见过有同事直接用 Spring Boot 3.2 + Elasticsearch 8.11，结果折腾了整整两天，问题集中在几个方面：

Spring Boot 3.x 基于 Jakarta EE，很多老教程里的 javax.* 包引用全部失效
Spring Data Elasticsearch 5.x 的 API 变化较大，原来习惯的 ElasticsearchRestTemplate 还在，但部分方法签名变了
ES 8.x 默认开启安全认证，本地开发如果不关闭或者不配置用户密码，连不上是常态

所以如果你不是非要使用虚拟线程、GraalVM 这些 Spring Boot 3 的新特性，继续用 2.7.x + 7.17 的组合是最省心的。如果你用 Spring Boot 3.x，那就必须老老实实给 ES 服务端配置安全认证，用 ES 8 对应的新客户端。

提示：版本选型这件事，我的判断标准很简单——先看 Spring Data Elasticsearch 的 Release Train 对应关系，再看社区活跃度。冷门版本组合遇到问题时，Github Issue 都没人回，那种无助感真的不想再体验第二次。

1.3 本机环境准备：Windows 和 Docker 两条路线对比

Elasticsearch 安装路径主要是两种：Windows 直接解压运行，或者用 Docker 容器化部署。两条路我都试过，各有优劣。

Windows 解压版适合快速体验和学习，下载 zip 包，解压后进入 bin 目录执行 elasticsearch.bat 就能启动。但有个前提：ES 7.x 依赖 JDK 11+，虽然发行包内置了 JDK（jdk 目录），但如果你系统环境变量里配置了其他版本的 JAVA_HOME，可能会出现版本加载错乱。启动前建议检查一下日志，确保是用内置 JDK 还是系统 JDK，版本是否符合要求。

Docker 部署是我在正式项目里用的方式，好处是环境隔离、迁移方便、集群扩展容易。下面是我常用的编排配置：

yaml复制version: "3"
services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.17.0
    container_name: es7
    environment:
      - discovery.type=single-node
      - ES_JAVA_OPTS=-Xms512m -Xmx512m
    ports:
      - "9200:9200"
      - "9300:9300"
    volumes:
      - es_data:/usr/share/elasticsearch/data
  kibana:
    image: docker.elastic.co/kibana/kibana:7.17.0
    container_name: kibana
    ports:
      - "5601:5601"
    environment:
      - ELASTICSEARCH_HOSTS=http://elasticsearch:9200
    depends_on:
      - elasticsearch
volumes:
  es_data:

这里有一个很容易被忽略的点：7.x 版本开始，ES 默认开启了 bootstrap check，Docker 环境下如果没有设置 discovery.type=single-node，单节点实例会启动失败。如果你看到类似 master not discovered yet 的报错，基本就是这个问题。

内存设置也值得注意。ES_JAVA_OPTS=-Xms512m -Xmx512m 这个配置是我在开发机上的常见选择，因为 ES 默认会占用机器一半内存，如果你本机就 8G 内存，跑 IDEA、Docker、浏览器，内存很容易告急。生产环境建议根据数据量评估，但至少也要保证堆内存不超过物理内存的 50%。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. Spring Boot 项目结构与新客户端选型逻辑

环境就绪之后，进入代码层面。很多教程一上来就贴代码，但我想先讲清楚选型问题。

2.1 三种客户端，到底怎么选

Spring Boot 集成 ES 目前主要有三种方式：

Spring Data Elasticsearch：符合 Spring 生态习惯，通过 Repository 接口就能操作，CRUD 非常方便，但复杂查询支持度有限
Java High Level REST Client：官方提供的完整客户端，功能最全，但代码量稍大，且 8.x 开始废弃
Elasticsearch Java API Client：8.x 新官方客户端，基于 RestClient 封装，是未来方向，但 Spring Data 集成度还在完善中

在 7.17 + Spring Boot 2.7 的组合下，我推荐 Spring Data Elasticsearch 为主，Java High Level REST Client 为辅。日常 CRUD 用 Repository，复杂聚合和深度分页场景直接注入 ElasticsearchRestTemplate 或者自定义客户端，这样兼顾开发效率和功能完整性。

如果你的项目排期紧、团队都是 Spring 新手，就直接用 Spring Data Elasticsearch，别碰原生客户端。但如果你要做地理位置搜索、复杂分词查询、自定义评分脚本这类功能，原生客户端几乎是绕不开的，Spring Data 的抽象层反而会成为阻碍。

2.2 Maven 依赖和基础配置

我在项目里实际使用的核心依赖如下：

xml复制<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
</dependency>
<dependency>
    <groupId>org.elasticsearch.client</groupId>
    <artifactId>elasticsearch-rest-high-level-client</artifactId>
    <version>7.17.0</version>
</dependency>

这里有个细节坑：spring-boot-starter-data-elasticsearch 自身会传递引入一个 elasticsearch 版本（和 Spring Boot 版本对应），如果你额外引入 elasticsearch-rest-high-level-client 时未指定版本，Maven 会依赖仲裁选择最近版本的依赖包，可能导致版本冲突。我的习惯是显式声明 elasticsearch 坐标的版本，确保所有 ES 相关依赖统一为 7.17.0。

接下来是配置文件。这里分为两部分：Spring Data 的自动配置和自定义客户端的 Bean 声明。

yaml复制spring:
  elasticsearch:
    uris: http://localhost:9200
    connection-timeout: 3s
    read-timeout: 10s
  data:
    elasticsearch:
      repositories:
        enabled: true

另外我在配置类里显式声明了一个 RestHighLevelClient 实例，用于执行那些 Spring Data 表达不了的原生查询：

java复制@Configuration
public class ElasticsearchConfig {

    @Bean
    public RestHighLevelClient restHighLevelClient() {
        return new RestHighLevelClient(
            RestClient.builder(
                new HttpHost("localhost", 9200, "http")
            ).setRequestConfigCallback(
                requestConfigBuilder -> requestConfigBuilder
                    .setConnectTimeout(3000)
                    .setSocketTimeout(10000)
            )
        );
    }
}

注意：如果 Spring Boot 版本是 2.7.x，spring.elasticsearch.uris 和 RestHighLevelClient 可以共存，Spring Boot 会优先使用自定义 Bean。但到了 Spring Boot 3.x，RestHighLevelClient 相关类在 starter 中已经被移除，必须使用新客户端 ElasticsearchClient，这个差异迁移时务必要注意。

3. 从索引管理到高亮查询：核心操作的完整实现

基础配置完成后，进入到实际业务操作阶段。这部分我按真实项目中最高频的操作路径来梳理：索引设计、文档 CRUD、复杂查询、聚合统计。

3.1 索引设计与实体映射

ES 里的索引（Index）类比 MySQL 的数据库表，文档（Document）类比一行记录。设计索引时，第一件事是明确字段类型，尤其是字符串类型——这个决定你的字段能否被正确分词和聚合。

下面是我常用的一种商品索引实体映射写法：

java复制@Data
@Document(indexName = "product", createIndex = true)
@Setting(shards = 3, replicas = 1)
public class Product {

    @Id
    private String id;

    @MultiField(mainField = @Field(type = FieldType.Text, analyzer = "ik_max_word"),
                 otherFields = {
                    @InnerField(suffix = "keyword", type = FieldType.Keyword)
                 })
    private String name;

    @Field(type = FieldType.Text, analyzer = "ik_max_word")
    private String description;

    @Field(type = FieldType.Keyword)
    private String category;

    @Field(type = FieldType.Double)
    private Double price;

    @Field(type = FieldType.Date, format = DateFormat.date_optional_time)
    private LocalDateTime createTime;
}

这段代码里有几个值得说透的点：

@MultiField 是中文搜索场景下最常用的注解，name 字段同时生成一个 text 类型用于分词搜索，生成一个 keyword 子字段用于精确匹配和排序聚合
createIndex = true 表示项目启动时自动创建索引，开发期很方便，但生产环境建议关闭自动创建，用专门的数据迁移脚本管理索引结构
如果用了 IK 分词器，需要在 ES 服务端提前安装并配置好 IK 插件，否则 analyzer = "ik_max_word" 在自动建索引时会直接报错

关于 IK 分词器的安装也可以说两句。ES 7.17 对应要下载 elasticsearch-analysis-ik-7.17.0.zip，解压到 ES 安装目录的 plugins/ik 文件夹下，重启 ES 后通过 Kibana 的 _analyze API 验证分词效果。Docker 部署的话需要通过自定义 Dockerfile 把插件打入镜像，不能直接在容器内下载，因为容器默认没装 unzip 工具，且非交互模式下下载容易失败。

3.2 实现商品增删改查

实体映射完之后，最省事的做法是直接写一个 Repository 接口：

java复制public interface ProductRepository extends ElasticsearchRepository<Product, String> {

    List<Product> findByName(String name);

    Page<Product> findByCategory(String category, Pageable pageable);

    List<Product> findByPriceBetween(Double min, Double max);
}

Spring Data 会自动根据方法名生成查询语句，这个机制和 JPA 的 Repository 非常像。findByName 会生成一个 match query，findByPriceBetween 会生成 range query。

CRUD 操作层面，有几段高频代码值得沉淀下来复用：

java复制@Service
public class ProductService {

    @Resource
    private ProductRepository productRepository;

    @Resource
    private ElasticsearchRestTemplate restTemplate;

    public void save(Product product) {
        if (product.getId() == null) {
            product.setId(UUID.randomUUID().toString());
        }
        productRepository.save(product);
    }

    public void batchSave(List<Product> products) {
        // 批量写入性能远优于循环单体写入
        productRepository.saveAll(products);
    }

    public void delete(String id) {
        productRepository.deleteById(id);
    }

    public Product getById(String id) {
        return productRepository.findById(id).orElse(null);
    }

    public Page<Product> searchByKeyword(String keyword, int page, int size) {
        NativeSearchQuery query = new NativeSearchQueryBuilder()
                .withQuery(QueryBuilders.multiMatchQuery(keyword, "name", "description"))
                .withPageable(PageRequest.of(page, size))
                .build();
        return restTemplate.search(query, Product.class);
    }
}

这里我要专门强调一下批量写入。实际项目中如果一次导入几万条数据，千万不要用循环 save()，一条一条地调用 HTTP 接口，耗时和内存都扛不住。saveAll 底层是 bulk API，性能差距是数量级的。如果你要导的数据量达到百万级甚至更高，建议直接通过 Kibana Dev Tools 的 _bulk 接口或者 Logstash 完成全量导入，Java 客户端更适合做增量实时写入。

3.3 高亮、过滤、排序：搜索接口背后你都得会

业务搜索接口往往不只是简单匹配，还要求返回结果中命中关键词要加亮显示，这就要用到高亮查询。

这段代码是搜索模块最常见的场景，我几乎在每个项目里都会写到：

java复制public List<Map<String, Object>> searchWithHighlight(String keyword, String category, int page, int size) {
    NativeSearchQueryBuilder queryBuilder = new NativeSearchQueryBuilder();

    BoolQueryBuilder boolQuery = QueryBuilders.boolQuery();
    boolQuery.must(QueryBuilders.multiMatchQuery(keyword, "name", "description"));
    if (StringUtils.hasText(category)) {
        boolQuery.filter(QueryBuilders.termQuery("category", category));
    }
    queryBuilder.withQuery(boolQuery);

    HighlightBuilder highlightBuilder = new HighlightBuilder();
    highlightBuilder.field("name").preTags("<span style='color:red'>").postTags("</span>");
    highlightBuilder.field("description").preTags("<span style='color:red'>").postTags("</span>");
    queryBuilder.withHighlightBuilder(highlightBuilder);

    queryBuilder.withPageable(PageRequest.of(page, size));
    queryBuilder.withSort(SortBuilders.fieldSort("createTime").order(SortOrder.DESC));

    SearchHits<Product> searchHits = restTemplate.search(queryBuilder.build(), Product.class);
    return searchHits.stream().map(hit -> {
        Product product = hit.getContent();
        Map<String, Object> result = new HashMap<>();
        result.put("product", product);
        result.put("highlightName", hit.getHighlightFields().get("name"));
        result.put("highlightDesc", hit.getHighlightFields().get("description"));
        return result;
    }).toList();
}

关于高亮，有个实际使用中的建议：返回给前端的高亮字段，尽量不要直接拼 HTML 字符串，而是返回高亮片段和位置信息，让前端自己渲染。我因为在后端拼 <span> 标签吃了不少安全方面的亏，后来统一改成前后端约定好高亮格式，前端自己做展示，省心很多。

3.4 聚合统计：按分类统计商品数量

电商后台经常会遇到这类需求：统计每个分类下的商品数量，或者统计某个价格区间的商品分布。这在 ES 里对应的是聚合（Aggregation）操作，Spring Data 也支持：

java复制public Map<String, Long> countByCategory() {
    NativeSearchQuery query = new NativeSearchQueryBuilder()
            .addAggregation(AggregationBuilders.terms("category_count").field("category"))
            .withPageable(PageRequest.of(0, 1))
            .build();

    SearchHits<Product> searchHits = restTemplate.search(query, Product.class);
    Aggregations aggregations = searchHits.getAggregations();
    ParsedStringTerms terms = aggregations.get("category_count");

    Map<String, Long> categoryCountMap = new HashMap<>();
    for (Terms.Bucket bucket : terms.getBuckets()) {
        categoryCountMap.put(bucket.getKeyAsString(), bucket.getDocCount());
    }
    return categoryCountMap;
}

聚合查询的 withPageable(PageRequest.of(0, 1)) 是一个关键细节：聚合结果默认不返回命中文档，设置一个很小的分页可以减少网络开销。很多人写聚合查询时忘了这个，每个分片都把大量命中结果拉回来，浪费内存和带宽。

4. 集成期高发问题：health check failed 等报错的定位链路

搜索引擎里高频出现 e.elasticsearchrestclienthealthindicator : elasticsearch health check failed，这也是我本人第一次集成 ES 时遇到的第一个坑。这个报错本身不复杂，但它背后的原因链条很长，值得完整走一遍排查链路。

4.1 从一次启动失败说起

当时项目启动日志打完 Started Application in x.xxx seconds 之后，紧接着控制台就出现了一行红色日志：

code复制e.elasticsearchrestclienthealthindicator : elasticsearch health check failed

刚看到这个报错时，直觉反应是 ES 连接不上。于是我去确认 ES 进程是否存活、9200 端口是否监听，结果都是正常的。再把 curl localhost:9200 拿回来的 JSON 内容仔细看了一遍，发现 cluster_name 是 elasticsearch，tagline 也有，一切都没问题。

然后我又试了从 Spring Boot 容器内部 telnet 到宿主机 9200，发现网络不通。这个时候问题才浮现出来——我本地的 ES 是 Docker 容器运行的，Spring Boot 应用也是在另一个 Docker 容器里，localhost 指向的是容器自身，而不是宿主机。解决方案是把配置里的 localhost 改成 host.docker.internal，这个在 Docker Desktop 里指向宿主机。

如果你不是 Docker 环境而是直接在本机跑 Spring Boot 应用，这类问题就不会出现。但如果你用 WSL2 跑 ES，宿主访问也需要格外小心 IP 地址的问题。

4.2 版本冲突引发的字段映射异常

如果 health check 通过，但操作索引时抛类似如下的异常：

code复制java.lang.IllegalArgumentException: mapper [name] of different type, current_type [text], merged_type [keyword]

这个问题的根源通常是你改了实体类字段上的注解类型，但 ES 索引里已经存在旧字段。ES 的字段映射一旦创建，不能直接修改类型，只能删除索引重新建，或者新建一个索引并通过 reindex 迁移数据。

我是这样处理的：

开发阶段直接删除索引让它自动重建
生产环境通过 _reindex 接口从旧索引迁移到新索引，并配合 alias 实现零停机切换

删除索引的 Java 代码很简单：

java复制DeleteIndexRequest request = new DeleteIndexRequest("product");
restHighLevelClient.indices().delete(request, RequestOptions.DEFAULT);

生产环境的分阶段迁移逻辑就复杂一些，我的做法是先创建带新映射的 product_v2 索引，然后执行 reindex，确认数据无误后再把别名 product 指向新索引，最后删掉旧索引。

4.3 中文分词不生效的排查思路

搜索分词不生效的典型表现是：搜"手机壳"查不到 "手机壳黑色版" 的结果。这种问题大概率是分词器没有正确应用。

排查链路大概是这样的：

第一步，用 Kibana 的 Analyze API 测试字段分词结果：

code复制POST /product/_analyze
{
  "field": "name",
  "text": "手机壳黑色版"
}

返回结果里如果 token 是一个完整的 "手机壳黑色版"，说明 text 类型的分词器配置没生效，可能原因是你没有给 @Field 指定 analyzer = "ik_max_word"。如果返回的 token 是"手"、"机"、"壳"这样按单字切分，说明默认 standard 分词器在生效，你需要安装 IK 插件，并在 mapping 里显式指定。

实际项目里我们还遇到过一种更隐蔽的情况：索引已经通过自动建索引创建好了，但你后来在实体类上加了 IK 分词器注解，项目重启后索引不会自动更新。必须手动删除索引，或者通过 ElasticsearchTemplate 调用 indexOps.create() 强制重建。这也是为什么我在团队里反复强调，索引结构变更要走统一脚本，不能依赖 Spring Boot 重启自动生效。

4.4 深度分页导致的 OOM 场景

业务中一旦出现 Result window is too large 的报错，说明你搜索的 from + size 超过了默认 10000 的上限。

ES 的分布式架构决定了 from + size 这种分页方式在深度分页时会有巨大的性能问题：它需要从每个分片都拉取 from + size 条数据到协调节点，然后排序后丢弃前面的 from 条。如果一台机器上聚集了百万级数据，深度分页甚至可能引发协调节点的内存溢出。

解决这个问题的两个主流方案，我都实际验证过：

Scroll API：适合导出全量数据、后台批处理，但不是实时数据的好选择，因为快照是数据源在查询时刻的视图
Search After API：适合前端页面无级滚动加载。实现思路是请求时携带上一页返回的 sort 值，下一页用这个值作为 search_after 参数继续搜索。这也是我能推荐大家采用的方案。

Search After 在 Spring Data 里的实现如下：

java复制public SearchHits<Product> searchAfter(String keyword, Object[] searchAfterValues, int size) {
    NativeSearchQueryBuilder queryBuilder = new NativeSearchQueryBuilder()
            .withQuery(QueryBuilders.matchQuery("name", keyword))
            .withPageable(PageRequest.of(0, size))
            .withSort(SortBuilders.fieldSort("createTime").order(SortOrder.DESC))
            .withSort(SortBuilders.fieldSort("_id").order(SortOrder.ASC));

    if (searchAfterValues != null) {
        queryBuilder.withSearchAfter(List.of(searchAfterValues));
    }

    return restTemplate.search(queryBuilder.build(), Product.class);
}

注意使用 Search After 时，排序必须包含一个唯一值字段（比如 _id），否则相同 createTime 的多条数据可能出现分页重复或跳页。

4.5 集群健康状态监控看什么

最后聊聊运营层面的监控。集成完成后，运维阶段最应该关注的就是集群健康状态。

一个判断集群健康的核心依据是 _cluster/health 接口的三个状态值：

状态	含义	是否需要处理
green	所有主分片和副本分片都正常	无需处理
yellow	主分片正常，但副本分片未分配	需要关注，常见于单节点集群，副本无处可放
red	存在不可用的主分片	必须立即处理，可能丢数据

你可以用 Spring Boot Actuator 暴露 ES 健康检查端点，这也是 health check failed 这条日志的来源。生产环境我建议让运维将 ES 集群的健康状态接入告警平台，一旦状态从 green 掉到 yellow 持续几分钟就通知相关人员排查，而不是等用户反馈搜索异常后再去补救。

5. 隔离环境到生产部署：我从 Docker Compose 到 Kubernetes 的迁移心得

这一节单独拿出来写，是因为很多项目在本地联调都好好的，一到部署阶段就各种怪问题。ES 在容器化环境里的坑，基本都和数据持久化、资源配置有关。

5.1 本地联调阶段的容器编排方案

本地开发我用 Docker Compose 起一套 ES + Kibana，配置前面已经贴过了。这里补充一个重要细节：如果你把 ES 的 data 挂载到宿主机目录，一定要给这个目录设置权限，否则 ES 容器会以 uid 1000 运行，遇到 Permission denied 错误起不来。

bash复制mkdir -p /opt/es-data
chown -R 1000:1000 /opt/es-data

这个权限问题在 Windows 的 Docker Desktop 上不常见，但在 Linux 服务器上几乎是必踩的坑。

如果你想限制日志占用磁盘空间，还需要在 ES 的 log4j2.properties 里调整滚动策略，或者在 Docker 层面限制日志文件大小。我在生产环境里是这样配置的：

yaml复制logging:
  driver: json-file
  options:
    max-size: "100m"
    max-file: "3"

5.2 上生产的资源规划

ES 是一个吃内存的应用。我在项目中见过太多因为堆内存设置不合理导致的频繁 Full GC，最终表现为查询时快时慢，偶尔还连接超时。

判断 ES 堆内存设置是否合理，可以从两个维度观察：

堆内存使用率是否长期维持在 70% 以上并伴随频繁 GC
JVM 老年代回收频率，如果频繁触发 CMS/G1 的 Full GC，说明堆太小或者字段 mapping 设计有问题

一个容易被忽略的冷知识是：ES 堆内存不要超过 31GB。这个数值来源于 JVM 的压缩指针机制，超过后对象指针不再压缩，内存利用率反而下降。所以物理机内存如果到 64G，分配给 ES 堆 31G 后，其余留给 Lucene 做文件缓存。

5.3 从单节点到多节点的平滑扩展

项目初期单节点就够用，但数据量增长后，单节点的写入和查询吞吐量都会成为瓶颈。扩容到多节点时，有几个地方需要注意：

节点角色要明确划分：master 节点负责集群管理，data 节点负责数据存储和查询，ingest 节点负责数据预处理。不建议把所有角色堆在一起，尤其是 master 和数据混合部署会导致集群脑裂风险升高
集群最少要有 3 个 master 候选节点，否则网络分区时无法选出新主节点
通过 discovery.seed_hosts 配置节点发现地址，在容器环境里这四个配置最容易出错

用 Docker Compose 搭一个 3 节点的 ES 集群比较繁琐，我实际生产环境用的是 Kubernetes + ECK Operator 管理，这里不展开，但核心配置思路相同：每个节点通过环境变量指定 node.roles，数据节点挂载单独的 PVC，master 节点使用稳定的无状态服务。

从单节点升级到多节点其实是一个平滑的过程，ES 会自动搬迁分片，但对业务的影响取决于数据量和分片大小。建议在业务低峰期操作，同时提前将 cluster.routing.allocation.enable 设置为 none，等所有节点加入集群后再恢复为 all，避免大规模分片迁移抢占带宽影响正常查询。

回看整个集成过程，我觉得最核心的经验其实是那句话：Elasticsearch 不只是一个"搜索引擎"，它是一套完整的分布式数据基础设施。 你在 Spring Boot 里写的那几行调用代码只是冰山一角，真正决定项目成败的往往是底层的版本选型、索引设计、资源规划和异常处理。希望我这篇基于真实踩坑经历汇总的文章，能帮你少绕几圈弯路。