企业官网建设流程全解析

Higress MCP 公共实验环境搭建指南：基于 Kind 与 Helm 的一键式可复现环境

【免费下载链接】higress🤖 AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress

本文围绕 Higress 仓库中 samples/mcp/environment 目录展开，系统讲解其"与 MCP 协议版本无关的公共实验环境"的设计思路、完整启动/检查/清理流程、可观察后端边界以及全部可覆盖参数。读者按本文操作即可在本地拉起一套包含 Higress Controller、Gateway、CRD、Console 和模拟业务后端的完整实验环境，并在此基础上运行samples/mcp/protocol下的任意 MCP Demo。

一、公共实验环境在 MCP Demo 体系中的定位

Higress 的 MCP Demo 体系遵循"公共依赖复用、版本边界明确"的设计原则（参见 samples/mcp/README.md）：

• environment/存放与 MCP 协议版本无关的公共环境：Kind 集群定义、Higress Helm 配置、通用模拟业务后端和环境控制脚本；
• protocol/<version>/存放协议版本专属的内容：插件构建方式、能力验证手册和对应 Demo 资源。

这意味着无论你要验证哪个 MCP 协议版本的能力（例如 2026-07-28 协议版本 下的无状态 HTTP、REST-to-MCP、modern-to-legacy、请求前置校验等 Demo），底层实验环境只需拉起一次、全局复用。

该环境的技术组成如下：

环境目录结构（对应 samples/mcp/environment）：

samples/mcp/environment/ ├── apps/observable-weather/ # 通用模拟业务后端（Dockerfile + deployment.yaml + server.py） ├── higress/values.yaml # Higress Helm values（本地化、轻量化配置） ├── kind/cluster.yaml.tpl # Kind 集群模板（挂载插件目录） └── scripts/ # up.sh / status.sh / down.sh / common.sh

二、前置条件

在启动环境前，请确认本机满足以下条件（见 environment/README.md）：

• Docker 或 Podman：用于构建后端镜像并承载 Kind 节点（脚本会自动探测可用的容器引擎）；
• Kind：创建本地 Kubernetes 集群；
• kubectl：操作集群资源；
• Helm：安装 Higress；
• curl：健康检查与 Demo 请求；
• jq：执行各 Demo 的响应断言；
• 至少约 4 GiB 可用内存：单节点 Kind 集群 + Higress 全套组件需要一定资源；
• 网络可达：能够访问 Higress Helm 仓库和所需镜像仓库。

脚本层面对工具存在性的校验非常严格：up.sh启动时会依次调用require_command检查kind、kubectl、helm、curl、sed五个命令，缺失任何一个都会以退出码 2 直接报错（见 scripts/up.sh 与 scripts/common.sh）。

三、环境整体架构与关键设计

3.1 组件关系

从 scripts/up.sh 的执行顺序可以还原出完整架构：

1. Kind 集群承载全部工作负载，kind/cluster.yaml.tpl定义了集群模板；
2. Higress 全家桶以 Helm 方式安装在higress-system命名空间；
3. 公共后端observable-weather运行在mcp-demo命名空间；
4. 三者通过三个kubectl port-forward暴露到宿主机固定端口。

3.2 插件目录挂载（关键设计）

公共环境会将宿主机的.runtime/plugins目录挂载到 Kind 节点的/opt/plugins。对应的 Kind 集群模板（kind/cluster.yaml.tpl）如下：

kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane extraMounts: - hostPath: __PLUGIN_HOST_PATH__ containerPath: /opt/plugins selinuxRelabel: true

__PLUGIN_HOST_PATH__是占位符，up.sh在创建集群前会用sed将其替换为真实的宿主机路径（$MCP_DEMO_RUNTIME/plugins）。这意味着：

• 先构建、后启动：启动环境前必须先在对应协议版本目录下执行plugin/build.sh构建协议插件，产物落在.runtime/plugins，供 Gateway 通过 WasmPlugin CRD 加载；
• 跨启动复用：.runtime/plugins不会提交到 Git，且清理环境时会被保留，下次启动可直接复用已构建的插件产物。

3.3 Higress 的本地化轻量配置

Helm values 定义在 higress/values.yaml，核心配置如下：

global: local: true # 本地化模式 volumeWasmPlugins: true # 以 volume 方式加载 Wasm 插件（对应 /opt/plugins 挂载） onlyPushRouteCluster: false enableStatus: false higress-core: gateway: replicas: 1 service: type: ClusterIP # 不暴露外部 LoadBalancer，依靠 port-forward 访问 resources: requests: {cpu: 100m, memory: 256Mi} limits: {cpu: "1", memory: 1Gi} controller: replicas: 1 resources: requests: {cpu: 100m, memory: 256Mi} limits: {cpu: "1", memory: 1Gi} higress-console: service: type: ClusterIP

