Boilerplates CLI 快速上手指南从安装 CLI、同步模板库到生成可配置工作负载【免费下载链接】boilerplatesCreate reusable templates and turn them into configurable workloads for homelabs and self-hosted infrastructure. Free and Open-Source.项目地址: https://gitcode.com/GitHub_Trending/bo/boilerplates本篇指南完整梳理当前 Boilerplates 项目的标准工作流安装 CLI、同步官方模板库、浏览与检视模板再到通过template.json清单生成可配置的工作负载文件。读完本文你将掌握boilerplates命令行工具从repo update到compose generate的完整链路并能用--var、--var-file与defaults机制对任意模板做非交互式定制化生成。前置条件在开始之前请确保本机满足以下条件Python 3.9 或更新版本可用python3 --version确认Git同步基于 Git 的模板库时必需网络访问用于下载依赖与拉取 Git 模板库。关于各平台Linux、macOS、NixOS、Windows/WSL的完整安装细节可参考 .wiki/Installation.md。安装 CLI项目提供一键安装脚本它会自动检查并补齐依赖Python、pip、git、pipx然后通过 pipx 将 CLI 安装到隔离环境中curl -fsSL https://raw.githubusercontent.com/christianlempa/boilerplates/main/scripts/install.sh | bash安装脚本本身是仓库内的 scripts/install.sh从源码可以看到它的完整逻辑依赖检查与自动安装check_dependencies()依次检查python3、git、pip、pipx缺失时按AUTO_INSTALL默认true自动补齐Linux 下按发行版分发Ubuntu/Debian 走apt、Fedora/RHEL 走dnf、openSUSE 走zypper、Arch 走pacman、Alpine 走apkmacOS 下优先使用 Homebrew见install_dependencies_macos()/install_dependencies_linux()版本解析与下载默认安装latest版本脚本通过 GitHub Releases API 解析最新 tag再从 release 资产中下载boilerplates-版本.tar.gz并解压验证download_and_extract()pipx 安装以pipx install --force将包装入隔离环境最终提示boilerplates命令已可用install_cli()。安装指定版本如需安装特定版本用--version传参curl -fsSL https://raw.githubusercontent.com/christianlempa/boilerplates/main/scripts/install.sh | bash -s -- --version v0.2.0脚本支持的环境变量与选项包括VERSION/INSTALL_VERSION版本、AUTO_INSTALL是否自动装依赖、--no-auto-install跳过自动依赖安装。验证安装boilerplates --version入口实现在 cli/main.py其中--version别名-v会直接打印版本号同时提供--log-level参数DEBUG/INFO/WARNING/ERROR/CRITICAL默认关闭日志遇到异常时可加--log-level DEBUG查看更多细节。备选安装方式Nix / NixOS项目提供 Nix Flake见 flake.nix可用nix run github:christianlempa/boilerplates -- --help免安装运行或nix profile install github:christianlempa/boilerplates安装到 profile源码开发模式git clone后创建虚拟环境并pip install -e .以python3 -m cli --help运行。同步默认模板库安装完成后第一步是同步官方默认模板库boilerplates repo update该命令由 cli/core/repo.py 实现首次运行会写入默认库配置默认指向christianlempa/boilerplates-library对每个启用的 Git 库执行clone 或 pull本地无检出时浅克隆--depth 1已有检出则git pull --ff-only快速更新。若远程地址变更或检出与远端分叉如 “Diverging branches cant be fast-forwarded”会自动替换为干净克隆_clone_or_pull_repo()、_replace_repo_checkout()支持sparse-checkout库配置中的directory字段只拉取模板仓库的指定子目录如library见_clone_sparse_repo()支持静态库type: static本地路径与禁用库enabled: false跳过同步。同步结果存放在配置目录下的libraries/文件夹中全局配置默认在~/.config/boilerplates/libraries/若 CLI 使用本地./config.yaml则同步到./libraries/。相关库管理命令还包括boilerplates repo list # 列出所有已配置库 boilerplates repo add mylib --type git --url url # 添加 Git 库并同步 boilerplates repo remove mylib # 移除库配置默认删除本地文件浏览与搜索模板模板按模块module组织例如compose、terraform、kubernetes、helm、ansible、bash、python等。列出某个模块下所有可用模板boilerplates compose list输出以 Rich 表格呈现包含ID、Name、Tags、Version、Library列。从 cli/core/module/base_commands.py 的list_templates()可见模板加载时会自动过滤草稿模板metadata.draft: true不进入正常发现。按 ID 模糊搜索boilerplates compose search nginx搜索逻辑为query.lower() in t.id.lower()对模板 ID 做大小写不敏感的包含匹配见search_templates()。检视模板生成之前先用show查看模板的完整信息boilerplates compose show nginxshow_template()cli/core/module/base_commands.py会展示四部分内容模板元数据名称、描述、作者、标签、图标等可见版本标签来自metadata.version.name若存在。注意这与旧格式顶层的version字段不同——后者是镜像/应用版本而metadata.version.name是面向用户的版本展示标签会出现在 list/show 输出的 Version 列见list_templates()中version template.metadata.version.name if template.metadata.version else -文件结构files/目录下的完整输出树render_file_tree()变量分组与条目模板实际暴露的变量组如general、ports、traefik、network、swarm及其中的具体变量展示默认值、类型与描述render_variables_table()。show也接受--var/--var-file与生成命令使用相同的变量优先级便于在生成前预览某个取值组合下的变量表。生成文件交互式生成boilerplates compose generate nginx --output ./my-nginx生成流程generate_template()cli/core/module/base_commands.py按优先级合并变量模板默认值 →defaults配置 →--var-file文件 →--var命令行覆盖_prepare_template()交互式收集未确定值collect_variable_values()随后校验全部变量并渲染files/下所有文件写出前检查目标目录若目录非空交互模式下会询问是否继续默认否并提示将有 N 个文件被覆盖check_output_directory()写入完成后给出文件数与体积摘要write_rendered_files()。非交互式生成在 CI 或脚本中用--no-interactive配合--var提供全部所需变量boilerplates compose generate nginx \ --output ./my-nginx \ --var service_namemy-nginx \ --no-interactive非交互模式下若目标目录非空只记录警告并继续覆盖见check_output_directory()的 else 分支。仅预览dry-runboilerplates compose generate nginx --dry-run --show-files--dry-run只渲染不落盘并统计将要创建/覆盖的文件数与总字节数execute_dry_run()--show-files会把每个渲染后的文件内容完整打印出来_display_rendered_file_contents()非常适合生成前人工审查渲染结果。未指定--output时dry-run 默认使用当前目录下的slug目录作为隐式目标仅用于统计。其他生成选项--remote/--remote-path将渲染结果直接上传到 SSH 远程目标--name为顶层输出文件重命名入口文件main.ext变为name.ext其余顶层路径加name_前缀见apply_output_name()--quiet静默模式不打印渲染明细。覆盖变量直接命令行覆盖boilerplates compose generate traefik \ --output ./proxy \ --var service_nametraefik \ --var traefik_enabledtrue \ --var traefik_hostproxy.example.com--var可多次使用每个参数形如namevalue。布尔变量可直接写true/false。变量文件覆盖把一组变量写入 YAML 文件适合复用与版本化管理boilerplates compose generate traefik \ --output ./proxy \ --var-file ./vars.yaml \ --no-interactive--var-file中的键值对与--var相同地作用于变量收集阶段apply_var_file()/apply_cli_overrides()。整条链路的变量来源优先级为CLI--var--var-filedefaults配置 模板内置默认值。若在渲染文件中引用了未在template.json中声明的变量模板会校验失败并在加载/渲染阶段报出模板错误参见 .wiki/Core-Concepts-Templates.md 与 cli/core/template/template.py 中的TemplateErrorHandler它会给出“未声明变量”及“你是指 …”的修正建议。保存可复用的默认值对于经常不变的变量时区、重启策略等可以写入模块级默认配置之后每次生成都会自动套用boilerplates compose defaults set container_timezoneEurope/Berlin boilerplates compose defaults set restart_policyunless-stopped查看当前模块的全部默认值boilerplates compose defaults list默认值管理实现在 cli/core/module/config_commands.pydefaults set VAR_NAME VALUE也支持VAR_NAMEVALUE形式调用ConfigManager.set_default_value()写入defaults list以平铺列表显示该模块下所有已配置默认值config_get()还提供defaults get、defaults remove、defaults clear等子命令。这些默认值在生成时通过apply_variable_defaults()注入优先级高于模板内置默认值、低于--var-file与--var。这意味着你可以在 nginx、traefik 等多个 compose 模板之间共享同一套“欧洲/柏林时区、unless-stopped 重启策略”的惯例配置不必重复输入。校验模板校验单个模板boilerplates compose validate nginx校验模块内全部模板boilerplates compose validate校验逻辑在validate_templates()cli/core/module/base_commands.py中覆盖以下维度清单结构template.json必须存在且结构合法变量声明覆盖files/中出现的每个变量都必须在template.json中声明template.used_variables分隔符兼容性必须使用自定义分隔符旧式 Jinja 默认分隔符会被拒绝可渲染性实际渲染一遍捕获未定义变量、语法错误等错误会附带文件路径与行号上下文语义校验可选默认开启通过--semantic对渲染结果做模块相关的语义检查如 YAML 解析compose模块还提供--matrix遍历所有可达的依赖组合与--kind/--docker依赖矩阵 Docker Compose 语义校验见 cli/modules/compose/init.py 与 cli/modules/compose/validate.py也支持validate --path 目录直接校验本地未入库的模板目录。当前格式与旧格式的差异当前运行时与旧示例的关键差异如下阅读网上旧教程时需特别留意维度当前格式旧格式已过时清单文件template.jsontemplate.yaml/template.yml渲染文件位置全部位于files/目录下仓库顶层散落的.j2文件Jinja 分隔符自定义变量 value 、块% if %、注释# #默认{{ }}、{% %}、{# #}现被拒绝版本元数据结构化可选的metadata.version对象顶层平铺的版本字段generate输出参数必须用--output位置式输出参数关于新清单结构的完整说明slug规范化规则、metadata.version字段语义、变量声明强制要求、自定义分隔符与files/渲染行为参见 .wiki/Core-Concepts-Templates.md变量清单结构参见 .wiki/Core-Concepts-Variables.md默认值概念参见 .wiki/Core-Concepts-Defaults.md。以仓库内 library/compose/nginx/template.yaml 为例注意该示例仍为旧格式仅用于对照变量分组概念模板通常按general、ports、traefik、network、swarm等分组声明变量每个变量可带typestr/int/bool/enum、default、description与 enum 的options。新格式将这些变量声明统一放入template.json的variables数组渲染文件置于files/下。小结一条完整的工作流从零开始到产出可部署配置典型路径如下# 1. 安装 curl -fsSL https://raw.githubusercontent.com/christianlempa/boilerplates/main/scripts/install.sh | bash # 2. 同步模板库 boilerplates repo update # 3. 浏览与检视 boilerplates compose list boilerplates compose search nginx boilerplates compose show nginx # 4. 设置常用默认值 boilerplates compose defaults set container_timezoneEurope/Berlin boilerplates compose defaults set restart_policyunless-stopped # 5. 预览并生成 boilerplates compose generate nginx --dry-run --show-files boilerplates compose generate nginx --output ./my-nginx \ --var service_namemy-nginx --no-interactive # 6. 校验可选模板作者常用 boilerplates compose validate nginx每一步对应的实现均可在此仓库中追踪安装逻辑在 scripts/install.shCLI 入口与模块注册在 cli/main.py库同步在 cli/core/repo.py模板的 list/search/show/validate/generate 命令在 cli/core/module/base_commands.py默认值管理在 cli/core/module/config_commands.py。按此流程你即可把社区维护的可复用模板转成属于你自己的可配置基础设施工作负载。【免费下载链接】boilerplatesCreate reusable templates and turn them into configurable workloads for homelabs and self-hosted infrastructure. Free and Open-Source.项目地址: https://gitcode.com/GitHub_Trending/bo/boilerplates创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考