pgSCV 介绍与选型指南

本文是 pgSCV 系列的第一篇，面向选型与评估。pgSCV（cherts/pgscv）是一款用 Go 编写的 PostgreSQL 生态指标采集器：单二进制常驻进程，通过 HTTP /metrics 端点以 Prometheus 指标格式暴露 PostgreSQL、PgBouncer、Patroni 与操作系统（Linux）四类监控数据。本文所有版本号、发布日期、许可证与星数均于 2026-10-28 通过 GitHub API（api.github.com）与官方仓库实查取证，非引用旧资料。

一、pgSCV 是什么

pgSCV 定位为「PostgreSQL 生态多用途监控代理与指标采集器」。与只盯数据库一个面的普通 exporter 不同，它的采集范围覆盖了单机上数据库实例的完整运行环境：

• PostgreSQL 指标：活动会话、锁、检查点、bgwriter、WAL、归档、复制与复制槽、表/索引/函数/Schema 统计、pg_stat_statements 语句统计、表空间与数据目录体积、pg_stat_io、SLRU、SSL 连接、订阅、设置参数、日志等。
• PgBouncer 指标：pools、stats、settings 三类连接池数据。
• Patroni 指标：通过 Patroni REST API（默认 8008 端口）读取集群角色、leader 状态、复制延迟等高可用信息。
• 操作系统指标（仅 Linux）：CPU、内存、磁盘 I/O、文件系统、网络设备、负载、内核参数、系统信息等，与 node_exporter 同源的 node_* 命名体系。

核心特性清单（摘自官方 README 并经本文实测确认）：

• 同时监控多个服务实例：一个采集进程内可注册多个 PostgreSQL/PgBouncer/Patroni 服务，共享一个 /metrics 端点。
• Prometheus 服务发现：/targets 端点以 JSON 返回全部已注册服务的抓取地址，可被 Prometheus http_sd_config 直接消费。
• 节流与并发限制：throttling_interval、concurrency_limit 可限制抓取频率与并行采集数，保护高负载实例。
• TLS 与 HTTP Basic 认证：/metrics 端点可用用户名口令与自签/正式证书保护。
• 用户自定义指标：collectors.postgres/custom 允许用任意 SQL 定义新指标（COUNTER/GAUGE）。
• 采集器管理：内置约 40 个采集器可逐个禁用，或按标签值（设备名、网卡、文件系统、用户、数据库等）过滤。
• 服务配置自动刷新：refresh_service_config_interval 定时重读服务连接配置，另有手动 /flush-services-config 端点。
• 云托管数据库发现：支持 Yandex Managed Service for PostgreSQL 的 API 自动发现（v0.15.x 新增）。

在 Ubuntu 22.04 + PostgreSQL 16.15 + pgSCV 0.15.3 的实测环境中，默认开启全部采集器时 /metrics 单次抓取返回约 440 个指标族（HELP 行计），其中 node_* 系统指标 297 个、postgres_* 数据库指标 102 个，外加 Go 运行时与采集器自监控指标。

二、上游溯源：两代仓库与当前主线

pgSCV 的上游历史上分两代，选型时必须区分清楚：

第一代：lesovsky/pgscv（原版，已归档）

• 作者 Alexey Lesovsky（《PostgreSQL High Performance Cookbook》合著者、pgcenter 作者），仓库创建于 2018-10-15。
• 最初服务于 Weaponry 监控平台，后迁出并去除平台专属功能（自动发现、bootstrap、指标推送、Patroni 支持等）。
• 最后一个正式稳定版 0.7.5（2021-09-02），最后一个 beta 为 v0.8.0-beta.6（2022-08-05）。
• 仓库现处于 archived 状态（2026-10-28 查询 archived: true，最后 push 2024-08-22），README 明确声明「pgSCV is archived and is not maintained」并指向继任 fork。
• 当前 173 stars / 42 forks。

第二代：cherts/pgscv（活跃维护版，本文系列的对象）

• 2024-02-11 由 Mikhail Grigorev（GitHub ID：CHERTS）创建 fork，README 声明「This project is a continuation of the development of the original pgSCV by Alexey Lesovsky」。
• 默认分支 release/0.15，贡献者含 Dmitry Bulashev、Stanislav Stolbov。
• 版本线（GitHub Releases 实查）：v0.14.2（2025-07-01）→ v0.15.0（2025-09-16）→ v0.15.1（2025-12-26）→ v0.15.2（2026-03-10）→ v0.15.3（2026-07-20，最新稳定版）；仓库最后 push 2026-10-27（含 dev-pg19 开发分支，正在跟进 PostgreSQL 19）。
• 当前 137 stars / 15 forks / 22 个开放 issue。
• v0.15.3 changelog 亮点：为 Debian/Ubuntu（deb）、RedHat 系（rpm）、Alpine（apk）构建官方软件包；驱动迁移到 pgx/v5；修复 system/filesystems 采集器 goroutine 泄漏（issue #336）；修复表/索引统计与 pg_subscription_rel 统计；更新 Grafana 仪表盘。

