现代linux系统直接apt install puppet或yum install puppet会失败，因官方仓库已移除主包，必须使用puppet官方apt/yum仓库并指定puppet7/puppet8分支；安装须先装puppet-agent再装puppetserver，配置路径为/etc/puppetlabs/puppet/puppet.conf，服务名为puppetserver.service，且需确保fqdn、ntp同步及webserver.conf监听地址正确。
直接装 puppet 包在现代 Linux（Ubuntu 22.04+、CentOS 8+/RHEL 8+、Debian 11+）上基本会失败——官方仓库早已移除主包，要么报“未找到”，要么装上 EOL 的 5.x 版本，连 puppetserver 都起不来。
为什么 apt install puppet 或 yum install puppet 总是失败
主流发行版已弃用系统源里的 Puppet，因为版本太老且不兼容 TLS 1.2+ 和新 Java 运行时。Puppet Inc. 要求你必须使用其官方 APT/YUM 仓库，并显式指定分支（如 puppet7 或 puppet8），否则默认通道指向废弃镜像。
- Ubuntu/Debian：必须先导入 GPG key，再添加
https://apt.puppet.com源，并在/etc/apt/sources.list.d/puppet.list中写死发行版代号 + 分支，例如deb https://apt.puppet.com jammy-puppet8 main（jammy = 22.04） - CentOS/RHEL 8+：用
dnf config-manager --add-repo https://yum.puppet.com/puppet8-release-el-8.noarch.rpm，后缀el-8必须和系统大版本一致；el-9系统不能混用el-8包 - 跳过
puppet-agent直接装puppetserver？不行——puppetserver依赖puppet-agent提供的 Ruby runtime 和核心库，必须先装 agent 再装 server
安装顺序和关键路径不能错
puppetserver 启动失败最常见的原因是路径错、服务名错、或残留旧版命令干扰。它不读 /etc/puppet/puppet.conf（那是 Puppet 5 时代的路径），只认 /etc/puppetlabs/puppet/puppet.conf；服务单元名是 puppetserver.service，不是已废弃的 puppetmaster.service。
- 先装 agent：
dnf install -y puppet-agent（RHEL/CentOS）或apt-get install -y puppet-agent（Debian/Ubuntu） - 再装 server：
dnf install -y puppetserver，启动前确认java -version输出的是 OpenJDK 11+（puppet8不支持 JDK 17+） - 改配置只动
/etc/puppetlabs/puppet/puppet.conf，[main] 段设certname = puppetmaster.example.com，[master] 段加dns_alt_names = puppetmaster,puppet - 启动命令必须是
systemctl enable --now puppetserver，不是puppet master命令（该命令在 7+ 已移除）
证书签发失败的典型表现和修复
Agent 连不上 Master，puppet agent -t 报 SSL_connect returned=1 errno=0 state=error: certificate verify failed，基本就是证书没签、主机名不是 FQDN、或时间不同步。
- Master 上执行
/opt/puppetlabs/bin/puppet cert list看有没有待签名条目；没有说明 Agent 根本没发起请求——检查 Agent 的server配置是否指向正确的 FQDN，且 DNS 可解析 - Agent 主机名必须是 FQDN（如
node01.example.com），不能是localhost或短名；用hostname -f验证 - 所有节点必须 NTP 同步，误差超过 5 分钟会导致证书被拒；运行
chronyd -q 'server time.nist.gov iburst'强制校准 - 签完证书后，Agent 首次运行必须用完整路径：
/opt/puppetlabs/bin/puppet agent -t，避免调到系统 PATH 里残留的旧版puppet
最易被忽略的是：puppetserver 默认监听 localhost:8140，如果 Master 绑定的是 127.0.0.1，外部 Agent 就连不上；必须改 /etc/puppetlabs/puppetserver/conf.d/webserver.conf 里的 host 为 0.0.0.0 或具体内网 IP，并开放防火墙端口 8140（不是 443）。
