--- title: "Easysearch 开发者入门" date: 2026-02-28 lastmod: 2026-02-28 tags: ["Easysearch", "入门", "介绍"] summary: "前言 - 什么是 Easysearch # 在介绍 Easysearch 之前，我们无法绕过 Elasticsearch（简称 ES）。作为全文检索领域的绝对霸主，ES 几乎是所有搜索和日志分析场景的首选。但是， 自 2021 年 ES 宣布修改开源协议（从 Apache 2.0 变更为 SSPL）后，以及同年 Elastics 解散了中国的直销团队，许多企业和开发者开始寻求更稳定、协议更友好的替代方案。 Easysearch 正是在这样的背景下诞生的。 为什么叫 “Easy”？对于中国开发者来说，原生 ES 的“毛坯房”体验往往伴随着不少痛点：下载后要寻找对应版本的中文分词插件、企业级的安全功能缺失，只有简单的用户权限控制、在黑乎乎的命令行使用 cURL 拼 DSL 体验劝退、用了 SQL 插件但却不支持 JOIN。 Easysearch 的核心理念就是“开箱即用”，它在保持与 ES 7.10.2 API 100% 兼容的基础上，替开发者完成了以下工作： 原生集成中文分词：默认集成了最流行的 analysis-ik 插件，不再需要因为版本不匹配而头秃，下载启动即可处理中文。 企业级安全特性：提供了完善的安全管控能力，支持细粒度的权限控制，保障数据安全。 内置管理 UI: 告别命令行操作，大多数功能可在 UI 完成。DSL 编写有语法高亮和自动补全。 自主可控: 源码完全自主可控，掌握核心研发。全面国产 OS / CPU / 主机 / 存储 / 算法，适配兼容测试优化。 基本概念 # Easysearch 是一个分布式的搜索引擎，底层基于 Lucene。为了方便理解，我们通常会将它的概念与我们熟悉的关系型数据库（如 MySQL）进行类比。" --- # 前言 - 什么是 Easysearch 在介绍 Easysearch 之前，我们无法绕过 Elasticsearch（简称 ES）。作为全文检索领域的绝对霸主，ES 几乎是所有搜索和日志分析场景的首选。但是，[自 2021 年 ES 宣布修改开源协议（从 Apache 2.0 变更为 SSPL）后](https://www.elastic.co/blog/elastic-license-update)，以及同年 Elastics 解散了中国的直销团队，许多企业和开发者开始寻求更稳定、协议更友好的替代方案。 **Easysearch 正是在这样的背景下诞生的。** 为什么叫 "Easy"？对于中国开发者来说，原生 ES 的“毛坯房”体验往往伴随着不少痛点：下载后要寻找对应版本的中文分词插件、企业级的安全功能缺失，只有简单的用户权限控制、在黑乎乎的命令行使用 cURL 拼 DSL 体验劝退、用了 SQL 插件但却不支持 JOIN。 Easysearch 的核心理念就是“开箱即用”，它在保持与 ES 7.10.2 API **100% 兼容**的基础上，替开发者完成了以下工作： - **原生集成中文分词**：默认集成了最流行的 analysis-ik 插件，不再需要因为版本不匹配而头秃，下载启动即可处理中文。 - **企业级安全特性**：提供了完善的安全管控能力，支持细粒度的权限控制，保障数据安全。 - **内置管理 UI**: 告别命令行操作，大多数功能可在 UI 完成。DSL 编写有语法高亮和自动补全。 - **自主可控**: 源码完全自主可控，掌握核心研发。全面国产 OS / CPU / 主机 / 存储 / 算法，适配兼容测试优化。 # 基本概念 Easysearch 是一个分布式的搜索引擎，底层基于 Lucene。为了方便理解，我们通常会将它的概念与我们熟悉的关系型数据库（如 MySQL）进行类比。 | **概念** | **对应关系型数据库 (MySQL)** | **说明** | | -------------------- | ---------------------------- | ---------------------------------------- | | **Index (索引）** | **Table (表)** | 数据的逻辑容器，存储具有相同结构的文档。 | | **Document （文档)** | **Row (行)** | 存储的每一条具体数据。 | | **Field (字段)** | **Column (列)** | 文档中的属性，如 name、age。 | | **Mapping** | **Schema (表结构)** | 定义字段类型（是数字还是字符串）。 | | **DSL** | **SQL** | Easysearch 两者都支持。 | ## Node（节点）与 Cluster（集群） - **Node（节点）**：一台运行着 Easysearch 进程的服务器。 - **Cluster（集群）**：由一个或多个节点组成，它们协同工作，共同存储数据并处理搜索请求。 Easysearch 是一个分布式数据库，允许多台服务器协同工作，每台服务器可以运行多个 Easysearch 实例。 ## Index（索引） **Index** 是含有相同属性的文档的集合。它对应数据库中的 **Table（表）**。 - 如果你要存用户数据，你会创建一个 user 索引。 - 如果你要存商品数据，你会创建一个 product 索引。 之所以叫 Index 而不是 Table 是因为 Easysearch 默认会对其中的文档建议索引，查找数据的时候，直接查找该索引。 ## Document（文档） **Document** 是你可以索引的基本信息单元，对应数据库中的 **Row（行）**。Easysearch 使用 **JSON** 格式来表示一个文档。 一条 MySQL 里的数据行可能是这样： | name | age | job | | ------ | --- | ------------ | | '张峰' | 32 | '电路工程师' | 而在 Easysearch 中，对应的 Document 是这样： ```json { "name": "张峰", "age": 32, "job": "电路工程师" } ``` ## Field（字段） 文档中的每一个 JSON Key，就是一个 **Field**，对应数据库中的 **Column（列）**。 你需要根据业务场景为字段定义类型： - text：会被分词，用于全文检索（如“华为手机”可以搜到“华为”）。 - keyword：不分词，用于精确匹配和聚合（如“北京”只能完整匹配“北京”）。 - date、long、double 等：标准数据类型。 # 安装与运行 (本地) ## 下载 Easysearch 原生支持在 Linux 和 macOS 上运行，也可以通过 WSL 在 Windows 上运行。 获取 Easysearch 本地版本最简单的方法是运行以下 cURL 命令。它会自动检测你的操作系统是否支持，并下载对应的 Easysearch 2.0.2 二进制文件。默认脚本会将 Easysearch 文件下载到 `/opt/easysearch`，如果你想将其下载到其他路径，请指定 `-d`参数。可能需要 sudo，如果当前账户没有下载路径的写入权限。 ```sh curl -sSL http://get.infini.cloud | bash -s -- -p easysearch -v 2.0.2 ``` 运行安装命令，你会看到： ```sh $ curl -sSL http://get.infini.cloud | bash -s -- -p easysearch -v 2.0.2 -d ~/easysearch @@@@@@@@@@@ @@@@@@@@@@@@ @@@@@@@@@@@@ @@@@@@@@@&@@@ #@@@@@@@@@@@@@ @@@ @@@@@@@@@@@@@ &@@@@@@@ &@@@@@@@@@@@@@ @&@@@@@@@&@ @@@&@@@@@@@&@ @@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@& @@@@@@@@@@@@@ %@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@&@@@@@@@@@@@@@@@ @@ ,@@@@@@@@@@@@@@@@@@@@@@@& @@@@@. @@@@@&@@@@@@@@@@@@@@ @@@@@@@@@@ @@@@@@@@@@@@@@@# @&@@@&@@@&@@@ &@&@@@&@@@&@ @@@@@@@@@@@@@. @@@@@@@* @@@@@@@@@@@@@ %@@@ @@@@@@@@@@@@@ /@@@@@@@&@@@@@ @@@@@@@@@@@@@ @@@@@@@@@@@@@ @@@@@@@@@@@@ Welcome to INFINI Labs! Now attempting the installation... Name: [easysearch], Version: [2.0.2-2499], Path: [/home/user/easysearch] File: [https://release.infinilabs.com/easysearch/stable/easysearch-2.0.2-2499-linux-amd64.tar.gz] ######################################################################## 100.0% Installation complete. [easysearch] is ready to use! ---------------------------------------------------------------- cd ~/easysearch && bin/initialize.sh && bin/easysearch ---------------------------------------------------------------- __ _ __ ____ __ _ __ __ / // |/ // __// // |/ // / / // || // _/ / // || // / /_//_/|_//_/ /_//_/|_//_/ ©INFINI.LTD, All Rights Reserved. ``` ## 初始化 现在运行初始化脚本进行初始化工作，在初始化过程中，脚本会询问是否要安装插件，我们使用 `-s`参数来回答 yes： ```shell $ cd ~/easysearch $ ./bin/initialize.sh -s ``` 你会看到如下的输出 ```shell @@@@@@@@@@@ @@@@@@@@@@@@ @@@@@@@@@@@@ @@@@@@@@@&@@@ #@@@@@@@@@@@@@ @@@ @@@@@@@@@@@@@ &@@@@@@@ &@@@@@@@@@@@@@ @&@@@@@@@&@ @@@&@@@@@@@&@ @@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@& @@@@@@@@@@@@@ %@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@&@@@@@@@@@@@@@@@ @@ ,@@@@@@@@@@@@@@@@@@@@@@@& @@@@@. @@@@@&@@@@@@@@@@@@@@ @@@@@@@@@@ @@@@@@@@@@@@@@@# @&@@@&@@@&@@@ &@&@@@&@@@&@ @@@@@@@@@@@@@. @@@@@@@* @@@@@@@@@@@@@ %@@@ @@@@@@@@@@@@@ /@@@@@@@&@@@@@ @@@@@@@@@@@@@ @@@@@@@@@@@@@ @@@@@@@@@@@@ Welcome to INFINI Labs! Now attempting the initializing... ###################################################################### # !!! RISK WARNING !!! # ###################################################################### This script is about to perform destructive operations: - It will DELETE and OVERWRITE any existing certificates. - It will RESET the admin password if the data directory is empty. If this is not a fresh installation, all existing cluster nodes and clients using the old certificates will lose connection. Are you absolutely sure you want to proceed? [y/N]: y Risk acknowledged. Proceeding with initialization... --- Operation Logging (Optional) --- For debugging purposes, you can choose to log the generated credentials to a file. This is NOT RECOMMENDED for production environments. Do you want to log operation to '/home/user/easysearch/logs/initialize.log'? [y/N]: y INFO: Operation will be logged to: /home/user/easysearch/logs/initialize.log INFO: EASYSEARCH_INITIAL_ADMIN_PASSWORD is not set. Generating a new strong random password INFO: Using existing JAVA_HOME: /usr/lib/jvm/java-21-openjdk-21.0.5.0.11-1.fc39.x86_64 (Version: 21) Certificate request self-signature ok subject=C = IN, ST = FI, L = NI, O = ORG, OU = UNIT, CN = infini.cloud Certificate request self-signature ok subject=C = IN, ST = FI, L = NI, O = ORG, OU = UNIT, CN = admin.infini.cloud DNS:infini.cloud, DNS:*.infini.cloud DNS:infini.cloud, DNS:*.infini.cloud @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: all easysearch plugins will be installed @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ Install easysearch plugins with online resources. [y/N]: y INFO: Installing Easysearch plugins... - Successfully installed 'sql' - Successfully installed 'analysis-ik' - Successfully installed 'analysis-pinyin' - Successfully installed 'analysis-stconvert' - Successfully installed 'ingest-common' - Successfully installed 'ingest-geoip' - Successfully installed 'ingest-user-agent' - Successfully installed 'mapper-annotated-text' - Successfully installed 'mapper-murmur3' - Successfully installed 'mapper-size' - Successfully installed 'transport-nio' - Successfully installed 'knn' - Successfully installed 'ai' - Successfully installed 'ui' ✅ All 14 Easysearch plugins have been installed successfully. ########################################################################## ✅ Easysearch is ready to use! You can connect to the cluster using the following bootstrap credential via API: curl -ku 'admin:NRgm=Ra6Ig2pgQRw8+y#pnv!' https://localhost:9200 Or visit the web based management console: https://localhost:9200/_ui/ 🔑 IMPORTANT: Please save the password shown above in a secure location. └── NOTE: This initial password is only valid for the first startup. ########################################################################## ---------------------------------------------------------------- cd /home/user/easysearch && bin/easysearch ---------------------------------------------------------------- __ _ __ ____ __ _ __ __ / // |/ // __// // |/ // / / // || // _/ / // || // / /_//_/|_//_/ /_//_/|_//_/ ©INFINI.LTD, All Rights Reserved. ``` 在脚本输出中，我们可以看到脚本为 admin 账户生成了一个随机密码 `NRgm=Ra6Ig2pgQRw8+y#pnv!`，我们需要保存下来以备后面使用。 ## 启动 Easysearch server 在一个终端中运行 easysearch ```shell $ ./bin/easysearch ``` 可以在另一个终端中运行 cURL 命令验证 Easysearch 是否成功启动： ```shell $ curl -ku 'admin:NRgm=Ra6Ig2pgQRw8+y#pnv!' https://localhost:9200 { "name" : "fedora", "cluster_name" : "easysearch", "cluster_uuid" : "CWvvlsXZQW-_7h-uD77M-w", "version" : { "distribution" : "easysearch", "number" : "2.0.2", "distributor" : "INFINI Labs", "build_hash" : "f9f6be82d56cc71ad6b0f67b6da32a7898c4c23a", "build_date" : "2025-12-17T01:49:20.267870870Z", "build_snapshot" : false, "lucene_version" : "9.12.2", "minimum_wire_lucene_version" : "8.7.0", "minimum_lucene_index_compatibility_version" : "8.7.0" }, "tagline" : "You Know, For Easy Search!" } ``` # 快速上手 如果你用过原生 Elasticsearch，一定经历过对着 9200 端口返回的 JSON 字符串发呆的时刻——如果不额外部署 Kibana 或 Cerebro，你很难直观地了解集群到底在发生什么。 Easysearch 则贴心地内置了**可视化管理界面**（Dashboard）。启动服务后，你不仅拥有一个强大的搜索引擎，还获得了一个功能完备的控制台，我们可以在浏览器访问 `https://127.0.0.1:9200/_ui` > 我在另一台机器上启动的 Easysearch，所以集群地址是 `htps://192.168.3.119:9200`，如果你在本机启动，那么集群地址就应该是 `https://127.0.0.1:9200`。 ![](/img/knowledge-base/basic/easysearch-developer-getting-started/1.png) 输入用户名和密码即可进入。 ![](/img/knowledge-base/basic/easysearch-developer-getting-started/2.png) 这个界面为开发者提供了上帝视角： - **集群全景监控**： - **健康状态**：大大的绿色 "green" 让你对系统状态一目了然。 - **资源仪表盘**：实时展示 **CPU、内存、JVM 堆内存**以及**磁盘使用率**。以前需要敲几行命令才能看到的指标，现在直接图形化呈现，性能瓶颈一眼便知。 - **拓扑视图**：右下角的拓扑图直观展示了节点分布，多节点集群管理不再抽象。 - **开发者的神兵利器**： - 请特别留意左侧菜单中的 **“开发工具” (Dev Tools)**。对于开发者来说，这是最常用的功能。它提供了一个支持语法高亮和自动补全的 Web 编辑器，你可以在这里直接编写 DSL 进行查询调试，彻底告别在终端里手敲 cURL 命令的痛苦。 - **核心资源管理**： - 你可以直接在界面上管理 **索引**、**分片 **和 **安全管理**，无需记忆复杂的运维 API。 ## 创建索引 (Create Table) 接下来的上手操作，我们将用到 UI 的开发工具，在其中编写 DSL。我们在左侧编写 DSL，使用 command (Windows 是 ctrl) + enter 键即可运行 DSL，结果将在右侧展示： ![](/img/knowledge-base/basic/easysearch-developer-getting-started/3.png) 在关系型数据库中，你需要先定义表结构（Schema）。在 Easysearch 中，我们创建一个名为 my_first_index 的索引，并定义字段映射。将下面的代码块内容拷贝到开发工具中，无需指定集群地址/用户/密码，开发工具会帮我们处理掉这些细节： ```json PUT /my_first_index { "mappings": { "properties": { "id": { "type": "long" }, "title": { "type": "keyword" }, "content": { "type": "text", "analyzer": "ik_max_word" }, "create_time": { "type": "date" } } } } ``` 我们给 content 字段设置了 `ik_max_word`的 analyzer，以获得更好的中文支持。 ## 写入数据 接下来，我们写入几条包含中文内容的测试数据。为了模拟真实场景，我们使用 \_bulk API 一次性写入多行数据。 ```json POST /my_first_index/_bulk {"index":{"_id":"1"}} {"id":1,"title":"Easysearch简介","content":"Easysearch 是一个基于 Elasticsearch 的衍生版本。","create_time":"2023-01-01"} {"index":{"_id":"2"}} {"id":2,"title":"功能特性","content":"它默认集成了中文分词插件和 SQL 支持。","create_time":"2023-01-02"} {"index":{"_id":"3"}} {"id":3,"title":"开发者体验","content":"开箱即用的体验让开发者告别复杂的配置。","create_time":"2023-01-03"} ``` 返回的 JSON 中包含 `"errors": false`表示写入成功： ![](/img/knowledge-base/basic/easysearch-developer-getting-started/4.png) ## 查询数据 现在数据已经就绪，我们可以开始检索了。这里我们将展示 Easysearch 的两种查询方式：**SQL 查询**（推荐）和 **原生 DSL**。 ### 使用 SQL 查询（像操作 MySQL 一样） ```json POST /_sql?format=txt { "query": "SELECT * FROM my_first_index WHERE MATCH_QUERY(content, '开箱即用') ORDER BY id DESC LIMIT 5" } ``` 我们使用了 `MATCH_QUERY`函数来进行全文搜索 ![](/img/knowledge-base/basic/easysearch-developer-getting-started/5.png) ### 使用 DSL 查询 为了证明中文分词真的在工作，我们尝试搜索“**衍生版本**”。如果是原生 ES（标准分词器），它会将“衍”、“生”拆开匹配，导致噪音；而 Easysearch 会精准匹配这个词组。 ```json GET /my_first_index/_search { "query": { "match": { "content": "衍生版本" } } } ``` ![](/img/knowledge-base/basic/easysearch-developer-getting-started/6.png) ## 总结 至此，你已经掌握了 Easysearch 的基本用法。 回顾一下，Easysearch 并非要重新发明轮子，而是致力于让这个轮子在中文开发环境中滚动的更加顺滑。作为 Elasticsearch 7.10.2 的衍生版本，它完美继承了开源时代的遗产，同时补齐了原生 ES 在**本地化**和**易用性**上的短板： - **对于运维**：它是一行命令即可部署、内置安全与监控的稳定引擎，告别繁琐的插件配置和复杂的集群调优。 - **对于开发**：它是一个听得懂 SQL、看得懂中文、API 完全兼容的强大后端，让你可以专注于业务逻辑而非底层细节。 无论你是由于开源协议变更正在寻找 ES 的替代方案，还是从零开始构建一个新的搜索业务，**Easysearch** 都是目前国内开发者的最优解之一。 # 下一步做什么？ 你可以在[官方文档](https://docs.infinilabs.com/easysearch/main/)中深入了解更多进阶功能，或者直接加入社区，与数千名开发者一起探索搜索技术的边界。 Happy Searching!