挖掘机驾驶宝典

Appearance

版本演进与升级 ​

旧资料基于 Elasticsearch 5.6.8，其核心搜索思想仍然成立，但 API、默认配置、安全模型和运维方式已经发生明显变化。本篇以 9.x 为当前主线，记录跨版本时最容易误用的内容；具体补丁版本仍应查阅对应 Release Notes 和 Breaking Changes。

版本演进 ​

版本关键变化对旧笔记的影响
5.x一个 Index 可包含多个 Mapping Type，默认常见 5 个主分片index/type/id 和“Index≈Database、Type≈Table”的类比只适用于历史理解
6.x限制新 Index 只能有一个 Type，开始移除 Type应停止用 Type 隔离不同业务实体
7.xTypeless API 成为主路径；默认主分片数改为 1；引入 Data Stream 相关基础能力新代码改用 index/_doc/id，分片数必须按容量设计，不能依赖旧默认值
8.xMapping Type 完全移除；默认启用安全能力；Data Stream、向量检索和 ESQL 持续成熟
9.x继续清理旧兼容能力，强化 ESQL、语义/向量搜索和数据流失败处理

版本演进不是所有能力都在某个大版本一次完成。Data Stream、ES|QL、向量检索等功能跨多个小版本持续增强，生产设计应以实际运行版本的文档和许可范围为准。

旧写法勘误 ​

Mapping Type 已移除 ​

旧写法：

http
PUT articleindex/article/1
GET articleindex/article/_search

现代写法：

http
PUT articleindex/_doc/1
GET articleindex/_search

不同实体需要通过独立 Index、字段或明确的领域模型区分，不能再把 Type 当作关系表。

Index 不等于关系数据库 ​

Index 是共享 Settings、Mapping 和分片布局的文档集合。它没有外键、跨文档 ACID 事务和关系数据库式 Schema 约束。把 Index、Type、Document 机械映射成 Database、Table、Row 会掩盖数据建模和一致性差异。

模糊查询不等于通配符查询 ​

旧资料把 title:*s* 称为模糊查询，实际是通配符查询。Fuzzy Query 处理编辑距离，例如拼写误差；Wildcard Query 匹配字符模式。前导 * 可能展开大量词项，应谨慎使用。

http
GET articles/_search
{
  "query": {
    "fuzzy": {
      "title.keyword": {
        "value": "elasticserch",
        "fuzziness": "AUTO"
      }
    }
  }
}

全文字段通常优先使用带 fuzziness 的 match，由 Analyzer 处理输入：

http
GET articles/_search
{
  "query": {
    "match": {
      "title": {
        "query": "elasticserch",
        "fuzziness": "AUTO"
      }
    }
  }
}

hits.total 不再总是数字 ​

现代 Search Response 中 hits.total 通常包含 value 和 relation。若业务需要精确总数，应理解 track_total_hits 的精度和性能代价，不能按旧版响应直接反序列化为整数。

_id 不用于排序和聚合 ​

_id 用于文档寻址，但不提供常规排序、聚合所需的 Doc Values。需要这些能力时，把业务 ID 冗余为 keyword 字段。

Head 插件不再是推荐管理入口 ​

旧版 elasticsearch-head 教程依赖浏览器跨域并直接暴露 Elasticsearch。现代环境优先使用 Kibana Dev Tools、Stack Monitoring 和受认证保护的 API；不应为了连接第三方页面而全局开放 CORS。

默认安全模型已经变化 ​

Elasticsearch 8.x 起首次启动默认配置 TLS、认证等安全能力。http://127.0.0.1:9200 无密码直连只适用于显式关闭安全的隔离测试环境。生产环境应使用 TLS、最小权限用户或 API Key，并妥善保管 CA 和凭据。

不手工假设默认分片数 ​

旧集群常见每个 Index 默认 5 个主分片，7.x 后默认值改为 1。无论默认值是什么，都应依据数据量、节点数、查询并行度和恢复时间显式规划；大量按天创建的小 Index 会造成分片膨胀。

现代能力补充 ​

Data Stream 与生命周期 ​

Data Stream 为日志、指标和事件等追加型时间序列数据提供稳定名称，底层由多个 Backing Index 组成。配合 Index Template、Rollover 和 ILM 或 Data Stream Lifecycle，可以避免应用自行拼接日期索引名。

普通业务搜索数据经常需要按 ID 更新、删除或复杂 Alias 切换，未必适合 Data Stream，应根据写入模型选择。

