附录：附录 Elasticsearch 速查手册

zjc 于 2026-02-05 发布

这是《Elasticsearch 零基础实战指南》的独立章节版。本章从概念、实操和生产排查三个视角展开，代码块保留了原书可直接运行的版本。本附录汇总常用 API、查询、聚合、Mapping、配置、指标和排查命令。建议把它当作工作台参考，但不要未经压测直接把参数复制到生产环境。

1. 集群与节点 API

1.1 集群健康

GET /_cluster/health
GET /_cluster/health?wait_for_status=yellow&timeout=10s
GET /_cluster/health?level=indices

1.2 节点

GET /_cat/nodes?v
GET /_cat/nodes?v&h=name,id,node.role,master,heap.percent,ram.percent,cpu,load_average,disk.used_percent
GET /_nodes/stats/jvm,os,fs,indices?human
GET /_nodes/hot_threads

1.3 分片与分配

GET /_cat/shards?v
GET /_cat/shards?v&h=index,shard,prirep,state,docs,store,node,unassigned.reason
GET /_cat/allocation?v
GET /_cluster/allocation/explain
GET /_cat/recovery?v&active_only=true

1.4 索引

GET /_cat/indices?v
GET /_cat/indices?v&health=yellow
GET /_cat/indices/order*?v&h=index,health,status,docs.count,store.size,pri.store.size
GET /orders-v3/_stats?human
GET /orders-v3/_segments?human
GET /orders-v3/_settings
GET /orders-v3/_mapping

1.5 任务与线程池

GET /_cat/tasks?v
GET /_tasks?actions=*search*&detailed
POST /_tasks/TASK_ID/_cancel
GET /_cat/thread_pool/write,search?v&h=node_name,name,active,queue,rejected,completed
GET /_cat/pending_tasks?v

2. 文档操作

2.1 写入

PUT /products-v3/_doc/sku_10001
{
  "sku_id": "sku_10001",
  "title": "轻薄笔记本",
  "price": 5999.00
}

只创建，不允许覆盖：

PUT /products-v3/_create/sku_10001
{
  "sku_id": "sku_10001"
}

2.2 查询

GET /products-v3/_doc/sku_10001
GET /products-v3/_source/sku_10001
HEAD /products-v3/_doc/sku_10001

2.3 更新

POST /products-v3/_update/sku_10001
{
  "doc": {
    "price": 5499.00
  }
}

脚本更新：

POST /products-v3/_update/sku_10001?retry_on_conflict=3
{
  "script": {
    "lang": "painless",
    "source": "ctx._source.stock += params.delta",
    "params": { "delta": -1 }
  }
}

2.4 删除

DELETE /products-v3/_doc/sku_10001
POST /products-v3/_delete_by_query?conflicts=proceed
{
  "query": {
    "term": { "status": "deleted" }
  }
}

2.5 Bulk

POST /_bulk
{"index": {"_index": "products-v3", "_id": "sku_1"}}
{"sku_id": "sku_1", "title": "无线鼠标", "price": 99}
{"update": {"_index": "products-v3", "_id": "sku_2"}}
{"doc": {"price": 199}}
{"delete": {"_index": "products-v3", "_id": "sku_3"}}

Bulk 必须逐项检查：

"items": [
  {
    "index": {
      "status": 429,
      "error": { "type": "es_rejected_execution_exception" }
    }
  }
]

3. 查询 DSL 速查

3.1 term

GET /products-v3/_search
{
  "query": {
    "term": { "status": "on_sale" }
  }
}

3.2 terms

GET /products-v3/_search
{
  "query": {
    "terms": {
      "category_id": ["cat_1", "cat_2"]
    }
  }
}

3.3 match

GET /products-v3/_search
{
  "query": {
    "match": {
      "title": {
        "query": "轻薄笔记本",
        "operator": "and"
      }
    }
  }
}

3.4 match_phrase

GET /products-v3/_search
{
  "query": {
    "match_phrase": {
      "title": {
        "query": "无线鼠标",
        "slop": 1
      }
    }
  }
}

3.5 multi_match

