iii 安装指南：使用官方 curl 安装器安装 iii 引擎并验证环境

iii 安装指南：使用官方 curl 安装器安装 iii 引擎并验证环境

【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii

本篇技术指南以 iii 0.18.0 版官方文档《Install》为骨架，完整讲解如何通过一行curl | sh命令安装 iii 引擎、如何用iii --version验证安装结果，并结合当前开源仓库中的 engine/install.sh 安装脚本源码，逐层拆解安装器背后的平台探测、版本解析、伴生组件（iii-init / iii-worker）安装与 PATH 配置等实现细节，帮助你不仅会装，还知道装了什么、装到了哪里、以及如何针对不同平台和版本精确控制安装过程。

1. 安装 iii 引擎

iii 的官方推荐安装方式是通过官网安装脚本完成，命令如下：

curl -fsSL https://install.iii.dev/iii/main/install.sh | sh

这条命令的语义拆解如下：

• -f（fail）：HTTP 请求失败（如 4xx/5xx）时立即报错退出，不静默输出错误页面；
• -s（silent）：关闭 curl 的进度条输出，保证管道到sh的只有脚本内容；
• -S（show error）：与-s配合使用，出错时仍然显示错误信息；
• -L（location）：跟随 HTTP 重定向，兼容下载地址的跳转；
• 脚本内容通过管道交给sh执行，脚本默认安装「最新稳定版」的 iii 引擎二进制。

仓库中实际承载这一逻辑的是 engine/install.sh，它以set -eu开头（任何命令失败立即退出、未定义变量立即报错），保证整个安装过程失败即中断，不会留下半成品状态。脚本顶部的注释说明了它的健壮性设计：curl_retry包装函数（engine/install.sh）只使用 curl 7.12.3（2005 年）以来就有的参数，对 504/502/503 及超时这类瞬时网络错误自动重试 5 次（--retry 5 --retry-delay 2 --retry-max-time 120 --connect-timeout 10），从而在弱网环境下依然能可靠完成下载。

1.1 安装前的前置依赖

脚本在执行任何下载动作之前，会先做依赖检查（engine/install.sh）：

• curl：下载必需；
• jq：解析 GitHub Releases API 返回的 JSON，用于选择版本与匹配目标平台的资产；
• tar：解压.tar.gz资产（Windows 场景下如遇.zip资产则还需要unzip）。

若缺少依赖，脚本会依据当前系统给出安装提示（pkg_manager_hint会针对 brew / apt-get / dnf / yum / apk / pacman 分别输出对应命令，见 engine/install.sh）。

1.2 安装脚本支持的参数与环境变量

与文档中给出的单行命令不同，仓库内的安装脚本实际是一个参数完备的 CLI（完整用法见 engine/install.sh）。下表整理自脚本源码，方便需要精确控制安装过程的用户：

对应的典型用法示例（同样摘自脚本自身 usage 输出）：

# 安装最新稳定版（等价于文档中的标准命令） curl -fsSL https://iii.dev/install.sh | sh # 安装最新的 next 预发布版 curl -fsSL https://iii.dev/install.sh | sh -s -- --next # 安装最新的 RC 候选版 curl -fsSL https://iii.dev/install.sh | sh -s -- --rc # 固定安装某个具体版本 curl -fsSL https://iii.dev/install.sh | VERSION=0.18.0 sh # 安装到自定义目录 curl -fsSL https://iii.dev/install.sh | BIN_DIR=/usr/local/bin sh

注意：--next与--rc不能同时使用，脚本会直接报错退出（engine/install.sh）。此外脚本保留了--no-cli、--cli-version、--cli-dir三个已废弃的 no-op 参数（仅打印废弃警告），为的是让旧文档中的命令在过渡期内不至于直接失效。

1.3 安装器实际做了什么：平台探测与版本选择

从源码结构看，安装器的主流程分为四个阶段：

1. 平台探测（engine/install.sh）：根据uname -s与uname -m判断 OS 与架构。支持的目标包括 Linux / macOS 下的 x86_64、aarch64、armv7。Linux x86_64 默认使用 musl 静态构建；只有显式设置III_USE_GLIBC且系统 glibc ≥ 2.35 时才切换到 glibc 构建。无法识别的平台会给出明确的错误提示，并支持通过TARGET=<triple>手动覆盖。
2. 版本解析（engine/install.sh）：默认请求https://api.github.com/repos/iii-hq/iii/releases/latest获取最新稳定版；指定VERSION时先尝试iii/v<版本>标签，再回退尝试v<版本>；--next/--rc则遍历最近 20 个 release 匹配-next.或-rc.标签。指定版本若为预发布版且未显式传入--next/--rc，会被拒绝安装。
3. 资产匹配与下载：从 release JSON 中挑选形如iii-<target>.tar.gz的主二进制资产，并通过一次并行的 curl 调用下载主二进制与伴生组件。
4. 安装与 PATH 引导：将二进制以 755 权限安装到目标目录，随后检测当前 shell（bash / zsh / fish 等）并输出对应的 PATH 配置命令。

值得关注的是「幂等性」设计：安装前脚本会调用iii_detect_from_version（engine/install.sh）执行iii --version检测已安装版本，若已是最新目标版本，则直接提示iii is already at vX.Y.Z — nothing to do并退出，不会重复下载（engine/install.sh）。

1.4 伴生组件：iii-init 与 iii-worker

与文档中「安装 iii 引擎」一句话不同，安装器实际上还会顺带安装两个支撑「沙箱 Worker（VM 隔离）」能力的伴生二进制（engine/install.sh）：

