iii 项目 Workers 实战指南生命周期、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 项目 Workers 实战指南生命周期、iii worker命令行全解与 iii.lock 版本管理本指南以docs/0-19-0/using-iii/workers.mdx.skill.md为骨架系统讲解 iii 项目中 worker 的核心概念它们如何通过 WebSocket 接入引擎、如何用iii worker命令完成从查找、添加、启停、巡检、更新到移除的完整生命周期管理以及基于 semver 与iii.lock的可复现安装机制。读完本文你将掌握在项目里像管理 npm 包一样安装、运行与卸载 worker 的全部命令并理解config.yaml、iii.lock与引擎微 VM 运行时之间的协作关系。理解 workeriii 视角下的服务在深入命令之前先建立一个心智模型worker 是 iii 系统中自包含、相互隔离、却又自由互操作的服务单元。任何你想为 iii 实例新增的功能最终都会以 worker 的形式出现——无论是状态存储、HTTP 端点、定时任务、队列、Pub/Sub还是桥接外部系统。它与传统服务的核心区别在于无需任何集成代码即可使用worker 可以被安装和管理方式与 npm 包类似通过下面的iii worker add命令完成。差别在于你得到的不是一个库而是一个完整可部署的运行时。每个 worker 运行在隔离的 microVM微虚拟机中向引擎注册自身提供的函数functions与触发器triggers供系统内其他 worker 按需调用或绑定。Worker 生命周期连接即注册断开即下线Worker 的生命周期围绕与引擎的 WebSocket 连接展开连接worker 启动后通过 WebSocket 连接到 iii 引擎。一旦连接建立该 worker 对整个 iii 系统及其中的每一个其他 worker 都变得可见它注册的函数与触发器立即可以被调用和绑定。断开当 worker 断开连接时其提供的函数和触发器停止可调用直到它重新连接为止。关于在 worker 代码中建立这条连接的 SDK 调用如 Node 侧的registerWorker、Python 侧的register_worker以及约定通过III_URL环境变量指定引擎地址参见 Creating Workers / Workers。从源码看这个连接即注册的机制正是引擎 worker 管理模块的核心职责之一。引擎通过 WebSocket 端口默认49134见 CLI 定义监听 worker 的连接与注册并在 worker 退出时清理其注册状态。引擎的config.yaml中甚至设有registration_namespace_grace_ms默认5000这样的注册宽限期参数见 engine/config.yaml用于协调 worker 注册与命名空间路由。管理 workeriii worker命令全解iii workerCLI 命令覆盖项目中每个 worker 的完整生命周期在注册表中查找新 worker、将其安装进config.yaml与iii.lock、控制运行状态、查看日志、以及在不再需要时移除。命令的实现位于 crates/iii-worker/src/cli/app.rsAdd、Remove、Update、List、Sync、Verify等子命令由 clap 定义下面逐一展开。查找 workeriii 维护着一个worker 注册表worker registry可访问 workers.iii.dev 浏览。注册表中收录了大量封装常见服务的 worker每个 worker 页面会列出它提供的函数与触发器类型、配置 schema、支持平台以及 Agent 技能skills用于判断它是否满足项目的某个能力需求。更多信息见 Worker Registry。除了官方注册表worker 也可以发布在 Docker 或 OCI 兼容镜像仓库中。添加 worker添加 worker 前你需要先 安装 iii 并 启动引擎。若只想临时起一个 iii 实例做测试可以运行iii --use-default-config默认配置见 engine.mdx 的 Default configuration 一节。worker 有三种来源均通过iii worker add name安装iii worker add iii-state # 从 iii registry 下载并添加 iii worker add ./workers/my_worker # 添加本地 worker由 iii worker init 创建 iii worker add ghcr.io/org/worker:tag # 从 Docker 或 OCI 镜像仓库拉取并添加从 CLI 定义看add接受的参数格式是WORKER[VERSION]|PATH见 app.rs即三种来源可以统一表达iii registry 名称如iii-state或带版本的iii-state1.2.0本地 worker 路径一个包含iii.worker.yaml清单的目录如./my_workerDocker / OCI 镜像引用如ghcr.io/org/worker:tag。执行后worker 会被写入项目的config.yaml并自动启动。add默认会等待最多 120 秒直到 worker 报告就绪若超过 120 秒worker 会继续在后台启动但命令先返回 shell之后可用iii worker status和iii worker logs持续观察见 app.rs。若想强制重新下载某个已存在的 worker使用iii worker reinstall name等价于add --force且不等待就绪配合--reset-config可把该 worker 的 config.yaml 条目重置为注册表默认值见 app.rs。重要提醒docker 镜像查找方式iii worker add从远程仓库iii registry 或 OCI 仓库或本地文件夹下载 worker 镜像然后运行在 microVM 中。裸引用如caller-worker:latest只会在这些远程仓库中查找iii 不会读取你本地 Docker daemon 中的镜像因此你用docker build本地构建的镜像无法按名称被找到。本地构建的 Docker 镜像可以像其他 Docker 镜像一样直接运行和测试docker run -it caller-worker:latest只是不能通过iii worker add按名安装。固定版本Pinning注册表 worker 按 semver 发布版本。安装时若不指定版本则默认选取最新 release在注册表名称后追加version即可固定到特定版本而不是跟踪最新版详见下文版本管理一节iii worker add iii-state1.2.0列出 workeriii worker list显示项目config.yaml中声明的每个 worker 及其当前状态是查看运行中和已停止 worker 列表的主要入口iii worker list启动与停止 worker已添加的 worker 会随引擎自动启动。需要手动控制时使用start、stop和restartiii worker start name # 启动一个 worker iii worker stop -y name # 停止一个 worker-y 跳过确认提示 iii worker restart name # 先停止再启动从源码看start支持--no-wait不等待就绪立即返回、--port指定 worker 回连引擎的 WebSocket 端口默认取 config.yaml 中的 iii-worker-manager 端口否则为49134以及--config把 YAML 配置转发给被启动的二进制 workerOCI worker 会忽略见 app.rs。stop被视为常规、可逆的操作——之后用iii worker start name即可重新拉起-y是向后兼容的无操作参数因为stop本身从不提示确认见 app.rs。若要调用运行中 worker 内的函数直接用worker.trigger/iii trigger或通过绑定事件并附加可选条件门控参见 Triggers。巡检 worker查看某个 worker 的状态、跟踪日志或在 worker 的沙箱内执行命令iii worker status name # 配置、沙箱状态、近期日志 iii worker logs name # 流式输出 worker 日志 iii worker exec name -- command # 在 worker 内执行命令细节补充见 app.rsstatus默认会实时刷新直到 worker 进入成功或失败状态引擎未运行时立即退出。加--no-watch可打印一次状态后立即退出。logs从本地日志文件~/.iii/logs/{name}/读取-f/--follow可跟踪输出。exec把 stdin/stdout/stderr 管道透传并返回子进程退出码-e KEYVALUE设置环境变量可重复-w指定来宾内工作目录默认/workspace-t分配交互式 PTYstdin 与 stdout 均为 TTY 时自动开启可用--no-tty强制管道模式--timeout用 humantime 语法如30s、5m限定执行时长超时发送 SIGKILL 并以退出码 124 结束与 coreutilstimeout(1)一致便于脚本区分超时与普通非零退出。命令及参数须放在--之后例如iii worker exec pdfkit -- /bin/ls -la /workspace。更新 workeriii worker update重新解析被锁定的 worker并把新固定的版本写回iii.lock。传入 worker 名称则只更新这一个省略则更新所有被锁定的 workeriii worker update worker-name # 只更新一个 iii worker update # 更新全部锁定 worker从 CLI 定义看Update的可选参数正是更新 iii.lock 中固定的 worker 到注册表最新发布版本并重写 config.yaml 与 iii.lock见 app.rs。移除 workeriii worker remove将 worker 从config.yaml中移除引擎会随之拆除正在运行的 worker 进程iii worker remove -y worker-name # -y 在 worker 运行时跳过确认提示源码注释确认Remove会从 config.yaml 与 iii.lock 中移除一个或多个 worker引擎的文件监听器负责拆除对应沙箱下载的构件保留在~/.iii/managed/{name}/见 app.rs。被下载的构件在移除后仍留在磁盘上。要连构件一起删除使用iii worker clear -y worker-name省略名称则清理所有 worker 的构件。clear是纯本地操作无需连接引擎只清理~/.iii/下下载的构件不影响 worker 自身的构建产物如node_modules、Cargo.lock见 app.rs。Worker 技能Skills面向 Agent 的能力扩展每个 worker 还会附带面向 Agent 化工作Agentic work的技能skills。技能由skillsworker 管理——它是一个正在积极开发的内容注册表 worker可以像任何其他 worker 一样添加到项目中。技能正文采用惰性加载顶层条目保持精简当某个函数引用解析到深层内容时Agent 才会通过iii://worker/leaf分节 URI 获取更深入的内容。iii 还内置了高层级技能让任何 Agent 都能立即使用 iii 及其 worker。需要说明的是该部分目前以skillsworker 的 v0.2.4 版本为准其 API 在稳定发布前可能变化文档中的 TODO 注释也提示了这一点见 workers.mdx。可用的函数与触发器函数和触发器来自已连接的 worker。要使用某种类型的触发器提供该触发器的 worker 必须处于连接状态。例如通过 iii-http worker 添加http触发器后你就可以像在 Express 或 FastAPI 这类 Web 框架中一样为你的函数暴露 HTTP 端点。这印证了 worker 的价值能力即插即用——worker 一旦连接它注册的函数通过function_id可调用和触发器其他 worker 可绑定就立即可用。版本管理semver、版本固定与 iii.lock版本固定Version pinsiii worker 遵循 semver。不带版本说明符安装会选取最新 release追加version可固定特定版本而非跟踪最新版iii worker add iii-state1.2.0该固定记录在iii.lock中并在之后每次安装时重放保证跨机器、跨平台的安装结果一致。锁文件 iii.lockiii.lock是位于项目根目录的 YAML 文件将每个受管理 worker 固定到特定版本与来源确保同一组 worker 在不同机器和平台上以相同方式安装。二进制 worker 可以在同一个锁文件中固定各平台的构件macOS、Linux、Windows而 Docker / OCI 镜像形态的 worker 则跨平台统一运行。从源码看锁文件的结构定义在 crates/iii-worker/src/cli/lockfile.rs顶层字段包括version锁文件格式版本当前为1、manifest_hashmanifest 依赖序列化的 SHA-256前缀形如sha256:v1:64-hex用于漂移检测、declared_dependencies写入锁时项目iii.worker.yaml声明的依赖让漂移报告能指出具体增删改的依赖以及workers名称到锁定条目的映射见 lockfile.rs每个LockedWorker记录version、typebinary/image/engine/bundle、dependencies和可选的source见 lockfile.rssource按kind区分binary按平台给出artifacts每个构件含 URL 与 sha256、imageOCI 镜像引用与bundle归档 URL 加 sha256见 lockfile.rs。将iii.lock与config.yaml一起提交即可实现可复现安装。直接操作锁文件的命令有两个iii worker sync # 严格按照 iii.lock 安装 worker iii worker sync --frozen # CI 形态仅校验锁文件不修改本地文件 iii worker verify # 报告 config.yaml 与 iii.lock 之间的漂移iii worker update是第三个与锁文件相关的命令它把固定版本重新解析为允许范围内的最新版本并写回iii.lock见 app.rs 中Sync与Verify的定义。其中verify还支持--strict额外核对依赖声明与锁定版本是否一致sync --frozen用于 CI/CD 中校验锁文件而无副作用。编写 workerAuthoring workers创建新 workeriii worker init、在 worker 代码中注册函数与触发器、以及构建或发布 worker 镜像均超出本文范围。需要时参见 Creating Workers / Workers。简单提示iii worker init支持typescriptts、javascriptjs、pythonpy、rustrs四种语言会生成包含 iii SDK、iii.worker.yaml清单及示例函数/触发器注册的独立项目目录worker 通过III_URL环境变量约定引擎 WebSocket 地址连接字符串是 worker 与 iii 实例之间唯一的耦合点因此 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），仅供参考