OpenVox 9.1.0 常用 CLI 与运维命令详解

目标：把日常运维真正会用到的命令按「触发收敛 / 证书 / 本地执行 / 查配置 / 查事实 / 管模块 / 看健康 / 排障」归类，每条命令给实测输入与逐行回显。基线为 2026-10-28 的 Ubuntu 22.04.5 LTS + openvox-server 9.1.0 + openvox-agent 9.1.0；安装与配置背景见《OpenVox 9.1.0 Ubuntu 22.04 安装指南》与《OpenVox 9.1.0 配置参数详解》。

一、环境信息

1.1 命令位置与 PATH

OpenVox 的可执行文件全部落在 /opt/puppetlabs/bin，默认不在 PATH 中：

$ ls /opt/puppetlabs/bin
facter
puppet
puppetserver

三种可用方式：

# 方式一：写全路径
$ /opt/puppetlabs/bin/puppet --version
9.1.0

# 方式二：临时加入 PATH
$ export PATH=/opt/puppetlabs/bin:$PATH
$ puppet --version
9.1.0

# 方式三：建软链（全系统可用）
$ ln -s /opt/puppetlabs/bin/puppet /usr/local/bin/puppet

后文的命令一律写全路径，方便直接复制；已把该目录加入 PATH 的读者可省略前缀。

1.2 版本确认

$ /opt/puppetlabs/bin/puppet --version
9.1.0
$ /opt/puppetlabs/bin/puppetserver --version
puppetserver version: 9.1.0
$ /opt/puppetlabs/bin/puppet agent --version
9.1.0

三个命令都指向同一版本线：puppet 是 CLI 主程序，puppetserver 是服务端管理脚本，puppet agent --version 是子命令形式。

二、命令总览与帮助

2.1 顶层子命令清单

$ /opt/puppetlabs/bin/puppet --help
Usage: puppet <subcommand> [options] <action> [options]

Available subcommands:
    
  Common:           
    agent             The puppet agent daemon provided by OpenVox
    apply             Apply Puppet manifests locally via OpenVox
    config            Interact with OpenVox's settings.
    help              Display OpenVox help.
    lookup            Interactive Hiera lookup for OpenVox
    module            Creates, installs and searches for modules on the Puppet Forge.
    resource          The OpenVox resource abstraction layer shell
  
                 
  Specialized:      
    catalog           Compile, save, view, and convert catalogs.
    describe          Display help about resource types available to OpenVox
    device            Manage remote network devices via OpenVox
    doc               Generate Puppet references for OpenVox
    epp               Interact directly with the EPP template parser/renderer.
    facts             Retrieve and store facts.
    filebucket        Store and retrieve files in an OpenVox filebucket
    generate          Generates Puppet code from Ruby definitions.
    node              View and manage node definitions.
    parser            Interact directly with the parser.
    plugin            Interact with the OpenVox plugin system.
    script            Run a puppet manifests as a script without compiling a catalog
    ssl               Manage SSL keys and certificates for OpenVox SSL clients

See 'puppet help <subcommand> <action>' for help on a specific subcommand action.
See 'puppet help <subcommand>' for help on a specific subcommand.
OpenVox v9.1.0

命令分为 Common（日常高频）与 Specialized（专项）两组。最后一行的 OpenVox v9.1.0 是版本标识，旧的 Puppet 包这里会显示 Puppet v8.x。

2.2 查子命令帮助的三种写法

$ /opt/puppetlabs/bin/puppet help agent
$ /opt/puppetlabs/bin/puppet agent --help
$ /opt/puppetlabs/bin/puppet help agent run

三种等价，输出都是 man 风格的 SYNOPSIS / USAGE / DESCRIPTION / OPTIONS 结构。子命令下还有 action 时（如 puppet module install），用 puppet help module install 查具体动作的参数。

三、puppet agent 日常操作

3.1 立即触发一次收敛

