企业官网建设流程全解析

过去两年我一直在帮团队做搜索和日志相关的改造，Elasticsearch 几乎成了标配。可越是常用，越发现很多人把它当普通数据库用：Mapping 里塞满 keyword，深分页翻到天荒地老，集群一扩容就毛爪。这篇文章想做的，不只是再贴一遍安装命令，而是把 Elasticsearch 这套知识体系从评估选型、环境搭建、建模查询到行业落地这几个环节串起来，用真实场景里的取舍来讲明白。如果你正准备在 Windows 上把 ES 跑起来，或者正为商品检索、订单状态查询这类需求挠头，这篇应该能帮你少走不少弯路。

1. 动手前先理清 Elasticsearch 能解决什么问题

1.1 从数据库到搜索：技术选型的底层逻辑

很多团队把 Elasticsearch 引入项目，第一句话是“我们要做全文搜索”。这没错，但只看到了冰山一角。ES 真正擅长的是三件事：倒排索引检索、海量日志聚合分析、大数据量下的近实时查询。它不是用来替代 MySQL 的，也不是用来替代 MongoDB 的，而是在“读多写少、筛选条件多、维度不定”的场景里承担加速器和分析引擎的角色。

我见过不少项目把 ES 当主库用，订单表、用户表全塞进去，结果事务没了、关联查询别扭了，同步任务还时不时出问题。Elasticsearch 知识体系的第一课，就是要分清边界：数据源和写入方仍应该由 MySQL、PostgreSQL、MongoDB 这类数据库承担，ES 通过同步或双写机制拿到数据，再对外提供检索、聚合、报表能力。定位清楚了，后面很多坑都能避开。

从业务视角看，ES 的落地价值通常体现在三个方向。第一，电商商品模块的搜索、筛选、排序，常规 SQL 用 LIKE 匹配性能差，而且无法处理“黑色羽绒服女”这种组合词。第二，订单中心和客服后台需要根据用户、状态、时间段、金额等多条件组合查询，传统分页在百万级数据后越来越吃力。第三，运维和业务监控需要实时收日志、统计接口耗时、分析错误率，这简直是 ES 加 Kibana 的主场。理解这些典型场景，你才能判断项目里到底值不值得引入 ES。

1.2 知识体系的四个层级：部署、建模、查询、治理

我习惯把 Elasticsearch 知识体系拆成四个层级，每个层级对应不同的工作内容。第一层是部署和运维，包括 Windows 或 Linux 下的安装启动、JVM 参数调整、集群节点配置、分片和副本规划。这层不要求你会写多复杂的查询，但至少要能独立把单机跑起来，知道集群状态为什么从 green 变成 yellow。

第二层是索引建模，也就是 Mapping 设计、分词器选择、字段类型定义。这一层决定查询的天花板。同样是商品名称，用 text 和用 keyword 行为完全不同；同样做聚合，字段是 long 还是 keyword 结果也会不一样。我见过太多人从一开始就没设计好，上线半年后业务要求变了，只能重建索引，那个过程相当痛苦。

第三层是查询和聚合。ES 的 Query DSL 写起来没有 SQL 直观，但掌握 bool 组合、filter 上下文、term 和 match 的区别、date_histogram 聚合，基本可以覆盖绝大多数需求。第四层是数据治理和稳定性，包括索引生命周期管理、容量规划、慢查询排查、并发冲突解决。这四个层级一层压一层，前面的功课补得越扎实，后面的运营成本越低。

1.3 行业场景里最常见的三个误区

误区一是“全字段上 text”。有些人做搜索时不管三七二十一，把所有字符串字段都设成 text，然后查询用 match。结果就是：精确匹配变成模糊匹配，聚合结果奇奇怪怪，状态查询“1”会把“10”和“11”都搜出来。正确做法是精确值用 keyword，需要分词的内容才用 text，必要时用 multi-fields 同时保留两种语义。

误区二是“深分页不是问题”。默认 from + size 最大只能到 10000 行，一旦用户一页页翻到后面，响应时间会迅速恶化。做行业应用时要记住，页面滚动或 APP 下拉加载用 search_after，导出数据用 scroll 或 pit，而不是靠无休止地加大 size。

