Higress on WYF 的技术博客

Higress 01：key-auth 插件本地 Docker 部署与运行机制指南

Thu, 17 Sep 2026 22:15:51 +0800

目标：不依赖 Kubernetes，只用 Docker 在本地完整复现 “McpBridge + Ingress + WasmPlugin(key-auth)” 三件套的运行效果（401 / 403 / 200 / 404），并讲清背后的原理。

本文所有操作已在 macOS + Docker Desktop 上实测通过（2026-09-17）。

一、背景：要复现的原配置

原始配置是三个 K8s 资源（完整内容见 citic-wasm-plugin/key-auth/keyauth.yaml）：

资源	作用	关键内容
`McpBridge mcp-keyauth-httpbin`	把集群外的 `httpbin.org:80` 注册进网关，服务名为 `httpbin.dns`	`type: dns`，网关周期性做 DNS 解析得到 IP 池
`Ingress ingress-keyauth-httpbin`	路由规则：`Host: httpbin.example.com` 的流量全部转发到 `httpbin.dns`	`higress.io/destination`、`upstream-vhost`、`backend-protocol` 三个注解
`WasmPlugin wasm-keyauth-httpbin`	在该 Ingress 上启用 key-auth 认证	2 个 consumer，只放行 `consumer1`；从 `x-api-key` / `apikey` 头取 Key

引用关系：Ingress.backend.resource → McpBridge 名；annotations.higress.io/destination → name.type（httpbin.dns）；WasmPlugin.matchRules[].ingress → Ingress 名。

二、总体方案与架构

K8s 里这套东西最终也是由 Higress 控制面翻译成 Envoy 配置下发的。所以我们绕过控制面，直接手写等价的 Envoy 静态配置，用 Docker 跑数据面：

1
2
3
4
5
6
7


┌─────────┐ curl -H "Host: httpbin.example.com" ┌──────────────────────────────┐ ┌──────────────────┐
│ 终端 │ ──────────── localhost:10000 ──────────▶ │ envoy 容器 (higress/gateway) │ ───▶ │ httpbin 容器 │
│ (curl) │ ◀────────────── 401/403/200 ──────────── │ ┌────────────────────────┐ │ │ go-httpbin :8080 │
└─────────┘ │ │ key-auth wasm 插件 │ │ │ （代替 httpbin.org）│
 │ │ (本地 Go 源码编译) │ │ └──────────────────┘
 │ └────────────────────────┘ │
 └──────────────────────────────┘

相比原方案的两处替换：

上游替换：httpbin.org（公网）→ 本地 mccutchen/go-httpbin 容器。行为等价（都是请求回显服务），且不依赖外网。
控制面替换：McpBridge/Ingress/WasmPlugin 三个 CRD → 一份 envoy.yaml。三者的语义被完整保留（域名匹配、路由名、插件配置、allow 白名单）。

所有文件在 key-auth-docker-demo/ 目录：

1
2
3
4
5


key-auth-docker-demo/
├── docker-compose.yaml # 两个容器：envoy + httpbin
├── envoy.yaml # 等价于三个 CRD 的 Envoy 静态配置
├── plugin.wasm # 用 golang:1.24 容器从本仓库 Go 源码编译
└── test.sh # 5 个场景的验证脚本

2.1 与官方独立部署方式的关系（先读这里）

Higress 官方文档提供了三种"脱离/本地化 K8s"的部署方式，它们和本文方案不是一回事，定位不同：

方式	组件规模	配置方式	适用场景	官方文档
All-in-One 单容器	1 个容器（gateway+console 打包）	控制台 UI / 本地 `/data` 卷	快速体验完整网关功能	deploy-by-docker↗
Docker Compose 独立部署	apiserver + controller + pilot + gateway + console（可选内置 nacos、Prometheus/Loki/Grafana 监控套件），约 12 个容器	控制台 UI / 模拟 K8s API / 本地配置文件	接近真实架构的本地测试	deploy-by-docker-compose↗
本地 K8s（kind）+ Helm	完整云原生模式	`kubectl apply` CRD（本文开头那份 YAML 可直接用）	与生产完全一致的验证	quickstart↗
本文方案：裸数据面	2 个容器（envoy + httpbin）	手写 `envoy.yaml`	只关心插件本身的行为和原理，最轻最快	本文

本文方案可以理解成：把官方架构中 pilot 最终下发给 gateway 的那份 Envoy 配置"手写"了出来，只跑数据面，不跑控制面。对"验证 key-auth 插件的认证行为（401/403/200）“这个目的来说，2 个镜像、一条 docker compose up -d 就够了。

官方两种方式的核心命令（引自官方文档，供需要完整控制台时使用）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 方式一：All-in-One 单容器（控制台 8001，网关 8080/8443，配置存到当前目录）
mkdir higress; cd higress
docker run -d --rm --name higress-ai -v ${PWD}:/data \
 -p 8001:8001 -p 8080:8080 -p 8443:8443 \
 higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest

# 方式二：Docker Compose 多组件独立部署
curl -fsSL https://higress.io/standalone/get-higress.sh | bash -s -- [安装目录] [选项]
# 常用选项：-a 装完自动启动；--use-builtin-nacos 用内置配置中心；
# -c file://<绝对路径> 用本地文件存配置；--console-port=8001 改控制台端口（默认 8080）

实测备注（2026-09-17 本机实际尝试过 compose 独立部署后的经验，供参考）：

重：约 12 个镜像（apiserver、controller、pilot、gateway、console、plugin-server、nacos、prometheus、loki、grafana 等），首次安装拉取超过 30 分钟；日常验证插件没必要。
-c file:///opt/higress/conf 默认会把配置写到宿主机 /opt/higress（macOS 上直接 Permission denied），要改成工作区内的绝对路径。
安装脚本内部用 docker compose -p higress 管理容器；如果自己在 compose/ 目录里手动执行 docker compose 而不带 -p higress，会另建一套 compose-* 前缀的重复容器并抢 80 端口报错。
一个利好：compose 部署内置 plugin-server 容器，自带 key-auth 2.0.0 等官方插件，WasmPlugin.url 直接写 http://plugin-server:8080/plugins/key-auth/2.0.0/plugin.wasm 即可，不需要自己编译 wasm——但那样跑的就不是本仓库的代码了。
卸载干净的方法：安装目录下 bash bin/reset.sh（停容器、删数据卷），再删安装目录和镜像。

