实战指南 —— 安装配置 Elasticsearch GitHub Copilot CLI 插件1. 前置条件在开始之前请确保你具备以下环境Elasticsearch 集群可以是 Elastic Cloud 免费试用版也可以本地运行推荐使用start-local脚本。GitHub Copilot CLI已安装并认证。Node.js环境用于 npm 安装或 Homebrew / winget 等包管理器。2. 安装 GitHub Copilot CLICopilot CLI 可以通过多种方式安装选择你习惯的包管理器即可。使用 npm推荐npminstall-ggithub/copilot使用 HomebrewmacOSbrewinstallcopilot-cli使用 wingetWindowswingetinstallGitHub.Copilot安装完成后进行身份认证copilot在交互界面中输入/login然后按提示在浏览器中完成 GitHub 授权。登录成功后输入/quit退出会话回到普通 shell。3. 安装 Elasticsearch 插件Elastic 插件已发布在Awesome GitHub Copilot 市场GitHub 官方维护的插件集合。该市场默认已在 Copilot CLI 中注册因此安装只需一条命令copilot plugininstallelasticsearchawesome-copilot验证是否安装成功copilot plugin list你应该能看到类似elasticsearchawesome-copilot (active)的输出。4. 配置 Elasticsearch 连接插件通过三个环境变量来连接你的集群变量名说明ELASTICSEARCH_URL集群的访问地址如https://my-cluster.es.region.elastic.cloud:443ELASTICSEARCH_API_KEY用于认证的编码后的 API KeyELASTIC_MCP_URLMCP Server 的 URL要求 Elasticsearch 9.2 或 Serverless4.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你的集群URLELASTICSEARCH_API_KEY你的编码API KeyELASTIC_MCP_URL你的MCP Server URL为什么不直接 export 到 shell 配置文件因为当你需要切换多个集群或环境时.env文件更灵活可以针对不同项目单独配置避免全局污染。加载.env文件到当前 shellset-asource.envsetaset -a使所有后续变量自动导出source加载文件set a关闭自动导出5. 安装示例数据测试用为了快速体验查询功能建议安装 Elasticsearch 自带的电商订单样例数据集。它包含一个名为kibana_sample_data_ecommerce的索引共 4,675 条订单记录涵盖商品类别、价格、地理位置等信息。安装步骤打开 Kibana进入Integrations页面可在顶部搜索“Integration”。找到Sample Data并点击安装。等待数据加载完成。你也可以参考官方文档Explore and Analyze Data。6. 首次查询列出所有索引执行以下命令让 Copilot 通过插件列出集群中的索引copilot-pelasticsearch Can you list my available Elasticsearch indices?--allow-toolshell-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-pelasticsearch 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-toolshell插件内部执行过程简要通过 MCP 获取kibana_sample_data_ecommerce的映射确认taxful_total_price和category.keyword字段存在。生成 ES|QLFROM 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 | Mens Clothing | 149,393.91 | | 2 | Womens Clothing | 135,099.91 | | 3 | Womens Shoes | 105,479.17 | | 4 | Mens Shoes | 91,797.92 | | 5 | Womens 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即可无需重新安装插件。
