本模块前置知识#

• 已完成 ES 部署并能正常访问 9200 端口（第一篇内容）
• 会使用 curl 或 Kibana Dev Tools 发起 HTTP 请求

本模块核心术语#

下表是 ES 术语与 MySQL 体系的类比对照，这是理解后续所有操作的基石，建议对照多读两遍：

graph LR
    subgraph 正排["正排思路（MySQL）"]
        D1["文档1"] -->|"包含"| W1["弹性 / 云 / 主机"]
    end
    subgraph 倒排["倒排思路（Lucene）"]
        T1["词：弹性"] -->|"出现在"| L1["文档1, 文档7, 文档23"]
    end

主分片 vs 副本分片#

ES 的数据可靠性靠「主分片 + 副本分片」的组合拳实现，二者职责泾渭分明：

• 主分片（Primary Shard）：可读可写（rw），所有写请求先落主分片，再同步到副本
• 副本分片（Replica Shard）：只读（ro），承担数据冗余与查询请求分流

关键约束

同一主分片与其副本永不分配在同一节点——否则该节点宕机时主副本同时丢失，冗余就失去了意义。这正是下文「单节点永远 yellow」现象的根本原因。

分片在双节点集群中的典型分配方式如下：

graph TD
    subgraph 节点A
        P0["主分片 P0 (rw)"]
        R1["副本 R1 (ro)"]
    end
    subgraph 节点B
        P1["主分片 P1 (rw)"]
        R0["副本 R0 (ro)"]
    end
    P0 -. 数据同步 .-> R0
    P1 -. 数据同步 .-> R1

注意交叉分配：节点A 存放 P0 与 R1，节点B 存放 P1 与 R0，任一节点宕机，数据依然完整可用。

集群健康颜色与排查命令#

集群健康状态只有三种颜色，但风险等级天差地别：

排查三板斧，按顺序执行：

1
curl -X GET "localhost:9200/_cluster/health?pretty"
2
curl -X GET "localhost:9200/_cat/shards?v"
3
curl -X GET "localhost:9200/_cluster/allocation/explain?pretty"

• health 返回的 status 字段直接显示当前颜色
• _cat/shards 中状态为 UNASSIGNED 的行就是「无处安家」的分片
• explain 会返回分片未分配的详细原因（如磁盘水位超标、节点数不足）

经典「假故障」复现

单节点集群创建默认带 1 副本的索引后，健康状态永远是 yellow——因为副本分片不能和主分片住同一台机器，而集群里根本没有第二台机器。这不是故障，是特性。

分片路由公式：为什么主分片数创建后不可改#

每条文档写入时，ES 用下面的公式决定它落到哪个分片：

$shard = hash(\text{文档ID}) \bmod \text{主分片数}$

推导一下你就明白为什么改不了：假设原来 5 个主分片，ID 为 7 的文档落在 7 % 5 = 2 号分片；如果把主分片数改成 3，取模结果变成 7 % 3 = 1，历史数据的定位全部错乱，等于整个索引报废。

补救路线

确实需要调整分片规模时，可用 _split（扩容）/ _shrink（缩容）/ _reindex（重建）三种方案，各有前置条件与代价，将在本系列后续文章展开。

本模块前置知识#

• 了解 HTTP 常见方法（GET/POST）
• 完成上一模块，知道 ES 通过 9200 端口提供 HTTP 服务

本模块核心术语#

• RESTful：一种 API 设计风格——URL 只表示「资源」（名词），动作用 HTTP 方法（动词）表达
• JSON：ES 请求体与响应体的统一数据格式

RESTful 风格：URL 是名词，HTTP 方法是动词#

反面教材是把动词塞进 URL，例如 /student/get_1001、/student/del_1001——每个人起名习惯不同，团队协作时就是灾难。RESTful 的正解是让同一个资源用同一 URL，用 HTTP 方法区分动作：

结论：ES 就是典型的 RESTful 程序——索引/文档是资源，HTTP 方法是动作。

JSON 语法硬性规则#

JSON 的类型系统非常简单：四种基础类型（字符串、数字、布尔 true/false、null）+ 两种复合类型（数组 [...]、对象 {...}），复合类型可任意嵌套。

但必须牢记三条铁律，违反任何一条都会直接报解析错误：

1. 字符串必须使用双引号，单引号非法
2. 最后一个元素后不允许尾随逗号
3. 不允许注释（// 和 /* */ 都不行）

课堂练习#

用 JSON 描述你自己（注意对象嵌套数组的写法），并通过 curl 提交给 ES 验证合法性：

