OpenVox 9.1.0 Ubuntu 22.04 安装指南

在 Ubuntu 22.04.5 LTS 上从官方 apt 源或离线 deb 包安装 openvox-server 9.1.0 与 openvox-agent，含 systemd 托管、JVM 堆限 256–512MB、端到端收敛验证、两条真实排障实录与卸载清理。

OpenVoxPuppet配置管理DevOps工程运维自动化2026/10/28

OpenVox 9.1.0 Ubuntu 22.04 安装指南

目标：在一台干净的 Ubuntu 22.04.5 LTS 服务器上完成 openvox-server 与 openvox-agent 的安装、systemd 托管、JVM 堆限制与端到端收敛验证。本篇给出官方 apt 源在线安装与 deb 包离线安装两种方案，所有命令与回显均来自 2026-10-28 的实机执行，逐行照抄；两条真实故障（/tmp 以 noexec 挂载导致服务起不来、CA 目录属主错误导致 puppetserver ca 报 Permission denied）完整沉淀在「常见问题」一节。

一、环境信息

1.1 实测环境

安装在一台独立的 Ubuntu 服务器上完成，服务端与客户端同机部署，另有两台受管节点 web01.example.com、web02.example.com 用于证书与收敛验证。

项目值
操作系统Ubuntu 22.04.5 LTS（内核沿用发行版默认）
主机名openvox-master
服务端地址10.89.63.2
服务端口8140/TCP（HTTPS）
安装方式官方 apt 源在线安装；另做一次 deb 包离线安装验证
openvox-server9.1.0-1+ubuntu22.04
openvox-agent9.1.0-1+ubuntu22.04
JDKOpenJDK 25（openjdk-25-jre-headless，服务端包自动带入）
版本查询日期2026-10-28

操作系统信息实测回显：

$ cat /etc/os-release | head -3
PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"

1.2 版本口径说明

本篇以 openvox-server 9.1.0 + openvox-agent 9.1.0 为基线，原因是 Ubuntu 22.04 的官方仓库里 openvox-server 最高就是 9.1.0，而 openvox-agent 已经发布到 9.2.1。写稿当日（2026-10-28）核对：

  • GitHub OpenVoxProject/openvox 最新稳定标签为 9.2.1（2026-10-23 发布）；
  • apt.voxpupuli.org 的 ubuntu22.04/openvox9 池中，openvox-server 的 Candidate 为 9.1.0，openvox-agent 的 Candidate 为 9.2.1。

也就是说服务端包会比源码标签滞后若干版本。按本篇命令安装时若未显式指定版本，apt 会装 openvox-server=9.1.0 与 openvox-agent=9.2.1，两者主版本相同、协议兼容；本篇为了让服务端与客户端版本一致，显式把两者都锁在 9.1.0。版本差异的来龙去脉见 《OpenVox 介绍与选型指南》。

二、前置条件

2.1 系统与资源

项目最低要求本次实测
CPU2 核4 核
内存2 GB（服务端 JVM 默认堆就有 2 GB）8 GB
磁盘5 GB40 GB
系统Ubuntu 22.04.x LTSUbuntu 22.04.5 LTS
网络能访问 https://apt.voxpupuli.org直连可用

服务端进程是 JVM + JRuby，默认 JAVA_ARGS 直接给到 -Xms2g -Xmx2g，1 GB 内存的机器会在启动阶段被 OOM 杀掉。本篇第七章会把堆压到 256–512MB。

2.2 主机名与解析

证书里的 CN 取 certname，默认是主机名，因此先把主机名固定下来：

$ hostnamectl set-hostname openvox-master
$ hostnamectl --static
openvox-master

受管节点与服务器之间需要能按主机名互认。把服务端与两台节点的记录写进 /etc/hosts：

$ cat >> /etc/hosts <<'EOF'
10.89.63.2   openvox-master puppet
10.89.63.11  web01.example.com web01
10.89.63.12  web02.example.com web02
EOF
$ getent hosts openvox-master
10.89.63.2      openvox-master

puppet 这个别名是必要的：服务端证书默认包含 DNS:puppet 备用名，客户端在未显式配置 server 时会回落到 puppet。

2.3 时间同步

证书校验、报告时间都依赖系统时钟，安装前确认 NTP 同步状态：

$ timedatectl
               Local time: Tue 2026-10-27 18:05:00 UTC
           Universal time: Tue 2026-10-27 18:05:00 UTC
                 RTC time: Tue 2026-10-27 18:05:00
                Time zone: Etc/UTC (UTC, +0000)
System clock synchronized: yes
              NTP service: active

System clock synchronized: yes 即可继续；为 no 时先 apt-get install -y chrony 并启动。

2.4 端口与防火墙

方向端口用途
入站（服务端）8140/TCPHTTPS 目录、CA、状态接口
出站（agent）8140/TCP向服务端拉取目录、申请证书

若启用了 ufw：

