DevOps配置管理运维【免费下载链接】pyinfra pyinfra turns Python code into shell commands and runs them on your servers. Execute ad-hoc commands and write declarative operations. Target SSH servers, local machine and Docker containers. Fast and scales from one server to thousands.项目地址https://gitcode.com/gh_mirrors/py/pyinfra点击查看免费下载导读pyinfra 是一个将 Python 代码转换为 shell 命令并在远端服务器上执行的自动化工具支持 SSH 服务器、本机与 Docker 容器等多种目标。本文基于 docs/cli.md 与 src/pyinfra_cli 源码系统讲解 pyinfra 命令行工具的全部用法从 inventory 与 operations 的组合方式、五类 CLI 子命令deploy / 单操作 / exec / fact / debug-inventory、verbosity 与重试选项到 inventory 的--limit/--exclude过滤、--json机器可读输出与 shell 自动补全。读完本文你将能够不看文档也能熟练地用一条条 pyinfra 命令完成批量安装软件、管理服务、调试分布式应用并将 pyinfra 接入 CI 与自动化脚本。CLI 参数与选项总览pyinfra 的 CLI 设计围绕两个核心概念展开inventory主机清单与operations操作。正如 getting-started 所述pyinfra 需要一个 inventory 来告诉它“操作哪些主机”再通过 operations 告诉它“要做什么”。命令行基本形态如下Usage: pyinfra [OPTIONS] INVENTORY OPERATIONS...INVENTORY 可以是三种形式之一一个 inventory 文件inventory.py一个主机名host.net逗号分隔的主机列表host-1.net,host-2.net,localOPERATIONS 支持五类子命令覆盖从“跑一个部署脚本”到“执行一条裸命令”的全场景# ① 运行一个或多个部署文件 pyinfra INVENTORY deploy_web.py [deploy_db.py]... # ② 直接运行单个内置操作 pyinfra INVENTORY server.user pyinfra home/home/pyinfra # ③ 在 inventory 上执行任意 shell 命令 pyinfra INVENTORY exec -- echo hello world # ④ 收集一个或多个 facts主机事实 pyinfra INVENTORY fact server.LinuxName [server.Users]... pyinfra INVENTORY fact files.File path/path/to/file... # ⑤ 调试打印inventory 的主机、分组与数据 pyinfra INVENTORY debug-inventory这些子命令的识别逻辑集中在 src/pyinfra_cli/cli.py 的_validate_operations中debug-inventory、fact、exec是保留字*.py结尾被视为部署文件带.的操作名则被解析为操作函数FUNC其余输入直接报CliError。从源码可以看出server.user pyinfra home/home/pyinfra这种写法会被get_func_and_args见 src/pyinfra_cli/commands.py解析成位置参数pyinfra与关键字参数home/home/pyinfra其中参数值经parse_cli_arg智能转换——true/false变为布尔、纯数字变为int、JSON 格式自动解析见 src/pyinfra_cli/util.py。注意--之后的所有内容会原样透传给远端主机不会被 pyinfra 解析这是exec子命令的关键约定。Verbosity 输出级别默认情况下 pyinfra 只打印高层信息如“本主机已连接”“某操作已开始”可用-v逐级提高详细程度级别输出内容默认连接、操作开始/结果等高层信息-v额外打印收集到的 facts 与 noop 信息如“软件包 X 已安装跳过”-vv在上述基础上额外打印发送到远端主机的 shell 输入-vvv在上述基础上额外打印远端主机的 shell 输出verbosity 在 cli.py 的_set_verbosity中实现-v开启print_fact_info/print_noop_info-vv追加print_input/print_fact_input-vvv再追加print_output/print_fact_output。注意命令行里verbose被声明为可重复的CountFlag每个-v追加一个True见 cli.py所以-vvv等价于-v -v -v。Retry 重试选项pyinfra 支持通过 CLI 选项自动重试失败的操作--retry N失败操作最多重试 N 次默认 0即不重试--retry-delay N两次重试之间等待 N 秒默认 5# 失败操作最多重试 3 次使用默认的 5 秒间隔 pyinfra inventory.py deploy.py --retry 3 # 使用自定义重试间隔 pyinfra inventory.py deploy.py --retry 2 --retry-delay 10底层实现上--retry/--retry-delay会写入 src/pyinfra/api/config.py 的Config.RETRY与Config.RETRY_DELAY再通过 src/pyinfra/api/operations.py 注入到每个操作的全局参数_retries与_retry_delay中最终在_run_host_op的while retry_attempt retries循环内按需重新执行命令。除 CLI 外单个操作还可以在调用时使用_retries、_retry_delay与_retry_until做更细粒度的按操作重试控制定义见 src/pyinfra/api/arguments.py_retry_until甚至可以传入一个回调函数根据命令输出决定是否继续重试。Inventory命令行直接指定或文件定义pyinfra 的 inventory 既可以放在命令行里也可以定义在文件中两者都支持完整的连接器connectors与多主机。常用的 CLI 写法# 从文件加载 inventory 主机 pyinfra inventory.py ... # 通过 SSH 执行到两台服务器 pyinfra my-server.net,my-other-server.net ... # 通过子进程在本机执行 pyinfra local ... # 混合执行本机子进程 一台 SSH 服务器 pyinfra my-server.net,local ... # 针对一个 Docker 容器执行 pyinfra docker/fedora:43 ...inventory 的解析逻辑位于 src/pyinfra_cli/inventory.py 的make_inventory优先判定是否为文件/主机列表/连接器含,或其次尝试按 Python 模块属性加载支持module.function或module:function语法最后才回退到单主机名解析。如果你传入的 inventory 参数引用了一个可调用的 Python 函数pyinfra 会以“alpha”状态调用它并按其返回的{group: hosts}字典构建 inventory。对于 inventory 文件如inventory.py其中定义的每个顶层list或tuple变量都会成为一个主机组例如app_servers [ app-1.net, app-2.net, ] db_servers ([db-1.net, db-2.net, db-3.net], {})文件inventory.py加载后所有主机还会自动归入all组与以文件名命名的组inventory组。主机级数据通过元组(hostname, data_dict)附加例如(app-1.net, {install_postgres: False})。若直接传入逗号分隔的主机名非文件pyinfra 会把这些主机归入all组见 inventory.py。Limit运行时限定执行范围--limit用于在执行时过滤 inventory可以重复指定多次。匹配规则为按主机名精确匹配或按 glob 通配模式匹配也可以直接按组名匹配。# 只对 local 执行 pyinfra inventory.py deploy.py --limit local # 只对 app_servers 组内的主机执行 pyinfra inventory.py deploy.py --limit app_servers # 只对名称匹配 db* 的主机执行 pyinfra inventory.py deploy.py --limit db* # 组合多个 limit pyinfra inventory.py deploy.py --limit app_servers --limit db-1.net实现上_apply_inventory_limit见 cli.py会调用_get_inventory_pattern_matches先尝试按组名取主机inventory.get_group取不到再退回fnmatch(host.name, pattern)的 glob 匹配见 cli.py。所有--limit的结果会合并去重最终作为State的初始限定范围参与后续所有操作。Exclude运行时排除主机--exclude与--limit相反用于在执行时剔除主机同样支持精确主机名、glob 模式与组名也可重复指定# 对所有主机执行但排除 db-1.net pyinfra inventory.py deploy.py --exclude db-1.net # 排除 db_servers 组内的所有主机 pyinfra inventory.py deploy.py --exclude db_servers # 排除所有名称匹配 db* 的主机 pyinfra inventory.py deploy.py --exclude db* # 先 limit 后 exclude最终范围 (limit 集合) - (exclude 集合) pyinfra inventory.py deploy.py --limit app_servers --exclude app-2.net_apply_inventory_exclude见 cli.py先按相同规则算出被排除主机集合再从 limit 结果若无 limit 则为整个 inventory中扣除。如果某个--limit/--exclude模式没有匹配到任何主机pyinfra 会打印No host matches found for ... pattern警告。Ad-hoc 命令执行pyinfra execpyinfra exec允许你在远端主机上执行任意 shell 命令pyinfra inventory.py exec -- my_command_goes_here --some-argument关键约定--右侧的一切内容都会原样透传给远端目标因此--some-argument不会被 pyinfra 当作自身参数解析。在源码层面exec子命令会把--之后的命令字符串拼接后交给server.shell操作执行并强制开启state.print_output以实时回显远端输出见 cli.py。实战示例用 pyinfra 调试分布式服务pyinfra 的核心设计特性之一就是实时返回远端命令输出。结合多主机并发能力你可以同时流式查看 N 台远端服务的日志——这对于调试分布式服务极其顺手。例如对于一个大型 Elasticsearch 集群可以并行地流式跟踪每一实例的日志pyinfra inventory.py exec --sudo -- tail -f /var/log/elasticsearch/elasticsearch.log--sudo让命令以 sudo 权限执行tail -f的实时输出会随命令执行即时回显。因为 pyinfra 默认对所有主机并行执行gevent 并发模型见 src/pyinfra_cli/main.py一次命令即可让整个集群的日志在终端中并行滚动。Ad-hoc 执行内置操作除了裸命令pyinfra 还能在 CLI 上直接调用其任意内置操作格式为pyinfra INVENTORY module.operation keyvalue ...。操作参数中的keyvalue会被解析为关键字参数纯位置参数则按顺序传入参数类型自动转换布尔/整数/JSON。示例用 ad-hoc 命令管理软件包例如确保nginx已安装到远端服务器# Ubuntu / Debian 示例更新软件源后安装 pyinfra inventory.py apt.packages nginx updatetrue _sudotrue # Fedora 示例 pyinfra inventory2.py yum.packages nginx _sudotrue这里apt.packages/yum.packages是 pyinfra 内置的包管理操作分别位于 src/pyinfra/operations/apt.py 与 src/pyinfra/operations/yum.pyupdatetrue表示安装前先更新软件源_sudotrue是全局参数表示该操作通过 sudo 执行。pyinfra 的包操作是幂等的若 nginx 已安装且版本满足要求则显示“无变化”而非重复安装。示例用 ad-hoc 命令管理服务nginx 装好后可以用 pyinfra 控制nginx服务——这里确保它正在运行并设置为开机自启pyinfra inventory.py init.service nginx runningtrue enabledtrueinit.service是一个跨发行版的 init 系统操作自动适配 systemd / sysvinit / upstart 等见 src/pyinfra/operations/init/init.py 的调度逻辑runningtrue启动服务enabledtrue设置开机自启。该操作内部会收集目标主机对应的 init 系统 facts据此决定调用systemd.service、sysvinit.service还是upstart.service。示例用 ad-hoc 命令重启机器假设 inventory.py 中已启用 sudo可以用两种方式重启实例# 方式一使用 server.reboot() 操作可控制等待与超时 pyinfra inventory.py server.reboot reboot_timeout0 delay0 # 方式二直接用 exec 执行裸命令 pyinfra inventory.py exec -- rebootserver.reboot是 src/pyinfra/operations/server.py 中专门的重启操作reboot_timeout0表示不等待机器恢复、delay0表示不额外延迟而exec -- reboot则完全不经过 pyinfra 的状态管理直接把reboot交给远端 shell。额外调试选项需要更深入的诊断信息时可组合使用以下选项--debug打印 pyinfra 自身的 debug 日志--debug-facts生成操作后打印收集到的 facts 并退出--debug-operations生成操作后打印操作清单并退出在 cli.py 中--debug-facts/--debug-operations会在连接主机、加载 inventory 与生成操作之后、实际执行之前打印并调用_exit()。--debug会把日志级别降到DEBUG见_setup_log_level而--debug-all则连 pyinfra 依赖的第三方库日志也一并打开见 cli.py。JSON 输出面向脚本与 CI 的机器可读模式从较新版本开始pyinfra 支持--json参数将 stdout 上原本的 pretty printer 输出替换为机器可读的 JSON。该模式适用于debug-inventory、fact、--debug-operations、--dry以及常规部署方便把输出直接管道给其他工具# 以 JSON 形式导出解析后的 inventory pyinfra inventory.py debug-inventory --json # 以 JSON 形式收集一个 fact pyinfra inventory.py fact server.LinuxName --json # 以 JSON 形式展示部署将产生的变更不触碰主机 pyinfra inventory.py deploy.py --json # 同上显式 dry-run pyinfra inventory.py deploy.py --dry --json # 真正应用部署并输出结构化 plan results pyinfra inventory.py deploy.py --json --yes--json模式下输出的 payload 结构见 src/pyinfra_cli/prints.py包含plan按op_hash排序的操作计划每个操作带name、names、args、hosts_with_change、hosts_with_conditional_change有_if条件时归入后者results真实执行后每个操作在各主机上的success/error/no_change名单以及全局totals与failed_hosts列表dry-run 时results为nulldebug-inventory --json输出每个主机的name、groups与datafact --json输出{fact名: 值}字典--debug-operations --json则输出每个主机对应的操作及其元信息见 prints.py。非交互行为--json模式天然是非交互的以确保 stdout 始终是纯净 JSON--json本身不会自动应用变更不带--yes或带--dry时只打印提议变更并退出不触碰主机只有显式加--yes才会真正应用并输出结果。主机连接失败 / 操作失败的确认提示会被跳过非交互模式下直接失败退出而不是停下来询问是否继续。进度条 spinner 会被禁用等价于设置PYINFRA_PROGRESSoff。以上行为在 cli.py 与 cli.py 中实现JSON 模式下将PYINFRA_PROGRESS默认置为off并且不会安装_set_fail_prompts回调该回调在交互模式下会把失败主机转成“是否继续”的确认问题。同时--json与--yes相互独立源码注释明确强调“JSON run must be able to diff a host without mutating it”因此必须显式传--yes才会执行变更cli.py。对应的回归测试见 tests/test_cli/test_cli.py覆盖了--jsondebug-inventory、--jsonfact、--json--dry、--json-y、不带--yes时不应用变更等场景。注意部署代码里的交互式提示如input(...)仍然会阻塞所以使用--json时应避免这类写法。JSON 模式注意事项Inventory data 按原样序列化如果某主机携带了无法 JSON 序列化的值自定义 Python 对象、set、无编码器的datetime等命令会直接失败。因此计划消费 JSON 输出时请确保 inventory data 使用基本类型 / JSON 友好类型。json_encode的兜底编码器见 src/pyinfra_cli/util.py虽然能处理HostData、datetime、set、bytes、Path等但对任意 Python 对象仍会抛出TypeError。日志与错误仍写入 stderr如需 stdout 只含纯 JSON请重定向pyinfra ... --json 2/dev/null out.json。Shell 自动补全pyinfra 可以自动安装 shell 补全脚本pyinfra --install-completion它会自动探测当前 shell支持bash、zsh和fish然后生成补全脚本并安装到对应 shell 的默认位置。安装后可能需要重启 shell 或 source 一下 shell 配置文件才能生效。也可以指定目标 shell 或自定义输出路径# 只为 zsh 安装补全 pyinfra --install-completion --shell zsh # 安装 bash 补全到自定义路径 pyinfra --install-completion --shell bash --output ~/.pyinfra-complete.bash该能力由 src/pyinfra_cli/cli.py 中的app.register_install_completion_command()注册是 cyclopts 应用框架提供的标准补全安装命令支持通过--shell指定 shell 类型、--output指定安装路径。完整参数速查结合 cli.py 的 CLI 入口定义以下为本文涉及的常用参数及其含义参数作用默认值-v/-vv/-vvv逐级提升输出详细度关闭--dry不执行任何操作只做变更检测关闭--diff显示文本文件与模板的差异关闭-y/--yes跳过变更确认直接执行也支持环境变量PYINFRA_YES关闭--limit PATTERN限定执行主机主机名 / glob / 组名可重复全部--exclude PATTERN排除执行主机主机名 / glob / 组名可重复无--fail-percent N失败主机占比达到 N% 时提前中止无--data keyvalue覆盖 inventory 数据可重复无--group-data PATH加载额外组数据目录无--config FILE指定配置文件config.py--chdir PATH执行前切换工作目录无--sudo/--sudo-user U以 sudo / 指定用户 sudo 执行关闭--use-sudo-password/--same-sudo-password使用 sudo 密码 / 所有主机共用同一密码关闭--su-user U先 su 到指定用户再执行无--dzdo/--dzdo-user U以 dzdo / 指定用户 dzdo 执行关闭--shell-exe PATH指定远端 shell如sh、cmd、pssh--parallel N并行执行的操作数默认等于主机数0--no-wait主机间不等待直接连续执行操作关闭--serial逐主机串行执行关闭--retry N失败操作重试次数0--retry-delay N重试间隔秒5--ssh-user U/--ssh-port PSSH 用户 / 端口无--ssh-key FILE/--ssh-key-password PSSH 私钥 / 私钥密码无--ssh-password P/--ssh-password-promptSSH 密码 / 交互式询问密码无--debug/--debug-alldebug 日志含 / 不含第三方库关闭--debug-facts/--debug-operations打印 facts / 操作后退出关闭--jsonstdout 输出纯 JSON关闭--version/-h版本信息 / 帮助—这些 CLI 参数在_set_configcli.py中映射到 src/pyinfra/api/config.py 的Config类如SUDO、SUDO_USER、PARALLEL、RETRY、RETRY_DELAY、DIFF等并会先加载工作目录下的config.py若存在再应用命令行覆盖。注意 SSH 相关参数--ssh-user等会被塞入 inventory 的override_data从而覆盖主机级ssh_user等数据见 cli.py。小结pyinfra 的 CLI 是一个“既可 ad-hoc 又可声明式”的统一入口exec负责裸命令的实时批量执行module.operation语法让内置操作开箱即用且幂等deploy 文件则用于沉淀完整的声明式部署流程。配合--limit/--exclude做执行时的精确裁剪、-v*做逐级排障、--retry做故障自愈以及--json与脚本/CI 的无缝对接pyinfra 可以覆盖从单机调试到数千台服务器编排的绝大多数自动化场景。相关文档可进一步参考getting-started、inventory-data、connectors、operations、using-operations 与 deploy-process。赞分享DevOps配置管理运维【免费下载链接】pyinfra pyinfra turns Python code into shell commands and runs them on your servers. Execute ad-hoc commands and write declarative operations. Target SSH servers, local machine and Docker containers. Fast and scales from one server to thousands.项目地址https://gitcode.com/gh_mirrors/py/pyinfra点击查看免费下载相关推荐Dora CLI 完全参考指南从本地开发到分布式部署的命令行实战手册Dora CLI 完全参考指南从本地开发到分布式部署的命令行实战手册 DoraAI DoraDataflow Oriented Robotic Archi机器人人工智能ROS消息路由Cortex CLI 命令实战指南从 API 部署、集群管理到环境配置的完整命令手册Cortex CLI 命令实战指南从 API 部署、集群管理到环境配置的完整命令手册 Cortex 是面向大规模机器学习的生产级基础设施而 cortex C人工智能模型推理服务后端云原生MLOpsTabular.vim 与代码格式化如何完美集成到你的开发工作流Tabular.vim 与代码格式化如何完美集成到你的开发工作流 Tabular.vim 是一款强大的 Vim 文本对齐插件能够快速对齐代码、配置文件和文本上一篇react-native-amap3d 项目推荐下一篇4GB 显存运行 Qwen1.5-4B配置清单与实测参数创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考