iii 引擎配置指南：从 config.yaml 到环境变量注入的完整实战-创锋一号

iii 引擎配置指南：从 config.yaml 到环境变量注入的完整实战

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

本篇技术指南以 iii 开源仓库docs/0-17-0/using-iii/engine.mdx.skill.md（及其同目录源文档docs/0-17-0/using-iii/engine.mdx）为核心，系统讲解 iii 引擎的启动方式、config.yaml配置结构、worker 声明与配置块写法，以及${VAR:default}环境变量展开机制。读完本文，你将掌握如何用一份配置文件启动引擎、按 worker 粒度注入配置、跨环境切换端口与地址，并能理解引擎读取配置与iii.lock之间的职责边界，直接上手自己的 iii 项目。

引擎配置：从一份`config.yaml`开始

iii 引擎从项目根目录的config.yaml文件启动。默认情况下，iii命令会在当前目录寻找该文件；你也可以通过--config <path>指向其他位置的配置文件：

iii --config config.yaml

从源码看，这一逻辑位于 engine/src/main.rs 的config_path_of函数：显式传入的--config值优先，否则回退到默认的config.yaml。随后run_serve会调用ensure_config_file做启动前检查——如果文件不存在，交互式会话会询问是否创建，非交互式会话（如 CI 与容器）则直接生成，避免首次运行被阻塞。

0-17-0 版本的文档还提到另一个启动开关：iii --use-default-config，它可以在不编写config.yaml的情况下以一组默认 worker 启动引擎，适合首次运行和临时试验。需要说明的是，这一开关在后续版本中已被移除：当前主干文档 docs/using-iii/engine.mdx 已改为"目录中无config.yaml时自动创建文件"，且 engine/src/main.rs 中的测试use_default_config_is_no_longer_a_flag明确断言--use-default-config不再被解析。因此使用 0-17-0 及更早版本时可按文档使用该 flag，升级到新版本后应改用自动创建配置的方式。

`config.yaml`的文件结构

config.yaml只有一个顶层键workers:，它列出了引擎应当加载的 worker 列表。每个条目包含：

name：一个 registry 别名（slug）或本地 worker 名称；
config：配置块，其字段结构由该 worker 自己定义。

workers: - name: iii-http config: port: 3111 host: 127.0.0.1 - name: iii-state config: adapter: name: kv config: store_method: file_based file_path: ./data/state_store.db

上述示例中，iii-http配置了监听端口与绑定地址，iii-state则声明使用kv适配器并采用基于文件的存储方式、数据落盘到./data/state_store.db。每个 worker 的config块结构不同，其完整字段说明位于各 worker 的 Worker Docs 页面，可通过 Worker Registry 找到对应 worker 的配置参考入口。

从源码结构看，引擎在 engine/src/workers/config.rs 中定义了EngineConfig结构体，除workers外还包含modules与全局配置项registration_namespace_grace_ms（新 worker 连接等待命名空间注册的宽限时间，默认 5000ms，可用环境变量III_NAMESPACE_GRACE_MS覆盖），并启用了deny_unknown_fields——这意味着配置中未识别的字段会导致解析报错，能及早发现拼写错误。仓库根目录的真实示例 engine/config.yaml 展示了引擎自身的完整配置：iii-stream（含port: ${STREAM_PORT:3112}的环境变量注入与 redis 适配器）、configurationworker（使用 fs 适配器将配置持久化到./config目录），以及被注释掉的iii-sandbox示例（含auto_install、image_allowlist、default_idle_timeout_secs、max_concurrent_sandboxes等字段），可作为编写自定义配置的参考模板。

需要补充的一个关键细节（源自同版本源文档 docs/0-17-0/using-iii/engine.mdx）：worker 条目下的config:块是首次启动种子（first-boot seed）。注册了配置 schema 的 worker 会在首次启动时读取该块、初始化自己的配置项；此后其设置会持久化到./config/目录下每 worker 一个的配置文件中，可在运行时从磁盘、控制台或configuration::set实时修改，而引擎会从config.yaml中移除已被消费的配置块，并在原位置留下一行注释。另外，仅含- name:的裸条目（即iii worker add写入的形式）会让 worker 以内置默认配置启动。

两条重要边界：`iii.lock`与远程 Worker

引擎不读取`iii.lock`

config.yaml与iii.lock职责不同：引擎只读取config.yaml并启动磁盘上的 worker 安装；它不读取iii.lock。锁文件属于 worker 安装层面的概念，由iii worker sync/update/verify写入和使用，目的是让安装过程可复现。完整说明见 Workers / The lockfile (iii.lock)。

Worker 不必与引擎同机运行

把 worker 写进config.yaml只是一种便利做法，并非强制。worker 可以部署在任何位置，只需要一条连接字符串即可接入 iii 实例。关于 worker 如何连接引擎，见 Creating Workers / Connecting to the engine。从引擎实现看，EngineConfig解析出的配置路径会被记录进引擎（engine/src/engine/mod.rs 中的config_path字段），并通过III_CONFIG_PATH环境变量传递给引擎派生的子进程，这保证了分布式部署时各进程对同一份配置的感知一致。

环境变量展开：`${VAR:default}`

config.yaml中的值支持${VAR:default}语法：展开时使用环境变量VAR的值，若该变量未设置则回退到default。这一机制让你无需为每个环境复制一份配置文件，就能按环境切换端口、URL 和功能开关：

workers: - name: iii-http config: port: ${HTTP_PORT:3111} host: ${HTTP_HOST:127.0.0.1}

该语法在仓库中有多处实际使用与实现佐证：

引擎自带的 engine/config.yaml 中即包含port: ${STREAM_PORT:3112}，把默认端口 3112 暴露为可覆盖的环境变量；
在 compose 场景下，crates/iii-compose/src/interpolate.rs 实现了${VAR}与${VAR:-default}的展开逻辑，且明确说明展开发生在 YAML 解析之前，因此可用于路径、版本号等任意值；裸$VAR不会被改写（避免破坏 shell 脚本语义），而$${VAR}用于保留字面量${VAR}；
除配置启动参数外，环境变量也参与引擎运行时调优：例如III_NAMESPACE_GRACE_MS可覆盖config.yaml中的registration_namespace_grace_ms（见 engine/src/engine/mod.rs 中registration_namespace_grace的优先级逻辑：环境变量 > 全局配置 > 5 秒默认值）。

在配置值的生命周期上，当前版本文档（docs/using-iii/engine.mdx）进一步说明：相同的${VAR:default}语法也适用于 per-worker 配置文件（./config/下的文件），其中的占位符在每次读取时重新展开，便于把敏感值以引用而非明文形式持久化。

默认配置与首次运行

iii --use-default-config（0-17-0）可以在不编写config.yaml的情况下以一组默认 worker 启动引擎，适合首次运行与临时实验；一旦需要自定义端口、适配器或 worker 集合，就应切换到真实的config.yaml。

在后继版本中，这一行为演进为"自动创建"模式：在没有任何config.yaml的目录中运行iii，交互式会话会询问是否创建文件，非交互式会话则直接生成；创建出的文件以空的workers:列表开头——引擎自身携带的内部服务（SDK worker 连接的 WebSocket 监听器、configuration worker、可观测性）照常启动，其余功能通过iii worker add <name>按需加入，且引擎会监听配置文件、实时拾取新增的 worker；新 worker 以内置默认配置启动，如需种子配置，可在其首次启动前在条目中加入config:块（详见 docs/using-iii/engine.mdx 与 engine/src/main.rs 的测试断言）。

企业官网建设流程全解析