Day 20 / 共 20 天 · 第 4 周 高级特性与实战
构建部署与收官串讲
恭喜坚持到最后一天,也是整个 higress-group 系列的收官!前 19 天我们都在讲"怎么写插件代码";今天走完"插件的一生"最后的部署环节(编译→镜像→部署),再把 Envoy→Istio→Higress→Console→wasm-go 五站连成一个 AI 网关产品的完整全貌。
📍 你在整门课的位置(wasm-go 20 天 · 第 4 周收官)
性能/测试 D19→
构建部署 + 五站串讲 D20→
🎓 毕业·会写会部署插件
L01
编译成 wasm
💡 本质:编译打包部署 = 把手写菜谱做成"预制菜"上架配送
你写的 Go 代码是"菜谱";
go build 成 .wasm 是"把菜做成标准化预制菜";FROM scratch 打成 OCI 镜像是"塑封装盒";推到镜像仓库是"上架冷链仓";WasmPlugin CRD 指向镜像是"下订单";Higress+Envoy 拉取加载是"门店把预制菜加热开卖"。整条链就是从"你的源码"到"网关每个请求都在跑它"的自动化流水线。图注:插件从源码到上线的六步流水线——今天补齐 ②③④⑤,Day 01 画的"插件的一生"至此全部走通。
README.md 的构建命令(以 request-block 为例):
cd examples/request-block
GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o main.wasm main.go
这行命令做了什么?
GOOS=wasip1 GOARCH=wasm 告诉 Go 编译器"目标是 WASI(Wasm 系统接口)平台",-buildmode=c-shared 生成动态库形式的 .wasm。结果 main.wasm 就是能被 Envoy 加载的插件字节码。需要 Go 1.24+(go.mod 要求)。注意:不是普通的 go build——普通编译产出本机可执行文件,这里产出的是跨平台 Wasm 字节码。L02
打成 OCI 镜像
README.md 的极简 Dockerfile:
FROM scratch
COPY main.wasm plugin.wasm
docker build -t /request-block:1.0.0 -f Dockerfile .
docker push /request-block:1.0.0
为什么用 FROM scratch?
scratch 是"空镜像"——里面什么都没有。插件镜像只需要装一个 main.wasm 文件(改名 plugin.wasm),不需要操作系统、不需要运行时。所以镜像极小(就是那个 wasm 文件的大小)。这不是"能跑的容器",而是"用 OCI 镜像格式当分发载体"——Higress 从镜像仓库拉这个 wasm 文件加载。回想上一站 Console:WasmPlugin CR 的 url: oci://... 指的就是这个镜像。⚠️ 常见误解:小白看到 Dockerfile 就以为"这是个能
docker run 起来的容器"。其实 FROM scratch 里没有任何可执行程序,run 不起来——它只是借用 OCI 镜像格式当"文件快递盒"来分发那个 plugin.wasm,真正加载运行它的是 Envoy。L03
WasmPlugin 部署
用 WasmPlugin CRD 部署(README.md,Day 02 见过):
apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata: { name: request-block, namespace: higress-system }
spec:
defaultConfig: { block_urls: ["swagger.html"] } # → parseConfig 的入参
url: oci:///request-block:1.0.0 # → 上一步的镜像
读法:
kubectl apply 这个 CR,Higress 控制器 watch 到 → 下发给 Envoy → Envoy 从 url 拉 wasm 加载 → 用 defaultConfig 调你的 parseConfig。也可以在上一站 Higress Console 界面里配(自定义插件)——最终生成的就是这个 CR。📝 举个例子:这份 CR 上线后,一个请求会怎样
上面的 CR 设
用户访问
用户访问
block_urls: ["swagger.html"]。用户访问
GET /swagger.html → Envoy 已加载你的 wasm → 请求头钩子里 config.blockUrls 命中 "swagger.html" → SendHttpResponseWithDetail(403) → 用户收到 403 Forbidden,请求没被转发到后端。用户访问
GET /api/users → 不命中 → ActionContinue → 正常转发。你写的那几十行 Go,就这样在每个请求上生效了。L04
插件的一生(回收 Day 01)
① 写:init 里 SetCtx 注册回调(W1)+ parseConfig/RuleMatcher(W2)+ 请求处理/外部调用(W3)+ 日志/Leader/Token(W4)
② 编译:
GOOS=wasip1 GOARCH=wasm go build → main.wasm③ 打包:FROM scratch + COPY → OCI 镜像 → push
④ 配置:WasmPlugin CRD(或 Console 界面)指向 oci:// 镜像
⑤ 运行:Higress 下发 → Envoy 拉 wasm、每 worker 克隆 VM → OnPluginStart 加载配置
⑥ 处理:请求到来 → GetMatchConfig 选配置 → 各阶段钩子 → 返回 Action
Day 01 画的这条链,现在每一环你都懂了。
L05
四周主线回顾
- W1 入门与生命周期:request-block 例子、proxy-wasm ABI、三级 Context、SetCtx 函数式选项。
- W2 配置与匹配:ParseConfig 家族、RuleMatcher 五种匹配、GetMatchConfig 运行时选配、全局vs规则+隔离容错、OnPluginStart 生命周期。
- W3 HTTP 与外部调用:六阶段钩子+Action、HttpContext 能力、Cluster 8 种、HttpCall/RedisCall 异步回调(Pause/Resume)。
- W4 高级特性:SafeLog、Leader 选举+SharedData CAS、tokenusage 多协议、rebuild 重建+IO 限流+单测。
一句话总纲:wasm-go = proxy-wasm ABI 的 Go 友好封装——用"填回调"的极简模型(SetCtx)+ 内置的配置解析/规则匹配/HTTP&Redis 客户端/日志/Leader选举/Token解析,让你专注写插件业务,把 Wasm 的复杂度(沙箱、异步、多 VM、内存)全藏在背后。
🎯 记忆口诀:一句话记住四周
"一周搭骨架(SetCtx 填回调),二周读配置(ParseConfig+规则匹配),三周干实活(六阶段钩子+HTTP/Redis 异步),四周上生产(安全日志+Leader+Token+重建)。" 会背这句,就能对着它想起每天学了啥。
L06
五站大串讲
Envoy数据面
C++ 代理,跑 Wasm VM
C++ 代理,跑 Wasm VM
Istio控制面
istiod 生成 xDS
istiod 生成 xDS
HigressAI 网关
Core 喂配置给 istiod
Core 喂配置给 istiod
Console管理界面
生成 K8s 配置
生成 K8s 配置
wasm-go插件 SDK
写扩展插件(本课)
写扩展插件(本课)
五站怎么协作成一个产品(完整闭环)
你用 wasm-go(本课)写个插件、编译成 wasm 推到镜像仓库 → 在 Console(上一站)界面里配置这个插件、绑定到某路由 → Console 生成 WasmPlugin CR 写进 K8s → Higress Core watch 到、翻译成 Istio 配置 → 经 MCP-over-xDS 喂给 Istio 的 istiod → istiod 生成 xDS 下发给 Envoy → Envoy 加载你的 wasm、每个请求在各阶段调用你写的钩子。
五站串起来就是"一个可扩展的 AI 网关产品"的完整技术栈:从流量执行(Envoy)、配置管理(Istio/Higress)、人机界面(Console)到能力扩展(wasm-go)。你现在能看懂整个产品是怎么搭起来的。
五站串起来就是"一个可扩展的 AI 网关产品"的完整技术栈:从流量执行(Envoy)、配置管理(Istio/Higress)、人机界面(Console)到能力扩展(wasm-go)。你现在能看懂整个产品是怎么搭起来的。
L07
写一个插件的路径
想动手写自己的插件,建议路径:
- 抄一个例子起步:复制
examples/request-block,改成你的逻辑。 - 定义配置:写配置结构体 + parseConfig(Day 06),需要多套配置就用 RuleMatcher(Day 07-09)。
- 写处理逻辑:选合适的阶段钩子(Day 11),需要外部数据就用 HttpCall/Redis(Day 14-15)。
- 加固:敏感日志用 UnsafeInfo(Day 16)、独占任务用 Leader(Day 17)、长跑加 rebuild(Day 19)。
- 测试 + 部署:用 pkg/test 写单测(Day 19),编译打镜像部署(今天)。
L08
毕业 + 动手
🎓 20 天后,你已经能
- 用 wasm-go 从零写一个 Higress Wasm 插件并部署。
- 说清插件生命周期、三级 Context、配置解析与规则匹配。
- 掌握异步外部调用(HTTP/Redis)的 Pause/Resume 节奏。
- 运用高级特性:安全日志、Leader 选举、Token 解析、性能重建。
- 把 Envoy→Istio→Higress→Console→wasm-go 五站串成一个 AI 网关产品的完整全貌。
✋ 毕业动手:写你的第一个插件
cd /Users/bitmart/work/codes/github/higress-group/wasm-go/examples
cp -r request-block my-plugin && cd my-plugin
# 改 main.go 的插件名和逻辑,然后:
GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o main.wasm main.go
ls -la main.wasm
# 恭喜——你已经能造 Higress 插件了!higress-group 五站全部学完 🎉
higress-group 系列 5/5 全部完成!Envoy(数据面)→ Istio(控制面)→ Higress(AI 网关)→ Console(管理界面)→ wasm-go(插件 SDK)——你已经通读了一个云原生 AI 网关产品的完整技术栈。接下来可以挑一个真实需求,写个插件贡献给社区。