企业官网建设流程全解析

实战指南 —— 安装配置 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 连接

插件通过三个环境变量来连接你的集群：

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