iii 引擎实战指南从 Function/Trigger/Worker 三大原语到安装、配置与 WebSocket 协议【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本指南以仓库 engine/README.md 为主线深入讲解 iii 引擎的核心抽象、安装启动、配置文件、Docker 部署、端口与 WebSocket 协议并结合 engine/src 目录下的 Rust 源码CLI 入口、引擎内核、协议定义、安全配置进行源码级佐证。读完本文你将掌握 iii 引擎从零启动到生产部署的完整路径并理解引擎与 SDK Worker 之间基于 JSON 消息的调用协议。引擎定位基于三大原语的实时编排系统iii 引擎engine是一个提供**持久化编排durable orchestration、跨语言互操作执行interoperable cross-language execution、功能实时发现live discovery of functionality、系统实时可扩展live system extensibility与系统实时可观测live system observability**的进程通信引擎。它只依赖三个简单原语即可组合出完整系统Function函数可被调用、可被发现的最小执行单元。SDK Worker 通过 WebSocket 向引擎注册函数引擎维护全局函数注册表FunctionsRegistry并按(namespace, function_id)路由调用。Trigger触发器把外部事件HTTP 请求、定时任务、队列消息、状态变更等绑定到函数上的机制。引擎维护触发器注册表TriggerRegistry事件到达时驱动目标函数执行。Worker工作进程承载函数与触发器的运行时进程。可以是 Node.js、Python、Rust 等任意语言的 SDK 进程通过 WebSocket 长连接接入引擎也可以是引擎内置的模块 WorkerAPI、队列、流、可观测性等。从源码结构看引擎内核将这三类原语的注册与路由集中管理engine/src/engine/mod.rs 中的Engine结构体同时持有worker_registry、functionsFunctionsRegistry、trigger_registryTriggerRegistry、service_registryServicesRegistry与invocationsInvocationHandler等核心注册表所有 Worker 连接和函数调用都汇聚于此构成一个请求进入 → 路由到 Worker → 响应返回的实时路由器。安装 iii 引擎与版本验证README 提供了一条官方一键安装命令curl -fsSL https://install.iii.dev/iii/main/install.sh | sh该命令安装的是包含全部 CLI 命令的 iii 引擎二进制engine 与 CLI 是同一个iii二进制。仓库内同时保留了安装脚本本体可查阅 engine/install.sh 了解其实现逻辑。自定义安装目录或锁定版本覆盖安装目录或锁定版本指定安装到$HOME/.local/bincurl -fsSL https://install.iii.dev/iii/main/install.sh | BIN_DIR$HOME/.local/bin sh锁定具体版本例如 v0.11.3curl -fsSL https://install.iii.dev/iii/main/install.sh | sh -s -- v0.11.3验证安装command -v iii iii --versioniii --version会打印CARGO_PKG_VERSION见 engine/src/main.rs。该文件是整个 CLI 的入口iii二进制基于 clap 解析子命令并支持--config path、--version、--no-update-check等全局参数。启动引擎默认模式、配置文件与 Console直接启动README 记载了iii --use-default-config的启动方式但需要说明的是该标志在当前仓库源码中已被移除。main.rs的单元测试use_default_config_is_no_longer_a_flag明确断言--use-default-config不再可解析engine/src/main.rs其职责由iii在缺少config.yaml时自动创建取代。因此当前版本直接运行iii不带任何子命令时CLI 进入 serve 模式启动引擎run_serve见 engine/src/main.rs。启动流程为计算配置文件路径显式--config优先否则默认config.yaml若文件不存在交互式终端会询问是否创建避免在错误目录静默写入容器/CI 等非交互会话则自动创建写入一个空workers:列表的起始配置EngineConfig::starter_config_yaml()见ensure_config_file加载配置、初始化日志通过EngineBuilder构建引擎并serve()。该行为与文档 docs/using-iii/engine.mdx 一致引擎自带 WebSocket 监听、配置 Worker 与可观测性等内部服务其余能力通过iii worker add name按需开启。使用项目配置文件项目化部署时在工作目录创建config.yaml或显式指定路径iii --config /path/to/config.yaml如果偏好自定义文件名例如iii-config.yaml显式传入即可iii --config /path/to/iii-config.yaml打开控制台iii console引擎启动后运行在ws://localhost:49134HTTP API 位于http://localhost:3111。iii console会拉起 Web 控制台其前端工程位于 console/packages/console-frontend用于实时观察函数、触发器和调用链路。引擎即路由器config.yaml 配置深度解析iii 引擎从项目根目录的config.yaml启动配置结构非常收敛顶层只有一个workers:键列出引擎需要加载的 Workerdocs/using-iii/engine.mdx 称其为first-boot seed——首次启动种子配置。仓库自带的示例配置 engine/config.yaml 展示了完整形态registration_namespace_grace_ms: 5000 # Only workers that are part of the engine lifecycle belong here. Project # workers such as http, state, cron, queue, pubsub, and bridge belong in # worker-compose.yaml. workers: - name: iii-stream config: port: ${STREAM_PORT:3112} host: 127.0.0.1 adapter: name: redis config: redis_url: redis://localhost:6379 - name: configuration config: adapter: name: fs config: directory: ./config ttl_seconds: 0 # Ephemeral sandboxes are an engine-managed exception to worker-compose. # - name: iii-sandbox # config: # auto_install: true # image_allowlist: # - python # - node # default_idle_timeout_secs: 300 # max_concurrent_sandboxes: 32 # default_cpus: 1 # default_memory_mb: 512要点解读workers:列表每个条目有name注册表 slug 或本地 Worker 名和可选的config块。config块只在该 Worker 首次启动时被读取一次作为配置种子写入配置存储此后配置以每个 Worker 一个文件的形式存放在./config/下支持从磁盘、Console 或configuration::set实时修改引擎会把已消费的config:块从config.yaml中移除并留下注释。registration_namespace_grace_ms: 5000全局配置控制 Worker 连接在命名空间确定前的注册缓冲宽限期默认 5 秒。引擎内核通过III_NAMESPACE_GRACE_MS环境变量优先、其次是该配置、最后回退 5 秒默认值来解析见 engine/src/engine/mod.rs。宽限期内命名空间相关的注册消息RegisterFunction、RegisterTrigger等会被排队缓冲等待engine::workers::register调用确定连接命名空间后再按到达顺序落位避免注册被错误归入default命名空间。iii-stream流模块 Worker监听端口支持${STREAM_PORT:3112}环境变量展开默认 3112其 Redis 适配器对应 engine/src/workers/stream/adapters 下的适配器实现。configuration配置 Worker使用文件系统适配器directory: ./configttl_seconds: 0表示条目不过期。注释中的iii-sandbox展示了临时沙箱的示例参数镜像白名单、空闲超时、并发上限、CPU/内存配额实际启用时按需取消注释。环境变量展开配置值支持${VAR:default}语法读取环境变量VAR未设置时回退到default。这允许在不拆分配置文件的前提下按环境切换端口、URL 与功能开关且该语法同样适用于每个 Worker 的独立配置文件workers: - name: http config: port: ${HTTP_PORT:3111} host: ${HTTP_HOST:127.0.0.1}安全配置HTTP 外部调用引擎对外部 HTTP 调用如registerfunction中的invocation指向外部 Lambda/HTTP 端点有独立的安全策略定义于 engine/src/config/mod.rs 的SecurityConfig字段默认值说明url_allowlist[*]空则视为*URL 白名单仅允许调用列表内的地址block_private_ipstrue阻止调用私网 IPSSRF 防护require_httpstrue强制要求 HTTPS 端点配置采用deny_unknown_fields严格解析未知字段会导致加载失败见 engine/src/config/mod.rs 的测试。该配置最终转换为UrlValidatorConfig供调用校验器在每次外部调用前检查目标 URL。Docker 部署基础镜像、生产加固与 Compose 全家桶拉取并运行镜像docker pull iiidev/iii:latest docker run -p 3111:3111 -p 49134:49134 \ -v ./iii-config.yaml:/app/iii-config.yaml:ro \ iiidev/iii:latest镜像的默认启动命令是[/app/iii, --config, /app/config.yaml]见 engine/Dockerfile容器内WORKDIR /appconfig.yaml挂载为只读。生产加固示例docker run --read-only --tmpfs /tmp \ --cap-dropALL --cap-addNET_BIND_SERVICE \ --security-optno-new-privileges:true \ -v ./iii-config.yaml:/app/iii-config.yaml:ro \ -p 3111:3111 -p 49134:49134 -p 3112:3112 -p 9464:9464 \ iiidev/iii:latest该命令体现了镜像的安全设计只读根文件系统 /tmp临时挂载、丢弃全部 Linux capabilities 仅保留NET_BIND_SERVICE绑定 80/443 等低端口、禁止提权。Dockerfile 基于gcr.io/distroless/cc-debian12:nonroot构建以 UID 65532 的非 root 用户运行、无 shell且预创建了/app/config与/app/data目录并设置属主保证配置 Worker 能落盘。CI 中还包含 Trivy 漏洞扫描、SBOM 物料清单证明与构建来源证明build provenance。Docker ComposeRedis RabbitMQ 全家桶仓库提供了完整编排文件 engine/docker-compose.ymldocker compose up -d该栈包含三个服务iii映射 49134/3111/3112/9464 四个端口设置RUST_LOGinfo与III_EXECUTION_CONTEXTdocker依赖 Redis 与 RabbitMQ 健康检查通过后启动、redis:7-alpine队列/流模块的存储后端带redis-cli ping健康检查、rabbitmq:3-management-alpine队列模块的 AMQP 后端默认凭据guest/guest生产环境请用.env覆盖。Docker Compose CaddyTLS 反向代理docker compose -f docker-compose.prod.yml up -dengine/docker-compose.prod.yml 引入了 Caddy 2 作为 TLS 反向代理并通过iii compose --namespace production --up --file /app/worker-compose.yaml以 worker-compose 方式启动项目含nc -z 127.0.0.1 3111健康检查。配套的 engine/Caddyfile 展示了端口到路径的路由映射your-domain.com { handle /api/* { reverse_proxy iii:3111 } handle /streams/* { reverse_proxy iii:3112 } handle /ws { reverse_proxy iii:49134 } handle { reverse_proxy iii:3111 } }即/api/*走 HTTP API、/streams/*走流 API、/ws走 WebSocket、其余兜底回 HTTP API。TLS 证书的申请与续期由 Caddy 自动完成。端口一览与网络拓扑端口服务49134WebSocketWorker 连接3111HTTP API3112Stream API9464Prometheus metrics49134是 SDK Worker 接入引擎的长连接端口承载 JSON 协议消息与遥测帧见下节。3111提供 REST API同时是 Console 的 HTTP 入口与iii triggerCLI 的调用目标。3112是流Stream通道 API对应流模块 Worker 的默认端口${STREAM_PORT:3112}。9464是 Prometheus 指标抓取端点配合可观测性模块engine/src/workers/observability使用。WebSocket 协议消息类型与调用语义引擎与 SDK Worker 之间通过 WebSocket 传输JSON 消息协议 schema 完整定义在 engine/src/protocol.rs 的Message枚举中。README 列出的关键消息类型如下括号内为协议字段名serderename_all lowercase消息方向作用registerfunctionWorker → 引擎注册函数含id、description、request_format/response_format、metadata、可选的invocation外部 HTTP 引用invokefunction双向调用函数携带invocation_id、function_id、data、traceparent/baggage、可选的action、metadata、namespaceinvocationresult引擎 → Worker调用结果携带invocation_id、result或errorErrorBodycodemessage 可选stacktraceregistertriggerWorker → 引擎注册触发器绑定trigger_type、function_id与configunregistertriggerWorker → 引擎注销触发器triggerregistrationresult引擎 → Worker触发器注册结果registerserviceWorker → 引擎注册服务functionsavailable引擎 → Worker函数可用性广播实时发现机制ping/pong双向心跳保活除此之外协议还包含引擎在重连场景下使用的高级消息engine/src/protocol.rsreattachWorker 重连时携带previous_worker_id与reattach_token引擎在上一条连接上通过workerregistered下发的秘密引擎据此退役旧连接、让注册重放落在干净状态上避免与旧连接的清理流程竞争。workerregistered引擎确认 Worker 身份并可附带reattach_token。registrationrejected注册被拒绝如WORKER_NAMESPACE_CONFLICT——同一命名空间已有同名存活 WorkerFUNCTION_NAMESPACE_CONFLICT——同一命名空间已有 Worker 导出该函数 idINVALID_NAMESPACE——命名空间为空白。Fire-and-forget 语义调用可以省略invocation_id实现即发即忘fire-and-forget。引擎内核对此有明确实现InvokeFunction.invocation_id为OptionUuidengine/src/protocol.rsspawn_invoke_function中invocation_id为Some时调用完成后回送InvocationResult为None时则以后台任务方式执行且不回送结果见 engine/src/engine/mod.rs。TriggerAction枚举也与之呼应{type:enqueue,queue:...}表示将调用转投队列{type:void}表示纯异步执行。外部 HTTP 函数registerfunction支持注册外部函数——引擎不经过本地 Worker而是直接对invocation指定的 URL 发起 HTTP 调用。HttpInvocationRefengine/src/protocol.rs包含url、method默认 POST、timeout_ms、headers与auth如 Bearer token 引用协议测试中有完整的注册示例external.my_lambda。这类调用受前述SecurityConfig约束。命名空间显式路由维度协议层面每个消息都可携带namespace字段缺省时落入默认命名空间defaultDEFAULT_NAMESPACE见 engine/src/protocol.rs。引擎的函数解析策略是显式路由维度不做跨命名空间搜索Some(ns)只在ns中解析None只在default中解析。不存在就近匹配调用方的命名空间不参与目标解析——analytics命名空间里的 Worker 若不显式指定命名空间拿到的是default中的函数而不是自己命名空间里的同名函数。见 engine/src/engine/mod.rs 中resolve_function的注释与实现。这样做消除了调用目标取决于谁在提问的歧义函数与 Worker 的注册表均以(namespace, id)为键例如服务注册表ServicesRegistry就以(namespace, service_name)为键engine/src/services.rs保证多个项目在同一引擎上互不覆盖。若函数在目标命名空间缺失引擎返回function_not_found错误码并附带该 id 实际存在于哪些命名空间的提示。可观测性OTLP 帧与 Prometheus除 JSON 协议消息外WebSocket 连接还支持三类二进制遥测帧通过魔数前缀区分见 engine/src/engine/mod.rs前缀内容OTLPTrace 追踪OTLP JSONMTRCMetrics 指标OTLP JSONLOGSLogs 日志OTLP JSONSDK 直接将 OpenTelemetry 数据以带前缀的二进制帧推送给引擎由handle_telemetry_frame分派到ingest_otlp_json/ingest_otlp_metrics/ingest_otlp_logs处理engine/src/engine/mod.rs。InvokeFunction与InvocationResult携带 W3Ctraceparent/baggage实现跨 Worker、跨进程的分布式追踪上下文传播指标则通过 9464 端口暴露给 Prometheus 抓取。README 提到引擎内置 in-memory OpenTelemetry 配置无需先创建 config.yaml 即可获得 traces/metrics/logs——结合上文可知当前版本中这一默认能力由引擎内置的可观测性服务承担启动即具备。仓库结构与源码导览README 给出的仓库布局当前仓库已将其中的src/modules/演进为src/workers/下的多个 Worker 目录engine/src/main.rs – CLI 入口iii二进制trigger别名t、console、cloud、project init/project generate-docker、compose、update等子命令缺省为 serve 模式启动引擎engine/src/engine/mod.rs – 引擎内核Worker 管理、函数/触发器/服务注册表、命名空间解析、调用生命周期Engine结构体与EngineTraitengine/src/protocol.rs – WebSocket 消息 schemaMessage枚举、ErrorBody、WorkerMetrics、HttpInvocationRefengine/src/workers – 核心模块 Workerhttp_functionsHTTP 函数、queue队列含 Redis/RabbitMQ 等适配器、stream流含适配器、observability可观测性OTLP 导出、指标、追踪存储与 UI、configuration配置存储、engine_fn、worker等engine/config.yaml – 示例模块配置engine/examples/custom_queue_adapter.rs – 自定义模块与适配器示例engine/tests – 端到端测试集例如cli_integration.rs、configuration_e2e.rs、queue_e2e_happy_path.rs、namespace_routing_e2e.rs、worker_ws_handshake_timeout_test.rs覆盖 CLI、配置加载、队列、命名空间路由与 WebSocket 握手等行为。各语言 SDK 位于 sdk/packages/node、sdk/packages/python、sdk/packages/rustREADME 中的安装命令对应如下语言包名安装命令Node.jsiii-sdkpnpm add iii-sdk或npm install iii-sdkPythoniii-sdkpip install iii-sdkRustiii-sdk在Cargo.toml中添加依赖本地开发与镜像构建cargo run # 启动引擎 cargo run -- --config iii-config.yaml # 带配置启动 cargo fmt cargo clippy -- -D warnings # 格式化与 Lint make watch # 监听模式文件变更自动重编译本地构建 Docker 镜像docker build -t iii:local . # 生产镜像distroless docker build -f Dockerfile.debug -t iii:debug . # 调试镜像Debian shell生产镜像的安全基线已在生产加固一节说明distroless 无 shell 运行时、非 root 执行、CI 中的 Trivy 扫描、SBOM 证明与构建来源证明。快速上手与后续阅读从零开始构建参阅 docs/quickstart.mdx 与 docs/tutorials 下的分步教程引擎配置详解参阅 docs/using-iii/engine.mdx 与 docs/using-iii/configuration.mdxCLI 参考参阅 docs/cli-reference/index.mdx函数与触发器开发参阅 docs/creating-workers 与 docs/using-iii/functions.mdx多服务编排worker-compose参阅 crates/iii-compose 与 docs/upgrading。许可证iii 引擎采用 Elastic License 2.0ELv2同时包含专利声明engine/PATENTS与商标声明engine/NOTICE仓库根目录另有一份 SPDX 许可证清单 LICENSE.spdx。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
iii 引擎实战指南：从 Function/Trigger/Worker 三大原语到安装、配置与 WebSocket 协议
iii 引擎实战指南从 Function/Trigger/Worker 三大原语到安装、配置与 WebSocket 协议【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本指南以仓库 engine/README.md 为主线深入讲解 iii 引擎的核心抽象、安装启动、配置文件、Docker 部署、端口与 WebSocket 协议并结合 engine/src 目录下的 Rust 源码CLI 入口、引擎内核、协议定义、安全配置进行源码级佐证。读完本文你将掌握 iii 引擎从零启动到生产部署的完整路径并理解引擎与 SDK Worker 之间基于 JSON 消息的调用协议。引擎定位基于三大原语的实时编排系统iii 引擎engine是一个提供**持久化编排durable orchestration、跨语言互操作执行interoperable cross-language execution、功能实时发现live discovery of functionality、系统实时可扩展live system extensibility与系统实时可观测live system observability**的进程通信引擎。它只依赖三个简单原语即可组合出完整系统Function函数可被调用、可被发现的最小执行单元。SDK Worker 通过 WebSocket 向引擎注册函数引擎维护全局函数注册表FunctionsRegistry并按(namespace, function_id)路由调用。Trigger触发器把外部事件HTTP 请求、定时任务、队列消息、状态变更等绑定到函数上的机制。引擎维护触发器注册表TriggerRegistry事件到达时驱动目标函数执行。Worker工作进程承载函数与触发器的运行时进程。可以是 Node.js、Python、Rust 等任意语言的 SDK 进程通过 WebSocket 长连接接入引擎也可以是引擎内置的模块 WorkerAPI、队列、流、可观测性等。从源码结构看引擎内核将这三类原语的注册与路由集中管理engine/src/engine/mod.rs 中的Engine结构体同时持有worker_registry、functionsFunctionsRegistry、trigger_registryTriggerRegistry、service_registryServicesRegistry与invocationsInvocationHandler等核心注册表所有 Worker 连接和函数调用都汇聚于此构成一个请求进入 → 路由到 Worker → 响应返回的实时路由器。安装 iii 引擎与版本验证README 提供了一条官方一键安装命令curl -fsSL https://install.iii.dev/iii/main/install.sh | sh该命令安装的是包含全部 CLI 命令的 iii 引擎二进制engine 与 CLI 是同一个iii二进制。仓库内同时保留了安装脚本本体可查阅 engine/install.sh 了解其实现逻辑。自定义安装目录或锁定版本覆盖安装目录或锁定版本指定安装到$HOME/.local/bincurl -fsSL https://install.iii.dev/iii/main/install.sh | BIN_DIR$HOME/.local/bin sh锁定具体版本例如 v0.11.3curl -fsSL https://install.iii.dev/iii/main/install.sh | sh -s -- v0.11.3验证安装command -v iii iii --versioniii --version会打印CARGO_PKG_VERSION见 engine/src/main.rs。该文件是整个 CLI 的入口iii二进制基于 clap 解析子命令并支持--config path、--version、--no-update-check等全局参数。启动引擎默认模式、配置文件与 Console直接启动README 记载了iii --use-default-config的启动方式但需要说明的是该标志在当前仓库源码中已被移除。main.rs的单元测试use_default_config_is_no_longer_a_flag明确断言--use-default-config不再可解析engine/src/main.rs其职责由iii在缺少config.yaml时自动创建取代。因此当前版本直接运行iii不带任何子命令时CLI 进入 serve 模式启动引擎run_serve见 engine/src/main.rs。启动流程为计算配置文件路径显式--config优先否则默认config.yaml若文件不存在交互式终端会询问是否创建避免在错误目录静默写入容器/CI 等非交互会话则自动创建写入一个空workers:列表的起始配置EngineConfig::starter_config_yaml()见ensure_config_file加载配置、初始化日志通过EngineBuilder构建引擎并serve()。该行为与文档 docs/using-iii/engine.mdx 一致引擎自带 WebSocket 监听、配置 Worker 与可观测性等内部服务其余能力通过iii worker add name按需开启。使用项目配置文件项目化部署时在工作目录创建config.yaml或显式指定路径iii --config /path/to/config.yaml如果偏好自定义文件名例如iii-config.yaml显式传入即可iii --config /path/to/iii-config.yaml打开控制台iii console引擎启动后运行在ws://localhost:49134HTTP API 位于http://localhost:3111。iii console会拉起 Web 控制台其前端工程位于 console/packages/console-frontend用于实时观察函数、触发器和调用链路。引擎即路由器config.yaml 配置深度解析iii 引擎从项目根目录的config.yaml启动配置结构非常收敛顶层只有一个workers:键列出引擎需要加载的 Workerdocs/using-iii/engine.mdx 称其为first-boot seed——首次启动种子配置。仓库自带的示例配置 engine/config.yaml 展示了完整形态registration_namespace_grace_ms: 5000 # Only workers that are part of the engine lifecycle belong here. Project # workers such as http, state, cron, queue, pubsub, and bridge belong in # worker-compose.yaml. workers: - name: iii-stream config: port: ${STREAM_PORT:3112} host: 127.0.0.1 adapter: name: redis config: redis_url: redis://localhost:6379 - name: configuration config: adapter: name: fs config: directory: ./config ttl_seconds: 0 # Ephemeral sandboxes are an engine-managed exception to worker-compose. # - name: iii-sandbox # config: # auto_install: true # image_allowlist: # - python # - node # default_idle_timeout_secs: 300 # max_concurrent_sandboxes: 32 # default_cpus: 1 # default_memory_mb: 512要点解读workers:列表每个条目有name注册表 slug 或本地 Worker 名和可选的config块。config块只在该 Worker 首次启动时被读取一次作为配置种子写入配置存储此后配置以每个 Worker 一个文件的形式存放在./config/下支持从磁盘、Console 或configuration::set实时修改引擎会把已消费的config:块从config.yaml中移除并留下注释。registration_namespace_grace_ms: 5000全局配置控制 Worker 连接在命名空间确定前的注册缓冲宽限期默认 5 秒。引擎内核通过III_NAMESPACE_GRACE_MS环境变量优先、其次是该配置、最后回退 5 秒默认值来解析见 engine/src/engine/mod.rs。宽限期内命名空间相关的注册消息RegisterFunction、RegisterTrigger等会被排队缓冲等待engine::workers::register调用确定连接命名空间后再按到达顺序落位避免注册被错误归入default命名空间。iii-stream流模块 Worker监听端口支持${STREAM_PORT:3112}环境变量展开默认 3112其 Redis 适配器对应 engine/src/workers/stream/adapters 下的适配器实现。configuration配置 Worker使用文件系统适配器directory: ./configttl_seconds: 0表示条目不过期。注释中的iii-sandbox展示了临时沙箱的示例参数镜像白名单、空闲超时、并发上限、CPU/内存配额实际启用时按需取消注释。环境变量展开配置值支持${VAR:default}语法读取环境变量VAR未设置时回退到default。这允许在不拆分配置文件的前提下按环境切换端口、URL 与功能开关且该语法同样适用于每个 Worker 的独立配置文件workers: - name: http config: port: ${HTTP_PORT:3111} host: ${HTTP_HOST:127.0.0.1}安全配置HTTP 外部调用引擎对外部 HTTP 调用如registerfunction中的invocation指向外部 Lambda/HTTP 端点有独立的安全策略定义于 engine/src/config/mod.rs 的SecurityConfig字段默认值说明url_allowlist[*]空则视为*URL 白名单仅允许调用列表内的地址block_private_ipstrue阻止调用私网 IPSSRF 防护require_httpstrue强制要求 HTTPS 端点配置采用deny_unknown_fields严格解析未知字段会导致加载失败见 engine/src/config/mod.rs 的测试。该配置最终转换为UrlValidatorConfig供调用校验器在每次外部调用前检查目标 URL。Docker 部署基础镜像、生产加固与 Compose 全家桶拉取并运行镜像docker pull iiidev/iii:latest docker run -p 3111:3111 -p 49134:49134 \ -v ./iii-config.yaml:/app/iii-config.yaml:ro \ iiidev/iii:latest镜像的默认启动命令是[/app/iii, --config, /app/config.yaml]见 engine/Dockerfile容器内WORKDIR /appconfig.yaml挂载为只读。生产加固示例docker run --read-only --tmpfs /tmp \ --cap-dropALL --cap-addNET_BIND_SERVICE \ --security-optno-new-privileges:true \ -v ./iii-config.yaml:/app/iii-config.yaml:ro \ -p 3111:3111 -p 49134:49134 -p 3112:3112 -p 9464:9464 \ iiidev/iii:latest该命令体现了镜像的安全设计只读根文件系统 /tmp临时挂载、丢弃全部 Linux capabilities 仅保留NET_BIND_SERVICE绑定 80/443 等低端口、禁止提权。Dockerfile 基于gcr.io/distroless/cc-debian12:nonroot构建以 UID 65532 的非 root 用户运行、无 shell且预创建了/app/config与/app/data目录并设置属主保证配置 Worker 能落盘。CI 中还包含 Trivy 漏洞扫描、SBOM 物料清单证明与构建来源证明build provenance。Docker ComposeRedis RabbitMQ 全家桶仓库提供了完整编排文件 engine/docker-compose.ymldocker compose up -d该栈包含三个服务iii映射 49134/3111/3112/9464 四个端口设置RUST_LOGinfo与III_EXECUTION_CONTEXTdocker依赖 Redis 与 RabbitMQ 健康检查通过后启动、redis:7-alpine队列/流模块的存储后端带redis-cli ping健康检查、rabbitmq:3-management-alpine队列模块的 AMQP 后端默认凭据guest/guest生产环境请用.env覆盖。Docker Compose CaddyTLS 反向代理docker compose -f docker-compose.prod.yml up -dengine/docker-compose.prod.yml 引入了 Caddy 2 作为 TLS 反向代理并通过iii compose --namespace production --up --file /app/worker-compose.yaml以 worker-compose 方式启动项目含nc -z 127.0.0.1 3111健康检查。配套的 engine/Caddyfile 展示了端口到路径的路由映射your-domain.com { handle /api/* { reverse_proxy iii:3111 } handle /streams/* { reverse_proxy iii:3112 } handle /ws { reverse_proxy iii:49134 } handle { reverse_proxy iii:3111 } }即/api/*走 HTTP API、/streams/*走流 API、/ws走 WebSocket、其余兜底回 HTTP API。TLS 证书的申请与续期由 Caddy 自动完成。端口一览与网络拓扑端口服务49134WebSocketWorker 连接3111HTTP API3112Stream API9464Prometheus metrics49134是 SDK Worker 接入引擎的长连接端口承载 JSON 协议消息与遥测帧见下节。3111提供 REST API同时是 Console 的 HTTP 入口与iii triggerCLI 的调用目标。3112是流Stream通道 API对应流模块 Worker 的默认端口${STREAM_PORT:3112}。9464是 Prometheus 指标抓取端点配合可观测性模块engine/src/workers/observability使用。WebSocket 协议消息类型与调用语义引擎与 SDK Worker 之间通过 WebSocket 传输JSON 消息协议 schema 完整定义在 engine/src/protocol.rs 的Message枚举中。README 列出的关键消息类型如下括号内为协议字段名serderename_all lowercase消息方向作用registerfunctionWorker → 引擎注册函数含id、description、request_format/response_format、metadata、可选的invocation外部 HTTP 引用invokefunction双向调用函数携带invocation_id、function_id、data、traceparent/baggage、可选的action、metadata、namespaceinvocationresult引擎 → Worker调用结果携带invocation_id、result或errorErrorBodycodemessage 可选stacktraceregistertriggerWorker → 引擎注册触发器绑定trigger_type、function_id与configunregistertriggerWorker → 引擎注销触发器triggerregistrationresult引擎 → Worker触发器注册结果registerserviceWorker → 引擎注册服务functionsavailable引擎 → Worker函数可用性广播实时发现机制ping/pong双向心跳保活除此之外协议还包含引擎在重连场景下使用的高级消息engine/src/protocol.rsreattachWorker 重连时携带previous_worker_id与reattach_token引擎在上一条连接上通过workerregistered下发的秘密引擎据此退役旧连接、让注册重放落在干净状态上避免与旧连接的清理流程竞争。workerregistered引擎确认 Worker 身份并可附带reattach_token。registrationrejected注册被拒绝如WORKER_NAMESPACE_CONFLICT——同一命名空间已有同名存活 WorkerFUNCTION_NAMESPACE_CONFLICT——同一命名空间已有 Worker 导出该函数 idINVALID_NAMESPACE——命名空间为空白。Fire-and-forget 语义调用可以省略invocation_id实现即发即忘fire-and-forget。引擎内核对此有明确实现InvokeFunction.invocation_id为OptionUuidengine/src/protocol.rsspawn_invoke_function中invocation_id为Some时调用完成后回送InvocationResult为None时则以后台任务方式执行且不回送结果见 engine/src/engine/mod.rs。TriggerAction枚举也与之呼应{type:enqueue,queue:...}表示将调用转投队列{type:void}表示纯异步执行。外部 HTTP 函数registerfunction支持注册外部函数——引擎不经过本地 Worker而是直接对invocation指定的 URL 发起 HTTP 调用。HttpInvocationRefengine/src/protocol.rs包含url、method默认 POST、timeout_ms、headers与auth如 Bearer token 引用协议测试中有完整的注册示例external.my_lambda。这类调用受前述SecurityConfig约束。命名空间显式路由维度协议层面每个消息都可携带namespace字段缺省时落入默认命名空间defaultDEFAULT_NAMESPACE见 engine/src/protocol.rs。引擎的函数解析策略是显式路由维度不做跨命名空间搜索Some(ns)只在ns中解析None只在default中解析。不存在就近匹配调用方的命名空间不参与目标解析——analytics命名空间里的 Worker 若不显式指定命名空间拿到的是default中的函数而不是自己命名空间里的同名函数。见 engine/src/engine/mod.rs 中resolve_function的注释与实现。这样做消除了调用目标取决于谁在提问的歧义函数与 Worker 的注册表均以(namespace, id)为键例如服务注册表ServicesRegistry就以(namespace, service_name)为键engine/src/services.rs保证多个项目在同一引擎上互不覆盖。若函数在目标命名空间缺失引擎返回function_not_found错误码并附带该 id 实际存在于哪些命名空间的提示。可观测性OTLP 帧与 Prometheus除 JSON 协议消息外WebSocket 连接还支持三类二进制遥测帧通过魔数前缀区分见 engine/src/engine/mod.rs前缀内容OTLPTrace 追踪OTLP JSONMTRCMetrics 指标OTLP JSONLOGSLogs 日志OTLP JSONSDK 直接将 OpenTelemetry 数据以带前缀的二进制帧推送给引擎由handle_telemetry_frame分派到ingest_otlp_json/ingest_otlp_metrics/ingest_otlp_logs处理engine/src/engine/mod.rs。InvokeFunction与InvocationResult携带 W3Ctraceparent/baggage实现跨 Worker、跨进程的分布式追踪上下文传播指标则通过 9464 端口暴露给 Prometheus 抓取。README 提到引擎内置 in-memory OpenTelemetry 配置无需先创建 config.yaml 即可获得 traces/metrics/logs——结合上文可知当前版本中这一默认能力由引擎内置的可观测性服务承担启动即具备。仓库结构与源码导览README 给出的仓库布局当前仓库已将其中的src/modules/演进为src/workers/下的多个 Worker 目录engine/src/main.rs – CLI 入口iii二进制trigger别名t、console、cloud、project init/project generate-docker、compose、update等子命令缺省为 serve 模式启动引擎engine/src/engine/mod.rs – 引擎内核Worker 管理、函数/触发器/服务注册表、命名空间解析、调用生命周期Engine结构体与EngineTraitengine/src/protocol.rs – WebSocket 消息 schemaMessage枚举、ErrorBody、WorkerMetrics、HttpInvocationRefengine/src/workers – 核心模块 Workerhttp_functionsHTTP 函数、queue队列含 Redis/RabbitMQ 等适配器、stream流含适配器、observability可观测性OTLP 导出、指标、追踪存储与 UI、configuration配置存储、engine_fn、worker等engine/config.yaml – 示例模块配置engine/examples/custom_queue_adapter.rs – 自定义模块与适配器示例engine/tests – 端到端测试集例如cli_integration.rs、configuration_e2e.rs、queue_e2e_happy_path.rs、namespace_routing_e2e.rs、worker_ws_handshake_timeout_test.rs覆盖 CLI、配置加载、队列、命名空间路由与 WebSocket 握手等行为。各语言 SDK 位于 sdk/packages/node、sdk/packages/python、sdk/packages/rustREADME 中的安装命令对应如下语言包名安装命令Node.jsiii-sdkpnpm add iii-sdk或npm install iii-sdkPythoniii-sdkpip install iii-sdkRustiii-sdk在Cargo.toml中添加依赖本地开发与镜像构建cargo run # 启动引擎 cargo run -- --config iii-config.yaml # 带配置启动 cargo fmt cargo clippy -- -D warnings # 格式化与 Lint make watch # 监听模式文件变更自动重编译本地构建 Docker 镜像docker build -t iii:local . # 生产镜像distroless docker build -f Dockerfile.debug -t iii:debug . # 调试镜像Debian shell生产镜像的安全基线已在生产加固一节说明distroless 无 shell 运行时、非 root 执行、CI 中的 Trivy 扫描、SBOM 证明与构建来源证明。快速上手与后续阅读从零开始构建参阅 docs/quickstart.mdx 与 docs/tutorials 下的分步教程引擎配置详解参阅 docs/using-iii/engine.mdx 与 docs/using-iii/configuration.mdxCLI 参考参阅 docs/cli-reference/index.mdx函数与触发器开发参阅 docs/creating-workers 与 docs/using-iii/functions.mdx多服务编排worker-compose参阅 crates/iii-compose 与 docs/upgrading。许可证iii 引擎采用 Elastic License 2.0ELv2同时包含专利声明engine/PATENTS与商标声明engine/NOTICE仓库根目录另有一份 SPDX 许可证清单 LICENSE.spdx。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考