• iii-init：Linux ELF，运行在虚拟机内部，负责沙箱 Worker 的初始化；macOS 主机上为 libkrun 客户机也需要它；
• iii-worker：需要 glibc（KVM/libkrun 场景），Linux 与 macOS aarch64 平台提供。

这两个组件属于「尽力而为」安装：下载或解压失败只打印 warning，不影响主引擎安装成功，但会明确提示「VM-based sandbox workers 将不可用，直到重新运行 install.sh 或手动从 releases 安装」。macOS Intel（x86_64）目前没有 iii-worker 资产，脚本会打印提示说明该机型上 VM 隔离类功能暂不可用。

2. 验证安装结果

安装完成后，运行：

iii --version

该命令应输出一个版本号。从源码看，这一输出直接来自编译期常量CARGO_PKG_VERSION（engine/src/main.rs），即当前引擎二进制编译时对应的 crate 版本，格式为语义化版本号（如0.18.0）。

值得说明的是，iii --version不仅是给用户看的验证手段，它同时被仓库多处内部逻辑复用：

• 安装脚本通过它检测已安装版本（iii_detect_from_version提取输出中的最后一个字段，见 engine/install.sh），实现升级路径判断与幂等跳过；
• CLI 的更新检测逻辑同样会执行binary --version（带 5 秒超时）来探测实际安装版本（engine/src/cli/update.rs）；
• 对应的单元测试 engine/tests/install_sh_unit.bats 用一个输出iii 0.11.0的假二进制验证了「取最后一个字段」的解析逻辑。

2.1 验证失败时的排查线索

安装脚本在安装完成后还会做一次主动校验（engine/install.sh）：如果iii --version没有任何输出，会打印 warning，并提示可能的原因——macOS Gatekeeper 拦截、libc 不匹配（glibc/musl 选错）等，同时建议直接执行完整路径$HOME/.local/bin/iii --version复测。

3. 版本兼容性注意事项

官方文档在验证步骤后特别强调了一条版本纪律：

Engine 与各 SDK 包在同一 minor 版本线内可以有不同的 patch 版本。除非发布说明另有说明，请让 engine 与 SDK 保持在同一 minor 版本（例如0.18.x）。

这意味着安装 engine0.18.2时搭配 SDK0.18.1通常没有问题，但不要混用0.17.x的 SDK 与0.18.x的 engine。从仓库的目录结构看，这一点也体现在文档版本的划分上：docs 下同时维护了0-18-0、0-19-0、0-20-0、0-21-0及next等多套版本化文档目录，每套目录都对应独立的安装、快速上手与 API 参考，版本线之间的差异会被单独记录在 docs/upgrading 目录中。

如果确实需要跨版本或预发布版本，请使用安装脚本的VERSION、--next、--rc参数（见 1.2 节表格），它们是官方脚本对版本控制的正式入口。

4. 安装后第一步：从 Quickstart 开始

安装并验证成功后，官方文档建议的下一步是 Quickstart：创建一个双语言示例项目，在数分钟内跑通「Python Worker 与 TypeScript Worker 通过引擎跨语言互调」的完整链路：

iii project init quickstart --template quickstart cd quickstart iii --config config.yaml # 启动引擎，监听 ws://localhost:49134 iii worker add ./workers/math-worker iii worker add ./workers/caller-worker iii trigger math::add_two_numbers a=10 b=20 # → { "c": 30 }

生产环境使用相关的配置、部署与运维知识，可继续阅读 using-iii 下的各篇指南。

5. 补充：如何安装 iii Console（可选）

iii 引擎之外，仓库还提供独立的iii-console（交互式可视化控制台）组件，其安装器为 console/install.sh。它的设计思路与引擎安装脚本一致，但能力更聚焦：

• 支持-v/--version <version>指定版本、-b/--binary <path>从本地二进制安装、--no-modify-path跳过 PATH 修改；
• 默认安装到$HOME/.local/bin；
• 下载后若存在.sha256校验文件会自动做 SHA-256 校验（console/install.sh）；
• 解压前会检查 tar 包是否存在路径穿越条目（../），并对安装目标做符号链接拒绝，防范供应链类攻击（console/install.sh）；
• 在 GitHub Actions 环境中会自动把安装目录追加到$GITHUB_PATH（console/install.sh）。

Console 的用途（查看 Workers、Functions、Triggers、日志、追踪与状态的可视化界面）在 Quickstart 文档中有对应描述，详见 console 文档（若存在）。

6. 总结

围绕「安装 iii 引擎并验证」，本文完整继承了官方文档的两步流程——curl -fsSL https://install.iii.dev/iii/main/install.sh | sh与iii --version，并结合仓库源码进一步明确了：安装脚本的实际能力边界（版本固定、预发布通道、目标平台覆盖、依赖检查、幂等跳过、伴生组件安装与 PATH 引导）、iii --version的底层实现（编译期版本常量及其在升级检测中的复用），以及 engine 与 SDK 同 minor 版本线兼容这一版本纪律。掌握了这些，你既可以按官方标准路径一键安装，也能在需要精确控制时熟练使用VERSION、BIN_DIR、--next、--rc等参数完成定制化部署。

相关文档与源码索引：

• 安装文档（0.18.0 版）
• 安装脚本（引擎）
• 安装脚本（Console）
• 安装脚本单元测试
• CLI 版本输出实现
• 更新检测中的版本探测
• Quickstart（安装后的下一步）

【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii