pgSCV 常用 CLI 命令详解

本文是 pgSCV 系列第四篇，覆盖日常运维 pgSCV 0.15.3 的全部操作面：二进制命令行参数、systemd 服务管控、HTTP 端点（/metrics、/targets、/flush-services-config）验证、日志观察与故障注入。所有回显均在 Ubuntu 22.04 + PostgreSQL 16.15 + pgSCV 0.15.3 + systemd 实测环境真实执行截取。

一、命令行参数（pgscv 自身 CLI）

pgSCV 是单二进制程序，CLI 面很小，全部参数如下（--help 实测回显）：

root@pgscv-lab:~# /usr/sbin/pgscv --help
usage: pgscv [<flags>]

Flags:
  --[no-]help         Show context-sensitive help (also try --help-long and
                      --help-man).
  --[no-]version      show version and exit
  --log-level="info"  set log level: debug, info, warn, error ($LOG_LEVEL)
  --config-file=""    path to config file ($PGSCV_CONFIG_FILE)

root@pgscv-lab:~# echo $?
0

1）--version：版本与构建信息（排障第一步）

root@pgscv-lab:~# /usr/sbin/pgscv --version
pgscv v0.15.3 (amd64) 9f2676dba1045b0a49d267b8961dc69e04654e39-HEAD

格式为 名称版本 (架构) gitcommit-分支。报 issue、对 changelog 时以此输出为准，比 dpkg 查询更直接（dpkg -s pgscv | grep Version 结果同为 0.15.3）。

2）--config-file：指定主配置

root@pgscv-lab:~# /usr/sbin/pgscv --config-file=/nonexistent.yaml
{"level":"info",...,"message":"starting pgscv v0.15.3 (amd64) 9f2676dba1045b0a49d267b8961dc69e04654e39-HEAD"}
{"level":"info",...,"message":"reading file information /nonexistent.yaml"}
{"level":"error",...,"message":"create config failed: lstat /nonexistent.yaml: no such file or directory"}
root@pgscv-lab:~# echo $?
1

指向目录同样失败（lstat 后判定为目录返回错误）。systemd 场景下该参数由 /etc/default/pgscv 注入：

root@pgscv-lab:~# cat /etc/default/pgscv
ARGS='--config-file=/etc/pgscv.yaml'

3）--log-level：日志级别

四档：debug/info/warn/error。前台运行用 debug 观察采集器装配过程（截选）：

root@pgscv-lab:~# /usr/sbin/pgscv --config-file=/etc/pgscv.yaml --log-level=debug 2>&1 | grep -E 'enable postgres|available through' | head -5
{"level":"debug",...,"message":"service [live:1] available through: pgscv@127.0.0.1:5432/postgres"}
{"level":"debug",...,"message":"enable postgres/logs"}
{"level":"debug",...,"message":"enable postgres/settings"}
{"level":"debug",...,"message":"enable postgres/storage"}

两点注意：debug 日志含含口令的 DSN 明文，生产勿常开；传入未定义的级别（如 verbose）不报错，按 info 处理。systemd 常驻时改级别用环境文件：ARGS='--config-file=/etc/pgscv.yaml --log-level=warn' 后重启，或临时 LOG_LEVEL=debug systemd-run 试验。

4）前台运行与信号退出

pgSCV 无 run 子命令，直接执行即前台运行；SIGINT/SIGTERM 触发优雅退出：

root@pgscv-lab:~# timeout --signal=TERM 5 /usr/sbin/pgscv --config-file=/etc/pgscv.yaml
...（正常抓取日志）...
{"level":"warn",...,"message":"received shutdown signal: 'terminated'"}

裸跑（无配置、无环境变量）会被拒绝：

{"level":"warn",...,"message":"received shutdown signal: 'no services defined'"}

二、systemd 服务管控