1
curl -X PUT "localhost:9200/student/_doc/1" -H 'Content-Type: application/json' -d'
2
{
3
  "name": "张三",
4
  "age": 28,
5
  "is_ops": true,
6
  "skills": ["Linux", "Docker", "K8s"],
7
  "address": {
8
    "city": "北京",
9
    "district": "海淀区"
10
  }
11
}'

若 JSON 合法，预期返回正常的写入响应（"result":"created"）；若格式有误，ES 会直接抛出 mapper_parsing_exception 并指出出错位置。

本模块前置知识#

• 掌握 RESTful 风格与 JSON 语法
• 理解索引、分片、副本的概念

本模块核心术语#

• 别名（Alias）：指向一个或多个索引的「虚拟名字」，可实现索引平滑切换
• 打开/关闭（open/close）：关闭的索引几乎不占集群资源，也不可读写，适合冷数据归档

索引的增删改查#

创建索引时直接指定分片与副本数：

1
curl -X PUT "localhost:9200/student" -H 'Content-Type: application/json' -d'
2
{
3
  "settings": {
4
    "number_of_shards": 1,
5
    "number_of_replicas": 1
6
  }
7
}'

预期输出：

1
{
2
  "acknowledged": true,
3
  "shards_acknowledged": true,
4
  "index": "student"
5
}

查看索引有两种视图，按需取用：

• GET /_cat/indices?v：列表视图，一眼看到 docs.count、store.size 等关键指标
• GET /student：详情视图，返回 settings 与 mappings 完整定义

修改副本数——副本数是少数支持动态调整的索引级配置：

1
curl -X PUT "localhost:9200/student/_settings" -H 'Content-Type: application/json' -d'
2
{
3
  "number_of_replicas": 0
4
}'

再次强调

主分片数只能在创建时指定，事后不可修改。生产环境规划容量时宁多勿少。

删除索引：

1
curl -X DELETE "localhost:9200/student"

预期输出 {"acknowledged":true}。

索引的打开与关闭#

冷数据归档的利器，一行命令完成状态切换：

1
curl -X POST "localhost:9200/student/_close"
2
curl -X POST "localhost:9200/student/_open"

关闭后执行 GET /_cat/indices?v，可观察到该索引状态变为 close，此时它几乎不再占用堆内存与文件句柄，但数据完整保留在磁盘上。

别名实战#

创建别名只需一个 _aliases 动作：

1
curl -X POST "localhost:9200/_aliases" -H 'Content-Type: application/json' -d'
2
{
3
  "actions": [
4
    { "add": { "index": "student", "alias": "student_v1_read" } }
5
  ]
6
}'

别名的经典场景是重建索引后的无感切换：业务代码始终读写别名，运维在后台建好新索引并完成数据迁移后，原子切换别名指向，业务零改动、零停机。

graph LR
    App["业务应用"] -->|"始终读写别名 student_read"| V1["student_v1（旧索引）"]
    App -. "别名原子切换" .-> V2["student_v2（重建后新索引）"]
    style V2 stroke:#3fb950,stroke-width:2px

索引关键排查指标#

_cat/indices?v 返回的每一列都值得读懂：

其他常用 settings 速查：refresh_interval（写入后多久可被搜索到，默认 1s，批量导入时可临时调大提速）、max_result_window（深度分页上限，默认 10000）。

本模块前置知识#

• 已掌握索引的创建与查看
• 熟悉 JSON 对象写法

本模块核心术语#

单条文档写入（POST 与 PUT 的区别）#

指定 ID 写入示例：

1
curl -X PUT "localhost:9200/student/_doc/1001" -H 'Content-Type: application/json' -d'
2
{
3
  "name": "张三",
4
  "age": 20,
5
  "tag": ["篮球", "编程"]
6
}'

预期输出包含 "result":"created"。使用 POST 自动生成 ID 时，响应中会返回一串系统生成的 _id。

写入响应的每个字段都是排查线索：

特别地，局部更新若提交的内容与原文档完全一致，result 返回 noop（无操作），_version 不递增。

_bulk 部分失败的典型响应片段如下，排障时逐条遍历定位：

1
{
2
  "errors": true,
3
  "items": [
4
    { "index":  { "_id": "1003", "status": 201 } },
5
    { "update": { "_id": "1001", "status": 200 } },
6
    { "delete": { "_id": "1002", "status": 404,
7
                  "error": { "reason": "document missing" } } }
8
  ]
9
}

幂等性说明

对同一 ID 重复 PUT 是覆盖式更新，_version 字段随之递增；而重复 POST 每次都会生成一条新文档，注意区分。

