orion

Orion 是一个声明式服务运行时。一个 Orion 服务由工作流和通道组成，并可选择连接到外部系统的连接器。提交这些定义并激活后，服务即可上线——无需编写应用服务器、为每个服务构建容器，也无需重启运行时。

Orion 以一致的方式处理周边基础设施：路由、入口防护、速率限制、超时、重试、熔断器、连接池、版本发布、回滚、指标和追踪。定义既可以由开发者编写，也可以由 AI 助手提出；两者遵循相同的草稿、测试、激活和审计流程。

说明

Orion 专为可表示为有序任务函数和 JSONLogic 的请求型与事件型工作而设计。它不是通用应用运行时，也不是持久化工作流引擎。为项目选择 Orion 前，请参阅适用场景。

快速入门

此经过测试的流程使用 Docker、curl 和兼容 POSIX 的 shell。它会启动本地 Orion 实例，部署订单处理工作流和通道，并调用生成的 API。

1. 启动 Orion

docker run --name orion-quickstart -d -p 8080:8080 \
  ghcr.io/goplasmatic/orion:latest

curl --retry 10 --retry-delay 1 --retry-connrefused \
  http://localhost:8080/healthz

2. 检查并部署示例

curl -fsSLo /tmp/orion-quickstart.sh \
  https://raw.githubusercontent.com/GoPlasmatic/Orion/main/examples/quickstart.sh
less /tmp/orion-quickstart.sh
bash /tmp/orion-quickstart.sh

该脚本会发起四次管理调用：创建并激活一个工作流，然后创建并激活其通道。最后，脚本会发送测试请求，并且可以安全地重复运行。从克隆的代码仓库运行时，请改用 ./examples/quickstart.sh。

3. 调用你的服务

curl -fsS -X POST http://localhost:8080/api/v1/data/orders \
  -H 'Content-Type: application/json' \
  -d '{ "data": { "order_id": "ORD-0001", "total": 12500 } }'

响应中包含解析后的订单，其中 "flagged": true。工作流承载业务逻辑；通道通过 POST /orders 将其对外开放。路由、验证、追踪和生命周期管理均由 Orion 提供。

如需查看预期输出、故障排查方法、适用于 Windows 的安装方式和清理说明，请参阅完整快速入门。

核心模型

flowchart LR
    Request["HTTP request, Kafka record, or schedule"] --> Channel
    Channel["Channel<br/>route + ingress policy"] --> Workflow
    Workflow["Workflow<br/>ordered business logic"] --> Connector
    Connector["Connector<br/>external system"]
    Workflow --> Response["Response or stored trace"]

原语	用途	示例
通道	接收流量并应用入口策略	POST /orders、Kafka 主题、0 15 2 * * * order.placed
工作流	以有序任务管道的形式运行业务逻辑	解析 → 验证 → 丰富 → 响应
连接器	提供与外部系统的可复用连接	PostgreSQL、Redis、Kafka、REST API

属于同一服务的定义可以一起作为一个包发布。一个 Orion 实例可以并行运行多个包，每个包都有自己的生命周期和发布流程。

Orion 的工作原理通过一个页面介绍请求执行、组合、部署拓扑和扩展边界。

可以构建什么

• 微服务和决策 API： 通过 HTTP 提供转换、验证、定价、资格判定和路由决策。
• Webhook 和数据采集服务： 规范化传入的负载，并通过受管控的连接器读写外部系统。
• Kafka 消费者： 处理记录、发布结果，并将失败消息路由到死信主题。
• AI Agent 工具： 提供受管控的 HTTP 操作，助手可使用 Orion CLI 和 Agent 技能来起草、试运行、激活和回滚这些操作。
• 定时作业： 按 cron 表达式运行工作流，而不是等待请求，并将每个计划执行时刻记录为持久化事件。
• 可组合服务： 使用 channel_call 在进程内调用其他通道，同时保留被调用方的防护措施并防止循环调用。

在 你要构建什么？ 中选择一条明确的路径，或者部署 examples/packages/ 中的经过测试的软件包。

运行时功能

领域	包含的功能
流量	REST、纯 HTTP、同步和异步通道、Kafka 入口、cron 计划
安全	负载验证、API 密钥/HMAC/JWT 通道身份验证、速率限制、背压、CORS 控制
韧性	超时、重试、断路器、幂等性、响应缓存、死信处理
交付	草稿、不可变版本、试运行、按百分比灰度发布、回滚、软件包、WebAssembly 插件、上线前需通过审核的 ONNX 模型
可观测性	健康和就绪端点、Prometheus 指标、结构化日志、OpenTelemetry 跟踪
数据	PostgreSQL、MySQL、SQLite、MongoDB、Elasticsearch、Redis、Kafka、HTTP、SMTP、S3 兼容存储
运维	单节点使用内嵌 SQLite；集群副本使用 PostgreSQL/MySQL 和 Redis