$ /opt/puppetlabs/bin/puppet agent -t
Info: Loading facts
Notice: Requesting catalog from openvox-master:8140 (10.89.63.2)
Notice: Catalog compiled by openvox-master
Info: Caching catalog for openvox-master
Info: Applying configuration version '1793124112'
Notice: /Stage[main]/Profile::Baseline/File[/etc/motd]/ensure: defined content as '{sha256}ba311a5f7b8494363f3af525e86f0a0baf625d5d0a32cc3b05273b23aa3dcf33'
Notice: /Stage[main]/Profile::Baseline/Package[nginx]/ensure: created
Notice: Applied catalog in 6.50 seconds

-t 是 --test 的短选项，等价于「前台运行一次 + 详细日志 + --detailed-exitcodes」。常用变体：

命令	作用
`puppet agent -t`	立即收敛一次，前台输出
`puppet agent -t --noop`	只报告会改什么，不动系统
`puppet agent -t --debug`	输出协议级调试日志，排证书/网络问题用
`puppet agent -t --tags nginx`	只应用带该标签的资源，灰度新类
`puppet agent -t --environment staging`	临时用指定环境的目录
`puppet agent -t --fingerprint`	只打印本机证书/CSR 指纹，不收敛
`puppet agent -t -v`	详细模式，看到每个资源的检查过程

3.2 幂等与漂移修复

系统已在期望状态时，第二次运行只有一行：

$ /opt/puppetlabs/bin/puppet agent -t
Info: Loading facts
Notice: Requesting catalog from openvox-master:8140 (10.89.63.2)
Notice: Catalog compiled by openvox-master
Info: Caching catalog for openvox-master
Info: Applying configuration version '1793124129'
Notice: Applied catalog in 0.75 seconds

手工把服务停掉，再跑一次，agent 会把漂移拉回：

$ systemctl stop nginx
$ systemctl is-active nginx
inactive
$ /opt/puppetlabs/bin/puppet agent -t
Info: Retrieving pluginfacts
Info: Retrieving plugin
Info: Loading facts
Notice: Requesting catalog from openvox-master:8140 (10.89.63.2)
Notice: Catalog compiled by openvox-master
Info: Caching catalog for openvox-master
Info: Applying configuration version '1793124139'
Notice: /Stage[main]/Profile::Baseline/Service[nginx]/ensure: ensure changed 'stopped' to 'running'
Info: /Stage[main]/Profile::Baseline/Service[nginx]: Unscheduling refresh on Service[nginx]
Notice: Applied catalog in 0.86 seconds
$ systemctl is-active nginx
active

ensure changed 'stopped' to 'running' 就是漂移被纠正的证据。

3.3 演练模式

$ /opt/puppetlabs/bin/puppet agent -t --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 就是没有真正落地。--noop 适合上线前预演，尤其是动服务、动配置文件的类。

3.4 暂停与恢复节点

$ /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
$ ls /opt/puppetlabs/puppet/cache/state/agent_disabled.lock
ls: cannot access '/opt/puppetlabs/puppet/cache/state/agent_disabled.lock': No such file or directory

--disable 不停止守护进程，只是让它每次运行前检查锁文件并跳过。做系统维护、避免被配置回滚时用这条，比 systemctl stop puppet 更轻。

3.5 退出码

--test 默认带 --detailed-exitcodes，退出码有明确语义：

退出码	含义
0	成功，无变更、无失败（已在期望状态）
1	运行失败，或已有运行在进行中
2	成功，且有资源被变更
4	成功，但有资源失败
6	成功，但既有变更又有失败

实测两次连续运行：

$ /opt/puppetlabs/bin/puppet agent -t --detailed-exitcodes >/tmp/de.txt 2>&1; echo "exit=$?"
exit=2
$ /opt/puppetlabs/bin/puppet agent -t --detailed-exitcodes >/tmp/de2.txt 2>&1; echo "second-exit=$?"
second-exit=0

第一次把 /etc/motd 从 web02 改回 openvox-master，退出码 2；第二次无变更，退出码 0。在 cron/定时任务里用退出码判断成败时，2 和 0 都算成功，不能只认 0，否则每次有正常变更都会误报告警。

