failed to load role query - 角色查询加载失败 | Easysearch | 分布式搜索引擎

适用版本： 7.6-8.9

1. 错误异常的基本描述 #

Failed to load role query 出现在安全授权链路里。源码在 bitsetCache.getBitSet(roleQuery, in.getContext()) 和 getNumDocs 过程中捕获异常，再包装成当前错误。这说明问题通常发生在 DLS（Document Level Security，文档级安全）角色查询的解析、重写或位集构建阶段。

这不是"认证失败"，而是"授权过滤查询构建失败"。

常见现象 #

只有开启文档级权限控制（DLS）的用户访问时失败，普通用户或超级用户不一定复现。
某些角色访问特定索引时报错，说明角色查询与索引 mapping 或数据状态有关。
安全审计日志可能同时出现角色解析、授权过滤或查询重写相关线索。
用户在执行搜索、获取文档等操作时收到 403 Forbidden 或 500 Internal Server Error。
Elasticsearch 日志中可以看到 Failed to load role query 关键字，伴随 QueryShardException 或 IOException。

典型报错与异常栈 #

常见日志形态通常类似下面这样：

ElasticsearchSecurityException: Failed to load role query
Caused by: org.elasticsearch.common.io.stream.NotSerializableExceptionWrapper: query_shard_exception: failed to create query
	at org.elasticsearch.xpack.security.support.RoleQueryBitSetCache...

或者字段不存在：

ElasticsearchSecurityException: Failed to load role query
Caused by: java.lang.IllegalArgumentException: unknown field [non_existent_field]
	at org.elasticsearch.index.mapper.MapperService...

或者查询解析错误：

ElasticsearchSecurityException: Failed to load role query
Caused by: org.elasticsearch.index.query.QueryShardException: failed to parse query
	at org.elasticsearch.index.query.QueryDSLParsers...

2. 为什么会发生这个错误 #

Failed to load role query 的根因是"DLS 角色查询无法被正确解析或执行"。Elasticsearch 的安全机制支持通过角色定义中的 query 字段来限制用户只能看到符合特定条件的文档（文档级安全）；如果角色查询有问题，就会导致授权过滤失败。

常见原因通常包括：

角色查询 DSL 不合法：角色里定义的查询 DSL 语法错误，或者查询结构不符合 Elasticsearch 查询规范。
字段引用不存在：角色查询引用了当前索引不存在的字段，或者字段名拼写错误。
字段类型不兼容：角色查询依赖的字段类型、脚本或查询能力与目标索引不兼容（如 text 字段用于 term 查询）。
DLS 查询上下文异常：查询在当前上下文重写后触发异常，例如 nested、runtime field 或 join 场景。
角色定义与索引不匹配：角色定义是为某个索引设计的，但被应用到了其他 mapping 不同的索引上。
缓存未更新：角色定义变更后缓存未及时更新，或不同节点上的安全配置存在漂移。
复杂查询问题：nested 查询、script 查询、join 查询等在 DLS 上下文中可能有限制或不支持。
权限冲突：角色中同时定义了 DLS 和 FLS（Field Level Security），可能存在冲突。

3. 如何排查和解决这个异常和解决这个异常 #

建议按"先导出角色定义、再验证查询 DSL、后检查 mapping 兼容性"的顺序处理：

导出问题角色定义：导出问题角色定义，重点检查 query 字段中的完整 DSL。

# 查看所有角色
curl -X GET "localhost:9200/_security/role?pretty"
   
# 查看特定角色定义
curl -X GET "localhost:9200/_security/role/my_role?pretty"

角色定义中的 DLS 查询示例：

{
  "my_role": {
    "indices": [
      {
        "names": ["my_index"],
        "privileges": ["read"],
        "query": {
          "term": { "status": "active" }
        }
      }
    ]
  }
}

验证查询 DSL：在目标索引上用同一查询单独执行，验证是否能脱离安全模块正常解析。

# 使用 _validate API 验证查询
curl -X GET "localhost:9200/my_index/_validate/query?explain=true" -H 'Content-Type: application/json' -d'
{
  "query": {
    "term": { "status": "active" }
  }
}
'
   
# 直接执行查询测试
curl -X GET "localhost:9200/my_index/_search" -H 'Content-Type: application/json' -d'
{
  "query": {
    "term": { "status": "active" }
  }
}
'

检查索引 mapping：对照 _mapping 检查角色查询引用的字段、nested path 和字段类型。

# 查看索引 mapping
curl -X GET "localhost:9200/my_index/_mapping?pretty"
   
# 检查特定字段的定义
curl -X GET "localhost:9200/my_index/_mapping/field/status?pretty"

查看审计日志：查看审计日志与服务日志，确认异常发生在查询解析、位集构建还是文档计数阶段。
```
# 查看安全审计日志（如果启用）
grep -r "role query\|DLS\|authorization" /var/log/elasticsearch/
```