误区三是“忽略分词器”。中文环境下如果直接用 standard 分词器，“猕猴桃”可能被切成“猕”“猴”“桃”，用户搜“猕猴桃”反而匹配不上。生产环境几乎都要配 IK、Smart Chinese 这类中文分词器，并且要区分索引分词器和搜索分词器。这些误区看着基础，却恰恰是行业落地时最容易暴露问题的环节。

2. 落地第一步：Windows 环境安装与版本选型

2.1 JDK 版本与 Elasticsearch 版本怎么配对

很多第一次在 Windows 上安装 ES 的人，第一反应是去官网下 JDK。这里要提醒一句：ES 的安装包内置了 OpenJDK，正常情况下你不需要额外设置 JAVA_HOME。但是，内置 JDK 不等于高枕无忧，因为 ES 不同版本对 Java 有明确要求，比如 8.x 版本基于 JDK 17 构建，7.x 系列则有自己对应支持的 Java 版本范围。最稳妥的做法是查官方兼容矩阵，不要想当然装个 JDK 21 就以为“越高越好”。

我在 Windows 上调试时，遇到过两个和 JDK 相关的典型问题。一是机器上装了多个 JDK，启动脚本检测到 JAVA_HOME 指向了不兼容版本，ES 启动后直接报Java version错误。解决办法是把 JAVA_HOME 临时指向 ES 要求的 JDK 路径，或者干脆把环境变量里的 JAVA_HOME 暂时改名。二是内存参数不合理，默认的 jvm.options 在某些机器上会分配过大堆内存，启动就会报内存不足。建议修改config/jvm.options里的-Xms和-Xmx，开发机给 1g 或 2g 足够，生产环境再按实际数据量评估。

热词里提到的 ES 9.x 版本，其实也沿用了同样的安装逻辑。不管版本号怎么变，你只要记住一个流程：下载压缩包、解压到英文路径、确认 JDK 兼容、调整 JVM 参数、启动脚本、验证端口。ES 对中文路径支持不稳定，解压路径里带“程序”或者“下载”这种中文名，启动时有可能报错或行为诡异，所以路径一定用纯英文。

2.2 Windows 启动与安装步骤

Windows 上安装 ES 其实不复杂，我以 8.x 为例记录一下完整步骤。先去官网下载 zip 压缩包，解压后目录结构长这样：bin 放启动脚本，config 放配置文件，logs 放日志，plugins 放插件。打开终端，进入 bin 目录，执行：

elasticsearch.bat

启动过程会打印一堆日志，看到started字样基本就成功了。然后打开浏览器访问http://localhost:9200，返回一个包含cluster_name和tagline的 JSON，说明服务起来了。如果你是通过远程浏览器访问开发机的 ES，需要修改config/elasticsearch.yml里的network.host，同时设置http.port，并注意开启防火墙端口。

8.x 版本默认开启了安全认证，第一次启动会在终端打印一个 elastic 用户的初始密码，还会生成证书。生产环境建议保留认证并妥善保存密码；本地快速调试嫌麻烦，可以在elasticsearch.yml里临时关闭安全认证：

xpack.security.enabled: false

不过这只是开发环境省事用的，正式环境千万不要这样。启动闪退也是 Windows 上的高频问题，最常见原因是 JVM 堆内存设置过大、数据目录权限不对、端口 9200 被占用。遇到闪退不要懵，去 logs 目录翻elasticsearch.log，多数原因日志里写得清清楚楚，只是很多人习惯只看终端滚动条，忽略了文件日志。

2.3 浏览器方式的在线控制台

服务起来之后，需要一个趁手的查询工具。虽然可以直接在浏览器地址栏拼 RESTful URL，但参数多了就非常难受。ES 生态里最常见的浏览器控制台有两个：Kibana 的 Dev Tools 和各种社区控制台插件。Kibana 和 ES 版本要配套，启动后进入http://localhost:5601，左侧菜单找到 Dev Tools，就能执行GET /_cluster/health、POST /index/_search这类命令，还有自动补全和请求历史记录，排查问题时效率高很多。

