Rocky 9 安装 pgexporter 0.8.0 指南

目标：在一台 Rocky Linux 9 服务器上以源码编译方式安装 pgexporter 0.8.0，配套一台内网 PostgreSQL 16 服务器作为被监控实例，完成账号授权、配置、加密 vault、systemd 服务化与 /metrics 端点验证的完整闭环。本文为部署篇（B1）：全部命令与回显均在实测环境逐条执行并照抄记录（实测日期 2026-10-28），途中踩到的四个安装/运行坑以"排障实录"形式沉淀；配置参数的逐项语义见配置篇《pgexporter 0.8.0 配置参数详解》，命令用法见《pgexporter 0.8.0 常用 CLI 命令与工具详解》。

一、环境与版本基准

项	值
监控服务器（本篇操作对象）	Rocky Linux 9（x86_64），主机名 `mon01`，编译并运行 pgexporter
被监控数据库服务器	内网另一台服务器 `10.89.74.10`，PostgreSQL 16.15，监听 5432
pgexporter 版本	0.8.0（源码 tag 0.8.0，commit `1cda464`；GitHub Releases 显示该版本发布于 2026-04-29）
服务端口	metrics 端点 8150（本篇统一约定）
实测日期	2026-10-28

💡 版本要求：pgexporter 0.8.0 官方配置文档明确 "PostgreSQL 13+ is required for PostgreSQL servers"（0.8.0 源码 doc/CONFIGURATION.md），被监控的 PostgreSQL 实例须为 13 及以上版本；本篇以 16.15 实测。

二、安装前准备

2.1 安装编译依赖（排障实录一：libyaml-devel / liburing-devel 在 CRB 仓库）

pgexporter 是 C 项目，编译依赖 gcc/cmake/OpenSSL/systemd/libyaml 等。直接按 README 的 Fedora 清单在 Rocky 9 上安装会报"找不到包"：

No match for argument: liburing-devel
Error: Unable to find a match: libyaml-devel liburing-devel

原因：Rocky 9 将 libyaml-devel、liburing-devel 等开发包放在 CRB（CodeReady Builder） 仓库，基础仓库不含。先启用 CRB 再安装完整依赖：

dnf -y install dnf-plugins-core
dnf config-manager --set-enabled crb
dnf -y install git gcc gcc-c++ cmake make openssl openssl-devel \
  systemd systemd-devel python3-docutils libyaml libyaml-devel \
  zlib zlib-devel libzstd libzstd-devel lz4 lz4-devel bzip2 bzip2-devel \
  liburing liburing-devel pkgconf-pkg-config sqlite sqlite-devel procps-ng

实测回显（结尾）：

Complete!

共安装 129 个包。其中 systemd-devel 与 python3-docutils 是官方 README 列明的依赖：前者提供 systemd 集成（CMake 探测到后以 -DHAVE_SYSTEMD 编译 sd_notify 支持），后者提供 rst2man 用于生成 man 手册页。

2.2 获取 0.8.0 源码

cd /root
git clone --depth 1 --branch 0.8.0 https://github.com/pgexporter/pgexporter.git
cd pgexporter
git log --oneline -1

实测回显：

Cloning into 'pgexporter'...

1cda464 Fix log log file creation

💡 --depth 1 --branch 0.8.0 只取该 tag 的最新一个提交，省流量且版本锁定；git log 确认检出的正是 0.8.0 的头号提交（与 GitHub Release 0.8.0 的变更列表第一条一致）。网络受限的服务器可让 git 走 HTTP 代理（git -c http.proxy=http://<proxy>:<port> clone ...）。

三、编译与安装（排障实录二：libev / libatomic 两个"文档未列"依赖）

3.1 cmake 配置

mkdir build && cd build
cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local ..

第一次执行失败，回显：

CMake Error at CMakeLists.txt:142 (message):
  libev needed


-- Configuring incomplete, errors occurred!

排障实录：pgexporter README 的依赖清单没有列 libev，但 0.8.0 的 CMakeLists 第 142 行强制检查（配置项 libev 支持多种事件后端，编译期即需要 libev 库）。补装后再次 cmake，又暴露第二个缺失：

  libatomic needed

一次装齐两个缺失依赖后，cmake 成功：