GET /products-v3/_search
{
  "query": {
    "multi_match": {
      "query": "轻薄笔记本",
      "type": "best_fields",
      "fields": ["title^4", "keywords^2", "combined_text"],
      "minimum_should_match": "2<75%"
    }
  }
}

3.6 range

GET /orders-v3/_search
{
  "query": {
    "range": {
      "paid_at": {
        "gte": "now-1d/d",
        "lte": "now"
      }
    }
  }
}

3.7 bool

GET /products-v3/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "title": "笔记本" } }
      ],
      "should": [
        { "term": { "tags": "hot" } }
      ],
      "filter": [
        { "term": { "status": "on_sale" } },
        { "range": { "price": { "gte": 3000, "lte": 8000 } } }
      ],
      "must_not": [
        { "term": { "tags": "blocked" } }
      ]
    }
  }
}

3.8 nested

GET /products-v3/_search
{
  "query": {
    "nested": {
      "path": "attrs",
      "query": {
        "bool": {
          "filter": [
            { "term": { "attrs.name": "颜色" } },
            { "term": { "attrs.value": "红色" } }
          ]
        }
      }
    }
  }
}

3.9 分页

GET /orders-v3/_search
{
  "from": 0,
  "size": 20,
  "sort": [
    { "paid_at": "desc" },
    { "_id": "asc" }
  ]
}

Search After：

GET /orders-v3/_search
{
  "size": 20,
  "sort": [
    { "paid_at": "desc" },
    { "_id": "asc" }
  ],
  "search_after": ["2026-08-25T10:00:00Z", "order_10001"]
}

3.10 高亮

GET /products-v3/_search
{
  "query": {
    "match": { "title": "笔记本" }
  },
  "highlight": {
    "fields": {
      "title": {}
    },
    "pre_tags": ["<em>"],
    "post_tags": ["</em>"]
  }
}

4. 聚合速查

4.1 terms

GET /orders-v3/_search
{
  "size": 0,
  "aggs": {
    "top_categories": {
      "terms": {
        "field": "category_id",
        "size": 20,
        "order": { "_count": "desc" }
      }
    }
  }
}

4.2 指标

GET /orders-v3/_search
{
  "size": 0,
  "aggs": {
    "gmv": { "sum": { "field": "pay_amount" } },
    "avg_amount": { "avg": { "field": "pay_amount" } },
    "max_amount": { "max": { "field": "pay_amount" } },
    "min_amount": { "min": { "field": "pay_amount" } },
    "buyers": { "cardinality": { "field": "user_id" } }
  }
}

4.3 时间分桶

GET /orders-v3/_search
{
  "size": 0,
  "query": {
    "range": { "paid_at": { "gte": "now-7d/d", "lte": "now" } }
  },
  "aggs": {
    "per_hour": {
      "date_histogram": {
        "field": "paid_at",
        "fixed_interval": "1h",
        "time_zone": "Asia/Shanghai",
        "min_doc_count": 0
      }
    }
  }
}

4.4 range

GET /products-v3/_search
{
  "size": 0,
  "aggs": {
    "price_ranges": {
      "range": {
        "field": "price",
        "ranges": [
          { "to": 100 },
          { "from": 100, "to": 500 },
          { "from": 500 }
        ]
      }
    }
  }
}

4.5 filter 嵌套

GET /orders-v3/_search
{
  "size": 0,
  "aggs": {
    "paid": {
      "filter": { "term": { "pay_status": "success" } },
      "aggs": {
        "gmv": { "sum": { "field": "pay_amount" } }
      }
    }
  }
}

4.6 composite

GET /orders-v3/_search
{
  "size": 0,
  "aggs": {
    "groups": {
      "composite": {
        "size": 1000,
        "sources": [
          { "channel": { "terms": { "field": "channel" } } },
          { "city": { "terms": { "field": "city_id" } } }
        ]
      }
    }
  }
}

5. Mapping 速查

5.1 常用类型

类型	用途
text	全文检索
keyword	精确匹配、聚合、排序
long / integer / short / byte	整数
double / float	浮点数
scaled_float	固定精度金额
date	时间
boolean	布尔
ip	IP 查询
object	JSON 对象
nested	数组内对象边界
join	父子关系
dense_vector	向量字段
geo_point / geo_shape	地理位置和形状
alias	字段别名