除了 Kibana，我还用过 Elasticsearch Head、Cerebro 这类老牌控制台工具。它们对查看分片分布、索引状态更直观，适合日常巡检。如果只是本地调试，Kibana Dev Tools 完全够用。需要注意一点：生产环境不要随意开action.destructive_requires_name: false这种危险配置，也不要让插件面板暴露在公网，否则很容易被扫描到然后被写入垃圾索引。

2.4 部署时的内存和系统参数

单机跑通 ES 很简单，但生产部署要考虑的细节多得吓人。先看内存。ES 默认堆大小是物理内存的一半，但业界经验是堆内存不要超过 31GB，因为超过这个值 JVM 的压缩普通对象指针会失效，内存利用率反而下降。开发机 8G 内存，-Xms4g -Xmx4g已经不小；如果只有 4G 内存，建议给 1g 到 2g，剩下的要留给 Lucene 的堆外缓存。

再看集群配置。多节点部署时，每个节点都需要指定node.name，主节点候选要配cluster.initial_master_nodes，节点之间要能互相访问 9300 端口。很多人图省事，直接用默认单节点配置，然后把多份节点启在同一台机器上，结果脑裂、分片无法分配的问题接踵而至。Windows 上做单机多节点测试可以，生产环境千万别这么干。

最后是索引生命周期。行业落地时，日志类数据增长极快，不能一直往一个索引里写。建议按天或按周建索引，配合 Index Lifecycle Management 自动滚动和删除。我见过有团队没做 ILM，半年后一个索引跑了几个 TB，查询慢、备份慢、恢复也慢，最后只能咬着牙重建。这些部署期的“土办法”，往往比查询优化更能决定系统能走多远。

3. 核心建模与查询：从理论到可复用模板

3.1 索引 Mapping 设计：电商商品模块为例

电商商品模块是个特别典型的 ES 落地场景，因为商品查询条件多、排序维度复杂。假设我们要把商品表同步到 ES，字段大概有商品 ID、标题、类目、品牌、价格、库存、上架状态、创建时间。如果直接照搬 MySQL 字段类型，Mapping 十有八九是灾难。正确的设计应该是：

