pgexporter 0.8.0 常用 CLI 命令与工具详解

目标：把 pgexporter 0.8.0 的三件套命令行工具——守护进程 pgexporter、运行时管理工具 pgexporter-cli、账号管理工具 pgexporter-admin——逐个命令实测留回显，并覆盖配套工具链（curl 抓 /metrics、systemctl 生命周期、自定义指标验证）。本文为命令篇（D1）：全部回显照抄自实测（实测日期 2026-10-28，环境为部署篇搭建的 Rocky 9 服务器 mon01 + 内网 PostgreSQL 16.15）；参数语义见配置篇《pgexporter 0.8.0 配置参数详解》。

一、三件套总览与通用约定

工具	角色	关键选项
`pgexporter`	守护进程本体	`-c` 主配置、`-u/-A` vault、`-Y/-J` 自定义指标、`-d` daemon 化、`-C/-X` 采集器过滤
`pgexporter-cli`	运行时管理客户端	`-c` 主配置（读 management 端口）、`-h/-p/-U/-P` 直连参数、`-F` 输出格式、`-C` 压缩、`-E` 加密
`pgexporter-admin`	vault 账号管理	`-f` vault 文件、`-U/-P` 账号口令、`-F text

通用约定一：全家桶禁止 root 运行（实测，三件套一致）：

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

处置：切普通用户执行（本系列用部署篇建的 pgexporter 系统账号）：

su -s /bin/bash pgexporter -c "<命令>"

通用约定二：-V/--version 与 -?/--help 的退出码为 1（实测：三件套 -? 均正常打印帮助但退出码 1；pgexporter -V 返回 0，而 pgexporter-cli -V、pgexporter-admin -V 打印版本但退出码 1）。写巡检脚本时不要用 $? 判断版本查询是否成功，应匹配输出内容。

二、pgexporter（守护进程）

pgexporter -? 实测回显（完整）：

pgexporter 0.8.0
  Prometheus exporter for PostgreSQL

Usage:
  pgexporter [ -c CONFIG_FILE ] [ -u USERS_FILE ] [ -d ]

Options:
  -c, --config CONFIG_FILE                            Set the path to the pgexporter.conf file
  -u, --users USERS_FILE                              Set the path to the pgexporter_users.conf file
  -A, --admins ADMINS_FILE                            Set the path to the pgexporter_admins.conf file
  -Y, --yaml METRICS_FILE_DIR                         Set the path to YAML file/directory
  -J, --json METRICS_FILE_DIR                         Set the path to JSON file/directory
  -a, --alerts ALERTS_FILE                            Set the path to the alert file
  -D, --directory DIRECTORY                           Set the configuration directory path
                                                      Can also be set via PGEXPORTER_CONFIG_DIR environment variable
  -d, --daemon                                        Run as a daemon
  -C, --collectors NAME_1,NAME_2,...,NAME_N           Enable only specific collectors
  -X, --exclude-collectors NAME_1,NAME_2,...,NAME_N   Exclude only specific collectors
  -V, --version                                       Display version information
  -?, --help                                          Display help

pgexporter: https://pgexporter.github.io/
Report bugs: https://github.com/pgexporter/pgexporter/issues

日常运维实际用到的调用形态（部署篇 systemd ExecStart 实测）：

pgexporter -Y /etc/pgexporter/metrics.d -c /etc/pgexporter/pgexporter.conf \
  -u /etc/pgexporter/pgexporter_users.conf -A /etc/pgexporter/pgexporter_admins.conf

💡 两个易踩点：其一，-Y 指定自定义指标目录是启动期行为（配置文件里的 metrics_path 实测启动时不加载，详见配置篇 2.9 排障实录）；其二，前台调试可直接运行 pgexporter -c ... -u ...，Ctrl-C 或 kill <pid>（SIGTERM）退出，日志跟随 log_type 走 console 或 file。

版本查询实测回显：

$ pgexporter -V
pgexporter 0.8.0

三、pgexporter-cli（运行时管理）

pgexporter-cli -? 实测回显的命令清单：

Commands:
  ping                     Check if pgexporter is alive
  shutdown                 Shutdown pgexporter
  status [details]         Status of pgexporter, with optional details
  conf <action>            Manage the configuration, with one of subcommands:
                           - 'reload' to reload the configuration
                           - 'ls' to print the configurations used
                           - 'get' to obtain information about a runtime configuration value
                           - 'set' to modify a configuration value;
  clear <what>             Clear data, with:
                           - 'prometheus' to reset the Prometheus statistics
  encrypt <input> [output] Encrypt a file
  decrypt <input> [output] Decrypt a file

💡 0.8.0 相比其 doc/CLI.md 文档新增了 encrypt/decrypt 两条文件加解密命令（文档未列，-? 实查所得），以及 wire 协议选项 -F text|json|raw、-C none|gz|zstd|lz4|bz2、-E none|aes|aes256|aes192|aes128（GCM）。

以下命令统一以 su -s /bin/bash pgexporter -c "pgexporter-cli -c /etc/pgexporter/pgexporter.conf ..." 执行（下文省略前缀）。

3.1 ping —— 存活探测

Header:
  ClientVersion: 0.8.0
  Command: ping
  Compression: none
  Encryption: none
  Output: text
  Timestamp: 20261028145308
Outcome:
  Status: true
  Time: 00:00:00
Request: {}
Response:
  ServerVersion: 0.8.0

Outcome.Status: true 即存活；输出为结构化 YAML 文本（-F text 默认格式；-F json 可切 JSON、-F raw 裸值），适合脚本逐字段解析。监控侧等价探测是 curl -s http://localhost:8150/metrics | head -1（见第五节）。

3.2 status / status details —— 状态查看

Response:
  NumberOfServers: 1
  ServerVersion: 0.8.0
  Servers:
    - Active: false
      Server: primary

status details 额外回显 FIPS 状态：

Response:
  NumberOfServers: 1
  PgexporterFips: false
  ServerVersion: 0.8.0
  Servers:
    - Active: false
      Fips: false
      Server: primary

Server: primary 对应主配置的 [primary] 段名；Active: false 表示当前无进行中的采集会话（指标查询按抓取触发，非长连接常驻）。

3.3 conf ls —— 运行时配置路径

Response:
  ServerVersion: 0.8.0
  admin_configuration_path: /etc/pgexporter/pgexporter_admins.conf
  main_configuration_path: /etc/pgexporter/pgexporter.conf
  users_configuration_path: /etc/pgexporter/pgexporter_users.conf

3.4 conf get —— 读运行时值

$ pgexporter-cli conf get metrics
8150
$ pgexporter-cli conf get server.primary.host
10.89.74.10

键名规则：主段键可直接写（metrics）或带段前缀（pgexporter.metrics）；Server 段键用 server.<段名>.<键>（实测 server.primary.host）。不带键执行 conf get 输出完整配置。

3.5 conf set —— 改运行时值（带规范值回显）

$ pgexporter-cli conf set log_level debug
2
$ pgexporter-cli conf get log_level
debug
$ pgexporter-cli conf set log_rotation_size 10MB
10485760

两个实测细节：其一，set 的返回值是解析后的规范值——log_level debug 回显枚举序号 2，10MB 回显字节数 10485760；其二，改完立即 conf get 可确认（debug）。演示完记得改回生产值（实测 conf set log_level info 恢复）。

3.6 conf reload —— 热加载

Response:
  Restart: false
  ServerVersion: 0.8.0

Restart: false 表示本次变更无需重启进程。注意两点（实测）：log_level 这类参数 reload 即生效；而 metrics_cache_max_age 实测 reload 后 conf get 仍回旧值 0s，重启后才读到 5s——"reload 即生效"要按参数逐项验证，速查表见配置篇第五节。

3.7 clear prometheus —— 复位指标统计

Header:
  ClientVersion: 0.8.0
  Command: reset
  Compression: none
  Encryption: none
  Output: text
  Timestamp: 20261028145333
Outcome:
  Status: true
  Time: 00:00:00
Request: {}

注意内部 Command 名是 reset（文档写 clear prometheus）。执行后 pgexporter_query_executions_total 等 exporter 自身计数器归零重新累计（不触碰 PostgreSQL 端统计数据）。

3.8 encrypt / decrypt —— 文件加解密（0.8.0 新增）

默认加密模式 none 不被支持（实测报错）：

Error: Encryption mode 'none' is not supported for encrypt/decrypt commands.

需以 -E 指定 AES 系列模式；命令执行时交互式要求输入主密钥（Password:，即 pgexporter-admin master-key 设置的密钥；脚本可用 PGEXPORTER_PASSWORD 环境变量）：

$ pgexporter-cli -E aes256 encrypt /tmp/enc_test.txt /tmp/enc_test.enc
Password:
Success: /tmp/enc_test.enc
$ pgexporter-cli -E aes256 decrypt /tmp/enc_test.enc /tmp/enc_test.dec
Password:
Success: /tmp/enc_test.dec
$ cat /tmp/enc_test.dec
secret line for test

实测 21 字节明文加密后为 65 字节（含认证标签等结构开销）。适用场景：为 vault 迁移、配置分发等准备加密文件。

3.9 shutdown —— 停止守护进程

pgexporter-cli shutdown 向守护进程下发停机指令（回显结构与 ping 相同，Outcome.Status: true）。systemd 托管场景不建议日常使用（服务会被拉起或进入 failed 态），停服统一走 systemctl stop pgexporter（SIGINT 由 unit 的 KillSignal 下发，与 shutdown 同路径）。

3.10 远程管理：-h/-p/-U/-P

pgexporter-cli 默认从 -c 指定的主配置读取 management 端口与本机管理通道；跨机管理时用 -h <host> -p <management端口> -U <admins账号> -P <口令> 直连（账号须在 pgexporter_admins.conf vault 中）。实测环境 management 端口为 8151（主配置 management = 8151），本机验证与远程验证一致。

四、pgexporter-admin（vault 账号管理）

pgexporter-admin -? 实测回显（完整）：

pgexporter-admin 0.8.0
  Administration utility for pgexporter

Usage:
  pgexporter-admin [ -f FILE ] [ COMMAND ]

Options:
  -f, --file FILE         Set the path to a user file
  -U, --user USER         Set the user name
  -P, --password PASSWORD Set the password for the user
  -g, --generate          Generate a password
  -l, --length            Password length
  -V, --version           Display version information
  -F, --format text|json  Set the output format
  -?, --help              Display help

Commands:
  master-key              Create or update the master key
  user <subcommand>       Manage a specific user, where <subcommand> can be
                          - add  to add a new user
                          - del  to remove an existing user
                          - edit to change the password for an existing user
                          - ls   to list all available users

4.1 master-key —— 创建/更新主密钥

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

注意三个事实（实测）：其一，root 执行被拒（第一节约定）；其二，交互输入主密钥须 ≥8 字符，脚本用 PGEXPORTER_PASSWORD；其三，密钥落盘在运行用户家目录 $HOME/.pgexporter/master.key（实测 /home/pgexporter/.pgexporter/master.key）——换运行用户 = 换密钥位置，vault 解密随之失效，迁移部署时要连带拷贝。

4.2 user add / ls / edit / del —— vault 账号生命周期

$ pgexporter-admin -f /etc/pgexporter/pgexporter_users.conf -U pgexporter -P q1w2e3r4 user add
Header: ...（Command: 12）
Outcome:
  Status: true
$ pgexporter-admin -f /etc/pgexporter/pgexporter_users.conf user ls
Response:
  Users:
    - pgexporter
$ pgexporter-admin -f /etc/pgexporter/pgexporter_users.conf -U pgexporter -P q1w2e3r5 user edit
Outcome:
  Status: true
$ pgexporter-admin -f /etc/pgexporter/pgexporter_users.conf -U readonly -P q1w2e3r4 user add
$ pgexporter-admin -f /etc/pgexporter/pgexporter_users.conf -U readonly user del
Outcome:
  Status: true
$ pgexporter-admin -f /etc/pgexporter/pgexporter_users.conf user ls
Response:
  Users:
    - pgexporter

vault 文件落盘效果（实测 cat，口令已是密文）：

pgexporter:hGz09UNweRlcBIMf5bwzZEJ9kNsX2bftY48w7cv0bp8hZ7dOaanOEySV8Xk0yBcSA8M/2g==

💡 user edit 改口令后需要 conf reload 或重启让守护进程重读 vault（运行中的连接使用旧凭据直至重载）；user add/del 同理。数据库侧口令变更（ALTER ROLE ... PASSWORD）与 vault 更新要同步做，顺序建议先 vault 后数据库。

五、配套工具：curl 抓取 /metrics 与 systemctl

5.1 curl —— Prometheus 视角的端点验证

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

实测回显：

HTTP=200 bytes=380058

输出结构（#HELP/#TYPE 注释 + 样例行，实测）：

#HELP pgexporter_postgresql_uptime Seconds since the PostgreSQL server started
#TYPE pgexporter_postgresql_uptime gauge
pgexporter_postgresql_uptime{server="primary"} 954

自描述指标抽样（实测）：

pgexporter_state 1
pgexporter_query_executions_total 118
pgexporter_postgresql_version{server="primary", version="16", minor_version="15"} 1
pgexporter_postgresql_primary{server="primary"} 1
pgexporter_version{pgexporter_version="0.8.0"} 1

server="primary" 标签可区分多实例（多 Server 段）；pgexporter_query_errors_total/pgexporter_query_timeouts_total 是排障入口（非零时查 log_level 提到 debug 复现）。Prometheus 侧抓取配置按常规 scrape_configs 指向 mon01:8150 即可。

5.2 systemctl —— 服务生命周期

systemctl start|stop|restart|reload|status pgexporter
systemctl enable pgexporter

实测 systemctl status pgexporter --no-pager -l（active 态）：

● 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
   Main PID: 204 (pgexporter)
     Memory: 28.6M (peak: 28.9M)
     CGroup: /system.slice/pgexporter.service
             └─204 "pgexporter: main"

unit 关键项（部署篇第六节）：Type=exec、User=pgexporter、KillSignal=SIGINT、ExecReload=/bin/kill -HUP $MAINPID（HUP 等价 conf reload）。Memory: 28.6M 为空载常驻实测值。

5.3 自定义指标验证闭环（curl + restart）

自定义 YAML 放入 /etc/pgexporter/metrics.d/ 后，systemctl restart pgexporter（-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

YAML 结构与 -Y/metrics_path 加载差异见配置篇第四/2.9 节。

六、命令速查表

需求	命令
存活探测	`pgexporter-cli -c <conf> ping` 或 `curl -s localhost:8150/metrics \| head -1`
看状态/多实例	`pgexporter-cli -c <conf> status [details]`
读运行时参数	`pgexporter-cli -c <conf> conf get <key>` / `conf get server.<名>.<键>`
改运行时参数	`pgexporter-cli -c <conf> conf set <key> <value>`（回显规范值）
热加载配置	`pgexporter-cli -c <conf> conf reload`（看 `Restart` 字段决定是否补重启）
复位指标计数	`pgexporter-cli -c <conf> clear prometheus`
建主密钥	`pgexporter-admin master-key`（≥8 字符；禁 root）
vault 账号增删改查	`pgexporter-admin -f <vault> -U <user> [-P <pwd>] user add\|del\|edit\|ls`
文件加解密（新）	`pgexporter-cli -E aes256 encrypt\|decrypt <in> [out]`
抓指标	`curl -s http://<host>:8150/metrics`
服务生命周期	`systemctl start\|stop\|restart\|reload\|status pgexporter`

七、参考

本专栏系列（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 配置参数详解》——pgexporter.conf 主段/Server 段逐项语义与验证：《pgexporter 0.8.0 配置参数详解》

官方与外部来源

源码内文档：doc/CLI.md（CLI 命令参考）、doc/GETTING_STARTED.md（vault 步骤）、doc/CONSOLE.md（Web 控制台）——0.8.0 源码树实查（encrypt/decrypt 为 -? 实查超出文档部分）
官方文档站：https://pgexporter.github.io/ （查询日期 2026-10-28）
仓库主页：https://github.com/pgexporter/pgexporter
站内相关：《PostgreSQL 18.6 介绍与选型指南》