四、证书管理：puppetserver ca

4.1 动作清单

$ /opt/puppetlabs/bin/puppetserver ca --help
Usage: puppetserver ca <action> [options]

Manage the Private Key Infrastructure for
Puppet Server's built-in Certificate Authority

Available Actions:

  Certificate Actions (requires a running Puppet Server):

    clean	Revoke cert(s) and remove related files from CA
    generate	Generate a new certificate signed by the CA
    list	List certificates and CSRs
    revoke	Revoke certificate(s)
    sign	Sign certificate request(s)

  Administrative Actions (requires Puppet Server to be stopped):

    delete	Delete signed certificate(s) from disk
    import	Import an external CA chain and generate server PKI
    setup	Setup a self-signed CA chain for Puppet Server
    enable	Setup infrastructure CRL based on a node inventory.
    migrate	Migrate the existing CA directory to /etc/puppetlabs/puppetserver/ca
    prune	Prune the local CRL on disk to remove certificate entries

General Options:
        --help                       Display this general help output
        --version                    Display the version
        --verbose                    Display low-level information

动作分成两类，选错会直接报错：

服务运行时可做：clean、generate、list、revoke、sign；
必须停服务才可做：delete、import、setup、enable、migrate、prune。这类动作要独占 CA 目录，服务在跑时会提示先停 puppetserver。

4.2 列出证书与待签请求

$ /opt/puppetlabs/bin/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"]

--all 同时列出已签与待签；不加只显示待签请求。只看某台：

$ /opt/puppetlabs/bin/puppetserver ca list --certname web02.example.com

需要交给自动化处理时输出 JSON：

$ /opt/puppetlabs/bin/puppetserver ca list --all --format json
{"requested":[],"signed":[{"name":"openvox-master","dns_alt_names":["DNS:puppet","DNS:openvox-master"],"state":"signed","authorization_extensions":{"pp_cli_auth":"true"},"subject_alt_names":["DNS:puppet","DNS:openvox-master"],"not_before":"2026-10-26T17:54:56UTC","serial_number":2,"fingerprint":"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"},{"name":"web02.example.com","state":"signed","subject_alt_names":["DNS:web02.example.com"],"not_before":"2026-10-26T18:03:27UTC","serial_number":4,"fingerprint":"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"}],"revoked":[]}

JSON 里有 not_before / not_after / serial_number，做证书到期巡检时直接解析这三个字段，不用正则刮文本。

4.3 签发、撤销与清理

新节点 web01.example.com 首次跑 agent 只提交 CSR：

$ /opt/puppetlabs/bin/puppet agent -t
Info: Creating a new RSA SSL key for web01.example.com
Info: csr_attributes file loading from /etc/puppetlabs/puppet/csr_attributes.yaml
Info: Creating a new SSL certificate request for web01.example.com
Info: Certificate Request fingerprint (SHA256): 3F:4A:0D:C3:EE:09:22:2D:3F:68:A4:89:4D:C3:4C:41:9D:F6:C0:31:02:93:DF:B6:6E:82:1A:79:D0:3F:66:F6
Info: Certificate for web01.example.com has not been signed yet
Couldn't fetch certificate from CA server; you might still need to sign this agent's certificate (web01.example.com).
Exiting now because the waitforcert setting is set to 0.

服务端看到请求：

$ /opt/puppetlabs/bin/puppetserver ca list
Requested Certificates:
    web01.example.com       (SHA256)  3F:4A:0D:C3:EE:09:22:2D:3F:68:A4:89:4D:C3:4C:41:9D:F6:C0:31:02:93:DF:B6:6E:82:1A:79:D0:3F:66:F6

核对指纹与客户端输出一致后再签：

$ /opt/puppetlabs/bin/puppetserver ca sign --certname web01.example.com
Successfully signed the following certificate requests:
  web01.example.com

撤销并清理：

$ /opt/puppetlabs/bin/puppetserver ca clean --certname web01.example.com
Certificate for web01.example.com has been revoked
Cleaned files related to web01.example.com

