尧图网页设计 
iii Worker Registry 分发指南发布、Semver 版本化与 tar.gz Bundle 安装机制【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本文以 iii 项目的 worker registryworkers.iii.dev为核心系统讲解三类制品binary、image、bundle的发布与消费模型如何通过iii worker add name从注册表安装 worker、如何用 Semver 管理与固定版本、如何为多平台构建二进制制品以及 bundletar.gz 归档从响应结构、清单契约、安全策略到错误码的完整安装管线。读完本文你将掌握在任意 iii 项目中按名安装、更新、固定、移除注册表 worker 的完整方法并理解其底层下载校验、沙箱提取与原子安装机制。Registry已发布 worker 的公共仓库iii registryworkers.iii.dev是所有已发布 worker 的存放处发布者把 worker 上传到注册表后其他 iii 项目就可以用一行命令把它安装进自己的工程iii worker add name从解析器的数据结构可以清楚看到注册表支持的四种响应形态见 crates/iii-worker/src/cli/registry.rs 的WorkerInfoResponse枚举响应type制品形态关键字段binary按平台三元组分发的二进制包binaries每个目标平台一个urlsha256、configimageOCI 镜像image_urlengine内建引擎 worker无制品体仅元数据无HTTP 204 响应bundle单一tar.gz归档打包源码 清单archive_url、sha256其中bundle类型对应BundleWorkerResponse结构registry.rs是本文后半部分的核心。注册表 API 默认地址为https://api.workers.iii.dev可通过环境变量III_API_URL覆盖仅 debug/test 构建允许file://本地夹具生产构建强制 HTTPS见 registry.rs 与fetch_worker_info的实现。发布一个 worker发布 worker 会把它的二进制或 OCI 镜像上传到注册表登记其 Semver 版本并让该 worker 可以在任何 iii 项目中按名字安装。一次发布产生的注册表条目对用户侧而言完全透明——安装命令始终是iii worker add name与制品类型无关binary、OCI、bundle 三种形态安装体验一致。发布动作背后的客户端行为可以对照源码验证fetch_worker_info会向GET {API}/download/{name}?version{v}发起解析请求404 返回 Worker not found204 表示 engine worker 无制品体其余成功响应按type字段反序列化为上述四种形态之一registry.rs。注册表响应本身被限制在 1 MiB 以内MAX_REGISTRY_RESPONSE_BYTES防止不可信注册表在解析阶段分配无界内存registry.rs。说明0-20-0 版本文档对“规范发布命令、认证要求、注册表期望的元数据描述、仓库 URL、支持的平台等”仍标注为 TODO当前仓库中发布侧 CLI 尚未固化以上解析与下载侧行为均有源码可查。版本化你的 worker注册表中的 worker 遵循 SemverPatch 递增修 bugMinor 递增新增能力向后兼容Major 递增函数签名或触发器签名发生破坏性变更。对使用方而言版本通过后缀固定iii worker add my-worker1.2.0会锁定到指定版本而裸iii worker add my-worker默认取最新版。解析层对nameversion的拆分为第一个之前的为名字、之后的为版本串parse_worker_input见 registry.rs因此版本串本身可以再包含如scopeorg1.0。解析出的精确版本会被记录在项目的iii.lock中跨机器、跨平台重放安装时保持一致保证可复现构建。相关 CLI 细节iii worker update重新解析并回写锁、iii worker reinstall强制重下可参见 docs/0-20-0/using-iii/workers.mdx。为多平台构建二进制制品二进制 worker 可以在单个注册表条目内同时发布多个平台目标的制品macOS arm64/x64、Linux arm64/x64/armv7、Windows arm64/x64/x86。一个已发布版本即可覆盖所有受支持的宿主无需按平台分别发布。源码中的响应结构与测试夹具印证了这一点BinaryWorkerResponse.binaries是一个以 Rust 目标三元组为键、以{url, sha256}为值的映射registry.rs。测试deserialize_binary_worker_response中的真实示例同时携带了aarch64-apple-darwin与x86_64-unknown-linux-gnu两个平台的制品 URL 与 SHA-256registry.rs。解析图请求还可以显式携带target字段由注册表按目标平台解析出对应的二进制。说明0-20-0 文档对“跨平台构建流程、具体目标三元组清单、制品签名/校验和方式、上传位置”仍标注为 TODO以上为文档已声明平台范围与源码可验证的响应结构。更新或移除已发布的 worker文档规划的维护路径如下0-20-0 版本仍标注为 TODO属于待固化内容发布新版本Semver 递增后重新发布semver bump republish弃用deprecate如何标记某个 worker 已弃用撤回yank/retract已发布版本是否可撤回、如何撤回。从安装侧源码看同名的重复安装是安全的bundle 安装以~/.iii/workers-bundle/{name}/为全局缓存键重新iii worker add会通过“先改名搁置旧版本、再原子替换、失败回滚”的方式原地替换atomic_install见下文“原子安装”小节旧版本永远不会在替换失败时丢失。移除命令为iii worker remove -y name如需连下载的制品一并删除使用iii worker clear -y name。Bundle Workerstar.gz 归档分发Bundle 是继binary、image之后的第三种制品形态。注册表为它提供一个单一的tar.gz归档归档内是打包好的 worker 源码归档根目录放一个iii.worker.yaml清单。iii worker add name会下载归档、校验 SHA-256、把归档解压到~/.iii/workers-bundle/name/然后走与本地路径local-pathworker 完全相同的 libkrun 沙箱通道运行——区别仅在于 bundle 没有宿主机侧的源码 watcher。何时使用 bundle你发布的是预构建的 JavaScript 包esbuild、tsdown、bun build或打包好的 Python worker并且不想发布 Docker 镜像你希望制品以KB 而非 MB计量归档内只携带打包后的源码运行时随引擎白名单基础镜像一起提供docker.io/iiidev/node:latest或docker.io/iiidev/python:latest你希望安装体验与其他注册表 worker 完全一致——对用户来说就是iii worker add my-worker与 binary、OCI 无异。Registry 响应结构bundle 类型的注册表条目形如{ type: bundle, name: my-worker, version: 1.2.0, archive_url: https://cdn.workers.iii.dev/my-worker/1.2.0/bundle.tar.gz, sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 }引擎GETarchive_url把字节流送入 SHA-256 哈希器与sha256比对。任何不匹配都会中止安装并立即删除已下载的 blob绝不让一个校验失败的归档残留在磁盘上。源码实现download_archive见 crates/iii-worker/src/cli/bundle_download.rs还进一步收紧了这条链路的信任边界SSRF 防护下载前拒绝明文 HTTP、file:、ftp:以及指向非路由/链路本地/私网段的字面 IP如云厂商 IMDS169.254.169.254。重定向同样逐跳重新校验每个Location:头都会再过一遍 SSRF 守卫并限制最多5 跳防止公开 CDN URL 被重定向进内网或触发重定向炸弹本地开发逃生口localhost/127.0.0.1/::1仅在显式设置III_BUNDLE_DEV_LOOPBACK1时才放行且不作用于重定向每次安装都会打印黄色警告生产构建默认拒绝回环地址全局开关设置III_BUNDLE_WORKERS_DISABLED1可整体禁用 bundle worker 的安装与启动管线下载限额HTTP 客户端超时 120 秒响应流式写入磁盘并受 64 MiB 总量上限与application/内容类型前缀约束本地缓存已验证的 blob 会按 SHA-256 入缓存缓存命中后复制进 staging 再二次重算哈希堵住“查缓存→复制”窗口期的 TOCTOU 竞态校验失败的缓存条目会被驱逐并回退网络重下。归档布局归档根目录必须包含iii.worker.yaml。除此之外的任何内容都放在 bundle 视角下运行时可发现的路径上my-worker-1.2.0.tar.gz ├── iii.worker.yaml ├── bundle.js └── assets/ └── ...清单契约iii.worker.yamlBundle 清单是本地 worker 清单的一个严格子集有三个字段被显式拒绝scripts.setup会在安装期间执行发布者提供的 shell——这是供应链走私supply-chain smuggling向量scripts.install同理。依赖应当被打进 bundle而不是安装时现场拉取runtime.base_image允许 bundle 以任意 OCI 镜像作为 rootfs 是危险的。bundle 固定使用引擎白名单基础镜像。必填字段name必须等于安装目标即传给iii worker add的名字scripts.start非空 shell 字符串引擎在沙箱 VM 内对它执行exec。示例node bundle.js、python -m worker、bun run bundle.js。可选字段超出引擎上限时被钳制并产生W182 BundleResourceClamped警告resources.cpus默认2上限钳制为4resources.memory默认2048MiB上限钳制为4096MiB。完整示例name: my-worker version: 1.2.0 scripts: start: node bundle.js resources: cpus: 2 memory: 2048校验器实现validate_bundle_manifest见 bundle_download.rs逐条落实上述契约清单文件大小在读入前就被限制在64 KiBMAX_BUNDLE_MANIFEST_BYTES——这是对 YAML “billion-laughs” 别名校膨胀攻击的防御serde_yaml0.9.x 基于 libyaml不限制指数级别名展开64 KiB 上限保证最坏情况下内存膨胀也停留在数 MiB 量级name缺失或不等于安装目标 → 拒绝W180scripts.setup非空 → 拒绝W180runtime.base_image若出现必须是“合理的 OCI 引用”字母数字加._-/:如oven/bun:1否则在安装期直接失败W180而不是等到启动期静默回退默认镜像scripts.start缺失或为空 → 拒绝W180。资源解析parse_bundle_resourcesResourceCaps见 bundle_download.rs同样受 64 KiB 清单上限保护默认上限4CPU /4096MiB 与本地 worker 的PerImageCap语义对齐当请求超过上限时返回“钳制后数值 原始请求值”由调用方发出 WARN 事件遵循“零静默失败Prime Directive”原则。归档安全策略Bundle 归档使用比 OCI 层更紧的提取限制限制项值解压后总大小64 MiB单个文件最大32 MiB最大条目数1024最大目录深度16允许的 tar 条目类型Regular、Directory包含符号链接、硬链接、字符设备、FIFO或带..路径组件的归档一律以W181 BundleArchiveUnsafe拒绝。源码常量与提取器extract_bundle_safely_blocking见 bundle_download.rs逐项落实并多加了数道防线常量定义MAX_BUNDLE_TOTAL 64 MiB、MAX_BUNDLE_FILE 32 MiB、MAX_BUNDLE_ENTRIES 1024、MAX_BUNDLE_DEPTH 16bundle_download.rs。相比之下 OCI 提取器面向 10 GiB / 百万条目设计且不显式拒绝符号链接bundle 是发布时构建的单体制品任何合法内容都不该是符号链接因此采用更紧的专用提取器路径校验拒绝绝对路径、拒绝..组件、拒绝RootDir/Prefix组件并对“合成目标路径脱离目标根”做最终兜底检查防御 unicode 归一化等绕过条目类型白名单仅Regular与Directory其余类型Symlink/Link/Char/Block/Fifo/GNUSparse 等全部拒绝tar 库设置set_preserve_permissions(true)、set_unpack_xattrs(false)、set_overwrite(true)从根部拒绝解析内部符号链接特权位剥离文件解压后模式掩码为0o0777setuid/setgid/sticky 位全部丢弃——bundle 永远不会提权运行CPU 密集解压放后台线程解压与条目校验走tokio::task::spawn_blocking避免阻塞异步运行时。原子安装与进程崩溃安全安装不是简单地“解压到目标目录”而是一套完整的原子化替换协议atomic_install/StagingGuard见 bundle_download.rs 与 bundle_download.rs所有工作都在~/.iii/workers-bundle/.staging/rand/内进行StagingGuard持有该 worker 的独占文件锁fslock并拥有 staging 目录Drop时先删 staging 目录、后释放锁Rust 字段按声明顺序 drop杜绝并发安装看到半清理状态最终一步是同文件系统的原子rename跨文件系统时退化为“先复制到{name}.partial.*兄弟目录再原子改名”中途失败绝不让半成品出现在iii worker list里替换旧版本采用“改名搁置rename-aside”旧目录先被改名为{name}.old.unique新树安装成功后才清理它新安装失败则把旧目录改回原位旧版本永远不丢进程被杀导致的残留 staging 目录由启动期的sweep_orphans()清扫{name}.old.*残留则在下一次成功安装同一 worker 时清扫sweep_stale_old_siblings——因为搁置的兄弟目录可能是该 worker 的唯一剩余副本绝不能提前删。错误码代码失败场景W142归档下载失败HTTP 错误、意外的 Content-Type、超过大小上限、SHA-256 不匹配。W180清单被拒绝出现scripts.setup、runtime.base_image等禁用字段或name/scripts.start不符合契约。W181归档含不安全条目符号链接、硬链接、路径穿越、超大文件、条目过多。W182资源请求超出引擎上限安装以钳制后的值继续警告而非失败。W183依赖图过宽或过深。这些错误码在 crates/iii-worker/src/core/error.rs 中一一对应Download (W142)、BundleManifestRejected (W180)、BundleArchiveUnsafe (W181)、BundleResourceClamped (W182)、BundleDepGraphExceeded (W183)并统一映射为W前缀的警告/错误事件。源码侧说明当前 crates/iii-worker/src/cli/registry.rs 的依赖图校验已从“深度 5 / 节点 32 的硬性拒绝”演进为“结构校验名字唯一、边指向已声明节点、可达性、无环 节点数超过 32 时要求显式确认LARGE_DEPENDENCY_GRAPH_THRESHOLD”因此W183所对应的“过宽/过深”判定在最新代码中表现为确认门槛而非硬失败文档表列出的仍是 0-20-0 版本契约的描述。安装位置与解析优先级Bundle worker 是按名字共享的机器级缓存不属于某个具体项目安装在~/.iii/workers-bundle/{name}/bundle_worker_path见 crates/iii-worker/src/cli/config_file.rs与二进制 worker 的~/.iii/workers/分离使解析器可以不读内容直接按目录判别安装类型。bundle_workers_dir()→~/.iii/workers-bundle/内部保留.locks/与.staging/作为控制目录bundle_is_installed(name)要求目录存在且含合法iii.worker.yaml才视为已安装——一个空目录或逃逸的 staging 目录不会造成误判worker 名校验validate_worker_name只允许字母数字、-、_、.禁止空名与..并禁止以.开头——否则iii worker remove .locks会通过remove_dir_all把全系统的 per-worker 文件锁目录一并清掉registry.rs解析优先级为本地路径 worker OCI 镜像 bundleresolve_worker_typeconfig_file.rs。已有二进制的同名 worker 在 bundle 根目录加入后仍解析为 Binary——空 bundle 目录不会遮蔽二进制安装集成测试将其列为回归关键项见 crates/iii-worker/tests/bundle_worker_integration.rs 的覆盖清单。安装后的日常管理走标准iii worker命令iii worker list查看状态、iii worker start/stop/restart控制启停、iii worker status/logs/exec检查状态与日志、iii worker update重新解析锁定的版本、iii worker remove -y name移除iii worker clear -y name连同制品一并删除。bundle 与本地 worker 共用 libkrun 微虚拟机沙箱通道但没有宿主机侧的源码 watcher——bundle 是发布时定型的制品不做热重载。进一步阅读本地 worker 清单完整字段参考docs/0-20-0/creating-workers/worker-manifest.mdxbundle 清单是其严格子集iii worker全生命周期命令与版本固定/锁文件docs/0-20-0/using-iii/workers.mdx从零创建 workeriii worker init脚手架docs/0-20-0/creating-workers/workers.mdx安装管线核心实现crates/iii-worker/src/cli/bundle_download.rs注册表解析与依赖图校验crates/iii-worker/src/cli/registry.rs错误码定义crates/iii-worker/src/core/error.rs提取安全、清单契约、资源钳制与原子安装的集成测试覆盖crates/iii-worker/tests/bundle_worker_integration.rs【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 iii Worker Registry 分发指南：发布、Semver 版本化与 tar.gz Bundle 安装机制
iii Worker Registry 分发指南发布、Semver 版本化与 tar.gz Bundle 安装机制【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本文以 iii 项目的 worker registryworkers.iii.dev为核心系统讲解三类制品binary、image、bundle的发布与消费模型如何通过iii worker add name从注册表安装 worker、如何用 Semver 管理与固定版本、如何为多平台构建二进制制品以及 bundletar.gz 归档从响应结构、清单契约、安全策略到错误码的完整安装管线。读完本文你将掌握在任意 iii 项目中按名安装、更新、固定、移除注册表 worker 的完整方法并理解其底层下载校验、沙箱提取与原子安装机制。Registry已发布 worker 的公共仓库iii registryworkers.iii.dev是所有已发布 worker 的存放处发布者把 worker 上传到注册表后其他 iii 项目就可以用一行命令把它安装进自己的工程iii worker add name从解析器的数据结构可以清楚看到注册表支持的四种响应形态见 crates/iii-worker/src/cli/registry.rs 的WorkerInfoResponse枚举响应type制品形态关键字段binary按平台三元组分发的二进制包binaries每个目标平台一个urlsha256、configimageOCI 镜像image_urlengine内建引擎 worker无制品体仅元数据无HTTP 204 响应bundle单一tar.gz归档打包源码 清单archive_url、sha256其中bundle类型对应BundleWorkerResponse结构registry.rs是本文后半部分的核心。注册表 API 默认地址为https://api.workers.iii.dev可通过环境变量III_API_URL覆盖仅 debug/test 构建允许file://本地夹具生产构建强制 HTTPS见 registry.rs 与fetch_worker_info的实现。发布一个 worker发布 worker 会把它的二进制或 OCI 镜像上传到注册表登记其 Semver 版本并让该 worker 可以在任何 iii 项目中按名字安装。一次发布产生的注册表条目对用户侧而言完全透明——安装命令始终是iii worker add name与制品类型无关binary、OCI、bundle 三种形态安装体验一致。发布动作背后的客户端行为可以对照源码验证fetch_worker_info会向GET {API}/download/{name}?version{v}发起解析请求404 返回 Worker not found204 表示 engine worker 无制品体其余成功响应按type字段反序列化为上述四种形态之一registry.rs。注册表响应本身被限制在 1 MiB 以内MAX_REGISTRY_RESPONSE_BYTES防止不可信注册表在解析阶段分配无界内存registry.rs。说明0-20-0 版本文档对“规范发布命令、认证要求、注册表期望的元数据描述、仓库 URL、支持的平台等”仍标注为 TODO当前仓库中发布侧 CLI 尚未固化以上解析与下载侧行为均有源码可查。版本化你的 worker注册表中的 worker 遵循 SemverPatch 递增修 bugMinor 递增新增能力向后兼容Major 递增函数签名或触发器签名发生破坏性变更。对使用方而言版本通过后缀固定iii worker add my-worker1.2.0会锁定到指定版本而裸iii worker add my-worker默认取最新版。解析层对nameversion的拆分为第一个之前的为名字、之后的为版本串parse_worker_input见 registry.rs因此版本串本身可以再包含如scopeorg1.0。解析出的精确版本会被记录在项目的iii.lock中跨机器、跨平台重放安装时保持一致保证可复现构建。相关 CLI 细节iii worker update重新解析并回写锁、iii worker reinstall强制重下可参见 docs/0-20-0/using-iii/workers.mdx。为多平台构建二进制制品二进制 worker 可以在单个注册表条目内同时发布多个平台目标的制品macOS arm64/x64、Linux arm64/x64/armv7、Windows arm64/x64/x86。一个已发布版本即可覆盖所有受支持的宿主无需按平台分别发布。源码中的响应结构与测试夹具印证了这一点BinaryWorkerResponse.binaries是一个以 Rust 目标三元组为键、以{url, sha256}为值的映射registry.rs。测试deserialize_binary_worker_response中的真实示例同时携带了aarch64-apple-darwin与x86_64-unknown-linux-gnu两个平台的制品 URL 与 SHA-256registry.rs。解析图请求还可以显式携带target字段由注册表按目标平台解析出对应的二进制。说明0-20-0 文档对“跨平台构建流程、具体目标三元组清单、制品签名/校验和方式、上传位置”仍标注为 TODO以上为文档已声明平台范围与源码可验证的响应结构。更新或移除已发布的 worker文档规划的维护路径如下0-20-0 版本仍标注为 TODO属于待固化内容发布新版本Semver 递增后重新发布semver bump republish弃用deprecate如何标记某个 worker 已弃用撤回yank/retract已发布版本是否可撤回、如何撤回。从安装侧源码看同名的重复安装是安全的bundle 安装以~/.iii/workers-bundle/{name}/为全局缓存键重新iii worker add会通过“先改名搁置旧版本、再原子替换、失败回滚”的方式原地替换atomic_install见下文“原子安装”小节旧版本永远不会在替换失败时丢失。移除命令为iii worker remove -y name如需连下载的制品一并删除使用iii worker clear -y name。Bundle Workerstar.gz 归档分发Bundle 是继binary、image之后的第三种制品形态。注册表为它提供一个单一的tar.gz归档归档内是打包好的 worker 源码归档根目录放一个iii.worker.yaml清单。iii worker add name会下载归档、校验 SHA-256、把归档解压到~/.iii/workers-bundle/name/然后走与本地路径local-pathworker 完全相同的 libkrun 沙箱通道运行——区别仅在于 bundle 没有宿主机侧的源码 watcher。何时使用 bundle你发布的是预构建的 JavaScript 包esbuild、tsdown、bun build或打包好的 Python worker并且不想发布 Docker 镜像你希望制品以KB 而非 MB计量归档内只携带打包后的源码运行时随引擎白名单基础镜像一起提供docker.io/iiidev/node:latest或docker.io/iiidev/python:latest你希望安装体验与其他注册表 worker 完全一致——对用户来说就是iii worker add my-worker与 binary、OCI 无异。Registry 响应结构bundle 类型的注册表条目形如{ type: bundle, name: my-worker, version: 1.2.0, archive_url: https://cdn.workers.iii.dev/my-worker/1.2.0/bundle.tar.gz, sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 }引擎GETarchive_url把字节流送入 SHA-256 哈希器与sha256比对。任何不匹配都会中止安装并立即删除已下载的 blob绝不让一个校验失败的归档残留在磁盘上。源码实现download_archive见 crates/iii-worker/src/cli/bundle_download.rs还进一步收紧了这条链路的信任边界SSRF 防护下载前拒绝明文 HTTP、file:、ftp:以及指向非路由/链路本地/私网段的字面 IP如云厂商 IMDS169.254.169.254。重定向同样逐跳重新校验每个Location:头都会再过一遍 SSRF 守卫并限制最多5 跳防止公开 CDN URL 被重定向进内网或触发重定向炸弹本地开发逃生口localhost/127.0.0.1/::1仅在显式设置III_BUNDLE_DEV_LOOPBACK1时才放行且不作用于重定向每次安装都会打印黄色警告生产构建默认拒绝回环地址全局开关设置III_BUNDLE_WORKERS_DISABLED1可整体禁用 bundle worker 的安装与启动管线下载限额HTTP 客户端超时 120 秒响应流式写入磁盘并受 64 MiB 总量上限与application/内容类型前缀约束本地缓存已验证的 blob 会按 SHA-256 入缓存缓存命中后复制进 staging 再二次重算哈希堵住“查缓存→复制”窗口期的 TOCTOU 竞态校验失败的缓存条目会被驱逐并回退网络重下。归档布局归档根目录必须包含iii.worker.yaml。除此之外的任何内容都放在 bundle 视角下运行时可发现的路径上my-worker-1.2.0.tar.gz ├── iii.worker.yaml ├── bundle.js └── assets/ └── ...清单契约iii.worker.yamlBundle 清单是本地 worker 清单的一个严格子集有三个字段被显式拒绝scripts.setup会在安装期间执行发布者提供的 shell——这是供应链走私supply-chain smuggling向量scripts.install同理。依赖应当被打进 bundle而不是安装时现场拉取runtime.base_image允许 bundle 以任意 OCI 镜像作为 rootfs 是危险的。bundle 固定使用引擎白名单基础镜像。必填字段name必须等于安装目标即传给iii worker add的名字scripts.start非空 shell 字符串引擎在沙箱 VM 内对它执行exec。示例node bundle.js、python -m worker、bun run bundle.js。可选字段超出引擎上限时被钳制并产生W182 BundleResourceClamped警告resources.cpus默认2上限钳制为4resources.memory默认2048MiB上限钳制为4096MiB。完整示例name: my-worker version: 1.2.0 scripts: start: node bundle.js resources: cpus: 2 memory: 2048校验器实现validate_bundle_manifest见 bundle_download.rs逐条落实上述契约清单文件大小在读入前就被限制在64 KiBMAX_BUNDLE_MANIFEST_BYTES——这是对 YAML “billion-laughs” 别名校膨胀攻击的防御serde_yaml0.9.x 基于 libyaml不限制指数级别名展开64 KiB 上限保证最坏情况下内存膨胀也停留在数 MiB 量级name缺失或不等于安装目标 → 拒绝W180scripts.setup非空 → 拒绝W180runtime.base_image若出现必须是“合理的 OCI 引用”字母数字加._-/:如oven/bun:1否则在安装期直接失败W180而不是等到启动期静默回退默认镜像scripts.start缺失或为空 → 拒绝W180。资源解析parse_bundle_resourcesResourceCaps见 bundle_download.rs同样受 64 KiB 清单上限保护默认上限4CPU /4096MiB 与本地 worker 的PerImageCap语义对齐当请求超过上限时返回“钳制后数值 原始请求值”由调用方发出 WARN 事件遵循“零静默失败Prime Directive”原则。归档安全策略Bundle 归档使用比 OCI 层更紧的提取限制限制项值解压后总大小64 MiB单个文件最大32 MiB最大条目数1024最大目录深度16允许的 tar 条目类型Regular、Directory包含符号链接、硬链接、字符设备、FIFO或带..路径组件的归档一律以W181 BundleArchiveUnsafe拒绝。源码常量与提取器extract_bundle_safely_blocking见 bundle_download.rs逐项落实并多加了数道防线常量定义MAX_BUNDLE_TOTAL 64 MiB、MAX_BUNDLE_FILE 32 MiB、MAX_BUNDLE_ENTRIES 1024、MAX_BUNDLE_DEPTH 16bundle_download.rs。相比之下 OCI 提取器面向 10 GiB / 百万条目设计且不显式拒绝符号链接bundle 是发布时构建的单体制品任何合法内容都不该是符号链接因此采用更紧的专用提取器路径校验拒绝绝对路径、拒绝..组件、拒绝RootDir/Prefix组件并对“合成目标路径脱离目标根”做最终兜底检查防御 unicode 归一化等绕过条目类型白名单仅Regular与Directory其余类型Symlink/Link/Char/Block/Fifo/GNUSparse 等全部拒绝tar 库设置set_preserve_permissions(true)、set_unpack_xattrs(false)、set_overwrite(true)从根部拒绝解析内部符号链接特权位剥离文件解压后模式掩码为0o0777setuid/setgid/sticky 位全部丢弃——bundle 永远不会提权运行CPU 密集解压放后台线程解压与条目校验走tokio::task::spawn_blocking避免阻塞异步运行时。原子安装与进程崩溃安全安装不是简单地“解压到目标目录”而是一套完整的原子化替换协议atomic_install/StagingGuard见 bundle_download.rs 与 bundle_download.rs所有工作都在~/.iii/workers-bundle/.staging/rand/内进行StagingGuard持有该 worker 的独占文件锁fslock并拥有 staging 目录Drop时先删 staging 目录、后释放锁Rust 字段按声明顺序 drop杜绝并发安装看到半清理状态最终一步是同文件系统的原子rename跨文件系统时退化为“先复制到{name}.partial.*兄弟目录再原子改名”中途失败绝不让半成品出现在iii worker list里替换旧版本采用“改名搁置rename-aside”旧目录先被改名为{name}.old.unique新树安装成功后才清理它新安装失败则把旧目录改回原位旧版本永远不丢进程被杀导致的残留 staging 目录由启动期的sweep_orphans()清扫{name}.old.*残留则在下一次成功安装同一 worker 时清扫sweep_stale_old_siblings——因为搁置的兄弟目录可能是该 worker 的唯一剩余副本绝不能提前删。错误码代码失败场景W142归档下载失败HTTP 错误、意外的 Content-Type、超过大小上限、SHA-256 不匹配。W180清单被拒绝出现scripts.setup、runtime.base_image等禁用字段或name/scripts.start不符合契约。W181归档含不安全条目符号链接、硬链接、路径穿越、超大文件、条目过多。W182资源请求超出引擎上限安装以钳制后的值继续警告而非失败。W183依赖图过宽或过深。这些错误码在 crates/iii-worker/src/core/error.rs 中一一对应Download (W142)、BundleManifestRejected (W180)、BundleArchiveUnsafe (W181)、BundleResourceClamped (W182)、BundleDepGraphExceeded (W183)并统一映射为W前缀的警告/错误事件。源码侧说明当前 crates/iii-worker/src/cli/registry.rs 的依赖图校验已从“深度 5 / 节点 32 的硬性拒绝”演进为“结构校验名字唯一、边指向已声明节点、可达性、无环 节点数超过 32 时要求显式确认LARGE_DEPENDENCY_GRAPH_THRESHOLD”因此W183所对应的“过宽/过深”判定在最新代码中表现为确认门槛而非硬失败文档表列出的仍是 0-20-0 版本契约的描述。安装位置与解析优先级Bundle worker 是按名字共享的机器级缓存不属于某个具体项目安装在~/.iii/workers-bundle/{name}/bundle_worker_path见 crates/iii-worker/src/cli/config_file.rs与二进制 worker 的~/.iii/workers/分离使解析器可以不读内容直接按目录判别安装类型。bundle_workers_dir()→~/.iii/workers-bundle/内部保留.locks/与.staging/作为控制目录bundle_is_installed(name)要求目录存在且含合法iii.worker.yaml才视为已安装——一个空目录或逃逸的 staging 目录不会造成误判worker 名校验validate_worker_name只允许字母数字、-、_、.禁止空名与..并禁止以.开头——否则iii worker remove .locks会通过remove_dir_all把全系统的 per-worker 文件锁目录一并清掉registry.rs解析优先级为本地路径 worker OCI 镜像 bundleresolve_worker_typeconfig_file.rs。已有二进制的同名 worker 在 bundle 根目录加入后仍解析为 Binary——空 bundle 目录不会遮蔽二进制安装集成测试将其列为回归关键项见 crates/iii-worker/tests/bundle_worker_integration.rs 的覆盖清单。安装后的日常管理走标准iii worker命令iii worker list查看状态、iii worker start/stop/restart控制启停、iii worker status/logs/exec检查状态与日志、iii worker update重新解析锁定的版本、iii worker remove -y name移除iii worker clear -y name连同制品一并删除。bundle 与本地 worker 共用 libkrun 微虚拟机沙箱通道但没有宿主机侧的源码 watcher——bundle 是发布时定型的制品不做热重载。进一步阅读本地 worker 清单完整字段参考docs/0-20-0/creating-workers/worker-manifest.mdxbundle 清单是其严格子集iii worker全生命周期命令与版本固定/锁文件docs/0-20-0/using-iii/workers.mdx从零创建 workeriii worker init脚手架docs/0-20-0/creating-workers/workers.mdx安装管线核心实现crates/iii-worker/src/cli/bundle_download.rs注册表解析与依赖图校验crates/iii-worker/src/cli/registry.rs错误码定义crates/iii-worker/src/core/error.rs提取安全、清单契约、资源钳制与原子安装的集成测试覆盖crates/iii-worker/tests/bundle_worker_integration.rs【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考