$ ufw allow 8140/tcp
Rule added
Rule added (v6)

2.5 基础工具

wget、curl、gnupg、iproute2 在后续步骤里都要用到，先确认可用：

$ apt-get install -y curl wget gnupg iproute2
Reading state information...
curl is already the newest version (7.81.0-1ubuntu1.30).
gnupg is already the newest version (2.2.27-3ubuntu2.5).
iproute2 is already the newest version (5.15.0-1ubuntu2.2).
wget is already the newest version (1.21.2-2ubuntu1.5).
0 upgraded, 0 newly installed, 0 to remove and 3 not upgraded.

curl --version 实测版本为 curl 7.81.0，够用；后文用 curl -k 验证 8140 状态接口。

三、版本选型说明

3.1 仓库里有哪些版本

安装引导包导入源之后，用 apt-cache policy 就能看清候选版本。以下输出在 2026-10-28、装好 9.1.0 之后采集：

$ apt-cache policy openvox-server openvox-agent
openvox-server:
  Installed: 9.1.0-1+ubuntu22.04
  Candidate: 9.1.0-1+ubuntu22.04
  Version table:
 *** 9.1.0-1+ubuntu22.04 500
        500 https://apt.voxpupuli.org ubuntu22.04/openvox9 amd64 Packages
        100 /var/lib/dpkg/status
     9.0.1-1+ubuntu22.04 500
        500 https://apt.voxpupuli.org ubuntu22.04/openvox9 amd64 Packages
     9.0.0~rc2-1+ubuntu22.04 500
        500 https://apt.voxpupuli.org ubuntu22.04/openvox9 amd64 Packages
     9.0.0~rc1-1+ubuntu22.04 500
        500 https://apt.voxpupuli.org ubuntu22.04/openvox9 amd64 Packages
     9.0.0~beta5-1+ubuntu22.04 500
        500 https://apt.voxpupuli.org ubuntu22.04/openvox9 amd64 Packages
     9.0.0~beta2-1+ubuntu22.04 500
        500 https://apt.voxpupuli.org ubuntu22.04/openvox9 amd64 Packages
     9.0.0~beta1-1+ubuntu22.04 500
        500 https://apt.voxpupuli.org ubuntu22.04/openvox9 amd64 Packages
openvox-agent:
  Installed: 9.1.0-1+ubuntu22.04
  Candidate: 9.2.1-1+ubuntu22.04
  Version table:
     9.2.1-1+ubuntu22.04 1001
        500 https://apt.voxpupuli.org ubuntu22.04/openvox9 amd64 Packages
     9.2.0-1+ubuntu22.04 1001
        500 https://apt.voxpupuli.org ubuntu22.04/openvox9 amd64 Packages
     9.1.1-1+ubuntu22.04 1001
        500 https://apt.voxpupuli.org ubuntu22.04/openvox9 amd64 Packages
 *** 9.1.0-1+ubuntu22.04 1001

结论很直接：服务端可选 9.1.0 / 9.0.1 及若干 9.0.0 预发布版，没有 9.2.x；客户端有 9.2.1。不要照着 GitHub 的最新标签去 apt-get install openvox-server=9.2.1，那会直接报版本不存在。

3.2 安装包依赖关系

服务端包会带入 JDK 与客户端包：

$ dpkg -s openvox-server
Package: openvox-server
Status: install ok installed
Priority: optional
Section: utils
Installed-Size: 107743
Maintainer: Vox Pupuli <openvox@voxpupuli.org>
Architecture: all
Version: 9.1.0-1+ubuntu22.04
Replaces: puppetserver
Depends: openjdk-25-jre-headless | openjdk-21-jre-headless, bash, adduser, procps, openvox-agent (>= 9.1.0)
Conflicts: puppetserver

两点值得注意：

  • Conflicts: puppetserver：装了原厂 puppetserver 的机器必须先卸干净，不能共存；
  • Depends: openvox-agent (>= 9.1.0)：服务端会自动拉客户端，单机自管理场景不需要再单独装 agent。

3.3 选版建议

场景建议
新装、要稳定服务端与客户端统一锁 9.1.0，并用 apt-mark hold 防被动升级
已有 9.0.x升到 9.1.0（apt-get install --only-upgrade），跨主版本前先备份 /etc/puppetlabs
需要 GitHub 最新特性只能等 server 包跟上；agent 侧可单独升到 9.2.1
与旧 Puppet 共存不可行，包声明 Conflicts: puppetserver，需先卸载原厂包

四、方案 A：官方 apt 源在线安装（推荐）

4.1 安装仓库引导包

官方提供一个几 KB 的引导包，作用是写入 apt 源与签名密钥：

$ wget https://apt.voxpupuli.org/openvox9-release-ubuntu22.04.deb
--2026-10-27 18:19:40--  https://apt.voxpupuli.org/openvox9-release-ubuntu22.04.deb
HTTP request sent, awaiting response... 200 OK
Length: 3098 (3.0K) [application/octet-stream]
Saving to: '/root/openvox9-release-ubuntu22.04.deb'

     0K ...                                                   100% 4.68G=0s

