iii Registry 实战指南发布 Worker、多平台二进制与 Bundletar.gz工件的安全安装机制【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本篇基于 iii 仓库官方文档 workers-registry 展开讲清 iii 注册表registry的三种工件形态binary、image、bundle如何发布 Worker、按 semver 管理版本、在单条注册表记录中覆盖多平台二进制目标以及 Bundle Worker 从下载到落盘的完整安全校验链路。读完本文你可以直接照着 manifest 契约与安全策略表打包发布一个 Bundle Worker并能从源码层面理解W142、W180W183各错误码背后的实现。一、iii 注册表是什么iii 的注册表部署在workers.iii.dev是所有已发布 Worker 的存放地。对于使用者而言注册表的意义只有一个让任意 iii 项目都能通过一条命令按名称安装 Workeriii worker add name从源码看安装与启动管线位于 crates/iii-worker/src/cli/bundle_download.rs 的模块注释中被明确描述为引擎经由注册表解析 Worker、通过 HTTPS 下载归档、校验 SHA-256、原子性地解包到~/.iii/workers-bundle/{name}/然后走本地路径 Worker 已有的 libkrun 沙箱轨道本地路径 Worker 那条沙箱路径只是少了宿主侧的源码 watcher。二、发布一个 Worker发布动作包含三件事上传 Worker 的二进制或 OCI 镜像到注册表记录其 semver 版本号使该 Worker 可在任意 iii 项目中按名称安装。原文档在该章节留有 TODO 标记说明规范的 publish 命令如iii worker publish、认证要求以及注册表期望的元数据描述、仓库地址、支持平台等尚在补全中——阅读时请以仓库最新版本为准不要在未确认命令形态前在生产流水线中猜测。三、Worker 的版本管理注册表中的 Worker 遵循 semver 约定patch 位递增缺陷修复minor 位递增新增能力major 位递增函数function或触发器trigger签名等破坏性变更。这意味着破坏性变更不能悄悄混进 patch 版本下游iii worker add的用户在升级时应当能根据版本号判断是否需要适配。四、一条注册表记录覆盖多平台二进制工件二进制 Worker 可以在同一条注册表记录中发布多个平台目标操作系统目标架构macOSarm64 / x64Linuxarm64 / x64 / armv7Windowsarm64 / x64 / x86一次发布即可覆盖所有受支持的主机架构无需为每个平台单独发布。原文档同样以 TODO 形式标注了交叉编译流程、具体 target triple、产物签名/校验方式等待补全细节属于方向已定、细节待落地的状态。五、更新或下架已发布的 Worker原文档该章节目前仅有 TODO 占位如何发布新版本semver 递增 重新发布、如何标记 Worker 弃用deprecate、以及已发布版本是否可以撤回yank均未定稿。可确定的事实是更新即semver 递增 重新发布且由于安装按名称解析iii worker add name版本治理是注册表侧必须提供的能力。六、Bundle Worker第三种工件形态tar.gz 归档在binary与image之外Bundle Worker 是第三种工件形态。注册表返回一个tar.gz归档其中包含打包好的 Worker 源码以及位于归档根部的iii.worker.yamlmanifest。iii worker add name会下载归档、校验 SHA-256 校验和、将其解包到~/.iii/workers-bundle/name/然后交由既有的 libkrun 轨道执行。6.1 什么时候用 Bundle你交付的是预构建产物esbuild、tsdown、bun build生成的 JS bundle或打包好的 Python Worker不想为此发布一个 Docker 镜像你希望产物以KB 而非 MB计。归档中只传输 bundle 后的源码运行时由引擎白名单基础镜像docker.io/iiidev/node:latest或docker.io/iiidev/python:latest提供你希望安装体验与其他注册表 Worker 完全一致iii worker add my-worker与 binary、OCI 无差别。6.2 注册表响应格式{ 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 }引擎对archive_url发起 GET 请求将字节流经 SHA-256 hasher 流式计算再与响应中的sha256比对不一致即中止安装并立即删除已下载的 blob。源码侧对应 crates/iii-worker/src/cli/bundle_download.rs 中的共享 HTTP 客户端它与注册表客户端默认最多 10 跳重定向不同会对每一跳Location:重定向重新执行 SSRF 校验防止公开 CDN 地址重定向到不可路由目标loopback、RFC-1918、IMDS 等。6.3 归档结构归档根部必须包含iii.worker.yaml其余文件相对 bundle 视角放在运行时可发现的路径上my-worker-1.2.0.tar.gz ├── iii.worker.yaml ├── bundle.js └── assets/ └── ...6.4 Manifest 契约iii.worker.yamlBundle manifest 使用本地 Worker manifest 的严格子集。按 0-13-0 文档的约定以下字段被显式拒绝scripts.setup会在安装期间执行发布者提供的 shell供应链投毒向量scripts.install同理应将依赖直接 vendor 进 bundleruntime.base_image会允许 bundle 拉取任意 OCI 镜像作为 rootfsbundle 改用引擎白名单基础镜像。必需字段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。示例 manifestname: my-worker version: 1.2.0 scripts: start: node bundle.js resources: cpus: 2 memory: 2048实现细节与文档差异以当前源码为准crates/iii-worker/src/cli/bundle_download.rs 的validate_bundle_manifest给出了当前代码的真实校验顺序先读 metadata 卡 manifest 大小iii.worker.yaml上限64 KiBMAX_BUNDLE_MANIFEST_BYTES理由是serde_yaml0.9.xlibyaml 系不限制指数级 anchor/alias 展开十亿笑声攻击64 KiB 封顶后最坏展开也仅数 MiB校验name非空且与安装目标严格相等校验scripts.start为非空字符串scripts.setup存在且非空即被拒绝——OS 层配置应放进预置镜像bundle 应当发布即开箱可运行。值得注意源码注释显示scripts.install在当前实现中是允许的它与scripts.start同属发布者 shell 信任上下文在沙箱 VM 内执行且启动脚本通过/var/.iii-prepared守卫保证只运行一次供 Python bundle 做 pip/浏览器引导runtime.base_image也并非一律拒绝而是先做 OCI 引用字符集校验is_plausible_image_ref见 project 模块不合理的引用在安装期即以W180失败。这与 0-13-0 文档三个字段一律拒绝的表述存在差异属于文档落后于代码演进的情况——如果你按当前仓库实现打包发布请以 bundle_download.rs 校验逻辑 为事实依据。6.5 归档安全策略Bundle 归档使用比 OCI 层更严格的解压限制实现见 extract_bundle_safely_blocking 与模块顶部常量限制项取值源码常量解压后总大小64 MiBMAX_BUNDLE_TOTAL单个文件最大32 MiBMAX_BUNDLE_FILE最大条目数1024MAX_BUNDLE_ENTRIES最大目录深度16MAX_BUNDLE_DEPTH允许的 tar 条目类型仅 Regular、Directory见源码注释包含符号链接、硬链接、字符设备、FIFO或路径中含..组件的归档会以W181 BundleArchiveUnsafe被拒绝。源码模块注释解释了收紧的理由OCI 层的extract_layer_with_limits面向 10 GiB / 100 万条目且不显式拒绝符号链接/硬链接而 Bundle 是发布期构建的自包含产物合法内容中不存在符号链接因此采用专用收紧解压器避免恶意或有缺陷的发布在验证运行前耗尽宿主磁盘。原子性与崩溃安全源码模型所有安装工作在~/.iii/workers-bundle/.staging/rand/中完成StagingGuard持有针对name的 fslock最终通过原子rename提交到~/.iii/workers-bundle/{name}/跨文件系统时退化为复制删除旧版本先被挪到{name}.old.unique旁挂安装失败则恢复。进程被杀导致的残留由启动期的sweep_orphans()清理。七、错误码速查错误码失败场景W142归档下载失败HTTP 错误、意外 content-type、超出大小上限、sha256 不匹配W180Manifest 被拒绝出现scripts.setup等禁止字段W181归档含不安全条目符号链接、硬链接、路径穿越、超大、条目过多W182资源请求超出引擎上限安装以钳制值继续警告而非失败W183依赖图过宽或过深最大深度 5最大传递依赖数 32这些错误码在 crates/iii-worker/src/core/error.rs 中定义BundleManifestRejectedW180携带field与reason、BundleArchiveUnsafeW181、BundleResourceClampedW182随 warn 事件携带而非作为Err返回、BundleDepGraphExceededW183。集成测试位于 crates/iii-worker/tests/bundle_worker_integration.rs可用于回归验证整条安装链路。八、运维开关源码中还暴露了两个与 Bundle 安装相关的环境变量适合在不受信 CDN 的环境中使用III_BUNDLE_WORKERS_DISABLED1完全禁用 Bundle Worker 的安装/启动管线CLI 安装handle_bundle_add与引擎启动start_bundle_worker在触及网络或文件系统前都会检查该开关III_BUNDLE_DEV_LOOPBACK1显式开启 loopback SSRF 旁路仅用于本地开发例如用 Pythonhttp.server替代注册表 CDN生产构建默认拒绝http://localhost/...、127.0.0.1这类归档地址。九、小结iii 注册表将 Worker 分发收敛为一句话安装iii worker add name其下支撑三种工件形态其中 Bundle Worker 以 KB 级 tar.gz 归档 白名单运行时镜像的组合把发布打包产物的成本压到最低。围绕这条链路仓库给出了明确的工程护栏manifest 64 KiB 防 YAML 膨胀、归档 64 MiB / 1024 条目 / 16 层深度硬上限、逐跳重定向 SSRF 校验、staging 原子 rename 的崩溃安全安装模型以及W180W183这套可直接用于排障的错误码。发布前对照 docs/0-13-0/creating-workers/workers-registry.mdx 检查 manifest 字段是否落在允许子集内再参考 crates/iii-worker/src/cli/bundle_download.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），仅供参考
iii Registry 实战指南：发布 Worker、多平台二进制与 Bundle（tar.gz）工件的安全安装机制
iii Registry 实战指南发布 Worker、多平台二进制与 Bundletar.gz工件的安全安装机制【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本篇基于 iii 仓库官方文档 workers-registry 展开讲清 iii 注册表registry的三种工件形态binary、image、bundle如何发布 Worker、按 semver 管理版本、在单条注册表记录中覆盖多平台二进制目标以及 Bundle Worker 从下载到落盘的完整安全校验链路。读完本文你可以直接照着 manifest 契约与安全策略表打包发布一个 Bundle Worker并能从源码层面理解W142、W180W183各错误码背后的实现。一、iii 注册表是什么iii 的注册表部署在workers.iii.dev是所有已发布 Worker 的存放地。对于使用者而言注册表的意义只有一个让任意 iii 项目都能通过一条命令按名称安装 Workeriii worker add name从源码看安装与启动管线位于 crates/iii-worker/src/cli/bundle_download.rs 的模块注释中被明确描述为引擎经由注册表解析 Worker、通过 HTTPS 下载归档、校验 SHA-256、原子性地解包到~/.iii/workers-bundle/{name}/然后走本地路径 Worker 已有的 libkrun 沙箱轨道本地路径 Worker 那条沙箱路径只是少了宿主侧的源码 watcher。二、发布一个 Worker发布动作包含三件事上传 Worker 的二进制或 OCI 镜像到注册表记录其 semver 版本号使该 Worker 可在任意 iii 项目中按名称安装。原文档在该章节留有 TODO 标记说明规范的 publish 命令如iii worker publish、认证要求以及注册表期望的元数据描述、仓库地址、支持平台等尚在补全中——阅读时请以仓库最新版本为准不要在未确认命令形态前在生产流水线中猜测。三、Worker 的版本管理注册表中的 Worker 遵循 semver 约定patch 位递增缺陷修复minor 位递增新增能力major 位递增函数function或触发器trigger签名等破坏性变更。这意味着破坏性变更不能悄悄混进 patch 版本下游iii worker add的用户在升级时应当能根据版本号判断是否需要适配。四、一条注册表记录覆盖多平台二进制工件二进制 Worker 可以在同一条注册表记录中发布多个平台目标操作系统目标架构macOSarm64 / x64Linuxarm64 / x64 / armv7Windowsarm64 / x64 / x86一次发布即可覆盖所有受支持的主机架构无需为每个平台单独发布。原文档同样以 TODO 形式标注了交叉编译流程、具体 target triple、产物签名/校验方式等待补全细节属于方向已定、细节待落地的状态。五、更新或下架已发布的 Worker原文档该章节目前仅有 TODO 占位如何发布新版本semver 递增 重新发布、如何标记 Worker 弃用deprecate、以及已发布版本是否可以撤回yank均未定稿。可确定的事实是更新即semver 递增 重新发布且由于安装按名称解析iii worker add name版本治理是注册表侧必须提供的能力。六、Bundle Worker第三种工件形态tar.gz 归档在binary与image之外Bundle Worker 是第三种工件形态。注册表返回一个tar.gz归档其中包含打包好的 Worker 源码以及位于归档根部的iii.worker.yamlmanifest。iii worker add name会下载归档、校验 SHA-256 校验和、将其解包到~/.iii/workers-bundle/name/然后交由既有的 libkrun 轨道执行。6.1 什么时候用 Bundle你交付的是预构建产物esbuild、tsdown、bun build生成的 JS bundle或打包好的 Python Worker不想为此发布一个 Docker 镜像你希望产物以KB 而非 MB计。归档中只传输 bundle 后的源码运行时由引擎白名单基础镜像docker.io/iiidev/node:latest或docker.io/iiidev/python:latest提供你希望安装体验与其他注册表 Worker 完全一致iii worker add my-worker与 binary、OCI 无差别。6.2 注册表响应格式{ 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 }引擎对archive_url发起 GET 请求将字节流经 SHA-256 hasher 流式计算再与响应中的sha256比对不一致即中止安装并立即删除已下载的 blob。源码侧对应 crates/iii-worker/src/cli/bundle_download.rs 中的共享 HTTP 客户端它与注册表客户端默认最多 10 跳重定向不同会对每一跳Location:重定向重新执行 SSRF 校验防止公开 CDN 地址重定向到不可路由目标loopback、RFC-1918、IMDS 等。6.3 归档结构归档根部必须包含iii.worker.yaml其余文件相对 bundle 视角放在运行时可发现的路径上my-worker-1.2.0.tar.gz ├── iii.worker.yaml ├── bundle.js └── assets/ └── ...6.4 Manifest 契约iii.worker.yamlBundle manifest 使用本地 Worker manifest 的严格子集。按 0-13-0 文档的约定以下字段被显式拒绝scripts.setup会在安装期间执行发布者提供的 shell供应链投毒向量scripts.install同理应将依赖直接 vendor 进 bundleruntime.base_image会允许 bundle 拉取任意 OCI 镜像作为 rootfsbundle 改用引擎白名单基础镜像。必需字段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。示例 manifestname: my-worker version: 1.2.0 scripts: start: node bundle.js resources: cpus: 2 memory: 2048实现细节与文档差异以当前源码为准crates/iii-worker/src/cli/bundle_download.rs 的validate_bundle_manifest给出了当前代码的真实校验顺序先读 metadata 卡 manifest 大小iii.worker.yaml上限64 KiBMAX_BUNDLE_MANIFEST_BYTES理由是serde_yaml0.9.xlibyaml 系不限制指数级 anchor/alias 展开十亿笑声攻击64 KiB 封顶后最坏展开也仅数 MiB校验name非空且与安装目标严格相等校验scripts.start为非空字符串scripts.setup存在且非空即被拒绝——OS 层配置应放进预置镜像bundle 应当发布即开箱可运行。值得注意源码注释显示scripts.install在当前实现中是允许的它与scripts.start同属发布者 shell 信任上下文在沙箱 VM 内执行且启动脚本通过/var/.iii-prepared守卫保证只运行一次供 Python bundle 做 pip/浏览器引导runtime.base_image也并非一律拒绝而是先做 OCI 引用字符集校验is_plausible_image_ref见 project 模块不合理的引用在安装期即以W180失败。这与 0-13-0 文档三个字段一律拒绝的表述存在差异属于文档落后于代码演进的情况——如果你按当前仓库实现打包发布请以 bundle_download.rs 校验逻辑 为事实依据。6.5 归档安全策略Bundle 归档使用比 OCI 层更严格的解压限制实现见 extract_bundle_safely_blocking 与模块顶部常量限制项取值源码常量解压后总大小64 MiBMAX_BUNDLE_TOTAL单个文件最大32 MiBMAX_BUNDLE_FILE最大条目数1024MAX_BUNDLE_ENTRIES最大目录深度16MAX_BUNDLE_DEPTH允许的 tar 条目类型仅 Regular、Directory见源码注释包含符号链接、硬链接、字符设备、FIFO或路径中含..组件的归档会以W181 BundleArchiveUnsafe被拒绝。源码模块注释解释了收紧的理由OCI 层的extract_layer_with_limits面向 10 GiB / 100 万条目且不显式拒绝符号链接/硬链接而 Bundle 是发布期构建的自包含产物合法内容中不存在符号链接因此采用专用收紧解压器避免恶意或有缺陷的发布在验证运行前耗尽宿主磁盘。原子性与崩溃安全源码模型所有安装工作在~/.iii/workers-bundle/.staging/rand/中完成StagingGuard持有针对name的 fslock最终通过原子rename提交到~/.iii/workers-bundle/{name}/跨文件系统时退化为复制删除旧版本先被挪到{name}.old.unique旁挂安装失败则恢复。进程被杀导致的残留由启动期的sweep_orphans()清理。七、错误码速查错误码失败场景W142归档下载失败HTTP 错误、意外 content-type、超出大小上限、sha256 不匹配W180Manifest 被拒绝出现scripts.setup等禁止字段W181归档含不安全条目符号链接、硬链接、路径穿越、超大、条目过多W182资源请求超出引擎上限安装以钳制值继续警告而非失败W183依赖图过宽或过深最大深度 5最大传递依赖数 32这些错误码在 crates/iii-worker/src/core/error.rs 中定义BundleManifestRejectedW180携带field与reason、BundleArchiveUnsafeW181、BundleResourceClampedW182随 warn 事件携带而非作为Err返回、BundleDepGraphExceededW183。集成测试位于 crates/iii-worker/tests/bundle_worker_integration.rs可用于回归验证整条安装链路。八、运维开关源码中还暴露了两个与 Bundle 安装相关的环境变量适合在不受信 CDN 的环境中使用III_BUNDLE_WORKERS_DISABLED1完全禁用 Bundle Worker 的安装/启动管线CLI 安装handle_bundle_add与引擎启动start_bundle_worker在触及网络或文件系统前都会检查该开关III_BUNDLE_DEV_LOOPBACK1显式开启 loopback SSRF 旁路仅用于本地开发例如用 Pythonhttp.server替代注册表 CDN生产构建默认拒绝http://localhost/...、127.0.0.1这类归档地址。九、小结iii 注册表将 Worker 分发收敛为一句话安装iii worker add name其下支撑三种工件形态其中 Bundle Worker 以 KB 级 tar.gz 归档 白名单运行时镜像的组合把发布打包产物的成本压到最低。围绕这条链路仓库给出了明确的工程护栏manifest 64 KiB 防 YAML 膨胀、归档 64 MiB / 1024 条目 / 16 层深度硬上限、逐跳重定向 SSRF 校验、staging 原子 rename 的崩溃安全安装模型以及W180W183这套可直接用于排障的错误码。发布前对照 docs/0-13-0/creating-workers/workers-registry.mdx 检查 manifest 字段是否落在允许子集内再参考 crates/iii-worker/src/cli/bundle_download.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），仅供参考
