Puppet 8 在现代 Linux 上必须通过官方仓库指定版本分支安装，否则因官方源移除主包或版本混装导致 puppetserver 启动失败、agent 卡在 TLS 握手或证书验证异常；需确保时间同步、FQDN 主机名、一致的 certname/server 域名、正确 modulepath 和唯一配置路径 /etc/puppetlabs/puppet/puppet.conf。
Puppet 8 在现代 Linux（如 RHEL 8+/CentOS Stream 8+、Ubuntu 22.04+）上不能直接用系统包安装，必须走官方仓库 + 明确版本分支，否则不是装不上，就是装错版本导致 puppetserver 启动失败或 puppet agent -t 卡死。
为什么 puppet agent -t 一直卡在 “Applying configuration version”
这不是网络延迟，而是 TLS 握手失败的典型表现。Puppet 的 SSL 验证比普通 HTTPS 严格得多：agent 请求时用的 certname（默认是 hostname -f）、server 配置值、以及 master 签发的证书 CN 必须完全一致（包括大小写和 FQDN 形式）。
- 运行
puppet config print certname和puppet config print server，确认输出是类似node01.example.com和puppetmaster.example.com这样的完整域名，而不是localhost或 IP - 在 master 上执行
puppet cert list --all | grep node01，如果没输出，说明证书根本没被签发或已过期 - 检查 master 的证书 CN：
openssl x509 -in /etc/puppetlabs/puppet/ssl/certs/puppetmaster.example.com.pem -text -noout | grep "Subject:"，确保 CN 匹配server值 - 别用
127.0.0.1或localhost当server—— 即使本地测试，也要设 hosts 让puppetmaster.local解析到 127.0.0.1，并用该域名配置
怎么让 puppet apply 正确加载自定义模块
模块找不到（Could not find class xxx）几乎全是路径或命名问题，跟语法无关。Puppet 8 默认只查两个位置：/etc/puppetlabs/code/environments/production/modules 和当前工作目录下的 modules/ 子目录。
Linux 安全审计工具，检查 SSH 配置、开放/监听端口、防火墙规则（ufw/iptables/nftables）、失败登录尝试、sudoers 权限...
- 先看 Puppet 实际认的路径：
puppet config print modulepath，输出类似/etc/puppetlabs/code/environments/production/modules:/opt/puppetlabs/puppet/modules - 把模块放进第一个路径（如
/etc/puppetlabs/code/environments/production/modules/nginx），而不是扔进/etc/puppetlabs/code/modules/（这个路径 Puppet 8 不扫） - 模块目录名必须小写、无下划线、与 class 名完全一致：想用
class nginx，目录就得叫nginx，且里面必须有manifests/init.pp - 临时调试更推荐显式指定：
puppet apply --modulepath ./my_modules site.pp，绕过全局配置干扰
puppetserver 启动失败常见定位点
报 Unit not found 或 Java 类找不到，基本锁定为版本混装或环境残留。Puppet 8 的 puppetserver 依赖同版本的 puppet-agent 提供的 Ruby 环境和核心库，不能混用。
- 确认命令来源一致：
which puppet应该是/opt/puppetlabs/bin/puppet；puppet --version和/opt/puppetlabs/bin/puppet --version输出必须都是8.x - 检查是否残留旧版服务：
systemctl list-unit-files | grep -E "(puppet|puppetmaster)"，禁用并删掉puppetmaster.service（Puppet 6+ 已废弃） - 关键配置文件只有唯一位置：
/etc/puppetlabs/puppet/puppet.conf—— 别去改/etc/puppet/puppet.conf，那个是 Puppet 3/4 时代的路径，server 根本不读 - 首次启动前务必运行
/opt/puppetlabs/bin/puppet infrastructure configure（Puppet 8 新增），它会生成必要证书和目录结构
真正容易被忽略的是时间同步和主机名：puppetserver 启动、证书签发、agent 连接，三者都依赖准确的系统时间（误差 >5 分钟就可能拒签）和合法的 FQDN 主机名（hostname -f 必须返回带点的全称）。这两项不达标，后面所有操作都是在填同一个坑。
