企业官网建设流程全解析

简介：这份资源面向需要搭建 Puppet 自动化运维体系的工程师与运维学习者，围绕 Puppet Master、The Foreman 与 smart-proxy 的安装和管理展开，帮助解决多角色 Puppet 架构部署与升级控制的问题。模块将 Puppet Master 细分为一体机、目录服务器与 CA 服务器三种角色，并采用 RVM、git 仓库与 gems 方式配置软件栈，而非依赖系统 Ruby 与 yum 包，从而获得更高的模块化程度和升级可控性。资源包共 60 个文件，约 64KB，以 pp 清单、erb 模板、rb 脚本为主，辅以 yml 配置、json 元数据及 Gemfile、Rakefile 等依赖与任务文件，目录涵盖 manifests、templates、spec、tests 等模块，结构清晰便于按角色查阅。目前已有 133 人学习下载，适合希望掌握 Puppet 多角色部署、模板管理与测试流程的读者参考实践。

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

如果你手上有一台刚装好的 Linux 机器，想把它变成能管几十台服务器的 Puppet 控制节点，那 puppet_stack 这个项目大概率会被你翻出来。它干的事情很直接：把 Puppet Master、The Foreman 和 smart-proxy 这三件套一次性装好、配好、串起来。听起来简单，但真正动手的时候你会发现，版本对不上、证书签不过、Foreman 找不到 Puppet 的报表，随便一个环节都能让你折腾一下午。我见过太多人卡在“Puppet Master 装完了，但 Foreman 里就是看不到节点”这一步，最后放弃改用别的方式。这篇笔记就是把我自己装这套环境的完整过程拆开，从版本选择到验证跑通，每一步都落到命令和配置上。适合正在搭自动化运维环境、需要一套能管起来的 Puppet 控制端的开发者，新手照着走能跑通，熟手可以看看版本取舍和参数细节。

2. 装之前先把版本和依赖定死：Puppet 7 + Foreman 3.x 的组合

2.1 为什么版本组合比安装命令更重要

Puppet 生态里最坑的一点是：Puppet Master、Foreman、smart-proxy 三者的版本必须互相兼容。你单独装最新版 Puppet 8，再装 Foreman，大概率会遇到 Ruby 版本冲突或者 API 不匹配。我一般会先确定一个经过验证的组合，而不是每个组件都追最新。目前比较稳的一套是：Puppet 7.x（比如 7.28）、Foreman 3.9 或 3.10、smart-proxy 跟着 Foreman 版本走。操作系统选 Rocky Linux 8 或 AlmaLinux 8，因为 Foreman 官方仓库对 EL8 的支持最完整，EL9 也能装但有些包还在迁移。

提示：如果你用的是 Ubuntu 22.04，Puppet 7 的 apt 仓库是有的，但 Foreman 的 deb 包依赖会多一些，新手建议先用 EL8 系。

2.2 系统准备：主机名、时间同步、防火墙

装之前先把基础环境弄干净，不然后面证书和通信全是玄学问题。主机名必须是一个完整的 FQDN，比如puppet.example.lab，不能是localhost。时间必须同步，Puppet 的证书有效期校验对时间偏差很敏感。

# 设置主机名，改成你自己的 FQDN hostnamectl set-hostname puppet.example.lab # 确认 /etc/hosts 里有对应的解析，没有就加上 echo "192.168.1.10 puppet.example.lab puppet" >> /etc/hosts # 时间同步，EL8 用 chrony dnf install -y chrony systemctl enable --now chronyd chronyc sources # 防火墙放行 Puppet 和 Foreman 需要的端口 firewall-cmd --permanent --add-port=8140/tcp # Puppet Master firewall-cmd --permanent --add-port=8443/tcp # Foreman HTTPS firewall-cmd --permanent --add-port=80/tcp # Foreman HTTP 跳转 firewall-cmd --permanent --add-port=443/tcp # Foreman HTTPS firewall-cmd --reload

