OpenVox 9.1.0 配置参数详解

目标：把 OpenVox 9.1.0 的配置拆成「文件在哪、段怎么优先生效、每个常用参数管什么」三层讲清。文中的默认值与命令回显均来自 2026-10-28 在 Ubuntu 22.04.5 LTS、openvox-server 9.1.0 实机的 puppet config print 与配置文件读取，逐行照抄；安装步骤见《OpenVox 9.1.0 Ubuntu 22.04 安装指南》。

一、环境信息

1.1 实测基线

项目	值
操作系统	Ubuntu 22.04.5 LTS
主机名 / certname	`openvox-master`
openvox-server	9.1.0-1+ubuntu22.04
openvox-agent	9.1.0-1+ubuntu22.04
配置目录	`/etc/puppetlabs/puppet`
代码目录	`/etc/puppetlabs/code`
服务端数据目录	`/opt/puppetlabs/server/data/puppetserver`
查询日期	2026-10-28

1.2 本篇涉及的配置文件

路径	归属	作用
`/etc/puppetlabs/puppet/puppet.conf`	服务端 + 客户端共用	主配置，`[main]` / `[server]` / `[agent]` 三段
`/etc/puppetlabs/puppet/hiera.yaml`	全局 Hiera	出厂为空层级，仅作兜底
`/etc/puppetlabs/puppet/autosign.conf`	服务端	自动签发白名单
`/etc/puppetlabs/puppetserver/conf.d/puppetserver.conf`	服务端	JRuby 实例、gem 路径、服务端目录
`/etc/puppetlabs/puppetserver/conf.d/webserver.conf`	服务端	HTTPS 监听地址与端口
`/etc/puppetlabs/puppetserver/conf.d/auth.conf`	服务端	接口授权规则
`/etc/puppetlabs/puppetserver/conf.d/ca.conf`	服务端	内置 CA 行为
`/etc/puppetlabs/code/environments/production/environment.conf`	环境级	覆盖 `modulepath` / `manifest` 等
`/etc/puppetlabs/code/environments/production/hiera.yaml`	环境级	环境自己的数据层级
`/etc/default/puppetserver`	服务端进程	JVM 参数与运行用户（非 Puppet 配置，但常改）

二、配置文件体系总览

2.1 四个层次

OpenVox 的配置按生效范围分四层，排障时先判断问题落在哪一层：