配置明确，其中一些生产控制措施在本地开发时采用宽松设置或处于禁用状态。尤其是，除非数据通道声明了身份验证，或位于提供身份验证的代理之后，否则这些通道默认开放。在公开实例之前，请按照 生产环境检查清单 逐项检查。

安全变更，包括 AI 生成的变更

flowchart LR
    Author --> Draft --> Validate --> DryRun["Dry-run"] --> Activate --> Rollout --> Observe
    Observe -->|problem| Rollback

无论由谁编写，工作流、通道和连接器定义都遵循相同的受管控生命周期。草稿不会处理任何流量。你可以验证并试运行草稿，批准确切版本，无需重启服务即可激活该版本，按百分比逐步放量，并回退到之前的不可变版本。管理变更会记录在审计日志中。

若要借助 AI 编写内容，请安装 Orion Agent 技能 或使用自包含的 提示词包。 Claude Code 教程 将带你完成完整的辅助工作流。

Orion 适用场景

Orion 适用于处理从 HTTP 请求或 Kafka 记录开始、作为有界管道完成，并可通过 Orion 的任务函数和 JSONLogic 表达的服务。当许多小型服务需要相同的运维和治理基础时，Orion 尤其有用。

在以下情况下，请选择其他运行时，或将其与 Orion 配合使用：

• 工作必须在中间步骤后经受重启，或等待数小时或数天；
• 入站流量需要 gRPC、WebSockets 或流式响应；
• 业务逻辑需要任意代码和 I/O，或脚本运行时——纯转换可作为沙箱化 WebAssembly 插件运行；任何需要访问其他系统的逻辑则不行；
• 图像处理、GPU 级推理或大型内存联接位于关键路径上——小型 ONNX 图可作为受治理模型在进程内运行，大型图则不行；或
• 必须在数据平面内终止完整的 OIDC 流程或双向 TLS。JWT 验证是内置的；这些流程则需要网关或服务网格。

阅读Orion 适合你吗？，了解 Orion 与持久执行引擎、API 网关、自动化平台、规则引擎和嵌入式 dataflow-rs 的详细比较。

安装

当前工作区版本为 1.12.0，从源代码构建时需要 Rust 1.98。服务端和 CLI 同步发布；请使用匹配的版本。

# Homebrew: macOS Apple Silicon and Linux
brew install GoPlasmatic/tap/orion-server
brew install GoPlasmatic/tap/orion-cli

# Server from source
cargo install --git https://github.com/GoPlasmatic/Orion --locked orion-server

# Server and CLI from source
cargo install --git https://github.com/GoPlasmatic/Orion --locked \
  orion-server orion-cli

Linux、macOS Apple Silicon 和 Windows 也提供发行版安装程序。请参阅安装与运行，了解所有方式、平台支持、启动和验证步骤。

常用的本地命令：

orion-server validate-config -c config.toml
orion-server fmt ./definitions
orion-server lint workflow.json
orion-server clippy ./definitions
orion-server dry-run -w workflow.json -i input.json
orion-server test examples/workflow-tests
orion-server compile ./definitions -o package.json
orion-server package apply -s http://localhost:8080 -f package.json

服务端命令参考和Orion CLI 参考列出了所有命令和标志。

性能

Orion 1.0.0 发布的基准测试显示，在一台 Apple M2 Pro 实例上，每秒可处理 5.1K–5.7K 个工作流请求；在记录的工作流场景中，平均延迟均为个位数毫秒。这些结果仅适用于特定版本和工作负载，不构成容量保证。请查看基准测试记录，了解硬件、场景、尾延迟、集群结果和复现步骤。

文档

完整手册位于 docs.goplasmatic.io。

目标	从这里开始
试用 Orion	快速入门
理解模型	Orion 的工作原理
构建完整服务	Orders API 黄金路径
查找准确的架构	参考索引
部署和运维	运维 Orion
保障生产环境安全	生产环境检查清单
安全升级	升级
检查兼容性	支持与兼容性

文档源文件位于 docs/src/。请编辑该目录，而不是生成的 docs/book/ 输出。目录结构和编辑规范请参阅 docs/STYLE_GUIDE.md。

项目与社区

• Orion UI 提供基于浏览器的 运维控制台。
• orion-cli 可通过终端管理工作流、频道、连接器、 插件和计划任务。
• CONTRIBUTING.md 介绍开发环境配置、测试和拉取 请求。
• 请通过 GitHub Discussions 提问，通过 GitHub Issues 报告 Bug。
• 请按照 SECURITY.md 中的说明私下报告漏洞。
• 如果你使用 Orion，请将你的项目添加到 ADOPTERS.md。

Orion 由 Plasmatic 构建，并根据 Apache License 2.0 发布。