ES操作

技能文档

---
name: es
description: Elasticsearch 操作工具。支持集群健康查看、索引管理、文档查询、DSL 查询、Mapping 查看、别名管理等。触发词：ES、Elasticsearch、查索引、查文档、DSL查询、ES集群、索引管理
title: ES操作
category: 开发
---

# ES 操作

通过 `es_cli.py` 脚本直接调用 Elasticsearch REST API，支持集群健康查看、索引管理、文档查询、Mapping 查看、别名管理等。

## 快速使用

**脚本路径**：`<SKILL目录>/scripts/es_cli.py`

```bash
# 查看集群健康
python3 <SKILL目录>/scripts/es_cli.py GET /_cluster/health

# 列出所有索引
python3 <SKILL目录>/scripts/es_cli.py --list

# 查看索引 Mapping
python3 <SKILL目录>/scripts/es_cli.py --mapping my_index

# 查询文档 (DSL)
python3 <SKILL目录>/scripts/es_cli.py POST /my_index/_search '{"query":{"match_all":{}}}'

# 查看指定文档
python3 <SKILL目录>/scripts/es_cli.py GET /my_index/_doc/1

# 索引/更新文档
python3 <SKILL目录>/scripts/es_cli.py PUT /my_index/_doc/1 '{"name":"test"}'

# 删除文档
python3 <SKILL目录>/scripts/es_cli.py DELETE /my_index/_doc/1

# JSON 格式输出
python3 <SKILL目录>/scripts/es_cli.py -j GET /_cluster/health
```

> **注意**：`<SKILL目录>` 会被自动替换为当前技能的实际路径

