为标注@Entity的JPA实体添加@Document注解后启动报连接超时如何解决

异常引发原因 #

该异常与你同时为实体类添加@Entity和@Document注解没有直接关联，报错根因是Spring Data Elasticsearch初始化Repository时，无法连接配置的Elasticsearch服务，触发了默认5000ms的连接超时，常见触发场景如下：

• 本地未启动Elasticsearch服务，或服务启动失败
• Elasticsearch服务实际监听端口不是9200，或绑定的地址不支持localhost访问
• 本地防火墙、代理规则拦截了9200端口的请求
• Elasticsearch开启了身份认证、HTTPS，配置类中未补充对应认证参数
• Spring Data Elasticsearch版本与Elasticsearch服务版本不兼容，导致握手失败

解决方案 #

1. 先解决Elasticsearch连接问题 #

• 首先验证服务可用性：在本地执行curl http://localhost:9200，如果能正常返回包含ES版本号的JSON响应，说明服务运行正常，否则先启动Elasticsearch服务。
• 检查ES配置文件elasticsearch.yml中的network.host、http.port配置，确保和你配置类中的地址一致。
• 按需调整客户端配置，补充认证、超时参数，参考配置如下：

@Configuration
@EnableElasticsearchRepositories("br.com.gwcloud.smartplace.catalog.elasticsearch.repositories")
public class ElasticSearchConfig {    
    @Bean
    public RestHighLevelClient client() {
        ClientConfiguration clientConfiguration 
            = ClientConfiguration.builder()
                .connectedTo("localhost:9200")
                // 若ES开启用户名密码认证，补充该配置
                .withBasicAuth("elastic", "你的ES密码")
                // 若ES开启HTTPS，补充该配置
                .usingSsl()
                // 调整超时时间避免短超时误杀
                .withConnectTimeout(Duration.ofSeconds(10))
                .withSocketTimeout(Duration.ofSeconds(30))
                .build();

        return RestClients.create(clientConfiguration).rest();
    }    
    @Bean
    public ElasticsearchOperations elasticsearchTemplate() {
        return new ElasticsearchRestTemplate(client());
    }    
}

• 校验Spring Data Elasticsearch与ES服务的版本匹配关系，大版本必须一致，比如ES服务是7.17.x，对应的Spring Data Elasticsearch版本也需要是4.4.x版本。

2. 实体类优化（可选但强烈推荐） #

虽然当前报错和双注解无关，但不建议直接复用JPA实体作为ES的文档实体，后续容易出现字段映射、序列化冲突问题，建议拆分两类实体：

• 保留原有带@Entity注解的JPA实体用于数据库操作
• 单独定义带@Document注解的ES专属实体，数据同步时做两类实体的属性转换即可

内容的提问来源于stack exchange，提问作者leorosignoli