dnf -y install libev libev-devel libatomic

Complete!

rm -rf build && mkdir build && cd build
cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local ..

实测回显（结尾）：

-- Performing Test HAS_NOW - Success
-- Configuring done (1.3s)
-- Generating done (0.0s)
-- Build files have been written to: /root/pgexporter/build

💡 复盘：0.8.0 在 Rocky 9 上从零编译共缺 3 组依赖——CRB 仓库的 libyaml-devel/liburing-devel、清单未列的 libev、原子操作库 libatomic。本文 2.1 的 dnf 清单可加上 libev libev-devel libatomic 一次到位。

3.2 make 编译与 make install

make -j$(nproc)
make install

make -j$(nproc) 编译约 1–2 分钟（实测机 16 核），无报错。make install 实测回显（节选，-- Installing: 共 40 余条）：

-- Installing: /usr/local/bin/pgexporter
-- Installing: /usr/local/bin/pgexporter-admin
-- Installing: /usr/local/bin/pgexporter-cli
-- Installing: /usr/local/lib64/libpgexporter.so.0.8.0
-- Installing: /usr/local/share/man/man1/pgexporter.1
-- Installing: /usr/local/share/man/man1/pgexporter-cli.1
-- Installing: /usr/local/share/man/man1/pgexporter-admin.1
-- Installing: /usr/local/share/man/man5/pgexporter.conf.5
-- Installing: /usr/local/share/pgexporter/extensions/pgexporter_ext.yaml
-- Installing: /usr/local/share/pgexporter/extensions/pgstattuple.yaml
-- Installing: /usr/local/share/pgexporter/extensions/postgis.yaml
-- Installing: /usr/local/share/pgexporter/extensions/timescaledb.yaml

安装产物四类：

产物	位置	说明
三个二进制	`/usr/local/bin/pgexporter`、`pgexporter-cli`、`pgexporter-admin`	守护进程、运行时管理、账号管理
核心库	`/usr/local/lib64/libpgexporter.so.0.8.0` 及 `.so`、`.so.0` 链接	三件套共用（注意在 lib64）
man 手册	`/usr/local/share/man/man1/`、`man5/`	`man pgexporter` 可查
扩展指标 YAML	`/usr/local/share/pgexporter/extensions/`（15 个）	pg_stat_statements、postgis、timescaledb 等扩展的指标定义

注意：官方 systemd unit 模板不会随 make install 安装，模板在源码树 doc/etc/pgexporter.service，第六节手动部署。

3.3 排障实录三：libpgexporter.so.0 找不到

安装完成直接运行报错：

# pgexporter -V
pgexporter: error while loading shared libraries: libpgexporter.so.0: cannot open shared object file: No such file or directory

原因：核心库装在 /usr/local/lib64（cmake 在 64 位系统默认 LIB_SUFFIX=64），而 Rocky 9 的动态链接器缓存默认不含该路径。写入 ld 配置并刷新：

echo /usr/local/lib64 > /etc/ld.so.conf.d/pgexporter.conf
ldconfig
pgexporter -V

实测回显：

pgexporter 0.8.0

四、被监控 PostgreSQL 实例的准备

pgexporter 需要以数据库账号连入 PostgreSQL 采集系统视图。在数据库服务器 10.89.74.10 的 PostgreSQL 16.15 上执行（postgres 超级用户）：

CREATE ROLE pgexporter WITH LOGIN PASSWORD 'q1w2e3r4';
GRANT pg_monitor TO pgexporter;
GRANT SELECT ON TABLE pg_file_settings, pg_authid TO pgexporter;
GRANT EXECUTE ON FUNCTION pg_show_all_file_settings() TO pgexporter;

实测回显：

CREATE ROLE
GRANT
GRANT
GRANT

四条授权的分工：

授权	作用
`GRANT pg_monitor`	读全部 `pg_stat_*` 统计视图的固定角色，指标采集的主体权限
`GRANT SELECT ON pg_file_settings, pg_authid`	官方 `doc/GETTING_STARTED.md` 明确要求：pgexporter 需要读这两个系统表（配置核对与角色信息）
`GRANT EXECUTE ON FUNCTION pg_show_all_file_settings()`	配合上条的函数执行权

