Solana 集群软件安装与自动更新机制详解从 solana-install 到链上 Update Manifest【免费下载链接】solanaWeb-Scale Blockchain for fast, secure, scalable, decentralized apps and marketplaces.项目地址: https://gitcode.com/GitHub_Trending/so/solana本文围绕 Solana 仓库中的实现提案文档《Cluster Software Installation and Updates》系统讲解solana-install安装器的设计目标、三种安装路径curl 引导脚本、Release 预编译二进制、源码构建、链上更新清单Update Manifest的数据结构与防篡改/防回滚机制以及发布包release tarball的内部结构。读完本文你将能够独立完成 Solana 节点软件的安装、向集群部署新版本以及运行一个会自动跟随更新、并在更新后自动重启的 validator 进程并理解其背后每一处 CLI 行为对应的源码实现。一、背景与设计目标Solana 集群软件solana-keygen、solana-validator等一系列工具早期要求用户自行从 git 仓库编译、并手动完成升级这一过程既容易出错又繁琐。该提案的目标是提供一个易用的软件安装器与更新器为受支持的平台部署预编译二进制用户既可以使用 Solana 官方提供的二进制也可以使用任意第三方供应方的二进制更新部署通过一个链上的更新清单update manifest账户来管理和分发。这套机制把发现新版本—校验完整性—下载—激活变成一个可被任何第三方复用的协议发布者只需把清单写入链上的 config 账户消费者只需读取该账户即可知道最新版本、下载地址及其 SHA256。二、安装方式一curl Shell 引导脚本对受支持平台而言最简单的安装方式是一行引导脚本原文档以 v1.0.0 为例$ curl -sSf https://raw.githubusercontent.com/solana-labs/solana/v1.0.0/install/solana-install-init.sh | sh该脚本会查询 GitHub 上最新的 tagged release并下载、运行对应的solana-install-init二进制。如果安装时需要额外参数使用如下 shell 语法$ init_args.... # arguments for solana-install-init ... $ curl -sSf https://raw.githubusercontent.com/solana-labs/solana/v1.0.0/install/solana-install-init.sh | sh -s - ${init_args}引导脚本的源码解析install/solana-install-init.sh 就是这个引导脚本本身它借鉴了 Rust 官方 rustup-init 的安装脚本风格。其核心逻辑可以概括为平台检测通过uname -s/uname -m推导 target triple。Linux 映射为unknown-linux-gnumacOSDarwin映射为apple-darwin其中arm64会被归一化为aarch64其他平台直接报machine architecture is currently unsupported。最终得到TARGET${_cputype}-${_ostype}见 install/solana-install-init.sh。确定 release 版本默认请求https://api.github.com/repos/solana-labs/solana/releases/latest并从中解析tag_name若设置了环境变量SOLANA_RELEASE则直接使用该版本install/solana-install-init.sh。下载并执行拼接$SOLANA_DOWNLOAD_ROOT/$release/solana-install-init-$TARGETSOLANA_DOWNLOAD_ROOT默认为 GitHub Releases 下载根路径可被覆盖下载后chmod ux并执行执行参数来自sh -s -传入的$或在无参数时来自环境变量SOLANA_INSTALL_INIT_ARGSinstall/solana-install-init.sh。健壮性细节脚本用 curl 或 wget 兜底下载downloader函数并在/tmp被挂载为noexec时给出明确提示建议把二进制拷贝到可执行位置后再运行install/solana-install-init.sh。三、安装方式二从 GitHub Release 获取预编译安装器在已知 release URL 的情况下可直接下载对应平台的预编译安装器$ curl -o solana-install-init https://github.com/solana-labs/solana/releases/download/v1.0.0/solana-install-init-x86_64-apple-darwin $ chmod x ./solana-install-init $ ./solana-install-init --help文件名中的x86_64-apple-darwin即上文所述的 target triple与引导脚本自动推导出的结果一致。四、安装方式三从源码构建当某个平台没有预编译产物时从源码构建始终是可选路径$ git clone https://github.com/solana-labs/solana.git $ cd solana/install $ cargo run -- --helpinstall/Cargo.toml 定义了solana-install这个 crate其入口 install/src/main.rs 直接委托给库函数solana_install::main()对应 install/src/lib.rs 中的 CLI 定义。当前版本的扩展按版本号或渠道安装原文档描述的init只接受更新清单公钥一种寻址方式。从当前源码看install/src/lib.rs 中init子命令还接受一个位置参数release即ExplicitRelease可以是一个具体 semver 版本号如1.13.6可带v前缀一个发布渠道取值限定为edge、beta、stable由 install/src/lib.rs 的is_release_channel校验。两种寻址方式互斥conflicts_with_all且handle_init要求二者至少指定其一否则报错提示用户Please specify the release to installinstall/src/lib.rs。从源码结构看两者的下载源不同install/src/command.rs固定版本号走 GitHub Releaseshttps://github.com/solana-labs/solana/releases/download/vsemver/solana-release-TARGET.tar.bz2渠道模式走https://release.solana.com/channel/solana-release-TARGET.tar.bz2并先下载同目录的solana-release-TARGET.yml来获取渠道当前的 commit从而判断是否有更新install/src/command.rs。版本比较策略由SemverUpdateType控制install/src/command.rsinit时用Fixed精确版本update时用Patch~语义只接受同 minor 内的 patch 升级check_for_newer_github_release会分页拉取 GitHub Releases 列表并按 semver 过滤、排序后取最大版本install/src/command.rs。五、向集群部署一个新版本deploy原文档给出的部署流程是给定一个已经上传到公开可访问 URL 的 Solana release tarball由ci/publish-tarball.sh生成执行$ solana-keygen new -o update-manifest.json # -- only generated once, the public key is shared with users $ solana-install deploy http://example.com/path/to/solana-release.tar.bz2 update-manifest.json其中update-manifest.json这个 keypair 只需生成一次其公钥将作为更新频道的身份共享给所有需要消费该更新的安装器用户。deploy 的源码级调用链solana-install deploy的实现在 install/src/command.rs 的deploy()函数中整体流程为读取两个 keypair付款账户funding account即-k/--keypair默认~/.config/solana/id.json见 install/src/defaults.rs和更新清单 keypair校验集群连通性与余额通过RpcClient查询付款账户余额余额为 0 直接报错创建链上账户需要支付租金下载 release 并计算 SHA256download_to_temp()下载到临时目录并流式计算 SHA256install/src/command.rs如果链上已有清单且其download_sha256与新包一致直接提示Update is already deployed并退出幂等性保护解包并读取 targetextract_release_archive()以 bzip2tar 解包load_release_target()读取包内solana-release/version.yml的target字段供用户确认部署对象平台构造并签名清单填充timestamp_secs当前 UNIX 秒、download_url、download_sha256用更新清单 keypair 对 manifest 本体签名并assert!(update_manifest.verify())install/src/command.rs;写链new_update_manifest()检查清单账户是否存在不存在则通过 config 程序的create_account指令创建按SignedUpdateManifest::max_space()申请租金豁免 lamports随后store_update_manifest()用config_instruction::store指令把签名清单写入该账户install/src/command.rs。也就是说deploy 本质上就是向 Solana 的config 程序programs/config写入了一个SignedUpdateManifest序列化数据。六、链上更新清单On-chain Update Manifest更新清单用于在 Solana 集群上通告新 release tarball 的部署。清单存储在config程序中每个清单账户对应一个逻辑更新频道和一个 target triple例如x86_64-apple-darwin账户公钥在部署方与消费方之间是约定已知的well-known。清单本体很小只描述去哪里下载release 包本身托管在链下off-chain的任意存储上由download_url指向use solana_sdk::signature::Signature; /// Information required to download and apply a given update pub struct UpdateManifest { pub timestamp_secs: u64, // When the release was deployed in seconds since UNIX EPOCH pub download_url: String, // Download URL to the release tar.bz2 pub download_sha256: String, // SHA256 digest of the release tar.bz2 file } /// Data of an Update Manifest program Account. #[derive(Serialize, Deserialize, Default, Debug, PartialEq)] pub struct SignedUpdateManifest { pub manifest: UpdateManifest, pub manifest_signature: Signature, }当前实现中的两点演进对照 install/src/update_manifest.rs当前代码相对提案文档有两个实现层面的差异download_sha256的类型从String收紧为Hashinstall/src/update_manifest.rs在序列化/反序列化层面杜绝了非法摘要字符串SignedUpdateManifest实现了Signable与ConfigState两个 traitSignable规定签名数据为 manifest 的 bincode 序列化结果签名公钥即清单账户公钥install/src/update_manifest.rsConfigState::max_space()返回256字节恰好容纳一个完整填充的SignedUpdateManifest这正是 deploy 时计算租金豁免的依据install/src/update_manifest.rs。反序列化入口SignedUpdateManifest::deserialize()在读取后立即调用verify()校验失败返回Manifest failed to verifyinstall/src/update_manifest.rs。防中间人与防回滚防中间人manifest_signature保证solana-install工具与集群 RPC API 之间即便被中间人截获篡改download_url或download_sha256也无法通过签名校验完整性下载时download_to_temp()会对文件重算 SHA256与清单中的download_sha256不一致则报Incorrect hash并终止install/src/command.rs防回滚攻击solana-install拒绝安装timestamp_secs比当前已安装版本更旧的更新。对应源码即init_or_update()中的检查if let Some(ref current_update_manifest) config.current_update_manifest { if update_manifest.timestamp_secs current_update_manifest.timestamp_secs { return Err(Unable to update to an older version.to_string()); } }install/src/command.rs此外还有一个时钟可信度检查若本机当前时间早于安装器自身的构建时间则判定system time seems unreliable并拒绝更新防止系统时钟错误绕过回滚保护install/src/command.rs。七、Release 包Release Archive的内部结构原文档约定 release 包为bzip2 压缩的 tar 文件内部结构为/version.yml— 一个简单的 YAML 文件含target字段target triple其他字段忽略/bin/— 本次发布中所有可用程序所在的目录solana-install会把它软链到~/.local/share/solana-install/bin供PATH环境变量使用其他任意文件和目录均被允许。从当前构建脚本看实际打包结构deploy命令文档中提到的 release tarball 由 ci/publish-tarball.sh 生成该脚本的实际做法是ci/publish-tarball.sh创建顶层目录solana-release/写入solana-release/version.yml包含三个字段channel渠道或 tag、commitgit rev-parse HEAD、target构建 targetLinux 固定为x86_64-unknown-linux-gnumacOS 按uname -m推导aarch64-apple-darwin等通过scripts/cargo-install-all.sh stable把所有 crate 的cargo-binstall产物装入solana-release/bin打包为solana-release-TARGET.tar.bz2并同时产出solana-release-TARGET.yml渠道版本描述文件和solana-install-init-TARGET安装器二进制。从源码结构看当前版本solana-install读取的就是包内solana-release/version.yml中的target字段install/src/command.rs 的load_release_target并在更新安装器自身时校验target build_env::TARGET不一致则报Incompatible update target拒绝安装install/src/command.rs。解包流程extract_release_archive()采用先解到tmp-extract再原子 rename的方式避免半成品目录被激活install/src/command.rs。八、solana-install 工具文件布局与命令行接口solana-install是用户安装与更新集群软件的主工具。原文档描述它管理用户主目录下的以下文件与目录~/.config/solana/install/config.yml— 用户配置与当前已安装版本的信息~/.local/share/solana/install/bin— 指向当前 release 的符号链接原文档记为~/.local/share/solana-install/bin形式指向~/.local/share/solana-update/update-pubkey-manifest_signature/bin~/.local/share/solana/install/releases/download_sha256/— 某个 release 的解包内容以 SHA256 为缓存键。当前源码中的默认路径定义见 install/src/defaults.rs常量默认路径用途CONFIG_FILE~/.config/solana/install/config.yml安装配置DATA_DIR~/.local/share/solana/install安装数据根目录-d/--data-dir默认值USER_KEYPAIR~/.config/solana/id.jsondeploy 时付款账户的默认 keypairConfig结构install/src/config.rs序列化到该 YAML 文件中的字段为字段类型说明json_rpc_urlString集群 JSON RPC URL默认http://api.devnet.solana.comupdate_manifest_pubkeyPubkey更新清单账户公钥current_update_manifestOptionUpdateManifest当前已安装版本对应的清单快照update_poll_secsu64轮询更新的周期默认60 * 60秒install/src/config.rsexplicit_releaseOptionExplicitReleaseSemver或Channel显式发布模式时非空releases_dirPathBufdata_dir/releases各版本缓存active_release_dirPathBufdata_dir/active_release当前激活版本的符号链接激活逻辑是符号链接切换更新成功后把release_dir/solana-release软链到active_release_dirinstall/src/command.rs因此切回旧版本只需换链无需重装。命令行接口原文档记录的 CLI 帮助输出v0.16.0 时代如下可作为理解各子命令语义的基准solana-install 0.16.0 The solana cluster software installer USAGE: solana-install [OPTIONS] SUBCOMMAND FLAGS: -h, --help Prints help information -V, --version Prints version information OPTIONS: -c, --config PATH Configuration file to use [default: .../Library/Preferences/solana/install.yml] SUBCOMMANDS: deploy deploys a new update help Prints this message or the help of the given subcommand(s) info displays information about the current installation init initializes a new installation run Runs a program while periodically checking and applying software updates update checks for an update, and if available downloads and applies itsolana-install-init initializes a new installation USAGE: solana-install init [OPTIONS] FLAGS: -h, --help Prints help information OPTIONS: -d, --data_dir PATH Directory to store install data [default: .../Library/Application Support/solana] -u, --url URL JSON RPC URL for the solana cluster [default: http://api.devnet.solana.com] -p, --pubkey PUBKEY Public key of the update manifest [default: 9XX329sPuskWhH4DQh6k16c87dHKhXLBZTL3Gxmve8Gp]solana-install info displays information about the current installation USAGE: solana-install info [FLAGS] FLAGS: -h, --help Prints help information -l, --local only display local information, dont check the cluster for new updatessolana-install deploy deploys a new update USAGE: solana-install deploy download_url update_manifest_keypair FLAGS: -h, --help Prints help information ARGS: download_url URL to the solana release archive update_manifest_keypair Keypair file for the update manifest (/path/to/keypair.json)solana-install update checks for an update, and if available downloads and applies it USAGE: solana-install update FLAGS: -h, --help Prints help informationsolana-install run Runs a program while periodically checking and applying software updates USAGE: solana-install run program_name [program_arguments]... FLAGS: -h, --help Prints help information ARGS: program_name program to run program_arguments... arguments to supply to the program The program will be restarted upon a successful software update注以上-c与-d的[default: ...]展示为 macOS 路径示例当前源码在 Linux 上的实际默认值以 install/src/defaults.rs 中的~/.config/solana/install/config.yml与~/.local/share/solana/install为准。各子命令在当前源码中的行为补充结合 install/src/lib.rs 与 install/src/command.rs当前版本的子命令全集与要点init写入仅在变化时配置文件 → 执行init_or_update(is_inittrue)完成首次安装 → 修改 PATH。PATH 修改的平台策略是Unix 下向已存在的~/.profile、~/.bash_profile、~/.zprofilezsh追加export PATHbin_dir:$PATH不会主动创建.bash_profile以免抢占.profile的读取修改后提示重开终端Windows 下改写HKEY_CURRENT_USER\Environment\PATH注册表项并广播WM_SETTINGCHANGEinstall/src/command.rs。若--no-modify-path则跳过并在PATH未包含 bin 目录时打印手工配置提示install/src/command.rs。info显示配置路径、激活 release 目录、release commit来自version.yml、清单公钥与 release 日期--local只查本地、不访问集群否则自动触发一次update(check_onlytrue)检查install/src/command.rs。deploy如上文第五节所述当前 CLI 额外提供-k/--keypair付款账户与-u/--url选项install/src/lib.rs。updateupdate(config_file, false)→init_or_update走清单比对、下载带 SHA256 校验、解包、换链、保存配置、gc的完整流程install/src/command.rs。run见下文专门小节。gc原文档之后新增按目录 mtime 排序releases/下的所有 release 缓存只保留最新的MAX_CACHE_LEN 5份删除更旧的以回收磁盘空间install/src/command.rs。list原文档之后新增列出releases/下已安装的各版本当前版本标记(current)install/src/command.rs。run 子命令自动更新并重启的进程包装器原文档给出的典型用法——运行一个会自动自我更新的 validator 节点$ solana-install init --pubkey 92DMonmBYXwEMHJ99c9ceRSpAmk9v6i3RdvDdXaVcrfj # -- pubkey is obtained from whoever is deploying the updates $ export PATH~/.local/share/solana-install/bin:$PATH $ solana-keygen ... # -- runs the latest solana-keygen $ solana-install run solana-validator ... # -- runs a validator, restarting it as necessary when an update is appliedrun的实现install/src/command.rs是一个事件循环解析data_dir/active_release/bin/program_nameWindows 自动补.exe不存在则直接报错启动子进程后进入循环try_wait()检测子进程退出并打印退出状态退出后下一轮循环自动重新拉起每经过update_poll_secs默认 3600 秒且处于清单模式explicit_release为None时调用update()若应用了新版本则通过stop_process()终止当前子进程下一轮循环即使用新版本二进制重启——这就是restarting it as necessary when an update is applied的实现注册ctrlc信号处理器收到 SIGTERM/SIGINT 时停止子进程并以 0 退出install/src/command.rs、install/src/command.rs。九、小结适用前提与约束本文所述安装/更新机制以提案文档 docs/src/implemented-proposals/installer.md 为主体源码佐证均来自当前仓库的 install crate 与 ci/publish-tarball.sh文档中的 CLI 帮助文本与目录路径为早期版本v0.16.0 前后记录当前版本的实际参数如init的release位置参数、gc/list子命令、active_release目录名请以 install/src/lib.rs 的 clap 定义为准清单模式-p/--pubkey要求能访问指定集群的 JSON RPC且部署方 keypair 需持有足够 lamports 支付清单账户租金显式 release/渠道模式则完全离线于链仅依赖 GitHub Releases 或release.solana.com的可用性回滚保护依赖timestamp_secs与本机时钟可信因此文档强调的拒绝旧版本仅在部署方按时间单调递增写清单、且消费端系统时间基本正确的前提下成立。【免费下载链接】solanaWeb-Scale Blockchain for fast, secure, scalable, decentralized apps and marketplaces.项目地址: https://gitcode.com/GitHub_Trending/so/solana创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考