clean = revoke + 删本地证书/CSR 文件；只 revoke 不删文件，节点再次申请会因同名证书已存在而失败（除非 allow_duplicate_certs = true）。

4.4 `puppet cert` 已移除

OpenVox 9 删掉了旧的 puppet cert 子命令，任何旧脚本都会直接报错：

$ /opt/puppetlabs/bin/puppet cert list --all
Error: Unknown subcommand 'cert'
See 'puppet help' for help on available subcommands

迁移对照：

旧命令	新命令
`puppet cert list`	`puppetserver ca list`
`puppet cert list --all`	`puppetserver ca list --all`
`puppet cert sign <名>`	`puppetserver ca sign --certname <名>`
`puppet cert clean <名>`	`puppetserver ca clean --certname <名>`
`puppet cert revoke <名>`	`puppetserver ca revoke --certname <名>`

puppet ssl 子命令仍然保留，用于客户端侧证书操作（见第九章）。

五、puppet apply 本地执行

5.1 执行本地清单

puppet apply 不经过服务端，直接在本地编译并应用清单，适合单机自管理、模块调试、上线前验证。

# /root/demo.pp
notice("hello from openvox ${::os[\"name\"]}")
file { "/tmp/openvox-demo.txt":
  ensure  => file,
  content => "managed by puppet apply\n",
}

$ /opt/puppetlabs/bin/puppet apply /root/demo.pp
Notice: Scope(Class[main]): hello from openvox Ubuntu 22.04
Notice: Compiled catalog for openvox-master in environment production in 0.01 seconds
Notice: /Stage[main]/Main/File[/tmp/openvox-demo.txt]/ensure: defined content as '{sha256}09aca433255bf15e29960af815b5029f7c895709e615a36f472410b190492f0e'
Notice: Applied catalog in 0.01 seconds

Scope(Class[main]) 那行是 notice() 函数的输出，证明 facts 在本机可用（::os["name"] 取到 Ubuntu）。

⚠️ 注意：不要用 puppet apply -e 在 Bash 里直接写含 Puppet 插值语法的清单。Puppet 的插值写法会被 shell 先行解析，报 bad substitution 且不执行任何 Puppet 代码。清单写进文件再 puppet apply <文件> 是最稳的方式。

5.2 语法检查与演练

$ /opt/puppetlabs/bin/puppet parser validate /root/demo.pp
$ /opt/puppetlabs/bin/puppet apply --noop /root/demo.pp
Notice: Scope(Class[main]): hello from openvox Ubuntu 22.04
Notice: Compiled catalog for openvox-master in environment production in 0.01 seconds
Notice: Applied catalog in 0.00 seconds
noop-exit=0

parser validate 无输出即语法通过；--noop 只编译不落地，第二次跑时该文件资源已在期望状态，连 diff 都不打印。

5.3 apply 与服务端模式的区别

维度	`puppet apply`	`puppet agent -t`
目录来源	本地编译	服务端编译后下发
需要服务端	否	是
需要证书	否	是
Hiera 数据	读本机环境配置	读服务端环境配置
适用	单机、调试、应急	规模化统一管理

模块开发时先用 puppet apply 在本地跑通，再推到服务端环境，是效率最高的路径。

六、puppet config 查询与修改

6.1 查询全部与单项

$ /opt/puppetlabs/bin/puppet config print all --section main | wc -l
234

当前版本共 234 个可查配置项。查常用项：

$ /opt/puppetlabs/bin/puppet config print certname codedir environment hiera_config report runinterval server ssldir strict_variables vardir basemodulepath
basemodulepath = /etc/puppetlabs/code/modules:/opt/puppetlabs/puppet/modules
certname = openvox-master
codedir = /etc/puppetlabs/code
environment = production
hiera_config = /etc/puppetlabs/puppet/hiera.yaml
report = true
runinterval = 1800
server = puppet
ssldir = /etc/puppetlabs/puppet/ssl
strict_variables = true
vardir = /opt/puppetlabs/puppet/cache

