企业官网建设流程全解析

简介：这份资源面向需要搭建 Puppet 自动化运维体系的工程师与运维学习者，围绕 Puppet Master、The Foreman 与 smart-proxy 的安装和管理展开，帮助解决多角色 Puppet 架构部署与升级控制问题。资源包共 60 个文件，约 64KB，以 22 个 pp 清单、14 个 erb 模板、8 个 rb 脚本为主，辅以 yml、json、Gemfile、Rakefile 等配置与依赖文件，覆盖 manifests、templates、spec、tests 等目录，结构清晰便于按模块查阅。其特色在于每个软件栈均通过 RVM、git 仓库与 gems 配置，而非依赖 yum 包和系统默认 Ruby，从而提升模块化程度并便于掌握 Ruby 安全补丁。模块还区分 aio、catalog、ca 三种 Puppet Master 角色，适合希望精细控制升级流程、规避系统 Ruby 限制的读者参考。目前已有 133 人学习下载。

1. 从一台干净的机器说起：puppet_stack 到底装了什么

上周帮一个朋友收拾他实验室的烂摊子，三台机器上分别跑着 Puppet Master、Foreman 和 smart-proxy，版本各不相同，证书签得乱七八糟，agent 连上来就报 400。他问我能不能重装一套干净的，我说可以，但得先想清楚 puppet_stack 这套东西到底装了什么。puppet_stack 不是一个单独的软件包，它是一套把 Puppet Master、The Foreman 和 smart-proxy 串起来的部署方案，通常用 Puppet 自己的模块来管理这三者的安装和配置。装不好会怎样？最直接的就是证书链对不上，Foreman 看不到 Puppet 的节点数据，smart-proxy 连不上 Foreman，整个链路断在中间。这套环境适合谁？适合需要集中管理几十台以上服务器、又不想手动维护节点清单的运维。如果你只有两三台机器，说实话没必要上这套，但如果你正在被节点信息散落各处、证书过期没人管的问题折磨，那往下看。

2. 装之前先把版本和依赖钉死：Puppet 7 与 Foreman 3.x 的搭配

2.1 版本选择：为什么我选 Puppet 7 而不是 8

Puppet 8 已经出来一段时间了，但我在生产环境里还是倾向 Puppet 7。原因很实际：Foreman 3.x 对 Puppet 7 的支持最成熟，社区模块的兼容性也最好。Puppet 8 改了 Ruby 版本要求，很多老模块还没跟上，你装到一半发现某个依赖模块报语法错误，那种感觉就像开车上高速发现油箱漏了。我一般会这样定版本：Puppet 7.28 或更高的 7.x 小版本，Foreman 3.9 或 3.10，smart-proxy 跟着 Foreman 的版本走。操作系统选 Rocky Linux 8 或 AlmaLinux 8，这两个是 Foreman 官方文档里验证最充分的。Ubuntu 22.04 也能跑，但包管理的细节差异会让你在排错时多花一两个小时。

2.2 依赖清单：装之前先跑一遍检查

在动手之前，先把这些依赖确认一遍。缺一个，后面就可能卡住。

# 检查系统版本和基础依赖 cat /etc/os-release | grep -E "^(NAME|VERSION_ID)" # 确认主机名和 DNS 解析正常，Puppet 证书里会写死主机名 hostname -f # 检查时间同步，证书对时间敏感 timedatectl status | grep "System clock synchronized" # 确认防火墙和 SELinux 状态，后面要放行端口 systemctl status firewalld getenforce

这几条命令看起来简单，但每一条背后都有血泪经验。hostname -f必须返回完整域名，如果只返回短名，Puppet 签出来的证书里 CN 就是短名，Foreman 那边配置的 URL 如果写的是完整域名，证书校验直接失败。时间同步不用多说，证书有效期校验差几分钟就报错。SELinux 我建议先设成 permissive，装完再调策略，否则 Foreman 的安装脚本可能因为权限问题中断。

2.3 仓库配置：Puppet 和 Foreman 的源怎么加

Puppet 7 的官方源和 Foreman 的源要分开加，顺序也有讲究。先加 Puppet 源，再装 Puppet agent，最后加 Foreman 源。