这几条命令里，hostnamectl改完最好重新登录一下 shell，让提示符里的主机名刷新。/etc/hosts那行是为了让本机解析自己的 FQDN，Puppet 证书生成时会用到。防火墙端口 8140 是 Puppet Master 的标配，8443 是 Foreman 的智能代理通信端口，80 和 443 是 Foreman Web 界面。如果你在云环境里，安全组也要对应放行。

2.3 配置 Puppet 7 的官方仓库

Puppet 7 的仓库包直接从官方源拿，EL8 用puppet7-release-el-8.noarch.rpm。装之前先确认系统里没有旧的 Puppet 6 残留。

# 清理可能存在的旧版本 rpm -qa | grep puppet # 如果有 puppet6-release 之类的包，先卸载 # rpm -e puppet6-release # 安装 Puppet 7 仓库 rpm -Uvh https://yum.puppet.com/puppet7-release-el-8.noarch.rpm # 确认仓库文件存在 ls /etc/yum.repos.d/puppet7.repo # 安装 puppet-agent 和 puppetserver dnf install -y puppet-agent puppetserver

puppet-agent是客户端也是 Master 的基础，puppetserver才是真正跑 Puppet Master 服务的包。装完之后，Puppet 的可执行文件在/opt/puppetlabs/bin/下，这个路径默认不在 PATH 里，需要手动加或者用绝对路径。

# 把 Puppet 工具加入 PATH，写入 profile echo 'export PATH=/opt/puppetlabs/bin:$PATH' >> /etc/profile.d/puppet.sh source /etc/profile.d/puppet.sh # 验证版本 puppet --version # 应该输出 7.x.x

2.4 初始化 Puppet Master 并签第一张证书

Puppet Master 第一次启动时会自动生成 CA 和自己的证书。启动之前先确认/etc/puppetlabs/puppet/puppet.conf里的certname和主机名一致。

# 查看默认配置 cat /etc/puppetlabs/puppet/puppet.conf # 如果没有 certname，手动加上 puppet config set certname puppet.example.lab --section main puppet config set server puppet.example.lab --section main # 启动 puppetserver systemctl enable --now puppetserver # 查看服务状态，第一次启动会生成 CA，需要等一会儿 systemctl status puppetserver # 确认 Puppet Master 自己的证书已经签好 puppetserver ca list --all

puppet config set会直接写进配置文件，比手动编辑更不容易出错。puppetserver ca list --all应该能看到puppet.example.lab的证书状态是Signed。如果这里报错说 CA 没初始化，就等 puppetserver 完全启动后再试，或者看/var/log/puppetlabs/puppetserver/puppetserver.log里的报错。

3. 装 The Foreman：把 Puppet Master 接进 Web 管理界面

3.1 Foreman 仓库和安装器

Foreman 的安装方式和 Puppet 不太一样，它用一个叫foreman-installer的工具来统一配置。先装 Foreman 的仓库，EL8 用foreman-release.rpm。

# 安装 Foreman 3.10 仓库 dnf install -y https://yum.theforeman.org/releases/3.10/el8/x86_64/foreman-release.rpm # 安装 foreman-installer dnf install -y foreman-installer # 确认 installer 可用 foreman-installer --version

foreman-installer会自动处理 Puppet 模块、Apache、PostgreSQL 等依赖。但这里有个坑：它会尝试自己装 Puppet 和 Puppet Server，如果你已经装了 Puppet 7，需要告诉 installer 不要重复装。

3.2 用 foreman-installer 对接已有 Puppet Master

我一般会用非交互模式跑 installer，把关键参数一次性传进去。下面这条命令是核心，参数比较多，逐个解释。

