postgres_exporter 0.20.1 常用 CLI 命令与工具详解

目标：给出 postgres_exporter 0.20.1 日常运维会用到的每一条命令——进程自查、前台调试、systemd 管控、端点验证、数据库侧配合——全部附 2026-10-28 真实执行回显。参数语义与生效机制见 C1 配置参数详解，安装与 systemd 单元见 B1 安装指南，选型背景见 A1 介绍与选型指南。

一、命令入口总览

postgres_exporter 是无子命令的单二进制：所有行为由旗标与环境变量驱动（参数清单见 C1），日常运维围绕四个入口展开：

入口	命令	用途
进程自查	`--version`、`--help`、`--dumpmaps`	版本核对、参数速查、内置指标映射调试
进程管控	`systemctl` / `journalctl`	常驻托管启停与日志
HTTP 端点	`curl /metrics`、`/probe`、`/debug/pprof/`	指标验证、多目标探测、性能剖析
数据库侧	`pg_isready`、`psql`	连通预检与权限/扩展配合

本文实测环境与 B1 一致：导出器宿主 Ubuntu 26.04.1（x86_64），二进制位于 /root/.local/bin/postgres_exporter，监听 :8150；被监控 PostgreSQL 16.15 位于实验网段内 10.89.74.10:5432。

二、进程自查命令

2.1 --version：版本与构建指纹

$ /root/.local/bin/postgres_exporter --version
postgres_exporter, version 0.20.1 (branch: HEAD, revision: 867fbcac31cd18c143e244190ea9168cca069827)
  build user:       root@f281ca536a03
  build date:       20260708-01:46:52
  go version:       go1.26.4
  platform:         linux/amd64
  tags:             unknown

五个字段与上游 Release 对账：版本 0.20.1、构建日期 2026-07-08、Go 1.26.4、linux/amd64。revision 可直接在 GitHub 仓库按 commit 检索溯源。

2.2 --help / --help-long / --help-man

--help 输出全部 26 个 --collector.* 开关与通用旗标，并在括号内标注环境变量对应关系（如 --web.telemetry-path="/metrics" ... ($PG_EXPORTER_WEB_TELEMETRY_PATH)），是 C1 参数表的权威出处；kingpin 解析器还提供 --help-long（展开更细）与 --help-man（man 手册格式）两个变体，便于离线检索。

2.3 --dumpmaps：打印内置指标映射

不启动服务、打印默认指标映射后立即退出（exit 0），用于调试 queries.yaml 列映射或核对某指标的字段语义：

$ DATA_SOURCE_NAME='postgresql://exporter:exp2026@10.89.74.10:5432/appdb?sslmode=disable' \
    /root/.local/bin/postgres_exporter --dumpmaps
  datid                                    {1 OID of a database map[] <nil>}
  datname                                  {1 Name of this database map[] <nil>}
  confl_tablespace                         {2 Number of queries in this database that have been canceled due to dropped tablespaces map[] <nil>}
  confl_lock                               {2 Number of queries in this database that have been canceled due to lock timeouts map[] <nil>}
  confl_snapshot                           {2 Number of queries in this database that have been canceled due to old snapshots map[] <nil>}
  confl_bufferpin                          {2 Number of queries in this database that have been canceled due to pinned buffers map[] <nil>}
  confl_deadlock                           {2 Number of queries in this database that have been canceled due to deadlocks map[] <nil>}

花括号内首数字为值类型（1=Counter、2=Gauge），随后是列说明与标签映射。这些 confl_* 列正是 C1 第四节提到的、由 database collector 名下产出的 pg_stat_database_conflicts_* 指标。

三、前台运行与日志调试

排障时先绕开 systemd 前台跑，看第一手日志（正常 logfmt 格式）：

$ DATA_SOURCE_NAME='postgresql://exporter:exp2026@10.89.74.10:5432/appdb?sslmode=disable' \
    /root/.local/bin/postgres_exporter --web.listen-address=:8150
time=2026-10-28T23:28:00.110+08:00 level=WARN source=main.go:81 msg="Error loading config" err="error opening config file \"postgres_exporter.yml\": open postgres_exporter.yml: no such file or directory"
time=2026-10-28T23:28:00.110+08:00 level=INFO source=main.go:91 msg="Excluded databases" databases=[]
time=2026-10-28T23:28:00.110+08:00 level=WARN source=main.go:94 msg="The extended queries.yaml config is DEPRECATED" file=/root/.local/share/postgres_exporter/queries.yaml
time=2026-10-28T23:28:00.110+08:00 level=INFO source=tls_config.go:372 msg="Listening on" address=[::]:8150
time=2026-10-28T23:28:00.110+08:00 level=INFO source=tls_config.go:375 msg="TLS is disabled." http2=false address=[::]:8150