结论：想体验控制台和完整控制面 → 用上面官方方式；想验证/调试本仓库的插件代码、搞清楚数据面到底发生了什么 → 用本文方案。

三、原理介绍

3.1 WASM 插件是怎么跑起来的

Higress 的数据面是 Envoy 的一个 fork。Envoy 内置 envoy.filters.http.wasm 过滤器，可以把一个 .wasm 文件加载进 V8 运行时，作为 HTTP 过滤器链的一环执行。
插件本身是用 Go 写的（citic-wasm-plugin/key-auth/main.go），基于 higress-group/proxy-wasm-go-sdk，通过 GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared 编译成 wasm。
插件通过 wrapper.SetCtx("key-auth", ...) 注册三类回调：
- ParseOverrideConfigBy(parseGlobalConfig, parseOverrideRuleConfig) — 插件启动/配置变更时解析配置
- ProcessRequestHeadersBy(onHttpRequestHeaders) — 每个请求到达时执行认证判断
请求流程：Envoy 收到请求 → 路由匹配（host + path）→ 执行 wasm 过滤器（key-auth 认证）→ 认证通过则转发给上游 cluster，并把 X-Mse-Consumer: <consumer名> 头注入给上游；不通过则由插件直接返回本地响应（401/403），请求根本不会到达上游。

插件里发回本地响应用的是 proxywasm.SendHttpResponseWithDetail（main.go:329-345），同时带上 WWW-Authenticate: Key realm=MSE Gateway 响应头——这就是实测输出里 www-authenticate: Key realm=MSE Gateway 的来源。

3.2 Proxy-Wasm ABI 与 0_2_100 的坑

Envoy 与 wasm 插件之间通过 Proxy-Wasm ABI（一组以 proxy_ 开头的导入/导出函数）通信。Envoy 加载 wasm 时会检查模块导出的 ABI 版本号函数：

官方 Envoy 认 proxy_abi_version_0_2_1
用官方 C++ SDK 编译的插件（如官方镜像 plugins/key-auth:1.0.0 里的 wasm）导出的就是 proxy_abi_version_0_2_1
但 Higress 的 Go SDK fork 导出的是 proxy_abi_version_0_2_100（Higress 私有扩展 ABI，增加了 redis 调用等能力）

验证方法（无需反编译器，strings 即可）：

1
2
3


strings plugin.wasm | grep proxy_abi
# Go 编译（本仓库源码）: proxy_abi_version_0_2_100
# 官方 C++ 编译镜像: proxy_abi_version_0_2_1

结论：Go 源码编译的 key-auth 插件只能跑在 Higress fork 的 Envoy 上。如果挂载到官方 envoyproxy/envoy，启动即失败：

1
2
3


[error][wasm] Wasm VM failed Missing or unknown Proxy-Wasm ABI version
[critical][wasm] Plugin key-auth failed to load
[critical][main] error initializing config '/etc/envoy/envoy.yaml': Unable to create Wasm plugin key-auth

所以本方案使用 higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway:v2.2.4（内含 Envoy 1.36.4 的 Higress fork），通过覆盖 entrypoint 直接裸跑 envoy：

1

entrypoint: ["/usr/local/bin/envoy", "-c", "/etc/envoy/envoy.yaml", "--concurrency", "1"]

3.3 key-auth 插件的认证逻辑

核心逻辑在 main.go 的 onHttpRequestHeaders（main.go:239）。插件行为由两个变量决定：

global_auth：全局配置里的开关（true / false / 未设置，三种状态）
当前路由是否配置了 allow 列表（即 matchRules 是否命中当前路由）

决策真值表：

global_auth	当前路由有 allow	行为
true	否	全局限流：所有 consumer 的 Key 都可用
true	是	只有 allow 列表里的 consumer 可用
false	否	直接放行，不认证
false	是	只有 allow 列表里的 consumer 可用
未设置	全部路由都没配	退化为全局认证
未设置	至少一个路由配了	等价于 false：没配的路由放行，配了的路由按 allow 校验

本次复现的配置是 global_auth: false + 路由配 allow: [consumer1]，即上表第 4 行。

取 Key 与判定顺序（main.go:259-326）：

按 keys 列表从 Header（in_header: true）或 URL query（in_query: true）取 token
取到多个 token → 401（deniedMultiKeyAuthData）
一个都没取到 → 401（deniedNoKeyAuthData，body: No Key Authentication information found）
token 在 consumers 里查不到 → 403（deniedUnauthorizedConsumer，body: Unauthorized consumer）
查到 consumer 后先注入 X-Mse-Consumer: <name> 头，再检查是否在 allow 列表：
- 不在 → 403（deniedUnauthorizedConsumer）
- 在 → 放行，请求转发上游

⚠️ 注意：假 Key 和"不在白名单的有效 Key"都是 403，只有"完全不带 Key"或"带多个 Key"才是 401。原 YAML 讲解文档里说假 Key 返回 401 是不准确的，以源码和实测为准。

3.4 规则匹配：rules 与 match_route

K8s 里 WasmPlugin.matchRules[].ingress: [ingress-keyauth-httpbin] 经控制面翻译后，落到 wasm 插件配置里是：

1

"_rules_": [{"_match_route_": ["<路由名>"], "allow": ["consumer1"]}]

wasm-go SDK 的 wrapper 在每次请求时取 Envoy 的 route_name 属性，和 _match_route_ 列表比对：命中则用该条规则的配置（覆盖全局配置中的 allow），不命中则用全局配置。

因此在裸 Envoy 配置里，我们只要给路由起个名字（name: keyauth-route），并在插件配置里写 _match_route_: ["keyauth-route"]，就等价复现了 matchRules 的语义。

3.5 与原 YAML 的字段对应关系

