Elasticsearch/OpenSearch连接器

概述

Elasticsearch/OpenSearch连接器提供从Elasticsearch或OpenSearch集群获取数据并注册到 Fess 索引的功能。

此功能需要 fess-ds-elasticsearch 插件。

支持版本

• Elasticsearch 7.x / 8.x

• OpenSearch 1.x / 2.x

前提条件

1. 需要安装插件

2. 需要对Elasticsearch/OpenSearch集群的读取访问权限

3. 需要执行查询的权限

插件安装

方法1: 直接放置JAR文件

# 从Maven Central下载
wget https://repo1.maven.org/maven2/org/codelibs/fess/fess-ds-elasticsearch/X.X.X/fess-ds-elasticsearch-X.X.X.jar

# 放置
cp fess-ds-elasticsearch-X.X.X.jar $FESS_HOME/app/WEB-INF/lib/
# 或者
cp fess-ds-elasticsearch-X.X.X.jar /usr/share/fess/app/WEB-INF/lib/

方法2: 从管理界面安装

1. 打开「系统」→「插件」

2. 上传JAR文件

3. 重启 Fess

配置方法

从管理界面的「爬虫」→「数据存储」→「新建」进行配置。

基本设置

项目	设置示例
名称	External Elasticsearch
处理器名称	ElasticsearchDataStore
启用	开

参数设置

基本连接:

settings.fesen.http.url=http://localhost:9200
index=myindex
size=100
scroll=5m

带认证的连接:

settings.fesen.http.url=https://elasticsearch.example.com:9200
index=myindex
settings.fesen.username=elastic
settings.fesen.password=changeme
size=100
scroll=5m

多主机设置:

settings.fesen.http.url=http://es-node1:9200,http://es-node2:9200,http://es-node3:9200
index=myindex
size=100
scroll=5m

参数列表

脚本设置

基本映射:

url=source.url
title=source.title
content=source.content
last_modified=source.timestamp

访问嵌套字段:

url=source.metadata.url
title=source.title
content=source.body.content
author=source.author.name
created=source.created_at
last_modified=source.updated_at

可用字段

• source.<field_name> - Elasticsearch文档的 _source 字段

• id - 文档ID

• index - 索引名

• score - 搜索得分

• version - 文档版本

• seqNo - 序列号

• primaryTerm - 主要期限

• clusterAlias - 集群别名（用于跨集群搜索）

• hit - SearchHit对象（高级用法）

查询设置

获取所有文档

默认获取所有文档。 如果不指定 query 参数，将使用 match_all。

特定条件过滤

query={"term":{"status":"published"}}

范围指定:

query={"range":{"timestamp":{"gte":"2024-01-01","lte":"2024-12-31"}}}

多条件:

query={"bool":{"must":[{"term":{"category":"news"}},{"range":{"views":{"gte":100}}}]}}

Note

query 参数仅接受查询主体。不需要外部 {"query":...} 包装。 排序等搜索级别的选项不能在此参数中指定。

只获取特定字段

使用fields参数限制获取字段

settings.fesen.http.url=http://localhost:9200
index=myindex
fields=title,content,url,timestamp
size=100

要获取所有字段，请不指定 fields 或留空。

使用示例

基本索引爬取

参数:

settings.fesen.http.url=http://localhost:9200
index=articles
size=100
scroll=5m

脚本:

url=source.url
title=source.title
content=source.content
created=source.created_at
last_modified=source.updated_at

从带认证的集群爬取

参数:

settings.fesen.http.url=https://es.example.com:9200
index=products
settings.fesen.username=elastic
settings.fesen.password=changeme
size=200
scroll=10m

脚本:

url="https://shop.example.com/product/" + source.product_id
title=source.name
content=source.description + " " + source.specifications
digest=source.category
last_modified=source.updated_at

从多个索引爬取

参数:

settings.fesen.http.url=http://localhost:9200
index=logs-2024-*
query={"term":{"level":"error"}}
size=100