并在 pg_hba.conf 放行监控服务器网段（内网 10.89.74.0/24）后重载配置：

host    all    pgexporter    10.89.74.0/24    scram-sha-256

su - postgres -c 'psql -c "SELECT pg_reload_conf()"'

💡 安全提示：pg_authid 含全体角色的口令哈希，官方文档即如此要求（pgexporter 用它做角色信息核对），生产环境建议以防火墙/网段把监控账号的访问限制到最小范围，不要放宽到 all。

五、监控服务器：配置与加密 vault

5.1 系统用户与目录

unit 模板以 User=pgexporter 运行，先建系统账号与三处目录：

useradd -r -s /sbin/nologin pgexporter
mkdir -p /etc/pgexporter /var/log/pgexporter /var/run/pgexporter /home/pgexporter
chown pgexporter:pgexporter /etc/pgexporter /var/log/pgexporter /var/run/pgexporter /home/pgexporter

（无回显即成功。）

5.2 主配置文件 /etc/pgexporter/pgexporter.conf

[pgexporter]
host = *
metrics = 8150

log_type = file
log_level = info
log_path = /var/log/pgexporter/pgexporter.log

unix_socket_dir = /var/run/pgexporter

management = 8151

[primary]
host = 10.89.74.10
port = 5432
user = pgexporter

语义速览（逐项详解见配置篇）：host = * 监听全部网卡；metrics = 8150 是 Prometheus 抓取端口；management = 8151 打开远程管理端口供 pgexporter-cli 使用；[primary] 是自定义命名的 Server 段，指向内网 PostgreSQL 实例。设置权限并落盘：

chmod 640 /etc/pgexporter/pgexporter.conf
chown pgexporter:pgexporter /etc/pgexporter/pgexporter.conf

5.3 加密 vault：master-key 与用户（排障实录四：root 一律被拒）

0.8.0 起账号口令存于加密 vault（pgexporter_users.conf），由 pgexporter-admin 管理。先建主密钥、再加用户：

直接以 root 执行会全部被拒：

# pgexporter-admin master-key
pgexporter-admin: pgexporter: Using the root account is not allowed

pgexporter 全家桶（admin/cli）都禁止 root 运行，必须切换到普通用户（这里用 5.1 建的 pgexporter）。主密钥交互输入需 ≥8 字符，脚本化可用 PGEXPORTER_PASSWORD 环境变量传递：

su -s /bin/bash pgexporter -c "PGEXPORTER_PASSWORD=q1w2e3r4 pgexporter-admin master-key"

实测回显：

Header:
  ClientVersion: 0.8.0
  Command: 11
  Compression: 0
  Encryption: 0
  Output: 0
  Timestamp: 20261028145047
Outcome:
  Status: true
  Time: 00:00:00

主密钥落盘在运行用户家目录（实测 $HOME/.pgexporter/master.key，即 /home/pgexporter/.pgexporter/master.key）。接着把数据库口令写入用户 vault：

su -s /bin/bash pgexporter -c "pgexporter-admin -f /etc/pgexporter/pgexporter_users.conf -U pgexporter -P q1w2e3r4 user add"
su -s /bin/bash pgexporter -c "pgexporter-admin -f /etc/pgexporter/pgexporter_users.conf -U admin -P q1w2e3r4 user add"
su -s /bin/bash pgexporter -c "pgexporter-admin -f /etc/pgexporter/pgexporter_users.conf user ls"

实测回显（add 的 Header/Outcome 结构同上，Command: 12；ls 结尾）：

Response:
  Users:
    - pgexporter

cat /etc/pgexporter/pgexporter_users.conf

实测回显：

pgexporter:hGz09UNweRlcBIMf5bwzZEJ9kNsX2bftY48w7cv0bp8hZ7dOaanOEySV8Xk0yBcSA8M/2g==

两个账号的分工：pgexporter（users vault）是连 PostgreSQL 采集指标的数据库口令载体；admin（admins vault，同样用 -f /etc/pgexporter/pgexporter_admins.conf 创建，步骤相同）是 pgexporter-cli 远程管理的鉴权账号。vault 文件里只有密文，口令不落明文。

六、systemd 服务化

6.1 安装 unit（官方模板的两处修正）