结论：生产选型应以 cherts/pgscv 的 v0.15.3 为准；lesovsky/pgscv 仅作历史溯源与老版本升级路线参考。

三、技术栈与架构

• 语言与依赖：纯 Go 实现（实测 --version 输出 pgscv v0.15.3 (amd64)，运行时 go_info 显示 go1.26.5）。数据库访问用 pgx/v5 纯 Go 驱动，命令行解析用 kingpin/v2，指标输出用 prometheus/client_golang。不依赖 libpq、不依赖任何运行时，编译产物是单个静态二进制。
• 二进制体积：deb 包安装的 /usr/sbin/pgscv 实测 96,739,672 字节（约 92 MiB），安装后总占用约 94.5 MB（Installed-Size 94485 KB）。
• 架构形态：单进程常驻。进程内三层结构——配置层（YAML 文件 + 环境变量合并，env 覆盖同名文件项）、服务注册层（每个被监控服务注册为 service_id，如 postgres:5432、system:0，注册时验证连通性）、采集器层（每个服务挂载一组采集器，抓取时执行 SQL 或读 /proc，转换为 Prometheus 指标经 HTTP 暴露）。
• HTTP 端点：/metrics（全部指标，可带 ?target=<service_id> 定向抓取单服务）、/targets（服务发现 JSON）、/flush-services-config（POST，手动重载服务配置）。默认监听 127.0.0.1:9890。
• 运行身份：官方 systemd 单元以 postgres 系统用户运行（便于走 peer/本地连接与读日志），单元文件含 Restart=on-failure、OOMScoreAdjust=1000 等运维参数。
• 内建采集器清单（来自官方配置样例，可整体禁用）：system 系 10 个（loadaverage、cpu、diskstats、filesystems、netdev、network、memory、sysconfig、sysinfo、pgscv 自监控）、postgres 系 24 个（activity、archiver、bgwriter、conflicts、databases、indexes、functions、locks、logs、replication、replication_slots、statements、schemas、settings、storage、stat_io、stat_slru、stat_subscription、subscription_rel、stat_ssl、tables、wal、custom、pgscv 自监控）、pgbouncer 系 4 个、patroni 系 2 个，合计约 40 个。

四、许可与发行形态

• 许可证：BSD-3-Clause（GitHub API 与仓库 LICENSE 文件一致，deb 包内亦随附 /usr/share/doc/pgscv/LICENSE），对商用集成友好，无 copyleft 传染。
• 官方预构建发行（v0.15.3 Release Assets 实查，均在 releases 页可下载）：
  • pgscv_0.15.3_amd64.deb / arm64.deb / armhf.deb / i386.deb——Debian/Ubuntu 软件包，内含二进制、systemd 单元、/etc/pgscv.yaml 与 /etc/default/pgscv；
  • pgscv-0.15.3-1.x86_64.rpm / aarch64 / armv6hl / i386——RHEL 系软件包；
  • pgscv_0.15.3_x86_64.apk 等——Alpine 软件包；
  • pgscv_0.15.3_linux_x86_64.tar.gz 等——裸压缩包（内含 pgscv 二进制、pgscv.yaml、pgscv.service、pgscv.default 四件套）；
  • pgscv-0.15.3-source.tar.gz——源码包。
• 上游打包文件布局在两种形态间保持一致（/usr/sbin/pgscv、/etc/pgscv.yaml、/lib/systemd/system/pgscv.service、/etc/default/pgscv），升级与配置迁移成本低。
• 配套资产：官方提供 4 张 Grafana 仪表盘（System 21409、PostgreSQL 21430、Pgbouncer 21429、Patroni 21462，均上架 grafana.com）、COSIGN 签名校验说明、以及可一键拉起的 demo-lab 演示环境。

四点五、指标命名与标签体系（实测样张）

pgSCV 指标命名遵循「域_子系统_指标」三级约定，标签统一附加 database、host、port、service_id。以下为实测环境中直接从 /metrics 截取的真实输出：

postgres_up{host="127.0.0.1",port="5432",service_id="postgres:5432"} 1
postgres_database_size_bytes{database="benchdb",host="127.0.0.1",port="5432",service_id="postgres:5432"} 8.6514711e+07
postgres_activity_queries_in_flight{...state="active",...} 3
postgres_wal_records_total{...} 4.2e+05
node_cpu_seconds_total{cpu="0",mode="idle"} 2834.55
node_memory_MemAvailable_bytes 1.62e+09
pgscv_services_registered_total{service="postgres",service_id="postgres:5432",...} 1

命名体系的三点观察：

• node_* 与 node_exporter 完全同源，系统层仪表盘/告警规则可直接复用；
• postgres_* 按「activity / database / wal / checkpoints / bgwriter / locks / statements / stat_io …」子系统分组，与 PostgreSQL 官方统计视图一一对应，学习成本低；
• 自定义指标自动归入 postgres_<子系统>_<指标名> 命名空间并继承公共标签，不会与内建指标冲突。