进程层：/etc/default/puppetserver（JVM 堆、用户），改完必须重启 puppetserver；
全局应用层：puppet.conf，服务端与 CLI 都读它，puppet config 命令只改这一层；
服务端组件层：/etc/puppetlabs/puppetserver/conf.d/*.conf（HOCON 格式），决定监听端口、JRuby 实例数、授权规则；
代码/数据层：/etc/puppetlabs/code/environments/<env>/ 下的 manifests/、modules/、data/、environment.conf、hiera.yaml，由环境隔离。

2.2 一个参数在多处出现时谁生效

优先级从高到低：命令行参数 > 环境级 environment.conf > puppet.conf 的段 > 内置默认值。同一参数在 puppet.conf 的 [main] 与 [agent] 同时存在时，agent 运行读 [agent]，服务端读 [server]，[main] 是两者的公共兜底。

这一点最容易踩坑：puppet config print server 默认读 [main]，返回 puppet；而 agent 实际运行读 [agent]，返回 openvox-master。两个值不一样，不代表配置写错了。

三、puppet.conf 的结构与段优先级

3.1 当前生效的完整内容

以下为本机安装并按安装篇配置后的 puppet.conf 全文（未改动部分为注释）：

# This file can be used to override the default puppet settings.
# See the following links for more details on what settings are available:
# - https://docs.openvoxproject.org/openvox/latest/config_important_settings.html
# - https://docs.openvoxproject.org/openvox/latest/config_about_settings.html
# - https://docs.openvoxproject.org/openvox/latest/config_file_main.html
# - https://docs.openvoxproject.org/openvox/latest/configuration.html
[server]
vardir = /opt/puppetlabs/server/data/puppetserver
logdir = /var/log/puppetlabs/puppetserver
rundir = /var/run/puppetlabs/puppetserver
pidfile = /var/run/puppetlabs/puppetserver/puppetserver.pid
codedir = /etc/puppetlabs/code
autosign = /etc/puppetlabs/puppet/autosign.conf

[agent]
server = openvox-master
certname = openvox-master
runinterval = 30m

出厂时只有 [server] 段那五行，autosign 与整个 [agent] 段是后续用 puppet config set 追加的。

3.2 段名与别名

段名只认 main、server、agent 三个（user 段已废弃）。旧文档里的 [master] 是 [server] 的历史别名，实测仍可读：

$ /opt/puppetlabs/bin/puppet config print server vardir --section master
server = puppet
vardir = /opt/puppetlabs/server/data/puppetserver

vardir 取到了 [server] 的值，说明别名生效；但新配置一律写 [server]，别用 [master]，后续版本随时可能彻底移除。

3.3 三段取值实测对照

$ /opt/puppetlabs/bin/puppet config print server certname runinterval --section main
server = puppet
certname = openvox-master
runinterval = 1800

$ /opt/puppetlabs/bin/puppet config print server certname runinterval --section agent
server = openvox-master
certname = openvox-master
runinterval = 1800

$ /opt/puppetlabs/bin/puppet config print server certname autosign --section server
server = puppet
certname = openvox-master
autosign = /etc/puppetlabs/puppet/autosign.conf

读法：

[main] 的 server = puppet 是内置默认值，没有被显式覆盖；
[agent] 的 server = openvox-master 是安装篇写入的；
runinterval 在文件里写的是 30m，config print 统一换算成 1800 秒——配置里可以写 30m、1h 这类单位，查询时一律按秒显示；
autosign 只出现在 [server] 段，所以 --section main 查不到它，--section server 才有。

四、[main] 段关键参数

4.1 目录类参数

$ /opt/puppetlabs/bin/puppet config print confdir codedir vardir logdir rundir ssldir --section main
confdir = /etc/puppetlabs/puppet
codedir = /etc/puppetlabs/code
vardir = /opt/puppetlabs/puppet/cache
logdir = /var/log/puppetlabs/puppet
rundir = /var/run/puppetlabs
ssldir = /etc/puppetlabs/puppet/ssl

参数	默认值	含义与改动风险
`confdir`	`/etc/puppetlabs/puppet`	`puppet.conf`、`hiera.yaml`、`autosign.conf` 所在目录；改它会让所有 CLI 找不到配置，几乎不该动
`codedir`	`/etc/puppetlabs/code`	环境与模块根目录；改后服务端与 agent 必须一致
`vardir`	`/opt/puppetlabs/puppet/cache`	agent 端缓存、目录缓存、锁文件
`logdir`	`/var/log/puppetlabs/puppet`	agent 日志目录
`rundir`	`/var/run/puppetlabs`	运行期 PID/锁目录
`ssldir`	`/etc/puppetlabs/puppet/ssl`	客户端证书、私钥、CA 证书

4.2 环境与清单类参数

$ /opt/puppetlabs/bin/puppet config print environmentpath default_manifest environment_timeout --section main
environmentpath = /etc/puppetlabs/code/environments
default_manifest = ./manifests
environment_timeout = 0

environmentpath：环境根目录，每个子目录是一个环境；
default_manifest：环境内入口清单的相对路径，./manifests 即 manifests/site.pp（目录形式时取目录下所有 .pp）；
environment_timeout = 0：每次请求都重新加载环境代码，开发期改清单立即生效，代价是编译开销。生产环境如果代码很少变，可以设成 300（秒）或 unlimited 降低开销，但改代码后必须执行 puppetserver reload 或删环境缓存。

4.3 行为类参数

$ /opt/puppetlabs/bin/puppet config print strict_variables report pluginsync --section main
strict_variables = true
report = true
pluginsync =

参数	实测值	说明
`strict_variables`	`true`	引用未定义变量直接报错，而不是静默当 `undef`；建议保持 `true`，能提前暴露拼写错误
`report`	`true`	每次运行生成报告；要接 PuppetDB 或外部报表必须为 `true`
`pluginsync`	空	空值表示由运行时默认行为决定（当前版本默认同步）；显式写 `false` 可关闭模块自带 fact/类型的下发

4.4 模块路径

$ /opt/puppetlabs/bin/puppet config print basemodulepath --section main
basemodulepath = /etc/puppetlabs/code/modules:/opt/puppetlabs/puppet/modules

最终 modulepath 是「当前环境自己的 modules/ + basemodulepath」。basemodulepath 通过 puppet.conf 全局共享，环境私有模块放 environments/<env>/modules/。不要在 puppet.conf 里设全局 modulepath，新版会直接拒绝，需要覆盖时写 environment.conf。

💡 技术拓展：模块查找路径的三种组织方式——

方式配置位置适用
环境隔离（推荐） environments/<env>/modules/ 不同环境用不同模块版本，灰度安全
全局共享 basemodulepath 指向 /etc/puppetlabs/code/modules 所有环境共用一套基础模块
只用内置 /opt/puppetlabs/puppet/modules 存放随包分发的模块，不建议手工往里放

本篇采用「环境隔离 + 全局 basemodulepath」组合：profile 放环境内，stdlib 用 puppet module install 装进环境内，内置目录保持出厂状态。

方式	配置位置	适用
环境隔离（推荐）	`environments/<env>/modules/`	不同环境用不同模块版本，灰度安全
全局共享	`basemodulepath` 指向 `/etc/puppetlabs/code/modules`	所有环境共用一套基础模块
只用内置	`/opt/puppetlabs/puppet/modules`	存放随包分发的模块，不建议手工往里放

五、[server] 段关键参数

5.1 服务端目录与文件

$ /opt/puppetlabs/bin/puppet config print vardir logdir rundir pidfile codedir --section server
vardir = /opt/puppetlabs/server/data/puppetserver
logdir = /var/log/puppetlabs/puppetserver
rundir = /var/run/puppetlabs/puppetserver
pidfile = /var/run/puppetlabs/puppetserver/puppetserver.pid
codedir = /etc/puppetlabs/code

服务端的 vardir 与 agent 的 /opt/puppetlabs/puppet/cache 是两个不同目录，前者存 JRuby 实例、gem、CA 之外的运行数据；logdir 也是独立的 /var/log/puppetlabs/puppetserver。备份服务端时这两个目录都要覆盖。

5.2 证书相关参数

$ /opt/puppetlabs/bin/puppet config print cacert cadir cakey ca_name autosign --section server
autosign = /etc/puppetlabs/puppet/autosign.conf
ca_name = Puppet CA: openvox-master
cacert = /etc/puppetlabs/puppetserver/ca/ca_crt.pem
cadir = /etc/puppetlabs/puppetserver/ca
cakey = /etc/puppetlabs/puppetserver/ca/ca_key.pem

参数	实测值	说明
`cadir`	`/etc/puppetlabs/puppetserver/ca`	CA 私钥、CA 证书、已签证书、CSR、CRL 都在这里，整目录备份
`cakey`	`<cadir>/ca_key.pem`	CA 私钥，权限必须 0640 且属主 `puppet:puppet`
`cacert`	`<cadir>/ca_crt.pem`	CA 证书，客户端要信任的就是它
`ca_name`	`Puppet CA: openvox-master`	CA 的 CN，由 certname 派生
`autosign`	`/etc/puppetlabs/puppet/autosign.conf`	自动签发策略文件，见第十一章

⚠️ 注意：/etc/puppetlabs/puppetserver/ca 的属主必须是 puppet，否则 puppetserver ca 会报 ca_key.pem (Permission denied) 的 500 错误。该故障的完整定位与修复见《OpenVox 9.1.0 Ubuntu 22.04 安装指南》第九章。

5.3 默认证书有效期

ca_ttl 在 puppet config print 中显示为 157680000 秒（即 5 年），可通过 ca.conf 的 ca-ttl 覆盖。puppet config print ca_ttl --section server 可直接查当前值；改短有效期（如 "1y"）后新签的证书才生效，已签证书不会重签。

六、[agent] 段关键参数

6.1 定位服务端

[agent] 段最关键的三个参数：

$ /opt/puppetlabs/bin/puppet config print server certname runinterval --section agent
server = openvox-master
certname = openvox-master
runinterval = 1800

参数	实测值	说明
`server`	`openvox-master`	服务端主机名；未配置时回落到 `[main]` 的 `puppet`
`certname`	`openvox-master`	本机证书 CN，必须与服务端签发的证书名一致；默认取主机名
`runinterval`	`1800`（文件里写 `30m`）	守护进程模式下两次运行的间隔

6.2 运行行为

参数	默认值（实测）	说明
`environment`	`production`	拉取哪个环境的目录
`report`	`true`	是否回传报告
`splay`	`false`	守护进程启动时是否随机延迟，避免大批节点同时打服务端；节点多时建议 `true` 并配 `splaylimit`
`usecacheonfailure`	`true`	服务端不可达时是否用本地缓存目录继续收敛
`noop`	`false`	全局演练模式，只报告不修改

environment 可以用 puppet agent -t --environment staging 临时覆盖，用于灰度验证某个环境，不必改配置文件。

6.3 配置写入与复核

$ /opt/puppetlabs/bin/puppet config set server openvox-master --section agent
$ /opt/puppetlabs/bin/puppet config print server --section agent
openvox-master

puppet config set 成功时没有任何输出，只看退出码会误以为失败；务必用 puppet config print 复核。删除参数：

$ /opt/puppetlabs/bin/puppet config set splay true --section agent
$ /opt/puppetlabs/bin/puppet config print splay --section agent
true
$ /opt/puppetlabs/bin/puppet config delete splay --section agent
Deleted setting from 'agent': 'splay = true'
$ /opt/puppetlabs/bin/puppet config print splay --section agent
false

删除后参数回到内置默认值 false，puppet config delete 会回显被删的键与值，这是少数会说话的子命令。

七、puppetserver 的 conf.d 配置

7.1 webserver.conf：监听地址与端口

webserver: {
    access-log-config: /etc/puppetlabs/puppetserver/request-logging.xml
    client-auth: want
    ssl-host: 0.0.0.0
    ssl-port: 8140
}

键	值	说明
`ssl-host`	`0.0.0.0`	监听所有地址；只允许内网访问时可改具体网卡 IP
`ssl-port`	`8140`	与 A1 篇、安装篇一致的端口；改端口后 agent 的 `serverport` 要同步改
`client-auth`	`want`	请求客户端证书但不强制；CA 的 `/puppet-ca/v1/certificate` 等接口需要免证书访问，不要改成 `need`

7.2 puppetserver.conf：JRuby 与目录

关键片段（保留出厂注释，未改动）：

jruby-puppet: {
    ruby-load-path: [/opt/puppetlabs/puppet/lib/ruby/vendor_ruby]
    gem-home: /opt/puppetlabs/server/data/puppetserver/jruby-gems
    server-conf-dir: /etc/puppetlabs/puppet
    server-code-dir: /etc/puppetlabs/code
    server-var-dir: /opt/puppetlabs/server/data/puppetserver
    server-run-dir: /var/run/puppetlabs/puppetserver
    server-log-dir: /var/log/puppetlabs/puppetserver
    #max-active-instances: 1
}

max-active-instances 默认注释掉，表示由 puppetserver 按内存自动计算（每实例约 512MB–1GB）。手工设值时，经验公式是「可用内存 / 1GB，向上取整，至少 1」，且必须配合第七章的 JVM 堆一起算，否则节点一多就 OOM。

7.3 ca.conf：CA 行为

certificate-authority: {
    # allow-subject-alt-names: false
    # allow-authorization-extensions: false
    # enable-infra-crl: false
    allow-auto-renewal: false
    auto-renewal-cert-ttl: "60d"
    #ca-ttl: "60d"
}

出厂即关闭自动续期（allow-auto-renewal: false），证书到期需要重新签发。allow-subject-alt-names: false 意味着 CSR 里带 SAN 会被拒，多域名节点要在签发时用 --subject-alt-names 显式追加。

八、auth.conf 授权规则

8.1 文件形态与匹配顺序

auth.conf 是 HOCON 数组，每条规则包含 match-request（路径、匹配类型、方法）、allow / deny / allow-unauthenticated、sort-order、name。sort-order 小的先匹配，命中即停止；最后一条 sort-order: 999 是兜底 deny all：

{
    # Deny everything else. This ACL is not strictly
    # necessary, but illustrates the default policy
    match-request: {
        path: "/"
        type: path
    }
    deny: "*"
    sort-order: 999
    name: "puppetlabs deny all"
}

8.2 出厂规则清单

实测 grep -n "name:" 共 27 条规则，按用途分组：

分组	规则名（节选）	授权方式	用途
目录	`puppetlabs v3 catalog from agents`	`allow: "$1"`	节点只能取自己的目录，`$1` 是 URL 里的 certname
目录	`puppetlabs v4 catalog for services`	`deny: "*"`	服务端间调目录默认关闭
证书	`puppetlabs certificate` / `crl` / `csr`	`allow-unauthenticated: true`	首次申请证书必须免认证，否则死锁
证书	`puppetlabs cert status` / `CRL update` / `cert sign`	`allow: { extensions: { pp_cli_auth: "true" } }`	只允许 CA CLI 携带专用扩展访问
状态	`puppetlabs status service - simple` / `- full`	`allow-unauthenticated: true`	健康检查探针
环境	`puppetlabs environments`	`allow: "*"`	已认证节点可列环境
数据	`puppetlabs facts` / `report` / `node`	`allow: "*"`	已认证节点上报事实与报告
文件	`puppetlabs file content` / `metadata` / `file bucket`	`allow: "*"`	目录里 `source`/`content` 走 file 服务
兜底	`puppetlabs deny all`	`deny: "*"`	其余全部拒绝

8.3 常见改法

收紧 facts 上报：把 puppetlabs facts 的 allow: "*" 改成 allow: "$1" 需要改 match-request 加捕获组，改动前先在测试环境验证 agent 仍能拿到目录；
放行外部只读接口：给 /puppet/v3/environments 加 allow-unauthenticated: true 会暴露环境名，一般不要；
新增规则：sort-order 取 500 以下的空档（如 400），并放在文件末尾 deny all 之前，否则永远匹配不到。

改完 auth.conf 需要重启 puppetserver（systemctl restart puppetserver），该文件不参与热加载。

九、Hiera 5 与数据分层

9.1 全局配置是空层级

---
# Hiera 5 Global configuration file

version: 5

# defaults:
#   data_hash: yaml_data
# hierarchy:
#  - name: Common
#    data_hash: yaml_data
hierarchy: []

<confdir>/hiera.yaml 出厂 hierarchy: []，即全局不提供任何数据。这是刻意的：所有业务数据都应落在环境级 hiera.yaml 里，避免全局变量污染所有环境。

$ /opt/puppetlabs/bin/puppet config print hiera_config --section main
/etc/puppetlabs/puppet/hiera.yaml

9.2 环境级配置与数据文件

---
version: 5
defaults:
  datadir: data
  data_hash: yaml_data
hierarchy:
  - name: "Common data"
    path: "common.yaml"

datadir: data 相对环境根目录，实际文件是 /etc/puppetlabs/code/environments/production/data/common.yaml：

---
profile::baseline::motd: "Managed by OpenVox 9.1.0 on %{trusted.hostname}\n"
profile::baseline::packages:
  - nginx

%{trusted.hostname} 属于 trusted facts，由服务端在签发证书时写入，agent 不能伪造。常用的还有 %{facts.os.family}、%{facts.networking.ip}、%{trusted.certname}。

9.3 查询与调试

$ /opt/puppetlabs/bin/puppet lookup profile::baseline::motd
--- 'Managed by OpenVox 9.1.0 on openvox-master

  '

输出是 YAML 序列化后的字符串，\n 被渲染成真实换行，所以看起来有空行。想知道为什么取到某个值，用 --explain：

$ /opt/puppetlabs/bin/puppet lookup profile::baseline::motd --explain
Searching for "lookup_options"
  Global Data Provider (hiera configuration version 5)
    Using configuration "/etc/puppetlabs/puppet/hiera.yaml"
    No such key: "lookup_options"
  Environment Data Provider (hiera configuration version 5)
    Using configuration "/etc/puppetlabs/code/environments/production/hiera.yaml"
    Hierarchy entry "Common data"
      Path "/etc/puppetlabs/code/environments/production/data/common.yaml"
        Original path: "common.yaml"
        No such key: "lookup_options"
  Module data provider for module "profile" not found
Searching for "profile::baseline::motd"
  Global Data Provider (hiera configuration version 5)
    Using configuration "/etc/puppetlabs/puppet/hiera.yaml"
    No such key: "profile::baseline::motd"
  Environment Data Provider (hiera configuration version 5)
    Using configuration "/etc/puppetlabs/code/environments/production/hiera.yaml"
    Hierarchy entry "Common data"
      Path "/etc/puppetlabs/code/environments/production/data/common.yaml"
        Original path: "common.yaml"

--explain 会逐层打印「查了哪个文件、命中还是 No such key」，是排查「Hiera 取不到值」最快的入口。

9.4 层级设计建议

💡 技术拓展：Hiera 层级常见的四种切分维度——

维度示例路径适用
按环境 %{environment}/common.yaml 环境间差异大，隔离要求高
按节点 nodes/%{trusted.certname}.yaml 单机特例多，需要覆盖
按操作系统 os/%{facts.os.family}.yaml 混合 Linux/Windows，包名与路径不同
按角色 role/%{role}.yaml 有明确角色划分（web/db/cache）

本篇只用单层 common.yaml，适合演示与小型环境。层级从左到右优先，越具体的层级放越前面，否则会被更泛的层级覆盖。

维度	示例路径	适用
按环境	`%{environment}/common.yaml`	环境间差异大，隔离要求高
按节点	`nodes/%{trusted.certname}.yaml`	单机特例多，需要覆盖
按操作系统	`os/%{facts.os.family}.yaml`	混合 Linux/Windows，包名与路径不同
按角色	`role/%{role}.yaml`	有明确角色划分（web/db/cache）

十、目录环境与环境级配置

10.1 目录结构

$ find /etc/puppetlabs/code -maxdepth 3
/etc/puppetlabs/code
/etc/puppetlabs/code/environments
/etc/puppetlabs/code/environments/production
/etc/puppetlabs/code/environments/production/environment.conf
/etc/puppetlabs/code/environments/production/hiera.yaml
/etc/puppetlabs/code/environments/production/modules
/etc/puppetlabs/code/environments/production/manifests
/etc/puppetlabs/code/environments/production/data
/etc/puppetlabs/code/modules

environments/ 下每个目录就是一个环境，目录名即环境名；code/modules 是全局模块目录，被 basemodulepath 引用。

10.2 environment.conf 的默认值

# Each environment can have an environment.conf file. Its settings will only
# affect its own environment. See docs for more info:
# https://docs.openvoxproject.org/openvox/latest/config_file_environment.html

# Any unspecified settings use default values; some of those defaults are based
# on puppet.conf settings.

# If these settings include relative file paths, they'll be resolved relative to
# this environment's directory.

# Allowed settings and default values:

# modulepath = ./modules:$basemodulepath
# manifest = (default_manifest from puppet.conf, which defaults to ./manifests)
# config_version = (no script; OpenVox will use the time the catalog was compiled)
# environment_timeout = (environment_timeout from puppet.conf, which defaults to 0)

四个可覆盖项：

键	默认	覆盖场景
`modulepath`	`./modules:$basemodulepath`	环境需要额外私有模块目录
`manifest`	`./manifests`	入口清单不在 `manifests/site.pp`
`config_version`	编译时间	需要把 Git 提交号写进目录版本，便于追溯
`environment_timeout`	继承 `puppet.conf`（`0`）	该环境单独调大缓存时间

config_version 的典型写法是 config_version = /etc/puppetlabs/code/bin/git-rev.sh，脚本输出一行字符串，会出现在 agent 日志的 Applying configuration version '<值>' 里。

10.3 新增环境

$ cp -a /etc/puppetlabs/code/environments/production /etc/puppetlabs/code/environments/staging
$ /opt/puppetlabs/bin/puppet agent -t --environment staging

预期结果：agent 日志里 Requesting catalog from openvox-master:8140 之后出现 Info: Using environment 'staging'，随后 Applying configuration version '<staging 的编译时间>'。未实测：本机只保留了 production 一个环境，上述命令是官方支持的标准用法，给命令与预期结果，执行前请确认 staging 目录内容已按需调整。

十一、证书与自动签发（autosign）

11.1 打开 autosign

自动签发由 [server] 段的 autosign 指向策略文件，再用 puppet config set 写入：

$ /opt/puppetlabs/bin/puppet config set autosign /etc/puppetlabs/puppet/autosign.conf --section server

命令无输出即成功，此时 puppet.conf 的 [server] 段变成：

[server]
vardir = /opt/puppetlabs/server/data/puppetserver
logdir = /var/log/puppetlabs/puppetserver
rundir = /var/run/puppetlabs/puppetserver
pidfile = /var/run/puppetlabs/puppetserver/puppetserver.pid
codedir = /etc/puppetlabs/code
autosign = /etc/puppetlabs/puppet/autosign.conf

策略文件内容就是一行通配：

$ cat /etc/puppetlabs/puppet/autosign.conf
*.example.com

改完重启服务：

$ systemctl restart puppetserver
$ systemctl is-active puppetserver
active

11.2 自动签发的实测效果

新节点 web02.example.com 首次运行 agent，不再停在 CSR 阶段，而是直接拿到证书并收敛：

-Managed by OpenVox 9.1.0 on web01
+Managed by OpenVox 9.1.0 on web02
Notice: /Stage[main]/Profile::Baseline/File[/etc/motd]/content: content changed '{sha256}e1905faf57e8ec9b16f3069b65134d2412290bf21fa66521b0620f4b35d92df9' to '{sha256}154688ff967edf95665df0b08818e7df29841b6ec6e855ac94654a268b1bbc6f'
Notice: Applied catalog in 0.87 seconds

服务端日志同步记录签发动作：

2026-10-27T18:03:27.667Z INFO  [qtp2074908056-84] [p.p.certificate-authority] Entity CA signed 1 certificate: web02.example.com.

puppetserver ca list --all 能看到两台已签节点：

Signed Certificates:
    openvox-master          (SHA256)  59:C6:3D:47:0E:44:98:DA:7F:07:71:A5:4F:C5:D6:17:28:72:28:1A:B0:CD:81:D8:CC:A4:C3:A6:72:7F:EF:10	alt names: ["DNS:puppet", "DNS:openvox-master"]	authorization extensions: [pp_cli_auth: true]
    web02.example.com       (SHA256)  21:4E:25:E7:7D:3F:D9:77:FC:D3:45:4C:3A:42:46:E7:B5:39:64:6F:07:47:75:4E:8A:0F:6F:F8:5E:FE:69:75	alt names: ["DNS:web02.example.com"]

11.3 三种签发策略

策略	配置	安全性	适用
手工签发	`autosign` 不配，逐台 `puppetserver ca sign`	最高	节点少、合规要求高
域名通配	`autosign.conf` 写 `*.example.com`	中（同域任何主机都能签）	同域大批量扩容
策略脚本	`autosign` 指向可执行脚本，脚本返回 0/1	高（可校验 CSR 内容与来源 IP）	有统一准入流程

autosign.conf 支持 *.example.com（任意层级子域）与 *.example.com 同域精确名；不支持正则，写 web0[1-9] 之类的通配不会按预期工作。

11.4 证书与配置的一致性

certname 决定证书 CN，改了 certname 后旧证书不再匹配，agent 会重新生成 CSR。改 certname 的标准流程：

systemctl stop puppet
改 puppet.conf [agent] 的 certname
删旧证书：rm -rf /etc/puppetlabs/puppet/ssl
puppet agent -t 重新申请
服务端 puppetserver ca sign --certname <新名> 或由 autosign 自动签

十二、配置变更流程与排障

12.1 标准变更流程

$ /opt/puppetlabs/bin/puppet config set runinterval 10m --section agent
$ /opt/puppetlabs/bin/puppet config print runinterval --section agent
600
$ /opt/puppetlabs/bin/puppet parser validate /etc/puppetlabs/code/environments/production/manifests/site.pp
$ /opt/puppetlabs/bin/puppet agent -t --noop

先改配置、再验证语法、再 --noop 演练，最后才真跑。--noop 只报告「会改什么」，不会动系统：

--- /etc/motd	2026-10-27 18:03:29.806018862 +0000
+++ /tmp/puppet-file20261027-10617-3x1t15	2026-10-27 18:18:43.883677315 +0000
@@ -1 +1 @@
-Managed by OpenVox 9.1.0 on web02
+Managed by OpenVox 9.1.0 on openvox-master
Notice: /Stage[main]/Profile::Baseline/File[/etc/motd]/content: content changed '{sha256}154688ff967edf95665df0b08818e7df29841b6ec6e855ac94654a268b1bbc6f' to '{sha256}ba311a5f7b8494363f3af525e86f0a0baf625d5d0a32cc3b05273b23aa3dcf33' (noop)
Notice: Class[Profile::Baseline]: Would have triggered 'refresh' from 1 event
Notice: Stage[main]: Would have triggered 'refresh' from 1 event
Notice: Applied catalog in 0.80 seconds

(noop) 后缀与 Would have triggered 是演练模式的标记，看到这两类字样就说明没有真正改系统。

12.2 `puppet.conf` 改了不生效

按顺序查三件事：

改的是不是应用实际读取的段？puppet config print <键> --section agent 与 --section server 各查一次；
服务端是否重启？puppet.conf 的 [server] 段由 puppetserver 进程在启动时读取，改完必须 systemctl restart puppetserver；
agent 是否被禁用？puppet agent --disable 会留下锁文件：

$ /opt/puppetlabs/bin/puppet agent --disable "maintenance window"
$ cat /opt/puppetlabs/puppet/cache/state/agent_disabled.lock
{"disabled_message":"maintenance window"}
$ /opt/puppetlabs/bin/puppet agent --enable

--disable 时 agent 即使被 systemctl start 也会跳过运行并打印 disabled 消息；--enable 删除锁文件后恢复。

12.3 Hiera 取不到值

先看 puppet lookup <键> --explain 的层级输出，再核三件事：键名是否拼错（Puppet 的类参数键是 类名::参数名）、数据文件是否在 datadir 下、hiera.yaml 的 path 是否与实际文件名一致。若输出里出现 No facts available for target node，说明指定了 --node 但该节点事实不在缓存中：

$ /opt/puppetlabs/bin/puppet lookup profile::baseline::motd --node openvox-master
Error: Could not run: No facts available for target node: openvox-master

去掉 --node 用本机事实查询即可。跨节点查数据应改用 puppet lookup --node <名> --facts <factset> 或直接查 PuppetDB。

12.4 auth.conf 改完 403

403 Forbidden 几乎都是新规则被更靠前的规则截胡，或者 sort-order 落在 deny all 之后。用 curl 带客户端证书复现：

$ curl --cert /etc/puppetlabs/puppet/ssl/certs/openvox-master.pem \
       --key /etc/puppetlabs/puppet/ssl/private_keys/openvox-master.pem \
       --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem \
       -s -o /dev/null -w '%{http_code}\n' https://openvox-master:8140/puppet/v3/environments
200

返回 200 说明该路径对已认证节点放行；返回 403 时对照 auth.conf 里路径前缀更长、sort-order 更小的规则逐条排除。

十三、参考链接

OpenVox 官方配置参考：https://docs.openvoxproject.org/openvox/latest/configuration.html
puppet.conf 主配置说明：https://docs.openvoxproject.org/openvox/latest/config_file_main.html
重要配置项清单：https://docs.openvoxproject.org/openvox/latest/config_important_settings.html
环境配置说明：https://docs.openvoxproject.org/openvox/latest/config_file_environment.html
puppetserver 配置说明：https://docs.openvoxproject.org/openvox-server/latest/config_file_puppetserver.html
Hiera 5 文档：https://docs.openvoxproject.org/openvox/latest/hiera_intro.html
站内：《OpenVox 介绍与选型指南》
站内：《OpenVox 9.1.0 Ubuntu 22.04 安装指南》

OpenVox 9.1.0 配置参数详解

OpenVox 9.1.0 配置参数详解

一、环境信息

1.1 实测基线

1.2 本篇涉及的配置文件

二、配置文件体系总览

2.1 四个层次

2.2 一个参数在多处出现时谁生效

三、puppet.conf 的结构与段优先级

3.1 当前生效的完整内容

3.2 段名与别名

3.3 三段取值实测对照

四、[main] 段关键参数

4.1 目录类参数

4.2 环境与清单类参数

4.3 行为类参数

4.4 模块路径

五、[server] 段关键参数

5.1 服务端目录与文件

5.2 证书相关参数

5.3 默认证书有效期

六、[agent] 段关键参数

6.1 定位服务端

6.2 运行行为

6.3 配置写入与复核

七、puppetserver 的 conf.d 配置

7.1 webserver.conf：监听地址与端口

7.2 puppetserver.conf：JRuby 与目录

7.3 ca.conf：CA 行为

八、auth.conf 授权规则

8.1 文件形态与匹配顺序

8.2 出厂规则清单

8.3 常见改法

九、Hiera 5 与数据分层

9.1 全局配置是空层级

9.2 环境级配置与数据文件

9.3 查询与调试

9.4 层级设计建议

十、目录环境与环境级配置

10.1 目录结构

10.2 environment.conf 的默认值

10.3 新增环境

十一、证书与自动签发（autosign）

11.1 打开 autosign

11.2 自动签发的实测效果

11.3 三种签发策略

11.4 证书与配置的一致性

十二、配置变更流程与排障

12.1 标准变更流程

12.2 puppet.conf 改了不生效

12.3 Hiera 取不到值

12.4 auth.conf 改完 403

十三、参考链接

12.2 `puppet.conf` 改了不生效