iii CLI 完全指南：启动引擎、用 trigger 调用函数与自更新机制解析

iii CLI 完全指南启动引擎、用 trigger 调用函数与自更新机制解析【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本文基于 iii 仓库0.12.0文档线中的 CLI 文档 展开覆盖 iii 命令行的完整使用面如何通过--help发现命令、如何裸跑iii启动引擎、如何用iii trigger向运行中的引擎调用已注册函数、iii update如何更新 iii 及其托管二进制。读完后你可以直接使用 CLI 完成函数调用与日常运维并能从 engine/src/main.rs 等源码中核对每个参数的默认值与底层行为。用 --help 发现命令与默认值文档的首要建议是最权威的命令、标志与默认值清单直接问二进制本身iii --help # 列出 iii 的顶层标志与可用子命令 iii subcommand --help # 列出该子命令接受的每个动作每个子命令的 help 还会给出影响该命令的默认值与环境变量。从源码看这一体验并非巧合engine/src/main.rs 中print_help_and_exit会拦截 clap 的默认 help 输出改用clap-help重新渲染并手动补出 clap-help 1.x 缺失的子命令列表print_subcommands_section因此iii --help的排版与命令行表格是刻意设计的。顶层标志由 Cli 结构定义 可知包括标志说明--config path/-c引擎配置文件路径缺省为config.yaml仅在无子命令serve 模式时生效--version/-v打印版本并退出--no-update-check禁用后台更新检查与安全公告advisory检查裸运行 iii启动引擎文档指出不带子命令直接运行iii会读取./config.yaml或--config传入的路径并启动引擎。0.12.0 文档中还提到--use-default-config标志用于以内置默认配置启动——需要注意的是当前仓库源码中该标志已被移除main.rs 的回归测试 中use_default_config_is_no_longer_a_flag断言--use-default-config无法再被解析因为现在的行为是配置文件缺失时iii会主动提供创建一个带空 workers 列表的config.yaml。这一创建逻辑见 ensure_config_file 函数交互式终端检测到文件缺失时会先询问Create it and start the engine? [Y/n]避免在错误目录静默生成配置无头会话容器、CI、服务管理器不询问直接创建保证iii可以无人值守启动创建后提示在worker-compose.yaml中声明项目 workers并用iii compose --up启动。确认配置存在后run_serve 依次执行EngineConfig::config_file加载配置 →logging::init_log_from_config初始化日志 →EngineBuilder构建并serve引擎。用 iii trigger 从命令行调用函数iii trigger function-id [argvalue ...]会对运行中的引擎调用一个已注册函数。引擎把这次调用路由到注册了该函数的 worker整个过程不涉及任何 trigger 注册——它是直接调用而不是触发某个已配置的 trigger。iii trigger math::add a2 b3完整的调用面payload 格式、fire-and-forget、队列路由的 action、以及从 worker 代码发起的等价 SDK 调用见 Triggers / Call a function directly。参数全览含默认值以下参数均取自 TriggerArgs 的 clap 定义与测试 engine/src/main.rs 中的解析断言一致参数说明默认值FUNCTION_PATH位置参数函数路径如my::fn、sandbox::create必填KV位置参数可多个keyvalue形式的 payload token如a10 bhello world无--json JSONJSON payload与 kv 同时出现时--json必须是对象kv 对同名的键做浅合并覆盖无--address引擎主机地址localhost--port引擎 WebSocket 端口49134DEFAULT_PORT--timeout-ms等待调用结果的最长时间毫秒30000-n, --namespace NS在该命名空间内解析FUNCTION_PATH省略时在引擎的default命名空间解析路由是严格的注册在其他命名空间的函数只能靠此标志触达无-h, --help打印帮助若同时给了 FUNCTION_PATH会向运行中的引擎查询该函数的描述与请求 schema-trigger还有一个短别名tCommands::Trigger 上的visible_alias所以iii t math::add a2 b3等价。注意旧版的位置标志--function-id与--payload已被拒绝见 main.rs 中的回归测试函数路径与参数统一走位置参数。payload 解析规则kv 与--json如何合成最终 payload由 payload::parse 决定规则是两者都没给返回空对象{}这让输入结构体字段全为可选的函数可以直接iii trigger fn-path调用只给--json原样解析为任意 JSON 值对象或数组只给 kv 对构建对象。kv 的值会先尝试按 JSON 解码——count10得到数字10namealice解码失败则回退为字符串两者都给--json必须是对象kv 对逐键覆盖浅合并。kv token 必须是keyvalue形式且键非空否则报错expected keyvalue/payload key must not be empty。以上规则均有单测覆盖例如--json {a:1,b:2}加a99得到{a:99,b:2}。特例compose::add。该函数的 JSON 契约里有一个列表字段而 shell 语法上更自然的是重复一个可读的单数键。run_trigger 中专门适配对compose::add调用parse_collecting把重复的workerdatabase workerweb收集为workers: [database, web]数组其他所有 trigger 保持既定的“同键后值胜出”行为。调用链与输出行为exec::invoke 的实现揭示了trigger的底层机制它通过 iii SDK 的register_worker以ws://address:port向引擎注册一个临时的 CLI 身份发出TriggerRequest { function_id, payload, action: None, timeout_ms }省略 namespace 时不附加保持default解析拿到结果后shutdown_async关闭连接再退出。输出规则返回非 null 结果以 pretty JSON 打印到 stdout远端函数返回错误结构化 JSONcode/message/stacktrace打印到 stderr进程静默以退出码 1 结束避免重复打印超时提示Timed out waiting for the engine (no response within the timeout). Is the engine running at the given address and port?连接层失败提示WebSocket error: ...。动态 help查询函数的请求 schemaiii trigger fn-path --help不是静态帮助。help::print 会向运行中的引擎调用engine::functions::info内省函数它返回完整的请求/响应 schema而engine::functions::list只有 id 加描述渲染出该函数的描述与参数表。若引擎不在线或过旧不支持内省则优雅降级为静态 CLI 帮助若目标函数不存在会提示run iii trigger engine::functions::list to see registered functions.。子命令一览文档给出的子命令表0.12.0 文档线如下子命令作用iii trigger在运行中的引擎上调用已注册函数iii worker管理 workersadd、remove、list、start/stop、update、verify。见 Workersiii project管理 iii 项目脚手架新项目、生成 Docker 资产。见 Deploymentiii console启动 iii Web 控制台。见 Consoleiii cloud管理托管的 iii 部署。见下文 iii Cloud 一节iii update更新 iii 及其托管二进制。见下文“更新 iii”一节对照当前仓库源码有几点演进值得注意可推断文档面向 0.12.0而源码已向前发展iii worker不再是根级公开子命令。engine/src/main.rs 的回归测试worker_is_no_longer_a_public_command断言iii worker add http必须被根 CLI 拒绝worker 的管理职能在新版本中并入iii composeworker-compose 项目与compose::*函数调用面。iii project当前有两个动作iii project init脚手架支持位置参数项目名、--directory、--docker、--template、--skip-iii与iii project generate-docker生成 Docker 资产旧命令iii create已被project init --template取代并不可解析。iii console与iii cloud是“派发型”子命令它们不解析自身参数trailing_var_arg true直接透传而是走 handle_dispatch 分派到托管二进制iii-console/iii-cloud。若本机没有对应二进制dispatch 会检查平台支持、自动从发行版下载校验 checksum、记录安装状态到本地 state 文件最后以exec替换进程执行子二进制若~/.local/bin不在 PATH 中还会打印提示。托管二进制的清单名称、仓库、平台矩阵、命令映射集中定义在 registry.rsiii-init、iii-console、iii-cloud、iii-worker。管理 iii Cloud 部署文档说明iii cloud子命令组用于管理托管的 iii 部署详见 Deployment 文档中的 iii Cloud Deployments 一节并注明“iiis cloud will be available soon”。文档自身也提醒这条关于 iii cloud 可用性的描述可能已经过时使用前应核实最新状态。从当前源码可以确认的一点是cloud命令的分派目标指向独立的iii-cloud-cli仓库产出的iii-cloud二进制registry.rs其参数完全透传例如iii cloud deploy --project abc --tag v1会被原样交给该二进制处理见 main.rs 中的解析测试。更新 iiiiii update 与其托管二进制iii update将 iii 本体及其托管二进制刷新到最新版本。文档特别强调它与iii worker update的区别——后者刷新的是项目内固定的 worker 版本而iii update面向的是 CLI 工具链自身。具体目标可单独更新iii update [target]用iii update --list-targets查看目标清单。print_targets 的输出表明self或iii旧名iii-cli向后兼容可被接受更新 iii 本身托管二进制包括consoleiii-console、cloudiii-cloud等示例为iii update # 更新一切 iii update self # 只更新 iii iii update console # 只更新 console更新流程handle_update 与 update.rs值得理解因为它解释了“自动更新”背后的行为通过 GitHub API 拉取对应发行版仓库的最新 releaseiii 本体 tag 前缀为iii见 SELF_SPEC解析出版本号以磁盘上二进制的实际版本为准运行binary --version探测5 秒超时而不是信任可能过期的 state 文件——这覆盖了 install.sh 重装、从旧版 iii-cli 迁移等场景已装版本不低于最新 release 则报already up to date否则下载对应平台资产、校验 checksum、安装到~/.local/bin并把安装记录写入 state 文件update不带 target 时先自更新、再遍历所有平台支持的托管二进制逐个更新任一失败即以非零码退出。配套的后台机制dispatch 型命令执行前会运行一个有 500ms 超时的后台更新检查run_background_check发现新版本时以info:行提示iii update target同时拉取安全公告advisories并对已安装二进制做匹配告警--no-update-check可整体禁用这些检查。自更新成功后 CLI 会提示重启 shell 或重跑命令以使用新版本。版本演进注意本文主体对应0.12.0文档线的 cli.mdx而仓库源码持续演进几处差异需要以你实际安装的版本--help输出为准0.12.0 文档中的iii worker子命令与--use-default-config标志在当前源码中均已不可用均有回归测试锁定该行为当前源码新增了iii composeworker-compose 项目守护与--up/-n/--engine等放置标志与隐藏的gen-cli-docs构建工具命令后者用于从本二进制的 clap 定义生成文档站中的 CLI 参考页见 scripts/generate-cli-docs.sh。命令行行为的完整回归保障位于 engine/tests/cli_args.rs 与 engine/src/main.rs 内的解析测试从trigger的 kv/json 组合、别名解析到update的 target 与--list-targets冲突、被移除子命令start、create、sandbox、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），仅供参考