iii Worker Registry 使用指南浏览、安装与管理可组合 Worker【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本指南以 iii 项目的官方 Worker Registry 为核心讲解如何浏览注册表、通过iii worker add从三种来源安装 Worker以及理解注册表 Worker 的制品类型、版本锁定与底层解析机制。读完本文你将掌握在项目中检索并安装第三方 Worker 的完整流程并能基于源码理解注册表解析、校验与缓存的具体原理。浏览注册表Browsing the registryiii 的 Worker Registry 托管在官方站点workers.iii.dev是可安装 Worker 的索引。可以把注册表理解为可部署运行时版的 npm registry你安装的不是一个库而是一个完整、可直接运行的 Worker 运行时。每个 Worker 页面会列出以下信息用于帮助你在安装前判断它是否满足项目需求提供的 functions函数与 trigger types触发器类型决定安装后你能调用哪些能力、绑定哪些事件configuration schema配置模式安装后需要或可以填写的配置项supported platforms支持的平台该 Worker 制品覆盖哪些操作系统与架构agent skillsAgent 技能Worker 附带的、供 Agent 化工作流使用的内容能力。也就是说注册表不仅是下载入口更是 Worker 的能力目录——先浏览、比对能力再用iii worker add把它装进项目。此外Worker 也可以发布在 Docker 与 OCI 兼容的镜像仓库中通过镜像引用直接安装见下文添加 Worker。从源码结构看注册表 Worker 的函数 / 触发器 / 配置 / 技能信息对应到仓库中 registry.rs 解析的ResolvedWorker结构binaries各平台二进制制品、archive_url/sha256bundle 制品的归档与摘要、configWorker 自带的默认配置这些字段正是worker 页面信息在解析层的落点。添加 WorkerAdding a workeriii worker add接受三种来源在所有情况下Worker 都会被写入项目的config.yaml并自动启动iii worker add iii-state # registry name注册表名称 iii worker add ./workers/my-worker # local path本地路径 iii worker add ghcr.io/org/worker:tag # Docker or OCI image容器镜像引用三种来源分别对应来源示例说明注册表名称iii worker add iii-state从workers.iii.dev解析并安装可追加版本号锁定版本本地路径iii worker add ./workers/my-worker安装本地 Worker 目录目录内需包含iii.worker.yaml清单Docker / OCI 镜像iii worker add ghcr.io/org/worker:tag按镜像引用安装运行在 OCI 运行时之上三种来源在源码中如何区分从源码结构看来源的判定逻辑位于 edit.rs 的parse_worker首字符是.或/即为本地路径其余一律视为注册表引用。因为注册表引用本身可能带主机名如api.workers.iii.dev/state或作用域如team/worker所以是否含斜杠不能作为判断依据——这是路径与包引用最关键的区分点state→ 解析为api.workers.iii.dev/state默认注册表主机见 edit.rs 中的DEFAULT_REGISTRY_HOSTnameversion→ 从最右侧切分出版本号例如iii-state1.2.0./workers/api→ 本地路径容器键取路径最后一段目录名api。写入config.yaml时注册表引用会被记录为worker: package://api.workers.iii.dev/state、version: 1.2.0的形式并附带# added by compose::add标记见 edit.rs文件按文本拼接方式编辑保留你原有的注释、空行与引号风格不会因序列化往返而丢失。安装后的自动启动安装完成后 Worker 会被自动启动。iii worker add默认最多等待 120 秒等待 Worker 向引擎报告就绪超时后命令返回 shell但 Worker 会继续启动。之后可用iii worker status name继续观察启动过程用iii worker logs name查看日志。制品类型Artifact types注册表里的每个 Worker 都以两种形态之一发布原生二进制native binary按平台分别发布制品覆盖 macOS、Linux 与 Windows。安装时会根据当前主机选择对应的平台制品Docker / OCI 兼容镜像Docker / OCI compatible image可在所有受支持平台上运行不区分平台制品。平台制品的底层选择逻辑从源码看平台选择由 registry.rs 的host_target()函数完成它通过编译期cfg!判断当前运行环境返回诸如x86_64-unknown-linux-gnu、aarch64-apple-darwin、x86_64-pc-windows-msvc之类的 target triple。由于 compose 守护进程与其子进程运行在同一台机器上因此守护进程的 target 就是子进程需要运行的 target无需运行时探测。原生二进制制品按name-version-target-sha256摘要目录名缓存若解析结果中没有当前平台的binaries条目安装会在下载前直接失败并列出可用平台UnsupportedPlatform错误避免浪费带宽。版本管理与锁定Versioning and pinning注册表 Worker 按semver 语义化版本发布。安装时不带版本号则选取最新发布版本用version追加在注册表名称后即可锁定某个具体版本iii worker add iii-state1.2.0锁定的版本会记录在项目根目录的iii.lock中并在之后的每次安装中回放从而保证跨机器、跨平台的可复现安装。二进制 Worker 可以在同一份 lockfile 中按平台macOS / Linux / Windows分别锁定制品。仓库中的 engine/iii.lock 就是一个真实示例version: 1 workers: iii-http: version: 0.13.0-next.1 type: engine dependencies: {}升级与回滚iii worker update重新解析iii.lock中锁定的 Worker 到最新允许版本并回写 lockfile带 Worker 名则只更新一个省略则更新全部修改锁定版本等同于请求升级或回滚对已存在的同容器条目compose::add会就地替换version:字段同时保留该条目中你手写的其他字段如env_file、config_name不会因为升级丢失凭据配置。锁文件相关命令与iii.lock直接相关的三条命令iii worker sync # 完全按照 iii.lock 安装 Worker iii worker sync --frozen # CI 形态只校验锁文件不改动本地文件 iii worker verify # 报告 config.yaml 与 iii.lock 之间的漂移注册表解析的底层原理Resolve → Verify → Cache安装一个注册表 Worker 时底层走的是解析、校验、缓存三步流水线全部实现在 registry.rsResolve解析compose 向注册表发送POST /resolve请求携带worker名称、version范围与target平台注册表返回该 Worker 及其完整依赖图的 URL 与 SHA-256 摘要。解析请求最多重试 3 次每次 20 秒超时、间隔 250ms 递增只对瞬时故障5xx、请求超时、429重试客户端错误直接返回——测试resolve_retries_a_transient_server_failure与resolve_does_not_retry_a_client_error分别验证了这两种行为Verify校验任何归档在写入磁盘前都要先做 SHA-256 摘要比对。下载内容与注册表承诺的摘要不一致时不会被当作慢下载或损坏下载处理而是被视为与注册表承诺不同的制品直接拒绝落盘PackageDigestMismatch错误。bundle 制品如果缺少archive_url sha256配对同样拒绝安装Cache缓存安装目录以包元数据 target SHA-256为键因此只有经过校验的精确制品才会在多个注册表与多个项目之间复用。第二次安装同一版本时直接命中缓存InstallStatus::Cached不再触碰网络——测试a_second_install_reuses_the_downloaded_artefact验证了这一点而同名同版本但摘要不同的制品会被视为不同制品而重新下载测试same_name_and_version_with_a_different_digest_is_downloaded_again。下载与解压采用先解压到带 UUID 的 staging 目录、校验通过后 rename 发布的策略中途崩溃不会留下被误判为缓存命中的半解压目录两个容器并发安装同一制品时后到者发现目标目录已就绪便直接复用对方的其校验已通过不会破坏正在执行的目录。更多iii worker子命令除add外iii worker命令集还覆盖 Worker 的完整生命周期详见 workers.mdx 与 app.rsiii worker list # 列出 config.yaml 中声明的全部 Worker 及状态 iii worker start name # 启动一个 Worker默认等待 120s 就绪 iii worker stop -y name # 停止一个 Worker iii worker restart name # 先停后启 iii worker status name # 查看配置、沙箱状态与近期日志 iii worker logs name # 流式查看 Worker 日志 iii worker exec name -- command # 在 Worker 的沙箱/VM 内执行命令 iii worker remove -y name # 从 config.yaml 移除并让引擎回收运行进程 iii worker clear -y name # 删除磁盘上的下载制品省略名称则清空全部移除后下载的制品仍留在磁盘上默认位于~/.iii/managed/{name}/需要彻底清理时再用iii worker cleariii worker reinstall name等价于add --force用于强制重新下载。小结iii Worker Registry 是可安装运行时的索引在workers.iii.dev浏览能力用iii worker add从注册表名称、本地路径或 OCI 镜像三种来源安装靠 semver 加iii.lock锁定版本以原生二进制或 OCI 镜像两种制品形态跨平台交付。底层则由 registry.rs 的解析 → 校验 → 缓存三步流水线保障安装的确定性、完整性与可复现性——这正是 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），仅供参考