几个要点：

• volumeWasmPlugins: true与 Kind 节点的/opt/plugins挂载配合，使 MCP 协议插件能够以本地 volume 方式被 Gateway 加载；
• Gateway 与 Console 的 Service 均为ClusterIP，不依赖云环境的外部负载均衡器，访问完全通过port-forward完成，适合纯本地实验；
• 对 CPU 与内存做了显式 request/limit 限制，配合--wait --timeout 10m的 Helm 安装参数，保证资源有限的本机也能稳定拉起。

四、完整启动流程

4.1 启动命令

从 Higress 仓库根目录执行（对应 environment/README.md 的"启动"小节）：

cd samples/mcp ./protocol/2026-07-28/plugin/build.sh ./environment/scripts/up.sh

两步的含义：

1. plugin/build.sh：按对应协议版本目录记录的 Higress 源码 commit 构建 MCP Server 插件，产物写入.runtime/plugins；
2. environment/scripts/up.sh：拉起公共实验环境。

4.2 up.sh 执行步骤详解

对照 scripts/up.sh 的源码，启动脚本实际完成以下工作：

步骤 1：环境准备

• 校验kind、kubectl、helm、curl、sed是否安装；
• 通过select_container_engine探测容器引擎：优先 Docker，其次 Podman；若.runtime/container-engine已有记录则使用记录值（Podman 会自动设置KIND_EXPERIMENTAL_PROVIDER=podman）；
• 创建.runtime/plugins与.runtime目录。

步骤 2：创建 Kind 集群

• 集群名默认为higress-mcp-demo（见 scripts/common.sh 的默认值定义）；
• 将kind/cluster.yaml.tpl渲染为.runtime/kind-cluster.yaml后执行kind create cluster，节点镜像默认kindest/node:v1.32.2；
• 创建成功后立即写入集群所有权标记（详见下文"所有权保护机制"），写入失败会自动删除集群并退出。

步骤 3：Helm 安装 Higress

• 添加并更新higress.ioHelm 仓库；
• 执行helm upgrade --install higress higress.io/higress，固定--version 2.2.3，使用--values environment/higress/values.yaml，指定--namespace higress-system --create-namespace，并带--wait --timeout 10m等待就绪。

步骤 4：构建并部署公共后端

• 用选定的容器引擎构建localhost/mcp-demo/observable-weather:1.0.0镜像；
• 若使用 Podman，需先podman save成 docker-archive 再kind load image-archive；使用 Docker 则直接kind load docker-image；
• kubectl apply应用 apps/observable-weather/deployment.yaml（包含 Namespace、Deployment、Service）；
• 依次等待observable-weather、higress-gateway、higress-controller三个 Deployment 完成 rollout。

步骤 5：建立端口转发并健康检查

• 三个start_port_forward分别建立：
  • Gateway：higress-system/service/higress-gateway的80→ 宿主机18080；
  • Console：higress-system/service/higress-console的8080→ 宿主机18081；
  • 后端：mcp-demo/service/observable-weather的8080→ 宿主机18082；
• 通过wait_http依次探测后端/healthz、Console/与 Gateway/，全部可达后才打印就绪信息。

4.3 环境地址

启动完成后，本机将暴露以下地址（来自 environment/README.md）：

端口可通过环境变量覆盖，详见第六节。

五、状态检查与清理

5.1 检查状态

./environment/scripts/status.sh

对应 scripts/status.sh，该命令会：

1. 校验集群存在且归本 Demo 所有（否则拒绝执行并报错）；
2. 切换到kind-<cluster>上下文；
3. 输出higress-system与mcp-demo两个命名空间下的 Pod 列表；
4. 分别探测后端/healthz、Gateway/、Console/，逐项输出三个端口转发是否ready/unavailable。

5.2 清理环境

./environment/scripts/down.sh

对应 scripts/down.sh，该命令会：

1. 再次执行所有权校验，拒绝删除非本 Demo 创建的集群；
2. 依次停止三个port-forward（按 PID 文件与命令签名匹配，避免误杀其他进程，见 scripts/common.sh）；
3. 删除 Kind 集群并清理.runtime中的所有权记录；
4. 保留.runtime/plugins下的插件产物，便于下次启动复用。

六、公共后端 observable-weather 详解

6.1 设计边界：协议无关

公共后端observable-weather只实现普通 HTTP，不理解 MCP 版本、JSON-RPC 方法或 Session（见 environment/README.md 的"公共后端边界"小节）。特定 MCP 版本的后端 fixture 由对应 Demo 提供，例如 03-modern-to-legacy 的 legacy_server.py。

这保证了公共环境可以跨越多个协议版本长期复用，协议演进只影响protocol/<version>/目录下的插件与 Demo 资源。