官方单元 /lib/systemd/system/pgscv.service 关键参数：Type=simple、User=postgres、EnvironmentFile=-/etc/default/pgscv、ExecStart=/usr/sbin/pgscv $ARGS、Restart=on-failure、RestartSec=10、TimeoutSec=5、OOMScoreAdjust=1000、WantedBy=multi-user.target、Requires/After=network-online.target。

常用管控命令实测：

root@pgscv-lab:~# systemctl enable --now pgscv
Created symlink /etc/systemd/system/multi-user.target.wants/pgscv.service → /lib/systemd/system/pgscv.service.
root@pgscv-lab:~# systemctl restart pgscv        # 配置变更后的标准生效方式
root@pgscv-lab:~# systemctl is-active pgscv
active
root@pgscv-lab:~# systemctl status pgscv --no-pager | head -8
● pgscv.service - pgSCV - PostgreSQL ecosystem metrics collector
     Loaded: loaded (/lib/systemd/system/pgscv.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2026-10-28 15:14:32 UTC; 3s ago
   Main PID: 6655 (pgscv)
      Tasks: 11 (limit: 2932)
     Memory: 13.1M
        CPU: 30ms

改过单元文件后需要 systemctl daemon-reload 再 restart（deb 升级覆盖单元文件时同样）。

三、journalctl 日志观察

启动全过程（截选关键行）：

root@pgscv-lab:~# journalctl -u pgscv --no-pager -n 12 | grep -oE '"message":"[^"]+"'
"message":"starting pgscv v0.15.3 (amd64) 9f2676dba1045b0a49d267b8961dc69e04654e39-HEAD"
"message":"read configuration from /etc/pgscv.yaml"
"message":"read configuration from environment"
"message":"no-track disabled, for details check the documentation about 'no_track_mode' option."
"message":"option 'databases' is deprecated and removed in next major release."
"message":"registered new service [system:0]"
"message":"registered new service [postgres:5432]"
"message":"listen on http://0.0.0.0:9890"

日志为 JSON 行格式，grep -oE '"message":"[^"]+"' 是快速提取可读信息的实用技巧。错误级别快速过滤：

root@pgscv-lab:~# journalctl -u pgscv --since -10min -p warning --no-pager | grep -c 'level":"warn'

典型需要警惕的日志：failed to connect（服务连不上）、update service config failed（skip_conn_error_mode 下的重试）、TLS handshake error（明文请求打到 TLS 端口）。

四、/metrics 端点验证

1）总量与健康指标

root@pgscv-lab:~# curl -s http://127.0.0.1:9890/metrics | grep -E '^postgres_up'
postgres_up{host="127.0.0.1",port="5432",service_id="postgres:5432"} 1
root@pgscv-lab:~# curl -s http://127.0.0.1:9890/metrics | grep -E '^pgscv_services_registered_total'
pgscv_services_registered_total{host="127.0.0.1",port="5432",service="postgres",service_id="postgres:5432"} 1
pgscv_services_registered_total{host="pgscv-lab",service="system",service_id="system:0"} 1

postgres_up 1 是最核心的健康探针。业务指标抽查（pgbench 造数后）：

root@pgscv-lab:~# curl -s http://127.0.0.1:9890/metrics | grep '^postgres_database_size_bytes{database="benchdb"'
postgres_database_size_bytes{database="benchdb",host="127.0.0.1",port="5432",service_id="postgres:5432"} 8.6514711e+07

2）指标规模盘点

root@pgscv-lab:~# curl -s http://127.0.0.1:9890/metrics | grep -c '^# HELP'
453
root@pgscv-lab:~# curl -s http://127.0.0.1:9890/metrics | grep '^# HELP' | awk '{print $3}' | sed 's/{.*//' | awk -F_ '{print $1}' | sort | uniq -c
    29 go
   297 node
     1 pgscv
   132 postgres
     9 process
     2 promhttp

（不同配置下 postgres/node 计数会变化；上表为禁用 postgres/tables 后的实测值。）

3）定向抓取单服务

root@pgscv-lab:~# curl -s 'http://127.0.0.1:9890/metrics?target=postgres:5432' | grep -c '^# HELP'
156
root@pgscv-lab:~# curl -s 'http://127.0.0.1:9890/metrics?target=system:0' | grep -c '^# HELP'
338
root@pgscv-lab:~# curl -s -o /dev/null -w '%{http_code}\n' 'http://127.0.0.1:9890/metrics?target=nosuch:1'
404

?target=<service_id> 只返回该服务的指标，适合大库分片抓取；不存在的 service_id 返回 404。

4）开启认证后的访问

root@pgscv-lab:~# curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9890/metrics
401
root@pgscv-lab:~# curl -s -u monitoring:<口令> -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9890/metrics
200

五、/targets 服务发现端点

root@pgscv-lab:~# curl -s http://127.0.0.1:9890/targets
[{"targets":["127.0.0.1:9890/metrics?target=system:0","127.0.0.1:9890/metrics?target=postgres:5432"]}]

返回 Prometheus http_sd_config 兼容的 JSON：每个已注册服务一个带 ?target= 的抓取 URL。Prometheus 侧配置：

  - job_name: pgscv
    http_sd_config:
      url: http://127.0.0.1:9890/targets
    refresh_interval: 1m

注意实测该端点不受 authentication 保护（无凭据 200），暴露面规划时单独评估。

六、/flush-services-config 配置热刷新

不重启进程重读服务连接配置（新增/修改 services 条目后使用）：

root@pgscv-lab:~# curl -s -X POST http://127.0.0.1:9890/flush-services-config
{"Status":"OK"}

与 refresh_service_config_interval 自动刷新等效；GET 方式返回 405。注意它刷新的是服务清单，listen_address、认证等全局参数仍需 restart 生效。

七、日常巡检命令速查

操作	命令
版本	`/usr/sbin/pgscv --version`
服务状态	`systemctl is-active pgscv && systemctl status pgscv --no-pager`
配置生效	`systemctl restart pgscv`
服务清单热刷新	`curl -s -X POST http://127.0.0.1:9890/flush-services-config`
数据库健康	`curl -s :9890/metrics \| grep '^postgres_up'`
服务发现	`curl -s :9890/targets`
指标规模	`curl -s :9890/metrics \| grep -c '^# HELP'`
启动失败定位	`journalctl -u pgscv -n 50 --no-pager`
单元内容	`systemctl cat pgscv`
包文件清单	`dpkg -L pgscv`

八、故障注入实测速查

以下故障均在实测环境复现，回显与处置：

端口被占：received shutdown signal: 'listen tcp 127.0.0.1:9890: bind: address already in use'——先 pkill -x pgscv 清掉前台残留进程再 start；
服务连不上（默认模式）：failed to connect to ... dial tcp 127.0.0.1:9999: connect: connection refused skip——该服务不注册，其余正常；改 skip_conn_error_mode: true 后服务注册并周期重试；
明文访问 TLS 端口：HTTP 400 + 日志 http: TLS handshake error ... client sent an HTTP request to an HTTPS server——换 https 或去掉证书配置；
配置文件缺失/YAML 语法错：exit 1，create config failed: ...——修配置后 restart；
零服务：裸跑退出 no services defined——pgSCV 拒绝无服务运行；
metric 端点 401：认证开启后带 -u user:pass 重试；
下载截断：Release 资产校验 sha256sum -c checksums.txt，curl -C - 续传。

pgSCV 常用 CLI 命令详解

pgSCV 常用 CLI 命令详解

一、命令行参数（pgscv 自身 CLI）

二、systemd 服务管控

三、journalctl 日志观察

四、/metrics 端点验证

五、/targets 服务发现端点

六、/flush-services-config 配置热刷新

七、日常巡检命令速查

八、故障注入实测速查

九、本系列导航