脚本:

url="https://logs.example.com/view/" + id
title=source.message
content=source.stack_trace
digest=source.service + " - " + source.level
last_modified=source.timestamp

OpenSearch集群爬取

参数:

settings.fesen.http.url=https://opensearch.example.com:9200
index=documents
settings.fesen.username=admin
settings.fesen.password=admin
size=100
scroll=5m

脚本:

url=source.url
title=source.title
content=source.body
last_modified=source.modified_date

限制字段爬取

参数:

settings.fesen.http.url=http://localhost:9200
index=myindex
fields=id,title,content,url,timestamp
size=100

脚本:

url=source.url
title=source.title
content=source.content
last_modified=source.timestamp

多主机负载均衡

参数:

settings.fesen.http.url=http://es1.example.com:9200,http://es2.example.com:9200,http://es3.example.com:9200
index=articles
size=100
scroll=5m

脚本:

url=source.url
title=source.title
content=source.content
last_modified=source.timestamp

故障排除

连接错误

症状: Connection refused 或 No route to host

确认事项:

1. 确认主机URL是否正确（协议、主机名、端口）

2. 确认Elasticsearch/OpenSearch是否已启动

3. 确认防火墙设置

4. 如果是HTTPS，确认证书是否有效

认证错误

症状: 401 Unauthorized 或 403 Forbidden

确认事项:

1. 确认用户名和密码是否正确

2. 确认用户是否有适当的权限:

   • 索引的读取权限

   • Scroll API的使用权限

3. 如果启用了Elasticsearch Security（X-Pack），确认是否正确配置

找不到索引

症状: index_not_found_exception

确认事项:

1. 确认索引名是否正确（包括大小写）

2. 确认索引是否存在:

   GET /_cat/indices
   

3. 确认通配符模式是否正确（例: logs-*）

查询错误

症状: parsing_exception 或 search_phase_execution_exception

确认事项:

1. 确认查询JSON是否正确

2. 确认查询是否与Elasticsearch/OpenSearch版本兼容

3. 确认字段名是否正确

4. 直接在Elasticsearch/OpenSearch上测试查询:

   POST /myindex/_search
   {
     "query": {...}
   }
   

滚动超时

症状: No search context found 或 Scroll timeout

解决方法:

1. 增加 scroll:

   scroll=10m
   

2. 减小 size:

   size=50
   

3. 确认集群资源

大量数据爬取

症状: 爬取速度慢或超时

解决方法:

1. 调整 ``size``（太大会变慢）:

   size=100  # 默认
   size=500  # 较大
   

2. 使用 fields 限制获取字段

3. 使用 query 只过滤必要的文档

4. 分割成多个数据存储（按索引、时间范围等）

内存不足

症状: OutOfMemoryError

解决方法:

1. 减小 size

2. 使用 fields 限制获取字段

3. 增加 Fess 的堆大小

4. 排除大字段（二进制数据等）

SSL/TLS连接

自签名证书的情况

Warning

在生产环境中请使用正确签名的证书。

使用自签名证书时，将证书添加到Java keystore:

keytool -import -alias es-cert -file es-cert.crt -keystore $JAVA_HOME/lib/security/cacerts

客户端证书认证

如果需要客户端证书，需要额外的参数设置。 详情请参考Elasticsearch客户端文档。

高级查询示例

包含聚合的查询

Note

query 参数仅接受查询主体。聚合（aggs）、排序等搜索级别的 选项不能指定。只获取文档。

脚本字段

Note

Elasticsearch/OpenSearch的脚本字段不包含在 _source 中，因此无法 通过 source.* 前缀访问。要使用脚本字段，请通过 hit 对象的 hit.getFields() 方法访问。

参考信息

• 数据存储连接器概述 - 数据存储连接器概述

• 数据库连接器 - 数据库连接器

• 数据存储爬取 - 数据存储配置指南

• Elasticsearch Documentation

• OpenSearch Documentation

• Elasticsearch Query DSL