前言 - 什么是 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）进行类比。

概念	对应关系型数据库 (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 是这样：

{
  "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，如果当前账户没有下载路径的写入权限。

curl -sSL http://get.infini.cloud | bash -s -- -p easysearch -v 2.0.2

运行安装命令，你会看到：

$ 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：

$ cd ~/easysearch
$ ./bin/initialize.sh -s

你会看到如下的输出


                                 @@@@@@@@@@@
                                @@@@@@@@@@@@
                                @@@@@@@@@@@@
                               @@@@@@@@@&@@@
                              #@@@@@@@@@@@@@
        @@@                   @@@@@@@@@@@@@
       &@@@@@@@              &@@@@@@@@@@@@@
       @&@@@@@@@&@           @@@&@@@@@@@&@
      @@@@@@@@@@@@@@@@      @@@@@@@@@@@@@@
      @@@@@@@@@@@@@@@@@@&   @@@@@@@@@@@@@
        %@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
            @@@@@@@@@@@@&@@@@@@@@@@@@@@@
    @@         ,@@@@@@@@@@@@@@@@@@@@@@@&
    @@@@@.         @@@@@&@@@@@@@@@@@@@@
   @@@@@@@@@@          @@@@@@@@@@@@@@@#
   @&@@@&@@@&@@@          &@&@@@&@@@&@
  @@@@@@@@@@@@@.              @@@@@@@*
  @@@@@@@@@@@@@                  %@@@
 @@@@@@@@@@@@@
/@@@@@@@&@@@@@
@@@@@@@@@@@@@
@@@@@@@@@@@@@
@@@@@@@@@@@@        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

$ ./bin/easysearch

可以在另一个终端中运行 cURL 命令验证 Easysearch 是否成功启动：

$ 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。

输入用户名和密码即可进入。

这个界面为开发者提供了上帝视角：

集群全景监控：
- 健康状态：大大的绿色 “green” 让你对系统状态一目了然。
- 资源仪表盘：实时展示 CPU、内存、JVM 堆内存以及磁盘使用率。以前需要敲几行命令才能看到的指标，现在直接图形化呈现，性能瓶颈一眼便知。
- 拓扑视图：右下角的拓扑图直观展示了节点分布，多节点集群管理不再抽象。
开发者的神兵利器：
- 请特别留意左侧菜单中的 “开发工具” (Dev Tools)。对于开发者来说，这是最常用的功能。它提供了一个支持语法高亮和自动补全的 Web 编辑器，你可以在这里直接编写 DSL 进行查询调试，彻底告别在终端里手敲 cURL 命令的痛苦。
核心资源管理：
- 你可以直接在界面上管理索引、**分片 **和 安全管理，无需记忆复杂的运维 API。

创建索引 (Create Table) #

接下来的上手操作，我们将用到 UI 的开发工具，在其中编写 DSL。我们在左侧编写 DSL，使用 command (Windows 是 ctrl) + enter 键即可运行 DSL，结果将在右侧展示：

在关系型数据库中，你需要先定义表结构（Schema）。在 Easysearch 中，我们创建一个名为 my_first_index 的索引，并定义字段映射。将下面的代码块内容拷贝到开发工具中，无需指定集群地址/用户/密码，开发工具会帮我们处理掉这些细节：

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 一次性写入多行数据。

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表示写入成功：

查询数据 #

现在数据已经就绪，我们可以开始检索了。这里我们将展示 Easysearch 的两种查询方式：SQL 查询（推荐）和 原生 DSL。

使用 SQL 查询（像操作 MySQL 一样） #

POST /_sql?format=txt
{
  "query": "SELECT * FROM my_first_index WHERE MATCH_QUERY(content, '开箱即用') ORDER BY id DESC LIMIT 5"
}

我们使用了 MATCH_QUERY函数来进行全文搜索

使用 DSL 查询 #

为了证明中文分词真的在工作，我们尝试搜索“衍生版本”。如果是原生 ES（标准分词器），它会将“衍”、“生”拆开匹配，导致噪音；而 Easysearch 会精准匹配这个词组。

GET /my_first_index/_search
{
  "query": {
    "match": {
      "content": "衍生版本"
    }
  }
}

总结 #

至此，你已经掌握了 Easysearch 的基本用法。

回顾一下，Easysearch 并非要重新发明轮子，而是致力于让这个轮子在中文开发环境中滚动的更加顺滑。作为 Elasticsearch 7.10.2 的衍生版本，它完美继承了开源时代的遗产，同时补齐了原生 ES 在本地化和易用性上的短板：

对于运维：它是一行命令即可部署、内置安全与监控的稳定引擎，告别繁琐的插件配置和复杂的集群调优。
对于开发：它是一个听得懂 SQL、看得懂中文、API 完全兼容的强大后端，让你可以专注于业务逻辑而非底层细节。

无论你是由于开源协议变更正在寻找 ES 的替代方案，还是从零开始构建一个新的搜索业务，Easysearch 都是目前国内开发者的最优解之一。

下一步做什么？ #

你可以在官方文档中深入了解更多进阶功能，或者直接加入社区，与数千名开发者一起探索搜索技术的边界。
Happy Searching!

标签

Easysearch 入门介绍

Easysearch 开发者入门