官方模板（源码 doc/etc/pgexporter.service）有两处与 0.8.0 实情不符：其一，Description 写的是"High-performance connection pool for PostgreSQL"（明显是姊妹项目 pgagroal 的描述残留）；其二，ExecStart=/usr/bin/pgexporter 路径不对（本篇装在 /usr/local/bin，且需要显式指定三个配置文件与 -Y 自定义指标目录——-Y 的原因见第七节排障实录五）。复制模板后修正：

cp /root/pgexporter/doc/etc/pgexporter.service /etc/systemd/system/pgexporter.service
sed -i "s/^Description=.*/Description=Prometheus exporter for PostgreSQL/; \
  s|^ExecStart=.*|ExecStart=/usr/local/bin/pgexporter -Y /etc/pgexporter/metrics.d -c /etc/pgexporter/pgexporter.conf -u /etc/pgexporter/pgexporter_users.conf -A /etc/pgexporter/pgexporter_admins.conf|" \
  /etc/systemd/system/pgexporter.service
systemctl daemon-reload

修正后的 unit 关键内容：

[Service]
Type=exec
User=pgexporter
ExecStart=/usr/local/bin/pgexporter -Y /etc/pgexporter/metrics.d -c /etc/pgexporter/pgexporter.conf -u /etc/pgexporter/pgexporter_users.conf -A /etc/pgexporter/pgexporter_admins.conf
ExecReload=/bin/kill -HUP $MAINPID
KillSignal=SIGINT

6.2 启动与状态

systemctl enable --now pgexporter
systemctl status pgexporter --no-pager -l

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/pgexporter.service → /etc/systemd/system/pgexporter.service.
● pgexporter.service - Prometheus exporter for PostgreSQL
     Loaded: loaded (/etc/systemd/system/pgexporter.service; enabled; preset: disabled)
     Active: active (running) since Wed 2026-10-28 14:52:09 UTC; 3s ago
       Docs: man:pgexporter(1)
             https://pgexporter.github.io/
   Main PID: 204 (pgexporter)
      Tasks: 1 (limit: 15642)
     Memory: 28.6M (peak: 28.9M)
        CPU: 165ms
     CGroup: /system.slice/pgexporter.service
             └─204 "pgexporter: main"

Type=exec 与 systemd 集成正常（编译期 -DHAVE_SYSTEMD 生效），进程标题 "pgexporter: main" 来自 update_process_title 默认值 verbose。常驻内存实测 28.6 MB，是 C 实现轻量性的直观注脚（认知篇选型对比可引用）。

日志文件（log_path 指定）实测内容：

2026-10-28 14:52:09 INFO  main.c:1344 pgexporter: started on *

七、排障实录五：自定义指标目录必须用 -Y 传给守护进程

部署到此处有一个容易踩的坑，值得单列。pgexporter 支持"自定义指标 YAML"（metrics_path 配置项或 -Y/--yaml 命令行参数）。实测发现：把 metrics_path = /etc/pgexporter/metrics.d 只写进 pgexporter.conf 而不传 -Y，启动后自定义指标不会加载；若写成单文件路径（metrics_path = /etc/pgexporter/custom.yaml），启动时日志直接报错：

2026-10-28 14:54:34 ERROR yaml_configuration.c:427 Duplicate metric name with previously loaded files: pgexporter_postgresql_primary
2026-10-28 14:54:34 ERROR yaml_configuration.c:485 YAML contains duplicate metric names

实测矩阵（同机重启对照）：

启动方式	内置基础指标（`pgexporter_postgresql_version` 等）	内置全套指标（`pgexporter_pg_settings_*` 系列，共约 2592 行）	自定义 YAML 指标
无 `metrics_path`、无 `-Y`	有	有	无
仅配置文件 `metrics_path`（目录）	有	有	不加载（静默）
仅配置文件 `metrics_path`（单文件）	有	有	不加载且启动报 duplicate ERROR
命令行 `-Y /etc/pgexporter/metrics.d`	有	无（被自定义目录整体替换）	加载成功

结论（0.8.0 实测）：自定义指标目录必须以 -Y 命令行参数传给 pgexporter 进程（本篇 unit 的 ExecStart 已含）；一旦传入 -Y，编译进二进制的内置全套指标 YAML 即被替换为"代码级基础指标 + 你的目录"，pgexporter_pg_settings_* 等指标会消失——官方语义是"用自定义 YAML 完全接管指标集"，需要保留内置全套时就不要传 -Y，或把官方 contrib/yaml/postgresql-16.yaml 一并放进自定义目录。