检查角色更新和缓存：如果角色最近被修改，确认缓存已刷新，且所有节点使用一致的安全配置。

# 清除角色缓存（如果需要）
curl -X POST "localhost:9200/_security/role/my_role/_clear_cache?pretty"
   
# 查看所有节点的角色缓存状态
curl -X GET "localhost:9200/_security/_query/cache?pretty"

排查时需要注意的问题 #

这个错误是授权查询问题，不是认证问题，需要重点关注角色定义和索引 mapping，而不是用户凭证。
如果问题只在某些用户或某些索引上出现，很可能是角色定义与索引 mapping 不匹配，需要对比角色查询和索引结构。
DLS 查询有一些限制（如不支持某些特殊查询类型），需要参考官方文档确认查询的合法性。
角色定义中的查询是在每个索引上单独解析的，如果角色应用到多个索引，需要确保所有索引都支持该查询。

4. 如何解决这个错误 #

常用修复思路 #

修正角色查询 DSL：修正角色查询 DSL，避免引用不存在或不兼容的字段。

# 更新角色定义，修正查询
curl -X PUT "localhost:9200/_security/role/my_role" -H 'Content-Type: application/json' -d'
{
  "indices": [
    {
      "names": ["my_index"],
      "privileges": ["read"],
      "query": {
        "term": { "status": "active" }  # 确保字段存在且类型正确
      }
    }
  ]
}
'

简化复杂查询：简化高风险 DLS 查询，先保证可解析和可执行，再逐步恢复复杂条件。

// 错误示例（引用不存在的字段）
{
  "query": {
    "term": { "non_existent_field": "value" }
  }
}
  
// 正确示例
{
  "query": {
    "bool": {
      "must": [
        { "term": { "status": "active" } },
        { "range": { "created_at": { "gte": "now-30d" } } }
      ]
    }
  }
}

建立测试用例：对经常变更的角色查询建立测试用例，避免错误 DSL 直接上线。

# 在测试环境验证角色查询
# 创建测试角色
curl -X PUT "localhost:9200/_security/role/test_role" -H 'Content-Type: application/json' -d'
{
  "indices": [
    {
      "names": ["test_index"],
      "privileges": ["read"],
      "query": { "match_all": {} }
    }
  ]
}
'

同步索引 mapping 变更：当索引 mapping 演进时，同步回收或升级历史角色中的旧字段引用。
```
# 更新角色以适配新的 mapping
# 例如：字段类型从 keyword 改为 text，需要调整查询方式
```

检查 nested 和 join 查询：如果角色查询涉及 nested 或 join 类型，确保查询格式正确。

// nested 查询示例
{
  "query": {
    "nested": {
      "path": "comments",
      "query": { "term": { "comments.author": "john" } }
    }
  }
}

后续注意事项与推荐建议 #

在更新角色定义前，先在测试环境验证查询 DSL 的正确性和执行效果。
为角色定义建立版本管理和审批流程，记录每次角色变更的内容和原因。
定期审查角色定义，清理不再使用的旧字段引用或过时的查询条件。
在应用层测试角色权限，确保 DLS 查询按预期工作，用户只能看到应该看到的文档。
为 DLS 相关错误配置专门的监控和告警，在角色查询失败时及时通知。

借助 INFINI 产品提升排障效率 #

INFINI Console 适合查看集群的安全配置、角色定义、用户权限和错误趋势，帮助快速定位 Failed to load role query 是角色定义问题、mapping 问题还是查询上下文问题，并提供可视化的角色管理和审计功能。
INFINI Gateway 可以记录所有搜索请求的详细日志，帮助定位 DLS 查询失败的具体环节，同时提供请求审计功能，记录哪些用户访问了哪些数据。
建议将角色查询成功率、DLS 错误和安全审计日志统一接入监控面板，结合 INFINI Console 的告警功能，在角色查询失败时及时通知管理员。

5. 小结 #

Failed to load role query 的重点不在"认证失败"，而在"授权过滤查询构建失败"。只要把角色 DSL、目标索引 mapping 和 DLS 执行上下文对齐，通常就能定位问题。大多数情况下，这个问题可以通过修正角色查询、验证字段存在性和确保查询兼容性来解决。

只要把角色定义校验、mapping 管理和查询测试固定下来，大多数角色查询加载类异常都可以被有效预防，也更容易通过 INFINI Console 和 INFINI Gateway 实现持续防护。

参考文档 #

附：日志上下文 #

下面保留当前页面中的源码或日志片段，便于继续结合异常调用栈定位问题：

assert Transports.assertNotTransportThread("resolving role query");
try {
    roleQueryBits = bitsetCache.getBitSet(roleQuery, in.getContext());
    numDocs = getNumDocs(in, roleQuery, roleQueryBits);
} catch (Exception e) {
    throw new ElasticsearchException("Failed to load role query", e);
}

标签

failed to load role query - 角色查询加载失败