原 YAML 字段	envoy.yaml 中的等价物
`Ingress rules[0].host: httpbin.example.com`	`virtual_hosts[].domains: ["httpbin.example.com"]`
`path: /` + `pathType: Prefix`	`routes[].match.prefix: /`
`McpBridge`（httpbin.org:80, type: dns）	`clusters[].name: httpbin` + `STRICT_DNS` 指向本地 httpbin 容器
`higress.io/upstream-vhost: httpbin.org`	本地回显服务不校验 Host，省略；真实场景对应 `host_rewrite_literal`
`matchRules[].ingress`	路由命名 `keyauth-route` + 插件配置 `_match_route_`
`defaultConfig`（consumers/keys/in_header/global_auth）	插件 JSON 配置的同名字段
`matchRules[].config.allow: [consumer1]`	`_rules_[0].allow: ["consumer1"]`

envoy.yaml 中插件配置的完整 JSON（即 defaultConfig + matchRules 合并后的结果）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
 "consumers": [
 {"name": "consumer1", "credential": "2bda943c-ba2b-11ec-ba07-00163e1250b5"},
 {"name": "consumer2", "credential": "c8c8e9ca-558e-4a2d-bb62-e700dcc40e35"}
 ],
 "keys": ["x-api-key", "apikey"],
 "in_header": true,
 "global_auth": false,
 "_rules_": [
 {"_match_route_": ["keyauth-route"], "allow": ["consumer1"]}
 ]
}

四、搭建步骤（从零开始）

4.1 准备镜像

1
2
3
4
5
6
7
8


# Higress gateway（含支持 Go 插件 ABI 的 Envoy fork）
docker pull higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/gateway:v2.2.4

# 本地回显服务
docker pull mccutchen/go-httpbin:latest

# 编译用的 golang 镜像
docker pull golang:1.24

docker.io 不通时可走镜像加速器，例如 DaoCloud： docker pull docker.m.daocloud.io/library/golang:1.24 && docker tag docker.m.daocloud.io/library/golang:1.24 golang:1.24。注意 mccutchen/go-httpbin 不在 DaoCloud 白名单内，需直连 docker.io 或开代理；阿里云 registry（higress-registry.cn-hangzhou.cr.aliyuncs.com）国内直连无压力。

4.2 编译 plugin.wasm

用 Docker 编译本仓库的 Go 源码，不污染本地 Go 环境：

1
2
3
4
5
6
7
8
9


cd citic-wasm-plugin/key-auth
docker run --rm \
 -v "$PWD:/src" -w /src \
 -v gomodcache:/go/pkg/mod -v gocache:/root/.cache/go-build \
 -e GOOS=wasip1 -e GOARCH=wasm -e GOPROXY=https://goproxy.cn,direct \
 golang:1.24 go build -buildmode=c-shared -o plugin.wasm .

# 拷贝到部署目录（compose 里挂载的是 key-auth-docker-demo/plugin.wasm）
cp plugin.wasm ../../key-auth-docker-demo/

产物约 5.4MB。gomodcache/gocache 两个 named volume 用于缓存依赖，二次编译会快很多。

备选：也可以直接从官方 OCI 镜像提取预编译 wasm（注意是 C++ 版本，ABI 为 0_2_1，可跑在官方 Envoy 上，但拒绝响应的文案与 Go 版不同）：

1
2
3
4
5


