Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add Chinese language support to wasm documentation #11572

Open
wants to merge 12 commits into
base: master
Choose a base branch
from
4 changes: 4 additions & 0 deletions docs/zh/latest/config.json
Original file line number Diff line number Diff line change
Expand Up @@ -241,6 +241,10 @@
"type": "doc",
"id": "external-plugin"
},
{
"type": "doc",
"id": "wasm"
},
{
"type": "doc",
"id": "CODE_STYLE"
Expand Down
84 changes: 84 additions & 0 deletions docs/zh/latest/wasm.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# Wasm

APISIX 支持使用 [Proxy Wasm SDK](https://github.com/proxy-wasm/spec#sdks) 编写的 Wasm 插件。

目前,仅实现了少数 API。请关注 [wasm-nginx-module](https://github.com/api7/wasm-nginx-module) 以了解进展。

## 编程模型

所有插件都在同一个 Wasm VM 中运行,就像 Lua 插件在 Lua VM 中一样。

每个插件都有自己的 VMContext(根 ctx)。

每个配置的路由/全局规则都有自己的 PluginContext(插件 ctx)。例如,如果我们有一个配置了 Wasm 插件的服务,并且有两个路由继承自它,将会有两个插件 ctx。

每个命中该配置的 HTTP 请求都有自己的 HttpContext(HTTP ctx)。例如,如果我们同时配置了全局规则和路由,HTTP 请求将有两个 HTTP ctx,一个用于来自全局规则的插件 ctx,另一个用于来自路由的插件 ctx。

## 如何使用

首先,我们需要在`config.yaml`中定义插件:

```yaml
wasm:
plugins:
- name: wasm_log # 插件的名称
priority: 7999 # 优先级
file: t/wasm/log/main.go.wasm # `.wasm` 文件的路径
http_request_phase: access # 默认是"access",可以是["access", "rewrite"]之一
```

就是这样。现在您可以像使用常规插件一样使用 Wasm 插件。

例如,在指定路由上启用此插件:

**注意**

您可以从`config.yaml`中获取`<beginning of the code>admin_key<end of the code>`,并使用以下命令将其保存到环境变量中:

```bash
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed's/"//g')
```

然后执行以下命令:

```bash
curl -i http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
"uri": "/index.html",
"plugins": {
"wasm_log": {
"conf": "blahblah"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
}
}'
```

以下是插件中可以配置的属性:

|名称 | 类型 | 要求 | 默认 | 有效 | 描述|
|---|---|---|---|---|---|
|conf|字符串 | 必填 | 无 | 不得为空 |插件 ctx 配置,可以通过 Proxy Wasm SDK 获取|

这里是 Proxy Wasm 回调与 APISIX 阶段的映射:

- `proxy_on_configure`:在新配置没有 PluginContext 时运行一次。例如,当第一个请求命中配置了 Wasm 插件的路由时。
- `proxy_on_http_request_headers`:在 access/rewrite 阶段运行,具体取决于`http_request_phase`的配置。
- `proxy_on_http_request_body`:在与`proxy_on_http_request_headers`相同的阶段运行。要运行此回调,我们需要在`proxy_on_http_request_headers`中将属性`wasm_process_req_body`设置为非空值。请参考`t/wasm/request-body/main.go`作为示例。
- `proxy_on_http_response_headers`:在 header_filter 阶段运行。
- `proxy_on_http_response_body`:在 body_filter 阶段运行。要运行此回调,我们需要在`proxy_on_http_response_headers`中将属性`wasm_process_resp_body`设置为非空值。请参考`t/wasm/response-rewrite/main.go`作为示例。

## 示例

我们在这个仓库的`t/wasm/`下重新实现了一些 Lua 插件:

- fault - injection
- forward - auth
- response - rewrite
- Slack
- Twitter
Loading