5.2 keyword + text

PUT /articles-v1
{
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "fields": {
          "keyword": { "type": "keyword", "ignore_above": 256 }
        }
      }
    }
  }
}

5.3 只查不聚合

"trace_id": {
  "type": "keyword",
  "doc_values": false
}

5.4 只聚合不查

"city_id": {
  "type": "keyword",
  "index": false
}

5.5 dense_vector

"embedding": {
  "type": "dense_vector",
  "dims": 768,
  "index": true,
  "similarity": "cosine"
}

6. 索引模板与 ILM

6.1 Component Template

PUT /_component_template/app-logs-settings
{
  "template": {
    "settings": {
      "number_of_shards": 3,
      "number_of_replicas": 1,
      "refresh_interval": "5s"
    }
  }
}

6.2 Index Template

PUT /_index_template/app-logs
{
  "index_patterns": ["app-logs-*"],
  "data_stream": {},
  "composed_of": ["app-logs-settings"],
  "priority": 200
}

6.3 ILM

PUT /_ilm/policy/app-logs-policy
{
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "rollover": {
            "max_primary_shard_size": "50gb",
            "max_age": "1d"
          }
        }
      },
      "delete": {
        "min_age": "30d",
        "actions": { "delete": {} }
      }
    }
  }
}

6.4 ILM 状态

GET /app-logs*/_ilm/explain

7. 别名与 Reindex

7.1 别名

POST /_aliases
{
  "actions": [
    { "add": { "index": "products-v3", "alias": "products-read" } },
    { "add": { "index": "products-v3", "alias": "products-write" } }
  ]
}

7.2 原子切换

POST /_aliases
{
  "actions": [
    { "remove": { "index": "products-v3", "alias": "products-read" } },
    { "add": { "index": "products-v4", "alias": "products-read" } }
  ]
}

7.3 Reindex

POST /_reindex?wait_for_completion=false&slices=auto&refresh=true
{
  "source": {
    "index": "products-v3",
    "size": 1000
  },
  "dest": {
    "index": "products-v4",
    "op_type": "create"
  }
}

查看任务：

GET /_tasks?actions=*reindex&detailed

8. 分析与分词

8.1 Analyze

POST /_analyze
{
  "analyzer": "standard",
  "text": "Elasticsearch 搜索引擎"
}

8.2 自定义 Analyzer

PUT /articles-v1
{
  "settings": {
    "analysis": {
      "filter": {
        "my_stop": {
          "type": "stop",
          "stopwords": ["的", "了"]
        }
      },
      "analyzer": {
        "my_analyzer": {
          "tokenizer": "standard",
          "filter": ["lowercase", "my_stop"]
        }
      }
    }
  }
}

8.3 同义词

"synonym_filter": {
  "type": "synonym_graph",
  "synonyms": [
    "手机,智能手机,移动电话",
    "电脑,笔记本"
  ]
}

9. 快照与恢复

9.1 注册仓库

PUT /_snapshot/backup-repo
{
  "type": "fs",
  "settings": {
    "location": "/mnt/es-backup"
  }
}

9.2 快照

PUT /_snapshot/backup-repo/snapshot-2026.08.25?wait_for_completion=false
{
  "indices": "orders-v3,products-v3",
  "include_global_state": false
}

9.3 查看

GET /_snapshot/backup-repo/_current
GET /_snapshot/backup-repo/snapshot-2026.08.25

9.4 恢复

POST /_snapshot/backup-repo/snapshot-2026.08.25/_restore?wait_for_completion=false
{
  "indices": "orders-v3",
  "rename_pattern": "(.+)",
  "rename_replacement": "restored-$1"
}

10. 常用设置

10.1 索引设置

PUT /orders-v3/_settings
{
  "number_of_replicas": 1,
  "refresh_interval": "5s"
}

10.2 只读限制

PUT /orders-v3/_settings
{
  "blocks.read_only_allow_delete": true
}

解除：

PUT /orders-v3/_settings
{
  "blocks.read_only_allow_delete": null
}

10.3 分页限制

