3条命令跑通实时服务编排系统：iii 完整教程（免费开源）

3条命令跑通实时服务编排系统：iii 完整教程（免费开源）

【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii

iii 是一个实时服务编排引擎：它把队列、定时任务、HTTP 端点、状态存储和 AI 代理，全部变成同一个运行时上可组合的 Worker。跨语言调用、运行中扩展、全链路追踪都是内置能力。这篇文章会用 3 条命令带你从零跑通第一个跨语言系统，再把原理讲透。

服务一多，连线就乱

先想象一个场景：你刚起步的后端只有 3 个服务，看起来还行。然后你要加一个队列、一个定时任务、一套可观测工具、一个 AI 代理……

每加一个组件，它就要和已有的每个组件对上一次线。4 个服务产生 6 条集成边，20 个服务就是 190 条。新能力带来的不是线性成本，而是平方级的协调成本。而且每个新工具都自带一套集成故事：队列要选型、代理要单独配重试和超时、可观测工具要逐个接。

iii（实时服务编排引擎）的思路是反过来：所有服务不再两两互连，而是都接到同一个共享运行时上。服务数量翻倍，集成工作量不变。

图：左边是传统点对点集成（8 个服务 = 45 条定制集成），右边是 iii 的方式——所有 Worker 通过共享运行时互联，一个统一的系统表面。

三个原语：Worker、Trigger、Function

理解 iii 只需要记住三个词，这也是它全部的心智模型：

• Worker：一个跑着的进程。TypeScript 的 API 服务是 Worker，Python 的数据管道是 Worker，Rust 微服务也是。它跑在你本机、云端、浏览器标签页，甚至硬件隔离的 microVM 里，都算同一种东西。
• Trigger：任何"让函数跑起来"的事。可以是 HTTP 请求、cron 时刻、队列消息、状态变更，也可以是流事件。
• Function：一个有稳定名字的工作单元，比如orders::validate。它收输入、干活、返回输出。

你写的代码只做一件事：声明"当某件事发生时，运行这个函数"。路由、序列化、投递这些脏活，engine 全包了。

这带来一个很实际的好处：iii worker add有点像npm install，但装进来的不是一个依赖包，而是一个完整运行中的服务——一个队列、一个沙箱、一个分类器。一条命令，一项能力立即可用，系统里其他所有 Worker 马上能调。平台团队发布 Worker，应用团队注册函数，两边守同一份契约，中间那层"各写各的胶水代码"直接消失了。

模型讲完了，我们直接把它跑起来。

⚡ 2 分钟装好并跑通

整个上手过程就三段命令。

先装 engine，一行官方安装脚本：

curl -fsSL https://install.iii.dev/iii/main/install.sh | sh

然后生成一个跨语言示例项目并启动。这个模板自带两个 Worker：一个 Python 写的加法器，一个 TypeScript 写的 HTTP 调用方。

iii project init myapp --template quickstart cd myapp iii --config config.yaml

engine 起来后会监听ws://localhost:49134。再开一个终端，把两个 Worker 接进来，然后发起第一次调用：

iii worker add ./workers/math-worker iii worker add ./workers/caller-worker iii trigger math::add_two_numbers a=10 b=20

你会看到返回{ "c": 30 }。

对，刚才那条命令里，TypeScript 进程通过 engine 调用了 Python 进程。两个语言、两个进程，互相没有任何直接依赖。

顺带一提：再执行一条iii worker add state，系统就多了持久化的键值存储，之前的加法函数会开始自动累加 running_total。想要一次性拉起一组 Worker，把它们写进worker-compose.yaml，然后iii compose --up一条命令全启动。

（小提醒：Linux 上如果看到KVM not accessible，说明 Worker 的 microVM 拿不到/dev/kvm，官方 troubleshooting 里有解法。）

跑通了你可能会有个疑问：这两个不同语言的进程，为什么能像调本地函数一样互调？我们拆开 engine 看看。

🔍 Engine 内部：一次调用是怎么路由的

engine 是个 Rust 写的核心运行时，职责就三件：

1. 接连接。每个 Worker 启动时通过 WebSocket 连上来，engine 维护一份"活注册表"，记录现在有谁在线。
2. 记目录。每个 Worker 注册了自己的 Function 和 Trigger 后，engine 把它们合并成一个系统级的统一目录——谁有什么能力，一眼可查，而且永远和线上真实状态一致。
3. 做路由。Trigger 触发或者某个 Function 被调用时，engine 在注册表里找到提供目标 Function 的 Worker，把调用派过去。

