在共享的Elasticsearch集群中，多个团队或租户常常共用同一套索引，但需要严格限制每个用户只能查看属于自己的数据。例如，销售团队的成员不应该看到财务部门的合同文档，而客服人员只能访问与自己工单相关的记录。这种“按文档内容进行授权”的需求，正是文档级安全（Document Level Security，简称DLS）的核心场景。DLS允许管理员在角色定义中绑定一条查询语句，当用户执行搜索时，Elasticsearch会自动将该查询作为过滤条件追加到原始请求之后，确保返回结果中只包含被授权的文档。接下来，我们将深入探讨DLS的实现机制、配置方法以及性能考量。
DLS的实现原理与安全模型区别
文档级安全并不是在索引写入时对文档做物理隔离，而是基于查询时的动态过滤。在Elasticsearch的安全体系中，一个角色（Role）可以包含索引权限、集群权限以及文档级查询条件。当用户绑定了具备DLS规则的角色后，所有发往目标索引的搜索请求都会经过安全拦截器，在协调节点阶段将角色中定义的查询语句（通常是一个bool查询或term查询）作为filter上下文注入到原始查询中。这种注入发生在Lucene执行查询之前，因此即使用户尝试通过脚本、聚合或直接访问底层分片，也无法绕过过滤条件。
与索引级安全（Index Level Security）和字段级安全（Field Level Security，FLS）相比，DLS的粒度更细。索引级安全控制用户能否访问某个索引的整体，FLS则限制用户只能看到文档中的部分字段，而DLS则是在文档维度上进行筛选，允许同一个索引中同时存储多个租户的数据，但每个租户只能检索到属于自己的子集。三者可以组合使用，形成多层防护。例如，一个角色可以同时配置：只允许访问“orders”索引，只能看到字段“customer_id”“amount”“order_date”，并且只能检索“customer_id”等于当前用户所属客户ID的文档。这种组合方式在SaaS类应用中非常常见。
从底层原理来看，DLS生成的过滤条件会被转换为Lucene的布尔查询，并通过缓存机制提升重复查询的性能。不过需要注意的是，DLS中的查询语句是在角色定义时固定的，不能直接引用运行时变量（如当前登录用户名）。为了实现动态用户隔离，通常需要配合自定义的查询模板或使用脚本字段，或者依赖外部系统在写入文档时预先写入用户标识字段，然后角色中的查询条件使用term匹配该字段。
配置步骤与代码示例
在实际配置中，我们需要通过Elasticsearch的安全API来创建角色。以下演示基于Elasticsearch 7.x及以上版本（具体版本不影响DLS配置语法），假设我们有一个索引sales_records，其中包含字段region表示销售区域。我们希望“east_sales”角色只能看到region为“east”的文档。首先，使用Kibana的Dev Tools或者curl命令发送PUT请求，创建角色并指定DLS查询。
PUT /_security/role/east_sales
{
"cluster": [],
"indices": [
{
"names": ["sales_records"],
"privileges": ["read"],
"query": {
"term": { "region": "east" }
}
}
]
}
上述JSON中，query字段就是文档级安全规则。它要求所有对该索引的读操作都必须满足region字段值为east。注意，indices数组中每个索引条目都可以单独设置不同的查询，因此可以实现对不同索引的差异化过滤。角色创建完成后，我们需要创建用户并映射到该角色。
POST /_security/user/sales_east_user
{
"password": "changeme",
"roles": ["east_sales"],
"full_name": "East Region Sales",
"email": "east@ipipp.com"
}
创建用户后，使用该用户的凭据执行搜索。即使搜索请求中没有任何过滤条件，返回结果也只会包含region为east的文档。例如，执行GET /sales_records/_search时，Elasticsearch会自动在查询中添加一个filter条件。我们可以通过开启慢查询日志或查看profile输出，观察到实际的查询被改写。需要注意的是，DLS只对搜索、聚合、mget等读操作生效，对于直接通过文档ID获取的get请求同样会被过滤，如果请求的文档不属于用户权限范围，将返回404或空结果。
此外，DLS还支持更复杂的查询，比如bool组合、range范围、terms多值匹配等。但有一个重要限制：查询中不能使用脚本、聚合或嵌套字段的某些复杂表达式，因为安全过滤器必须在每个分片上高效执行。如果需要基于当前用户的属性动态变化，可以借助Elasticsearch的运行时字段（runtime fields）或外部数据同步机制，但本质上角色中的查询是静态的。
性能影响与最佳实践
引入文档级安全后，每一次搜索都会额外执行一个过滤查询。对于大多数场景，这个过滤条件相对简单且选择性高，因此性能损耗通常可以接受。但如果过滤条件非常复杂、涉及大量文档扫描，或者索引数据量极大，额外的过滤会显著增加查询延迟。此外，DLS的过滤条件在协调节点注入后，会分发到所有相关分片执行，这意味着每个分片都要做一次额外的位图计算或跳跃扫描。为了评估实际影响，建议在开启DLS前后分别测量常用查询的响应时间和吞吐量。
优化DLS性能的一个关键策略是让过滤条件尽可能简单且命中率高。例如，使用term查询比wildcard或regexp高效得多，如果可能，将权限字段设计为低基数的keyword类型，并配置doc values。另外，可以利用索引别名将不同租户的数据预先拆分到不同的索引中，然后在索引级别做隔离，减少对DLS的依赖。但对于需要在同一索引中灵活查询的场景，DLS仍然是必需的。
另一个最佳实践是结合字段级安全使用，避免返回用户无权查看的敏感字段。同时，定期审计角色定义和用户映射关系，防止权限配置错误导致的数据泄露。Elasticsearch提供了安全审计日志功能，可以记录每次查询触发的过滤条件，便于追踪异常访问。对于高性能要求的系统，还可以考虑在应用层实现类似的过滤逻辑，但这样会失去数据库层统一防护的优势，因此需要权衡。
常见问题与故障排查
配置DLS后，最容易遇到的问题就是“权限不生效”或“用户看到了不该看的数据”。这种情况通常是因为角色定义中的索引名称或权限不匹配。首先检查用户是否同时绑定了其他角色，而其他角色可能没有设置DLS，导致合并后的权限更宽松。Elasticsearch的权限模型是叠加的，用户拥有的所有角色权限会合并，如果其中一个角色允许无限制读取某个索引，那么即使另一个角色有DLS，最终该用户仍可能绕过过滤。因此，务必避免为同一用户同时分配带DLS和不带DLS的相同索引权限。
另一个常见错误是查询语法错误。DLS的query必须是一个合法的Elasticsearch查询DSL对象，如果包含拼写错误或不支持的语法，角色创建会失败并返回400错误。建议先在普通搜索中验证查询语句的正确性，再复制到角色定义中。如果查询中包含嵌套对象或父子关系，需要特别注意过滤条件的路径是否与映射一致。此外，DLS过滤条件对于_id字段不生效，因为文档ID不属于索引字段，如果需要按ID过滤，必须在文档中显式添加一个字段存储ID值。
最后，如果发现开启DLS后性能急剧下降，可以检查过滤条件的执行计划。使用GET /sales_records/_search?explain=true查看过滤条件的评分和匹配情况，或者使用Profile API查看每个分片的耗时。如果过滤条件导致大量文档被扫描，考虑优化字段映射或改用更精确的查询。记住，DLS是安全机制，不能因为性能问题而降低安全标准，但可以通过合理的数据建模和查询设计找到平衡点。
Elasticsearch文档级安全DLS修改时间：2026-09-22 21:29:56