mise bootstrap plan声明式机器引导的资源变更计划、JSON 输出与 CI 退出码实战指南【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise在 mise 的机器引导machine bootstrap体系中mise bootstrap plan是一条只读命令它计算当前配置下声明式 bootstrap 资源收敛到期望状态所需的变更并以表格或 JSON 形式输出计划但绝不执行任何变更。读完本文你能掌握 plan 命令的四个标志位用法、人类可读与机器可读两种输出格式、--detailed-exitcode在 CI 中的漂移检测技巧并能从源码层面理解计划图的构建、依赖拓扑排序与退出码判定逻辑。一、mise bootstrap plan的定位只读、面向声明式资源原始 CLI 参考文档docs/cli/bootstrap/plan.md对该命令的定义是Usage:mise bootstrap plan [FLAGS]Effect:read-only只读不改变系统状态功能描述:Show the changes declarative bootstrap resources would make展示声明式 bootstrap 资源将会做出的变更文档同时给出了两条重要的使用边界这两点在源码中同样得到印证它只覆盖声明式资源不覆盖完整 bootstrap 流程中的每一个 hook、每一次包插件安装或 task 执行。文档原文建议Usebootstrap --dry-runto preview the complete workflow——若你想预览完整工作流含 hooks 与 task应改用mise bootstrap --dry-run。--detailed-exitcode用于区分三种结果无变更退出码 0、有变更退出码 2、出错退出码 1。从源码结构看mise bootstrap的整体阶段顺序定义在 src/cli/bootstrap.rs 的文档注释中账户 → 包 → 特权文件/服务/防火墙/Compose → 仓库与 dotfiles → shell 激活/macOS 配置/systemd → 工具 → task。而bootstrap plan只是其中声明式资源子集的计划视图对应实现是独立的BootstrapPlan参数结构体// src/cli/bootstrap.rsL325-L344节选 /// Show the changes declarative bootstrap resources would make /// /// Covers declarative resources, not every hook, package installation, or task in a /// full bootstrap run. Use bootstrap --dry-run to preview the complete workflow. /// --detailed-exitcode distinguishes unchanged (0), changes (2), and errors (1). #[derive(Debug, usage_rs::Args)] #[usage(verbatim_doc_comment)] struct BootstrapPlan { /// Output a stable machine-readable plan in JSON format #[usage(long, short J)] json: bool, /// Exit 2 when the plan contains changes, 0 when unchanged, and 1 on errors #[usage(long, verbatim_doc_comment)] detailed_exitcode: bool, /// Prompt securely for missing bootstrap secret inputs #[usage(long)] prompt_secrets: bool, }在子命令枚举中Plan(BootstrapPlan)与Status、ConfigRoots、Accounts、Packages、Repos等并列src/cli/bootstrap.rs说明它是 bootstrap 子命令族中专注于计划的一条路径。二、标志位速查标志作用典型场景-J,--json以稳定的机器可读 JSON 格式输出计划供脚本/Agent 解析计划--detailed-exitcode计划含变更时退出码 2无变更退出码 0出错退出码 1CI 中检测系统是否已收敛--prompt-secrets对缺失的 bootstrap secret 输入进行安全交互式提示配置引用了未注入的 secret 时-h,--help打印帮助—--prompt-secrets的必要性bootstrap 配置中的某些资源如特权文件内容可能引用 secret 值。计划构建前会先解析 secrets// src/cli/bootstrap.rsimpl BootstrapPlan::runL2424-L2428节选 let config Config::get().await?; let secrets system::secrets::resolve(config, self.prompt_secrets)?; let plan system::resources::plan(config, secrets).await?; let output plan.output()?;secrets::resolve接收prompt_secrets布尔值若开启当配置声明的 secret 输入在环境中缺失时会通过安全方式向用户索取而不是直接报错。这在计划阶段尤其重要——没有 secret 就无法比对文件期望内容计划会失真。三、人类可读输出五列计划表 汇总行不传--json时命令将每个资源渲染为五行一列的表格并在末尾打印汇总。源码中的渲染逻辑src/cli/bootstrap.rs// 若计划为空 info!(nothing configured for bootstrap planning); // 否则构建表格列名为 MiseTable::new(false, [Action, Resource, Current, Desired, Config]) // 每个资源一行action / id / current / desired / origin.config 路径 // 末尾汇总 miseprintln!( Plan: {} create, {} update, {} unchanged, {} remove, {} unknown, output.summary.create, output.summary.update, output.summary.unchanged, output.summary.remove, output.summary.unknown, );各列含义Action收敛动作取值create/update/remove/unchanged/unknown对应源码枚举ResourceAction的Create/Update/Remove/Noop/Unknown其中Noop显示为unchanged见 src/system/resources.rsResource资源身份格式为kind:name例如package:apt:git、user:alice、directory:/etc/miseResourceId的Display实现为write!(f, {}:{}, self.kind, self.name)见 src/system/resources.rsCurrent / Desiredsecret-safe 的当前状态与期望状态描述Config声明该资源的配置文件路径origin.config便于定位声明来源。四、--json机器可读输出传-J时输出为serde_json::to_string_pretty格式化后的 JSON。其结构由BootstrapPlanOutput定义src/system/resources.rs{ resources: [ { id: { kind: package, name: apt:git }, current: 2.43.0 installed, desired: latest, action: update, origin: { config: mise.toml, config_root: /home/user, environment: [] }, depends_on: [] } ], summary: { create: 1, update: 1, remove: 0, unchanged: 3, unknown: 0 } }字段取值以实际配置为准以上为结构示意。关键结构体说明ResourcePlansrc/system/resources.rs每个资源一条含id、current、desired、action、可选的originResourceOrigin含config、config_root、environment、source四字段路径序列化时会处理非 UTF-8 路径与depends_on依赖的资源 id 列表。注释特别标注它是A secret-safe description——即 current/desired 描述被刻意做成不泄露 secret 明文的形式。PlanSummarysrc/system/resources.rs五类动作的计数并提供两个判定方法has_changes()create update remove 0has_unknown()unknown 0。这两个方法正是--detailed-exitcode退出码的直接依据文档承诺的稳定机器接口由#[serde(rename_all snake_case)]的枚举序列化保证。五、--detailed-exitcode把漂移变成退出码这是该命令面向 CI/定时巡检的核心能力。源码实现src/cli/bootstrap.rsif self.detailed_exitcode { if output.summary.has_unknown() { bail!(bootstrap plan contains resources with unknown state); } if output.summary.has_changes() { return Err(crate::request_exit(2)); } }三种结果的优先级与语义计划内容行为退出码存在unknown状态资源直接报错unknown意味着管理器不可用、插件缺失等无法判断是否收敛1错误含 create/update/remove正常打印计划后请求退出码 22有变更全部unchanged正常结束0无变更一个典型的 CI 用法在系统初始化流水线中每次部署后运行mise bootstrap plan --detailed-exitcode退出码为 0 表示机器状态已完全收敛于mise.toml声明为 2 则说明存在漂移例如某台机器少了某个服务或包可据此触发mise bootstrap修复为 1 则提示先排查unknown资源常见原因是包管理器插件未安装。注意不开--detailed-exitcode时无论计划是否有变更命令成功执行即为退出码 0——该标志是显式开启的。六、计划如何生成从配置到资源图bootstrap plan的核心调用链是Config::get()→secrets::resolve()→system::resources::plan()src/system/resources.rs。源码注释说明其定位Build the resource plan currently supported by the provisioning engine. Other bootstrap sections will move into this graph as resource adapters land.——即这是一个逐步扩大的资源图当前版本已经纳入的资源类别可以从plan()函数体中确认账户super::accounts::prepare_requests_from_config每个 user/group 生成一条ResourcePlan用户加入的 Present 组会建立user → group依赖删除组前会确保依赖它的用户先被移除add_dependency反向建边内置包管理器packages_from_config逐包比对installed()状态得出动作管理器不可用被system_packages.managers排除或平台不支持时对应包标记为Unknown并附原因如unavailable (excluded by system_packages.managers)包插件待装包pending_plugin_packages_from_config_including_disabled插件未安装时同样标记Unknown (package plugin is not installed)特权文件与目录managed_files::status_requests_from_config含属主/属组校验与通知服务校验服务services::status_requests_from_config及依赖边。图的校验去重、缺失依赖与环检测计划不是简单列表而是一张声明顺序的资源图BootstrapPlan在IndexMapResourceId, ResourcePlan之上提供三类校验src/system/resources.rs重复声明检测insert()对同一ResourceId二次插入直接bail!(bootstrap resource {} is declared more than once)——同一资源在多个配置文件根中被重复声明会被明确报错而非静默覆盖拓扑排序ordered()用入度队列做 Kahn 算法输出按依赖顺序排列的资源序列引用了不存在的资源会报depends on missing resource循环依赖检测若排序后数量不足收集剩余资源报bootstrap resource dependency cycle: ...。output()在排序成功的基础上汇总计数src/system/resources.rs最终交给 CLI 层渲染。这也解释了--json输出中资源是按依赖顺序而非纯配置顺序出现的。--skip语义与计划的交互虽然plan本身没有--skip标志但 bootstrap 主命令的--skip/--only部件枚举BootstrapPart见 src/cli/bootstrap.rs在计划预测中同样有影响bootstrap_resource_is_skipped与bootstrap_prediction_has_skipped_changesrc/cli/bootstrap.rs会沿依赖图递归判断被跳过的部件中是否存在会产生变更的资源用于主流程的预测输出。这提示读者plan展示的是未被任何环境排除的声明式资源全集而实际bootstrap运行时可通过--only/--skip收窄执行范围。七、与相关命令的配合文档的 Related documentation 段落指向了三份材料按仓库路径分别是 Bootstrap workflow、mise bootstrap [FLAGS] [SUBCOMMAND]与 全局标志。在实操中推荐按以下顺序使用命令用途与 plan 的关系mise bootstrap plan看声明式资源要做什么变更本文主题只读mise bootstrap plan -J --detailed-exitcodeCI 中收敛性检查机器可读 退出码mise bootstrap --dry-run预览完整工作流含 hooks/taskplan 的超集预览mise bootstrap status查看已配置资源的当前状态--missing对漂移返回非零退出码mise bootstrap config-roots查看各配置根未组合前的声明分布定位声明来源补充 plan 的 Config 列例如bootstrap status同样输出Action / Resource / Current / Desired表格对比 src/cli/bootstrap.rs 中的BootstrapStatus其--missing标志对漂移返回退出码 1两者视角互补status 面向现在系统长什么样plan 面向声明要求它变成什么样、需要哪些动作。端到端测试也覆盖了这条命令链仓库中的 e2e/cli/test_bootstrap_config_roots、e2e/cli/test_bootstrap_accounts、e2e/cli/test_bootstrap_secrets 等脚本会在临时环境中执行bootstrap plan系列调用可作为预期行为的回归参照。八、适用前提与限制小结只读承诺Effect: read-only但注意mise bootstrap主文档注释提醒——dotfile 模板在检查状态时可能执行其中的exec()调用见 src/cli/bootstrap.rs 对status的说明plan 聚焦声明式资源风险面小得多但仍建议先理解配置内容。覆盖面仅覆盖声明式资源账户、包、特权文件/目录、服务等已纳入资源图的部分不覆盖 hook、task、版本化工具安装需要完整预览请用bootstrap --dry-run。unknown不是无变更管理器不可用、插件未装等情形会计入unknown在--detailed-exitcode下直接视为错误退出而不是静默通过。重复声明会报错同一资源 id 在配置中被多次声明时plan会以错误结束提示检查配置文件根组合。通过mise bootstrap plan你可以把机器该有什么这一声明与机器实际有什么的差距变成可审阅的表格、可解析的 JSON 和可门禁的退出码——这正是 mise 引导体系在变更预览与自动化巡检环节提供的核心能力。【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考