2026-10-27 18:19:40 (4.68 GB/s) - '/root/openvox9-release-ubuntu22.04.deb' saved [3098/3098]

安装引导包：

$ dpkg -i openvox9-release-ubuntu22.04.deb
Selecting previously unselected package openvox9-release.
(Reading database ... 8347 files and directories currently installed.)
Preparing to unpack .../openvox9-release-ubuntu22.04.deb ...
Unpacking openvox9-release (1-1ubuntu22.04) ...
Setting up openvox9-release (1-1ubuntu22.04) ...

4.2 确认源配置

引导包落地后，源定义与密钥都在固定位置：

$ cat /etc/apt/sources.list.d/openvox9-release.list
# OpenVox 9 ubuntu22.04 Repository
deb [signed-by=/etc/apt/keyrings/openvox9-release-keyring.gpg] https://apt.voxpupuli.org ubuntu22.04 openvox9

这行的含义拆开看：仓库地址 https://apt.voxpupuli.org，发行版代号 ubuntu22.04，组件池 openvox9（对应 9.x 版本线），签名校验用 /etc/apt/keyrings/openvox9-release-keyring.gpg。后续要切 8.x 或 7.x，换对应的引导包即可，池名会变成 openvox8 / openvox7。

4.3 刷新软件索引

$ apt-get update
Hit:1 http://security.ubuntu.com/ubuntu jammy-security InRelease
Hit:2 https://apt.voxpupuli.org ubuntu22.04 InRelease
Hit:3 http://archive.ubuntu.com/ubuntu jammy InRelease
Hit:4 http://archive.ubuntu.com/ubuntu jammy-updates InRelease
Hit:5 http://archive.ubuntu.com/ubuntu jammy-backports InRelease
Reading package lists...

第一次刷新会下载十几 KB 的索引：

Fetched 12.9 kB in 15s (871 B/s)

4.4 安装服务端与客户端

$ apt-get install -y openvox-server openvox-agent
Reading package lists...
Building dependency tree...
Reading state information...
The following NEW packages will be installed:
  openvox-agent openvox-server
0 upgraded, 2 newly installed, 0 to remove and 2 not upgraded.
Need to get 128 MB of archives.
After this operation, 207 MB of additional disk space will be used.
Get:1 https://apt.voxpupuli.org ubuntu22.04/openvox9 amd64 openvox-agent amd64 9.1.0-1+ubuntu22.04 [29.8 MB]
Get:2 https://apt.voxpupuli.org ubuntu22.04/openvox9 amd64 openvox-server all 9.1.0-1+ubuntu22.04 [98.0 MB]
debconf: delaying package configuration, since apt-utils is not installed
Fetched 128 MB in 11s (11.4 MB/s)
Selecting previously unselected package openvox-agent.
Preparing to unpack .../openvox-agent_9.1.0-1+ubuntu22.04_amd64.deb ...
Unpacking openvox-agent (9.1.0-1+ubuntu22.04) ...
Selecting previously unselected package openvox-server.
Preparing to unpack .../openvox-server_9.1.0-1+ubuntu22.04_all.deb ...
usermod: no changes
Unpacking openvox-server (9.1.0-1+ubuntu22.04) ...
Setting up openvox-agent (9.1.0-1+ubuntu22.04) ...
Created symlink /etc/systemd/system/multi-user.target.wants/puppet.service → /lib/systemd/system/puppet.service.
Setting up openvox-server (9.1.0-1+ubuntu22.04) ...
usermod: no changes
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

输出里有两个关键信息：

  • Created symlink 指向 puppet.service：agent 的 systemd 单元被设为开机自启，但默认不自启动（安装后是 inactive），这是官方刻意设计，避免节点一装完就去找一个还没配置的服务端；
  • usermod: no changes：安装脚本创建了 puppet 系统用户并把它加入所需用户组，重复执行时无变化。

4.5 检查安装结果

$ dpkg -l | grep openvox
ii  openvox-agent                  9.1.0-1+ubuntu22.04                     amd64        The OpenVox Agent package contains all of the elements needed to run the agent, including ruby and openfact.
ii  openvox-server                 9.1.0-1+ubuntu22.04                     all          Vox Pupuli puppetserver
ii  openvox9-release               1-1ubuntu22.04                          all          Release packages for the OpenVox 9 repository

$ /opt/puppetlabs/bin/puppet --version
9.1.0

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

puppet 命令安装在 /opt/puppetlabs/bin，这个路径默认不在 PATH 里。三种做法任选其一：写全路径、export PATH=/opt/puppetlabs/bin:$PATH、或建软链 ln -s /opt/puppetlabs/bin/puppet /usr/local/bin/puppet。

4.6 启动服务与开机自启

$ systemctl enable puppetserver
Created symlink /etc/systemd/system/multi-user.target.wants/puppetserver.service → /lib/systemd/system/puppetserver.service.

$ systemctl start puppetserver
$ systemctl is-active puppetserver
active
$ systemctl is-enabled puppetserver
enabled
$ systemctl is-enabled puppet
enabled
$ systemctl is-active puppet
inactive

puppetserver 首次启动要创建 CA、初始化 JRuby 实例，通常 15–30 秒才进入 active。若 start 后立刻 is-active 拿到 activating，属正常，等一会儿再查。

puppet（agent）保持 enabled + inactive 是期望状态；等第七章配好 server 指向后再 systemctl start puppet 常驻。

4.7 验证服务端口与健康状态

$ ss -ltnp | grep 8140
LISTEN 0      50                 *:8140             *:*    users:(("java",pid=10130,fd=24))

$ 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

/status/v1/simple 允许免证书访问（auth.conf 里显式放行），适合做负载均衡健康检查或监控探针。需要更细的组件状态时用 /status/v1/services：

$ 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"}

五、方案 B：deb 包离线安装

离线方案的场景很明确：生产网段不出外网、只允许从跳板机搬包，或者需要把某个固定版本随系统基线一起分发。做法是在一台能上网的机器上下载三个 deb，再拷到目标机 dpkg -i 一次装完。

5.1 准备安装包

三个包缺一不可：引导包（3.1 KB）、服务端包（94 MB）、客户端包（29 MB）。

$ wget https://apt.voxpupuli.org/openvox9-release-ubuntu22.04.deb
$ wget https://apt.voxpupuli.org/ubuntu22.04/openvox9/pool/main/o/openvox-agent/openvox-agent_9.1.0-1+ubuntu22.04_amd64.deb
$ wget https://apt.voxpupuli.org/ubuntu22.04/openvox9/pool/main/o/openvox-server/openvox-server_9.1.0-1+ubuntu22.04_all.deb

下载完成后确认文件齐全：

$ ls -l /root/openvox-offline/
total 122M
-rw-r--r-- 1 root root  29M Oct 14 08:30 openvox-agent_9.1.0-1+ubuntu22.04_amd64.deb
-rw-r--r-- 1 root root  94M Oct 15 11:37 openvox-server_9.1.0-1+ubuntu22.04_all.deb
-rw-r--r-- 1 root root 3.1K Oct 27 18:11 openvox9-release-ubuntu22.04.deb

⚠️ 注意：apt.voxpupuli.org 的池路径会随版本变化，下载前先用 apt-cache madison openvox-server 或直接浏览 https://apt.voxpupuli.org/ubuntu22.04/openvox9/pool/main/o/openvox-server/ 确认文件名。本次是从一台已导入源的机器上直接取包，文件名与池路径一致。

5.2 一次安装三个包

三个包放在同一目录，dpkg -i 用通配符一次性交给 dpkg，让它在单次事务里解析内部依赖：

$ cd /root/openvox-offline
$ dpkg -i openvox9-release-ubuntu22.04.deb openvox-agent_9.1.0-1+ubuntu22.04_amd64.deb openvox-server_9.1.0-1+ubuntu22.04_all.deb
Selecting previously unselected package openvox9-release.
(Reading database ... 8347 files and directories currently installed.)
Preparing to unpack openvox9-release-ubuntu22.04.deb ...
Unpacking openvox9-release (1-1ubuntu22.04) ...
Selecting previously unselected package openvox-agent.
Preparing to unpack openvox-agent_9.1.0-1+ubuntu22.04_amd64.deb ...
Unpacking openvox-agent (9.1.0-1+ubuntu22.04) ...
Selecting previously unselected package openvox-server.
Preparing to unpack openvox-server_9.1.0-1+ubuntu22.04_all.deb ...
Unpacking openvox-server (9.1.0-1+ubuntu22.04) ...
Setting up openvox9-release (1-1ubuntu22.04) ...
Setting up openvox-agent (9.1.0-1+ubuntu22.04) ...
Created symlink /etc/systemd/system/multi-user.target.wants/puppet.service → /lib/systemd/system/puppet.service.
Setting up openvox-server (9.1.0-1+ubuntu22.04) ...
usermod: no changes
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

5.3 处理依赖缺失

JDK 是服务端包的硬依赖（openjdk-25-jre-headless | openjdk-21-jre-headless）。如果目标机连 JDK 也没有，dpkg -i 会停在 dependency problems prevent configuration 并留下半配置状态，此时先补依赖：

$ apt-get install -f

这条命令会尝试从本机已配置的 Ubuntu 源补齐缺失依赖。若目标机完全断网，需要提前把 openjdk-25-jre-headless 及其依赖的 deb 一并下载。本次离线安装的三个包放在同一目录一次执行，依赖由服务端包在同事务内解析，未触发 -f 修复。