TOKEN=$(curl -s "https://dockerauth.cn-hangzhou.aliyuncs.com/auth?service=registry.aliyuncs.com:cn-hangzhou:china:cri-r0xfyoxudmtseqq7&scope=repository:plugins/key-auth:pull" \
 | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")
# 先 GET /v2/plugins/key-auth/manifests/1.0.0 找到 wasm 层的 digest，再：
curl -sL -H "Authorization: Bearer $TOKEN" -o plugin.wasm \
 "https://higress-registry.cn-hangzhou.cr.aliyuncs.com/v2/plugins/key-auth/blobs/<digest>"

4.3 编写配置

envoy.yaml 和 docker-compose.yaml 已就绪（见 key-auth-docker-demo/），关键点：

监听 0.0.0.0:10000，宿主机映射 10000:10000
admin 开在 9901 端口（可选，用于看配置和统计）
wasm 过滤器配置中 runtime: envoy.wasm.runtime.v8，code.local.filename: /etc/envoy/plugin.wasm
plugin.wasm 以只读方式挂载进容器

4.4 启动与验证

1
2
3
4
5
6
7
8


cd key-auth-docker-demo
docker compose up -d

# 确认插件加载成功
docker compose logs envoy | grep "plugin start successfully"

# 跑全部验证场景
bash test.sh

五、验证结果（实测输出）

① 不带 Key → 401

1
2
3
4
5


HTTP/1.1 401 Unauthorized
www-authenticate: Key realm=MSE Gateway
server: envoy

Request denied by Key Auth check. No Key Authentication information found.

② consumer1 的 Key（在白名单）→ 200

1
2
3


curl -s -i -H "Host: httpbin.example.com" \
 -H "x-api-key: 2bda943c-ba2b-11ec-ba07-00163e1250b5" \
 http://localhost:10000/get

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


HTTP/1.1 200 OK
server: envoy
x-envoy-upstream-service-time: 16

{
 "headers": {
 "Host": ["httpbin.example.com"],
 "X-Mse-Consumer": ["consumer1"], ← 插件注入，证明上游收到了认证身份
 ...
 }
}

③ consumer2 的 Key（有效但不在 allow）→ 403

1
2
3
4


HTTP/1.1 403 Forbidden
www-authenticate: Key realm=MSE Gateway

Request denied by Key Auth check. Unauthorized consumer.

④ 假 Key → 403（不是 401！）

1
2
3


HTTP/1.1 403 Forbidden

Request denied by Key Auth check. Unauthorized consumer.

credential 在 consumers 里查不到，与"不在白名单"走同一个分支（main.go:288-292）。

⑤ Host 不匹配 → 404

1

curl -s -i http://localhost:10000/get # 不带 Host 头

`1`	`HTTP/1.1 404 Not Found`

请求根本没命中 httpbin.example.com 这个 virtual host，路由不存在，与插件无关。

六、踩坑记录

官方 Envoy 加载不了 Go 编译的插件：报 Missing or unknown Proxy-Wasm ABI version。原因是 Higress Go SDK 导出 proxy_abi_version_0_2_100，官方 Envoy 只认 0_2_1。解法：换 higress/gateway 镜像。（详见 3.2）
docker pull OCI wasm 插件镜像报 unsupported media type application/vnd.oci.empty.v1+json：wasm 插件镜像是 FROM scratch + OCI 空层的纯 artifact，Docker 旧存储驱动不支持。解法：要么在 Docker Desktop 设置里启用 containerd 存储，要么绕过 daemon 直接 curl registry API 下载 blob（见 4.2 备选方案）。
docker.io 拉取超时：国内直连 docker.io 经常不通。阿里云 registry 不受影响；其余镜像走加速器或代理。
原始文档的错误：网上流传的该 YAML 讲解中"假 Key 返回 401"的说法与 Go 实现不符，实际是 403。读插件源码（main.go 的四个 denied* 函数）是最可靠的事实来源。

七、常用命令速查

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


cd key-auth-docker-demo

docker compose up -d # 启动
docker compose down # 停止并删除容器
docker compose restart envoy # 改了 envoy.yaml / 插件配置后重启
docker compose logs -f envoy # 看日志（含插件日志，如 consumer "consumer1" authenticated）
bash test.sh # 一键跑 5 个验证场景

# 修改插件代码后重新编译（在仓库根目录执行）
cd citic-wasm-plugin/key-auth && docker run --rm -v "$PWD:/src" -w /src \
 -v gomodcache:/go/pkg/mod -v gocache:/root/.cache/go-build \
 -e GOOS=wasip1 -e GOARCH=wasm -e GOPROXY=https://goproxy.cn,direct \
 golang:1.24 go build -buildmode=c-shared -o plugin.wasm . \
 && cp plugin.wasm ../../key-auth-docker-demo/ && cd ../../key-auth-docker-demo \
 && docker compose restart envoy

# envoy admin 接口（调试）
curl localhost:9901/config_dump | python3 -m json.tool | head -50
curl localhost:9901/stats | grep wasm

附：单元测试路线（不需要 Docker）

如果只想快速验证插件逻辑的正确性，不追求真实 HTTP 效果，可以直接跑仓库里自带的单元测试（main_test.go，基于 wasm-go 的 host 模拟框架，wazero 在进程内跑 wasm，不需要 Docker）：

1
2


cd citic-wasm-plugin/key-auth
go test ./... -v

它覆盖了配置解析（合法/非法配置）、Header/Query 取 Key、401/403 分支、X-Mse-Consumer 注入等场景。但它验证的是"插件内部逻辑”，而不是"网关端到端行为"——后者还是要靠本文的 Docker 方案。

Higress 02：key-auth 插件原理与代码导读（结合 docker demo 实战）

Thu, 17 Sep 2026 22:15:51 +0800

导读对象有两份，对照着看：

代码：citic-wasm-plugin/key-auth/main.go（364 行，Higress 官方 key-auth 移植版）

Demo：higress/key-auth-docker-demo/（docker-compose.yaml + envoy.yaml + plugin.wasm + test.sh）

Demo 的价值：它绕开 K8s 和 Higress 控制面，用裸 Envoy 直接加载插件，于是"插件挂在哪、配置长什么样、每个分支对应什么现象"全部看得见摸得着。读完这两份，Wasm 插件从部署到代码的整条链路就通了。

第 1 章是所有 Higress Wasm 插件通用的运行原理，提炼自《ai-security-guard插件实现原理.md》的 §2~§4、§13——原理是相通的，这里做了 key-auth 视角的对照改写；两篇文档互为补充。

0. Demo 全景：一条请求的全部旅程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


curl → localhost:10000
 │
 ▼ docker-compose 里的两个容器
 ┌─────────────────────────────────────────┐
 │ envoy 容器（higress/gateway:v2.2.4） │
 │ 监听 :10000 │
 │ listener → HttpConnectionManager │
 │ → 路由匹配（Host + 路径） │
 │ → wasm filter（加载 plugin.wasm）★ │ ← key-auth 代码在这里跑
 │ → router filter │
 │ → 转发到 cluster httpbin │
 └───────────────┬─────────────────────────┘
 ▼
 ┌─────────────────────────────────────────┐
 │ httpbin 容器（go-httpbin，:8080） │ ← 后端，回显请求信息
 └─────────────────────────────────────────┘

四个文件各管一件事：

文件	作用
`docker-compose.yaml`	起两个容器，把 envoy.yaml 和 plugin.wasm 挂进 envoy 容器，10000 端口暴露给宿主机
`envoy.yaml`	Envoy 的全部配置：监听、路由、wasm filter 及其配置、后端 cluster
`plugin.wasm`	key-auth 的编译产物（`GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared`）
`test.sh`	5 个 curl 场景，每个对应代码里一个分支

1. Wasm 插件通用运行原理（与 ai-security-guard 相通）

本章机制对所有 Higress Wasm 插件都成立。每节分「通俗理解」与「技术实现」两层，技术实现层都给出 key-auth 的具体对照。

1.1 地基：沙箱、hostcall 与"每线程一个 VM"

通俗理解

Higress 的数据面是 Envoy，给它加功能传统上要改 C++ 源码重新编译——门槛高、风险大。Wasm（WebAssembly）换了个思路：插件编译成 .wasm 二进制，运行在 Envoy 内部的沙箱虚拟机里。

打个比方：Envoy 是一栋大楼，Wasm 插件是楼里的"租客"——住在隔音隔热的房间里（沙箱），崩溃不会拖垮大楼，也不能随便动楼里的东西；但大楼给租客留了一部服务电话，想做什么就打电话让前台代办。这部电话就是 hostcall（宿主调用）。

还要注意：大楼里有很多前台窗口（Envoy 多 worker 线程），每个窗口都配一个一模一样的租客（每线程一个独立 Wasm VM）。所以插件不能指望"上一次请求存在内存里的东西这次还在"——你可能换了窗口、换了租客。这就是插件里不能存跨请求全局状态的原因。

技术实现

plugin.wasm 作为 Envoy 的 Http Filter 加载，Envoy 每个 worker 线程实例化一个 Wasm VM 执行它。demo 里 envoy 启动参数带 --concurrency 1（单线程），就是排除多 VM 副本的干扰。

插件的一切能力来自 proxy-wasm ABI 的 hostcall。key-auth 只用了 3 个，是"最瘦"的一类插件：

插件想干什么	hostcall	代码位置
读请求头（取 token）	`GetHttpRequestHeader`	main.go:263
注入消费者头	`AddHttpRequestHeader`	main.go:294
直接给客户端回拒绝响应	`SendHttpResponseWithDetail`	main.go:330

对照 ai-security-guard，它还需要 GetHttpRequestBody（读 body）、DispatchHttpCall（外呼安全服务）、ResumeHttpRequest（异步放行）、InjectEncodedDataToFilterChain（流式注入）等——插件要干的事越多，用到的 hostcall 越多。

跨请求状态的处理原则：要么不存，要么建在配置期。credential2Name（main.go:130）这种"配置不变它就不变"的表，在 parseGlobalConfig 时每个 VM 各建一份；而请求级状态（本次认出的 consumer 名）不落 VM 内存，而是注入 X-Mse-Consumer 请求头随请求往下游走。
ABI 版本注意：Go 编译的插件导出 proxy_abi_version_0_2_100 扩展 ABI，只有 Higress fork 的 Envoy 支持，官方 Envoy 加载即失败（demo 用 higress/gateway 镜像的原因；详解见《key-auth插件本地Docker部署与运行机制指南.md》§3.2）。

1.2 骨架：wrapper 框架与回调注册

通俗理解

一次请求在网关里要过几个"检查站"，插件在 init() 里登记了每个站点要干什么。wasm-go 的 wrapper 包还帮插件干了两件麻烦事：一是把分片到达的 body 拼完整再交给你（裸 SDK 里要自己拼）；二是根据请求命中的配置级别（全局/域名/路由）把对应配置递给你的回调。

技术实现

插件执行阶段与优先级由代码注解声明：key-auth 是 @Phase AUTHN @Priority 321（main.go:62-63）。多插件并存时这决定执行顺序——认证（AUTHN 阶段）天然排在业务类插件（默认阶段）前面，先过门禁再谈别的。
wrapper.SetCtx 注册回调（main.go:37-43，详见 §3）。key-auth 只挂两类：ParseOverrideConfigBy（配置解析）+ ProcessRequestHeadersBy（请求头处理），因为认证只看请求头就够了；ai-security-guard 要挂 5~6 类（还要读请求体、拦响应），复杂度差别就在这。
wrapper 的配置分层机制：顶层 JSON 给 parseGlobalConfig，_rules_ 数组里每条给 parseOverrideRuleConfig；请求期框架按请求命中的路由/域名，把对应的那份配置递给回调。这套机制的"实体"见 §2.3 对 envoy.yaml:42 的剖析。

1.3 异步模型：ActionPause / Resume，以及 key-auth 的"同步特权"

通俗理解

这是理解插件执行模型最关键的一点。Envoy 的每个线程是单线程事件循环：插件代码运行时，这个线程上其他请求都在排队。所以插件里绝不允许"发一个网络请求然后干等结果"——那会把整个线程卡死，全网关的请求都跟着遭殃。

需要外呼的插件（如 ai-security-guard）正确姿势是"过安检“模式：旅客（请求）到安检口，安检员说"你先到旁边等着”（ActionPause），安检仪扫完（安全服务返回回调），安检员看结果——没问题就喊"过来继续走"（ResumeHttpRequest），有问题就直接请出去（SendHttpResponse）。等待期间安检口照常处理其他旅客。

key-auth 没这个烦恼：它是"看一眼证件“的安检员——所有判定都是内存操作（查 map、比名单），微秒级出结果，从不外呼，所以永远同步返回。

技术实现

key-auth 的 onHttpRequestHeaders（main.go:239）只做：读头 → map 查询 → 要么 ActionContinue 放行，要么 SendHttpResponse 本地拒绝后 return ActionContinue（请求已被 hostcall 终止，返回值只是形式，见 §6）。
需要外呼的插件是另一套写法：body hook 返回 types.ActionPause，在 DispatchHttpCall 的回调里根据结果 ResumeHttpRequest() 放行或 SendHttpResponse() 拦截；同一时刻只许一次在途调用（单飞），避免结果乱序。
判断一个插件属于哪类的方法：看回调里有没有发起异步调用（HTTP / Redis 等）。有 → 必须 Pause/Resume；没有 → 像 key-auth 一样同步返回即可，代码简单一个数量级。

1.4 部署链路：plugin.wasm 怎么变成生效的插件

通俗理解

OCI 镜像是 wasm 的"快递盒”：plugin.wasm 只有几 MB，要送进 K8s 集群里每个网关 Pod，最省事的办法是借用现成的 Docker 镜像物流体系——装进盒子（Dockerfile COPY）、贴上单号（VERSION tag）、寄到仓库（docker push），网关填个快递单号（url: oci://...）就能收到并拆包加载。

McpBridge 是给服务"铺路"：默认 Higress 只把"路由用到的服务"下发成 Envoy cluster；路由之外的服务（比如 ai-security-guard 要外呼的安全服务）想用，就得用 McpBridge 额外注册。

配置生效讲"就近原则"：请求命中了具体路由/域名配置就用它，完全不沾边才用 defaultConfig。

技术实现

WasmPlugin.spec.url 的三种形态：
- oci://...：镜像分发，生产环境用（keyauth.yaml 示例里的 oci://docker.io/dongjiang1989/keyauth:1.0.0）；
- http://plugin-server:8080/...：standalone 部署内置插件服务，官方插件（如 key-auth 2.0.0）开箱即用；
- file:///...：本地文件挂载，demo 用的就是这种（plugin.wasm 直接挂进 envoy 容器），改代码重编后重启容器即生效，最适合调试。
K8s 链路：WasmPlugin CRD → Higress 控制面翻译成 Envoy 的 wasm filter 配置下发到 gateway。demo 里手写的 envoy.yaml:26-42 就是这份"翻译结果"的样貌（§2.2 逐行拆解）。
McpBridge 的两个用途：① 给路由提供上游（本例把 httpbin.org 注册成 httpbin.dns 供 Ingress 引用）；② 给插件外呼铺路建 cluster（key-auth 无外呼用不到；ai-security-guard 靠它获得 outbound|443||safecheck.dns 这个 cluster）。
配置匹配的就近原则落到插件内部，就是 _rules_ / _match_route_ 的命中逻辑（§2.3、§4.3）。

2. envoy.yaml：插件是怎么"挂"进请求链路的

K8s 里我们写 WasmPlugin CRD，控制面把它翻译成 Envoy 配置；demo 里没有控制面，这段 envoy.yaml 就是翻译后的最终产物，所以看它最能理解插件的真实形态。

2.1 路由层（envoy.yaml:14-25）

1
2
3
4
5
6
7
8


route_config:
 virtual_hosts:
 - name: httpbin
 domains: [httpbin.example.com]  # Host 头必须匹配
 routes:
 - name: keyauth-route  # ★ 路由名，插件配置里引用它
 match: { prefix: / }
 route: { cluster: httpbin }

两个关键点：

domains 决定哪些 Host 走这条路由——test.sh 场景⑤不带 Host 直接访问，匹配不到 virtual host，Envoy 直接回 404，请求根本没到插件；
路由名 keyauth-route 是给插件配置引用的"身份证号"，马上会看到。

2.2 wasm filter 层（envoy.yaml:26-42）——全篇最重要的一段

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


http_filters:
 - name: envoy.filters.http.wasm
 typed_config:
 "@type": .../filters.http.wasm.v3.Wasm
 config:
 name: key-auth  # 对应 wrapper.SetCtx("key-auth", ...)
 vm_config:
 runtime: envoy.wasm.runtime.v8  # V8 沙箱里跑 wasm
 code:
 local: { filename: /etc/envoy/plugin.wasm }
 configuration:
 "@type": type.googleapis.com/google.protobuf.StringValue
 value: >-
 {"consumers":[...],"keys":["x-api-key","apikey"],"in_header":true,
 "global_auth":false,
 "_rules_":[{"_match_route_":["keyauth-route"],"allow":["consumer1"]}]}

逐行拆解：

http_filters 的顺序就是请求的处理顺序：wasm 排在 router 前面，所以插件先执行，拦下的请求根本不会转发给 httpbin。
configuration.value 是一段 JSON 字符串——这就是插件 parseGlobalConfig/parseOverrideRuleConfig 收到的原始 gjson.Result。
注意它的结构：全局字段（consumers/keys/in_header/global_auth）平铺在顶层，路由级规则放在 _rules_ 数组里，每条用 _match_route_ 指定生效的路由名。

2.3 大揭秘：`_rules_` 就是 WasmPlugin 的 matchRules

对照 K8s 版配置（keyauth.yaml），两边其实一模一样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# K8s 里你写的 # Envoy 实际收到的（envoy.yaml:42）
spec:
 defaultConfig: ──合并──► 顶层字段：consumers/keys/in_header/global_auth
 consumers: [...]
 global_auth: false
 ...
 matchRules: ──合并──► "_rules_": [{
 - ingress: → "_match_route_": ["keyauth-route"],
 - ingress-keyauth-httpbin "allow": ["consumer1"] }]
 config:
 allow: [consumer1]

Higress 控制面干的事就是把 defaultConfig + matchRules 编译成这样一段 JSON（K8s 里 _match_route_ 的值是 ingress 名，demo 里是手写的 envoy 路由名）。wasm-go wrapper 收到后：顶层 JSON 给 parseGlobalConfig，_rules_ 里每条给 parseOverrideRuleConfig。

“两级配置机制"的抽象说法，在 envoy.yaml:42 这一行里能看到实体。

2.4 docker-compose 里的两个细节

envoy 镜像是 higress/gateway（compose 文件第 11 行注释）：Go 编译的插件用了 proxy_abi_version_0_2_100 这个 ABI 扩展，只有 Higress fork 的 Envoy 支持，官方 Envoy 加载会失败（见 §1.1）。
--concurrency 1：单 worker 线程。回忆 §1.1"每个 worker 线程一个独立 Wasm VM”——demo 设成 1，保证你看到的日志和行为都来自同一个 VM，排除多副本干扰。

3. 代码骨架（main.go:35-43）

1
2
3
4
5
6
7
8
9


func main() {}

func init() {
	wrapper.SetCtx(
		"key-auth", // ← 对应 envoy.yaml 的 name: key-auth
		wrapper.ParseOverrideConfigBy(parseGlobalConfig, parseOverrideRuleConfig),
		wrapper.ProcessRequestHeadersBy(onHttpRequestHeaders),
	)
}

Wasm 插件没有进程入口，main() 是编译占位；真正的入口是 init()——插件加载时向 wrapper 框架挂号三件事：我的名字（要和 envoy.yaml / WasmPlugin 里的 name 对上）、配置来了调谁、请求头到了调谁。之后所有代码都是被动回调。

只挂两个 hook，因为认证只看请求头就够了。对比 ai-security-guard 挂 6 个（要读 body、拦响应），复杂度差别就在这（见 §1.2）。

4. 配置解析：把 envoy.yaml:42 那段 JSON 变成内存结构

4.1 配置结构体（main.go:88-131）

1
2
3
4
5
6
7
8
9


type KeyAuthConfig struct {
	globalAuth *bool `yaml:"global_auth,omitempty"` // 指针！三态的关键
	Keys []string `yaml:"keys"`
	InQuery bool `yaml:"in_query,omitempty"`
	InHeader bool `yaml:"in_header,omitempty"`
	consumers []Consumer
	allow []string
	credential2Name map[string]string `yaml:"-"` // 不从配置读，解析时自建
}

globalAuth 用 *bool 指针（main.go:94）：bool 零值 false 分不清"配了 false"和"根本没配"。指针区分三态：nil=未设置、&true、&false——这是后面裁决表的基础。
credential2Name 是运行时索引（main.go:130）：配置里 consumers 是列表，逐请求遍历是 O(n)；解析时建成 凭证→名字 的 map，运行时 O(1) 查表。配置解析一次、请求千千万万次——开销挪到解析期，是插件开发通用思路（§1.1 的状态原则）。

4.2 `parseGlobalConfig`：校验 + 建索引（main.go:133-204）

收到顶层 JSON（demo 里就是 consumers/keys/in_header/global_auth 那部分），先做一串防御式校验，任一不满足整条配置被拒：

keys 必须非空（:148-154）——没定义从哪取 key，认证无从谈起；
in_query/in_header 至少配一个（:163-165）；
consumers 非空，name/credential 都不能空；
凭证不允许重复（:192-194）——两个 consumer 同 key 就分不清"你是谁"，直接拒配。

通过后建索引。用 demo 的配置，解析完内存里是：

1
2
3
4


credential2Name = {
 "2bda943c-ba2b-11ec-ba07-00163e1250b5": "consumer1",
 "c8c8e9ca-558e-4a2d-bb62-e700dcc40e35": "consumer2",
}

demo 视角：改 envoy.yaml:42 里的 JSON（比如删掉 consumers），重启 compose，就能在 envoy 日志里看到对应的校验报错——配置错误在插件加载期就暴露，不会带病运行。

4.3 `parseOverrideRuleConfig`：叠加路由级 allow（main.go:206-225）

对 _rules_ 里每条规则调用一次：

1
2
3


*config = global // 先把全局配置整个拷过来（consumers/keys 自动继承）
// ... 解析 allow 列表
ruleSet = true // 标记：至少有一条路由配了插件

用 demo 配置：命中 keyauth-route 的请求，拿到的最终 config = 全局 consumers/keys + allow: ["consumer1"]；不命中任何 _rules_ 的请求，拿到的就是纯全局配置（allow 为空）。

ruleSet 是包级全局变量，记录"至少有一条路由配了插件"，裁决时用来猜管理员意图（见 §5 第一步）。

5. 核心裁决：`onHttpRequestHeaders`（main.go:239-327）

请求头到达时框架调它。开头算四个布尔值：

1
2
3
4


noAllow = len(config.allow) == 0 // 当前请求没命中任何 _rules_
globalAuthNoSet = config.globalAuth == nil
globalAuthSetTrue = !globalAuthNoSet && *config.globalAuth
globalAuthSetFalse = !globalAuthNoSet && !*config.globalAuth

第一步：要不要认证？（:249-254）

1
2
3
4
5


if globalAuthSetFalse || (globalAuthNoSet && ruleSet) {
	if noAllow {
		return types.ActionContinue // 不归我管，直接放行
	}
}

demo 配置 global_auth: false：请求没命中 keyauth-route（不会有，因为只有一个 virtual host；K8s 多路由场景才有意义）→ 直接放行，连 token 都不取。

ruleSet 的作用：global_auth 没设置时猜意图——任何路由都没配过插件（ruleSet==false）说明想全局认证；有路由配了，说明按路由精细控制，没配的路由放行。

第二步：取 token（:259-278）

1
2
3
4
5
6
7
8


if config.InHeader {
	for _, key := range config.Keys { // keys: [x-api-key, apikey]
		value, err := proxywasm.GetHttpRequestHeader(key)
		if err == nil && value != "" {
			tokens = append(tokens, value)
		}
	}
} else if config.InQuery { /* 从 :path 的 query 参数取 */ }

demo 配置 in_header: true：先试 x-api-key 头，再试 apikey 头。两个头都带就都收进 tokens——下一步会当成攻击拒绝（test.sh 没演示这个，可以自己加一条 curl 验证）。

坑：else if 意味着 in_header/in_query 同开时 query 永不生效（官方原版行为）。

第三步：数量检查（:281-285）

1
2


if len(tokens) > 1 { return deniedMultiKeyAuthData() } // 401 multi_key
if len(tokens) <= 0 { return deniedNoKeyAuthData() } // 401 no_key

带多个 key 为什么拒绝？防凭证混淆——一合法一非法同时带，后端处理顺序不同可能放行非法请求。→ test.sh 场景①（不带 Key）命中的就是这步的 401。

第四步：认证——查表认出"你是谁"（:288-294）

1
2
3
4
5


name, ok := config.credential2Name[tokens[0]]
if !ok {
	return deniedUnauthorizedConsumer() // 403：凭证不在名单
}
proxywasm.AddHttpRequestHeader("X-Mse-Consumer", name)

一次 map 查找完成认证。查到就把 consumer 名写进请求头往下游传——X-Mse-Consumer 是 Higress 消费者体系的通用语言，限流、ai-security-guard 的消费者级配置都读它。

→ test.sh 场景④（假 Key wrong-key）命中的就是这步的 403。 想亲眼看到注入效果：场景②通过的请求，httpbin 的 /get 响应体会把收到的请求头原样回显，里面就有 X-Mse-Consumer: consumer1。

第五步：授权——“你能进这扇门吗”（:299-326）

global_auth	路由无 allow	路由有 allow
true	凭证合法即放行	合法且在 allow 里
false	直接放行（第一步已走掉）	合法且在 allow 里
未设置	`ruleSet==false` → 按 true；否则按 false	同上

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


if (globalAuthSetTrue && noAllow) || (globalAuthNoSet && !ruleSet) {
	return authenticated(name) // 全局模式，凭证合法就行
}
if globalAuthSetTrue && !noAllow { ... } // 全局模式 + allow 校验
if globalAuthSetFalse || (globalAuthNoSet && ruleSet) {
	if !noAllow {
		if !contains(config.allow, name) { return deniedUnauthorizedConsumer() }
		return authenticated(name)
	}
}

demo 落在第三分支：→ test.sh 场景③（consumer2 的 Key，凭证合法但不在 allow: [consumer1]）命中这里的 403；场景②（consumer1）走到 authenticated 放行。

6. 拒绝响应怎么发（main.go:329-345）

1
2
3
4
5
6
7
8


_ = proxywasm.SendHttpResponseWithDetail(
	http.StatusUnauthorized, // 401（或 403）
	"key-auth.no_key", // 内部 detail 码，进日志
	WWWAuthenticateHeader(protectionSpace), // WWW-Authenticate: Key realm=MSE Gateway
	[]byte("Request denied by Key Auth check..."),
	-1,
)
return types.ActionContinue

WWW-Authenticate 是 RFC 7235 的要求，告诉客户端"这里用 Key 认证"。test.sh 的 ①③④ 输出里都能看到这行响应头，可以对照确认命中了哪个拒绝函数（body 文案各不相同）。

容易困惑的点：发了拒绝响应为什么还 return ActionContinue？SendHttpResponse 是"立即响应并终止该请求"的 hostcall，请求已结束，返回值只是形式。对比 ai-security-guard 外呼时的 ActionPause（等异步回调，见 §1.3），语义完全不同。

7. 剧本对照表：test.sh ⑤ 个场景 → 代码分支

test.sh 场景	请求	命中代码	期望
① 不带 Key	无认证头	`len(tokens)<=0` → `deniedNoKeyAuthData`（:283）	401 no_key
② consumer1 的 Key	`x-api-key: 2bda...`	查表得 consumer1（:288）→ allow 命中（:317-322）	200，响应回显含 `X-Mse-Consumer: consumer1`
③ consumer2 的 Key	`apikey: c8c8...`（第二个 key 名）	认证过、授权失败（:317-319）	403 unauthorized
④ 假 Key	`x-api-key: wrong-key`	查表未命中（:289-291）	403 unauthorized
⑤ 不带 Host	直接访问 IP:10000	到不了插件：virtual host `domains` 不匹配（envoy.yaml:18-19），Envoy 路由层 404	404

场景⑤是"插件不是万能的"的最好示例：它只在命中路由后执行，路由都没匹配上的请求根本轮不到它。

想动手验证：cd key-auth-docker-demo && docker compose up -d && ./test.sh。改 envoy.yaml:42 的 JSON 后 docker compose restart envoy 即生效，不用重编 wasm——配置和代码是两条独立的发布链路。

8. 设计脉络总结

1
2
3
4


加载期 init() → SetCtx 挂号（name 对应 envoy.yaml 的 filter 名）
配置期 envoy.yaml 的 configuration JSON → parseGlobalConfig 校验+建索引
 → _rules_ 每条 → parseOverrideRuleConfig 叠加 allow
请求期 取 token（keys 逐个试）→ 数量检查 → 查 map 认证 → 注入 X-Mse-Consumer → allow 授权 → 放行/401/403

一句话：配置期做好校验和索引（慢一次），请求期只做取 token、查 map、比名单（快万次）；三态 global_auth 是唯一绕的地方，记住"nil = 未设置，靠 ruleSet 猜意图"。

9. 已知小问题（移植自官方，未改动）

in_header/in_query 是 else if 关系，同开时 query 不生效（main.go:268）；
url.Parse 错误被忽略（main.go:270）；
凭证以 %q 打进日志（main.go:290），有轻微泄露风险；
落后于上游：官方已支持 consumer 多凭证 credentials 字段，此版本只有单 credential（main.go:57）；
keyauth.yaml 示例镜像指向个人仓库 docker.io/dongjiang1989/keyauth:1.0.0，实际部署需替换。

附：测试怎么验证这些（main_test.go，580 行）

TestParseGlobalConfig（:240）：喂残缺 JSON，验证校验报错；
TestParseRuleConfig（:361）：验证 allow 解析与 *config = global 继承；
TestOnHTTPRequestHeaders（:388）：用 wasm-go pkg/test 的 mock host 模拟请求头，断言 action 与发出的响应状态码——§7 的剧本①②③④都有对应断言。

单测（mock host，进程内跑）和 demo（真实 Envoy，容器里跑）是两种互补的验证层：前者快、覆盖分支；后者验证真实 ABI、真实配置链路和实际 HTTP 行为。

Higress on WYF 的技术博客

Higress 01：key-auth 插件本地 Docker 部署与运行机制指南

目录

一、背景：要复现的原配置

二、总体方案与架构

2.1 与官方独立部署方式的关系（先读这里）

三、原理介绍

3.1 WASM 插件是怎么跑起来的

3.2 Proxy-Wasm ABI 与 0_2_100 的坑

3.3 key-auth 插件的认证逻辑

3.4 规则匹配：rules 与 match_route

3.5 与原 YAML 的字段对应关系

四、搭建步骤（从零开始）

4.1 准备镜像

4.2 编译 plugin.wasm

4.3 编写配置

4.4 启动与验证

五、验证结果（实测输出）

① 不带 Key → 401

② consumer1 的 Key（在白名单）→ 200

③ consumer2 的 Key（有效但不在 allow）→ 403

④ 假 Key → 403（不是 401！）

⑤ Host 不匹配 → 404

六、踩坑记录

七、常用命令速查

附：单元测试路线（不需要 Docker）

Higress 02：key-auth 插件原理与代码导读（结合 docker demo 实战）

0. Demo 全景：一条请求的全部旅程

1. Wasm 插件通用运行原理（与 ai-security-guard 相通）

1.1 地基：沙箱、hostcall 与"每线程一个 VM"

1.2 骨架：wrapper 框架与回调注册

1.3 异步模型：ActionPause / Resume，以及 key-auth 的"同步特权"

1.4 部署链路：plugin.wasm 怎么变成生效的插件

2. envoy.yaml：插件是怎么"挂"进请求链路的

2.1 路由层（envoy.yaml:14-25）

2.2 wasm filter 层（envoy.yaml:26-42）——全篇最重要的一段

2.3 大揭秘：_rules_ 就是 WasmPlugin 的 matchRules

2.4 docker-compose 里的两个细节

3. 代码骨架（main.go:35-43）

4. 配置解析：把 envoy.yaml:42 那段 JSON 变成内存结构

4.1 配置结构体（main.go:88-131）

4.2 parseGlobalConfig：校验 + 建索引（main.go:133-204）

4.3 parseOverrideRuleConfig：叠加路由级 allow（main.go:206-225）

5. 核心裁决：onHttpRequestHeaders（main.go:239-327）

第一步：要不要认证？（:249-254）

第二步：取 token（:259-278）

第三步：数量检查（:281-285）

第四步：认证——查表认出"你是谁"（:288-294）

第五步：授权——“你能进这扇门吗”（:299-326）

6. 拒绝响应怎么发（main.go:329-345）

7. 剧本对照表：test.sh ⑤ 个场景 → 代码分支

8. 设计脉络总结

9. 已知小问题（移植自官方，未改动）

附：测试怎么验证这些（main_test.go，580 行）

2.3 大揭秘：`_rules_` 就是 WasmPlugin 的 matchRules

4.2 `parseGlobalConfig`：校验 + 建索引（main.go:133-204）

4.3 `parseOverrideRuleConfig`：叠加路由级 allow（main.go:206-225）

5. 核心裁决：`onHttpRequestHeaders`（main.go:239-327）