自监控指标（pgscv_services_registered_total 等）由 */pgscv 系采集器输出，可用于监控「监控器本身」——采集器掉线时该序列消失，是最可靠的 agent 存活探针。

五、竞品量化对比

以下数据全部于 2026-10-28 通过 GitHub API 实查（星数为当日值），版本与日期取各自仓库最新 Release：

横向解读：

1. 对 postgres_exporter：后者是 Prometheus 官方社区的标准选择、生态默认与 Grafana 模板的事实基准，但只覆盖数据库本身。pgSCV 的差异点是「一个进程覆盖 OS + PG + 池 + HA 三层」，省去 node_exporter + pgbouncer_exporter + patroni 采集的多进程组合；且指标名直接带 node_* 前缀，与 node_exporter 仪表盘习惯兼容。若团队只要 PG 指标且要最大社区支持，postgres_exporter 仍更稳；若要单机一体化监控，pgSCV 更省事。
2. 对 pgexporter：两者哲学接近（单一二进制、系统级采集、官方软件包、BSD-3）。pgexporter 是 C 语言实现、依赖 libpq、主打 PostgreSQL 官方生态位；pgSCV 是 Go 实现、零依赖、外加 PgBouncer/Patroni 覆盖。pgexporter 由 PostgreSQL 社区人物主导（前批文档已详测），pgSCV 由个人维护者驱动，响应速度快但巴士因子低。
3. 对 pgwatch：pgwatch 是「监控平台」而非「采集器」——自带存储、Web UI、告警，体量大。若已有 Prometheus/Grafana 技术栈，pgSCV 这类纯 exporter 更贴合；要从零起步且不想搭 Prometheus，pgwatch 一体化更省。
4. 对 Patroni 自带 metrics：Patroni REST API 自带 /metrics，只覆盖 HA 状态；pgSCV 的 patroni 采集器消费同一 API，可与 PG 指标同端点出数，减少 scrape 配置条目。
5. 风险提示：cherts/pgscv 主要维护者为个人（另有两位贡献者），issue 响应依赖维护者个人投入；对比 prometheus-community 的组织化维护，这是选型时需要接受的权衡。原版归档、fork 接续的历史也提示应锁定版本、自留构建能力。

六、适用与不适用场景

适合：

• 单机或少量实例的自管 PostgreSQL，希望一个采集进程同时拿到系统层与数据库层指标；
• PgBouncer 池化 + Patroni 高可用组合栈，想减少 exporter 进程数量；
• 已有 Prometheus，需要 /targets 服务发现与可定制抓取保护的场景；
• 需要「库表/索引/语句 Top-N 可控」与自定义 SQL 指标的运维团队。

不适合：

• 只需要最标准 PG 指标、追求最大社区与模板生态——选 postgres_exporter；
• 非 Linux 的系统层采集需求——pgSCV 只在 Linux 上运行（可连远端其他系统的数据库服务，但 OS 指标仅本机 Linux）；
• 需要 APM/慢查询文本级分析——那是 pgwatch、pganalyze 或日志类工具的领地；
• Windows 服务器本机监控。

六点五、版本兼容与依赖要求

• 操作系统：pgSCV 只在 Linux 上运行（官方 README 明确「Can run on Linux only」）；被监控的数据库服务可以运行在其他系统或云托管环境，但操作系统指标只针对本机 Linux。
• PostgreSQL 版本：官方 wiki 口径支持 PostgreSQL 12 及以上；部分采集器按版本特性自适应（如 PG16 的 pg_stat_io 采集器在旧版本上自动无输出）。v0.15 线已实测兼容 PostgreSQL 16.15；dev-pg19 分支表明 PG19 支持在演进中。
• 扩展依赖：statements 采集器需要目标库启用 pg_stat_statements（shared_preload_libraries 预加载 + CREATE EXTENSION）；postgres/logs 采集器需要运行账号可读日志文件——官方默认让服务以 postgres 系统用户运行正是为此。
• 账号权限：监控账号授予 pg_monitor 系统角色即可满足绝大多数采集器；个别采集器（读 pg_stat_statements 文本、日志文件）需要更细粒度授权，官方 wiki 的 Security considerations 页有最小权限清单。
• Go 运行时：无。静态单二进制，deb/rpm/apk 包互不依赖第三方库，嵌入式/极简系统也能跑（apk 包即为此场景准备）。

七、本系列导航

• 部署落地：pgSCV 安装部署指南 —— Ubuntu 22.04 官方 deb + systemd 全流程实测与排障实录。
• 配置详解：pgSCV 配置参数详解 —— 全部 YAML 参数与环境变量逐项实测。
• 运维操作：pgSCV 常用 CLI 命令详解 —— 命令行参数、服务管控与 HTTP 端点操作实测。