iii-engine-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Engine Config

引擎配置

Comparable to: Infrastructure as code, Docker Compose configs

可类比于：Infrastructure as code、Docker Compose 配置

Key Concepts

核心概念

Use the concepts below when they fit the task. Not every deployment needs all modules or adapters.

iii-config.yaml defines the engine port, modules, workers, adapters, and queue configs
Environment variables use
```
${VAR:default}
```
syntax (default is optional)
Modules are the building blocks — each enables a capability (API, state, queue, cron, etc.)
Workers are external binary modules managed via
```
iii.toml
```
and the
```
iii worker
```
CLI commands
Adapters swap storage backends per module: in_memory, file_based, Redis, RabbitMQ
Queue configs control retry count, concurrency, ordering, and backoff per named queue
The engine listens on port 49134 (WebSocket) for SDK/worker connections

根据任务需求选用以下概念，并非所有部署都需要全部模块或适配器。

iii-config.yaml 定义引擎端口、模块、Worker、适配器和队列配置
环境变量 使用
```
${VAR:default}
```
语法（默认值为可选）
模块是构建基础组件——每个模块对应一项功能（API、状态管理、队列、定时任务等）
Worker 是通过
```
iii.toml
```
和
```
iii worker
```
CLI 命令管理的外部二进制模块
适配器 为各模块切换存储后端：in_memory、file_based、Redis、RabbitMQ
队列配置 按命名队列控制重试次数、并发数、排序规则和退避策略
引擎通过端口 49134（WebSocket）监听 SDK/Worker 连接

Architecture

架构

The iii-config.yaml file is loaded by the iii engine binary at startup. Modules are initialized in order, adapters connect to their backends, and the engine begins accepting worker connections over WebSocket on port 49134. External workers defined in the

workers

section are spawned as child processes automatically.

iii引擎二进制文件在启动时加载iii-config.yaml文件。模块按顺序初始化，适配器连接对应后端，引擎开始通过端口49134的WebSocket接受Worker连接。

workers

部分定义的外部Worker会自动作为子进程启动。

iii Primitives Used

使用的iii原语

Primitive	Purpose
`modules::api::RestApiModule`	HTTP API server (port 3111)
`modules::stream::StreamModule`	WebSocket streams (port 3112)
`modules::state::StateModule`	Persistent key-value state storage
`modules::queue::QueueModule`	Background job processing with retries
`modules::pubsub::PubSubModule`	In-process event fanout
`modules::cron::CronModule`	Time-based scheduling
`modules::observability::OtelModule`	OpenTelemetry traces, metrics, logs
`modules::http_functions::HttpFunctionsModule`	Outbound HTTP call security
`modules::shell::ExecModule`	Spawn external processes
`modules::bridge_client::BridgeClientModule`	Distributed cross-engine invocation
`modules::telemetry::TelemetryModule`	Anonymous product analytics
`workers` section in iii-config.yaml	External binary workers (worker modules)
`iii.toml`	Worker manifest (name → version)
`iii worker add NAME[@VERSION]`	Install a worker from the registry
`iii worker remove NAME`	Uninstall a worker
`iii worker list`	List installed workers
`iii worker info NAME`	Show registry info for a worker

原语	用途
`modules::api::RestApiModule`	HTTP API 服务器（端口3111）
`modules::stream::StreamModule`	WebSocket 流服务（端口3112）
`modules::state::StateModule`	持久化键值对状态存储
`modules::queue::QueueModule`	带重试机制的后台任务处理
`modules::pubsub::PubSubModule`	进程内事件广播
`modules::cron::CronModule`	基于时间的任务调度
`modules::observability::OtelModule`	OpenTelemetry 链路追踪、指标、日志
`modules::http_functions::HttpFunctionsModule`	出站HTTP调用安全控制
`modules::shell::ExecModule`	启动外部进程
`modules::bridge_client::BridgeClientModule`	分布式跨引擎调用
`modules::telemetry::TelemetryModule`	匿名产品分析统计
iii-config.yaml 中的 `workers` 部分	外部二进制Worker（Worker模块）
`iii.toml`	Worker清单（名称 → 版本）
`iii worker add NAME[@VERSION]`	从注册表安装Worker
`iii worker remove NAME`	卸载Worker
`iii worker list`	列出已安装的Worker
`iii worker info NAME`	显示Worker的注册表信息

Reference Implementation

参考实现

See ../references/iii-config.yaml for the full working example — a complete engine configuration with all modules, adapters, queue configs, and environment variable patterns.

完整的可用示例请查看 ../references/iii-config.yaml —— 包含所有模块、适配器、队列配置和环境变量模式的完整引擎配置。

Common Patterns

常见模式

Code using this pattern commonly includes, when relevant:

```
iii --config ./iii-config.yaml
```
— start the engine with a config file
```
docker pull iiidev/iii:latest
```
— pull the Docker image

Dev storage:

store_method: file_based

with

file_path: ./data/...

Prod storage: Redis adapters with
```
redis_url: ${REDIS_URL}
```
Prod queues: RabbitMQ adapter with
```
amqp_url: ${AMQP_URL}
```
and
```
queue_mode: quorum
```

Queue config:

queue_configs

with

max_retries

concurrency

type

backoff_ms

per queue name

Env var with fallback:
```
port: ${III_PORT:49134}
```
Health check:
```
curl http://localhost:3111/health
```
Ports: 3111 (API), 3112 (streams), 49134 (engine WS), 9464 (Prometheus)

相关场景下，使用本模式的代码通常包含以下内容：

```
iii --config ./iii-config.yaml
```
—— 通过配置文件启动引擎
```
docker pull iiidev/iii:latest
```
—— 拉取Docker镜像

开发环境存储：

store_method: file_based

搭配

file_path: ./data/...

生产环境存储：Redis适配器，配置
```
redis_url: ${REDIS_URL}
```
生产环境队列：RabbitMQ适配器，配置
```
amqp_url: ${AMQP_URL}
```
和
```
queue_mode: quorum
```

队列配置：

queue_configs

按队列名称设置

max_retries

、

concurrency

、

type

、

backoff_ms

带默认值的环境变量：
```
port: ${III_PORT:49134}
```
健康检查：
```
curl http://localhost:3111/health
```
端口：3111（API）、3112（流服务）、49134（引擎WebSocket）、9464（Prometheus）

Worker Module System

Worker模块系统

External workers are installed via the CLI and configured in

iii-config.yaml

```
iii worker add pdfkit@1.0.0
```
— install a worker binary from the registry
```
iii worker add
```
(no name) — install all workers listed in
```
iii.toml
```
```
iii worker remove pdfkit
```
— remove binary, manifest entry, and config block
```
iii worker list
```
— show installed workers and versions from
```
iii.toml
```

Workers appear in

iii.toml

as a version manifest:

toml

[workers]
pdfkit = "1.0.0"
image-processor = "2.3.1"

Worker config blocks in

iii-config.yaml

use marker comments for automatic management:

yaml

workers:
  # === iii:pdfkit BEGIN ===
  - class: workers::pdfkit::PdfKitWorker
    config:
      output_dir: ./output
  # === iii:pdfkit END ===

At startup, the engine resolves each worker class, finds the binary in

iii_workers/

, and spawns it as a child process. Worker binaries are stored in the

iii_workers/

directory.

外部Worker通过CLI安装并在

iii-config.yaml

中配置：

```
iii worker add pdfkit@1.0.0
```
—— 从注册表安装Worker二进制文件
```
iii worker add
```
（无名称）—— 安装
```
iii.toml
```
中列出的所有Worker
```
iii worker remove pdfkit
```
—— 删除二进制文件、清单条目和配置块
```
iii worker list
```
—— 显示
```
iii.toml
```
中已安装的Worker及其版本

Worker在

iii.toml

中以版本清单形式存在：

toml

[workers]
pdfkit = "1.0.0"
image-processor = "2.3.1"

iii-config.yaml中的Worker配置块使用标记注释实现自动管理：

yaml

workers:
  # === iii:pdfkit BEGIN ===
  - class: workers::pdfkit::PdfKitWorker
    config:
      output_dir: ./output
  # === iii:pdfkit END ===

启动时，引擎解析每个Worker类，在

iii_workers/

目录中找到二进制文件并将其作为子进程启动。Worker二进制文件存储在

iii_workers/

目录中。

Adapting This Pattern

模式适配

Use the adaptations below when they apply to the task.

Start with file_based adapters for development, switch to Redis/RabbitMQ for production
Define queue configs per workload: high-concurrency for parallel jobs, FIFO for ordered processing
Use environment variables with defaults for all deployment-sensitive values (URLs, ports, credentials)
Enable only the modules you need — unused modules can be omitted from the config
Use
```
iii worker add
```
to install external workers and auto-generate their config blocks
Set
```
max_retries
```
and
```
backoff_ms
```
based on your failure tolerance and SLA requirements
Configure
```
OtelModule
```
with your collector endpoint and sampling ratio for observability

根据任务需求选用以下适配方式：

开发环境使用file_based适配器，生产环境切换为Redis/RabbitMQ
按工作负载定义队列配置：并行任务使用高并发配置，有序处理使用FIFO配置
所有部署敏感值（URL、端口、凭证）使用带默认值的环境变量
仅启用所需模块——未使用的模块可从配置中省略
使用
```
iii worker add
```
安装外部Worker并自动生成其配置块
根据故障容忍度和SLA要求设置
```
max_retries
```
和
```
backoff_ms
```
配置
```
OtelModule
```
，设置收集器端点和采样比例以实现可观测性

Pattern Boundaries

模式边界

For HTTP handler logic (request/response, path params), prefer
```
iii-http-endpoints
```
.
For queue processing patterns (enqueue, FIFO, concurrency), prefer
```
iii-queue-processing
```
.
For cron scheduling details (expressions, timezones), prefer
```
iii-cron-scheduling
```
.
For OpenTelemetry SDK integration (spans, metrics, traces), prefer
```
iii-observability
```
.
For real-time stream patterns, prefer
```
iii-realtime-streams
```
.
Stay with
```
iii-engine-config
```
when the primary problem is configuring or deploying the engine itself.

对于HTTP处理器逻辑（请求/响应、路径参数），优先使用
```
iii-http-endpoints
```
。
对于队列处理模式（入队、FIFO、并发），优先使用
```
iii-queue-processing
```
。
对于定时任务调度细节（表达式、时区），优先使用
```
iii-cron-scheduling
```
。
对于OpenTelemetry SDK集成（链路、指标、追踪），优先使用
```
iii-observability
```
。
对于实时流模式，优先使用
```
iii-realtime-streams
```
。
当核心需求是配置或部署引擎本身时，使用
```
iii-engine-config
```
。

When to Use

使用场景

Use this skill when the task is primarily about
```
iii-engine-config
```
in the iii engine.
Triggers when the request directly asks for this pattern or an equivalent implementation.

当任务主要涉及iii引擎中的
```
iii-engine-config
```
时，使用本技能。
当请求直接要求实现本模式或等效方案时触发。

Boundaries

边界限制

Never use this skill as a generic fallback for unrelated tasks.
You must not apply this skill when a more specific iii skill is a better fit.
Always verify environment and safety constraints before applying examples from this skill.

切勿将本技能作为无关任务的通用 fallback。
当更特定的iii技能更合适时，不得使用本技能。
在应用本技能的示例前，务必验证环境和安全约束。