docs: document gateway deployment workflow

- explain the separate control-plane and data-plane listeners - document revision activation and raw binary invocation - clarify restart restoration and actor-memory semantics
2026-07-29 16:32:21 +08:00
parent 9160362fc0
commit 3f5bb344f7
2 changed files with 55 additions and 6 deletions
@@ -23,6 +23,23 @@ wit/                     Wasmeld WIT package 源码
 cargo +stable run -p wasmeld-console
 ```

+后端会启动本地管理 API `127.0.0.1:8080` 和公开数据面
+`0.0.0.0:8081`。注册 Component 后，通过管理 API 激活一个版本：
+
+```bash
+curl -X POST http://127.0.0.1:8080/api/v1/deployments/echo/activate \
+  -H 'Content-Type: application/json' \
+  -d '{"revision":"0.1.0"}'
+```
+
+客户端只访问 Gateway，并以原始二进制请求调用活动版本：
+
+```bash
+curl http://127.0.0.1:8081/v1/services/echo/invoke \
+  -H 'Content-Type: application/octet-stream' \
+  --data-binary 'hello'
+```
+
 管理面：

 ```bash
@@ -6,17 +6,18 @@
 - 发布、查询和下载不可变的二进制 WIT Package
 - 启动、停止和重启内嵌的 `wasmeld-runtime`
 - 启动、停止和重启常驻 Actor
- 转发二进制调用
+- 管理服务 ID 到活动版本的 Deployment
+- 通过独立 Gateway 转发原始二进制调用
 - 暴露调用计数、状态和最近事件

 Wasm 制品保存在本地文件系统。服务 manifest、调用计数和最近 256 条事件通过
 [Toasty](https://github.com/tokio-rs/toasty) 写入本地 libSQL 数据库，默认路径是
-`var/wasmeld/console.db`。
+`var/wasmeld/console.db`。Deployment 也存储在同一数据库中。

 `wasmeld-console` 启动时会在同一进程内创建 `wasmeld-runtime`、加载 Wasmtime Engine，
 并重新注册已保存的 Component。Runtime 停止后 Console HTTP 和数据库仍然在线；
-再次启动 Runtime 会重新注册 Component，但 Actor 内存不做快照，服务运行状态统一
-恢复为 `stopped`。
+再次启动 Runtime 会重新注册 Component。未部署的版本恢复为 `stopped`；Deployment
+指向的版本会用空初始化配置创建新的 Actor。Actor 的 Store 和线性内存不做快照。

 ## 启动

@@ -27,11 +28,18 @@ Wasm 制品保存在本地文件系统。服务 manifest、调用计数和最近
 cargo +stable run -p wasmeld-console
 ```

-默认监听 `127.0.0.1:8080`。
+进程默认启动两个独立 Listener：
+
+- 管理 API：`127.0.0.1:8080`
+- Gateway：`0.0.0.0:8081`
+
+管理 Router 不会挂载到 Gateway Listener，Gateway 也不暴露注册、Runtime 生命周期和
+WIT Registry 路由。

 可用环境变量：

 - `WASMELD_ADDR`
+- `WASMELD_GATEWAY_ADDR`
 - `WASMELD_ARTIFACT_DIR`
 - `WASMELD_DATABASE_PATH`
 - `WASMELD_WIT_REGISTRY_DIR`
@@ -46,19 +54,43 @@ cargo +stable run -p wasmeld-console
 | `GET` | `/api/v1/runtime` | Runtime 状态 |
 | `POST` | `/api/v1/runtime/start` | 启动 Runtime 并重新注册受管 Component |
 | `POST` | `/api/v1/runtime/stop` | 停止 Runtime 并释放所有 Actor |
-| `POST` | `/api/v1/runtime/restart` | 重建 Runtime，服务恢复为停止状态 |
+| `POST` | `/api/v1/runtime/restart` | 重建 Runtime，并重新创建活动 Deployment 的 Actor |
 | `GET` | `/api/v1/services` | 服务版本列表 |
 | `POST` | `/api/v1/services` | multipart 上传单个 `package` 字段（`.wasmpkg`） |
 | `POST` | `/api/v1/services/{id}/{revision}/start` | 启动 Actor |
 | `POST` | `/api/v1/services/{id}/{revision}/stop` | 停止 Actor |
 | `POST` | `/api/v1/services/{id}/{revision}/restart` | 重启 Actor |
 | `POST` | `/api/v1/services/{id}/{revision}/invoke` | Base64 二进制调用 |
+| `GET` | `/api/v1/deployments` | 活动 Deployment 列表 |
+| `GET` | `/api/v1/deployments/{id}` | 查询服务的活动版本 |
+| `POST` | `/api/v1/deployments/{id}/activate` | 启动目标版本并原子切换活动版本 |
 | `GET` | `/api/v1/events` | 最近 256 条持久化事件 |
 | `GET` | `/api/v1/wit/packages` | WIT 包版本列表 |
 | `POST` | `/api/v1/wit/packages` | multipart 发布单个二进制 WIT `package` 字段 |
 | `GET` | `/api/v1/wit/packages/{namespace}/{name}/{version}` | WIT 包元数据 |
 | `GET` | `/api/v1/wit/packages/{namespace}/{name}/{version}/content` | 下载 WIT 包 |

+激活已注册版本：
+
+```bash
+curl -X POST http://127.0.0.1:8080/api/v1/deployments/echo/activate \
+  -H 'Content-Type: application/json' \
+  -d '{"revision":"0.1.0"}'
+```
+
+Gateway 只提供 `GET /healthz` 和
+`POST /v1/services/{id}/invoke`。调用请求与成功响应的
+`Content-Type` 都是 `application/octet-stream`：
+
+```bash
+curl http://127.0.0.1:8081/v1/services/echo/invoke \
+  -H 'Content-Type: application/octet-stream' \
+  --data-binary 'hello'
+```
+
+成功响应通过 `X-Wasmeld-Revision` 返回实际路由的版本。Gateway 错误统一返回 JSON；
+未部署为 `404`，Actor 不可用为 `503`，过载为 `429`，执行超时为 `504`。
+
 组件包的构建与格式说明见
 [`docs/design/wasmeld-component-package.md`](../../docs/design/wasmeld-component-package.md)。
 WIT 依赖、Registry 和本地 replace 说明见