> 详细参数说明见下方 [参数说明](#es_cli-参数说明)

## 核心操作

### 集群信息

```bash
# 查看集群健康状态
python3 <SKILL目录>/scripts/es_cli.py GET /_cluster/health

# 快捷方式
python3 <SKILL目录>/scripts/es_cli.py --health

# 查看节点信息
python3 <SKILL目录>/scripts/es_cli.py --nodes

# 查看集群统计
python3 <SKILL目录>/scripts/es_cli.py GET /_cluster/stats
```

### 索引管理

```bash
# 列出所有索引
python3 <SKILL目录>/scripts/es_cli.py --list

# 查看索引 Mapping
python3 <SKILL目录>/scripts/es_cli.py --mapping my_index

# 查看索引 Settings
python3 <SKILL目录>/scripts/es_cli.py GET /my_index/_settings

# 创建索引
python3 <SKILL目录>/scripts/es_cli.py PUT /my_index '{"settings":{"number_of_shards":1}}'

# 删除索引
python3 <SKILL目录>/scripts/es_cli.py DELETE /my_index
```

### 文档操作

```bash
# 查询文档 (DSL)
python3 <SKILL目录>/scripts/es_cli.py POST /my_index/_search '{"query":{"match_all":{}}}'

# 根据 ID 获取文档
python3 <SKILL目录>/scripts/es_cli.py GET /my_index/_doc/1

# 索引/更新文档
python3 <SKILL目录>/scripts/es_cli.py PUT /my_index/_doc/1 '{"name":"test","age":18}'

# 删除文档
python3 <SKILL目录>/scripts/es_cli.py DELETE /my_index/_doc/1
```

### 别名管理

```bash
# 查看所有别名
python3 <SKILL目录>/scripts/es_cli.py --aliases

# 查看指定索引的别名
python3 <SKILL目录>/scripts/es_cli.py GET /my_index/_alias
```

## 首次使用配置

首次执行命令时，如果检测到配置不存在，会自动启动交互式配置向导。

也可以手动运行配置命令：

```bash
python3 <SKILL目录>/scripts/es_cli.py --init
```

配置文件位置：`~/.config/es/config.json`（可通过 `AGENT_ES_CONFIG` 环境变量覆盖）

### 配置示例

```json
{
  "current": "local",
  "local": {
    "host": "localhost",
    "port": 9200,
    "scheme": "http",
    "username": "",
    "password": ""
  }
}
```

### 多环境配置

支持同时配置多个环境，通过 `--env` 切换：

```json
{
  "current": "local",
  "local": {
    "host": "localhost",
    "port": 9200,
    "scheme": "http",
    "username": "",
    "password": ""
  },
  "prod": {
    "host": "es.prod.example.com",
    "port": 9200,
    "scheme": "https",
    "username": "elastic",
    "password": "secret"
  }
}
```

切换环境：

```bash
python3 <SKILL目录>/scripts/es_cli.py --env prod GET /_cluster/health
```

## 自动错误处理

脚本会自动处理以下问题，无需手动操作：

| 问题 | 自动处理 |
|------|----------|
| `requests` 未安装 | 自动安装依赖 |
| 配置文件不存在 | 自动启动配置向导 |
| ES 连接失败 | 显示详细错误信息 |
| HTTP 4xx/5xx 错误 | 显示状态码和错误详情 |

**常见错误**：
- `ConnectionError` - 连接失败，检查 ES 服务是否启动
- `Authentication failed` - 认证失败，检查用户名密码
- `index_not_found_exception` - 索引不存在
- `parse_exception` - DSL 查询语法错误

## es_cli.py 参数说明

| 参数 | 说明 | 示例 |
|------|------|------|
| `method` | HTTP 方法: GET, POST, PUT, DELETE, HEAD | `GET /_cluster/health` |
| `path` | 请求路径 | `/_cat/indices` |
| `body` | 请求体 (JSON 字符串) | `'{"query":{"match_all":{}}}'` |
| `--init` | 初始化配置 | `--init` |
| `--env, -e` | ES 环境 | `--env prod` |
| `--config, -c` | 配置文件路径 | `--config /path/to/config.json` |
| `--json, -j` | JSON 格式输出 | `-j` |
| `--health` | 查看集群健康 | `--health` |
| `--list` | 列出所有索引 | `--list` |
| `--nodes` | 查看节点信息 | `--nodes` |
| `--mapping` | 查看指定索引 mapping | `--mapping my_index` |
| `--aliases` | 查看别名 | `--aliases` |
| `--cat` | 执行 _cat API | `--cat indices` |

**使用示例**：

```bash
# 查看集群健康
python3 <SKILL目录>/scripts/es_cli.py GET /_cluster/health

# 列出索引
python3 <SKILL目录>/scripts/es_cli.py --list

# 查询文档
python3 <SKILL目录>/scripts/es_cli.py POST /my_index/_search '{"query":{"match_all":{}}}'
```

## 执行规则（AI 必读）

### 强制预检查

**在执行 ES 操作前，必须遵循：**

1. **不确定索引名** → 先用 `--list` 或 `GET /_cat/indices` 查看
2. **不确定字段名** → 先用 `--mapping <index>` 查看 Mapping
3. **查询报错** → 根据错误信息调整，不要盲目重试

### 查询流程建议

| 需求 | 推荐命令 |
|------|---------|
| 查看有哪些索引 | `--list` |
| 查看索引结构 | `--mapping <index>` |
| 查询文档 | `POST /<index>/_search '{"query":{...}}'` |
| 查看集群状态 | `--health` |

### 常见错误处理

| 错误信息 | 原因 | 解决方法 |
|---------|------|----------|
| `index_not_found_exception` | 索引不存在 | `--list` 查看正确索引名 |
| `parse_exception` | DSL 语法错误 | 检查 JSON 格式和查询语法 |
| `Authentication failed` | 认证失败 | 检查用户名密码 |
| `Connection refused` | ES 未启动 | 检查 ES 服务状态 |

### 执行前自检清单

- [ ] 索引名是否正确？（不确定的话 `--list`）
- [ ] 字段名是否正确？（不确定的话 `--mapping <index>`）
- [ ] DSL 查询语法是否正确？（JSON 格式是否合法）
- [ ] 删除操作是否确认？

**记住**：花 5 秒钟预检查，胜过花 5 分钟调试错误！

使用说明

# ES 操作技能

通过自然语言直接操作 Elasticsearch，推荐用 `/es` 显式调用。

## 使用方法

```
/es 连接本地 ES
/es 查看集群健康
/es 列出所有索引
/es 查 my_index 的 mapping
/es 搜索 my_index 中 name 包含 test 的文档
/es 切换到生产环境
```

## 能做什么

| 场景 | 示例 |
|------|------|
| 连接配置 | `/es 连接本地`、`/es 切换到生产环境` |
| 集群信息 | `/es 查看集群健康`、`/es 查看节点信息` |
| 索引管理 | `/es 列出所有索引`、`/es 查看 my_index 的 mapping` |
| 文档查询 | `/es 查 my_index 的文档`、`/es 搜索 my_index` |
| 别名管理 | `/es 查看所有别名` |

## 首次使用

首次执行时会自动引导配置 ES 连接信息，配置文件保存在 `~/.config/es/config.json`，支持多环境切换。

```json
{
  "current": "local",
  "local": {
    "host": "localhost",
    "port": 9200,
    "scheme": "http",
    "username": "",
    "password": ""
  }
}
```

支持 HTTP/HTTPS 协议以及基础认证。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。