💡 自定义指标写法与验证实测见配置篇 4.x 节；本文先保证端点可用。

八、端点验证

curl -s -o /dev/null -w "HTTP=%{http_code} bytes=%{size_download}\n" http://localhost:8150/metrics

实测回显：

HTTP=200 bytes=380058

指标内容抽样（grep 过滤）：

pgexporter_postgresql_version{server="primary", version="16", minor_version="15"} 1
pgexporter_postgresql_uptime{server="primary"} 954
pgexporter_postgresql_primary{server="primary"} 1
pgexporter_version{pgexporter_version="0.8.0"} 1

三个关键信号：server="primary" 标签与配置段名对应；version="16", minor_version="15" 说明到 PostgreSQL 16.15 的采集链路已通；pgexporter_version="0.8.0" 是 exporter 自述版本。跨机验证（Prometheus 服务器侧视角）同样可达：

HTTP=200 bytes=380000

💡 380 KB / 次抓取是"内置全套指标"模式的量级（2592 个指标行）；传 -Y 接管后实测降到约 60–70 KB / 386 行。抓取体量与抓取间隔是容量规划的两个输入项。

最后把抓取端点交给 Prometheus 侧的 scrape 配置（prometheus.yml 中追加 job，static_configs 指向 mon01:8150 即可，本文不展开）。

九、常见问题（FAQ）

现象	原因与处置
`dnf` 报 `Unable to find a match: libyaml-devel liburing-devel`	启用 CRB 仓库（第二节排障实录一）
cmake 报 `libev needed` / `libatomic needed`	`dnf install libev libev-devel libatomic`（第三节排障实录二）
`pgexporter -V` 报 `libpgexporter.so.0 ... No such file or directory`	`/usr/local/lib64` 未进链接器缓存：写 `/etc/ld.so.conf.d/pgexporter.conf` 后 `ldconfig`（排障实录三）
`pgexporter-admin`/`pgexporter-cli` 报 `Using the root account is not allowed`	全家桶禁 root，`su -s /bin/bash pgexporter -c "..."` 切普通用户（排障实录四）
systemd 启动失败且日志无 pgexporter 字样	检查 unit 的 `ExecStart` 路径与 `User=` 账号是否存在；`systemd-devel` 未装则 sd_notify 集成缺失
`/metrics` 返回 200 但没有 `pgexporter_postgresql_*` 实例指标	检查 `[primary]` 段 `host/port/user`、PG 端 `pg_hba.conf` 放行与 `pgexporter_users.conf` vault 里的口令
传了 `-Y` 后 `pgexporter_pg_settings_*` 全消失	`-Y` 目录整体替换内置指标集（第七节排障实录五），属预期行为

十、参考

本专栏系列（pgexporter 0.8.0）

认知篇：《pgexporter 0.8.0 介绍与选型指南》——定位、架构与同类选型量化对比：《pgexporter 0.8.0 介绍与选型指南》
配置篇：《pgexporter 0.8.0 配置参数详解》——pgexporter.conf 主段/Server 段逐项语义与验证：《pgexporter 0.8.0 配置参数详解》
命令篇：《pgexporter 0.8.0 常用 CLI 命令与工具详解》——pgexporter-cli/pgexporter-admin/curl 逐命令实测：《pgexporter 0.8.0 常用 CLI 命令与工具详解》

官方与外部来源

GitHub 仓库（README 编译依赖、测试平台）：https://github.com/pgexporter/pgexporter （查询日期 2026-10-28）
0.8.0 发布说明：https://github.com/pgexporter/pgexporter/releases/tag/0.8.0 （查询日期 2026-10-28）
官方文档站：https://pgexporter.github.io/
源码内文档：doc/GETTING_STARTED.md（PG 端授权与 vault 步骤）、doc/CONFIGURATION.md（PG 13+ 要求）、doc/etc/pgexporter.service（unit 模板）——0.8.0 源码树实查
站内相关：《PostgreSQL 18.6 介绍与选型指南》