├── files ├── McpSampleServer.zip └── higress-config.yaml ├── images ├── mcp-with-sse │ ├── new-route.png │ ├── request-sse.png │ ├── service-list.png │ ├── higress-config.png │ ├── route-rewrite.png │ ├── new-service-source.png │ ├── request-tools-call-1.png │ ├── request-tools-call-2.png │ ├── request-tools-list-1.png │ └── request-tools-list-2.png ├── load-wasm-with-http │ └── http.png ├── mcp-with-nacos3 │ ├── tool-meta.png │ ├── request-sse.png │ ├── higress-config.png │ ├── new-mcp-server.png │ ├── service-list.png │ ├── mcp-server-list.png │ ├── new-service-source.png │ ├── request-tools-call-1.png │ ├── request-tools-call-2.png │ ├── request-tools-list-1.png │ └── request-tools-list-2.png ├── non-k8s-skywalking │ ├── route.png │ ├── service.png │ ├── servicesource.png │ └── higress-config.png └── mcp-with-nacos3-sse │ ├── mcp-server-list.png │ ├── new-mcp-server.png │ └── new-service-source.png ├── docs ├── load-wasm-with-http.md ├── standalone-crs.md ├── servicename-config.md ├── log-viewing.md ├── non-k8s-skywalking.md ├── wasm-test-redis.md ├── mcp-with-sse.md ├── mcp-with-nacos3-sse.md ├── faq.md └── mcp-with-nacos3.md ├── README.md └── scripts └── download-wasm-files.sh /files/McpSampleServer.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/files/McpSampleServer.zip -------------------------------------------------------------------------------- /images/mcp-with-sse/new-route.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-sse/new-route.png -------------------------------------------------------------------------------- /images/load-wasm-with-http/http.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/load-wasm-with-http/http.png -------------------------------------------------------------------------------- /images/mcp-with-nacos3/tool-meta.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-nacos3/tool-meta.png -------------------------------------------------------------------------------- /images/mcp-with-sse/request-sse.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-sse/request-sse.png -------------------------------------------------------------------------------- /images/mcp-with-sse/service-list.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-sse/service-list.png -------------------------------------------------------------------------------- /images/non-k8s-skywalking/route.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/non-k8s-skywalking/route.png -------------------------------------------------------------------------------- /images/mcp-with-nacos3/request-sse.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-nacos3/request-sse.png -------------------------------------------------------------------------------- /images/mcp-with-sse/higress-config.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-sse/higress-config.png -------------------------------------------------------------------------------- /images/mcp-with-sse/route-rewrite.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-sse/route-rewrite.png -------------------------------------------------------------------------------- /images/non-k8s-skywalking/service.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/non-k8s-skywalking/service.png -------------------------------------------------------------------------------- /images/mcp-with-nacos3/higress-config.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-nacos3/higress-config.png -------------------------------------------------------------------------------- /images/mcp-with-nacos3/new-mcp-server.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-nacos3/new-mcp-server.png -------------------------------------------------------------------------------- /images/mcp-with-nacos3/service-list.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-nacos3/service-list.png -------------------------------------------------------------------------------- /images/mcp-with-nacos3/mcp-server-list.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-nacos3/mcp-server-list.png -------------------------------------------------------------------------------- /images/mcp-with-sse/new-service-source.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-sse/new-service-source.png -------------------------------------------------------------------------------- /images/non-k8s-skywalking/servicesource.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/non-k8s-skywalking/servicesource.png -------------------------------------------------------------------------------- /images/mcp-with-nacos3-sse/mcp-server-list.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-nacos3-sse/mcp-server-list.png -------------------------------------------------------------------------------- /images/mcp-with-nacos3-sse/new-mcp-server.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-nacos3-sse/new-mcp-server.png -------------------------------------------------------------------------------- /images/mcp-with-nacos3/new-service-source.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-nacos3/new-service-source.png -------------------------------------------------------------------------------- /images/mcp-with-sse/request-tools-call-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-sse/request-tools-call-1.png -------------------------------------------------------------------------------- /images/mcp-with-sse/request-tools-call-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-sse/request-tools-call-2.png -------------------------------------------------------------------------------- /images/mcp-with-sse/request-tools-list-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-sse/request-tools-list-1.png -------------------------------------------------------------------------------- /images/mcp-with-sse/request-tools-list-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-sse/request-tools-list-2.png -------------------------------------------------------------------------------- /images/non-k8s-skywalking/higress-config.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/non-k8s-skywalking/higress-config.png -------------------------------------------------------------------------------- /images/mcp-with-nacos3/request-tools-call-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-nacos3/request-tools-call-1.png -------------------------------------------------------------------------------- /images/mcp-with-nacos3/request-tools-call-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-nacos3/request-tools-call-2.png -------------------------------------------------------------------------------- /images/mcp-with-nacos3/request-tools-list-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-nacos3/request-tools-list-1.png -------------------------------------------------------------------------------- /images/mcp-with-nacos3/request-tools-list-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-nacos3/request-tools-list-2.png -------------------------------------------------------------------------------- /images/mcp-with-nacos3-sse/new-service-source.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CH3CHO/higress-notes/HEAD/images/mcp-with-nacos3-sse/new-service-source.png -------------------------------------------------------------------------------- /docs/load-wasm-with-http.md: -------------------------------------------------------------------------------- 1 | # 使用 HTTP/HTTPS 协议加载 Wasm 插件 2 | 3 | ## 文件要求 4 | 5 | 考虑到便捷性，建议目标 URL 直接指向 Wasm 文件。 6 | 7 | ## HTTP 协议 8 | 9 | 直接配置即可，但需要确保目标 URL 可以被 Gateway 容器访问到。可以尝试在容器内 curl 验证。 10 | 11 | ![http](../images/load-wasm-with-http/http.png) 12 | 13 | ## HTTPS 协议 14 | 15 | 配置方式和要求与 HTTP 协议类似。但如果服务端使用的是自签等非可信任证书的话，需要在 Gateway 容器内增加一个名为“WASM_INSECURE_REGISTRIES”的环境变量，值可以直接配置为“*”，表示信任所有服务器返回的 HTTPS 证书。 16 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Higress 笔记 2 | 3 | - [一些常见问题](./docs/faq.md) 4 | - [Wasm 插件本地测试时如何连接本地 Redis](./docs/wasm-test-redis.md) 5 | - [使用 HTTP/HTTPS 协议加载 Wasm 插件](./docs/load-wasm-with-http.md) 6 | - [非 K8s 部署下对接 Skywalking](./docs/non-k8s-skywalking.md) 7 | - [如何正确配置 Wasm 插件访问外部服务](./docs/servicename-config.md) 8 | - [如何直接修改非 K8s 安装的 Higress 的配置数据](./docs/standalone-crs.md) 9 | - [如何查看 Higress 的运行日志](./docs/log-viewing.md) 10 | - 如何让 MCP Server 接入 Higress 网关 11 | - [对接 Nacos 3 的 MCP Server 注册中心](./docs/mcp-with-nacos3.md) 12 | - [对接现存的 SSE MCP Server](./docs/mcp-with-sse.md) -------------------------------------------------------------------------------- /docs/standalone-crs.md: -------------------------------------------------------------------------------- 1 | # 如何直接修改非 K8s 安装的 Higress 的配置数据 2 | 3 | ## 概述 4 | 5 | 非 K8s 安装的 Higress 目前支持两种配置数据存储方式：Nacos 和文件。以下将分别介绍。 6 | 7 | ## Nacos 存储方式 8 | 9 | 1. 打开 Nacos 的控制台页面 10 | 2. 进入左侧的配置管理 11 | 3. 在上方选择对应的命名空间，默认为 higress-system 12 | 4. 下方列出的就是所有 Higress 会读取的配置数据。 13 | 5. 各个 dataId 的前缀代表了它保存的配置数据类型，配置数据的格式即为对应的 K8s YAML 格式数据。大家可以按需编辑 14 | 6. 如果要创建新的配置数据，则需要注意 dataId 的命名需要符合规则，且配置的 group 为 higress-system。 15 | 7. dataId 以 `__names__` 结尾的是 Higress 内部数据。大家无需关心。 16 | 17 | ## 文件存储方式 18 | 19 | 这也是使用 all-in-one 镜像运行 Higress 时所使用的配置存储方式。文件默认位于执行 shell 脚本的目录下的 higress 子目录内。 20 | 21 | 各类配置文件分别放在对应的子目录下。文件名字就是配置资源名字。文件内容是 K8s 的 YAML 格式数据。大家可以按需编辑或新增。 22 | 23 | > 注意：由于容器内的 Higress 进程可能无法监听到宿主机的文件变更，如果大家在宿主机上修改或者新增了文件，可以重启容器来更新配置。 -------------------------------------------------------------------------------- /docs/servicename-config.md: -------------------------------------------------------------------------------- 1 | # 如何正确配置 Wasm 插件访问外部服务 2 | 3 | ## 背景 4 | 5 | 现在 Higress 很多 Wasm 插件的功能都涉及到访问外部服务，从 Redis 存储到大模型 API。很多时候，我们填写好配置，结果发现请求并不能正常发出，Gateway 的日志中也出现了类似 `bad argument` 的字样。 6 | 7 | 那么如何正确编写插件配置来保证请求能够正常工作呢？下文将为各位详细介绍。 8 | 9 | ## 基础知识 10 | 11 | Higress 的数据面基于 Envoy 搭建。Wasm 插件也运行在 Envoy 当中，请求都由插件的 Envoy 宿主实际负责发起。所有请求的目标必须为 Envoy 内的一个服务，而并非任意一个 IP 或者域名。而我们需要配置的所谓 `serviceName` 和 `servicePort` 就是这个对 Envoy 可见的 Service 的对应信息。 12 | 13 | ## 配置流程 14 | 15 | ### 1. 创建服务来源 16 | 17 | 1. 打开 Higress Console 18 | 2. 进入“服务来源”页面 19 | 3. 点击“创建服务来源”按钮 20 | 4. 如果使用 IP 连接目标服务 21 | 1. 类型选择“固定地址” 22 | 2. 根据提示填入服务地址，即 `IP:端口` 23 | 3. 如果使用域名或者主机名连接目标服务 24 | 1. 类型选择“DNS域名” 25 | 2. 端口填入目标服务的访问端口 26 | 3. 域名列表填入目标服务的域名或主机名 27 | 4. 根据实际情况选择目标服务的协议。如果目标服务使用 TCP 协议访问，则此处选择 HTTP 即可。 28 | 5. 点击“保存” 29 | 6. 进入“服务列表”页面，记录新增的目标服务名称（类似 xxx.static 或 xxx.dns）和端口信息 30 | 31 | ### 2. 让服务对 Envoy 可见 32 | 33 | 截止 2.0.7 版本，在默认配置下，Higress 只会下发配置了路由的服务至 Envoy。以下有两种方法可以让我们的目标服务对 Envoy 可见。 34 | 35 | #### 方法 1：配置占位路由 36 | 37 | 1. 打开 Higress Console 38 | 2. 进入“路由配置”页面 39 | 3. 点击“创建路由”按钮 40 | 4. 按照以下配置填写路由表单： 41 | - 名称任意，可以考虑使用类似“xxx-dummy-route”之类的名称 42 | - 域名留空 43 | - 匹配规则任意，可以考虑使用“前缀匹配 + /xxx-dummy-route”的配置 44 | - 请求头设置一个绝对不会匹配到的规则，例如：“never-matched-header: nevery-matched” 45 | - 服务选择之前配置的目标服务 46 | 4. 点击“保存” 47 | 48 | #### 方法 2. 修改配置下发全部服务 49 | 50 | 本方法供使用 helm 安装的 Higress 实例选择使用。将 `global.onlyPushRouteCluster` 参数设置为 `false` 更新安装配置即可。 51 | 52 | 相关文档：https://higress.cn/docs/latest/ops/deploy-by-helm/#%E5%B8%B8%E7%94%A8%E5%AE%89%E8%A3%85%E5%8F%82%E6%95%B0 53 | -------------------------------------------------------------------------------- /scripts/download-wasm-files.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | PLUGIN_NAME=${PLUGIN_NAME:-ai-proxy} 4 | IMAGE_URL="higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/$PLUGIN_NAME:1.0.0" 5 | if [ "$PLUGIN_NAME" == "mcp-server" ]; then 6 | IMAGE_URL="higress-registry.cn-hangzhou.cr.aliyuncs.com/mcp-server/all-in-one:1.0.0" 7 | fi 8 | 9 | set -e 10 | 11 | trap " 12 | rm $PLUGIN_NAME.json > /dev/null 13 | rm $PLUGIN_NAME.tar.gz > /dev/null 14 | " 0 15 | 16 | oras manifest fetch $IMAGE_URL > $PLUGIN_NAME.json 17 | 18 | WASM_SHA256=$(jq -r '.layers[] | select(.mediaType == "application/vnd.module.wasm.content.layer.v1+wasm") | .digest' $PLUGIN_NAME.json) 19 | if [ -n "$WASM_SHA256" ]; then 20 | echo "Downloading wasm file from $WASM_SHA256 blob..." 21 | oras blob fetch $IMAGE_URL@$WASM_SHA256 --output $PLUGIN_NAME.wasm 22 | echo "Done" 23 | exit 0 24 | fi 25 | 26 | WASM_SHA256=$(jq -r '.layers[] | select(.mediaType == "application/vnd.docker.image.rootfs.diff.tar.gzip") | .digest' $PLUGIN_NAME.json) 27 | if [ -z "$WASM_SHA256" ]; then 28 | WASM_SHA256=$(jq -r '.layers[] | select(.mediaType == "application/vnd.oci.image.layer.v1.tar+gzip") | .digest' $PLUGIN_NAME.json) 29 | fi 30 | if [ -n "$WASM_SHA256" ]; then 31 | echo "Downloading tgz from $WASM_SHA256 blob..." 32 | oras blob fetch $IMAGE_URL@$WASM_SHA256 --output $PLUGIN_NAME.tar.gz 33 | plugin_file_name=$(tar -zxvf $PLUGIN_NAME.tar.gz) 34 | mv $plugin_file_name $PLUGIN_NAME.wasm 35 | # rm -f $PLUGIN_NAME.tar.gz 36 | echo "Done" 37 | exit 0 38 | fi 39 | 40 | echo "Unsupport image format" 41 | cat $PLUGIN_NAME.json | jq 42 | exit 1 43 | -------------------------------------------------------------------------------- /docs/log-viewing.md: -------------------------------------------------------------------------------- 1 | # 如何查看 Higress 的运行日志 2 | 3 | ## 查看组件日志 4 | 5 | ### K8s 部署 6 | 7 | 直接使用 `kubectl logs` 命令即可。例如： 8 | 9 | ```bash 10 | kubectl logs -n higress-system higress-gateway-5cb7f44768-snfbd 11 | ``` 12 | 13 | 注意，`higress-controller` pod 里有两个容器，`higress-core` 和 `discovery`，分别对应 `controller` 和 `pilot` 两个组件。查看日志的时候可以使用 `-c` 参数来执行要查看日志的容器名称。例如： 14 | 15 | ```bash 16 | kubectl logs -n higress-system higress-controller-5c768d64d9-m5gtp -c discovery 17 | ``` 18 | 19 | ### Docker Compose 部署 20 | 21 | 在安装目录下执行 `./bin/logs.sh 组件名称` 即可查看对应组件的日志。 22 | 23 | 常用的组件名称如下： 24 | 25 | - apiserver 26 | - controller 27 | - pilot 28 | - gateway 29 | - console 30 | 31 | ### all-in-one 镜像部署 32 | 33 | all-in-one 模式下，Higress 所有的日志文件均保存在容器内的 `/var/log/higress` 目录下。使用 `docker exec` 命令进入到容器内直接查看文件内容即可。 34 | 35 | ```bash 36 | docker exec -it higress-ai-gateway bash 37 | 38 | cd /var/log/higress 39 | ls -l 40 | cat gateway.log 41 | ``` 42 | 43 | ## 查看访问日志 44 | 45 | ### 已开启内置监控套件 46 | 47 | 如果开启了 Higress 内置的监控套件，那么你可以在 Higress Console 上直接查看请求日志： 48 | 49 | 1. 进入 Higress Console 的监控面板页面 50 | 2. 点击右侧监控区域最左边的“四个小方格”图标 51 | 3. 点击右侧的“Higress Access Logs”即可进入访问日志看板页面 52 | 53 | ### 未开启内置监控套件 54 | 55 | 这种情况下，访问日志会与运行日志一同数据。参考运行日志的查看方法即可。 56 | 57 | ## 调整日志等级 58 | 59 | 目前需要调整日志等级的主要是 gateway 组件。临时调整日志等级的具体方式为： 60 | 61 | 1. 打开 gateway 所在容器的 `bash` 终端 62 | - K8s 部署：`kubectl exec -it higress-gateway-xxxx-yyyyy -n higress-system -- bash` 63 | - Docker Compose 部署：`docker exec -it higress-gateway-1 bash` 64 | - all-in-one 镜像部署：`docker exec -it higress-ai-gateway bash` 65 | 2. 执行命令：`curl localhost:15000/logging?模块名=日志等级 -X POST` 66 | 67 | 常用模块名称有： 68 | 69 | - golang：MCP Server 模块 70 | - wasm：Wasm 插件模块 71 | 72 | 日志等级包括： 73 | 74 | - trace 75 | - debug 76 | - info 77 | - warning/warn（默认值） 78 | - error 79 | - critical 80 | - off 81 | 82 | 调整后的日志等级在 gateway 重启后将会自动失效。 -------------------------------------------------------------------------------- /docs/non-k8s-skywalking.md: -------------------------------------------------------------------------------- 1 | # 非 K8s 部署下对接 Skywalking 2 | 3 | ## 配置 Skywalking 服务 4 | 5 | ### 配置服务来源 6 | 7 | 1. 打开 Higress Console 8 | 2. 进入“服务来源”页面 9 | 3. 点击“创建服务来源”按钮 10 | 4. 如果使用 IP 连接 Skywalking 服务 11 | 1. 类型选择“固定地址” 12 | 2. 根据提示填入服务地址，端口需要使用 Skywalking 服务的 gRPC 端口，默认为 11800 13 | 3. 如果使用域名或者主机名连接 Skywalking 服务 14 | 1. 类型选择“DNS域名” 15 | 2. 端口填入 Skywalking 服务的 gRPC 端口，默认为 11800 16 | 3. 域名列表填入 Skywalking 服务的域名或主机名 17 | 4. 点击“保存” 18 | 5. 进入“服务列表”页面，记录新增的 Skywalking 服务名称（类似 xxx.static 或 xxx.dns） 19 | 20 | 配置示例： 21 | 22 | ![servicesource](../images/non-k8s-skywalking/servicesource.png) 23 | 24 | ![service](../images/non-k8s-skywalking/service.png) 25 | 26 | ### 配置占位路由 27 | 28 | 注：本步骤仅在 https://github.com/alibaba/higress/issues/1316 解决前需要执行。 29 | 30 | 1. 打开 Higress Console 31 | 2. 进入“路由配置”页面 32 | 3. 点击“创建路由”按钮 33 | 4. 按照以下配置填写路由表单： 34 | - 名称任意，可以考虑使用类似“skywalking-dummy-route”之类的名称 35 | - 域名留空 36 | - 匹配规则任意，可以考虑使用“前缀匹配 + /skywalking-dummy-route”的配置 37 | - 请求头设置一个绝对不会匹配到的规则，例如：“never-matched-header: nevery-matched” 38 | - 附加注解添加“higress.io/backend-protocol: GRPC” 39 | - 服务选择之前配置的 Skywalking 服务 40 | 4. 点击“保存” 41 | 42 | 配置示例： 43 | 44 | ![route](../images/non-k8s-skywalking/route.png) 45 | 46 | ## 启用 Higress Skywalking 功能 47 | 48 | 注：此处基于 Nacos 配置方式进行讲解。如果使用其他配置方式，请自行领悟~ 49 | 50 | 1. 打开 Nacos 控制台 51 | 2. 进入"配置管理"→“配置列表”，选择 higress-system 命名空间 52 | 3. 编辑 Data Id 为 configmaps.higress-config 的配置 53 | 4. 在“data:”节点下添加以下配置： 54 | ```yaml 55 | data: 56 | higress: |- 57 | tracing: 58 | enable: true 59 | sampling: 100 60 | timeout: 500 61 | skywalking: 62 | service: {前面记录下来的 Skywalking 服务名称} 63 | port: {如果你用的是固定类型的服务来源，这里统一填 80。如果用的是 DNS 域名类型的服务来源，这里填配置服务来源时填写的服务端口。} 64 | ``` 65 | ![higress-config](../images/non-k8s-skywalking/higress-config.png) 66 | 5. 发布配置 67 | 68 | ## 配置完成 -------------------------------------------------------------------------------- /docs/wasm-test-redis.md: -------------------------------------------------------------------------------- 1 | # Wasm 插件本地测试时如何连接本地 Redis 2 | 3 | ## TL;DR 4 | 5 | envoy.yaml 里配置 Redis cluster 时，socketAddr 要尽量用 IP，不要用主机名。 6 | 7 | ## 背景 8 | 9 | 在开发 Wasm 插件过程中，我们镜像会使用 Docker Compose + Envoy + Volume Mount 的方式测试本地构建出来的插件。如果插件需要连接 Redis，那么我们就需要在 envoy.yaml 中配置一个 Redis 的 cluster。如果配置中的 Redis 节点地址使用机器名，那么在启动插件的时候可能会出现初始化 Redis 客户端报“bad argument”的错误。 10 | 11 | ## 原因 12 | 13 | 这种错误一般只发生在插件在 `parseConfig` 阶段调用 `RedisClusterClient.Init()` 函数的时候。、 14 | 15 | 在 Envoy 初始化的过程中，集群信息的初始化与 Wasm 插件的初始化可以认为是并行进行的。如果使用主机名进行配置，要获取实例的实际 IP 就需要经过 DNS 解析。而 DNS 解析一般是需要一些时间的（笔者的测试机和网络条件下需要约 200ms），Redis 客户端的初始化又需要与 Redis 集群建立连接和通信。这一延迟就可能会导致 Wasm 插件进行初始化时 Redis 的集群信息还没有就绪，进而引发上述报错。 16 | 17 | 而在 Higress 的实际运行过程中，集群信息是通过 xDS 进行下发的，这个延迟的问题不会非常显著。 18 | 19 | ## 解决方案示例 20 | 21 | Docker Compose 本身是支持给服务配置静态 IP 的。我们可以使用这一配置来让 Redis 集群获得静态 IP 以便我们更新 Envoy 配置。 22 | 23 | ```yaml 24 | version: '3.7' 25 | services: 26 | envoy: 27 | image: higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway:1.4.2 28 | entrypoint: /usr/local/bin/envoy 29 | command: -c /etc/envoy/envoy.yaml --log-level info --component-log-level wasm:debug 30 | depends_on: 31 | - http-echo 32 | networks: 33 | - wasmtest 34 | ports: 35 | - "10000:10000" 36 | - "9901:9901" 37 | volumes: 38 | - /home/me/higress/plugins/wasm-go/extensions/ai-proxy/test/envoy.yaml:/etc/envoy/envoy.yaml 39 | - /home/me/higress/plugins/wasm-go/extensions/ai-proxy/out/plugin.wasm:/etc/envoy/plugin.wasm 40 | 41 | redis: 42 | image: redis:latest 43 | networks: 44 | wasmtest: 45 | ipv4_address: 172.20.0.100 46 | ports: 47 | - "6379:6379" 48 | 49 | http-echo: 50 | image: mendhak/http-https-echo:latest 51 | networks: 52 | - wasmtest 53 | ports: 54 | - "12345:8080" 55 | 56 | networks: 57 | wasmtest: 58 | ipam: 59 | config: 60 | - subnet: 172.20.0.0/24 61 | ``` 62 | 63 | ```yaml 64 | - name: outbound|6379||redis.dns 65 | connect_timeout: 30s 66 | type: LOGICAL_DNS 67 | dns_lookup_family: V4_ONLY 68 | lb_policy: ROUND_ROBIN 69 | load_assignment: 70 | cluster_name: outbound|6379||redis.dns 71 | endpoints: 72 | - lb_endpoints: 73 | - endpoint: 74 | address: 75 | socket_address: 76 | address: 172.20.0.100 77 | port_value: 6379 78 | ``` -------------------------------------------------------------------------------- /files/higress-config.yaml: -------------------------------------------------------------------------------- 1 | apiVersion: v1 2 | kind: ConfigMap 3 | metadata: 4 | name: higress-config 5 | namespace: higress-system 6 | creationTimestamp: "2000-01-01T00:00:00Z" 7 | resourceVersion: "1" 8 | data: 9 | higress: |- 10 | mcpServer: 11 | enable: false 12 | sse_path_suffix: /sse 13 | redis: 14 | address: redis-address:6379 15 | username: "" 16 | password: "" 17 | db: 0 18 | match_list: [] 19 | servers: [] 20 | downstream: 21 | connectionBufferLimits: 32768 22 | http2: 23 | initialConnectionWindowSize: 1048576 24 | initialStreamWindowSize: 65535 25 | maxConcurrentStreams: 100 26 | idleTimeout: 180 27 | maxRequestHeadersKb: 60 28 | routeTimeout: 0 29 | upstream: 30 | connectionBufferLimits: 10485760 31 | idleTimeout: 10 32 | mesh: |- 33 | accessLogEncoding: TEXT 34 | accessLogFile: /dev/stdout 35 | accessLogFormat: | 36 | {"ai_log":"%FILTER_STATE(wasm.ai_log:PLAIN)%","authority":"%REQ(X-ENVOY-ORIGINAL-HOST?:AUTHORITY)%","bytes_received":"%BYTES_RECEIVED%","bytes_sent":"%BYTES_SENT%","downstream_local_address":"%DOWNSTREAM_LOCAL_ADDRESS%","downstream_remote_address":"%DOWNSTREAM_REMOTE_ADDRESS%","duration":"%DURATION%","istio_policy_status":"%DYNAMIC_METADATA(istio.mixer:status)%","method":"%REQ(:METHOD)%","path":"%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%","protocol":"%PROTOCOL%","request_id":"%REQ(X-REQUEST-ID)%","requested_server_name":"%REQUESTED_SERVER_NAME%","response_code":"%RESPONSE_CODE%","response_flags":"%RESPONSE_FLAGS%","route_name":"%ROUTE_NAME%","start_time":"%START_TIME%","trace_id":"%REQ(X-B3-TRACEID)%","upstream_cluster":"%UPSTREAM_CLUSTER%","upstream_host":"%UPSTREAM_HOST%","upstream_local_address":"%UPSTREAM_LOCAL_ADDRESS%","upstream_service_time":"%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%","upstream_transport_failure_reason":"%UPSTREAM_TRANSPORT_FAILURE_REASON%","user_agent":"%REQ(USER-AGENT)%","x_forwarded_for":"%REQ(X-FORWARDED-FOR)%","response_code_details":"%RESPONSE_CODE_DETAILS%"} 37 | configSources: 38 | - address: xds://127.0.0.1:15051 39 | - address: k8s:// 40 | defaultConfig: 41 | disableAlpnH2: true 42 | discoveryAddress: 127.0.0.1:15012 43 | controlPlaneAuthPolicy: MUTUAL_TLS 44 | proxyStatsMatcher: 45 | inclusionRegexps: 46 | - .* 47 | dnsRefreshRate: 200s 48 | enableAutoMtls: false 49 | enablePrometheusMerge: true 50 | ingressControllerMode: "OFF" 51 | mseIngressGlobalConfig: 52 | enableH3: false 53 | enableProxyProtocol: false 54 | protocolDetectionTimeout: 100ms 55 | rootNamespace: higress-system 56 | trustDomain: cluster.local 57 | meshNetworks: 'networks: {}' -------------------------------------------------------------------------------- /docs/mcp-with-sse.md: -------------------------------------------------------------------------------- 1 | # 如何让 Higress 对接现存的 MCP Server（SSE 版） 2 | 3 | ## 概述 4 | 5 | 本文将介绍如何将一个现存使用 SSE Transport 的 MCP Server 通过 Higress 暴露给 MCP Client 访问的完整过程。整个流程将基于一个测试用的简单后端服务实现进行。所有的配置内容也均以此服务所提供的功能为模版编写。建议大家先严格按照本文的步骤配置完成后再尝试自行调整配置对接其他服务。 6 | 7 | ## 环境准备 8 | 9 | ### 1. 部署 Higress 10 | 11 | 在本地使用 all-in-one 镜像方式启动 Higress： 12 | 13 | ```bash 14 | # 创建一个工作目录 15 | mkdir higress; cd higress 16 | # 强制拉取最新的 all-in-one 镜像 17 | docker pull higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest 18 | # 启动 higress，配置文件会写到工作目录下 19 | docker run -d --rm --name higress-ai -v ${PWD}:/data \ 20 | -p 8001:8001 -p 8080:8080 -p 8443:8443 \ 21 | higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest 22 | ``` 23 | 24 | 安装完成后，在浏览器中访问 Higress Console，确认底部显示的版本号不低于 2.1.4。 25 | 26 | ### 2. 启动后端服务 27 | 28 | 1. 测试服务使用 NodeJS 编写。所以请大家先访问 NodeJS 官网（[https://nodejs.org](https://nodejs.org/en)）下载并安装 NodeJS 运行环境 29 | 2. 下载[测试服务压缩包](../files/McpSampleServer.zip) 30 | 3. 解压至任意目录 31 | 4. 执行以下命令启动测试服务 32 | ```bash 33 | npm install 34 | npm start 35 | ``` 36 | 5. 启动完成后，在浏览器访问 [http://localhost:3000/](http://localhost:3000)。若能够显示“Hello world!”，则代表服务启动成功。 37 | 38 | ## 配置流程 39 | 40 | 以下所有配置都将在 Higress Console 中进行。在浏览器中打开 Higress Console（[http://localhost:8001/](http://localhost:8001/)） 41 | 42 | 43 | ### 服务来源配置 44 | 45 | 1. 点击左侧的“服务来源” 46 | 2. 点击“创建服务来源”按钮 47 | 3. 参考下图填写服务来源信息
48 | ![new-service-source](../images/mcp-with-sse/new-service-source.png) 49 | 4. 点击“确定”按钮 50 | 5. 点击左侧的“服务列表”，确认列表中出现了我们刚刚创建的 MCP Server
51 | ![service-list](../images/mcp-with-sse/service-list.png) 52 | 53 | ### 路由配置 54 | 55 | 1. 点击左侧的“路由配置” 56 | 2. 点击“创建路由”按钮 57 | 3. 参考下图填写路由信息
58 | ![new-route](../images/mcp-with-sse/new-route.png) 59 | 4. 点击“确定”按钮 60 | 5. 点击新创建的路由右侧的“策略”链接 61 | 6. 点击“重写”策略下方的配置按钮 62 | 7. 按下图填入配置
63 | ![route-rewrite](../images/mcp-with-sse/route-rewrite.png) 64 | 8. 点击“保存”按钮 65 | 66 | ### MCP Server Filter 配置 67 | 68 | 1. 点击左侧的“系统设置” 69 | 2. 点击右侧链接下载模版文件，并将文件内容完整粘贴到输入框中：[文件链接](../files/higress-config.yaml) 70 | 3. 修改 `higress` 配置项中的 `mcpServer` 配置 71 | 1. 将 `enable` 改为 `true` 72 | 2. 移除 `redis` 配置项 73 | 3. 在 `match_list` 中添加一个新元素： 74 | ```yaml 75 | - match_rule_domain: "*" 76 | match_rule_path: /mcp/sample 77 | match_rule_type: prefix 78 | upstream_type: sse 79 | enable_path_rewrite: true 80 | path_rewrite_prefix: /mcp 81 | ``` 82 | 4. 修改后的配置如下图所示
83 | ![higress-config](../images/mcp-with-sse/higress-config.png) 84 | 5. 点击“提交”按钮 85 | 6. 提交之后如果页面没有任何提示的话，可以刷新页面，确认配置为更新后的内容即可 86 | 87 | ## 测试验证 88 | 89 | 1. 在浏览器中打开 `http://localhost:8080/mcp/sample/sse` 90 | 2. 正常情况下页面显示如下图所示
91 | ![request-sse](../images/mcp-with-sse/request-sse.png) 92 | 3. 用 curl 命令验证获取工具列表 93 | ```bash 94 | # sessionId 需要使用浏览器中返回的值 95 | curl http://localhost:8080/mcp/sample/new/messages?sessionId=62d5e258-f1d6-43e8-81a1-f7a2ae36abfb \ 96 | -H 'Content-Type: application/json' \ 97 | -d '{ 98 | "jsonrpc": "2.0", 99 | "id": 1, 100 | "method": "tools/list" 101 | }' 102 | ``` 103 | 4. 正常情况下，终端中会输出“Accepted”字样，而之前的浏览器页面上则会推送工具列表信息
104 | ![request-tools-list-1](../images/mcp-with-sse/request-tools-list-1.png) 105 | ![request-tools-list-2](../images/mcp-with-sse/request-tools-list-2.png) 106 | 5. 用 curl 命令验证工具调用 107 | ```bash 108 | curl http://localhost:8080/mcp/sample/new/messages?sessionId=62d5e258-f1d6-43e8-81a1-f7a2ae36abfb \ 109 | -H 'Content-Type: application/json' \ 110 | -d '{ 111 | "jsonrpc": "2.0", 112 | "id": 2, 113 | "method": "tools/call", 114 | "params": { 115 | "name": "add", 116 | "arguments": { 117 | "a": 1, 118 | "b": 2 119 | } 120 | } 121 | }' 122 | ``` 123 | 6. 正常情况下，终端中会输出“Accepted”字样，而之前的浏览器页面上则会推送调用结果
124 | ![request-tools-call-1](../images/mcp-with-sse/request-tools-call-1.png) 125 | ![request-tools-call-2](../images/mcp-with-sse/request-tools-call-2.png) 126 | 127 | ### 工具验证 128 | 129 | 在完成简单验证之后，大家就可以把这个 MCP Server 配置到支持 MCP Client 的工具（如 DeepChat、Cherry Studio 等）中进行验证了。工具的 URL 为 `http://localhost:8080/mcp/sample/sse`。 130 | 131 | ## 配置要点 132 | 133 | TBD -------------------------------------------------------------------------------- /docs/mcp-with-nacos3-sse.md: -------------------------------------------------------------------------------- 1 | # 如何让 Higress 对接 Nacos 3 MCP Server 管理功能（SSE 服务版） 2 | 3 | ## 概述 4 | 5 | 本文将介绍在 Nacos 3 上配置 MCP Server，将一个支持 SSE Transport 的 MCP Server 通过 Higress 暴露给 MCP Client 访问的完整过程。整个流程将基于一个测试用的简单后端服务实现进行。所有的配置内容也均以此服务所提供的功能为模版编写。建议大家先严格按照本文的步骤配置完成后再尝试自行调整配置对接其他服务。 6 | 7 | ## 环境准备 8 | 9 | ### 1. 部署 Higress 10 | 11 | 在本地使用 all-in-one 镜像方式启动 Higress： 12 | 13 | ```bash 14 | # 创建一个工作目录 15 | mkdir higress; cd higress 16 | # 强制拉取最新的 all-in-one 镜像 17 | docker pull higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest 18 | # 启动 higress，配置文件会写到工作目录下 19 | docker run -d --rm --name higress-ai -v ${PWD}:/data \ 20 | -p 8001:8001 -p 8888:8080 -p 8443:8443 \ 21 | higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest 22 | ``` 23 | 24 | 安装完成后，在浏览器中访问 Higress Console，确认底部显示的版本号不低于 2.1.4。 25 | 26 | ### 2. 部署 Nacos 27 | 28 | 参考 Nacos 官网（[https://nacos.io)](https://nacos.io/)）部署 Nacos，版本不低于 3.0.1。推荐下载压缩包在本地用 standalone 单机模式启动的部署方式。此处不展开介绍。 29 | 30 | ### 3. 启动后端服务 31 | 32 | 1. 测试服务使用 NodeJS 编写。所以请大家先访问 NodeJS 官网（[https://nodejs.org](https://nodejs.org/en)）下载并安装 NodeJS 运行环境 33 | 2. 下载[测试服务压缩包](../files/McpSampleServer.zip) 34 | 3. 解压至任意目录 35 | 4. 执行以下命令启动测试服务 36 | ```bash 37 | npm install 38 | npm start 39 | ``` 40 | 5. 启动完成后，在浏览器访问 [http://localhost:3000/](http://localhost:3000)。若能够显示“Hello world!”，则代表服务启动成功。 41 | 42 | ## 配置流程 43 | 44 | ### Nacos 配置 45 | 46 | 1. 在浏览器中打开 Nacos 3 控制台（[http://localhost:8080/](http://localhost:8080/)） 47 | 2. 首次运行时，默认会要求配置用户名密码。请务必牢记 48 | 3. 点击左侧的“MCP管理”→“MCP列表” 49 | 5. 参考下图填写 MCP Server 信息，并发布
50 | ![new-mcp-server](../images/mcp-with-nacos3-sse/new-mcp-server.png) 51 | 6. 发布后的 MCP Server 列表如下图所示：
52 | ![mcp-server-list](../images/mcp-with-nacos3-sse/mcp-server-list.png) 53 | 54 | ### Higress 配置 55 | 56 | 1. 在浏览器中打开 Higress Console（[http://localhost:8001/](http://localhost:8001/)） 57 | 2. 首次打开时会要求配置登录信息，配置完成后登录进入 Console 主页面 58 | 3. 点击左侧的“服务来源” 59 | 4. 点击“创建服务来源”按钮 60 | 5. 参考下图填写服务来源信息
61 | ![new-service-source](../images/mcp-with-nacos3-sse/new-service-source.png) 62 | 此处要填写的认证信息就是登录 Nacos 控制台的用户名和密码 63 | 6. 点击“确定”按钮 64 | 7. 点击左侧的“服务列表”，确认列表中出现了我们刚刚创建的 MCP Server
65 | ![service-list](../images/mcp-with-nacos3-sse/service-list.png) 66 | 如果没出现，请查看文档最下方的 FAQ 67 | 8. 点击左侧的“系统设置” 68 | 9. 点击右侧链接下载模版文件，并将文件内容完整粘贴到输入框中：[文件链接](../files/higress-config.yaml) 69 | 10. 修改 `higress` 配置项中的 `mcpServer` 配置 70 | 1. 将 `enable` 改为 `true` 71 | 2. 将 `redis-address` 替换为本机的非 127.0.0.1 内网 IP 72 | 3. 修改后的配置如下图所示
73 | ![higress-config](../images/mcp-with-nacos3-sse/higress-config.png) 74 | 4. 点击“提交”按钮 75 | 5. 提交之后如果页面没有任务提示的话，可以刷新页面，确认配置为更新后的内容即可 76 | 77 | ## 测试验证 78 | 79 | 1. 在浏览器中打开 `http://localhost:8888/mcp/sample/sse` 80 | 2. 正常情况下页面显示如下图所示
81 | ![request-sse](../images/mcp-with-nacos3-sse/request-sse.png) 82 | 3. 用 curl 命令验证获取工具列表 83 | ```bash 84 | # sessionId 需要使用浏览器中返回的值 85 | curl http://localhost:8888/mcp/sample?sessionId=b9048bb9-9bed-400c-86a1-516f9f69700c \ 86 | -H 'Content-Type: application/json' \ 87 | -d '{ 88 | "jsonrpc": "2.0", 89 | "id": 1, 90 | "method": "tools/list" 91 | }' 92 | ``` 93 | 4. 正常情况下不仅终端中会返回工具列表，之前的浏览器页面上也会推送工具列表信息
94 | ![request-tools-list-1](../images/mcp-with-nacos3-sse/request-tools-list-1.png) 95 | ![request-tools-list-2](../images/mcp-with-nacos3-sse/request-tools-list-2.png) 96 | 5. 用 curl 命令验证工具调用 97 | ```bash 98 | curl http://localhost:8888/mcp/sample?sessionId=b9048bb9-9bed-400c-86a1-516f9f69700c \ 99 | -H 'Content-Type: application/json' \ 100 | -d '{ 101 | "method": "tools/call", 102 | "params": { 103 | "name": "add", 104 | "arguments": { 105 | "a": 1, 106 | "b": 2 107 | } 108 | } 109 | }' 110 | ``` 111 | 6. 正常情况下不仅终端中会返回调用结果，之前的浏览器页面上也会推送调用结果
112 | ![request-tools-call-1](../images/mcp-with-nacos3-sse/request-tools-call-1.png) 113 | ![request-tools-call-2](../images/mcp-with-nacos3-sse/request-tools-call-2.png) 114 | 115 | 116 | ### 工具验证 117 | 118 | 在完成简单验证之后，大家就可以把这个 MCP Server 配置到支持 MCP Client 的工具（如 DeepChat、Cherry Studio 等）中进行验证了。工具的 URL 为 `http://localhost:8888/mcp/sample/sse`。 119 | 120 | ## FAQ 121 | 122 | ### 1. 服务列表中没有出现我的 MCP Server 123 | 124 | 可以尝试先停止 Higress 容器，再使用开头的 `docker run` 命令在相同的目录下重新启动 Higress。 125 | 126 | ```bash 127 | docker stop higress-ai 128 | ``` 129 | 130 | 如果重启后还是没有出现的话，可以查看容器内的 `/var/log/higress/controller.log` 日志文件是否有错误信息。 131 | 132 | ### 2. 在请求 `http://localhost:8888/mcp/sample/sse` 是页面卡住 133 | 134 | 检查网关能否正常访问 Redis。可以进入容器内验证 6379 端口的连通性。 135 | 136 | ```bash 137 | docker exec -it higress-ai bash 138 | # 以下命令在容器 shell 内执行 139 | nc RedisIP 6379 140 | # 正常情况下，shell 会出现一个新行。 141 | # 输入 QUIT 并回车后，服务端会返回 +OK。 142 | # 再次回车，连接会自动断开并回到容器 shell。 143 | ``` -------------------------------------------------------------------------------- /docs/faq.md: -------------------------------------------------------------------------------- 1 | # 常见问题 2 | 3 | ## 前置阅读 4 | 5 | 基本上所有的问题都可以通过查看 Higress 各个组件的运行时日志、网关的访问日志以及核对它们的运行时配置是否符合预期来解决。理解日志所输出信息的 **“字面含义”** 是排障过程中的重中之重。 6 | 7 | - [如何查看日志？](https://higress.cn/docs/latest/ops/how-tos/view-logs/) 8 | - [如何查看运行时配置？](https://higress.cn/docs/latest/ops/how-tos/view-configs/) 9 | 10 | ## 一般问题 11 | 12 | ### 为什么我的网关本来运行正常，但重启之后就起不来了？ 13 | 14 | 原因是当前的最新配置有问题，网关加载失败。正常运行时，网关会拒绝控制面推送过来的异常配置，保留之前获取到的可用配置并继续运行。但在启动过程中，网关必须要拿到一份正常配置才能够完成启动。这时也没有可用配置的缓存了。所以异常配置会直接阻塞网关的正常启动。 15 | 16 | 解决方法：查看 gateway 的运行日志，找到加载失败的错误配置并修正。 17 | 18 | ### 为什么我的配置没有生效？ 19 | 20 | 网关的很多配置都是打包推送的。在某一类配置加载出现问题时，网关就会拒绝该类配置的推送，保留之前获取到的可用配置并继续运行。所以在同类配置中存在错误配置的情况下，哪怕后续的配置更新本身是没有问题的，网关也不会接受这些新的配置。 21 | 22 | 解决方法： 23 | 1. 查看 gateway 的运行日志，找到加载失败的错误配置并修正。 24 | 25 | 备注：如果日志太多不便于查询，在不影响业务的情况下，可以通过重启网关来清理日志。 26 | 27 | ### Higress Console 路由配置中的 Header、Query 等参数是做什么用的？ 28 | 29 | 路由配置中的域名、Path、Header、Query 都是这条路由的匹配条件，也就是说只有当请求满足这些匹配条件时，网关才会按照这条路由的各项配置对请求进行修改和转发，并执行该路由所关联的插件。 30 | 31 | ### 请求网关返回 404 怎么办？ 32 | 33 | 请查看访问日志，通过 404 状态码、请求路径等方式找到报错请求所对应的日志条目。查看其中的 `response_code_details` 字段。其不同的取值就代表不同的 404 原因。 34 | 35 | - `route_not_found`：没有找到对应的路由。需要检查路由列表，判断是否配置了能够匹配到该请求的路由规则。 36 | - 如果确认配置无误，那么可以拉取 controller 和 gateway 的运行时配置，查看配置中是否包含期望中的路由。 37 | - 如果 controller 中包含该路由但 gateway 中没有，那基本可以确定是有配置加载失败了。可以查看 gateway 的日志，找到加载失败的原因并对其进行修正。 38 | - `via_upstream`：404 是后端服务返回的。建议查看后端服务的相关日志并判断原因。 39 | 40 | ## AI 相关问题 41 | 42 | ### AI 路由相关问题 43 | 44 | 注意：AI 路由功能极大的依赖 Higress 的各类 Wasm 插件。如果你的服务器无法访问外网，经查看下方“插件相关问题”一节中的对应问题来解决在内网下载 Wasm 插件的问题。 45 | 46 | #### 我的大模型部署方式不在大模型提供方类型列表中，怎么办？ 47 | 48 | 如果你的大模型兼容 OpenAI API，那么可以直接使用“OpenAI/OpenAI兼容服务”这里类型，在下方“OpenAI服务类型”下拉框中选择“自定义服务”，并填入服务的 URL。 49 | 50 | ### MCP Server 相关问题 51 | 52 | 注意：MCP Server 功能极大的依赖 Higress 的各类 Wasm 插件。如果你的服务器无法访问外网，经查看下方“插件相关问题”一节中的对应问题来解决在内网下载 Wasm 插件的问题。 53 | 54 | #### mcpServer 配置中的 Redis 是做什么用的？ 55 | 56 | 这里的 Redis 仅在存量 REST API 服务转 MCP Server 的时候进行 SSE 会话保持使用。如果被代理服务的已经是 MCP Server，或者仅需通过 Streamable HTTP 方式来请求存量服务转化而成的 MCP Server，那么是不需要配置 Redis 的。 57 | 58 | #### 存量 API 转 MCP Server 可以使用 Streamable HTTP 方式请求，但使用 SSE 方式请求就返回 405，怎么办？ 59 | 60 | 请通过 Higress Console 的系统设置页面检查 `higress-config` ConfigMap 中 `mcpServer` 的各项配置是否已正确配置： 61 | 62 | - `enable` 需要设置为 `true` 63 | - `redis` 需要正确配置，并确认网关内可以访问。可以进入网关容器内使用 `telnet` 命令来确认端口可以正常连接。不要用 `ping`。 64 | - `match_list` 中配置的匹配规则可以覆盖到客户端请求。 65 | 66 | #### 每加一个 MCP Server 就要改一次 `match_list`，太麻烦了 67 | 68 | 可以直接使用从 Higress 2.1.5 起支持的“MCP管理”功能直接进行配置。这样就完全不需要配置 `match_list` 了（但需要的话 `redis` 还是得配）。 69 | 70 | 如果现有的“MCP管理”功能无法满足需求，那么可以考虑通过给相应的路由添加注解的方式进行配置。 71 | 72 | | 注解名称 | 注解描述 | 示例 | 73 | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | 74 | | `higress.io/mcp-server` | 是否为该路由启用 MCP Server 功能 | true | 75 | | `higress.io/mcp-server-match-rule-domains` | 等同于 `match_list` 中的 `match_rule_domain` | * | 76 | | `higress.io/mcp-server-match-rule-type` | 等同于 `match_list` 中的 `match_rule_type` | prefix | 77 | | `higress.io/mcp-server-match-rule-value` | 等同于 `match_list` 中的 `match_rule_path` | /mcp/example | 78 | | `higress.io/mcp-server-upstream-type` | 等同于 `match_list` 中的 `upstream_type`。仅当后端为使用 SSE 传输方式的 MCP Server 时需要配置，值为 `sse` | sse | 79 | | `higress.io/mcp-server-enable-path-rewrite` | 等同于 `match_list` 中的 `enable_path_rewrite`。仅当后端为使用 SSE 传输方式的 MCP Server 且要求重写请求路径时需要配置，值为 `true` | true | 80 | | `higress.io/mcp-server-path-rewrite-prefix` | 等同于 `match_list` 中的 `path_rewrite_prefix`。仅当后端为使用 SSE 传输方式的 MCP Server 且要求重写请求路径时需要配置，值为重写后的请求路径前缀 | /mcp | 81 | 82 | 编辑路由并在“附加注解”列表中添加上述注解即可。 83 | 84 | ## 插件相关问题 85 | 86 | ### 配置的插件功能不工作或非预期 87 | 88 | Higress 上所有的插件配置是打包下发的，也就是意味着如果你同时配置了 A、B 两个插件，只要有一个插件的配置加载异常，两个插件的配置都不会正常生效。 89 | 90 | 解决方法：查看 gateway 的运行日志，找到配置加载失败的插件及相关的失败原因，并修正错误的配置。 91 | 92 | 备注：如果日志太多不便于查询，在不影响业务的情况下，可以通过重启网关来清理日志。 93 | 94 | ### 网关服务器无法访问外网，怎么使用插件？ 95 | 96 | Higress 默认从公网镜像仓库来下载插件镜像。如果你的服务器无法访问外网，那么所有的插件都将不能正常工作。 97 | 98 | 解决办法： 99 | 1. 在内网部署社区开源的 [plugin-server](https://github.com/higress-group/plugin-server/)，并根据其文档修改内置插件的镜像地址。 100 | 2. 如果你已经配置了一些插件（含 AI 路由、MCP Server），这些插件配置中已经记录了默认的外网镜像地址。你需要将已有 `WasmPlugins` 资源中的 `url` 字段改为对应插件在 plugin-server 上的 URL 才行。如果你使用的是容器方式来部署的 Higress，请查看此文档了解修改各种资源配置的方法：[链接](./standalone-crs.md) 101 | 102 | ### 插件请求 API 或 Redis 要怎么配，为什么会遇到 `bad argument` 错误？ 103 | 104 | 这里 `bad argument` 错误在绝大部分场景下都是由于配置了网关并不知晓的服务信息。 105 | 106 | Wasm 插件只能请求网关拿到的 Cluster 信息，也就是 Higress Console 的服务列表页面所列出的服务，而不能直接指定目标服务的地址和端口来请求。 107 | 108 | 针对要通过 IP 或域名访问的服务，我们需要为其创建对应的服务来源，然后到服务列表中查看它所对应的服务名称和服务端口。这两个信息也是我们需要写入 Wasm 插件的配置里的。其中固定地址类型的服务来源所生成服务的端口固定为 80，请务必注意。 109 | 110 | 针对 K8s 内的 Service，由于 Higress 默认只会下发关联了路由的 K8s 服务，所以可以为要调用的服务创建一个路由，通过配置一些特殊的匹配规则使其并不会有任何请求匹配到它即可。 111 | 112 | ### 为什么 WasmPlugin 配置里的镜像地址都已经改了，网关还在去官方仓库下载 mcp-server 插件？ 113 | 114 | 这种问题一般发生于网关对接了 Nacos 3.x 的 MCP Server 功能后。请查看文档：[链接](https://higress.cn/docs/latest/ops/how-tos/builtin-plugin-url/#%E5%AF%B9%E6%8E%A5-nacos-3x-%E6%89%80%E7%94%9F%E6%88%90%E7%9A%84-mcp-server-%E6%8F%92%E4%BB%B6%E5%9C%B0%E5%9D%80%E9%85%8D%E7%BD%AE) 115 | 116 | ## 常见错误 117 | 118 | ### 使用 `127.0.0.1` 来配置网关要访问的服务 119 | 120 | 在网关的各项配置中，除非 100% 确定，请不要使用 `127.0.0.1` 这个 loopback IP。因为当网关访问这个 IP 时，实际被访问的是网关自己，而不是网关容器所在的宿主机。请使用其他网关可以正常访问的 IP 进行配置。 121 | 122 | ### 使用 `ping` 来检查后端服务的连通性 123 | 124 | `ping` 用的是 ICMP 协议，而网关转发请求用的是 TCP 协议。能 `ping` 通不代表目标服务的地址和端口可以连接。请使用 `telnet` 或 `nc` 命令进行检查。 -------------------------------------------------------------------------------- /docs/mcp-with-nacos3.md: -------------------------------------------------------------------------------- 1 | # 如何让 Higress 对接 Nacos 3 MCP Server 管理功能（HTTP 服务版） 2 | 3 | ## 概述 4 | 5 | 本文将介绍在 Nacos 3 上配置 MCP Server，将一个 HTTP Web Service 通过 Higress 暴露给 MCP Client 访问的完整过程。整个流程将基于一个测试用的简单后端服务实现进行。所有的配置内容也均以此服务所提供的功能为模版编写。建议大家先严格按照本文的步骤配置完成后再尝试自行调整配置对接其他服务。 6 | 7 | ## 环境准备 8 | 9 | ### 1. 部署 Higress 10 | 11 | 在本地使用 all-in-one 镜像方式启动 Higress： 12 | 13 | ```bash 14 | # 创建一个工作目录 15 | mkdir higress; cd higress 16 | # 强制拉取最新的 all-in-one 镜像 17 | docker pull higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest 18 | # 启动 higress，配置文件会写到工作目录下 19 | docker run -d --rm --name higress-ai -v ${PWD}:/data \ 20 | -p 8001:8001 -p 8888:8080 -p 8443:8443 \ 21 | higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest 22 | ``` 23 | 24 | 安装完成后，在浏览器中访问 Higress Console，确认底部显示的版本号不低于 2.1.4。 25 | 26 | ### 2. 部署 Nacos 27 | 28 | 参考 Nacos 官网（[https://nacos.io)](https://nacos.io/)）部署 Nacos，版本不低于 3.0.1。推荐下载压缩包在本地用 standalone 单机模式启动的部署方式。此处不展开介绍。 29 | 30 | ### 3. 部署 Redis 31 | 32 | 在本地启动一个 Redis 实例。推荐使用 Docker 方式： 33 | 34 | ```bash 35 | docker run --rm --name redis -p 6379:6379 higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/redis-stack-server:7.4.0-v3 36 | ``` 37 | 38 | ### 4. 启动后端服务 39 | 40 | 1. 测试服务使用 NodeJS 编写。所以请大家先访问 NodeJS 官网（[https://nodejs.org](https://nodejs.org/en)）下载并安装 NodeJS 运行环境 41 | 2. 下载[测试服务压缩包](../files/McpSampleServer.zip) 42 | 3. 解压至任意目录 43 | 4. 执行以下命令启动测试服务 44 | ```bash 45 | npm install 46 | npm start 47 | ``` 48 | 5. 启动完成后，在浏览器访问 [http://localhost:3000/](http://localhost:3000)。若能够显示“Hello world!”，则代表服务启动成功。 49 | 50 | ## 配置流程 51 | 52 | ### Nacos 配置 53 | 54 | 1. 在浏览器中打开 Nacos Console（[http://nacos-server-ip:8080/](http://nacos-server-ip:8080/)） 55 | 3. 点击左侧的“MCP管理”→“MCP列表” 56 | 4. 点击“创建 MCP Server”按钮 57 | 5. 参考下图填写 MCP Server 信息，并发布
58 | ![new-mcp-server](../images/mcp-with-nacos3/new-mcp-server.png) 59 | 6. 点击刚刚创建的 MCP Server 右侧的“编辑”链接 60 | 7. 将“服务版本”修改改为 1.0.1 61 | 7. 点击下方“Tools”右侧的“添加”按钮 62 | 8. 参考下图配置 Tool 的元信息
63 | ![tool-meta](../images/mcp-with-nacos3/tool-meta.png) 64 | 注意：添加参数时需要先选中“参数列表”，然后才能点击它上方的“添加参数”按钮 65 | 10. 在“协议转化配置”中填入以下信息 66 | `{"requestTemplate":{"method":"GET","url":"/add","argsToUrlParam":true},"responseTemplate":{"body":"Result: {{ .result }}"}}` 67 | 11. 点击“确定”保存 Tool 信息 68 | 12. 点击“发布为最新版本” 使 Tool 配置生效
69 | ![mcp-server-list](../images/mcp-with-nacos3/mcp-server-list.png) 70 | 71 | ### Higress 配置 72 | 73 | 1. 在浏览器中打开 Higress Console（[http://localhost:8001/]） 74 | 2. 首次打开时会要求配置登录信息，配置完成后登录进入 Console 主页面 75 | 3. 点击左侧的“服务来源” 76 | 4. 点击“创建服务来源”按钮 77 | 5. 参考下图填写服务来源信息
78 | ![new-service-source](../images/mcp-with-nacos3/new-service-source.png) 79 | 此处要填写的认证信息就是登录 Nacos 控制台的用户名和密码 80 | 6. 点击“确定”按钮 81 | 7. 点击左侧的“服务列表”，确认列表中出现了我们刚刚创建的 MCP Server
82 | ![service-list](../images/mcp-with-nacos3/service-list.png) 83 | 如果没出现，请查看文档最下方的 FAQ 84 | 8. 点击左侧的“系统设置” 85 | 9. 点击右侧链接下载模版文件，并将文件内容完整粘贴到输入框中：[文件链接](../files/higress-config.yaml) 86 | 10. 修改 `higress` 配置项中的 `mcpServer` 配置 87 | 1. 将 `enable` 改为 `true` 88 | 2. 将 `redis-address` 替换为本机的非 127.0.0.1 内网 IP 89 | 3. 修改后的配置如下图所示
90 | ![higress-config](../images/mcp-with-nacos3/higress-config.png) 91 | 4. 点击“提交”按钮 92 | 5. 提交之后如果页面没有任务提示的话，可以刷新页面，确认配置为更新后的内容即可 93 | 94 | ## 测试验证 95 | 96 | 1. 在浏览器中打开 `http://localhost:8888/mcp/sample/sse` 97 | 2. 正常情况下页面显示如下图所示
98 | ![request-sse](../images/mcp-with-nacos3/request-sse.png) 99 | 3. 用 curl 命令验证获取工具列表 100 | ```bash 101 | # sessionId 需要使用浏览器中返回的值 102 | curl http://localhost:8888/mcp/sample?sessionId=b9048bb9-9bed-400c-86a1-516f9f69700c \ 103 | -H 'Content-Type: application/json' \ 104 | -d '{ 105 | "jsonrpc": "2.0", 106 | "id": 1, 107 | "method": "tools/list" 108 | }' 109 | ``` 110 | 4. 正常情况下不仅终端中会返回工具列表，之前的浏览器页面上也会推送工具列表信息
111 | ![request-tools-list-1](../images/mcp-with-nacos3/request-tools-list-1.png) 112 | ![request-tools-list-2](../images/mcp-with-nacos3/request-tools-list-2.png) 113 | 5. 用 curl 命令验证工具调用 114 | ```bash 115 | curl http://localhost:8888/mcp/sample?sessionId=b9048bb9-9bed-400c-86a1-516f9f69700c \ 116 | -H 'Content-Type: application/json' \ 117 | -d '{ 118 | "method": "tools/call", 119 | "params": { 120 | "name": "add", 121 | "arguments": { 122 | "a": 1, 123 | "b": 2 124 | } 125 | } 126 | }' 127 | ``` 128 | 6. 正常情况下不仅终端中会返回调用结果，之前的浏览器页面上也会推送调用结果
129 | ![request-tools-call-1](../images/mcp-with-nacos3/request-tools-call-1.png) 130 | ![request-tools-call-2](../images/mcp-with-nacos3/request-tools-call-2.png) 131 | 132 | 133 | ### 工具验证 134 | 135 | 在完成简单验证之后，大家就可以把这个 MCP Server 配置到支持 MCP Client 的工具（如 DeepChat、Cherry Studio 等）中进行验证了。工具的 URL 为 `http://localhost:8888/mcp/sample/sse`。 136 | 137 | ## FAQ 138 | 139 | ### 1. 服务列表中没有出现我的 MCP Server 140 | 141 | 可以尝试先停止 Higress 容器，再使用开头的 `docker run` 命令在相同的目录下重新启动 Higress。 142 | 143 | ```bash 144 | docker stop higress-ai 145 | ``` 146 | 147 | 如果重启后还是没有出现的话，可以查看容器内的 `/var/log/higress/controller.log` 日志文件是否有错误信息。 148 | 149 | ### 2. 在请求 `http://localhost:8888/mcp/sample/sse` 时页面卡住 150 | 151 | 检查网关能否正常访问 Redis。可以进入容器内验证 6379 端口的连通性。 152 | 153 | ```bash 154 | docker exec -it higress-ai bash 155 | # 以下命令在容器 shell 内执行 156 | nc RedisIP 6379 157 | # 正常情况下，shell 会出现一个新行。 158 | # 输入 QUIT 并回车后，服务端会返回 +OK。 159 | # 再次回车，连接会自动断开并回到容器 shell。 160 | ``` 161 | 162 | ### 3. 在请求 `http://localhost:8888/mcp/sample/sse` 时返回 405 163 | 164 | 检查上方“Higress 配置”一节中提到的“系统设置”部分是否正确配置了。 165 | 166 | 如果配置无误，可以参考官网关于“查看运行时配置”的文档获取 gateway 的运行时配置，在其中搜索 `mcp-session`，并检查相应 filter 中 gateway 获取到的配置与前面在 console 上写入的配置是否一致。如果二者不一致，则需要进一步检查 controller 和 pilot 的运行时配置，确认配置不一致的源头，进而检查相应组件的日志，判断问题发生的原因。 167 | 168 | ### 4. 在请求 `http://localhost:8888/mcp/sample/sse` 时返回 404 169 | 170 | 查看访问日志（access log），在其中找到对应 404 请求的记录，根据 `response_code_details` 中记录的原因进行分析。 171 | 172 | #### route_not_found 173 | 174 | 查看 controller 的日志，检查是否有与 Nacos 通信相关的错误。 175 | 176 | #### via_upstream 177 | 178 | 查看访问日志中的 `route_name` 和 `upstream_host`，确认是否命中了期望的路由和后端服务器。 179 | 180 | 如果命中正确，那请检查后端服务器是否可以正确处理相应的请求，或者是否在 Nacos 中为其添加的 Tools 配置存在错误。 181 | 182 | 如果命中错误，那么请检查请求的 URL 是否正确，是否与 Nacos 中配置的 MCP Server 相匹配，以及 Nacos 中与 MCP Server 关联的服务信息是否正确。 183 | 184 | ## 参考文档 185 | 186 | - 如何查看日志：https://higress.cn/docs/latest/ops/how-tos/view-logs/ 187 | - 如何查看运行时配置：https://higress.cn/docs/latest/ops/how-tos/view-configs/ --------------------------------------------------------------------------------