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这条命令的语义拆解如下-ffailHTTP 请求失败如 4xx/5xx时立即报错退出不静默输出错误页面-ssilent关闭 curl 的进度条输出保证管道到sh的只有脚本内容-Sshow error与-s配合使用出错时仍然显示错误信息-Llocation跟随 HTTP 重定向兼容下载地址的跳转脚本内容通过管道交给sh执行脚本默认安装「最新稳定版」的 iii 引擎二进制。仓库中实际承载这一逻辑的是 engine/install.sh它以set -eu开头任何命令失败立即退出、未定义变量立即报错保证整个安装过程失败即中断不会留下半成品状态。脚本顶部的注释说明了它的健壮性设计curl_retry包装函数engine/install.sh只使用 curl 7.12.32005 年以来就有的参数对 504/502/503 及超时这类瞬时网络错误自动重试 5 次--retry 5 --retry-delay 2 --retry-max-time 120 --connect-timeout 10从而在弱网环境下依然能可靠完成下载。1.1 安装前的前置依赖脚本在执行任何下载动作之前会先做依赖检查engine/install.shcurl下载必需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。下表整理自脚本源码方便需要精确控制安装过程的用户参数 / 环境变量说明默认值-h/--help打印完整用法说明—--next安装最新的 next 预发布版本关闭--rc安装最新的 release candidateRC 候选版关闭VERSION指定要安装的引擎版本如0.18.0最新稳定版BIN_DIR二进制安装目录$PREFIX/bin若设置了PREFIX否则$HOME/.local/binPREFIX安装前缀$HOME/.localTARGET覆盖目标三元组如x86_64-apple-darwin、aarch64-unknown-linux-gnu自动探测III_USE_GLIBCLinux x86_64 下强制使用 glibc 构建任意非空值启用默认 muslGITHUB_TOKEN为 GitHub API 调用鉴权将速率限制从 60 次/小时提升到 5000 次/小时未设置对应的典型用法示例同样摘自脚本自身 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 | VERSION0.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 安装器实际做了什么平台探测与版本选择从源码结构看安装器的主流程分为四个阶段平台探测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 构建。无法识别的平台会给出明确的错误提示并支持通过TARGETtriple手动覆盖。版本解析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会被拒绝安装。资产匹配与下载从 release JSON 中挑选形如iii-target.tar.gz的主二进制资产并通过一次并行的 curl 调用下载主二进制与伴生组件。安装与 PATH 引导将二进制以 755 权限安装到目标目录随后检测当前 shellbash / zsh / fish 等并输出对应的 PATH 配置命令。值得关注的是「幂等性」设计安装前脚本会调用iii_detect_from_versionengine/install.sh执行iii --version检测已安装版本若已是最新目标版本则直接提示iii is already at vX.Y.Z — nothing to do并退出不会重复下载engine/install.sh。1.4 伴生组件iii-init 与 iii-worker与文档中「安装 iii 引擎」一句话不同安装器实际上还会顺带安装两个支撑「沙箱 WorkerVM 隔离」能力的伴生二进制engine/install.shiii-initLinux ELF运行在虚拟机内部负责沙箱 Worker 的初始化macOS 主机上为 libkrun 客户机也需要它iii-worker需要 glibcKVM/libkrun 场景Linux 与 macOS aarch64 平台提供。这两个组件属于「尽力而为」安装下载或解压失败只打印 warning不影响主引擎安装成功但会明确提示「VM-based sandbox workers 将不可用直到重新运行 install.sh 或手动从 releases 安装」。macOS Intelx86_64目前没有 iii-worker 资产脚本会打印提示说明该机型上 VM 隔离类功能暂不可用。2. 验证安装结果安装完成后运行iii --version该命令应输出一个版本号。从源码看这一输出直接来自编译期常量CARGO_PKG_VERSIONengine/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 a10 b20 # → { 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_PATHconsole/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考