iii-engine-config

Engine 配置

类似于：基础设施即代码、Docker Compose 配置

核心概念

根据任务需要使用以下概念。并非每种部署都需要所有模块或适配器。

• iii-config.yaml 定义引擎端口、模块、工作进程、适配器和队列配置
• 环境变量 使用 ${VAR:default} 语法（默认值可选）
• 模块 是构建模块 — 每个模块都会启用一项功能（API、状态、队列、cron 等）
• 工作进程 是通过 iii.toml 和 iii worker CLI 命令管理的外部二进制模块
• 适配器 可按模块切换存储后端：in_memory、file_based、Redis、RabbitMQ
• 队列配置 控制每个命名队列的重试次数、并发数、排序和退避
• 引擎在端口 49134（WebSocket）上侦听 SDK/工作进程连接

架构

iii-config.yaml 文件由 iii 引擎二进制文件在启动时加载。模块按顺序初始化，适配器连接到各自的后端，随后引擎开始在端口 49134 上通过 WebSocket 接受工作进程连接。workers 部分中定义的外部工作进程会自动作为子进程启动。

使用的 iii 原语

原语	用途
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 部分	外部二进制工作进程（工作进程模块）
iii.toml	工作进程清单（名称 → 版本）
iii worker add NAME[@VERSION]	从注册表安装工作进程
iii worker remove NAME	卸载工作进程
iii worker list	列出已安装的工作进程
iii worker info NAME	显示工作进程的注册表信息

参考实现

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

常见模式

使用此模式的代码通常会在适用时包含以下内容：

• 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（引擎 WS）、9464（Prometheus）

Worker 模块系统

通过 CLI 安装外部 Worker，并在 iii-config.yaml 中配置：

• iii worker add [email protected] — 从注册表安装 Worker 二进制文件
• iii worker add（不指定名称）— 安装 iii.toml 中列出的所有 Worker
• iii worker remove pdfkit — 移除二进制文件、清单条目和配置块
• iii worker list — 显示 iii.toml 中已安装的 Worker 及其版本

Worker 会作为版本清单显示在 iii.toml 中：

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

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

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

启动时，引擎会解析每个 Worker 类，在 iii_workers/ 中查找二进制文件，并将其作为子进程启动。Worker 二进制文件存储在 iii_workers/ 目录中。

调整此模式

适用时，请使用以下调整方式。

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

模式边界

• 对于 HTTP 处理程序逻辑（请求/响应、路径参数），优先使用 iii-http-endpoints。
• 对于队列处理模式（入队、FIFO、并发），优先使用 iii-queue-processing。
• 对于 cron 调度详情（表达式、时区），优先使用 iii-cron-scheduling。
• 对于 OpenTelemetry SDK 集成（跨度、指标、追踪），优先使用 iii-observability。
• 对于实时流模式，优先使用 iii-realtime-streams。
• 如果主要问题是配置或部署引擎本身，请继续使用 iii-engine-config。

适用场景

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

边界

• 切勿将此技能用作无关任务的通用备用方案。
• 如果有更具体的 iii 技能更适用，则不得使用此技能。
• 应用此技能中的示例前，务必核实环境和安全约束。