From f4e9e6c425cdc58108275999abac98d86668e6fe Mon Sep 17 00:00:00 2001 From: "lang.shuocheng" Date: Fri, 27 Mar 2026 17:38:49 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=20Elasticsearch=208.?= =?UTF-8?q?x=20=E5=8F=AA=E8=AF=BB=E6=9F=A5=E8=AF=A2=E5=B7=A5=E5=85=B7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 功能特性: - 支持 Elasticsearch 8.x 的只读查询操作 - 实现 API 路径白名单验证机制，确保只执行只读操作 - 支持多索引搜索和批量文档获取 (_mget) - 支持 SSL/TLS 安全连接和证书验证 - 提供完善的错误处理和中文错误提示 - 包含文档搜索、聚合分析、集群信息查询等功能 技术实现: - 双重安全验证: 白名单路径 + GET 方法限制 - 支持 13 种只读 API 路径 (_search, _mget, _count, _cat/* 等) - 完整的异常处理机制 - 符合 MaxKB 工具规范 测试验证: - Python 语法检查通过 - 白名单验证逻辑测试通过 - 参数验证测试通过 - .tool 文件结构验证通过 --- ...asticsearch \346\237\245\350\257\242.tool" | Bin 0 -> 8608 bytes tools/tool_elasticsearch/README.md | 264 ++++++++++++++++++ tools/tool_elasticsearch/data.yaml | 5 + tools/tool_elasticsearch/logo.png | Bin 0 -> 136 bytes 4 files changed, 269 insertions(+) create mode 100644 "tools/tool_elasticsearch/1.0.0/Elasticsearch \346\237\245\350\257\242.tool" create mode 100644 tools/tool_elasticsearch/README.md create mode 100644 tools/tool_elasticsearch/data.yaml create mode 100644 tools/tool_elasticsearch/logo.png diff --git "a/tools/tool_elasticsearch/1.0.0/Elasticsearch \346\237\245\350\257\242.tool" "b/tools/tool_elasticsearch/1.0.0/Elasticsearch \346\237\245\350\257\242.tool" new file mode 100644 index 0000000000000000000000000000000000000000..6b8d238746e54cb846bc4db08908e04247357c2f GIT binary patch literal 8608 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 literal 0 HcmV?d00001 diff --git a/tools/tool_elasticsearch/README.md b/tools/tool_elasticsearch/README.md new file mode 100644 index 0000000..2936c5d --- /dev/null +++ b/tools/tool_elasticsearch/README.md @@ -0,0 +1,264 @@ +# Elasticsearch 数据库查询工具 + +一个强大的 Elasticsearch 8.x 只读查询工具，支持执行各种 ES 查询操作，为 MaxKB 智能体平台提供 Elasticsearch 查询能力。 + +## 功能特性 + +- ✅ 支持 Elasticsearch 8.x 版本 +- ✅ 支持文档搜索、聚合分析、集群信息查询 +- ✅ 集成到 MaxKB 智能体平台 +- ✅ 简单易用的配置和部署 +- ✅ 支持灵活的查询 DSL +- ✅ 支持多索引搜索和批量文档获取 +- ✅ 安全的白名单验证机制 +- ✅ 支持 HTTPS 连接和 SSL 证书验证 +- ✅ 友好的中文错误提示 + +## 系统要求 + +- Elasticsearch 8.x 集群 +- MaxKB 平台环境 +- Python 3.7+ + +## 安装依赖 + +在使用此工具之前，需要先安装所需的依赖包： + +```bash +pip install elasticsearch>=8.0.0,<9.0.0 +``` + +依赖包说明： +- `elasticsearch>=8.0.0,<9.0.0` - Elasticsearch Python 客户端（8.x 版本） + +## 参数说明 + +| 参数 | 类型 | 必填 | 默认值 | 说明 | +|------|------|------|--------|------| +| host | string | 是 | - | Elasticsearch 服务器地址 | +| port | string | 是 | 9200 | Elasticsearch 端口 | +| user | string | 是 | - | 认证用户名 | +| password | string | 是 | - | 认证密码 | +| use_ssl | boolean | 否 | true | 是否使用 HTTPS 连接 | +| verify_certs | boolean | 否 | true | 是否验证 SSL 证书 | +| api_path | string | 是 | - | ES API 路径（如: index_name/_search） | +| query_dsl | string | 否 | - | 查询 DSL JSON 字符串（可选） | +| timeout | number | 否 | 30 | 连接超时时间(秒) | + +## 支持的 API + +### 搜索类 API +- `_search` - 搜索文档 +- `_mget` - 批量获取多个文档 +- `_count` - 统计文档数量 +- `_validate/query` - 验证查询语法 + +### 信息类 API +- `_get` 或 `_doc/{id}` - 获取单个文档 +- `_cat/*` - 集群信息查询（indices, aliases, health, nodes 等） +- `_cluster/health` - 集群健康状态 +- `_cluster/state` - 集群状态 +- `_aliases` - 索引别名信息 +- `_mapping` - 索引映射信息 +- `_settings` - 索引设置 + +## 使用示例 + +### 基础搜索 + +```python +# 搜索所有文档 +result = query_elasticsearch( + host="localhost", + port="9200", + user="elastic", + password="changeme", + api_path="my_index/_search", + query_dsl='{"query": {"match_all": {}}}' +) + +# 条件搜索 +result = query_elasticsearch( + host="localhost", + port="9200", + user="elastic", + password="changeme", + api_path="my_index/_search", + query_dsl='{"query": {"match": {"title": "搜索关键词"}}}' +) +``` + +### 获取单个文档 + +```python +result = query_elasticsearch( + host="localhost", + port="9200", + user="elastic", + password="changeme", + api_path="my_index/_doc/123" +) +``` + +### 批量获取多个文档 + +```python +result = query_elasticsearch( + host="localhost", + port="9200", + user="elastic", + password="changeme", + api_path="_mget", + query_dsl='{"docs": [{"_index": "my_index", "_id": "1"}, {"_index": "my_index", "_id": "2"}]}' +) +``` + +### 多索引搜索 + +```python +result = query_elasticsearch( + host="localhost", + port="9200", + user="elastic", + password="changeme", + api_path="index1,index2/_search", + query_dsl='{"query": {"match_all": {}}}' +) +``` + +### 聚合查询 + +```python +result = query_elasticsearch( + host="localhost", + port="9200", + user="elastic", + password="changeme", + api_path="my_index/_search", + query_dsl='{"size": 0, "aggs": {"avg_price": {"avg": {"field": "price"}}}}' +) +``` + +### 集群信息查询 + +```python +# 集群健康状态 +result = query_elasticsearch( + host="localhost", + port="9200", + user="elastic", + password="changeme", + api_path="_cluster/health" +) + +# 索引列表 +result = query_elasticsearch( + host="localhost", + port="9200", + user="elastic", + password="changeme", + api_path="_cat/indices" +) + +# 索引映射 +result = query_elasticsearch( + host="localhost", + port="9200", + user="elastic", + password="changeme", + api_path="my_index/_mapping" +) +``` + +## 错误处理 + +工具会返回友好的中文错误提示： + +| 错误类型 | 提示信息 | +|----------|----------| +| 连接失败 | 无法连接到 Elasticsearch 服务器 {host}:{port}，请检查地址和端口 | +| 认证失败 | 认证失败，请检查用户名和密码 | +| SSL 错误 | SSL 证书验证失败，请检查证书或设置 verify_certs=False | +| 权限不足 | 权限不足，请检查用户是否有相应的查询权限 | +| 索引不存在 | 索引 {index_name} 不存在 | +| 查询语法错误 | 查询语法错误: {详细信息} | +| 超时 | 连接超时，请检查网络或增加 timeout 参数 | +| 不支持的 API | 不允许的 API 路径: {api_path}。此工具只支持只读查询操作 | +| 不支持的 HTTP 方法 | 不支持的 HTTP 方法: {method}。只允许 GET 和 HEAD 请求 | + +## 安全验证 + +工具实现了双重安全验证机制： + +1. **白名单路径验证**: 只允许预定义的只读 API 路径 +2. **HTTP 方法验证**: 只允许 GET 和 HEAD 请求 + +这确保了工具只能执行只读查询操作，防止误操作导致数据修改或删除。 + +## 注意事项 + +1. 生产环境建议使用专用只读账户 +2. 建议在 ES 集群配置中启用安全认证和 HTTPS +3. 不要在日志中记录敏感信息（如密码） +4. 检查防火墙是否允许 ES 端口访问 +5. 大数据量查询时建议在 query_dsl 中添加分页参数（from, size） +6. 避免使用高开销的查询（如通配符查询、正则查询）在大数据集上 +7. 建议设置合理的 timeout 参数，避免长时间等待 + +## 测试说明 + +### 本地测试 + +在提交工具前，建议进行以下测试： + +1. **参数验证测试** +```python +from elasticsearch_query import query_elasticsearch + +# 测试缺少必填参数 +result = query_elasticsearch(host="", port="9200", user="elastic", password="changeme", api_path="test/_search") +print(result) # 应返回参数错误 + +# 测试无效的 API 路径 +result = query_elasticsearch(host="localhost", port="9200", user="elastic", password="changeme", api_path="test/_delete") +print(result) # 应返回不允许的 API 路径错误 +``` + +2. **连接测试** +```python +# 测试基础搜索（需要实际 ES 环境） +result = query_elasticsearch( + host="localhost", + port="9200", + user="elastic", + password="changeme", + api_path="_cat/indices" +) +print(result) # 应返回索引列表或认证失败错误 +``` + +3. **查询 DSL 测试** +```python +# 测试无效的 JSON +result = query_elasticsearch( + host="localhost", + port="9200", + user="elastic", + password="changeme", + api_path="test_index/_search", + query_dsl="{invalid json}" +) +print(result) # 应返回 JSON 解析错误 +``` + +### 集成测试 + +在 MaxKB 平台中测试： + +1. 上传工具到平台 +2. 配置连接参数 +3. 测试各种 API 路径： + - `_cat/indices` - 获取索引列表 + - `index_name/_search` - 搜索文档 + - `_cluster/health` - 集群健康状态 +4. 验证错误处理是否返回友好的中文提示 diff --git a/tools/tool_elasticsearch/data.yaml b/tools/tool_elasticsearch/data.yaml new file mode 100644 index 0000000..d178fa2 --- /dev/null +++ b/tools/tool_elasticsearch/data.yaml @@ -0,0 +1,5 @@ +name: Elasticsearch 数据库查询 +tags: + - 数据库查询 +title: 实现 Elasticsearch 的只读查询操作 +description: 实现 Elasticsearch 8.x 的只读查询操作，支持文档搜索、聚合分析、集群信息查询等功能，提供安全的白名单验证机制。 diff --git a/tools/tool_elasticsearch/logo.png b/tools/tool_elasticsearch/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..49787017c24e820954d0ce86dd676411104f6642 GIT binary patch literal 136 zcmeAS@N?(olHy`uVBq!ia0vp^Mj*_=1SBWM%0B~A{+=$5Ar*7po-<@TpuljzU`D+; z#{ns}Z(o{}11DI1lY0L%kNsb!XjE(1!q5!DluUg-