foreman-installer \ --foreman-initial-admin-username admin \ --foreman-initial-admin-password 'YourStrongPassword' \ --foreman-proxy-puppet true \ --foreman-proxy-puppetca true \ --foreman-proxy-puppet-url https://puppet.example.lab:8140 \ --foreman-proxy-puppet-use-ssl true \ --foreman-proxy-puppet-ssl-ca /etc/puppetlabs/puppet/ssl/certs/ca.pem \ --foreman-proxy-puppet-ssl-cert /etc/puppetlabs/puppet/ssl/certs/puppet.example.lab.pem \ --foreman-proxy-puppet-ssl-key /etc/puppetlabs/puppet/ssl/private_keys/puppet.example.lab.pem \ --foreman-proxy-ssl-port 8443 \ --foreman-proxy-http false \ --enable-foreman-proxy \ --no-enable-puppet \ --puppet-server false

--foreman-initial-admin-username和--foreman-initial-admin-password是 Web 界面的初始账号，密码要够强，不然 installer 会拒绝。--foreman-proxy-puppet true表示启用 smart-proxy 的 Puppet 功能，--foreman-proxy-puppetca true让它能管理证书签名。后面三个 SSL 路径指向 Puppet Master 自己生成的证书，这样 Foreman 才能和 Puppet Master 通信。--no-enable-puppet和--puppet-server false是关键，防止 installer 再装一套 Puppet。--foreman-proxy-http false强制走 HTTPS，生产环境别开 HTTP。

跑完 installer 后，它会输出一堆日志，最后告诉你 Foreman 的访问地址和账号。如果中途报错，先看/var/log/foreman-installer/foreman-installer.log，大部分是证书路径不对或者端口被占用。

3.3 验证 Foreman 和 Puppet Master 的连通性

装完之后别急着开 Web 界面，先在命令行确认 smart-proxy 能连上 Puppet Master。

# 检查 foreman-proxy 服务状态 systemctl status foreman-proxy # 用 curl 测试 smart-proxy 的 Puppet 接口 curl -k -u admin:YourStrongPassword https://puppet.example.lab:8443/puppet/environments # 应该返回 JSON 格式的环境列表，比如 production

如果 curl 返回 401，说明密码不对或者 smart-proxy 没读到认证配置。如果返回 500，看/var/log/foreman-proxy/proxy.log，通常是 SSL 证书路径写错了或者权限不对。Puppet 的私钥文件权限是 600，属主是 puppet，smart-proxy 默认以 foreman-proxy 用户跑，需要确保它能读到这些文件。常见做法是把 foreman-proxy 加入 puppet 组，或者把证书复制一份给 foreman-proxy 专用。

# 把 foreman-proxy 加入 puppet 组 usermod -aG puppet foreman-proxy # 重启 foreman-proxy systemctl restart foreman-proxy

3.4 在 Foreman 里导入 Puppet 环境

连通之后，登录 Foreman Web 界面，地址是https://puppet.example.lab，用 installer 里设的账号密码。进去之后到Configure->Environments，点Import environments from puppet.example.lab。如果前面 curl 能通，这里应该能列出production环境。导入之后，再到Configure->Classes，点Import classes，把 Puppet Master 上的模块类都拉过来。这一步做完，Foreman 才算真正接管了 Puppet 的配置管理。

4. 避坑记录：装 puppet_stack 时最容易翻车的五个地方

4.1 证书签不过：现象是 Puppet agent 一直卡在 waiting for certificate

现象：客户端跑puppet agent -t时一直提示Waiting for certificate，Master 上puppetserver ca list能看到请求但没签。

原因：Puppet Master 的 CA 没有自动签，或者客户端的主机名和证书请求里的 certname 不一致。

解决：在 Master 上手动签，puppetserver ca sign --certname client.example.lab。如果客户端 certname 不对，先在客户端puppet config set certname client.example.lab，然后删掉/etc/puppetlabs/puppet/ssl重新跑。

4.2 Foreman 看不到 Puppet 报表：现象是节点列表空白

现象：Foreman 里Hosts->All Hosts没有节点，但 Puppet agent 明明跑成功了。

原因：Puppet Master 没有配置报表处理器，或者 Foreman 的报表接口没启用。

解决：在 Puppet Master 的puppet.conf里加reports = foreman，并确保foreman-report插件装了。EL8 下是puppet-foreman包，装完重启 puppetserver。

