pgexporter 0.8.0 配置参数详解

目标：把 pgexporter 0.8.0 的配置体系讲透——三个配置文件的角色与加载方式、[pgexporter] 主段与 Server 段的逐项语义/默认值/取值域、自定义指标 YAML 的结构，以及对关键参数的实测验证（改参数→验证生效的闭环，含 4 条实测排障）。本文为配置篇（C1）：参数语义以 0.8.0 源码内 doc/CONFIGURATION.md 为基准（本地实查），实测日期 2026-10-28；安装过程见部署篇《Rocky 9 安装 pgexporter 0.8.0 指南》，命令操作见《pgexporter 0.8.0 常用 CLI 命令与工具详解》。

一、配置体系总览

1.1 三个配置文件

实测备忘：pgexporter-cli conf ls 会回读三个文件的运行时路径（回显见命令篇）。另有 -D/--directory 可一次指定整个配置目录。master key 与 vault 文件相互独立：master key 存运行用户家目录（实测 /home/pgexporter/.pgexporter/master.key），vault 里是密文（实测样例）：

pgexporter:hGz09UNweRlcBIMf5bwzZEJ9kNsX2bftY48w7cv0bp8hZ7dOaanOEySV8Xk0yBcSA8M/2g==

1.2 语法规则

0.8.0 采用 INI 风格分段：主段固定为 [pgexporter]，Server 段名自取（如 [primary]、[replica1]），键值格式 key = value；# 或 ; 开头为注释；Bool 类型接受 on/yes/1/true/off/no/0/false（0.8.0 doc/CONFIGURATION.md 原文）。时长大类参数统一支持 ms/s/m/h/d/w 后缀（缺省秒），容量类统一支持 B/K/KB/M/MB/G/GB（缺省字节）；大量路径参数支持 $HOME 等环境变量插值。

💡 迁移提示：0.8.0 Release 说明 "New vault security (migration needed)"——从 0.7.x 升级时旧的 users 配置需重新以 pgexporter-admin 生成加密 vault，不能直接拷贝旧明文 users 文件。

二、[pgexporter] 主段逐项详解

2.1 必填三项

三项缺一启动即失败。示例（本系列实测环境的主段骨架）：

[pgexporter]
host = *
metrics = 8150
unix_socket_dir = /var/run/pgexporter

2.2 指标通路与缓存

metrics_cache_max_age 生效验证（实测）：设 5s 并重启后，连续三次抓取（间隔 1 秒）pgexporter_query_executions_total 恒为 14（缓存窗口内不回库查询），窗口过期后恢复增长——缓存确凿生效：

pgexporter_query_executions_total 14
pgexporter_query_executions_total 14
pgexporter_query_executions_total 14

2.3 Bridge / JSON 输出

Bridge/JSON 是 pgexporter 区别于多数 exporter 的"聚合代理"能力（认知篇对比表中的附加能力项）；本篇未实测 bridge（0.8.0 源码 doc/BRIDGE.md/doc/JSON.md 为语义依据），生产启用前建议先单机试跑。

2.4 远程管理与告警

实测提醒：设了 management = 8151 但没配 admins vault 时，日志出现 WARN configuration.c:1817 pgexporter: Remote management enabled, but no admins are defined——管理端口开着但无人能登录，CLI 全部 401 类失败。正确姿势是先用 pgexporter-admin -f /etc/pgexporter/pgexporter_admins.conf -U admin -P <密码> user add 建管理员再启动。

2.5 日志

实测：conf set log_rotation_size 10MB 返回 10485760（人类可读值被解析为字节数回显），conf set log_level debug 后 conf get log_level 即回 debug——运行时改级无需重启（详见命令篇 conf 系列实测）。

2.6 超时

2.7 TLS

TLS 证书三件套的属主/权限约束是官方文档明文要求，不符时启动拒绝加载。本篇实测未启用 TLS（内网环境），启用步骤请按官方 doc/ENCRYPTION.md。

2.8 内核与进程行为

