FAQ

常见问题 #

Easysearch 使用过程中的高频问题与快速解答。

产品与兼容性 #

Easysearch 和 Elasticsearch 是什么关系？ #

Easysearch 兼容 ES 7.10 API 与生态工具，原有基于 ES 7.x 构建的应用和工作流可以平滑迁移。在此基础上，Easysearch 持续迭代，新增了向量检索、内置安全、国产化适配等企业级增强功能，并采用商用友好协议。

Easysearch 兼容哪些 ES 客户端和工具？ #

  • 客户端：ES 7.10.2 OSS 版本的 Java/Python/Go 等客户端均可直接使用
  • 工具：Logstash 7.10.2 OSS、Filebeat 7.10.2 OSS、Kibana 7.10.2 OSS 可直接连接
  • ORM 框架：Easy-ES、Spring Data Elasticsearch（2.x 系列）均兼容

需要在 easysearch.yml 中开启兼容模式：

elasticsearch.api_compatibility: true

Easysearch 是否开源？ #

Easysearch 不是开源软件，是一款商业软件，采用商用友好协议。

商用友好协议的核心优势：

  • 无限度的内部使用自由：企业可在任何规模的生产环境中自由部署和使用
  • 完整的二次开发权：允许深度定制和功能扩展，衍生成果完全归企业所有
  • 无限制的商业化权利：可基于 Easysearch 构建 SaaS 服务、托管服务或商业产品，无需公开源代码
  • 无传染性风险：不会因为提供服务而被迫公开技术栈

安装与部署 #

最低系统要求是什么？ #

项目最低推荐（生产）
CPU2 核16 核+
内存4 GB64 GB+
JDK1117+
磁盘20 GBSSD，按数据量规划

详见 测试环境部署 和 生产环境部署。

安装后忘记了 admin 密码怎么办？ #

初始密码仅在执行 bin/initialize.sh 时的终端输出中显示一次，不会保存到文件。如果丢失，可通过内置证书重置：

# 使用 security 工具重置密码
bin/security-admin.sh -cd config/security -cacert config/root-ca.pem \
  -cert config/admin.pem -key config/admin-key.pem -nhnv

参考博客： Easysearch 集群重置 admin 用户密码

Docker 部署时提示 max virtual memory areas vm.max_map_count [65530] is too low 怎么办？ #

# 宿主机执行
sudo sysctl -w vm.max_map_count=262144
# 持久化
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

支持哪些操作系统？ #

  • Linux：CentOS 7+、Ubuntu 18.04+、Debian 10+ 及各信创平台（麒麟、统信、龙芯、鲲鹏等）
  • Windows：支持，但不建议用于生产
  • macOS：支持，适合开发测试
  • 容器化：Docker、Docker Compose、Kubernetes (Helm/Operator)

信创平台参考 信创安装指南。

连接与客户端 #

连接时报 SSL/TLS 证书错误？ #

Easysearch 默认使用自签名证书。客户端连接时需要：

  • curl：使用 -k 跳过验证，或 --cacert root-ca.pem 指定 CA
  • Java：配置 SSLContext 信任自签名证书
  • Python：设置 verify_certs=False 或指定 CA 路径
# curl 示例
curl -ku admin:password https://localhost:9200

如何使用 Logstash / Filebeat 连接？ #

使用 7.10.2 OSS 版本的 Logstash / Filebeat，output 配置示例：

# Logstash
output {
  elasticsearch {
    hosts => ["https://localhost:9200"]
    user => "admin"
    password => "your-password"
    ssl => true
    ssl_certificate_verification => false
    ilm_enabled => false
  }
}

# Filebeat
output.elasticsearch:
  hosts: ["https://localhost:9200"]
  username: "admin"
  password: "your-password"
  ssl.verification_mode: none

索引与查询 #

集群状态显示 yellow 是什么意思？ #

yellow 表示所有主分片正常，但有副本分片未分配。常见于：

  • 单节点集群：副本无法分配到其他节点（正常现象）
  • 节点故障：某个节点下线导致副本丢失

单节点可以将副本数设为 0：

PUT /my-index/_settings
{
  "number_of_replicas": 0
}

中文搜索效果不好怎么办？ #

默认的 standard 分析器按字符切分中文，效果差。需要使用 IK 分词器：

PUT /my-index
{
  "mappings": {
    "properties": {
      "content": {
        "type": "text",
        "analyzer": "ik_max_word",
        "search_analyzer": "ik_smart"
      }
    }
  }
}

详见 文本分析 和 NLP。

写入速度慢怎么优化？ #

  1. 使用 _bulk API 批量写入（每批 5~15 MB）
  2. 增大 refresh_interval（如 30s）减少段创建频率
  3. 写入期间临时设置 number_of_replicas: 0
  4. 调整 index.translog.durability: async 和 index.translog.flush_threshold_size: 512mb

详见 Bulk API。

深度分页（from + size 超过 10000）报错？ #

默认 index.max_result_window 为 10000。深度分页建议使用 search_after：

GET /my-index/_search
{
  "size": 10,
  "sort": [{ "timestamp": "desc" }, { "_id": "asc" }],
  "search_after": ["2024-01-01T00:00:00Z", "doc_12345"]
}

详见 分页与排序。

运维与监控 #

如何备份和恢复数据？ #

使用快照 API：

# 注册仓库
PUT _snapshot/my_backup
{ "type": "fs", "settings": { "location": "/mnt/backup" } }

# 创建快照
PUT _snapshot/my_backup/snap_1

# 恢复
POST _snapshot/my_backup/snap_1/_restore

详见 备份与恢复。

磁盘满了怎么办？ #

  1. 删除不需要的旧索引：DELETE /old-index-*
  2. 清理已关闭的索引
  3. 如果集群进入只读模式，手动解除：
PUT _all/_settings
{
  "index.blocks.read_only_allow_delete": null
}
  1. 长期方案：配置 ILM 自动清理过期数据

详见 数据生命周期 和 故障排查。

更多资源 #

©INFINI.LTD, All Rights Reserved.