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 Registry 是什么、如何用iii worker add从三种来源注册表名称、本地路径、Docker/OCI 镜像安装 worker以及 worker 的制品类型与版本固定机制。结合 iii 仓库中iii-workerCLI 的实际解析源码本文进一步还原iii worker add背后的注册表解析、依赖图下载与iii.lock锁文件流程使你在完成 worker 安装实操的同时能够理解每一步命令在引擎内真实发生的事。一、什么是 iii Worker Registryiii 的 Worker Registry注册表地址为 workers.iii.dev是外部站点此处仅作名词说明是全部可安装 worker 的索引。每个 worker 的页面会列出以下关键信息该 worker 提供的functions可被触发调用的函数与trigger types触发器类型该 worker 的配置 schema配置字段的结构与取值支持的平台macOS / Linux / Windows 等随 worker 附带的agent skills供 AI Agent 使用的技能条目。实际使用时的检索思路是先明确项目需要的一种能力例如 HTTP 端点、队列、状态存储再到注册表页面中按“函数 / 触发器 / 配置”三要素定位满足该能力的 worker。除了官方注册表worker 还可以发布在Docker 与 OCI 兼容的镜像仓库中——这直接对应后文iii worker add的第三种来源。CLI 源码中同样内置了注册表地址作为引导信息见 engine/src/trigger.rs。二、iii worker add三种 worker 来源iii worker add接受三种来源。在所有情况下worker 都会被写入项目根目录的config.yaml并自动启动无需手动配置启动项iii worker add iii-state # 来源 1注册表名称 iii worker add ./workers/my-worker # 来源 2本地路径 iii worker add ghcr.io/org/worker:tag # 来源 3Docker 或 OCI 镜像三种来源的含义来源适用场景解析行为结合源码可确认注册表名称使用官方/社区发布的现成 worker调用注册表 API 解析出制品类型、版本与下载地址见下文“注册表解析机制”本地路径自研 worker 的开发调试以目录形式接入走本地 worker 安装通道相关实现位于 crates/iii-worker/src/cli/local_worker.rsDocker/OCI 镜像自托管或第三方镜像仓库中发布的 worker解析镜像引用参考 crates/iii-worker/src/cli/oci_ref.rs在任何受支持平台上以镜像方式运行一个真实可参考的配置形态来自引擎内置的queueworker 文档通过package://协议 URL 从注册表解析 worker并显式写死version字段见 engine/src/workers/queue/README.mdcontainers: queue: worker: package://api.workers.iii.dev/queue version: 0.21.5 config_name: queue版本固定pinning与更新注册表中的 worker 以semver 版本号发布。不指定版本时安装最新发布版在名称后附加version可固定特定版本iii worker add iii-state1.2.0 # 固定到 1.2.0nameversion的拆分在源码中由parse_worker_input完成——以第一个为界切分为名称与版本两部分不带则版本为None取最新见 crates/iii-worker/src/cli/registry.rs。固定下来的版本会记录进项目根目录的iii.lock锁文件之后每次安装都按锁文件回放保证同一 iii 系统部署在不同机器上可复现。更新则用iii worker update name单个或iii worker update全部锁定 worker重新解析并回写iii.lock。更多版本与更新细节见 docs/0-12-0/using-iii/workers.mdx 中的“Versioning and pinning”与“Updating a worker”小节。其他相关子命令速查完整的iii worker子命令集start / stop / restart / remove / clear / sync / verify 等在 docs/0-12-0/using-iii/workers.mdx 有完整说明与注册表安装流程直接相关的几条iii worker reinstall name # 强制重新下载等价于 add --force iii worker remove worker-name # 从 config.yaml 移除并停止进程 iii worker sync # 严格按 iii.lock 安装 iii worker sync --frozen # CI 形态只校验锁文件不修改本地文件 iii worker verify # 报告 config.yaml 与 iii.lock 之间的漂移三、制品类型文档口径与源码中的完整枚举原文档的口径是每个注册表 worker 以原生二进制按 macOS、Linux、Windows 提供各平台制品或Docker/OCI 兼容镜像运行于所有受支持平台两种方式之一发布。从源码结构看CLI 实际识别的制品类型比文档口径更细。WorkerInfoResponse是一个按type字段区分的四元枚举见 crates/iii-worker/src/cli/registry.rs#[serde(tag type)] pub enum WorkerInfoResponse { #[serde(rename binary)] Binary(BinaryWorkerResponse), // 原生二进制各平台 URL sha256 #[serde(rename image)] Oci(OciWorkerResponse), // OCI/Docker 镜像image_url #[serde(rename engine)] Engine(EngineWorkerResponse), // 引擎内置 worker仅名称与版本 #[serde(rename bundle)] Bundle(BundleWorkerResponse), // 打包目录tar.gz 归档 sha256 }各类型的载荷字段与安装行为均以源码注释为准binarybinaries为“平台 → {url, sha256}”的映射下载后按 sha256 校验image只有image_url跨平台统一运行engine随 iii 引擎本体发布的内置 worker无需下载制品bundle打包好的 local-worker 目录 tar.gz 归档归档根必须包含iii.worker.yaml引擎下载、校验 sha256、原子解压后通过 libkrun 沙箱运行见 crates/iii-worker/src/cli/registry.rs 的注释。引擎自身维护的iii.lock就是一个 engine 类型的真实样例见 engine/iii.lockversion: 1 workers: iii-http: version: 0.13.0-next.1 type: engine dependencies: {}二进制工件的平台覆盖“按平台提供制品”这一点在引擎的托管二进制注册表中可直接验证。engine/src/cli/registry.rs 中的REGISTRY静态表为每个托管二进制声明了supported_targets覆盖aarch64-apple-darwin、x86_64-apple-darwin、x86_64-unknown-linux-gnu、x86_64-unknown-linux-musl、aarch64-unknown-linux-gnu及 Windows MSVC 目标has_checksum: true表明各平台制品均附校验和。该表中的iii-worker条目把iii worker子命令整体映射到独立二进制CommandMapping { cli_command: worker }说明iii worker add的执行体是随 iii 分发、按需解析平台制品的iii-worker程序。四、iii worker add 名称的注册表解析机制当来源是注册表名称时CLI 端有一个完整的“解析 → 校验 → 下载 → 写锁”流水线核心在 crates/iii-worker/src/cli/registry.rs。1. 端点与安全边界。默认 API 基址为https://api.workers.iii.devregistry.rs#L15可通过环境变量III_API_URL覆盖仅调试构建支持file://指向本地 fixture 文件用于离线/测试场景registry.rs#L190-L219。注册表 JSON 响应有 1 MiB 的大小上限MAX_REGISTRY_RESPONSE_BYTES目的是在依赖安全检查与下载字节上限生效之前先防止不可信注册表造成无界内存分配registry.rs#L16-L22。2. 名称校验。worker 名称只允许字母、数字、短横线、下划线和点且禁止以.开头、禁止..。源码注释解释了原因bundle 安装根目录保留.locks、.staging两个内部控制目录以点开头的 worker 名会在磁盘上遮蔽它们因此直接拒绝registry.rs#L170-L179。3. 版本查询参数。请求形如GET /download/{name}带版本时附加?versionv在 CI 环境探测GITHUB_ACTIONS、CI、JENKINS_URL等标准变量中附加citrue见with_download_queryregistry.rs#L54-L64。4. 依赖图解析。单个 worker 不是孤立下载的。解析结果ResolvedWorkerGraph包含根节点root、按版本解析出的 worker 列表graph每项含名称、类型、版本、制品地址、依赖映射与依赖边edges含语义化版本范围range见 registry.rs#L128-L168。这意味着执行iii worker add iii-state时该 worker 声明的依赖会被一并解析安装对 bundle 类型锁文件路径强制要求archive_url与sha256同时存在防止安装退化为不可校验的拉取registry.rs#L141-L150。5. 锁文件落盘。解析结果最终写入项目根目录的iii.lock。锁文件模块维护一个 format version当前version: 1写入采用“相邻临时文件 原子替换”避免半写文件读取时执行validate()不支持的 format 版本会被直接拒绝。相关实现与测试见 crates/iii-worker/src/cli/lockfile.rs测试覆盖了往返序列化、版本校验拒绝version: 2、原子写入不留临时文件等场景lockfile.rs#L678-L800。由此可以把文档中的一句话——“worker 被加入config.yaml并自动启动”——展开为完整链路iii worker add iii-state1.2.0 → parse_worker_input 拆分名称/版本 → validate_worker_name 名称校验 → GET https://api.workers.iii.dev/download/iii-state?version1.2.0 → 按 type 解析制品binary/image/engine/bundle → 展开依赖图graph edges下载并校验 sha256 → 写入/更新 config.yaml落盘 iii.lock → 引擎启动该 workerWebSocket 连上后可见其函数与触发器worker 通过 WebSocket 连上引擎后即可被整个系统与所有其他 worker 发现断连后其函数与触发器停止可调用直至重连见 docs/0-12-0/using-iii/workers.mdx 的“Worker lifecycle”一节。五、实操建议与适用范围可复现部署把iii.lock与config.yaml一起提交到版本库CI 流水线使用iii worker sync --frozen校验而不改写文件。版本策略开发期可不带版本跟随最新生产环境用version固定升级走iii worker update变更集中体现在iii.lockdiff 中。来源选择官方/社区能力优先注册表名称本地迭代用路径来源私有仓库或自托管发行用 OCI 镜像引用。平台前提binary 制品受各 worker 声明的平台目标约束Linux gnu/musl、macOS aarch64/x86_64 等可参照 engine/src/cli/registry.rs 的目标清单跨平台一致性要求高的场景可优先选 image 制品。适用版本说明本文基于 iii 仓库 0.12.0 文档目录docs/0-12-0/using-iii/workers-registry.mdx与当前iii-workerCLI 源码撰写原文档中标注的“LLM 浏览注册表”能力尚在 skills worker 中待稳定暂不作为可用特性描述。延伸阅读原文档skill 渲染版docs/0-12-0/using-iii/workers-registry.mdx.skill.mdWorkers 全生命周期与锁文件命令docs/0-12-0/using-iii/workers.mdx注册表解析与依赖图实现crates/iii-worker/src/cli/registry.rs锁文件读写与校验crates/iii-worker/src/cli/lockfile.rs托管二进制平台注册表engine/src/cli/registry.rs引擎内锁文件实例engine/iii.lock【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考