输出按字母序排列，与命令里键名的书写顺序无关；puppet config print 后跟多个键名时只输出指定的键，不带全量。

6.2 分段查询

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

同一个键在三段取值不同是正常的：[main] 是兜底，[agent] 是客户端实际使用，[server] 是服务端实际使用。判断「某个配置是否生效」时，先确认查的是不是运行角色对应的段。

6.3 修改与删除

$ /opt/puppetlabs/bin/puppet config set runinterval 10m --section agent
$ /opt/puppetlabs/bin/puppet config print runinterval --section agent
600
$ /opt/puppetlabs/bin/puppet config delete runinterval --section agent
Deleted setting from 'agent': 'runinterval = 600'

set 无输出、delete 有回显，这是两者的固定行为。runinterval 写 10m 会被换算成 600 秒显示；删除后回到默认 1800。

七、资源与事实查询

7.1 `puppet resource`：把系统现状翻译成清单

$ /opt/puppetlabs/bin/puppet resource package nginx
package { 'nginx':
  ensure   => '1.18.0-6ubuntu14.22',
  mark     => 'none',
  provider => 'apt',
}

输出就是可直接粘进清单的 Puppet 代码，这是「逆向生成基线」最快的办法。查服务：

$ /opt/puppetlabs/bin/puppet resource service nginx
service { 'nginx':
  ensure   => 'running',
  enable   => 'true',
  provider => 'systemd',
}

puppet resource 只读不改；加上属性赋值就会真正修改系统（如 puppet resource service nginx ensure=running），生产环境慎用。

7.2 `puppet describe`：查资源类型支持哪些属性

$ /opt/puppetlabs/bin/puppet describe user
user
====
Manage users.  This type is mostly built to manage system
users, so it is lacking some features useful for managing normal
users.
This resource type uses the prescribed native tools for creating
groups and generally uses POSIX APIs for retrieving information
about them.  It does not directly modify `/etc/passwd` or anything.
**Autorequires:** If OpenVox is managing the user's primary group (as
provided in the `gid` attribute) or any group listed in the `groups`
attribute then the user resource will autorequire that group. If OpenVox

写清单时不确定属性名，先 puppet describe <类型>，比翻文档快。

7.3 `puppet facts`：查看本机事实

