iii Worker 管理完全指南：从安装、生命周期到锁文件版本化与 RBAC 访问控制

iii Worker 管理完全指南从安装、生命周期到锁文件版本化与 RBAC 访问控制【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本文基于 iii 仓库的官方文档 Workers 使用指南 展开系统讲解 worker 在 iii 项目中的定位、WebSocket 生命周期、iii workerCLI 的完整命令族add/list/start/stop/status/logs/exec/update/remove/clear/sync/verify以及iii.lock锁文件的版本固定机制。读完后你可以独立完成 worker 的查找、安装、启停、检查、升级与清理并理解其背后的源码实现iii-workercrate 的 CLI 入口、WorkerSource解析与确认流程。Worker 的定位与生命周期Worker 是 iii 中自包含、隔离、可互相协作的服务你在 iii 项目中添加的任何功能能力都会以 worker 的形式出现。与传统服务不同worker 不需要任何集成工作而是像 npm 包一样用iii worker add安装和管理区别是它交付的是完整的可部署运行时而非库。Worker 通过WebSocket连接到 iii 引擎连接建立后该 worker 对整个 iii 系统以及系统中的其他所有 worker 可见连接断开后它的 functions 和 triggers 将不可被调用直到重新连接。引擎侧的 WebSocket 处理逻辑可以参见 engine/src/workers/worker/ws_handler.rs。从 worker 代码侧建立连接的 SDK 调用registerWorker()等见 Creating Workers / Workers 的 Connecting to the engine 章节。不受信任的 Worker 与访问控制引擎默认监听端口会信任任何连接到它的客户端——这对于你自己运行的 worker 没有问题但你无法控制的 worker、浏览器客户端或第三方 worker 不应该获得同样的无限制访问权。为此iii 提供了iii-worker-managerworker它暴露一个独立的基于角色的访问控制RBAC监听器iii worker add iii-worker-managerRBAC 监听器会在每个连接上运行你编写的 auth 函数用于决定是否接纳或拒绝该连接决定该连接可以使用哪些 functions 和哪些类型的 triggers。这样不受信任的 worker 只能看到你显式授权的能力面function/trigger 类型白名单。相关的 auth 与 middleware 函数结构、完整连接流程参见 iii-worker-manager worker 的官方页面。引擎侧对应的 RBAC 配置与会话实现位于 engine/src/workers/worker/rbac_config.rs 与 engine/src/workers/worker/rbac_session.rs。使用iii workerCLI 管理 Workeriii worker命令族覆盖项目中每个 worker 的完整生命周期在 registry 中查找、安装到config.yaml与iii.lock、控制运行状态、查看日志、以及移除不再需要的 worker。从源码结构看引擎二进制并不直接实现这些命令iiiCLI 会把iii worker ...分发给独立的iii-worker二进制其入口在 crates/iii-worker/src/main.rs引擎根 CLI 会显式拒绝该命令参见 engine/src/main.rs 中的测试worker_is_no_longer_a_public_command。查找 Workeriii 官方维护了一个 worker registry收录了大量封装常见服务的 worker。更多 registry 信息见 Worker Registry。添加 Worker前置条件需要先 安装 iii 并启动引擎。要临时拉起一个 iii 实例做测试可运行iii --use-default-config见 引擎默认配置。Worker 可以从三种来源添加iii worker registry、Docker/OCI 兼容镜像仓库、或本地开发的 worker本地 worker 的脚手架方式见 Scaffold a new Worker。iii worker add iii-state # 从 iii registry 下载并添加 worker iii worker add ./workers/my_worker # 添加用 iii worker init 创建的本地 worker iii worker add ghcr.io/org/worker:tag # 从 Docker/OCI 镜像仓库拉取并添加添加后worker 会写入config.yaml并自动启动。要强制重新下载已有 worker使用iii worker reinstall name等价于add --force。这三种来源在源码中有一一对应的枚举定义 WorkerSourceRegistry { name, version: OptionString }registry slug如pdfkit可选 semver 版本缺省取最新稳定版Oci { reference }完整 OCI 引用如ghcr.io/iii-hq/node:latestLocal { path }引擎/守护主机上的 worker 项目目录目录内必须包含iii.worker.yaml清单清单字段包括name、scripts.start/setup/install、dependencies、resources.cpus/memory、env、runtime.base_image等。CLI 输入到来源的解析逻辑见 parse_source_for_cli裸名称走 registry带镜像仓库前缀走 OCI路径走 local。重要提示iii worker add从远端仓库iii registry 或 OCI registry或本地文件夹下载 worker 镜像然后在**微虚拟机microVM**中运行。类似caller-worker:latest的裸引用只会在上述远端仓库中查找iii不会从本地 Docker daemon 读取镜像所以你用docker build构建的本地镜像无法按名称被 iii 找到。本地构建的 Docker 镜像仍可按普通 Docker 镜像方式运行和测试docker run -it caller-worker:latest。此外AddOptions 的结构还定义了若干安装行为参数force删除缓存产物后强制重新下载用于恢复损坏的缓存、reset_config重新添加前重置该 worker 的config.yaml配置块常与 force 组合做干净重装、yes当 registry 依赖图超过 32 个 worker 时跳过确认、wait默认阻塞等待 worker 就绪。reinstall命令在实现上正是以force: true复用add路径见 crates/iii-worker/src/main.rs。固定 Worker 版本Registry worker 以 semver 版本发布。不指定版本时取最新 release在 registry 名称后追加version即可固定到特定 release而不是跟踪 latestiii worker add iii-state1.2.0固定的 pin 会记录到iii.lock中并在后续每次安装时按此重放。配置文件的组织当前仓库结构需要注意配置的组织方式随版本演进。以当前仓库快照为例引擎自带配置 engine/config.yaml 的注释明确写道只有属于引擎生命周期engine lifecycle的 worker如iii-stream、configuration放在这里http、state、cron、queue、pubsub、bridge等项目级 worker归属worker-compose.yaml参见 engine/worker-compose.yaml。文档所述worker 添加到config.yaml描述的是iii worker add对项目声明文件的写入行为在不同版本中声明文件可能是config.yaml或worker-compose.yaml但版本固定统一记录在iii.lock。列出 Workeriii worker list显示项目config.yaml中声明的所有 worker 及其当前状态这是查看运行中/已停止 worker 列表的标准方式iii worker list启动与停止 Worker通过add添加的 worker 会随引擎自动启动。手动控制请使用start、stop、restart命令stop目前需要-y跳过交互式确认iii worker start name # 启动单个 worker iii worker stop -y name # 停止单个 worker-y 跳过确认提示 iii worker restart name # 先停后启需要说明的是这些命令管理的是 iii 用其内置虚拟化替你运行的 worker。但 iii 并非必须亲自运行 worker任何使用 iii SDK、调用registerWorker()并连接到 iii 实例的进程都是一个 worker。这一点在创建 worker或部署 iii 系统时会变得更加重要。如需调用运行中 worker 内的函数直接用worker.trigger/iii trigger或绑定到事件并附加可选的 condition 门控参见 Triggers。检查 Worker 状态查看某个 worker 的状态、跟随其日志、或在 worker 沙箱内执行命令iii worker status name # 配置、沙箱状态、近期日志 iii worker logs name # 流式查看 worker 日志 iii worker exec name -- command # 在 worker 内部运行命令更新 Workeriii worker update重新解析已锁定locked的 worker并把新的 pin 写回iii.lock。传入 worker 名称则只更新一个省略则更新所有已锁定的 workeriii worker update worker-name # 更新一个 worker iii worker update # 更新所有已锁定的 worker移除 Workeriii worker remove将 worker 从config.yaml中移除引擎会拆除正在运行的 worker 进程worker 正在运行时需-y跳过确认iii worker remove -y worker-name # -y 在 worker 运行中时跳过确认移除后下载的产物仍保留在磁盘上。要一并删除使用iii worker clear -y worker-name省略名称则清除所有 worker 的产物。源码层面remove的确认逻辑位于 crates/iii-worker/src/main.rs-y/--yes直接通过否则当 stderr 是终端时交互询问[y/N]在非交互环境如脚本中直接报错退出避免静默破坏。clear的交互确认在同一文件的 L271-L295。Worker Skills面向 Agent 的懒加载技能每个 worker 还附带面向 Agentic 工作的 skills由skillsworker 统一管理——它是一个持续开发的内容注册表型 worker添加方式与其他 worker 相同。关键机制是懒加载Skill 顶层条目保持小巧常驻上下文只有当某个 function 引用解析到深层内容时Agent 才会通过iii://worker/leaf形式的 section URI 按需拉取完整内容。iii 还随仓库发布了一批高层级 skills使任意 Agent 都能立即上手 iii 及其 worker可直接浏览 skills/ 目录如 iii-getting-started、iii-core-primitives。可用的 Functions 与 Triggers 从何而来Functions 和 triggers 都来自已连接的 worker。要使用某种类型的 trigger必须让提供它的 worker 处于连接状态。例如添加 iii-http worker 后即可使用http类型的 triggers把你的 function 暴露为 HTTP 端点——体验上与在 Express 或 FastAPI 这类 Web 框架中写路由一致。版本化与 iii.lock 锁文件iii worker 遵循 semver。项目在iii.lock中记录每个受管 worker 的解析版本从而保证跨机器、跨平台的可复现安装。版本 Pin前文已述不带版本说明符取最新 releaseversion固定具体 releasepin 记录到iii.lock并在后续每次安装时重放。锁文件iii.lockiii.lock是位于项目根部的 YAML 文件。它将每个受管 worker 固定到特定版本与来源使同一套 worker 在不同机器、不同平台上以相同方式安装。二进制 worker 可以在同一锁文件中固定各平台macOS、Linux、Windows的产物。建议将iii.lock与config.yaml一起提交以获得可复现安装。仓库根部的 engine/iii.lock 是一个真实样例version: 1 workers: iii-http: version: 0.13.0-next.1 type: engine dependencies: {}可以看到锁文件记录了 worker 名称、解析出的具体版本、worker 类型type: engine表示引擎内建/引擎管理的 worker以及依赖映射。直接操作锁文件的命令有两个加上下文的update共三个锁文件相关命令iii worker sync # 严格按照 iii.lock 安装 worker iii worker sync --frozen # CI 形态只校验锁文件不改动本地文件 iii worker verify # 报告 config.yaml 与 iii.lock 之间的漂移从源码看sync与verify分别对应 handle_worker_sync 与handle_worker_verify后者支持--strictupdate则通过 Update 命令 调用core::update将名称集合置空表示全部已锁定 worker。小结场景命令安装registry / 本地 / OCIiii worker add name/add ./path/add ghcr.io/org/worker:tag固定版本iii worker add iii-state1.2.0强制重下iii worker reinstall nameadd --force查看列表与状态iii worker list、iii worker status name启停iii worker start/stop -y/restart name日志与沙箱内执行iii worker logs name、iii worker exec name -- cmd升级 piniii worker update [name]锁文件复现安装iii worker sync、sync --frozen、iii worker verify移除与清理iii worker remove -y name、iii worker clear -y [name]worker 的编写iii worker init脚手架、在 worker 代码中注册 functions/triggers、构建与发布镜像不在本篇范围内请参见 Creating Workers / Workers。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考