# 添加 Puppet 7 仓库（以 Rocky Linux 8 为例） rpm -Uvh https://yum.puppet.com/puppet7-release-el-8.noarch.rpm # 安装 Puppet agent yum install -y puppet-agent # 把 puppet 命令加到 PATH echo 'export PATH=$PATH:/opt/puppetlabs/bin' >> /etc/profile source /etc/profile # 验证 puppet 版本 puppet --version

这里有个细节：Puppet 装完后命令在/opt/puppetlabs/bin下面，不手动加 PATH 的话，后面跑puppet apply会提示找不到命令。我见过有人以为是安装失败，重装了三遍。加完 PATH 后puppet --version应该输出 7.x 的版本号，如果报错，检查 rpm 包是否真的装上了。

# 添加 Foreman 3.10 仓库 yum install -y https://yum.theforeman.org/releases/3.10/el8/x86_64/foreman-release.rpm # 安装 foreman-installer yum install -y foreman-installer

Foreman 的仓库地址里版本号要和你选的版本对上，3.10 就写 3.10，别写 3.9 然后指望它自动升级。foreman-installer是后面一键部署的核心工具，它把 Puppet Master、Foreman 和 smart-proxy 的安装串在一起，省去手动配每个组件的麻烦。

3. 用 foreman-installer 一键拉起 Puppet Master 和 Foreman

3.1 安装命令与参数拆解

foreman-installer支持交互式和非交互式两种模式。我第一次装的时候用了交互式，结果它问了我二十几个问题，有些我根本不确定该选什么。后来我改成非交互式，把所有参数写在命令行里，一次跑完，出问题也好回溯。

# 非交互式安装，关键参数一次给全 foreman-installer \ --foreman-initial-admin-username admin \ --foreman-initial-admin-password 'YourStrongPass123' \ --foreman-proxy-dns false \ --foreman-proxy-dhcp false \ --foreman-proxy-tftp false \ --enable-foreman-proxy \ --foreman-proxy-foreman-base-url https://puppet.example.lab \ --puppet-server true \ --puppet-server-foreman-url https://puppet.example.lab

逐条说。--foreman-initial-admin-username和--foreman-initial-admin-password是 Foreman 的初始管理员账号，装完后用这个登录 Web 界面。密码里如果有特殊字符，用单引号包起来，否则 shell 会解释。--foreman-proxy-dns false这些是关掉 smart-proxy 的 DNS、DHCP、TFTP 功能，因为我的场景里不需要它管网络服务，只需要它转发 Puppet 的证书请求和事实数据。如果你确实需要 Foreman 管 DNS，就把对应的改成 true，但配置会复杂不少。--enable-foreman-proxy是显式启用 smart-proxy，有些版本默认不装。--foreman-proxy-foreman-base-url和--puppet-server-foreman-url都指向同一个地址，就是这台机器的完整域名，必须和hostname -f的输出一致。

3.2 安装过程看什么：日志和进度

命令跑起来后，终端会输出一堆 Puppet 的 apply 日志。不用逐行看，但有几个关键节点要留意。

# 安装过程中另开一个终端，跟踪日志 tail -f /var/log/foreman-installer/foreman-installer.log

日志里出现Success!和* Foreman is running at https://puppet.example.lab就说明主流程走完了。如果卡在某个Exec资源上超过两分钟，大概率是网络问题或者证书生成卡住了。我遇到过一次卡在puppet cert generate上，原因是/etc/puppetlabs/puppet/ssl目录权限不对，Puppet 用户写不进去。解决办法是删掉那个目录重新跑安装，但删之前确认里面没有已经签发的证书。

3.3 装完后的目录结构：知道东西在哪

安装完成后，几个关键目录得心里有数。

这些路径记不住没关系，但排错的时候你得知道去哪个目录找日志。比如 Foreman 报 500 错误，先看/var/log/foreman/production.log；Puppet agent 连不上 Master，先看/var/log/puppetlabs/puppetserver/puppetserver.log。

4. 配置 smart-proxy 与 Puppet Master 的证书信任链

