深入 iii Worker 命令集:安装、排障与 iii.lock 可复现部署完全指南【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii如果你需要在多个机器、多个平台之间保持一致的 iii 部署,那么「Worker 生命周期管理」和「锁文件可复现」是你绕不开的两个核心能力。本文面向第一次接触 iii 的开发者,用四个运维场景带你走完 Worker 从装到卸的全过程:如何在空项目里装出第一个 Worker、日常如何排障与进沙箱、iii.lock如何保证跨机器一致、以及怎样有节奏地升级和下线。沙箱、版本锁定、可复现部署这些关键词,都会在对应场景里落到具体命令上。能力速览:一张表看懂 worker 子命令命令一句话作用典型场景iii worker add name把 Worker 写入config.yaml并自动启动首次接入能力(状态、HTTP、队列等)iii worker reinstall name强制重新下载(等价add --force)本地缓存损坏时恢复iii worker list列出config.yaml中声明的 Worker 及状态快速核对声明 vs 在线iii worker start name/stop name/restart name手动启停、重启单个 Worker引擎自动启动之外的精细控制iii worker status name查看配置段、沙箱状态、近期日志装上了但没连上的第一排障步iii worker logs name流式输出该 Worker 日志长驻跟踪运行行为iii worker exec name -- command在 Worker 沙箱内执行命令验证依赖、检查文件系统iii worker update [name]重新解析已锁定版本并写回iii.lock有节奏地升级iii worker sync/sync --frozen严格按iii.lock安装 / CI 只校验不落盘可复现部署、CI 门禁iii worker verify报告config.yaml与iii.lock之间的漂移本地发现配置漂移iii worker remove name从config.yaml删除并拆除运行进程下线某个能力iii worker clear name删除磁盘上已下载的产物下线后清盘(省略名称则全清)下面按场景展开。场景一:从空项目到装好第一个 Worker先把引擎跑起来。如果只想临时试验,不需要任何配置文件:做什么:用默认配置拉起一个 iii 实例。怎么用:iii --use-default-config注意什么:正式项目仍建议安装并运行你自己的引擎(见仓库文档 using-iii/engine.mdx 的 Default configuration 一节)。然后去 Worker Registry 找能力。Registry 收录了大量封装常见服务的 Worker,每个页面都列出其函数、触发器类型、配置 schema、支持平台以及面向 Agent 的 skills 信息。找到目标后执行安装:iii worker add iii-state做什么:add把 Worker 写入项目的config.yaml,引擎随即自动把它拉起。怎么用:一条命令,装完即可见。注意什么:装完不等于在线。Worker 进程起来后,还要等进程内的 SDK 通过 WebSocket 完成注册,它的函数与触发器才对外可调;断开连接后这些能力立即停止可被调用,重连才恢复。add实际接受三类来源,源码里对应WorkerSource枚举,见 crates/iii-worker/src/core/add.rs 的source_label:iii worker add iii-state # registry 名称 iii worker add ./workers/my-worker # 本地路径(目录内需有 manifest) iii worker add ghcr.io/org/worker:tag # Docker / OCI 镜像两个值得知道的实现细节:成功路径上add会按序发出事件:Started { op: add } → Stage(downloading) → Stage(downloaded) → Done;失败路径则是前两个事件加一个携带错误信息的Failed。单元测试emits_started_downloading_downloaded_done_in_order与emits_failed_on_shim_error明确断言了这个序列,是事件契约的可靠依据。CLI 与通过总线触发worker::add的调用方因此拿到一致的进度反馈。本地路径安装(kind: local)现在也可以经 trigger 总线触发,路径在 daemon 所在主机上解析,manifest 的 setup/install/start 脚本也在该主机执行。把 daemon 暴露给不受信任的 Worker 之前,请留意这一点。如果同名 Worker 已存在、想强制重新下载,用iii worker reinstall name(等价add --force),配合--force的语义是删除缓存产物后重装,常用于恢复缓存损坏。场景二:日常运维与排障装完之后,你 90% 的时间都在这几个命令里打转。列出:先对一遍账。iii worker list做什么:显示config.yaml声明的所有 Worker 及当前状态。怎么用:无参数,一条命令。注意什么:它读的是声明,不承诺在线。声明了但没连上正是排障的起点。实现位于 crates/iii-worker/src/core/list.rs,与 add/start/stop 共享同一套ProjectCtxWorkerHostShim抽象。启停:引擎之外的手动档。iii worker start name # 启动单个 worker iii worker stop name # 停止单个 worker iii worker restart name # 先停后启做什么:单独控制某个 Worker 进程。怎么用:三条命令,参数都是 Worker 名;restart是先停后启的复合动作。注意什么:add安装的 Worker 会随引擎自动启动,这三个命令是给想单独干预某个进程的场景准备的。实现分别在 core/start.rs 与 core/stop.rs,沙箱进程的实际托管(含 OCI 运行时 libkrun 适配)在 crates/iii-worker/src/cli/worker_manager。检查:状态、日志、沙箱三板斧。iii worker status name # 配置、沙箱状态、近期日志 iii worker logs name # 流式输出该 worker 的日志 iii worker exec name -- command # 在 worker 沙箱内执行命令做什么:status一次性给出配置段、沙箱当前状态和最近日志,是Worker 装上了但没连上的第一排障步;logs长驻跟踪;exec直接进沙箱执行任意命令,例如验证依赖、检查文件系统。怎么用:exec用--分隔 Worker 名和要执行的命令,命令本身原样透传。注意什么:一定保留--,否则命令的开头参数会被误当成 Worker 名。status实现在 crates/iii-worker/src/cli/status.rs,日志读取在 core/logs.rs。能力 已连接 Worker 的并集。函数和触发器都来自已连接的 Worker:想用某类触发器,提供它的 Worker 就必须在线。比如通过 iii-http Worker 添加http触发器后,你就像用 Express 或 FastAPI 一样为函数暴露 HTTP 端点——而引入这份能力只需一条iii worker add。想直接调用运行中 Worker 的函数,或把函数绑定到事件并附加条件门,参见 Triggers 文档。顺带一提:每个 Worker 还随附面向 Agent 的 skills,由名为skills的 Worker 统一托管(它本身也是一个内容注册表类型的 Worker)。加载是惰性的:顶层条目保持精简,只有当某个函数引用解析到深层内容时,Agent 才通过iii://worker/leaf形式的 section URI 拉取详情。这部分接口在稳定版发布前仍可能变化,以文档最新说明为准。场景三:用 iii.lock 做可复现部署为什么需要。想象两台机器:你在这台跑iii worker add iii-state,它解析到最新 release;同事下周在另一台机器再装一次,拿到的可能已经是新版本。二进制类 Worker 在 macOS、Linux、Windows 上产物还各不相同。iii.lock解决的就是这个:项目根目录的 YAML 文件,把每个受管 Worker 锁定到具体的版本与来源,同一份锁文件里还可以按平台分别锁定二进制产物。建议把它和config.yaml一起提交版本控制。怎么工作。直接操作锁文件的命令有三个,读锁、写锁的实现都集中在 crates/iii-worker/src/cli/lockfile.rs:iii worker sync # 严格按照 iii.lock 安装 worker iii worker sync --frozen # CI 形态:只校验锁文件,不改动本地文件 iii worker verify # 报告 config.yaml 与 iii.lock 之间的漂移字段层面,手工阅读iii.lock时记住这张最小字典:顶层WorkerLockfile:version(当前为1)、可选manifest_hash(声明依赖的规范序列化 SHA-256,形状sha256:v1:64位小写hex)、可选declared_dependencies(写锁时刻项目声明的依赖映射,用于精确定位增删改)、workers(名 →LockedWorker)。LockedWorker:version(锁定的 semver)、type(binary/image/engine/bundle)、dependencies(默认空)、可选source。source三种:Binary携带artifacts,是平台名 →{url, sha256}的映射;Image携带image镜像引用;Bundle携带archive_url与sha256。几条源码级细节,决定了锁文件为什么敢在 CI 里被信任:哈希形状在验证阶段就拦:手写的大写 hex 哈希会在字节级比较中永远匹配不上,导致每次sync误报漂移,所以校验直接拒绝大写(见is_valid_manifest_hash)。legacy 兼容:旧式二进制来源若缺artifacts,反序列化器会尝试从单个target/url/sha256字段恢复,早期锁文件依然可读。原子写入:写入走同目录临时文件 fsync rename(2)。POSIX 同一文件系统上 rename 原子,并发读方只会看到旧内容或新内容,绝不会看到半截文件;rename 失败则清理临时文件,目标文件保持原样。CI 里怎么做。把sync --frozen放进流水线:它只验证锁文件能严格复现安装,不落盘任何变更——这就是可复现校验的门禁形态。本地则用verify日常体检漂移:谁改了config.yaml却没更新锁,一眼可见。场景四:升级与下线版本锁定从安装那一刻开始。Worker 以 semver 发布。不带版本说明符就装最新 release;想锁定,在 registry 名称后追加version:iii worker add iii-state1.2.0这个 pin 会记进iii.lock,之后每次安装回放同一版本,跨机器一致。升级:让锁跟着走。iii worker update worker-name # 只更新一个 iii worker update # 更新全部已锁定 worker做什么:重新解析允许范围内的最新版本,并把新的 pin 写回iii.lock。怎么用:给名字则单点更新,省略则全量。注意什么:它是三个直接操作锁文件的命令之一(另外两个是sync与verify),语义是重解析 落盘,升级完记得提交新的iii.lock。实现在 crates/iii-worker/src/core/update.rs。下线:摘除与清盘是两步。iii worker remove worker-name iii worker clear worker-name # 省略名称则清除所有 worker 产物做什么:remove把 Worker 从config.yaml删除,引擎随之拆除正在运行的进程;clear才删磁盘上的已下载产物。怎么用:先remove观察,确认无事再clear。注意什么:remove之后产物仍留在磁盘上——这是有意设计,让先摘除、观察、再清理的运维节奏成立。实现在 core/remove.rs 与 core/clear.rs。边界:本文不覆盖的内容创建新 Worker、在 Worker 代码里注册函数与触发器、构建与发布 Worker 镜像,属于创作而非使用,请参见仓库文档 creating-workers/workers.mdx 与 creating-workers/workers-registry.mdx。另外,Worker Registry 的浏览方式与三种安装来源的更多细节,见 using-iii/workers-registry.mdx。收尾:一条可复制的运维闭环把前面的场景串起来,从接入到下线的最小闭环是:iii worker add iii-state1.2.0 # 锁定版本安装,pin 落入 iii.lock iii worker list # 核对声明与在线状态 iii worker status iii-state # 排障:配置/沙箱/近期日志 iii worker exec iii-state -- node -v # 沙箱内做一轮验证 iii worker verify # 本地体检:config.yaml 与锁是否漂移 iii worker update iii-state # 到节奏时升级并写回锁 iii worker sync --frozen # CI 里做可复现校验 iii worker remove iii-state iii worker clear iii-state # 下线并清盘这套命令的底层实现集中在 crates/iii-worker:编排逻辑在src/core/,锁文件、二进制下载与沙箱托管在src/cli/。当文档与行为有出入时,建议以源码与 crates/iii-worker/tests 下的集成测试为准。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