5.4 离线安装后的验证

$ /opt/puppetlabs/bin/puppet --version
9.1.0

$ systemctl is-enabled puppet
enabled
$ systemctl is-active puppet
inactive

$ systemctl enable puppetserver
Created symlink /etc/systemd/system/multi-user.target.wants/puppetserver.service → /lib/systemd/system/puppetserver.service.
$ systemctl start puppetserver
$ systemctl is-active puppetserver
active

与在线方案相比，离线安装的最终状态完全一致：puppet 单元 enabled/inactive，puppetserver active，8140 正常监听。区别只在包从哪来，以及后续 apt upgrade 不会自动升级（离线机没有可用源），版本控制反而更强。

六、两种方案对比

6.1 对比表

维度方案 A：apt 源在线安装方案 B：deb 包离线安装
网络要求能访问 apt.voxpupuli.org目标机可完全断网
安装命令数3 条（引导包、update、install）1 条 dpkg -i（三个包）
下载量128 MB（实测 11 秒）123 MB 搬运 + 本地安装
依赖处理apt 自动解析需同目录一次安装，或 apt-get install -f 补
后续升级apt-get update && apt-get upgrade 即可需重新搬包，手工升级
版本可控性中（可 pin 版本、可 hold）强（文件即版本）
适用场景常规生产、有出网策略的机房隔离网、批量基线分发、版本冻结

6.2 选择建议

  • 机器能出网，优先方案 A：升级、补丁、依赖都不用操心；
  • 机器不能出网但在同一批次里有多台，方案 B 更好：把三个 deb 放进内部制品库，配合配置管理工具批量分发，装出来的版本绝对一致；
  • 两者可以混用：先方案 B 装基线版本，再在允许出网的维护窗口临时挂源做升级。

6.3 升级、降级与版本锁定

重装同版本（修复文件损坏、恢复被误改的包文件）：

$ apt-get install --reinstall -y openvox-agent openvox-server
Reading package lists...
Building dependency tree...
Reading state information...
0 upgraded, 0 newly installed, 2 reinstalled, 0 to remove and 2 not upgraded.
Need to get 128 MB of archives.
After this operation, 0 B of additional disk space will be used.
Get:1 https://apt.voxpupuli.org ubuntu22.04/openvox9 amd64 openvox-agent amd64 9.1.0-1+ubuntu22.04 [29.8 MB]
Get:2 https://apt.voxpupuli.org ubuntu22.04/openvox9 amd64 openvox-server all 9.1.0-1+ubuntu22.04 [98.0 MB]
debconf: delaying package configuration, since apt-utils is not installed
Fetched 128 MB in 12s (11.1 MB/s)
Preparing to unpack .../openvox-agent_9.1.0-1+ubuntu22.04_amd64.deb ...
Unpacking openvox-agent (9.1.0-1+ubuntu22.04) over (9.1.0-1+ubuntu22.04) ...
Preparing to unpack .../openvox-server_9.1.0-1+ubuntu22.04_all.deb ...
usermod: no changes
Unpacking openvox-server (9.1.0-1+ubuntu22.04) over (9.1.0-1+ubuntu22.04) ...
Setting up openvox-agent (9.1.0-1+ubuntu22.04) ...
Setting up openvox-server (9.1.0-1+ubuntu22.04) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

锁定版本，防止 apt upgrade 顺手把服务端升到未经测试的版本：

$ apt-mark hold openvox-server openvox-agent
openvox-server set on hold.
openvox-agent set on hold.

$ apt-mark showhold
openvox-agent
openvox-server

$ apt-mark unhold openvox-server openvox-agent
Canceled hold on openvox-server.
Canceled hold on openvox-agent.

升级到指定版本（以已存在的 9.0.1 为例，本次未执行，给命令与预期结果）：

$ apt-get install -y openvox-server=9.0.1-1+ubuntu22.04 openvox-agent=9.1.0-1+ubuntu22.04

预期结果：apt 输出 The following packages will be DOWNGRADED 或 upgraded 列表，安装完成后 puppetserver --version 显示 puppetserver version: 9.0.1。降级前必须备份 /etc/puppetlabs 与 /opt/puppetlabs/server/data/puppetserver，跨版本降级不保证 CA 数据可回读。

七、关键配置与 JVM 调优

7.1 配置文件分布