所以iii trigger math::add_two_numbers的完整路径是：engine 查到这个函数属于 TypeScript Worker，派给它；TS 代码里对 Python Worker 的math::add只是一次普通调用，序列化、跨语言边界、投递全部被 engine 抹掉了。

关键是：这条路由路径跟语言、运行时、位置都无关。笔记本上的 Python 代理、浏览器标签页里的 TS Worker、microVM 里的 Rust 二进制、K8s 上的 OCI 镜像，走的是一模一样的路。

engine 还在运行时盯着config.yaml：文件一变，它自动解析、diff、只重启有变化的 Worker，没动的继续跑，热加载零停机。

图：engine 和内置的 Streams、REST API、Events 模块居中，Node.js 与 Python 的 Worker 各自通过 bridge layer 接入，底层数据经 Redis 适配器共享。

原理看明白了，接下来跟一个真实请求走一遍，比抽象描述直观得多。

跟一个请求：从触发到状态落库

第一个场景，跨语言求和。

• 输入：iii trigger math::add_two_numbers a=10 b=20
• 中间：engine 路由到 TypeScript Worker → 它通过 engine 调用 Python Worker 的math::add→ Python 算出 30 并写回 → 加上 state Worker 后，每次调用还会读旧值、累加、写回running_total
• 输出：{ "c": 30, "running_total": 35 }，累加值跨调用持久保存

第二个场景，客服工单流。

假设线上跑着 5 个 Worker 组成的工单系统：

• 输入：用户通过 API 提交一张工单
• 中间：CreateTicket把工单入队；TriageTicket挂着多个 Trigger（队列来单自动分诊、人工分诊、cron 兜底扫单）；SLAMonitor定时检查超时工单；EscalateTicket把违约的单子升级；NotifyCustomer在分诊完成时发通知
• 输出：用户收到通知，而你在 Console 的 FLOW 视图里能看到这 5 个节点之间的触发关系和实时执行状态

图：Console 的 FLOW 视图，support-ticket-flow 中每个步骤挂了什么 Trigger、当前在线状态，一目了然。

这张截图背后是 iii 的观测面：不只是"能看到"，而是 Worker、Trigger、队列、状态、追踪、日志全都实时可见。

命令行之外：Console、浏览器 Worker 与 AI 代理

跑顺之后，你会用到这三块增值能力：

Console（React + Rust 写的开发者控制台）：仪表盘、Worker 列表、Trigger、队列、带火焰图的 Traces、日志、实时状态，全部在一个界面里。改配置、调函数、查链路不用切五个工具。

多语言 SDK：Node（npm install iii-sdk）、Python（pip install iii-sdk）、Rust 和 Go 各有 SDK，源码都在 sdk/。Worker 写在哪种语言里都行，engine 不关心。

浏览器也是 Worker：前端标签页可以作为一个 Worker 接入，一条 WebSocket 连接就和后端状态保持实时同步。下面这个 Todo 应用就是这么做的——"This is realtime" 那一条加进去，界面立刻变。

图：基于 iii 的 Todo 应用，浏览器前端作为 Worker 单连接接入，与后端状态实时同步。

AI 代理是 Worker：这是 iii 最不一样的一点。在 iii 里，代理不是被圈在某个单独的 agent 运行时里——它就是系统里的一个 Worker。它的工具是 Function，记忆是 State，编排是 Trigger。当代理遇到系统还缺的能力时，它可以直接在运行时注册一个新 Worker，扩展自己正在工作的这套系统。人类和代理共享同一套心智模型，新同学第一天就能上手，AI 也能在单个上下文窗口里可靠地理解整个系统。

配套地，仓库里有一份代理可读的参考材料，覆盖 HTTP、队列、cron、状态、流等所有原语：npx skills add iii-hq/iii/skills一键安装，列表在 skills/。

开始你的第一个 Worker

核心代码、文档、SDK 都在这个仓库里：

• 完整文档：docs/
• engine 源码：engine/
• 开发者控制台：console/
• 四语言 SDK：sdk/
• 代理参考材料：skills/

engine 开源、SDK 免费。别收藏了，去把开头那 3 条命令敲一遍——两分钟后，你手里就有一个跑得起来的实时服务编排系统。

【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii