Puppet环境异常求助：‘none’环境找不到及环境不匹配问题排查

我之前帮团队排查过几乎一模一样的问题，分享下实际遇到的场景和代码层面的定位方向：

首先先明确你遇到的核心错误日志：

Jun 22 19:26:30 node puppet-agent[12345]: Local environment: "production" doesn't match server specified environment "none", restarting agent run with environment "none"
Jun 22 19:44:55 node INFO [puppet-server] Puppet Not Found: Could not find environment 'none'

类似问题的常见触发场景 #

这种问题通常不是表面配置文件写错，而是环境协商的隐式逻辑出了问题，常见的几个原因：

• Agent端环境被隐式覆盖：即使你在puppet.conf里设置了environment=production，如果有外部脚本、自定义Facter变量或者错误的ENC（外部节点分类器）配置，可能会在agent发起请求时覆盖环境参数，导致传递给server的环境为空，server fallback到none。
• Server端环境解析分支异常：当server处理agent请求时，如果节点名称不存在、ENC返回空环境值，或者环境加载的缓存逻辑出错（比如environment_timeout设置导致旧缓存未更新），会触发代码里的默认分支，返回none作为环境标识。
• 请求参数被中间件干扰：如果agent和server之间有反向代理，代理规则可能意外清空了请求中的环境参数，导致server无法识别正确的环境。

代码层面的定位方向 #

如果你要深入代码排查，可以重点关注这几个模块（基于Puppet 6.x/7.x开源版本）：

• Agent端环境协商逻辑：lib/puppet/agent.rb中的run方法会处理初始环境设置，lib/puppet/network/http/api/v1/indirector/catalog/master.rb负责和server协商环境，这里会对比本地环境和server返回的环境，触发重启逻辑。
• Server端环境加载与验证：lib/puppet/server/environment.rb是环境加载的核心，其中的find方法会尝试匹配请求的环境，如果找不到会返回nil，后续逻辑可能将其转为none；另外lib/puppet/indirector/catalog/compiler.rb中会根据请求参数确定最终使用的环境，这里的分支逻辑是重点。
• ENC相关处理：如果启用了外部节点分类器，lib/puppet/node/enc.rb会处理ENC的返回结果，如果返回的环境字段为空或无效，server会进入默认分支，返回none。
• 请求参数解析：lib/puppet/network/http/server.rb中的请求解析部分，检查是否正确从请求中提取environment参数，有没有默认值被错误设置为none的情况。

额外排查建议 #

• 强制指定环境运行agent：执行puppet agent --test --environment production，看是否还会出现切换到none的情况，验证是否是环境参数被动态覆盖。
• 检查ENC输出：如果用了ENC，手动执行ENC脚本，查看返回的JSON中environment字段是否正确，有没有返回空值。
• 过滤server调试日志：搜索environment关键词，跟踪请求到达后server是如何解析环境的，看是否有分支逻辑触发了none的返回。

内容的提问来源于stack exchange，提问作者diesello