PUT /orders-v3/_settings
{
  "index.max_result_window": 10000
}

10.4 慢查询

PUT /orders-v3/_settings
{
  "index.search.slowlog.threshold.query.warn": "5s",
  "index.search.slowlog.threshold.query.info": "2s",
  "index.search.slowlog.threshold.fetch.warn": "1s"
}

11. 关键指标

指标	说明
cluster status	green/yellow/red
number_of_nodes	节点数
unassigned_shards	未分配分片
pending_tasks	master 任务队列
heap used percent	JVM 堆使用率
old GC count/time	老年代回收
disk used percent	磁盘使用率
write rejected	写入拒绝
search rejected	查询拒绝
query_time / query_total	查询平均耗时
indexing_time / indexing_total	写入平均耗时
merge total/throttled time	合并压力
refresh/flush time	刷新与提交耗时
breaker tripped	熔断次数
recovery bytes	恢复流量
snapshot success	快照成功率

12. 故障排查命令

12.1 集群异常

GET /_cluster/health?level=indices
GET /_cat/indices?v&health=red
GET /_cat/shards?v&h=index,shard,prirep,state,store,node,unassigned.reason
GET /_cluster/allocation/explain

12.2 写入异常

GET /_cat/thread_pool/write?v
GET /_nodes/stats/indices/indexing,merge,refresh,flush?human
GET /_cat/allocation?v

12.3 查询异常

GET /_cat/thread_pool/search?v
GET /_nodes/stats/indices/search?human
GET /_tasks?actions=*search*&detailed
GET /_nodes/hot_threads

12.4 磁盘异常

GET /_cat/allocation?v
GET /_nodes/stats/fs?human
GET /_all/_settings?filter_path=*.settings.index.blocks.read_only_allow_delete

13. 黄金清单

13.1 Mapping

明确事实来源和文档粒度；
ID、枚举、标签用 keyword；
标题描述用 text；
排序聚合字段保留 doc_values；
高基数字段禁止自由聚合；
嵌套结构有数量上限；
生产索引使用 dynamic strict 或 false。

13.2 查询

必须限制索引和时间范围；
filter 优先；
控制 size；
深分页使用 search after；
大导出使用 PIT；
避免前置通配符；
聚合控制桶数；
慢查询接入日志平台。

13.3 写入

使用 Bulk；
明确文档 ID 和幂等；
429 指数退避；
按场景设置 refresh interval；
避免热点文档频繁 update；
监控 write rejected 和 merge；
导入后恢复副本。

13.4 集群

master quorum 至少 3；
分片大小和数量有容量依据；
副本分布跨故障域；
磁盘提前告警；
每日快照并异地保存；
定期恢复演练；
滚动升级控制 allocation；
保持 cluster state 可控。

13.5 安全

TLS 全链路启用；
不使用超级用户给应用；
API key 有过期和轮换；
索引权限最小化；
敏感字段使用 DLS/FLS；
高危操作有审批和审计；
集群和 Kibana 不暴露公网。

14. 推荐版本

学习环境：Elasticsearch 8.x 或 9.x；
Java 客户端：Elasticsearch Java API Client；
Spring：Spring Boot 3.x；
Kibana：与服务端主版本匹配；
采集：Filebeat / OpenTelemetry Collector；
压测：Rally；
监控：Prometheus / Grafana。

15. 一页排障图

集群 red
  -> cat indices health=red
  -> cat shards + allocation explain
  -> 恢复节点 / 磁盘 / 分配 / 快照

集群 yellow
  -> allocation explain
  -> 节点数 / 磁盘水位 / 分配规则 / 副本数

写入 429
  -> write rejected
  -> bulk 策略 / merge / 磁盘 / 副本恢复
  -> 客户端限流退避

查询慢
  -> search latency + rejected
  -> 索引范围 / 时间范围 / from+size / profile
  -> 缩小范围，取消大任务

JVM 高
  -> GC + breaker + hot threads
  -> 大聚合 / 深分页 / scroll
  -> 取消任务并治理请求

磁盘满
  -> cat allocation
  -> 清理 / 扩容 / 降低副本
  -> 解除 read-only block