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.mdxworker 条目下的config:块是首次启动种子first-boot seed。注册了配置 schema 的 worker 会在首次启动时读取该块、初始化自己的配置项此后其设置会持久化到./config/目录下每 worker 一个的配置文件中可在运行时从磁盘、控制台或configuration::set实时修改而引擎会从config.yaml中移除已被消费的配置块并在原位置留下一行注释。另外仅含- name:的裸条目即iii worker add写入的形式会让 worker 以内置默认配置启动。两条重要边界iii.lock与远程 Worker引擎不读取iii.lockconfig.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-config0-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 的测试断言。延伸阅读Worker Registry查找各 worker 的配置参考与文档入口Workersiii.lock锁文件与 worker 安装、同步机制Creating Workers / Connecting to the engine远程部署 worker 时的连接方式engine/config.yaml仓库内真实可用的引擎配置示例Configuration当前版本配置 worker 的完整生命周期与运行时修改方式【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考