{ "mappings": { "properties": { "productId": { "type": "keyword" }, "title": { "type": "text", "analyzer": "ik_max_word", "search_analyzer": "ik_smart", "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } } }, "categoryId": { "type": "keyword" }, "brandId": { "type": "keyword" }, "price": { "type": "double" }, "stock": { "type": "integer" }, "status": { "type": "keyword" }, "createTime": { "type": "date", "format": "strict_date_optional_time||epoch_millis" } } } }

这里有几个容易被忽略的点。productId这种精确匹配的 ID 用 keyword，不要用 long，因为同一份数据在 Kafka、数据库和 ES 里的兼容性更好。title用了 text 做全文检索，又通过fields.keyword做了精确匹配，这样既能搜“黑色连衣裙”，也能做“标题完全一致”的过滤。categoryId和brandId用 keyword 而不是 long，是为了避免在 term 查询和 terms 聚合时出现类型映射问题。createTime建议用 date 类型，方便做时间范围筛选和日期直方图聚合。

设计 Mapping 的核心是反向思考：想清楚将来会有哪些查询，再往前推导字段类型。比如库存字段，如果只需要做条件过滤，integer 就够了；如果要做“按库存余量排序”，可能还需要考虑fielddata或者 doc_values 的设置。提前多想一版，后面能少建一两次索引。

3.2 分词器与中文检索

中文分词是 ES 落地绕不开的话题。标准分词器把中文按单字切，搜索体验很差。行业里最常用的是 IK 分词器，它支持ik_max_word和ik_smart两种粒度。前者会尽可能切出更多词，索引时用；后者更偏向句子的自然语义，搜索时用。这样一来，搜“深度学习”时，既能命中“深度”，也能命中“学习”，还能保持整体词组的权重优先。

安装 IK 分词器很简单，下载和 ES 主版本一致的 zip 包，解压到 plugins/ik 目录，重启 ES 即可。然后可以用_analyze接口测试效果：

GET _analyze { "text": "珍珠奶茶", "analyzer": "ik_max_word" }

输出里能看到“珍珠”“奶茶”“珍”“珠”这些词条。如果没有自定义词库，像“特斯拉”这种品牌名可能被切成“特”“斯拉”，这时候就要在 IK 的词典文件里加自定义词。还有一个容易踩的坑：ik_smart和ik_max_word用在不同阶段，如果索引和搜索分析器都设成同一档，部分查询结果会变得很奇怪。所以最佳实践是索引用ik_max_word尽可能覆盖词条，搜索用ik_smart专注语义。

3.3 聚合分析的几个高频写法

聚合是 ES 区别于普通搜索的重要能力。日志统计、订单报表都靠它。最常用的有 terms 聚合、date_histogram 聚合、filter 聚合。比如统计某电商平台每天的下单量，可以这样写：

GET /order_index/_search { "size": 0, "aggs": { "daily_orders": { "date_histogram": { "field": "createTime", "calendar_interval": "day" }, "aggs": { "total_amount": { "sum": { "field": "amount" } } } } } }

这里的size: 0表示只拿聚合结果，不返回明细。date_histogram按天分桶，桶内再算金额总和。这种方式在运营后台查“最近三十天销售趋势”时非常好用。

聚合查询的底层原理是 doc_values，所以参与聚合的字段必须是doc_values默认开启的字段。曾经有人拿 text 字段做 terms 聚合，直接报错，因为 text 默认不开启 doc_values。解决办法是用 keyword 子字段或者开启 fielddata，但 fielddata 内存消耗高，生产环境慎用。另一个常见问题是聚合桶太多，结果不准。ES 默认size: 10，只返回前十项聚合桶，别指望默认状态能给你完整分类统计。

3.4 数据一致性：与 MySQL/MongoDB 的协作方式

ES 不是主库，数据一致性的本质是“最终一致”。行业落地最常见的模式有三种：同步双写、异步 MQ、Binlog 监听。同步双写简单直接，业务代码在写入 MySQL 后，紧接着写入 ES，适合数据量小、一致性要求相对高的场景。缺点是代码侵入强，一旦 ES 写失败容易影响主流程，所以通常加上失败重试或降级。

异步 MQ 是我比较推荐的方式。业务方只发一条消息，由消费者异步写入 ES。这样主流程不依赖 ES 的可用性，同时可以利用消息重试机制处理失败。Binlog 监听则适合那种旧系统改不动代码、又想快速接入 ES 的存量数据迁移，通过 Canal 这类中间件解析 MySQL binlog，再投递到 ES。数据最终一致，但要接受几十毫秒到几秒的延迟。

还有团队会问，那 MongoDB 呢？ES 和 MongoDB 确实都属于 NoSQL 阵营，但定位不同。MongoDB 适合存文档型数据，事务能力和查询语法更接近数据库；ES 的核心是倒排索引和聚合分析。它们不是替代关系。一个可行组合是：业务主库用 MongoDB，搜索和分析场景把数据同步到 ES。后面我会专门写一节对比，这里先记住“各司其职”。

4. 行业应用落地：从电商订单到高并发场景

4.1 商品检索与库存维度

商品检索最怕的不是查询慢，而是查询结果不符合业务预期。一个典型需求是：用户搜“华为手机 256G”，既要命中标题里有“华为”和“手机”的商品，又希望品牌是华为、价格区间在某个范围内，同时过滤掉下架商品。写成 Query DSL 时，核心是 bool 查询：

GET /product_index/_search { "query": { "bool": { "must": [ { "match": { "title": "华为手机 256G" } } ], "filter": [ { "term": { "brandId": "HUAWEI" } }, { "range": { "price": { "gte": 2000, "lte": 6000 } } }, { "term": { "status": "ON" } } ] } } }

这里特意把价格、状态放到 filter，而不是 must。原因很简单，filter 只做过滤，不走相关性打分，结果会被缓存，性能更好。商品筛选项多，但用户翻到第二页、第三页时，查询条件基本不变，filter 缓存收益非常明显。如果需要在过滤的同时修改排序，可以用function_score把库存、销量、上架时间这些业务因子叠加进去。

关于库存字段，有个小技巧：不要把实时库存和商品检索放在同一个字段强依赖。电商场景下库存变化频繁，如果每秒都在更新 ES，索引压力很大。常见做法是把“是否有货”这种低频状态同步到 ES，实时库存继续由 Redis 和数据库扛。用户看到有货后才下单，下单时由业务系统再校验一次实际库存。这是业务视角下商品模块和库存模块解耦的标准玩法。

4.2 订单过期与状态机在 ES 中的应用

“订单过期了怎么办”这类问题，在订单中心里太常见了。用户下单后如果超时未支付，订单要自动关闭。这个状态变化通常在 MySQL 里通过定时任务或延迟消息处理，和 ES 没有直接关系。但问题在于：用户和客服都可能在 ES 里查订单状态，如果 ES 的状态更新晚于 MySQL，就会产生数据不一致的体验。

我在项目中遇到过类似情况。订单在 23:59 过期关闭，业务系统已经改了 MySQL 状态，但 ES 里的状态还是“待支付”，用户一搜订单列表，发现订单还能看到“去支付”按钮，一点却提示已关闭。后来我们把订单状态同步改成 MQ 异步通知，并加了明细状态机校验，所有状态变更都必须带version字段，ES 更新时用_seq_no做乐观并发控制。效果立竿见影，但代价是每次更新状态都要额外传版本号。

再往深一层说，订单检索场景本身很适合 ES。订单表动辄上亿行，用 MySQL 做多维筛选效率偏低。把订单写入 ES 后，运营可以按用户、店铺、时间、金额、状态组合搜索，还能用聚合统计 GMV 和退款率。此时索引 Mapping 里的订单状态建议用 keyword，金额用 double 或 scaled_float，创建时间用 date。订单数据实时性要求高，可以选用 Canal 监听 MySQL binlog，延迟基本控制在秒级以内。

4.3 秒杀场景下的服务熔断和降级

秒杀是电商领域最考验系统稳定性的场景之一，ES 在这种场景下既要承接大量商品查询，又可能被瞬时流量打垮。很多团队的误区是把秒杀商品索引和普通商品索引混在一起，瞬间的搜索请求全部压到同一批分片上，结果不只是慢，严重的会把整个集群 CPU 打满，影响其他业务。

我建议秒杀场景做三件事。第一，商品预热。秒杀开始前把热门商品从 ES 刷到 Redis，查询链路优先走 Redis，ES 只做兜底。第二，服务熔断。调用 ES 的超时时间要单独设置，不能和普通查询共用同一套超时配置。如果 ES 平均响应时间超过阈值，直接熔断降级到静态缓存或数据库。第三，限流隔离。给秒杀相关索引单独建集群或单独节点，避免资源争抢。还有一种做法是写入 ES 的秒杀索引只保留未结束的活动数据，活动结束后立即删除或切换到归档索引，减少无关扫描。

说到服务熔断和降级，热词里经常把它和 Spring Boot 放在一起。现实项目中，我们用的是 Sentinel 或 Hystrix 对 ES 调用做线程池隔离。一旦 ES 查询异常比例升高，快速失败返回默认值，而不是让请求排队堆积。熔断的目的是保护 ES，也是保护业务系统本身。很多人只关注 ES 集群内部优化，忽略了调用端的保护机制，结果 ES 一抖动，整条链路跟着雪崩。

4.4 多实例部署下的 Session 共享与服务发现

服务多次部署后如何共享 Session，是老生常谈的问题，但经常被拉出来问。先说 cookie 和 session 的区别：cookie 存在客户端，session 存在服务端，sessionId 通常放在 cookie 里。单机部署时 session 存在本机内存没问题，多实例部署后请求被负载均衡到不同节点，本机 session 对不上，用户就掉线了。解决办法是 session 集中存储，比如放到 Redis，或者改用 JWT 这类无状态 token。

这跟 ES 有什么关系呢？关系在于整个链路中的数据一致性。session 共享用 Redis 后，用户的登录状态和业务状态分离了，但用户的操作日志、商品点击日志还是要进 ES，用来做行为分析和推荐。ES 在整个分布式系统里更像是“读模型”和“分析模型”，而 Redis 是“临时状态模型”。如果团队里有人不太理解这些中间件的职责边界，很容易出现用 ES 存 session、用 Redis 做搜索的怪事。

Spring Boot 服务注册和发现用 Nacos 或 Eureka 比较常见。服务启动后把自己 IP 和端口注册到注册中心，消费者再去注册中心拉取服务列表。这个过程和 ES 节点发现有一些相似之处，ES 集群里的节点也需要通过discovery.seed_hosts互相发现。理解了一个，另一个也就好懂了。知识体系就是这样，很多概念是相通的，别孤立地学中间件。

4.5 并发更新与版本冲突处理

数据库死锁一般出现在两个事务互相持有对方需要的锁，避免方法是统一加锁顺序、缩短事务时间、合理使用索引。ES 里没有传统意义上的事务和行锁，但并发更新同一个文档时会遇到版本冲突。举个例子，两个消费者线程同时更新商品库存，各自读到旧版本，后提交的请求可能把前一个更新给覆盖掉，或者直接报版本冲突异常。

ES 的文档更新接口默认带乐观并发控制，每次更新都可以带if_seq_no和if_primary_term参数，服务端校验版本匹配才执行。在业务代码里，我们通常把版本号放到请求内容里，更新前先从 ES 查询当前版本，提交时带上版本，失败了就重试。这比单纯用“先读再写”的普通方式安全得多。

死锁问题同样会出现在 ES 和业务数据库的跨系统操作中。比如在一个事务里先写 MySQL，再调 ES 同步，结果 ES 超时，事务回滚了，ES 却写进去了，两边不一致。这种问题没法用数据库死锁解决，只能通过补偿任务或消息队列做最终一致。理解这个思路后，再回头看“三个修饰符修饰 list 后还能不能改”之类的 Java 并发问题，会发现不同抽象层级要处理的是不同粒度的“锁”和“一致性”。

5. 常见问题与排查技巧实录

5.1 Elasticsearch 与 MongoDB 到底怎么选

热词里常有人问：“了解 mongodb 和 elasticsearch 框架吗？”这两个东西放一块比较，说明提问者还没完全分清存储和检索的边界。MongoDB 是文档数据库，擅长存储字段不固定的 JSON 结构，有完整的 CRUD 和事务能力；Elasticsearch 是分布式搜索和分析引擎，倒排索引和聚合是它的强项。如果业务要长期保存数据、需要事务和复杂更新，首选 MongoDB；如果要做站内搜索、日志分析、指标统计，首选 Elasticsearch。

很多团队会把 MongoDB 当作主库，然后同步数据到 ES 支撑检索。这个组合很常见。需要注意的点是：MongoDB 的_id同步到 ES 后应该用 keyword 类型，不要把ObjectId转成字符串后丢进 text 字段。还要处理好删除和更新事件，因为 Mongo 的变更流可以很自然地把操作投递给 MQ，再写入 ES。如果只是简单把 ES 当 MongoDB 的“加速索引”，架构上完全没问题，关键是不能在 ES 里做频繁的文档级更新，否则副本和分片的消耗会让你怀疑人生。

对比表看看更清晰：

5.2 Session 共享、Cookie 与 ES 的关联

cookie 和 session 的区别一句话就能说清：cookie 是客户端保存的数据，session 是服务端保存的数据。服务端通过 sessionId 找到对应 session，sessionId 一般存在 cookie 里。多实例部署后，session 必须集中存储，最普遍的是 Redis。这和 ES 的关系其实在“用户行为链路”上：用户登录后，搜索行为、浏览行为、下单行为会被记录，这些数据进入 ES 后可以为个性化推荐和运营分析提供输入。

有人会问，session 能不能存 ES？理论上可以，但不要这么做。ES 更新文档的吞吐量和并发控制都比较重，session 需要毫秒级读写的场景，Redis 是更合适的选择。ES 更适合存储最终沉淀下来的行为数据，而不是临时会话状态。把合适的数据放在合适的存储里，才是最佳实践。

实战中，我们会在用户搜索请求上加上一个 requestId，这个 ID 会贯穿网关、业务、ES 查询日志。用户反馈“页面卡顿”时，只要在 ES 日志里按 requestId 搜索，就能把整条链路的耗时和报错串起来。多实例服务共享 Session 后，这个 requestId 依然有效，因为它不依赖本地 session，而是放在请求头和日志上下文里。这也是另一种形式的“共享状态”治理。

5.3 死锁、慢查询与集群健康检查

死锁在数据库里要尽量通过加锁顺序和事务边界避免，ES 里虽然少有死锁，但会有“查询堆积导致节点假死”的情况。ES 慢查询的典型表现是 CPU 高、响应慢、队列积压。排查第一步不是翻监控，而是先看_cluster/health，确认集群状态是不是 green。如果是 yellow，大概率有副本分片没分配；如果是 red，说明主分片丢了，必须马上处理。

再用一条命令看热点节点：

GET _cat/nodes?v=true&h=name,cpu,heap.percent,ram.percent,load_1m

如果某个节点 CPU 一直很高，可以进一步查慢查询日志和热线程。ES 在config/log4j2.properties里有慢查询日志的配置入口，开启后能在索引日志里看到查询耗时超过阈值的请求体。排查慢查询时，第一步一定是分析查询语句，很多慢查询是 term 查询写错了字段，导致查询扫了整个索引；第二步看索引段数量和分片大小；第三步才考虑加节点。

还有一个频繁遇到的问题：虽然集群是 green，但搜索还是会超时。这通常因为分片设计不合理。一个分片太大，比如超过 50GB，查询性能就会明显下降。最佳实践是根据数据总量规划分片数，单分片建议控制在 20GB 到 40GB 之间。日志类索引按时间切分后，分片数量天然可控。如果发现已有索引分片过大，别硬等，直接用 reindex 重建索引，长痛不如短痛。

5.4 WikiJS 调试 Elasticsearch 的踩坑记录

WikiJS 是一个流行的开源 Wiki 系统，它默认可以用 PostgreSQL、SQLite 或 MySQL 做存储，也支持接入 Elasticsearch 做全文搜索。我在调试 WikiJS 对接 ES 时踩过几个坑，记下来给大家参考。首先是版本兼容问题，WikiJS 要求的 ES 版本和 ES 服务版本不匹配时，日志里会出现Status: 400或者version_conflict的报错。建议先查一下当前 WikiJS 版本对应的搜索引擎配置文档，再选择 ES 版本。

其次，WikiJS 管理后台里填写 ES 连接信息时，endpoint 不要加多余路径。比如http://localhost:9200就好，不要写成http://localhost:9200/wikijs。如果 ES 启用了安全认证，要在配置里加上 username 和 password，否则建索引和写入文档都会报401。

调试时最实用的手段是在 Kibana Dev Tools 里执行：

GET _cat/indices?v=true

看看有没有wikijs前缀的索引被创建出来。如果索引存在但没有文档，多半是 WikiJS 的同步任务没跑起来，需要去管理后台的搜索页面手动触发索引更新。如果索引完全不存在，检查 WikiJS 日志看连接是否成功。这套排查思路也适用其他 CMS 对接 ES，核心是先确认“索引是否创建”，再确认“文档是否写入”，最后确认“查询是否命中”。

调试过程中还有个小细节：ES 的illegal_argument_exception错误信息往往很直接，比如unknown field [xxx]，意思就是 Mapping 里没有这个字段。多读日志，少猜问题。我用 WikiJS 调试 ES 那几天，最大的收获反而是养成了“先看索引状态、再看分片、最后看查询 DSL”的习惯，这个习惯让我在之后的所有 ES 排障里都少踩了很多坑。

如果只让我留一句经验，我会说：Elasticsearch 的行业落地，难点从来不在安装和使用 API，而在建模之前的业务理解，以及遇到问题时的排查顺序。每次交付前，我都会把三件事做一遍：确认 Mapping 没有滥用 text 字段、确认深分页都换成了 search_after、确认集群健康状态是 green。这些不起眼的习惯，才是真正让 Elasticsearch 项目长期稳定运行的关键。