dnf install -y puppet-foreman puppet config set reports foreman --section master systemctl restart puppetserver

4.3 smart-proxy 启动失败：现象是 8443 端口没监听

现象：systemctl status foreman-proxy显示 active，但ss -tlnp | grep 8443没有输出。

原因：smart-proxy 的 SSL 证书路径配置错误，或者 foreman-proxy 用户读不到私钥。

解决：检查/etc/foreman-proxy/settings.d/puppet.yml里的ssl_ca、ssl_cert、ssl_key路径，确保文件存在且权限是 640 或 600，属主是 puppet 或 foreman-proxy 能读。改完systemctl restart foreman-proxy。

4.4 Puppet 7 和 Foreman 3.10 的 Ruby 版本冲突

现象：foreman-installer跑一半报 Ruby gem 依赖错误，说puppetgem 版本不满足。

原因：Foreman 3.10 依赖 Ruby 3.0，而 Puppet 7 自带的 Ruby 是 2.7，两者混用会冲突。

解决：不要用系统 Ruby 装 Foreman 的 gem，让 foreman-installer 用它自己的 Ruby 环境。如果已经冲突了，先dnf remove foreman-installer，清理/usr/share/foreman下的 gem 缓存，再重装。我一般会在装 Foreman 之前先把 Puppet 的 Ruby 环境隔离好，避免 PATH 里混入/opt/puppetlabs/bin/ruby。

4.5 防火墙没放行 8140 导致 agent 连不上

现象：客户端puppet agent -t报Connection refused或超时。

原因：Master 的防火墙没放行 8140，或者云安全组没开。

解决：firewall-cmd --add-port=8140/tcp --permanent && firewall-cmd --reload。云环境还要在控制台的安全组里加规则。这个坑最简单但也最容易忘，尤其是本地测试时关了防火墙，上生产忘了开。

5. 装完怎么验证跑通：从 agent 到 Foreman 的完整链路检查

装完不代表跑通，我一般会按下面的顺序走一遍验证，确保每一环都通。先在一台客户端上装 puppet-agent，指向 Master。

# 客户端装 Puppet 7 仓库和 agent rpm -Uvh https://yum.puppet.com/puppet7-release-el-8.noarch.rpm dnf install -y puppet-agent # 配置客户端指向 Master /opt/puppetlabs/bin/puppet config set server puppet.example.lab --section main /opt/puppetlabs/bin/puppet config set certname client.example.lab --section main # 跑一次 agent，生成证书请求 /opt/puppetlabs/bin/puppet agent -t # 第一次会提示 waiting for certificate，正常

然后到 Master 上签证书：

puppetserver ca sign --certname client.example.lab

签完再回客户端跑一次puppet agent -t，这次应该能成功应用 catalog。如果 catalog 是空的，说明 Master 上还没有给这个节点分配类，可以在 Foreman 里给节点分配一个简单的类，比如motd，再跑一次。

验证 Foreman 报表：客户端跑完之后，到 Foreman Web 界面Hosts->All Hosts，应该能看到client.example.lab，点进去看Reports标签，应该有最近一次运行的记录。如果报表没出来，检查 Master 的puppet.conf里reports = foreman是否生效，以及/var/log/puppetlabs/puppetserver/puppetserver.log里有没有 foreman 相关的报错。

最后验证 smart-proxy 的证书管理：在 Foreman 界面Infrastructure->Smart Proxies，点puppet.example.lab，应该能看到Puppet和Puppet CA两个功能都是启用的。再到Infrastructure->Smart Proxies->Certificates，应该能列出待签和已签的证书。如果这里能操作，说明 smart-proxy 的 puppetca 功能也通了。

我自己的习惯是每次装完这套环境，都会用一台干净的客户端从零跑一遍完整流程：装 agent、签证书、应用 catalog、在 Foreman 里看到报表。只要这四步都过，后面加节点就是重复劳动。从那以后我每次装 puppet_stack 都强制走一遍这个验证链路，不再靠“看起来装完了”来判断。希望帮到你。

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