实战指南 —— 安装配置 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（推荐）

npm install -g @github/copilot

使用 Homebrew（macOS）

brew install copilot-cli

使用 winget（Windows）

winget install GitHub.Copilot

安装完成后，进行身份认证：

copilot

在交互界面中输入 /login，然后按提示在浏览器中完成 GitHub 授权。登录成功后，输入 /quit 退出会话，回到普通 shell。

---

3. 安装 Elasticsearch 插件

Elastic 插件已发布在 Awesome GitHub Copilot 市场（GitHub 官方维护的插件集合）。该市场默认已在 Copilot CLI 中注册，因此安装只需一条命令：

copilot plugin install elasticsearch@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

1. 在 Kibana 中进入 Stack Management → Security → API Keys，或直接在顶部搜索“API Keys”。
2. 点击 Create API Key，输入一个名称（如 copilot-cli），保持默认权限，点击创建。
3. 复制生成的 编码后的 API Key（注意：只显示一次，请妥善保存）。

4.3 获取 MCP URL

1. 在 Kibana 中进入 Agents → View all tools → Manage MCP。
2. 复制显示的 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 条订单记录，涵盖商品类别、价格、地理位置等信息。

安装步骤：

1. 打开 Kibana，进入 Integrations 页面（可在顶部搜索“Integration”）。
2. 找到 Sample Data 并点击安装。
3. 等待数据加载完成。

你也可以参考官方文档：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'

插件内部执行过程（简要）：

1. 通过 MCP 获取 kibana_sample_data_ecommerce 的映射，确认 taxful_total_price 和 category.keyword 字段存在。
2. 生成 ES|QL：

   FROM kibana_sample_data_ecommerce
   | STATS total_revenue = SUM(taxful_total_price) BY category.keyword
   | SORT total_revenue DESC
   | LIMIT 5
   

3. 执行并返回表格：

   | 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）即可，无需重新安装插件。

---