4.1 证书签发：smart-proxy 怎么拿到自己的证书

smart-proxy 和 Puppet Master 之间的通信靠证书。默认情况下，foreman-installer会帮 smart-proxy 生成证书并向 Puppet CA 申请签发。但如果你像我一样，Puppet Master 和 smart-proxy 装在同一台机器上，这一步通常是自动完成的。如果分开部署，就得手动签。

# 在 Puppet Master 上查看待签的证书请求 puppetserver ca list --all # 签发 smart-proxy 的证书（假设主机名是 proxy.example.lab） puppetserver ca sign --certname proxy.example.lab # 验证证书已签发 puppetserver ca list --all | grep proxy.example.lab

puppetserver ca list --all会列出所有证书请求和已签发的证书。如果 smart-proxy 的请求不在列表里，说明它还没向 Master 发起请求，检查 smart-proxy 的settings.yml里puppet_url是否指向了正确的 Master 地址。签发之后，smart-proxy 需要重启才能加载新证书。

4.2 smart-proxy 配置：settings.yml 里改什么

smart-proxy 的核心配置在/etc/foreman-proxy/settings.yml。这个文件里大部分配置在安装时已经写好了，但有几个地方我建议手动确认一遍。

# /etc/foreman-proxy/settings.yml 关键片段 :settings_directory: /etc/foreman-proxy/settings.d :ssl_certificate: /etc/foreman-proxy/ssl/certs/proxy.example.lab.pem :ssl_private_key: /etc/foreman-proxy/ssl/private/proxy.example.lab.key :ssl_ca_file: /etc/foreman-proxy/ssl/certs/ca.pem :foreman_url: https://puppet.example.lab :puppet_url: https://puppet.example.lab:8140

:ssl_certificate和:ssl_private_key的路径必须和实际文件位置一致。我见过有人从别的机器拷贝配置，路径没改，smart-proxy 启动时报SSL_CTX_use_PrivateKey_file失败。:foreman_url是 Foreman 的地址，:puppet_url是 Puppet Master 的地址，端口 8140 是 Puppet Server 的默认端口，如果改过就要跟着改。改完配置后重启服务：

systemctl restart foreman-proxy systemctl status foreman-proxy

状态显示active (running)才算正常。如果启动失败，journalctl -u foreman-proxy -n 50看最近 50 行日志，通常能直接定位到是哪一行配置写错了。

4.3 在 Foreman 里注册 smart-proxy

smart-proxy 服务跑起来还不够，得在 Foreman 的 Web 界面里把它注册进去，否则 Foreman 不知道有这个代理存在。登录 Foreman，进入Infrastructure > Smart Proxies，点Create Smart Proxy，填上 smart-proxy 的 URL，通常是https://proxy.example.lab:8443。保存后 Foreman 会去连这个地址，如果证书信任链没问题，状态会显示为绿色。如果报SSL certificate verify failed，回到 4.1 检查证书是不是签给了正确的主机名。

5. 避坑与排查：装 puppet_stack 时最容易翻车的五件事

5.1 现象：Foreman 界面能打开，但 Puppet 节点列表是空的

原因通常是 Puppet Master 没有把节点数据上报给 Foreman。Puppet 7 需要装puppet-foreman插件才能上报事实和报告。检查/etc/puppetlabs/puppet/puppet.conf里有没有facts_terminus = foreman和reports = foreman。如果没有，手动加上然后重启 Puppet Server。另一个可能是 Foreman 的puppet_url配错了，在 Foreman 的Settings > Puppet里确认 URL 指向的是 Puppet Master 的 8140 端口。

5.2 现象：smart-proxy 启动时报Address already in use

smart-proxy 默认监听 8443 端口，如果这台机器上跑了别的 HTTPS 服务占用了这个端口，就会报这个错。ss -tlnp | grep 8443看是谁占的。如果是 Foreman 自己的 HTTPS 服务占了 443，那不冲突；但如果另一个服务占了 8443，要么改 smart-proxy 的端口，要么停掉那个服务。改端口的话，settings.yml里加一行:https_port: 8444，然后 Foreman 里注册的 URL 也要跟着改。

