【 Elasticsearch】安装配置 GitHub Copilot CLI 插件
实战指南 —— 安装配置 Elasticsearch GitHub Copilot CLI 插件
1. 前置条件
在开始之前，请确保你具备以下环境：
- Elasticsearch 集群：可以是 Elastic Cloud 免费试用版，也可以本地运行（推荐使用
start-local脚本）。 - GitHub Copilot CLI已安装并认证。
- Node.js环境（用于 npm 安装）或 Homebrew / winget 等包管理器。
2. 安装 GitHub Copilot CLI
Copilot CLI 可以通过多种方式安装，选择你习惯的包管理器即可。
使用 npm（推荐）
npminstall-g@github/copilot使用 Homebrew（macOS）
brewinstallcopilot-cli使用 winget（Windows）
wingetinstallGitHub.Copilot安装完成后，进行身份认证：
copilot在交互界面中输入/login，然后按提示在浏览器中完成 GitHub 授权。登录成功后，输入/quit退出会话，回到普通 shell。
3. 安装 Elasticsearch 插件
Elastic 插件已发布在Awesome GitHub Copilot 市场（GitHub 官方维护的插件集合）。该市场默认已在 Copilot CLI 中注册，因此安装只需一条命令：
copilot plugininstallelasticsearch@awesome-copilot验证是否安装成功：
copilot plugin list你应该能看到类似elasticsearch@awesome-copilot (active)的输出。
4. 配置 Elasticsearch 连接
插件通过三个环境变量来连接你的集群：
| 变量名 | 说明 |
|---|---|
ELASTICSEARCH_URL | 集群的访问地址，如https://my-cluster.es.region.elastic.cloud:443 |
ELASTICSEARCH_API_KEY | 用于认证的编码后的 API Key |
ELASTIC_MCP_URL | MCP Server 的 URL（要求 Elasticsearch 9.2+ 或 Serverless） |
4.1 获取集群 URL
- 在 Elastic Cloud 上，登录 Kibana，右上角主页通常显示集群 URL，以
.es.region.elastic.cloud:443结尾。 - 本地运行可设置为
https://localhost:9200。
4.2 生成 API Key
- 在 Kibana 中进入Stack Management → Security → API Keys，或直接在顶部搜索“API Keys”。
- 点击Create API Key，输入一个名称（如
copilot-cli），保持默认权限，点击创建。 - 复制生成的编码后的 API Key（注意：只显示一次，请妥善保存）。
4.3 获取 MCP URL
- 在 Kibana 中进入Agents → View all tools → Manage MCP。
- 复制显示的MCP Server URL（如果可用）。
4.4 创建.env文件（推荐做法）
在项目的根目录（或任意你执行命令的目录）创建.env文件，内容如下：
ELASTICSEARCH_URL="你的集群URL"ELASTICSEARCH_API_KEY="你的编码API Key"ELASTIC_MCP_URL="你的MCP Server URL"为什么不直接 export 到 shell 配置文件？
因为当你需要切换多个集群或环境时，.env文件更灵活，可以针对不同项目单独配置，避免全局污染。
加载.env文件到当前 shell：
set-a&&source.env&&set+a（set -a使所有后续变量自动导出，source加载文件，set +a关闭自动导出）
5. 安装示例数据（测试用）
为了快速体验查询功能，建议安装 Elasticsearch 自带的电商订单样例数据集。它包含一个名为kibana_sample_data_ecommerce的索引，共 4,675 条订单记录，涵盖商品类别、价格、地理位置等信息。
安装步骤：
- 打开 Kibana，进入Integrations页面（可在顶部搜索“Integration”）。
- 找到Sample Data并点击安装。
- 等待数据加载完成。
你也可以参考官方文档：Explore and Analyze Data。
6. 首次查询：列出所有索引
执行以下命令，让 Copilot 通过插件列出集群中的索引：
copilot-p"@elasticsearch Can you list my available Elasticsearch indices?"--allow-tool'shell'-p表示提示（prompt）。@elasticsearch指定使用 Elastic 代理。--allow-tool 'shell'授权 Copilot 执行必要的后台命令。
预期输出类似：
Here are your available Elasticsearch indices: | Index Name | Health | Status | |-----------------------------|--------|--------| | kibana_sample_data_ecommerce| green | open | | system-logs-2026 | green | open |7. 进阶查询：用自然语言分析销售数据
现在，尝试一个更复杂的业务问题：“找出销售额最高的前 5 个商品类别”。命令如下：
copilot-p"@elasticsearch Use ES|QL to find the top 5 product categories by total sales revenue in the kibana_sample_data_ecommerce index. Show me the results in a table."--allow-tool'shell'插件内部执行过程（简要）：
- 通过 MCP 获取
kibana_sample_data_ecommerce的映射，确认taxful_total_price和category.keyword字段存在。 - 生成 ES|QL：
FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5 - 执行并返回表格：
| Rank | Category | Total Revenue | |------|---------------------|---------------| | 1 | Men's Clothing | 149,393.91 | | 2 | Women's Clothing | 135,099.91 | | 3 | Women's Shoes | 105,479.17 | | 4 | Men's Shoes | 91,797.92 | | 5 | Women's Accessories | 60,830.31 |
整个过程无需你手动编写任何 ES|QL 语法，AI 全权代理。
8. 常见问题与注意事项
- 认证失败：检查
.env中的 URL 和 API Key 是否正确，确保集群可访问。 - MCP 未启用：如果使用的是 Elasticsearch 8.x 版本，需要升级到 9.2+ 或改用 Serverless 才能使用 MCP。否则插件可能降级使用普通 API 查询（但功能受限）。
- 权限不足：API Key 应具备读取索引映射和执行
_query的权限。 - 切换集群：只需修改
.env文件并重新加载（source .env）即可，无需重新安装插件。