ES|QL ​

ES|QL 使用管道串联读取、过滤、计算、聚合和排序，降低日志探索与分析查询的表达成本。Query DSL、KQL、EQL 和 ES|QL 各有边界，升级时要检查 Dashboard、告警和客户端实际使用的是哪一种语言。

语义与混合检索 ​

现代 Elasticsearch 可以在传统全文检索之外使用 dense_vector、sparse_vector、semantic_text、kNN 和 Retriever 组合语义检索。升级收益不仅是 API 变化，也包括向量量化、混合召回和推理工作流的增强。

Synthetic _source ​

合成 _source 可以从 Doc Values 或存储字段重建文档，减少部分场景的磁盘占用，但读取 _source 可能更慢，重建结果也不一定与原始 JSON 的字段顺序和表现形式完全一致。该能力还可能受许可约束，不能把它当作无成本的通用压缩开关。

Failure Store ​

较新的 9.x 数据流可以把部分 Ingest Pipeline 或 Mapping 失败的文档重定向到 Failure Store，便于保留和排查无法正常入库的事件。它不能代替采集端重试、消息队列或数据质量治理，启用前还要确认具体版本、数据流配置和保留策略。

升级路径 ​

7.x 升级到 9.x ​

不能从 7.x 直接滚动升级到 9.x。应先升级到 7.17，处理弃用项，再进入最新 8.19.x，最后升级到目标 9.x。7.x 或更早版本创建的 Index 不能直接作为 9.x 的普通可写索引继续使用，应在升级前 Reindex、删除，或按官方支持方式归档。

8.x 升级到 9.x ​

目标为 9.1 及以后版本时，应先升级到最新 8.19.x。若目标是较早的 9.0.x，官方曾提供从 8.18.x 进入的路径，但新升级应以目标版本页面给出的路径为准，不要只依据“相邻大版本”推断兼容性。

8.19 版 Beats、Elastic Agent 和 Logstash 可作为迁移桥梁连接 9.x Elasticsearch；这不代表任意 8.x 采集组件都兼容 9.x，也不代表可以长期忽略组件升级。

升级前检查 ​

  1. 盘点 Elasticsearch、Kibana、客户端、Beats、Logstash、插件、JVM、操作系统和编排平台版本。
  2. 阅读目标补丁版本的 Release Notes、Known Issues 和 Breaking Changes。
  3. 查看 Deprecation Log，运行 Kibana Upgrade Assistant，清理废弃 API 与设置。
  4. 检查所有 Index 的创建版本；对过旧 Index 执行 Reindex、删除或归档。
  5. 验证自定义插件、IK 分词插件、Snapshot Repository 和客户端兼容性。插件必须与 Elasticsearch 版本匹配。
  6. 在非生产环境使用生产 Snapshot 恢复演练，并执行写入、搜索、聚合、告警和回滚预案验证。
  7. 升级前创建成功的 Snapshot，并实际确认其可恢复。Elasticsearch 节点升级后不能原地降级，失败时只能重建旧版本集群并恢复升级前 Snapshot。

自建集群滚动升级顺序 ​

高可用集群通常逐节点滚动升级，同一集群只允许在升级窗口内短暂混用兼容版本。官方推荐的节点角色顺序为：

  1. 数据节点按 data_frozen → data_cold → data_warm → data_hot → 其他数据节点升级。
  2. 升级 ML、Ingest、Transform、Remote Cluster Client 和专用协调节点等非 Master 节点。
  3. 最后升级 Master-eligible 与 Voting-only 节点。

Master 节点最后升级，是因为新版本节点通常可以加入仍由旧版本 Master 管理的集群，反方向未必成立。每升级一个节点都应等待节点重新加入、必要分片恢复和集群状态稳定，再处理下一个节点。

升级后的验证 ​

  • 所有节点版本正确，Cluster Health、分片分配和 Pending Tasks 正常。
  • 没有 Archived Settings、持续 Deprecation Warning 或插件加载失败。
  • 核心索引可读写，Alias、Data Stream、Template、ILM 和 Ingest Pipeline 正常。
  • 搜索相关性、聚合结果、分页、中文分词和客户端序列化没有回归。
  • Snapshot、CCR、Remote Cluster、Monitoring 和安全审计链路正常。
  • 观察完整业务周期后再清理旧 Snapshot、兼容配置和迁移中间资源。