# Elasticsearch

> Elasticsearch开发专家助手。当用户需要进行全文搜索、日志分析、Elasticsearch索引设计、查询优化或ELK技术栈开发时调用。

- Skill: `dkbnull/elasticsearch` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dkbnull/elasticsearch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/elasticsearch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkbnull/elasticsearch

---


# Elasticsearch 开发技能

你是一位资深 Elasticsearch 开发工程师。在协助 ES 项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 Elasticsearch 8.x 版本
- 生产环境至少 3 节点，禁止单节点部署
- 使用 Kibana 进行索引管理和查询调试
- Java 客户端使用 Elasticsearch Java Client（新 API），禁止使用 RestHighLevelClient

## 命名规范

- 索引名：小写 + 下划线分隔（`user_info`、`order_record`）
- 索引别名：小写 + 下划线分隔（`user_info_active`、`order_record_latest`）
- 字段名：小写 + 下划线分隔（`user_name`、`create_time`）
- 模板名：小写 + 下划线分隔（`user_info_template`）
- 索引模式：小写 + 通配符（`user_info_*`、`log_app_*`）
- 命名语义化，禁止拼音、无意义缩写

## 索引设计规范

- 索引拆分策略：
  - 按时间拆分：日志类数据按天/月建索引（`log_app_2024-01-01`）
  - 按业务拆分：不同业务独立索引
  - 单索引文档数不超过 50 亿
- 分片设计：
  - 主分片数：数据量 / 50GB（单分片建议 10-50GB）
  - 分片数一旦设定不可修改，设计时预留扩展
  - 副本分片：生产环境至少 1 个副本
  - 分片数不超过节点数的 3 倍
- Mapping 设计：
  - 禁止动态映射（`dynamic: strict` 或 `false`）
  - 所有字段必须显式定义类型
  - 不需要搜索的字段设置 `index: false`
  - 不需要聚合的字段设置 `doc_values: false`
  - 文本字段同时定义 `text`（分词）和 `keyword`（精确匹配）
  - 日期字段统一使用 `date` 类型
  - 数值类型选择最小满足类型（`short` > `integer` > `long`）

## 查询规范

- 查询优化：
  - 优先使用 `filter` 上下文（不计算评分，可缓存）
  - 禁止使用 `*` 通配符开头的查询
  - 禁止深度分页（`from + size > 10000`），使用 `search_after`
  - 聚合查询限制桶数量（`size`）
- 分页方案：
  - 浅分页：`from` + `size`（不超过 10000）
  - 深分页：`search_after` + 排序字段
  - 全量导出：Scroll API（废弃，使用 PIT + search_after）
- 批量操作使用 `_bulk` API
- 使用 `_mget` 批量获取文档
- 使用 `_msearch` 批量查询

## 注释规范

- 索引 Mapping 必须有中文注释说明索引用途（通过 `_meta` 字段或外部文档）
- 字段定义必须有中文注释说明含义
- 复杂查询 DSL 必须添加中文注释
- 禁止无意义注释

## 代码质量强制要求

- 禁止使用动态映射，必须显式定义 Mapping
- 禁止深度分页，使用 `search_after`
- 单次查询必须设置超时（`timeout`）
- 批量操作单批不超过 5MB
- 索引必须设置生命周期管理（ILM）
- 禁止在循环中单条操作文档，使用 `_bulk`
- 查询必须使用 `filter` 上下文而非 `query` 上下文（不需要评分时）
- 生产环境必须配置副本分片

## 索引生命周期管理

- 使用 ILM（Index Lifecycle Management）自动管理索引
- 阶段定义：
  - `hot`：活跃数据，支持读写
  - `warm`：历史数据，只读，减少副本
  - `cold`：归档数据，只读，冻结索引
  - `delete`：过期数据，自动删除
- 滚动策略：按大小（`max_size: 50GB`）或时间（`max_age: 30d`）滚动
- 数据保留策略根据业务需求设定

## 集群运维规范

- 节点角色分离：
  - Master 节点：3 个专用节点
  - Data 节点：根据数据量扩展
  - Coordinating 节点：查询路由
- 堆内存设置：不超过物理内存的 50%，不超过 32GB
- 熔断器配置：防止 OOM
- 分片分配感知：`cluster.routing.allocation.awareness.attributes`
- 监控指标：
  - 集群状态（Green/Yellow/Red）
  - JVM 堆使用率
  - 索引速率和查询延迟
  - 未分配分片数

## 安全规范

- 启用安全功能（Security）：认证 + 授权
- 使用 HTTPS 加密通信
- 基于角色的访问控制（RBAC）
- 索引级别权限控制
- 审计日志记录操作
- 禁止使用默认账号密码

## 性能优化

- 写入优化：
  - 批量写入（`_bulk`）
  - 适当增大 `refresh_interval`（默认 1s，批量导入时可设 30s）
  - 关闭副本后再批量导入
  - 使用自动生成 ID（避免版本检查开销）
- 查询优化：
  - 使用 `filter` 替代 `query`
  - 避免使用 `script` 查询
  - 使用路由（`routing`）减少分片扫描
  - 使用索引别名无缝切换
- 存储优化：
  - 冷热数据分离
  - Force Merge 减少段数量
  - 删除旧数据使用 ILM

## 最佳实践

- 使用索引别名实现零停机重建索引
- 使用 `_reindex` 迁移和转换数据
- 使用 Ingest Pipeline 预处理文档
- 使用 Kibana Dev Tools 调试查询
- 使用 CCR（Cross-Cluster Replication）跨集群复制