两条 WARN 均非致命：config.file 缺省文件不存在只告警继续跑；queries.yaml 路径已标 DEPRECATED 但功能正常。接 Prometheus 抓取后追加两条关键 INFO——连接建立与版本探测：

level=INFO source=server.go:96 msg="Established new database connection" fingerprint=10.89.74.10:5432
level=INFO source=postgres_exporter.go:537 msg="Semantic version changed" server=10.89.74.10:5432 from=0.0.0 to=16.15.0

接入日志采集器时切 JSON 输出（--log.format=json --log.level=debug），实测结构化行：

{"time":"2026-10-28T23:38:17.24510927+08:00","level":"WARN","source":"main.go:81","msg":"Error loading config","err":"error opening config file \"postgres_exporter.yml\": open postgres_exporter.yml: no such file or directory"}
{"time":"2026-10-28T23:38:17.245498178+08:00","level":"INFO","source":"tls_config.go:372","msg":"Listening on","address":"[::]:8161"}

四、systemd 管控命令

B1 给出的单元文件（或验证环境等价的 transient 单元）落地后，日常管控四件套实测：

$ systemctl restart postgres-exporter && systemctl is-active postgres-exporter
active
$ systemctl stop postgres-exporter && systemctl is-active postgres-exporter && systemctl is-failed postgres-exporter
inactive
inactive
$ journalctl -u postgres-exporter --no-pager -n 4 -o cat
time=2026-10-28T23:37:58.257+08:00 level=INFO source=tls_config.go:375 msg="TLS is disabled." http2=false address=[::]:8150
Stopping postgres-exporter.service - Prometheus exporter for PostgreSQL (lab)...
postgres-exporter.service: Deactivated successfully.
Stopped postgres-exporter.service - Prometheus exporter for PostgreSQL (lab).

要点：is-failed 输出 inactive 说明上次 stop 是干净退出（若端口占用等启动失败会显示 failed）；跟日志用 journalctl -u postgres-exporter -f；查询进程号 systemctl show -p MainPID postgres-exporter。配置变更（env 文件、queries.yaml）后都需 restart 生效。

五、HTTP 端点验证命令

5.1 /metrics 指标抓取与体检三连

$ curl -s -o /tmp/metrics.txt -w 'HTTP %{http_code}, %{size_download} bytes\n' http://127.0.0.1:8150/metrics
HTTP 200, 91929 bytes
$ grep -E '^pg_up|^pg_exporter_(last_scrape_error|scrapes_total)' /tmp/metrics.txt
pg_up 1
pg_exporter_last_scrape_error 0
pg_exporter_scrapes_total 7

体检语义：pg_up 1 = 最近一轮抓取能连上库；pg_exporter_last_scrape_error 0 = 本轮无致命错误；两者同时为 0/1 才算健康。再看采集器成色（15 个默认 collector 全绿）：

$ grep -oE '^pg_scrape_collector_success\{collector="[a-z_]+"' /tmp/metrics.txt | grep -oE '[a-z_]+"$' | sort | tr '\n' ' '
database locks replication replication_slots roles settings stat_activity stat_archiver
stat_bgwriter stat_database statio_user_tables stat_progress_vacuum stat_replication
stat_user_tables wal
$ grep -c '^pg_scrape_collector_success{.*} 0' /tmp/metrics.txt
0

5.2 /probe：多目标探测（BETA）

以 --config.file（auth_modules 见 C1 第七节）启动的实例，可对任意目标按需探测，无需为它写环境变量：

$ curl -s -o /tmp/probe_out.txt -w 'HTTP %{http_code}, %{size_download} bytes\n' \
    'http://127.0.0.1:8160/probe?target=10.89.74.10:5432/postgres&auth_module=lab1'
HTTP 200, 74999 bytes
$ grep -E '^pg_up|^pg_stat_database_numbackends' /tmp/probe_out.txt | head -5
pg_stat_database_numbackends{datid="1",datname="template1"} 0
pg_stat_database_numbackends{datid="16390",datname="appdb"} 1
pg_stat_database_numbackends{datid="4",datname="template0"} 0
pg_stat_database_numbackends{datid="5",datname="postgres"} 2
pg_up 1

注意 /probe 输出不带 server 标签（目标即抓取对象本身）。Prometheus 侧配套 relabel（把抓取地址改写到 exporter、原始地址传给 target 参数）按 README 示例配置即可。目标不可达时 /probe 返回 500 且响应体含错误文本，可用于抓取前预检。

