1
┌─────────────────────────────────────────────────┐
2
│                 Wasm 插件优势                     │
3
├──────────────┬──────────────────────────────────┤
4
│ 多语言       │ Go / Rust / AssemblyScript / C++ │
5
│ 沙箱隔离     │ 内存隔离，崩溃不影响 Envoy        │
6
│ 热更新       │ 不停机替换插件                    │
7
│ 高性能       │ ~原生 80-90%                      │
8
│ 标准化       │ Proxy-Wasm 规范，跨代理（Envoy/MOSN）│
9
│ 生态         │ OCI 镜像分发，插件市场             │
10
└──────────────┴──────────────────────────────────┘

1
┌─────────────────────────────────────────────────┐
2
│  Envoy（宿主）                                   │
3
│  ┌───────────────────────────────────────────┐  │
4
│  │  Proxy-Wasm ABI（C++ 实现）                │  │
5
│  │  ┌─────────────────────────────────────┐  │  │
6
│  │  │  Wasm VM（V8 / Wasmtime / WAMR）    │  │  │
7
│  │  │  ┌───────────────────────────────┐  │  │  │
8
│  │  │  │  Wasm 插件（Go/Rust 编译）     │  │  │  │
9
│  │  │  │  - OnHttpRequestHeaders       │  │  │  │
10
│  │  │  │  - OnHttpRequestBody          │  │  │  │
11
│  │  │  │  - OnHttpResponseHeaders      │  │  │  │
12
│  │  │  │  - OnLog                      │  │  │  │
13
│  │  │  └───────────────────────────────┘  │  │  │
14
│  │  └─────────────────────────────────────┘  │  │
15
│  └───────────────────────────────────────────┘  │
16
└─────────────────────────────────────────────────┘

1
Envoy 进程内存空间
2
┌─────────────────────────────────────────┐
3
│  Envoy 核心代码                          │
4
│  ─────────────────────────────────────  │
5
│  Wasm VM 内存（沙箱）                    │
6
│  ┌───────────────────────────────────┐  │
7
│  │  插件 A 内存（线性内存，受限）      │  │
8
│  │  - 堆：最大 256MB（可配置）        │  │
9
│  │  - 栈：独立                       │  │
10
│  └───────────────────────────────────┘  │
11
│  ┌───────────────────────────────────┐  │
12
│  │  插件 B 内存（独立沙箱）            │  │
13
│  └───────────────────────────────────┘  │
14
└─────────────────────────────────────────┘
15

16
关键特性：
17
1. 插件无法访问 Envoy 内存（只能读/写自己的线性内存）
18
2. 插件崩溃只影响自己的沙箱，Envoy 继续运行
19
3. 插件间内存隔离，互不影响
20
4. 宿主通过 ABI 接口受控地暴露能力

1
Wasm 插件默认【不能】：
2
- 直接访问文件系统
3
- 直接发起网络请求（需通过 proxy_http_call）
4
- 直接访问系统调用
5
- 直接访问 Envoy 内部数据结构
6

7
Wasm 插件【可以】（通过 ABI）：
8
- 读/写 HTTP Header/Body
9
- 发起 HTTP/gRPC 请求（proxy_http_call）
10
- 读/写共享数据（proxy_get/set_shared_data）
11
- 写日志（proxy_log）
12
- 访问插件配置（proxy_get_plugin_configuration）

1
插件代码（不可信）
2
   ↓ 编译为 Wasm
3
   ↓
4
Wasm VM 验证
5
   ├── 内存访问边界检查
6
   ├── 函数签名验证
7
   └── 无限循环检测（燃料机制）
8
   ↓
9
沙箱执行
10
   ↓ 通过 ABI 调用宿主能力
11
   ↓
12
Envoy 验证并执行

1
1. 开发者推送新版本 Wasm 镜像到 OCI 仓库
2
   oras push registry.example.com/plugins/my-plugin:v2 plugin.wasm
3

4
2. 更新 WasmPlugin CRD 镜像版本
5
   kubectl patch wasmplugin my-plugin -p '{"spec":{"url":"oci://registry.example.com/plugins/my-plugin:v2"}}'
6

7
3. Higress Controller 监听到 CRD 变化
8

9
4. Controller 拉取新版本 Wasm 镜像
10

11
5. Controller 通过 xDS 推送新配置到 Gateway
12

13
6. Envoy 加载新版本 Wasm（新请求用新插件，旧请求继续用旧插件）
14

15
7. 旧版本插件在所有请求完成后卸载
16

17
整个过程【无需重启 Envoy】，实现真正的热更新。

1
# 按路由灰度插件版本
2
apiVersion: extensions.higress.io/v1alpha1
3
kind: WasmPlugin
4
metadata:
5
  name: my-plugin
6
spec:
7
  url: oci://registry.example.com/plugins/my-plugin:v2
8
  # 只在特定路由启用新版本
9
  matchRules:
10
    - ingress: [default/canary-route]
11
      config:
12
        version: v2
13
  # 其他路由用旧版本
14
  defaultConfig:
15
    version: v1

1
传统分发方式：
2
- 文件下载：版本管理混乱、无签名验证
3
- ConfigMap：大小限制 1MB、不适合二进制
4
- 自定义协议：生态不兼容
5

6
OCI 镜像分发优势：
7
- 复用 Docker Registry 生态（Harbor/ACR/GHCR/Docker Hub）
8
- 版本管理（tag/digest）
9
- 签名验证（cosign/notary）
10
- 访问控制（RBAC/Token）
11
- 全球分发（Registry Mirror/CDN）

1
OCI Artifact（Wasm 插件镜像）
2
├── manifest.json
3
│   ├── mediaType: application/vnd.oci.image.manifest.v1+json
4
│   └── layers:
5
│       ├── mediaType: application/vnd.module.wasm.content.layer.v1+wasm
6
│       │   └── plugin.wasm（Wasm 二进制）
7
│       └── mediaType: application/vnd.oci.image.layer.v1.tar+gzip
8
│           └── README.md / config.json（可选）
9
└── config.json
10
    └── 插件元数据（名称、版本、描述）

1
apiVersion: extensions.higress.io/v1alpha1
2
kind: WasmPlugin
3
metadata:
4
  name: my-plugin
5
spec:
6
  url: oci://registry.example.com/plugins/my-plugin:v1
7
  # 私有仓库认证
8
  imagePullSecret: registry-credentials
9
  # 或
10
  imagePullPolicy: IfNotPresent   # Always / IfNotPresent / Never
11
---
12
# 创建 Secret
13
apiVersion: v1
14
kind: Secret
15
metadata:
16
  name: registry-credentials
17
  namespace: higress-system
18
type: kubernetes.io/dockerconfigjson
19
data:
20
  .dockerconfigjson: <base64-encoded-docker-config>

1
┌─────────────────────────────────────────────────┐
2
│  插件加载阶段                                     │
3
│  1. Envoy 拉取 Wasm 镜像                         │
4
│  2. Wasm VM 验证并编译                           │
5
│  3. 调用 proxy_on_context_create（初始化）        │
6
│  4. 调用 proxy_on_configure（加载配置）           │
7
└─────────────────────────────────────────────────┘
8
                    ↓
9
┌─────────────────────────────────────────────────┐
10
│  请求处理阶段（每个请求）                          │
11
│  5. proxy_on_request_headers（请求头）            │
12
│  6. proxy_on_request_body（请求体，可选）          │
13
│  7. [转发到上游]                                 │
14
│  8. proxy_on_response_headers（响应头）           │
15
│  9. proxy_on_response_body（响应体，可选）         │
16
│  10. proxy_on_log（请求完成，记录日志）            │
17
└─────────────────────────────────────────────────┘
18
                    ↓
19
┌─────────────────────────────────────────────────┐
20
│  插件卸载阶段                                     │
21
│  11. proxy_on_context_destroy（清理资源）         │
22
│  12. Wasm VM 释放内存                            │
23
└─────────────────────────────────────────────────┘

1
// Continue：继续处理，进入下一个 Filter
2
return types.ActionContinue
3

4
// Pause：暂停处理，等待异步操作完成
5
// 常用于 proxy_http_call（发起 HTTP 请求）
6
return types.ActionPause
7

8
// Stop：停止处理，直接返回响应
9
// 常用于认证失败、限流触发
10
proxywasm.SendHttpResponse(403, nil, []byte("Forbidden"), -1)
11
return types.ActionStop

1
apiVersion: extensions.higress.io/v1alpha1
2
kind: WasmPlugin
3
metadata:
4
  name: jwt-auth
5
  namespace: higress-system
6
spec:
7
  # 插件镜像
8
  url: oci://registry.example.com/plugins/jwt-auth:v1
9

10
  # 镜像拉取策略
11
  imagePullPolicy: IfNotPresent
12
  imagePullSecret: registry-credentials
13

14
  # 插件阶段（执行顺序）
15
  phase: AUTHN          # AUTHN / AUTHZ / STATS / UNSPECIFIED_PHASE
16

17
  # 优先级（同 phase 内，数字越大越先执行）
18
  priority: 1000
19

20
  # 默认配置（全局生效）
21
  defaultConfig:
22
    issuer: "https://auth.example.com"
23
    jwks_uri: "https://auth.example.com/.well-known/jwks.json"
24

25
  # 匹配规则（特定路由/域名/服务生效）
26
  matchRules:
27
    # 路由级配置
28
    - ingress: [default/api-route]
29
      config:
30
        issuer: "https://api-auth.example.com"
31

32
    # 域名级配置
33
    - domain: [admin.example.com]
34
      config:
35
        issuer: "https://admin-auth.example.com"
36

37
    # 服务级配置
38
    - service: [payment-service.default.svc.cluster.local]
39
      config:
40
        strict: true
41

42
  # 插件失败策略
43
  failStrategy: FAIL_OPEN   # FAIL_OPEN（继续）/ FAIL_CLOSE（拒绝）

1
路由级 > 域名级 > 服务级 > 全局级（defaultConfig）
2

3
示例：
4
- defaultConfig: issuer = "https://auth.example.com"
5
- domain[admin.example.com]: issuer = "https://admin-auth.example.com"
6
- ingress[default/api-route]: issuer = "https://api-auth.example.com"
7

8
最终生效：
9
- api-route → "https://api-auth.example.com"（路由级）
10
- admin.example.com 其他路径 → "https://admin-auth.example.com"（域名级）
11
- 其他所有 → "https://auth.example.com"（全局级）

1
请求处理顺序：
2
1. AUTHN（认证）→ JWT / OAuth2 / API Key
3
2. AUTHZ（鉴权）→ RBAC / ABAC
4
3. UNSPECIFIED_PHASE（自定义）→ 业务插件
5
4. STATS（统计）→ Metrics / Logging
6

7
同 Phase 内按 priority 降序执行（数字大的先执行）