Puppet 是一款经典的基础设施即代码工具，通常以 Linux 服务器作为 Puppet Server，而将 Windows Server 作为受管节点纳入统一配置管理体系，是企业混合环境中非常常见的做法。要在 Windows 上实现集中管控，第一步就是在目标机器上安装并配置 Puppet 代理（Puppet Agent）。本文将从准备工作、安装方式、配置要点和常见问题排查几个方面，完整讲解 Windows Server 上 Puppet 代理的部署过程。
一、安装前的准备工作
在动手安装之前，需要先确认几个前提条件。首先是操作系统版本，Puppet 官方对 Windows 的支持范围一般包括较新的 Windows Server 版本，具体支持列表以官方文档为准，安装前建议到官网核对当前 Puppet 版本是否支持你的系统。其次是网络连通性，Windows 节点必须能够访问 Puppet Server 的 8140 端口，这是 Puppet 通信的默认端口，可以在 PowerShell 中用 Test-NetConnection master.ippipp.com -Port 8140 测试连通性。
时间同步也非常关键。Puppet 的证书体系依赖系统时间，如果客户端与服务器时间偏差过大，证书校验会直接失败。建议将 Windows 节点的 NTP 配置指向与 Puppet Server 相同的时间源，可以通过 w32tm 命令或组策略统一配置。另外，节点的主机名和域名解析要正常，Puppet 证书是基于主机名的，若 DNS 或 hosts 文件解析不一致，后续签名和认证都会出问题。
最后准备好安装包。Puppet 官网提供 Windows 版 MSI 安装包，包含 puppet-agent 完整组件（Ruby 运行环境、Puppet、Facter 等）。如果目标机器较多，也可以提前下载到内网文件服务器，方便批量分发。
二、安装 Puppet 代理的两种方式
第一种是图形化安装。双击 MSI 安装包，按照向导提示逐步执行，在安装过程中需要填写 Puppet Master 的主机名，例如 master.ippipp.com，向导会自动写入配置文件。安装完成后，程序默认安装在 C:\Program Files\Puppet Labs\Puppet 目录下，实例数据（证书、日志、缓存等）则存放在 C:\ProgramData\PuppetLabs\puppet\etc 和 C:\ProgramData\PuppetLabs\puppet\var 中。要注意 ProgramData 是隐藏目录，在资源管理器中需要开启显示隐藏文件才能看到。
第二种是命令行静默安装，适合批量部署场景。以管理员身份打开 PowerShell，执行类似下面的命令：
msiexec /qn /i puppet-agent-x64-latest.msi PUPPET_MASTER_SERVER=master.ippipp.com
其中 PUPPET_MASTER_SERVER 指定服务器地址，还可以通过 INSTALLDIR 参数自定义安装目录，例如 INSTALLDIR="C:\Puppet"。静默安装的退出码为 0 表示成功，脚本化部署时建议检查返回值。安装完成后，安装程序会自动创建 puppet 和 mcollective 两个 Windows 服务，其中 puppet 服务负责代理的周期性运行。
三、核心配置与证书签名
安装完成后，主配置文件位于 C:\ProgramData\PuppetLabs\puppet\etc\puppet.conf。可以用文本编辑器直接修改，也可以使用 puppet config set 命令，例如：
& "C:\Program Files\Puppet Labs\Puppet\bin\puppet.bat" config set server master.ippipp.com --section main & "C:\Program Files\Puppet Labs\Puppet\bin\puppet.bat" config set runinterval 1800 --section agent
server 指定 Puppet Server 地址，runinterval 控制代理默认每多少秒执行一次目录同步，默认值是 1800 秒即半小时，可按需调整。注意在 PowerShell 中调用 puppet 命令时要使用 .bat 完整路径或先把 bin 目录加入 Path 环境变量，因为 PowerShell 默认不会自动解析 bat 文件。
配置完成后，代理首次运行时会向服务器发起证书签名请求。手动触发一次代理运行：
& "C:\Program Files\Puppet Labs\Puppet\bin\puppet.bat" agent --test
此时命令会提示证书待签名，需要在 Puppet Server 上执行 puppetserver ca sign --certname 节点名 完成签名（旧版本使用 puppet cert sign）。签名通过后，再次运行代理即可正常获取目录并执行配置。也可以在服务器端开启自动签名策略，简化大规模部署流程，但要评估安全风险。
四、服务验证与常见问题排查
验证安装是否成功，可以先检查服务状态：Get-Service puppet 应显示 Running。然后执行 puppet agent --test，如果输出 Notice: Applied catalog in x.x seconds，说明代理与服务器通信、证书认证和目录应用全部正常。再看一眼日志目录 C:\ProgramData\PuppetLabs\puppet\var\log 下的日志文件，确认没有报错。
常见问题主要有几类。一是证书报错，比如 Certificate ... does not match，多数是主机名变更或重复安装导致证书残留，可以删除 C:\ProgramData\PuppetLabs\puppet\etc\ssl 目录后重新申请，同时在服务器端清理旧证书。二是连接超时，通常是防火墙拦截 8140 端口或 DNS 解析错误，用 Test-NetConnection 逐段排查。三是代理服务启动失败，可检查 Windows 事件查看器中的应用日志，以及确认服务账户权限是否正常。
对于大规模 Windows 环境，推荐将 MSI 包放在共享目录，通过组策略或脚本批量推送静默安装命令，配合 Puppet Server 的自动签名，实现新节点即装即管的自动化流程。日常运维中还应定期升级代理版本，保持与服务端版本兼容，并对 puppet.conf 做版本化管理，确保配置变更可追溯。通过以上步骤，Windows Server 节点就能稳定地纳入 Puppet 的统一配置管理体系中。
Puppet代理Windows Server自动化运维修改时间：2026-09-02 02:56:28