实测佐证：systemctl status 的 CGroup 里进程名显示 "pgexporter: main"，即 update_process_title = verbose 的效果。

2.9 扩展与采集器控制（含排障实录：metrics_path 的三种结局）

三层优先级：Server 段 extensions > 全局 extensions > 默认（全部启用）。

排障实录（0.8.0 实测矩阵）：自定义指标 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

结论：要用自定义指标，统一在 systemd ExecStart 传 -Y /etc/pgexporter/metrics.d（目录形态）；传入 -Y 后内置全套 YAML 指标被替换为"代码级基础指标 + 自定义目录"（实测 /metrics 从 380 KB/2592 行 降至约 60–70 KB/386 行），需要内置全套时勿传 -Y。

三、Server 段逐项详解（[primary]）

每个被监控 PostgreSQL 实例一个段，段名即指标里的 server 标签（实测 pgexporter_postgresql_version{server="primary", version="16", minor_version="15"}）：

本系列实测的 Server 段与采集验证：

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

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

💡 提示：段名 primary 不是关键字而是自定义名——它恰好符合"主库"语义所以顺手；指标标签跟随段名，改名即改标签。多实例场景（主/备/多套）逐段罗列即可，pgexporter-cli status 会逐段回显（见命令篇）。

四、自定义指标 YAML 结构

-Y 目录下的每个 YAML 是一串指标查询定义（0.8.0 源码 doc/YAML.md 与 contrib/yaml/postgresql-16.yaml 为格式基准）。实测可用的最小结构：

metrics:
- tag: activity_by_state
  collector: custom
  sort: data
  server: both
  queries:
  - query: SELECT state, count(*) AS cnt FROM pg_stat_activity GROUP BY state
    version: 10
    columns:
    - name: state
      type: label
    - name: cnt
      type: gauge
      description: Number of backend connections grouped by state

逐层说明：

实测加载结果（该文件经 -Y 生效后抓取）：

#HELP pgexporter_activity_by_state_cnt Number of backend connections grouped by state
#TYPE pgexporter_activity_by_state_cnt gauge
pgexporter_activity_by_state_cnt{server="primary", state="active", database="postgres"} 1
pgexporter_activity_by_state_cnt{server="primary", state="n/a", database="postgres"} 5

state="n/a" 是后台工作进程无事务状态的占位标签值——自定义 label 的空值会被规范化为 n/a，写面板时注意。

五、关键参数生效方式速查（实测汇总）

💡 排障实录（metrics_cache_max_age）：配置 5s 后先 conf reload，conf get metrics_cache_max_age 回显仍是 0s，抓取计数器每秒 +10（未缓存）；systemctl restart pgexporter 后 conf get 回 5s、窗口内计数器恒 14——该参数与官方标注的 max_size 一样属"改动需重启"，官方文档对 max_age 未标注，以实测为准。

六、参考

本专栏系列（pgexporter 0.8.0）

• 认知篇：《pgexporter 0.8.0 介绍与选型指南》——定位、架构与同类选型量化对比：《pgexporter 0.8.0 介绍与选型指南》
• 部署篇：《Rocky 9 安装 pgexporter 0.8.0 指南》——源码编译 + systemd 单机部署全过程实录：《Rocky 9 安装 pgexporter 0.8.0 指南》
• 命令篇：《pgexporter 0.8.0 常用 CLI 命令与工具详解》——pgexporter-cli/pgexporter-admin/curl 逐命令实测：《pgexporter 0.8.0 常用 CLI 命令与工具详解》

官方与外部来源

• 0.8.0 源码 doc/CONFIGURATION.md（参数表权威依据）、doc/YAML.md（自定义指标）、doc/ENCRYPTION.md（TLS/vault）、doc/BRIDGE.md/doc/JSON.md（Bridge/JSON）、doc/ALERT.md（告警）——0.8.0 源码树实查
• 仓库文档在线版：https://pgexporter.github.io/ （查询日期 2026-10-28）
• 仓库主页：https://github.com/pgexporter/pgexporter
• 站内相关：《PostgreSQL 18.6 介绍与选型指南》