Obelisk

一个基于 WASM Component Model 构建的 deterministic 工作流引擎。

[!WARNING] 预发布版本：CLI、gRPC、WIT 和数据库架构可能会发生变化。

Obelisk 实战

Stargazers 应用包含以下功能：

一个监听 GitHub star 事件的 webhook。
用于与 Turso DB、OpenAI 和 GitHub 交互的 Activities。
一个编排这些 Activities 的工作流。

Obelisk fly.io 部署工具包含以下功能：

一个用于在 fly.io 上部署 Obelisk 应用的完整工作流
失败时的清理 / 补偿操作

包含内容

Obelisk Runtime：一个执行确定性工作流、activities 和 webhook 端点的单一二进制文件，使用 SQLite 或 PostgreSQL 将步骤持久化到执行日志中。
控制接口：
- CLI：通过 obelisk 命令管理执行。
- gRPC API：编程式交互。
- Web UI：查看和提交函数执行、执行日志、WIT 定义，以及一个显示记录事件回溯和源代码的时间旅行调试器。

核心原则

可重放工作流：确定性执行确保可靠的恢复、调试和审计。
弹性 Activities：在错误和超时时自动重试，并持久化输入和结果。
模式优先设计与端到端类型安全：使用 WASM Component Model 和 WIT IDL 生成 API 绑定。

使用场景

AI 辅助代码的沙箱化与审计
周期性任务：使用常规代码自动化执行具有复杂逻辑的周期性检查。
后台作业：利用内置的错误处理和重试机制卸载任务。
批处理作业：管理大规模任务，如 faas 部署。
端到端测试：自动化测试并记录每个步骤的详细日志。

核心特性

WASI 活动

活动必须是幂等的（可重试的）。此契约必须由活动本身满足。
通过 WASI 0.2 HTTP 客户端支持 HTTP 请求。
在错误、超时和 panic（WASM 陷阱）时自动重试。
持久化执行结果。

确定性工作流

运行时保证确定性，具有持久化执行日志，因此完全可重放且具备崩溃恢复能力。
超时时自动重试。
支持生成子执行，采用结构化并发。

WASI Webhook 端点

挂载为 URL 路径，提供 HTTP 流量服务。
支持生成子执行。

工作窃取执行器

并发限制和可自定义的重试处理。

安装

支持的平台

Linux x64, arm64 (musl, glibc v2.35+, NixOS)
MacOS x64, arm64

预构建二进制文件

curl -L --tlsv1.2 -sSf https://raw.githubusercontent.com/obeli-sk/obelisk/main/download.sh | bash

或使用 cargo-binstall：

cargo binstall obelisk

Docker

# Use host's network. Ports 8080 (web) and 5005 (grpc) will be bound to 127.0.0.1
mkdir config
docker run getobelisk/obelisk generate config > config/obelisk.toml
docker run \
  --net=host
  -v $(pwd)/config:/config \
  getobelisk/obelisk \
  server run --config /config/obelisk.toml

# Forward ports explicitly
docker run \
  -p 8080:8080 -e 'OBELISK__webui__listening_addr=0.0.0.0:8080' \
  -p 5005:5005 -e 'OBELISK__api__listening_addr=0.0.0.0:5005' \
  -v $(pwd)/config:/config \
  getobelisk/obelisk \
  server run --config /config/obelisk.toml

# Share the cache directory from host
docker run --net=host \
  -u $(id -u):$(id -g) \
  -v $(pwd)/config:/config \
  -e 'OBELISK__WASM__CACHE_DIRECTORY=/cache/obelisk/wasm' \
  -v ~/.cache/obelisk/wasm:/cache/obelisk/wasm \
  getobelisk/obelisk \
  server run --config /config/obelisk.toml

从源码构建

需要 protoc。

cargo install --locked obelisk

使用 Nix：

nix run github:obeli-sk/obelisk/latest

更多选项请参阅安装。

快速入门

详情请参阅快速入门指南。

启动服务器

obelisk server run --deployment deployment-testing-wasm-oci.toml

使用 Postgres 运行

docker run -it --rm \
  --name obelisk-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:18

# export env vars if .envrc is not used
export POSTGRES_HOST="localhost"
export POSTGRES_USER="postgres"
export POSTGRES_PASSWORD="postgres"
export POSTGRES_DATABASE="obelisk"

obelisk server run --server-config server-postgres.toml --deployment deployment-testing-wasm-oci.toml

CLI 用法

obelisk component list
# Call fibonacci(10) activity from the workflow 500 times in series.
obelisk execution submit testing:fibo-workflow/workflow.fiboa '[10, 500]' --follow

Web UI

访问 localhost:8080 以管理组件、函数和执行历史。

贡献

本项目有一个路线图，功能将按照特定顺序添加。在贡献之前，请通过 GitHub Discussions 讨论功能。需要签署贡献者许可协议。

开发

通过 Nix 设置依赖项：

cp .envrc-example .envrc
$EDITOR .envrc
direnv allow
# If direnv is not available use `nix develop`

或手动安装依赖项（参见 dev-deps.txt）。

运行程序：

cargo run --release

有关仓库结构、构建说明、测试、代码模式和贡献约定，请参阅 DEVELOPMENT.md。

运行测试

Postgres 必须正在运行。有关如何设置环境变量，请参阅 .envrc-example。快速入门：

cp .envrc-example .envrc && $EDITOR .envrc && direnv allow
cargo run --release
./scripts/test.sh

项目许可信息

本项目（除以下注明外，所有文件和文件夹）均根据 GNU Affero General Public License version 3 授权。

子文件夹例外

以下子文件夹根据 MIT License 授权：

wit/ – 参见 LICENSE-MIT
proto/ – 参见 LICENSE-MIT

生成的 WIT 文件

运行时包含可能生成新的“extension” WIT 文件的功能。这些生成的文件通常基于用户提供的 WIT 文件和位于 MIT 授权的 wit/ 目录中的基础 WIT 定义的组合。

用户可自由使用、修改和分发这些生成的 WIT 文件，其条款遵循 MIT 许可证，例如，以允许其他 WASM 组件通过这些扩展接口进行交互。