单条文档查询与删除#

1
curl -X GET "localhost:9200/student/_doc/1001"
2
curl -X DELETE "localhost:9200/student/_doc/1001"

• 查询成功：返回体含 _index、_id、_version、_source 等字段
• 查询不存在的 ID：返回 "found":false（对比记忆）
• 删除成功："result":"deleted"

文档更新：全量覆盖 vs 局部更新#

• 全量更新：再次 PUT 同 ID 的完整 JSON，旧内容被整体替换
• 局部更新：使用 _update 端点，只改指定字段，其余字段保持不变

1
curl -X POST "localhost:9200/student/_doc/1001/_update" -H 'Content-Type: application/json' -d'
2
{
3
  "doc": { "age": 22 }
4
}'

并发控制

ES 通过 _seq_no / _primary_term 实现乐观锁：更新时携带查询时读到的这两个值，若期间文档被他人修改，则本次更新失败。运维阶段了解即可。

批量查询 _mget#

一次请求取回多条文档，避免 N 次网络往返：

1
curl -X GET "localhost:9200/student/_mget" -H 'Content-Type: application/json' -d'
2
{
3
  "ids": ["1001", "1002"]
4
}'

预期输出 docs 数组，按请求顺序逐条返回；不存在的 ID 对应条目标记 found:false，不影响其他文档返回。

批量操作 _bulk（重点中的重点）#

_bulk 的格式铁律：每个动作由「元数据行 + 数据行」两行组成，且每行必须以换行符结尾（包括最后一行）。一次请求可混合增、改、删：

1
POST /_bulk
2
{"index":{"_index":"student","_id":"1003"}}
3
{"name":"李四","age":20}
4
{"update":{"_index":"student","_id":"1001"}}
5
{"doc":{"age":22}}
6
{"delete":{"_index":"student","_id":"1002"}}

上述请求一次完成三件事：新增 1003、修改 1001 的年龄、删除 1002。预期输出解读要点：

• items 数组逐条回显每个动作的执行结果，顺序与请求一致
• 顶层 errors 字段为 false 表示全部成功
• 部分失败特性：单条失败不影响其他条目执行，失败条目的 error.reason 给出具体原因

高频踩坑

_bulk 报 illegal_argument_exception 十有八九是换行问题。通过文件提交时务必使用 --data-binary @bulk.json 而非 -d，避免 curl 吃掉换行符。

本模块前置知识#

• 掌握 RESTful 风格与 JSON 语法
• 理解索引、分片、副本的概念

本模块核心术语#

• 别名（Alias）：指向一个或多个索引的「虚拟名字」，可实现索引平滑切换
• 打开/关闭（open/close）：关闭的索引几乎不占集群资源，也不可读写，适合冷数据归档

索引的增删改查#

创建索引时直接指定分片与副本数：

1
curl -X PUT "localhost:9200/student" -H 'Content-Type: application/json' -d'
2
{
3
  "settings": {
4
    "number_of_shards": 1,
5
    "number_of_replicas": 1
6
  }
7
}'

预期输出：

1
{
2
  "acknowledged": true,
3
  "shards_acknowledged": true,
4
  "index": "student"
5
}

查看索引有两种视图，按需取用：

• GET /_cat/indices?v：列表视图，一眼看到 docs.count、store.size 等关键指标
• GET /student：详情视图，返回 settings 与 mappings 完整定义

修改副本数——副本数是少数支持动态调整的索引级配置：

1
curl -X PUT "localhost:9200/student/_settings" -H 'Content-Type: application/json' -d'
2
{
3
  "number_of_replicas": 0
4
}'

再次强调

主分片数只能在创建时指定，事后不可修改。生产环境规划容量时宁多勿少。

删除索引：

1
curl -X DELETE "localhost:9200/student"

预期输出 {"acknowledged":true}。

索引的打开与关闭#

冷数据归档的利器，一行命令完成状态切换：

1
curl -X POST "localhost:9200/student/_close"
2
curl -X POST "localhost:9200/student/_open"

关闭后执行 GET /_cat/indices?v，可观察到该索引状态变为 close，此时它几乎不再占用堆内存与文件句柄，但数据完整保留在磁盘上。

别名实战#

创建别名只需一个 _aliases 动作：

1
curl -X POST "localhost:9200/_aliases" -H 'Content-Type: application/json' -d'
2
{
3
  "actions": [
4
    { "add": { "index": "student", "alias": "student_v1_read" } }
5
  ]
6
}'