6.2 后端接口

其实现位于 apps/observable-weather/server.py，是一个基于 Python 标准库http.server的轻量服务，对外提供四个端点：

调用/weather时会记录事件的 HTTP 方法、路径、查询参数和X-Request-ID请求头，并按顺序编号。这套"可观察"设计是各 Demo 做响应断言的关键：通过__state可以核对网关转发的真实请求细节（例如 MCP 方法是否被正确映射为 HTTP 请求）。

6.3 部署形态

apps/observable-weather/deployment.yaml 定义了：

• 命名空间mcp-demo；
• 单副本 Deployment，容器端口8080，配置了基于/healthz的 readinessProbe（每 2 秒探测一次）；
• ClusterIP Serviceobservable-weather，端口8080→targetPort: http。

镜像基于 apps/observable-weather/Dockerfile 的python:3.12-alpine构建，由up.sh在本地构建并加载进 Kind 集群，无需外部拉取。

七、可覆盖参数（全部环境变量）

所有环境变量默认值集中定义在 scripts/common.sh，均可通过环境变量覆盖：

原文给出的端口覆盖示例（来自 environment/README.md 的"可覆盖参数"小节）：

MCP_DEMO_CLUSTER=my-mcp-demo \ MCP_DEMO_GATEWAY_PORT=28080 \ MCP_DEMO_CONSOLE_PORT=28081 \ MCP_DEMO_BACKEND_PORT=28082 \ ./environment/scripts/up.sh

实际使用时建议至少保证三个端口不与本机已有服务冲突；集群名称的覆盖需要与所有权记录保持一致，否则会触发"拒绝操作"保护。

八、所有权保护机制（源码级解析）

环境脚本设计了一套"集群所有权"机制，防止误删或误用其他工具创建的 Kind 集群，是up.sh、status.sh、down.sh三者的共同安全底座。

8.1 双重记录

1. 宿主机侧：.runtime下写入三个文件（scripts/common.sh）：
   • container-engine：记录使用的容器引擎（docker/podman）；
   • cluster-name：记录集群名；
   • instance-id：记录本次创建的实例 ID（优先uuidgen，失败时回退为时间戳-PID-随机数）。
2. 集群侧：在kube-system命名空间创建名为higress-mcp-demo-owner的 ConfigMap，以instance-id字段记录相同实例 ID（scripts/common.sh）。

8.2 校验逻辑

cluster_is_owned会比对宿主机记录的 instance-id 与集群内 ConfigMap 的instance-id，两者一致才判定"归本 Demo 所有"。基于此：

• 启动时：若存在同名集群但非本 Demo 创建，up.sh直接拒绝复用并退出（scripts/up.sh）；
• 清理时：down.sh对无主集群一律拒绝删除（scripts/down.sh）。

因此，如果你本地已有一个恰好同名的 Kind 集群，最稳妥的做法是通过MCP_DEMO_CLUSTER指定一个全新的名称。

8.3 端口转发的可追溯停止

start_port_forward/stop_port_forward会把每次转发的命令行签名写入.runtime/<name>.command，停止时校验 PID 对应的实际命令行包含该签名，避免误杀无关进程（scripts/common.sh）。

九、启动后的下一步：运行 MCP Demo

环境就绪后，即可进入对应协议版本的 Demo 目录按 README 逐步验证。以 01-stateless-http 为例，典型流程为：

cd protocol/2026-07-28/01-stateless-http export GATEWAY_URL=http://127.0.0.1:18080/mcp export MCP_HOST=stateless.mcp.demo # 部署 Demo 资源（Ingress + WasmPlugin） kubectl apply -f resources.yaml # 以独立 HTTP 请求调用 server/discover、tools/list、tools/call curl -sS "$GATEWAY_URL" -H "Host: $MCP_HOST" -H 'MCP-Protocol-Version: 2026-07-28' \ -H 'Mcp-Method: server/discover' -H 'X-Request-ID: demo-stateless-discover' \ --data-binary @requests/discover.json | jq

该 Demo 无需initialize、不产生协议 Session，且可通过kubectl logs -n higress-system deployment/higress-gateway检索demo-stateless关键字查看网关侧证据。

十、常见问题速查

结语

本文以 samples/mcp/environment 为骨架，完整还原了 Higress MCP 公共实验环境的架构设计、启动/检查/清理全流程、可观察后端的接口边界以及全部可覆盖参数，并结合 scripts 源码剖析了容器引擎选择、插件目录挂载和集群所有权保护等关键实现。掌握了这套环境，你就可以在本地以完全可复现的方式，依次验证 Higress 对各 MCP 协议版本能力的支持情况。

【免费下载链接】higress🤖 AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress