现代Linux发行版官方仓库已移除Puppet主包，需添加官方APT/YUM源并指定puppet7或puppet8分支；puppetserver依赖puppet-agent，必须先装agent；版本不一致、配置路径错误、SSL证书未签发是常见失败原因。
为什么直接装 puppet 包在现代 Linux 上大概率失败
因为主流发行版（Ubuntu 22.04+、CentOS 8+、Debian 11+）的官方仓库已移除 puppet 主包，只保留极旧版本或完全不提供。你执行 apt install puppet 或 yum install puppet 会报“未找到包”或装上 5.x 这类早已 EOL 的版本，连 puppetserver 都启动不了。
正确路径是使用 Puppet 官方 APT/YUM 仓库，且必须指定版本分支（如 puppet7 或 puppet8），否则默认源指向废弃通道。
- Ubuntu/Debian：先导入 GPG key，再添加
https://apt.puppet.com源，并在/etc/apt/sources.list.d/puppet.list中明确写入deb https://apt.puppet.com focal-puppet7 main（focal 对应 20.04；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） - 跳过
puppet-agent单机模式直接装puppetserver？不行——它依赖puppet-agent提供的核心库，必须先装 agent 再装 server
puppetserver 启动失败常见报错和定位方法
最典型的是 Failed to start puppetserver.service: Unit not found 或日志里反复出现 java.lang.ClassNotFoundException: puppetlabs.trapperkeeper.services.metrics.metrics-service。这基本说明版本混装了：比如装了 puppet8 的 server，但本地 puppet 命令却是系统残留的 5.x。
验证方式很简单：
- 运行
puppet --version和/opt/puppetlabs/bin/puppet --version，两者必须一致（都显示 8.x） - 检查
systemctl list-unit-files | grep puppet，确认启用的是puppetserver.service而非已废弃的puppetmaster.service - 关键配置路径固定为
/etc/puppetlabs/puppet/puppet.conf，别去改/etc/puppet/puppet.conf（那是旧版位置，server 根本不读）
写第一个 site.pp 时变量作用域和语法陷阱
新手常把 Hiera 数据和 class 参数写反，或者误用 include 导致重复声明。Puppet 7+ 默认启用 strict_variables = true，任何未定义变量都会直接报错退出，不会静默 fallback。
一个能跑通的最小 /etc/puppetlabs/code/environments/production/manifests/site.pp 应该这样写：
node 'web01.example.com' {
$web_port = 8080
class { 'nginx':
package_ensure => 'present',
service_ensure => 'running',
}
file { '/var/www/html/index.html':
ensure => file,
content => "Hello from Puppet on ${facts['hostname']}\n",
mode => '0644',
}
}
-
node块内定义的变量（如$web_port）不能被class内部直接访问，必须显式传参或用 Hiera 绑定 -
content里插值必须用${facts['hostname']}，不是$::hostname（后者是旧事实名，已弃用） - 别用
include nginx—— 它无法传参；要用class { 'nginx': ... }或contain+ 参数化 class
Agent 端连不上 Server 的三个真实原因
执行 puppet agent -t 卡在 “Getting initial certificate” 或报 SSL_connect returned=1 errno=0 state=error: certificate verify failed，通常不是网络不通，而是证书链断了。
- Agent 首次运行时生成 CSR，但 Server 端没执行
puppetserver ca sign --all或只签了部分节点名（比如签了web01却没签web01.example.com） - Agent 的
/etc/puppetlabs/puppet/puppet.conf里server值写成 IP 而非 Server 的 FQDN，导致证书 CN 不匹配 - Server 时间比 Agent 快/慢超过 5 分钟，SSL 握手直接拒绝（
date -R对两边时间）
证书问题没法绕过，必须严格对齐域名、时间、签名流程。哪怕只是临时测试，也得走完 CA 签发这一步——没有“跳过 SSL”的安全选项。