别名的经典场景是重建索引后的无感切换：业务代码始终读写别名，运维在后台建好新索引并完成数据迁移后，原子切换别名指向，业务零改动、零停机。

graph LR
    App["业务应用"] -->|"始终读写别名 student_read"| V1["student_v1（旧索引）"]
    App -. "别名原子切换" .-> V2["student_v2（重建后新索引）"]
    style V2 stroke:#3fb950,stroke-width:2px

本模块前置知识#

• 已掌握索引的创建与查看
• 熟悉 JSON 对象写法

本模块核心术语#

单条文档写入（POST 与 PUT 的区别）#

指定 ID 写入示例：

1
curl -X PUT "localhost:9200/student/_doc/1001" -H 'Content-Type: application/json' -d'
2
{
3
  "name": "张三",
4
  "age": 20,
5
  "tag": ["篮球", "编程"]
6
}'

预期输出包含 "result":"created"。使用 POST 自动生成 ID 时，响应中会返回一串系统生成的 _id。

幂等性说明

对同一 ID 重复 PUT 是覆盖式更新，_version 字段随之递增；而重复 POST 每次都会生成一条新文档，注意区分。

单条文档查询与删除#

1
curl -X GET "localhost:9200/student/_doc/1001"
2
curl -X DELETE "localhost:9200/student/_doc/1001"

• 查询成功：返回体含 _index、_id、_version、_source 等字段
• 查询不存在的 ID：返回 "found":false（对比记忆）
• 删除成功："result":"deleted"

文档更新：全量覆盖 vs 局部更新#

• 全量更新：再次 PUT 同 ID 的完整 JSON，旧内容被整体替换
• 局部更新：使用 _update 端点，只改指定字段，其余字段保持不变

1
curl -X POST "localhost:9200/student/_doc/1001/_update" -H 'Content-Type: application/json' -d'
2
{
3
  "doc": { "age": 22 }
4
}'

并发控制

ES 通过 _seq_no / _primary_term 实现乐观锁：更新时携带查询时读到的这两个值，若期间文档被他人修改，则本次更新失败。运维阶段了解即可。

批量查询 _mget#

一次请求取回多条文档，避免 N 次网络往返：

1
curl -X GET "localhost:9200/student/_mget" -H 'Content-Type: application/json' -d'
2
{
3
  "ids": ["1001", "1002"]
4
}'

预期输出 docs 数组，按请求顺序逐条返回；不存在的 ID 对应条目标记 found:false，不影响其他文档返回。

批量操作 _bulk（重点中的重点）#

_bulk 的格式铁律：每个动作由「元数据行 + 数据行」两行组成，且每行必须以换行符结尾（包括最后一行）。一次请求可混合增、改、删：

1
POST /_bulk
2
{"index":{"_index":"student","_id":"1003"}}
3
{"name":"李四","age":20}
4
{"update":{"_index":"student","_id":"1001"}}
5
{"doc":{"age":22}}
6
{"delete":{"_index":"student","_id":"1002"}}

上述请求一次完成三件事：新增 1003、修改 1001 的年龄、删除 1002。预期输出解读要点：

• items 数组逐条回显每个动作的执行结果，顺序与请求一致
• 顶层 errors 字段为 false 表示全部成功
• 部分失败特性：单条失败不影响其他条目执行，失败条目的 error.reason 给出具体原因

高频踩坑

_bulk 报 illegal_argument_exception 十有八九是换行问题。通过文件提交时务必使用 --data-binary @bulk.json 而非 -d，避免 curl 吃掉换行符。

本模块前置知识#

• 已完成文档写入操作
• 理解 Mapping 是字段的「表结构定义」

本模块核心术语#

• 动态映射（Dynamic Mapping）：未定义 Mapping 时，ES 按写入数据自动推断字段类型

查看与理解自动推断的 Mapping#

1
curl -X GET "localhost:9200/student/_mapping?pretty"

对照之前写入的文档，你会发现一个有趣的现象：字符串字段被推断成了 text + keyword 的双子字段结构——

1
"name": {
2
  "type": "text",
3
  "fields": {
4
    "keyword": {
5
      "type": "keyword",
6
      "ignore_above": 256
7
    }
8
  }
9
}

这份结构的含义：name 用于全文搜索，name.keyword 用于精确匹配与排序聚合——一份数据，两种用法。

显式定义 Mapping 实战#

动态映射方便但不可控，生产环境应在创建索引时显式声明：

1
curl -X PUT "localhost:9200/student_v2" -H 'Content-Type: application/json' -d'
2
{
3
  "mappings": {
4
    "properties": {
5
      "name":     { "type": "text" },
6
      "tag":      { "type": "keyword" },
7
      "birthday": { "type": "date", "format": "yyyy-MM-dd" },
8
      "ip_addr":  { "type": "ip" },
9
      "score":    { "type": "double" }
10
    }
11
  }
12
}'

类型校验的价值，写入一个非法 IP 立刻可见：

1
curl -X PUT "localhost:9200/student_v2/_doc/1" -H 'Content-Type: application/json' -d'
2
{
3
  "name": "王五",
4
  "ip_addr": "999.999.999.999"
5
}'

ES 直接拒绝并抛出 mapper_parsing_exception，脏数据被挡在门外——这就是强类型 Mapping 的意义。

运维对 Mapping 的定位#

职责边界

Mapping 设计主要是开发的工作。运维需要做到的是：会查（_mapping）、会辅助排查（字段类型不符导致的写入报错），以及在变更评审时守住底线。

关键约束

已有字段的类型不可修改（例如把 text 改成 keyword），只能新建索引后 _reindex 迁移数据；新增字段则是允许的。了解即可，实操在进阶篇展开。

本模块前置知识#

• 理解分词器（Analyzer）是把文本切成词项的组件
• 会在 Mapping 中为字段指定类型

本模块核心术语#

• ik_max_word：最细粒度切分，穷尽各种可能的词组合
• ik_smart：最粗粒度切分，只切一次不重复
• 自定义词典（custom dic）：扩展 IK 词库的文件/远程地址，让新词（如行业术语）能被正确切出

为什么要中文分词器#

先用默认的 standard 分词器试试中文：

1
curl -X GET "localhost:9200/_analyze" -H 'Content-Type: application/json' -d'
2
{
3
  "analyzer": "standard",
4
  "text": "中华人民共和国人民大会堂"
5
}'

预期输出把句子按单字切分：中、华、人、民……每字一个 token。这意味着搜「人民」只是逐字匹配，搜「华人」也能误命中——完全无法表达「词」的概念，搜索体验极差。这就是必须引入 IK 的根本原因。

IK 分词器安装#

铁律

IK 插件版本必须与 ES 版本严格一致，否则节点启动直接失败。这是新手炸掉集群的头号原因。

在线安装（离线环境可先下载 zip 包，再 install file:///path/to/zip）：

1
bin/elasticsearch-plugin install https://get.infini.cloud/elasticsearch/analysis-ik/8.11.1
2
# 安装完成后必须重启节点
3
systemctl restart elasticsearch

验证插件是否加载成功：

1
curl -X GET "localhost:9200/_cat/plugins?v"

预期输出中出现 analysis-ik 即表示安装成功。

两种分词模式对比实战#

用同一句话分别测试两种模式：

1
curl -X POST "localhost:9200/_analyze" -H 'Content-Type: application/json' -d'
2
{"analyzer":"ik_max_word","text":"中华人民共和国人民大会堂"}'
3

4
curl -X POST "localhost:9200/_analyze" -H 'Content-Type: application/json' -d'
5
{"analyzer":"ik_smart","text":"中华人民共和国人民大会堂"}'

选型建议

索引侧用 ik_max_word 保证召回（能搜到），搜索侧用 ik_smart 保证精准（不误搜）。这是社区公认的最佳实践组合。

自定义词典配置#

新词与行业术语（如「弹性云主机」）默认不在 IK 词库中，需要手动扩展，三步走：

第一步，编辑 IK 配置文件（路径为 config/analysis-ik/config/IKAnalyzer.cfg.xml），声明扩展词典：

1
<?xml version="1.0" encoding="UTF-8"?>
2
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
3
<properties>
4
  <comment>IK Analyzer 扩展配置</comment>
5
  <entry key="ext_dict"></entry>
6
  <entry key="ext_dict">custom/myword.dic</entry>
7
</properties>

第二步，在 config/analysis-ik/config/custom/ 目录下新建 myword.dic，每行一个词：

1
弹性云主机
2
云原生

第三步，重启节点后重新验证：

1
curl -X POST "localhost:9200/_analyze" -H 'Content-Type: application/json' -d'
2
{"analyzer":"ik_max_word","text":"使用弹性云主机部署云原生应用"}'

预期输出中「弹性云主机」「云原生」被整体切出，不再被拆碎。

进阶了解

本地词典每次修改都要重启节点。生产环境可配置远程词典（HTTP 地址），IK 会定时轮询拉取实现热更新，避免重启集群，具体方案留待进阶篇展开。