$ /opt/puppetlabs/bin/puppet facts show os
{
  "os": {
    "architecture": "amd64",
    "distro": {
      "codename": "jammy",
      "description": "Ubuntu 22.04.5 LTS",
      "id": "Ubuntu",
      "release": {
        "full": "22.04",
        "major": "22.04"
      }
    },
    "family": "Debian",
    "hardware": "x86_64",

事实是清单里做条件判断的依据（$facts['os']['family'] == 'Debian'）。查全部事实用 puppet facts show，输出很大，建议加 --json 后用 jq 过滤。

7.4 `puppet lookup`：查 Hiera 数据

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

  '
$ /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"

--explain 会打印每一层的查找过程与 No such key，是排查「参数没取到」的第一入口。注意 --node <名> 需要该节点事实在缓存中，否则报 No facts available for target node。

八、puppet module 模块管理

8.1 已装模块

$ /opt/puppetlabs/bin/puppet module list --tree
/etc/puppetlabs/code/environments/production/modules
├── profile (???)
└── puppetlabs-stdlib (v10.1.1)
/etc/puppetlabs/code/modules (no modules installed)
/opt/puppetlabs/puppet/modules (no modules installed)

profile 显示 ??? 是因为它没有 metadata.json（手写的本地模块），其余模块会显示版本号。三个路径分别对应「当前环境」「全局 basemodulepath」「包内置」。

8.2 安装、升级、卸载

$ /opt/puppetlabs/bin/puppet module install puppetlabs-stdlib --force
Notice: Preparing to install into /etc/puppetlabs/code/environments/production/modules ...
Notice: Downloading from https://forgeapi.puppet.com ...
Notice: Installing -- do not interrupt ...
/etc/puppetlabs/code/environments/production/modules
└── puppetlabs-stdlib (v10.1.1)

（以上三行 Notice 末尾的省略号是程序原样输出，不是本文省略。）

不加 --force 时若已存在同版本会报 "already installed"；--force 用于覆盖。其他动作：

命令	作用
`puppet module install <作者-模块>`	从 Forge 安装到当前环境
`puppet module install <模块> --version 10.1.1`	锁定版本
`puppet module upgrade <模块>`	升级
`puppet module uninstall <模块>`	卸载
`puppet module changes <模块>`	查看本地被改过的文件，升级前必跑
`puppet module list --tree`	以树形展示依赖与安装位置

生产环境升级模块前先 changes，确认没有本地魔改，否则升级会覆盖。

九、SSL 与服务健康检查

9.1 校验本机证书链

$ /opt/puppetlabs/bin/puppet ssl verify
Notice: Verified CA certificate 'CN=Puppet CA: openvox-master' fingerprint (SHA256) 4C:C0:BF:CE:71:07:E5:19:32:88:4D:72:B5:DD:1E:51:59:3A:87:90:CE:3B:9A:C1:67:23:51:DD:5A:58:B3:44
Notice: Verified client certificate 'CN=openvox-master' fingerprint (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

两行 Notice 都出现即 CA 证书与客户端证书都验证通过；只有第一行说明客户端证书缺失或不可信，查 /etc/puppetlabs/puppet/ssl。

9.2 HTTP 状态接口

$ curl -k -s -o /dev/null -w '%{http_code}\n' https://localhost:8140/status/v1/simple
200
$ curl -k -s https://localhost:8140/status/v1/simple
running
$ curl -k -s https://localhost:8140/status/v1/services/puppet-profiler
{"service_version":"9.1.0","service_status_version":1,"detail_level":"info","state":"running","status":{},"active_alerts":[],"service_name":"puppet-profiler"}

/status/v1/simple 免证书，适合探针；/status/v1/services 需要认证，给的是逐服务明细。监控接入时优先用 simple，避免证书过期把健康检查一起拖挂。

十、日志与排障

10.1 日志位置

日志	路径	内容
服务端主日志	`/var/log/puppetlabs/puppetserver/puppetserver.log`	启动、CA 签发、目录编译
服务端访问日志	`/var/log/puppetlabs/puppetserver/puppetserver-access.log`	每个 HTTPS 请求
服务端状态日志	`/var/log/puppetlabs/puppetserver/puppetserver-status.log`	状态接口调用
服务端 JVM 崩溃	`/var/log/puppetlabs/puppetserver/puppetserver_err_pid<pid>.log`	仅崩溃时生成
agent 日志	`/var/log/puppetlabs/puppet/agent.log`	需显式指定 `--logdest` 才落盘

实测目录：

$ ls -l /var/log/puppetlabs/puppetserver/
-rw-r--r-- 1 root   root        0 Oct 27 17:54 puppetserver-access.log
-rw-r----- 1 puppet puppet      0 Oct 27 17:53 puppetserver-status.log
-rw-r----- 1 puppet puppet 510330 Oct 27 18:03 puppetserver.log

agent 默认把日志打到终端，要落盘就显式指定：

$ /opt/puppetlabs/bin/puppet agent -t --logdest /var/log/puppetlabs/puppet/agent.log
$ tail -3 /var/log/puppetlabs/puppet/agent.log
2026-10-27 18:29:02 +0000 Puppet (info): Caching catalog for openvox-master
2026-10-27 18:29:02 +0000 Puppet (info): Applying configuration version '1793125742'
2026-10-27 18:29:03 +0000 Puppet (notice): Applied catalog in 0.82 seconds

--logdest 可选 syslog、eventlog、console 或绝对路径。守护进程模式（systemd）下由单元文件里的配置决定，默认写 journal。

10.2 看日志的正确顺序

# 1. 服务状态
$ systemctl status puppetserver --no-pager | head -8
● puppetserver.service - puppetserver Service
     Loaded: loaded (/lib/systemd/system/puppetserver.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2026-10-27 18:05:19 UTC; 12min ago
   Main PID: 10130 (java)
      Tasks: 64 (limit: 4915)
     Memory: 873.7M
        CPU: 37.928s

# 2. systemd 侧启动记录
$ journalctl -u puppetserver --no-pager | tail -5
Oct 27 18:19:15 openvox-offline java[4887]: 18:19:15,387 |-INFO in ch.qos.logback.access.common.joran.JoranConfigurator@600e2e6f - Registering current configuration as safe fallback point
Oct 27 18:19:15 openvox-offline systemd[1]: Started puppetserver Service.

# 3. 应用侧主日志
$ tail -5 /var/log/puppetlabs/puppetserver/puppetserver.log
2026-10-27T18:02:56.651Z INFO  [async-mixed-1] [p.s.c.certificate-authority-service] Starting CA service
2026-10-27T18:02:56.653Z INFO  [async-mixed-1] [p.s.m.master-service] OpenVox Server has successfully started and is now ready to handle requests
2026-10-27T18:02:56.654Z INFO  [async-mixed-1] [p.t.internal] Sending sd_notify message to NOTIFY_SOCKET "/run/systemd/notify": "READY=1\n"
2026-10-27T18:02:58.191Z INFO  [pool-2-thread-2] [puppetserver] Puppet Puppet settings initialized; run mode: server
2026-10-27T18:02:59.855Z INFO  [pool-2-thread-2] [p.s.j.i.jruby-agents] Finished creating JRubyInstance 2 of clojure.core$count@7977527f

先看 systemd 状态 → 再看 journal 里的启动失败原因 → 最后看应用日志的业务细节。三步都无异常再去看访问日志与 agent 端。

10.3 三类高频故障

现象	日志关键字	处理
服务起不来、每 5 秒重启	`can't find user for 0` / `Cannot determine basic system flavour`	`/tmp` 被 noexec 挂载，`mount -o remount,exec /tmp`；详见安装篇 9.1
证书命令 500	`ca_key.pem (Permission denied)`	`chown -R puppet:puppet /etc/puppetlabs/puppetserver/ca`；详见安装篇 9.2
agent 拿不到目录	`Couldn't fetch certificate from CA server`	证书未签，`puppetserver ca list` → `sign`

10.4 agent 端排障

$ /opt/puppetlabs/bin/puppet agent -t --debug 2>&1 | grep -iE "certificate|catalog|http" | head -12
Debug: Applying settings catalog for sections main, agent, ssl
Debug: Using settings: adding file resource 'requestdir': 'File[/etc/puppetlabs/puppet/ssl/certificate_requests]{path: "/etc/puppetlabs/puppet/ssl/certificate_requests", mode: "755", owner: "puppet", group: "puppet", ensure: :directory, loglevel: :debug, links: :follow, backup: false}'
Debug: /File[/etc/puppetlabs/puppet/ssl/certificate_requests]: Adding autorequire relationship with File[/etc/puppetlabs/puppet/ssl]
Debug: Verified CA certificate 'CN=Puppet CA: openvox-master' fingerprint (SHA256) 4C:C0:BF:CE:71:07:E5:19:32:88:4D:72:B5:DD:1E:51:59:3A:87:90:CE:3B:9A:C1:67:23:51:DD:5A:58:B3:44
Debug: Verified client certificate 'CN=openvox-master' fingerprint (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
Debug: Environment not passed via CLI and no catalog was given, attempting to find out the last server-specified environment
Debug: Resolving service 'fileserver' using Puppet::HTTP::Resolver::Settings
Debug: Creating new connection for https://openvox-master:8140
Debug: Starting connection for https://openvox-master:8140
Debug: Caching connection for https://openvox-master:8140
Debug: Resolved service 'fileserver' to https://openvox-master:8140/puppet/v3
Debug: Using cached connection for https://openvox-master:8140

--debug 会打印 HTTP 请求、证书校验、catalog 解析的每一步，输出量很大，务必配 grep 过滤。常见的「拿不到目录」检查顺序：

ping/getent hosts 确认服务端主机名可解析；
curl -k https://openvox-master:8140/status/v1/simple 确认服务端可达；
puppet ssl verify 确认证书链；
puppetserver ca list 确认本机证书已签；
最后才查 auth.conf 与目录编译错误。

十一、常用命令速查表

目的	命令
立即收敛一次	`puppet agent -t`
演练不落地	`puppet agent -t --noop`
只看指定类	`puppet agent -t --tags <类名>`
临时换环境	`puppet agent -t --environment <环境名>`
暂停/恢复节点	`puppet agent --disable "<原因>"` / `puppet agent --enable`
看本机证书指纹	`puppet agent -t --fingerprint`
列证书/待签	`puppetserver ca list --all`
签发	`puppetserver ca sign --certname <名>`
撤销并清理	`puppetserver ca clean --certname <名>`
本地执行清单	`puppet apply <文件.pp>`
语法检查	`puppet parser validate <文件.pp>`
查配置	`puppet config print <键> --section <段>`
改/删配置	`puppet config set/delete <键> <值> --section <段>`
系统现状转清单	`puppet resource <类型> <名>`
查资源属性	`puppet describe <类型>`
查事实	`puppet facts show <事实路径>`
查 Hiera	`puppet lookup <键> [--explain]`
装模块	`puppet module install <作者-模块>`
列模块	`puppet module list --tree`
校验证书链	`puppet ssl verify`
健康检查	`curl -k https://<服务端>:8140/status/v1/simple`
看服务端日志	`tail -f /var/log/puppetlabs/puppetserver/puppetserver.log`

十二、参考链接

OpenVox 官方文档：https://docs.openvoxproject.org/
命令行参考：https://docs.openvoxproject.org/openvox/latest/commands.html
puppet agent 手册：https://docs.openvoxproject.org/openvox/latest/man/agent.html
puppetserver ca 说明：https://docs.openvoxproject.org/openvox-server/latest/subcommands.html
站内：《OpenVox 介绍与选型指南》
站内：《OpenVox 9.1.0 Ubuntu 22.04 安装指南》
站内：《OpenVox 9.1.0 配置参数详解》

OpenVox 9.1.0 常用 CLI 与运维命令详解

OpenVox 9.1.0 常用 CLI 与运维命令详解

一、环境信息

1.1 命令位置与 PATH

1.2 版本确认

二、命令总览与帮助

2.1 顶层子命令清单

2.2 查子命令帮助的三种写法

三、puppet agent 日常操作

3.1 立即触发一次收敛

3.2 幂等与漂移修复

3.3 演练模式

3.4 暂停与恢复节点

3.5 退出码

四、证书管理：puppetserver ca

4.1 动作清单

4.2 列出证书与待签请求

4.3 签发、撤销与清理

4.4 puppet cert 已移除

五、puppet apply 本地执行

5.1 执行本地清单

5.2 语法检查与演练

5.3 apply 与服务端模式的区别

六、puppet config 查询与修改

6.1 查询全部与单项

6.2 分段查询

6.3 修改与删除

七、资源与事实查询

7.1 puppet resource：把系统现状翻译成清单

7.2 puppet describe：查资源类型支持哪些属性

7.3 puppet facts：查看本机事实

7.4 puppet lookup：查 Hiera 数据

八、puppet module 模块管理

8.1 已装模块

8.2 安装、升级、卸载

九、SSL 与服务健康检查

9.1 校验本机证书链

9.2 HTTP 状态接口

十、日志与排障

10.1 日志位置

10.2 看日志的正确顺序

10.3 三类高频故障

10.4 agent 端排障

十一、常用命令速查表

十二、参考链接

4.4 `puppet cert` 已移除

7.1 `puppet resource`：把系统现状翻译成清单

7.2 `puppet describe`：查资源类型支持哪些属性

7.3 `puppet facts`：查看本机事实

7.4 `puppet lookup`：查 Hiera 数据