Maofeng
2c6e761288
Explain the wasmeld dev watch-build-package-deploy loop, isolated development service IDs, hash revisions, failure retention, cleanup behavior, and command options. Document the inactive-revision DELETE endpoint and the switch-before-unregister safety rule.
115 lines
5.2 KiB
Markdown
115 lines
5.2 KiB
Markdown
# Wasmeld Console
|
||
|
||
`wasmeld-console` 是 `wasmeld-runtime` 的本地 HTTP 管理适配器。它负责：
|
||
|
||
- 接收 `.wasmpkg`，校验并保存 `component.wasm` 与运行时 manifest
|
||
- 发布、查询和下载不可变的二进制 WIT Package
|
||
- 启动、停止和重启内嵌的 `wasmeld-runtime`
|
||
- 启动、停止和重启常驻 Actor
|
||
- 管理服务 ID 到活动版本的 Deployment
|
||
- 通过独立 Gateway 转发原始二进制调用
|
||
- 为导入 `wasmeld:kv/store@0.1.0` 的 Component 提供持久化 KV
|
||
- 暴露调用计数、状态和最近事件
|
||
|
||
Wasm 制品保存在本地文件系统。服务 manifest、调用计数和最近 256 条事件通过
|
||
[Toasty](https://github.com/tokio-rs/toasty) 写入本地 libSQL 数据库，默认路径是
|
||
`var/wasmeld/console.db`。Deployment 也存储在同一数据库中。
|
||
Host KV 使用 `(service_id, key)` 复合主键存储在该数据库中：同一服务的 Revision
|
||
共享数据，不同服务互相隔离，Runtime 或 Console 重启不会清空 KV。
|
||
|
||
`wasmeld-console` 启动时会在同一进程内创建 `wasmeld-runtime`、加载 Wasmtime Engine，
|
||
并重新注册已保存的 Component。Runtime 停止后 Console HTTP 和数据库仍然在线；
|
||
再次启动 Runtime 会重新注册 Component。未部署的版本恢复为 `stopped`；Deployment
|
||
指向的版本会用空初始化配置创建新的 Actor。Actor 的 Store 和线性内存不做快照。
|
||
|
||
## 启动
|
||
|
||
`wasmeld-console` 需要 Rust 1.95 或更高版本；Wasm 组件继续使用项目约定的 Rust 1.90
|
||
工具链构建。
|
||
|
||
```bash
|
||
cargo +stable run -p wasmeld-console
|
||
```
|
||
|
||
进程默认启动两个独立 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`
|
||
- `WASMELD_ALLOWED_ORIGINS`，多个 Origin 使用逗号分隔
|
||
- `RUST_LOG`
|
||
|
||
## API
|
||
|
||
| 方法 | 路径 | 用途 |
|
||
| --- | --- | --- |
|
||
| `GET` | `/healthz` | 健康检查 |
|
||
| `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，并重新创建活动 Deployment 的 Actor |
|
||
| `GET` | `/api/v1/services` | 服务版本及精确 Host Capability 列表 |
|
||
| `POST` | `/api/v1/services` | multipart 上传单个 `package` 字段（`.wasmpkg`） |
|
||
| `DELETE` | `/api/v1/services/{id}/{revision}` | 注销非活动 Revision 并删除制品 |
|
||
| `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 包 |
|
||
|
||
活动 Deployment 不能直接注销。开发工具会先完成新 Revision 的编译、注册和切换，
|
||
再注销上一份开发 Revision，因此失败的构建不会影响当前可调用版本。
|
||
|
||
激活已注册版本：
|
||
|
||
```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`。
|
||
|
||
服务响应的 `capabilities` 来自 Component 二进制中的 WIT imports，例如
|
||
`wasmeld:clock/monotonic-clock@0.1.0`。Console 不接受手工能力声明，Runtime 只会链接
|
||
注册表中存在且版本完全匹配的接口。
|
||
|
||
## Host KV
|
||
|
||
`wasmeld:kv/store@0.1.0` 提供 `get`、`set` 和 `delete`。Key 必须是非空 UTF-8，
|
||
最大 256 B；Value 最大 64 KiB。数据库命令通过有界专用工作线程执行，Host 等待时间
|
||
不会超过服务的 `deadline_ms`。v0.1.0 不提供 TTL、遍历、事务或 CAS。
|
||
|
||
组件包的构建与格式说明见
|
||
[`docs/design/wasmeld-component-package.md`](../../docs/design/wasmeld-component-package.md)。
|
||
WIT 依赖、Registry 和本地 replace 说明见
|
||
[`docs/design/wit-package-management.md`](../../docs/design/wit-package-management.md)。
|