ElasticSearch设置IfSeqNo/IfPrimaryTerm未触发版本冲突异常排查

问题现象 #

• ES集群版本：6.8；Java客户端版本：elasticsearch-6.6.1
• 测试逻辑：设置与目标文档当前sequence number、primary term不符的IfSeqNo和IfPrimaryTerm参数，预期触发VersionConflictEngineException
• 实际结果：Java代码中文档被正常更新，sequence number递增，未触发预期异常；同一集群使用Kibana客户端测试时，可正常触发版本冲突异常

核心排查点 #

1. 客户端与集群版本不兼容 #

ES 6.x系列中，minor版本（如6.6到6.8）的差异可能导致乐观锁校验逻辑的实现不一致。6.6版本的Java客户端在构造IfSeqNo/IfPrimaryTerm相关请求时，可能存在参数传递或序列化的bug，导致ES 6.8集群未接收到校验参数，直接跳过版本冲突检查执行更新。

2. Java代码参数设置错误 #

确认代码中是否正确调用了ifSeqNo()和ifPrimaryTerm()方法，而非误用了传统的版本号参数：

// 错误示例：使用旧版version参数，未触发seqNo/primaryTerm校验
UpdateRequest updateRequest = new UpdateRequest("test_index", "doc", "1")
    .doc(XContentFactory.jsonBuilder().field("name", "new_name"))
    .version(2);

// 正确示例：指定错误的seqNo和primaryTerm以触发冲突
UpdateRequest updateRequest = new UpdateRequest("test_index", "doc", "1")
    .doc(XContentFactory.jsonBuilder().field("name", "new_name"))
    .ifSeqNo(5)  // 与文档当前seqNo不符
    .ifPrimaryTerm(3);  // 与文档当前primaryTerm不符

3. 请求参数未被正确传递 #

开启ES集群的debug级日志，检查Java客户端发送的请求中是否包含if_seq_no和if_primary_term字段。如果请求中缺失这两个参数，ES会直接执行更新操作，不会触发版本冲突校验。

Kibana与Java客户端的差异 #

Kibana发送的是标准REST API请求，会严格携带指定的if_seq_no和if_primary_term参数，而旧版本Java客户端可能在请求序列化时遗漏这些参数，导致校验逻辑未生效。

解决方案 #

• 升级Java客户端版本至6.8.x，与ES集群版本保持一致
• 检查代码中UpdateRequest的参数设置，确保调用ifSeqNo()和ifPrimaryTerm()方法
• 开启Java客户端的请求日志（如设置org.apache.http.wire为DEBUG），确认请求体中包含if_seq_no和if_primary_term参数

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