puppet apply 本地执行不生效因默认不加载puppetfile及模块依赖，--modulepath未配对时include静默失败；service资源在systemd系统需显式指定provider=>'systemd'并检查systemctl is-active；大文件同步应改用source+checksum=>'mtime'避免超时；agent连不上server先用openssl测试8140端口连通性。
为什么 puppet apply 本地执行不生效？
因为默认不会加载 Puppetfile 或模块自动依赖，且 --modulepath 没配对时，include 会静默失败。常见现象是资源声明没报错，但目标文件/服务完全没变化。
- 用
puppet apply --modulepath ./modules ./site.pp显式指定路径，别依赖当前目录或/etc/puppetlabs/code/modules -
site.pp里避免写include stdlib这类依赖——除非你确认stdlib真在--modulepath下的某个子目录里 - 加
--debug看实际加载了哪些模块，重点搜Loaded module和Could not find class
如何让 service 资源在 systemd 系统上可靠重启？
Linux 发行版混用 SysVinit / systemd 后，service { 'nginx': ensure => running, enable => true } 容易卡在“已启动但未监听端口”状态，本质是 Puppet 不感知 unit 文件重载或依赖顺序。
- 强制用
systemd提供者：service { 'nginx': provider => 'systemd', ... } - 若服务依赖其他 unit（比如
network-online.target），别指望 Puppet 自动处理，得在模块里用Exec手动systemctl daemon-reload或写require关系 - 检查
systemctl is-active nginx返回值是否为active，而非只看ps aux | grep nginx——Puppet 的ensure => running依据的是前者
file 资源同步大文件时卡住或超时？
默认 file 类型走本地拷贝 + checksum => 'md5' 校验，但大文件（>100MB）在 agent 内存受限或磁盘 I/O 慢时，会触发 Ruby GC 停顿或超时中断。
- 改用
source => 'puppet:///modules/mymodule/large.tar.gz'+checksum => 'mtime'，跳过内容校验，靠时间戳判断变更 - 如果必须校验，把
checksum改成'sha256'并确保 Puppet Server 开启use_cache_for_modules = true，避免每次重算 - 别在
file里设backup => '.puppet-bak'同步大文件——备份会双倍占用磁盘，且无压缩
agent 启动后反复报告 “Could not retrieve catalog from remote server”
不是证书问题就是 DNS 或防火墙堵了 puppetserver 的 8140 端口，但错误日志常被掩盖在 curl 超时或 TLS 握手失败之后。
- 先在 agent 上跑
openssl s_client -connect puppet.example.com:8140 -servername puppet.example.com，看是否能连通并拿到证书 - 确认
/etc/puppetlabs/puppet/puppet.conf里[agent] server = puppet.example.com的域名能被 agent 正确解析，别用 localhost 或未配置反向 DNS 的 IP - Server 端检查
puppetserver gem list | grep jruby-kafka——如果用了旧版puppetserver（webserver.conf
真正麻烦的是跨网络策略和证书生命周期管理——比如 agent 证书过期后，puppet cert clean 不等于自动重签，得配合 csr_attributes.yaml 和 autosign 配置，否则下次 run 还是卡在 handshake。