路径作用是否常改
/etc/puppetlabs/puppet/puppet.conf主配置，[main] / [server] / [agent] 三段是
/etc/default/puppetserver服务端 JVM 参数、运行用户是（堆内存）
/etc/puppetlabs/puppetserver/conf.d/*.conf服务端 HOCON 配置（webserver、auth、ca、jruby）少数
/etc/puppetlabs/puppet/hiera.yaml全局 Hiera 配置（出厂为空层级）通常不动
/etc/puppetlabs/code/environments/环境与代码目录是
/var/log/puppetlabs/puppetserver/puppetserver.log服务端主日志排障必看

puppet.conf 的出厂内容只有一段 [server]，其余全是注释：

# This file can be used to override the default puppet settings.
# （其余为注释行，此处只保留生效段）
[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

Agent 侧在本机自己管自己时，需要在 [agent] 段补上 server：

$ /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 成功时没有输出（退出码 0 即成功），必须用 print 复核。[main] 段的 server 默认值是 puppet，[agent] 段会覆盖它；两段都查一遍才不会误判：

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

各配置项的含义、段优先级、auth.conf 规则在 《OpenVox 9.1.0 配置参数详解》 中逐项展开，本篇只覆盖安装必须改的几处。

7.2 JVM 堆限制（256–512MB）

服务端是 JVM 进程，发行包默认给 -Xms2g -Xmx2g，在 2 GB 内存的机器上非常危险。参数位置固定在 /etc/default/puppetserver 第 11 行：

$ grep -n "JAVA_ARGS" /etc/default/puppetserver
11:JAVA_ARGS="-Xms2g -Xmx2g"
13:# Modify this as you would JAVA_ARGS but for non-service related subcommands

改成 256MB 初始、512MB 上限：

$ sed -i 's/^JAVA_ARGS="-Xms2g -Xmx2g"/JAVA_ARGS="-Xms256m -Xmx512m"/' /etc/default/puppetserver
$ grep -n '^JAVA_ARGS=' /etc/default/puppetserver
11:JAVA_ARGS="-Xms256m -Xmx512m"

重启服务使参数生效，并用 jps -v 确认实际传给 JVM 的参数：

$ systemctl restart puppetserver
$ jps -v
10130 main --add-opens=java.base/sun.nio.ch=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --enable-native-access=ALL-UNNAMED -Xms256m -Xmx512m -Dlogappender=F1 -XX:+CrashOnOutOfMemoryError -XX:ErrorFile=/var/log/puppetlabs/puppetserver/puppetserver_err_pid%p.log
10408 Jps -Dapplication.home=/usr/lib/jvm/java-25-openjdk-amd64 -Xms8m -Djdk.module.main=jdk.jcmd

jps 由 JDK 提供，只装了 JRE 的话会 command not found，补装即可：

$ apt-get install -y openjdk-25-jdk-headless

内存占用对照实测：

配置systemctl status 里的 Memory说明
默认 -Xms2g -Xmx2g（新装未改）Memory: 2.0G堆直接按初始值吃掉 2 GB
改后 -Xms256m -Xmx512mMemory: 873.7M堆上限 512 MB，其余是 JVM 元空间、JRuby、线程栈与本地库
$ 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

💡 技术拓展：JVM 堆不是「越小越好」，Puppet 服务端的目录编译会瞬时吃掉大量堆，-Xmx 过低会导致 OutOfMemoryError: Java heap space 或频繁 Full GC。常见档位：

节点规模-Xms/-Xmx 建议预期常驻内存
数十节点、单机自管理256m / 512m0.9–1.3 GB
数百节点512m / 1g1.5–2.5 GB
数千节点、多 JRuby 实例1g / 2g 起，配合 max-active-instances 调整3 GB 以上

本篇按写作规范取 256m/512m，对应的是数十节点以内的中小规模。扩大规模时先看 puppetserver.log 里的编译耗时与 GC 日志，再决定加堆。

7.3 首次启动日志确认

$ tail -n 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

四行到齐即启动正常：CA 服务起来、OpenVox Server has successfully started、READY=1 通知 systemd、JRuby 实例创建完成。sd_notify 这行也解释了 service 文件里的 Type=notify——只有收到 READY=1，systemd 才认为启动完成。

八、端到端验证

安装完不等于能用。本节用最小清单验证「服务端编译目录 → 客户端拉取 → 本地收敛 → 幂等」整条链路。

8.1 编写清单与 Hiera 数据

服务端代码目录结构：

$ 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

入口清单 site.pp：

node default {
  include profile::baseline
}

基线模块 modules/profile/manifests/baseline.pp：

# 基线配置：统一 motd 内容，确保 nginx 已安装并处于运行状态
class profile::baseline (
  String $motd = "Welcome to OpenVox managed node\n",
  Array[String] $packages = ["nginx"],
) {
  file { "/etc/motd":
    ensure  => file,
    content => $motd,
    owner   => "root",
    group   => "root",
    mode    => "0644",
  }

  package { $packages:
    ensure => installed,
  }

  service { "nginx":
    ensure  => running,
    enable  => true,
    require => Package["nginx"],
  }
}

数据文件 data/common.yaml，用 %{trusted.hostname} 让同一份代码按节点渲染：

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

环境级 hiera.yaml 出厂即指向 data/common.yaml：

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

写完后先做语法检查，避免带着语法错误去跑 agent：

$ /opt/puppetlabs/bin/puppet parser validate /etc/puppetlabs/code/environments/production/manifests/site.pp /etc/puppetlabs/code/environments/production/modules/profile/manifests/baseline.pp

无输出即通过。

8.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 '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

四行 Notice 分别对应：向服务端要目录、服务端编译、本地缓存、应用完成。File[/etc/motd] 是第一次写文件，Package[nginx] 是 created（从无到有），耗时 6.50 秒主要花在装 nginx 上。

验证渲染结果与包状态：

$ cat /etc/motd
Managed by OpenVox 9.1.0 on openvox-master
$ nginx -v
nginx version: nginx/1.18.0 (Ubuntu)

%{trusted.hostname} 被替换成 openvox-master，说明 Hiera 数据生效。

8.3 幂等验证

立即再跑一次：

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

没有任何资源变更事件，只有一行 Applied catalog in 0.75 seconds，耗时从 6.50 秒降到 0.75 秒——这就是幂等：系统已经处于声明状态，agent 只做检查不做修改。

8.4 服务资源收敛

把 nginx 手工停掉，再让 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
$ systemctl is-enabled nginx
enabled

ensure changed 'stopped' to 'running' 是漂移被修复的直接证据；enable => true 同时保证开机自启。

8.5 证书链路验证

首次跑 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.

服务端签发后再跑，/etc/motd 的内容会从 openvox-master 变成 web01：

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

证书的列、签、撤销命令与排障见 《OpenVox 9.1.0 常用 CLI 与运维命令详解》；puppet.conf 里 autosign 的写法见 《OpenVox 9.1.0 配置参数详解》。

九、常见问题（排障实录）

9.1 服务启动失败：Cannot determine basic system flavour

现象：systemctl start puppetserver 反复失败，journalctl -u puppetserver 每 5 秒一组，restart counter 一路上涨：

Oct 27 17:53:44 openvox-master java[4671]: Failed to load feature test for posix: can't find user for 0
Oct 27 17:53:44 openvox-master java[4671]: Execution error (RuntimeError) at RUBY/<main> (/opt/puppetlabs/puppet/lib/ruby/vendor_ruby/puppet/feature/base.rb:21).
Oct 27 17:53:44 openvox-master java[4671]: (Error) Cannot determine basic system flavour
Oct 27 17:53:44 openvox-master java[4671]: Full report at:
Oct 27 17:53:44 openvox-master java[4671]: /tmp/clojure-12908723728559246451.edn
Oct 27 17:53:44 openvox-master systemd[1]: puppetserver.service: Main process exited, code=exited, status=1/FAILURE
Oct 27 17:53:44 openvox-master systemd[1]: puppetserver.service: Failed with result 'exit-code'.
Oct 27 17:53:44 openvox-master systemd[1]: Failed to start puppetserver Service.

定位：JRuby 启动时需要把 native 辅助库写到临时目录再加载，而本机 /tmp 被以 noexec 挂载，加载失败后 JRuby 回退到纯 Java 实现；纯 Java 实现拿不到 uid 0 的用户条目，Etc.getpwuid(0) 返回 nil，于是 posix 特性测试报 can't find user for 0，最终 puppet/feature/base.rb 抛 Cannot determine basic system flavour。

处理：确认并恢复 /tmp 的可执行权限，再重启服务：

$ findmnt -no OPTIONS /tmp
rw,noexec,nosuid,nodev
$ mount -o remount,exec /tmp
$ systemctl restart puppetserver
$ systemctl is-active puppetserver
active

修复后 findmnt -no OPTIONS /tmp 不再含 noexec：

$ findmnt -no OPTIONS /tmp
rw,nosuid,nodev,relatime,inode64

持久化：remount 只对当前挂载生效，重启会丢。把 /etc/fstab 里 /tmp 的选项删掉 noexec，或改挂到独立分区并保留 exec。安全加固场景确实需要 noexec /tmp 时，可给服务单元加 PrivateTmp=false 并另配 TMPDIR 到一个可执行目录，但这条路径本次未验证，不建议直接上生产。

9.2 puppetserver ca 报 Permission denied

现象：服务 active、8140 正常，但执行证书命令直接 500：

$ /opt/puppetlabs/bin/puppetserver ca list --all
Error:
    code: 500
    body: Internal Server Error: java.io.FileNotFoundException: /etc/puppetlabs/puppetserver/ca/ca_key.pem (Permission denied)
Error while getting certificates

定位：puppetserver ca 以 puppet 用户身份读取 CA 目录，而该目录的属主是 root:root、ca_key.pem 为 0640，puppet 用户没有读权限。这种状态在升级或手工搬过 CA 文件的机器上更常见，全新安装的机器属主通常是 puppet:puppet。

处理：

$ ls -l /etc/puppetlabs/puppetserver/ca/ca_key.pem
-rw-r----- 1 root root 3243 Oct 27 17:54 /etc/puppetlabs/puppetserver/ca/ca_key.pem
$ chown -R puppet:puppet /etc/puppetlabs/puppetserver/ca
$ chmod 0640 /etc/puppetlabs/puppetserver/ca/ca_key.pem /etc/puppetlabs/puppetserver/ca/inventory.txt
$ /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]

9.3 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

替代命令是 puppetserver ca，动作对照：puppet cert list → puppetserver ca list，puppet cert sign → puppetserver ca sign，puppet cert clean → puppetserver ca clean。迁移脚本时全局替换。

9.4 想装 9.2.1 的 server 包但找不到

apt-cache policy 已说明：Ubuntu 22.04 池里 openvox-server 最高 9.1.0。强行指定 9.2.1 会得到版本解析失败：

E: Version '9.2.1-1+ubuntu22.04' for 'openvox-server' was not found

处理方式只有两种：装 9.1.0（本篇方案），或从源码自行构建服务端包。不要用 --allow-downgrades 之类的参数绕过，那不会让不存在的包出现。

9.5 8140 被占用

puppetserver 启动失败且日志里出现 Address already in use 时，先查占用者：

$ ss -ltnp | grep 8140
LISTEN 0      50                 *:8140             *:*    users:(("java",pid=10130,fd=24))

若 pid 不是当前 puppetserver 的 Main PID（systemctl show -p MainPID puppetserver），说明有残留进程或别的服务占了端口。确认后 kill <pid> 再启动；原厂 puppetserver 未卸干净是常见原因，dpkg -l | grep puppetserver 可确认。

十、卸载与清理

10.1 停止并取消开机自启

$ systemctl stop puppetserver
$ systemctl disable puppetserver

agent 侧同理：systemctl stop puppet、systemctl disable puppet。

10.2 卸载软件包

$ apt-get purge -y openvox-server openvox-agent openvox9-release
Reading package lists...
Building dependency tree...
Reading state information...
The following packages will be REMOVED:
  openvox-agent* openvox-server* openvox9-release*
0 upgraded, 0 newly installed, 3 to remove and 2 not upgraded.
After this operation, 207 MB disk space will be freed.
Removing openvox-server (9.1.0-1+ubuntu22.04) ...
Removing openvox-agent (9.1.0-1+ubuntu22.04) ...
Removing openvox9-release (1-1ubuntu22.04) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...
Purging configuration files for openvox-server (9.1.0-1+ubuntu22.04) ...
dpkg: warning: while removing openvox-server, directory '/opt/puppetlabs/server/data/puppetserver' not empty so not removed
dpkg: warning: while removing openvox-server, directory '/etc/puppetlabs/puppetserver' not empty so not removed
Purging configuration files for openvox-agent (9.1.0-1+ubuntu22.04) ...
dpkg: warning: while removing openvox-agent, directory '/opt/puppetlabs' not empty so not removed
dpkg: warning: while removing openvox-agent, directory '/etc/puppetlabs/puppet' not empty so not removed
Purging configuration files for openvox9-release (1-1ubuntu22.04) ...

not empty so not removed 的警告是 dpkg 的保护行为：配置目录里有用户数据（CA 私钥、Hiera 数据、模块），它不会替你删。需要彻底清干净时手工删除：

$ ls -d /etc/puppetlabs /opt/puppetlabs /var/log/puppetlabs
/etc/puppetlabs
/opt/puppetlabs
$ rm -rf /etc/puppetlabs /opt/puppetlabs /var/log/puppetlabs /var/run/puppetlabs
$ ls -d /etc/puppetlabs /opt/puppetlabs /var/log/puppetlabs
ls: cannot access '/etc/puppetlabs': No such file or directory
ls: cannot access '/opt/puppetlabs': No such file or directory
ls: cannot access '/var/log/puppetlabs': No such file or directory

10.3 移除软件源与密钥

$ rm -f /etc/apt/sources.list.d/openvox9-release.list /etc/apt/keyrings/openvox9-release-keyring.gpg
$ ls /etc/apt/sources.list.d/

ls 无输出说明源目录已空。若机器上还有别的第三方源，这里应只剩那些文件。

10.4 残留复核

$ command -v puppet
$ dpkg -l | grep openvox

两条都无输出，/etc/puppetlabs、/opt/puppetlabs、/var/log/puppetlabs 均已不存在，卸载完成。注意 /etc/passwd 里的 puppet 用户会保留（包卸载不删用户），如需彻底清理执行 userdel puppet。

十一、参考链接

  • OpenVox 项目主页：https://openvoxproject.org/
  • OpenVox 源码与 Releases：https://github.com/OpenVoxProject/openvox
  • OpenVox 官方安装指引：https://voxpupuli.org/openvox/install/
  • OpenVox 官方文档：https://docs.openvoxproject.org/
  • OpenVox 软件源索引：https://apt.voxpupuli.org/
  • 配置项完整列表：https://docs.openvoxproject.org/openvox/latest/configuration.html
  • 站内：《OpenVox 介绍与选型指南》