5.3 诊断端点

/debug/pprof/（0.19.0 起启用）HTTP 200，可在指标毛刺时抓 CPU/堆剖面；根路径 / 返回 200（导出器首页文本）；--web.telemetry-path 改名后注意 Prometheus metrics_path 同步（C1 第三节实测 404/200 对照）。

六、数据库侧配合命令

6.1 连通预检

$ pg_isready -h 10.89.74.10 -p 5432
10.89.74.10:5432 - accepting connections

accepting connections 只代表端口层可用；认证/授权问题仍要看导出器日志（B1 实录一/二）。

6.2 权限与扩展准备（psql）

首次部署四连（真实回显）：

postgres=# CREATE ROLE exporter LOGIN PASSWORD 'exp2026';
CREATE ROLE
postgres=# GRANT pg_monitor TO exporter;
GRANT ROLE
appdb=# CREATE EXTENSION pg_stat_statements;
CREATE EXTENSION
appdb=# GRANT SELECT ON orders TO exporter;
GRANT

核对账号属性：

postgres=# \du
                             List of roles
 Role name |                         Attributes
-----------+------------------------------------------------------------
 exporter  |
 postgres  | Superuser, Create role, Create DB, Replication, Bypass RLS
 viewer    |

（exporter 无特殊属性是正常的，pg_monitor 属于角色成员关系，可用 SELECT pg_has_role('exporter','pg_monitor','member'); 二次确认。）

6.3 统计配合命令

三类运维动作配合实测（超管执行）：

appdb=# SELECT pg_stat_statements_reset();
 pg_stat_statements_reset
--------------------------

(1 row)

appdb=# SELECT pg_stat_reset();
 pg_stat_reset
---------------

(1 row)

appdb=# SELECT pg_reload_conf();
 pg_reload_conf
----------------
 t
(1 row)

用途：压测前重置语句统计让 pg_stat_statements_* 指标从零累积；修改 postgresql.conf 后 pg_reload_conf() 热加载，随后在 pg_settings 指标里核对生效值（pending_restart 类参数需重启实例）。

七、日常运维组合拳

新增一个自定义指标（全链路，五步）：

psql 里试跑 SQL 并确认采集账号可执行（缺就 GRANT SELECT）；
追加到 /root/.local/share/postgres_exporter/queries.yaml（格式与 usage 取值见 C1 第六节）；
python3 -c "import yaml,sys; yaml.safe_load(open('queries.yaml'))" 本地先校验（坏文件不会让进程退出，只会让自定义指标静默消失，见 C1 实测）；
systemctl restart postgres-exporter；
curl -s http://127.0.0.1:8150/metrics | grep '^app_' 验证出数。

收敛指标面：先 grep pg_scrape_collector_success 列出在跑 collector，再按需加 --no-collector.<名> 重启，逐个验证归零（注意 pg_stat_database_conflicts_* 归属 database collector 的坑，见 C1）。

密码轮换：库端 ALTER ROLE exporter PASSWORD ... → 改 env 文件 → systemctl restart → pg_up 1 复核；窗口期内日志会出现实录二式的认证失败，属预期。

八、排障速查表

症状	首查命令	定位	详见
`pg_up 0` + SSL 报错	连接串是否带 `?sslmode=disable`	lib/pq 默认 require	B1 实录一
`pg_up 0` + password failed	env 密码 / pg_hba.conf	认证	B1 实录二
`pg_up 1` 但个别指标缺失	`pg_scrape_collector_success{...} 0`	单 collector 权限（如 `pg_ls_waldir`）	B1 实录三
自定义指标消失、`last_scrape_error 1`	journalctl 查 `permission denied`	业务表未 GRANT	C1 实测
进程活着但只有 29 条指标	查 `Failed to create PostgresCollector`	`PG_EXPORTER_COLLECTION_TIMEOUT` 非法	C1 实测
配置改了没生效	是否重启进程	全量重启生效	C1 第八节
`disable-default-metrics`/`metric-prefix` 无效	0.20.0 BREAKING CHANGES	已失效，改用 `--no-collector.*`	C1 第五节

九、参考与延伸

本专栏系列：A1 介绍与选型指南、B1 安装指南、C1 配置参数详解。
上游：v0.20.1 README（Multi-Target Support / Running the tests 章节）、exporter-toolkit pprof 文档。
站内延伸（姊妹组件）：pgexporter 0.8.0 常用 CLI 命令与工具详解。