docs: document Wasmeld architecture and workflows

- describe resident Runtime boundaries and sandbox guarantees
- specify component archive and host capability contracts
- document Console ownership and persistence behavior
- explain versioned WIT Registry, lock files, and path replace
- provide startup, packaging, publication, and dependency commands
This commit is contained in:
Maofeng
2026-07-27 05:03:24 +08:00
parent 8de300b634
commit ad7d8cdd72
6 changed files with 763 additions and 0 deletions
+54
View File
@@ -0,0 +1,54 @@
# Wasmeld Console 管理后端
**状态:** Implemented
**范围:** 本地 Wasmeld Runtime 管理控制面
## 边界
`wasmeld-console` 是独立 Rust 进程,对外提供管理 HTTP API,对内只调用
`wasmeld-runtime`。Runtime 作为库嵌入同一进程,不另起网络服务。前端 `console`
不直接访问 Runtime、文件系统或数据库。
~~~text
TanStack Console / wasmeld CLI
|
| HTTP + JSON / multipart
v
wasmeld-console
+-- API / CORS
+-- component artifact registry
+-- immutable WIT package registry
+-- Toasty persistence
+-- local libSQL
|
v
wasmeld-runtime
+-- Wasmtime Engine
+-- resident Actor
+-- Store + Component Instance
~~~
## 状态
- Console 接收一个 `.wasmpkg`,从包内读取并校验组件身份。
- `component.wasm` 和平台生成的运行时 `manifest.toml` 保存到本地制品目录。
- 运行限制由 Console 策略注入,不接受组件包覆盖。
- manifest、调用计数和最近 256 条事件通过 Toasty 保存到 libSQL。
- Console 进程启动时自动创建 Runtime Engine,从数据库恢复服务元数据,并从制品目录注册 Component。
- Console 可显式启动、停止和重启 Runtime;停止 Runtime 不会停止 Console HTTP 管理面。
- Runtime 停止时释放全部 Actor、Store、Instance 和 epoch worker。
- Actor 内存和运行状态只存在于当前进程。
- Runtime 或 Console 重启后所有服务回到 `stopped`,调用计数与事件保留,但不会伪造 Wasm 内存恢复。
## 约束
- 默认只监听 `127.0.0.1:8080`
- libSQL 数据库默认位于 `var/wasmeld/console.db`
- CORS 默认只允许本地开发面板,其他 Origin 必须显式配置。
- 服务 ID 和 revision 只能包含 ASCII 字母、数字、点、下划线和短横线。
- `.wasmpkg` 上传和解压后的 Component 上限均默认为 64 MiB。
- 二进制 WIT Package 上传上限默认为 4 MiB,同名同版本发布后不可覆盖。
- 包内固定只有 `package.toml``component.wasm`,不会直接解压任意路径。
- Wasm 编译、实例化和调用通过阻塞任务执行,不占用 Tokio 异步 worker。
- Sandbox、fuel、deadline、内存和 mailbox 限制仍由 `wasmeld-runtime` 执行。