5.3 现象：Puppet agent 第一次跑报certificate verify failed

这是证书链的问题。agent 不信任 Master 的 CA 证书。检查 agent 的/etc/puppetlabs/puppet/puppet.conf里ca_server是否指向了 Master。如果指向正确，把 agent 上的/etc/puppetlabs/puppet/ssl目录删掉，重新跑puppet agent -t，它会重新生成请求并向 Master 申请签发。在 Master 上用puppetserver ca sign --certname agent.example.lab签发。注意，删 ssl 目录之前确认 agent 上没有其他依赖这个证书的服务。

5.4 现象：foreman-installer 跑完后 Foreman 报 500 错误

先看/var/log/foreman/production.log。最常见的原因是数据库迁移没跑完。foreman-installer会在安装过程中执行foreman-rake db:migrate，如果这一步因为数据库连接问题中断了，Foreman 启动后就会报 500。手动补跑：

foreman-rake db:migrate foreman-rake db:seed

db:seed是初始化默认角色和权限的，如果之前没跑过，不跑这个登录进去什么权限都没有。跑完后重启foreman和foreman-proxy服务。

5.5 现象：Puppet Server 启动慢，日志里大量JRuby相关警告

Puppet Server 跑在 JRuby 上，默认内存给得比较保守。如果机器内存够（8G 以上），可以在/etc/sysconfig/puppetserver里把JAVA_ARGS的-Xmx调到 2G 或 4G。改完重启 Puppet Server。这个不是致命问题，但启动慢会影响你排错的节奏，调大内存后启动时间能从两三分钟降到三十秒左右。

6. 装完怎么验证：从 agent 跑通到 Foreman 看到节点

装完不验证，等于没装。我一般按这个顺序走一遍，每一步都确认通过了再往下。

第一步，在 Puppet Master 上确认服务状态。

puppetserver ca list --all systemctl status puppetserver systemctl status foreman systemctl status foreman-proxy

三个服务都应该是active (running)。puppetserver ca list --all至少能看到 Master 自己的证书。

第二步，找一台测试机器装 Puppet agent，跑一次。

# 在测试机器上 yum install -y puppet-agent echo 'export PATH=$PATH:/opt/puppetlabs/bin' >> /etc/profile source /etc/profile puppet agent -t --server puppet.example.lab

第一次跑会报no certificate found，这是正常的。去 Master 上签发：

puppetserver ca sign --certname test-node.example.lab

然后回到测试机器再跑一次puppet agent -t，这次应该能看到Notice: Applied catalog之类的输出，说明 agent 和 Master 的通信完全打通了。

第三步，登录 Foreman Web 界面，进Hosts > All Hosts，看测试节点有没有出现。如果出现了，点进去看Facts标签页，应该能看到 CPU、内存、操作系统等事实数据。如果节点没出现，回 5.1 检查facts_terminus和reports配置。

第四步，在 Foreman 里进Infrastructure > Smart Proxies，确认 smart-proxy 的状态是绿色。点进去看Puppet和Puppet CA两个功能是不是都启用了。如果Puppet CA显示未启用，检查 smart-proxy 的settings.d/puppetca.yml里:enabled是不是true。

第五步，跑一个最简单的 Puppet 清单，验证配置下发。

# /etc/puppetlabs/code/environments/production/manifests/site.pp node 'test-node.example.lab' { file { '/tmp/puppet_test.txt': ensure => file, content => "puppet_stack is working\n", mode => '0644', } }

在测试机器上再跑一次puppet agent -t，然后cat /tmp/puppet_test.txt，看到内容就说明整条链路从 Foreman 到 Puppet Master 到 agent 全部通了。

这套验证流程我每次装完都会走一遍，哪怕是在测试环境里。有一次我偷懒跳过了第五步，结果上线后发现 Foreman 里配的环境变量根本没下发到 agent，原因是environment参数在puppet.conf里写错了。从那以后我每次装完 puppet_stack，都强制走一遍从 agent 到 Foreman 的完整验证，不看到/tmp/puppet_test.txt里的那行字不算完。希望帮到你。

本文还有配套的精品资源，点击获取