pgSCV 安装部署指南（Ubuntu 22.04）

在 Ubuntu 22.04 上以官方 deb 软件包安装 pgSCV 0.15.3 的全流程实测：PGDG PostgreSQL 16 被监控端准备、监控账号与 pg_stat_statements 配置、sha256 下载校验、dpkg 安装与文件布局、systemd 托管、/metrics 与 Prometheus 抓取闭环、tar.gz 手工路线与四则排障实录。

pgSCVpgSCVPostgreSQLPrometheus监控可观测性2026/10/28

pgSCV 安装部署指南（Ubuntu 22.04）

本文是 pgSCV 系列第二篇，在 Ubuntu 22.04 LTS 上完成 pgSCV 0.15.3 的生产形态安装：官方 deb 软件包 + PostgreSQL 16（PGDG 仓库）被监控端 + systemd 常驻托管 + Prometheus 抓取闭环。文中全部命令与回显均在实测环境（Ubuntu 22.04、PostgreSQL 16.15-1.pgdg22.04+2、pgscv 0.15.3、内核 5.15 x86_64）真实执行通过；下载校验、服务启动、连接失败的三个真实坑沉淀在排障一节。

一、部署形态选型

先看上游发行形态再定安装方式。pgSCV 0.15.3 的 GitHub Release 提供五类资产（2026-10-28 实查）：

  1. deb 包（pgscv_0.15.3_amd64.deb，30,036,870 字节）——Debian/Ubuntu 官方软件包；
  2. rpm 包（pgscv-0.15.3-1.x86_64.rpm 等）——RHEL 系；
  3. apk 包（pgscv_0.15.3_x86_64.apk 等）——Alpine；
  4. tar.gz 裸包（pgscv_0.15.3_linux_x86_64.tar.gz 等）——内含二进制 + 配置 + systemd 单元四件套；
  5. 源码包（pgscv-0.15.3-source.tar.gz）——Go 源码，可自行构建。

本文选 官方 deb 包作为主线路径：Ubuntu 22.04 属 deb 系，官方包自带 systemd 单元、环境变量文件与样例配置，升级走 dpkg 标准流程，比 tar.gz 手工拷贝更可维护。tar.gz 路线作为附录给出（适合无法用包管理器的环境）。源码构建仅需要 Go 工具链，无 C 依赖，本文不展开。

前提条件：

  • Ubuntu 22.04 LTS（x86_64，实验机为 5.15 内核）；
  • 可访问 GitHub Releases 下载 deb 与 checksums.txt；
  • 已安装或可安装 PostgreSQL（本文用 PGDG 的 PostgreSQL 16）；
  • systemd 可用（Ubuntu 22.04 默认）。

二、安装 PostgreSQL 16 被监控端

pgSCV 需要 PostgreSQL 12 及以上版本作为监控目标。Ubuntu 22.04 自带仓库只有 PG 14，本文按 PGDG 官方仓库装 PG 16，与生产主流版本对齐。

root@pgscv-lab:~# echo deb http://apt.postgresql.org/pub/repos/apt jammy-pgdg main \
  > /etc/apt/sources.list.d/pgdg.list
root@pgscv-lab:~# curl -s https://www.postgresql.org/media/keys/ACCC4CF8.asc \
  -o /tmp/pgdg.asc
root@pgscv-lab:~# gpg --dearmor -o /etc/apt/trusted.gpg.d/pgdg.gpg /tmp/pgdg.asc
root@pgscv-lab:~# apt-get update -qq
root@pgscv-lab:~# DEBIAN_FRONTEND=noninteractive apt-get install -y -qq postgresql-16

启动集群并确认版本与端口：

root@pgscv-lab:~# systemctl start postgresql
root@pgscv-lab:~# pg_lsclusters
Ver Cluster Port Status Owner    Data directory              Log file
16  main    5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log
root@pgscv-lab:~# /usr/lib/postgresql/16/bin/postgres --version
postgres (PostgreSQL) 16.15 (Ubuntu 16.15-1.pgdg22.04+2)

创建监控专用账号。官方安全基线建议专用最小权限账号，授予 pg_monitor 系统角色即可满足绝大多数采集器（语句统计、IO 统计等需要额外扩展配合）：

root@pgscv-lab:~# su - postgres -c "psql"
postgres=# CREATE ROLE pgscv LOGIN PASSWORD 'S3curePgscv';
CREATE ROLE
postgres=# GRANT pg_monitor TO pgscv;
GRANT ROLE

启用 pg_stat_statements（statements 采集器依赖，需预加载后重启实例）：

root@pgscv-lab:~# sed -i "s/^#shared_preload_libraries = .*/shared_preload_libraries = 'pg_stat_statements'/" \
  /etc/postgresql/16/main/postgresql.conf
root@pgscv-lab:~# grep '^shared_preload' /etc/postgresql/16/main/postgresql.conf
shared_preload_libraries = 'pg_stat_statements'
root@pgscv-lab:~# systemctl restart postgresql@16-main
root@pgscv-lab:~# su - postgres -c "psql -c 'CREATE EXTENSION IF NOT EXISTS pg_stat_statements;'"
CREATE EXTENSION

pg_hba 说明：pgSCV 默认以 postgres 系统用户运行，走 TCP 127.0.0.1:5432 连接，Ubuntu 默认 pg_hba 对本机 TCP 已允许 scram-sha-256 口令认证，上面创建的口令账号可直接使用；若 pgSCV 部署在独立机器上，需在目标库 pg_hba.conf 放行采集器来源地址。

三、下载并校验官方 deb 包

校验是必做步骤——GitHub 大文件下载在网络抖动时可能截断，实测中同一 deb 下载两次分别只得 6.5 MB 与 20.9 MB（完整为 30,036,870 字节），靠 checksums.txt 才确认最终完整。先取上游校验清单，再下载、校验：

root@pgscv-lab:~# curl -sL --max-time 60 -o /tmp/checksums.txt \
  https://github.com/cherts/pgscv/releases/download/v0.15.3/checksums.txt
root@pgscv-lab:~# grep amd64.deb /tmp/checksums.txt
636e69e31e4affe4e3d46629030396b922b1feba1c428b5c63df4bacd1abf81c  pgscv_0.15.3_amd64.deb
root@pgscv-lab:~# curl -sL -C - --max-time 120 -o /tmp/pgscv_0.15.3_amd64.deb \
  https://github.com/cherts/pgscv/releases/download/v0.15.3/pgscv_0.15.3_amd64.deb
root@pgscv-lab:~# sha256sum -c --ignore-missing checksums.txt
pgscv_0.15.3_amd64.deb: OK

-C - 为断点续传参数，网络不稳时可重复执行直到校验通过。校验通过说明包完整且未被篡改（上游由 goreleaser 生成固定校验值）。

四、安装 deb 包与文件布局

root@pgscv-lab:~# dpkg -i /tmp/pgscv_0.15.3_amd64.deb
Selecting previously unselected package pgscv.
(Reading database ... 72246 files and directories currently installed.)
Unpacking pgscv (0.15.3) ...
Setting up pgscv (0.15.3) ...

 Configuration settings can be adjusted here:
    /etc/pgscv.yaml

----------------------------------------------------------------------

查看包内文件清单与关键文件：

root@pgscv-lab:~# dpkg -L pgscv
/etc/default/pgscv
/etc/pgscv.yaml
/usr/lib/systemd/system/pgscv.service
/usr/sbin/pgscv
/usr/share/doc/pgscv/LICENSE
/usr/share/doc/pgscv/README.md
root@pgscv-lab:~# ls -l /usr/sbin/pgscv /etc/pgscv.yaml /etc/default/pgscv
-rw-r----- 1 root postgres   3501 /etc/pgscv.yaml
-rw-r--r-- 1 root root         37 /etc/default/pgscv
-rwxr-xr-x 1 root root   96739672 /usr/sbin/pgscv
root@pgscv-lab:~# /usr/sbin/pgscv --version
pgscv v0.15.3 (amd64) 9f2676dba1045b0a49d267b8961dc69e04654e39-HEAD

四个关键文件的作用：

文件作用
/usr/sbin/pgscv静态编译的 Go 二进制，约 92 MiB，无运行时依赖
/etc/pgscv.yaml主配置（权限 640、属主 root:postgres，内含完整参数样例）
/etc/default/pgscvsystemd 环境变量文件，内容 ARGS='--config-file=/etc/pgscv.yaml'
/lib/systemd/system/pgscv.servicesystemd 单元，User=postgres，ExecStart=/usr/sbin/pgscv $ARGS

注意 dpkg 安装后服务是 disabled 状态，不会自启——需要显式 enable（排障实录 2）。

五、编写最小可用配置

官方样例 /etc/pgscv.yaml 自带大量注释示例。最小可用配置只需监听地址与服务清单。修改两处：

listen_address: 0.0.0.0:9890
services:
  "postgres:5432":
    service_type: "postgres"
    conninfo: "postgres://pgscv:S3curePgscv@127.0.0.1:5432/postgres"
  • listen_address：对外提供服务发现与抓取的监听地址；只在本机 Prometheus 抓取时可保持默认 127.0.0.1:9890，跨机抓取需改 0.0.0.0:9890 并配合防火墙/认证。
  • services：被监控服务清单，键为 service_id（任取，惯例 主机:端口）；service_type 取 postgres / pgbouncer / patroni；conninfo 为标准 PostgreSQL 连接串。
  • 官方样例里默认启用的 pgbouncer:6432 条目在生产机没有 PgBouncer 时务必注释掉，否则每次抓取都会刷连接失败告警（排障实录 3）。

六、systemd 托管与启动验证

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 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:12:45 UTC; 3s ago
       Docs: https://github.com/cherts/pgscv/wiki
   Main PID: 6435 (pgscv)
      Tasks: 11 (limit: 2932)
     Memory: 13.1M
        CPU: 32ms

启动日志确认服务注册成功：

root@pgscv-lab:~# journalctl -u pgscv --no-pager -n 4 | grep -oE 'registered new service \[[^]]+\]|listen on [^"]+'
registered new service [system:0]
registered new service [postgres:5432]
listen on http://0.0.0.0:9890

system:0 是操作系统指标服务（自动注册），postgres:5432 是配置文件声明的数据库服务。验证指标端点：

root@pgscv-lab:~# curl -s http://127.0.0.1:9890/metrics | grep -E '^postgres_up|^pgscv_services_registered_total'
postgres_up{host="127.0.0.1",port="5432",service_id="postgres:5432"} 1
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 即数据库连通采集正常。指标规模（默认全采集器）：

root@pgscv-lab:~# curl -s http://127.0.0.1:9890/metrics | grep -c '^# HELP'
440
root@pgscv-lab:~# curl -s http://127.0.0.1:9890/metrics | grep -c '^# HELP postgres_'
102

七、接入 Prometheus 与 Grafana

以 Ubuntu 仓库的 Prometheus 为例，追加一个抓取作业后重启：

  - job_name: pgscv
    static_configs:
      - targets: ['127.0.0.1:9890']

实例多时改用 pgSCV 自带的服务发现端点（/targets 返回 JSON，含每个 service_id 的抓取 URL）：

  - job_name: pgscv
    http_sd_config:
      url: http://127.0.0.1:9890/targets

抓取健康验证（Prometheus API 实查）：

# job=pgscv  instance=127.0.0.1:9890  health=up
# instant query postgres_up → {service_id="postgres:5432"} 1

Grafana 导入官方仪表盘 ID：21409（System）、21430（PostgreSQL）、21429（Pgbouncer）、21462（Patroni），数据源指向上述 Prometheus 即可出图。被监控端可先用 pgbench 造些流量便于观察（实测 4 客户端 × 200 事务，tps 2812.741720）。

八、tar.gz 手工部署路线（附录）

无法使用包管理器时，用裸包四件套手工落位：

root@pgscv-lab:~# curl -sL -C - --max-time 120 \
  -o /tmp/pgscv_0.15.3_linux_x86_64.tar.gz \
  https://github.com/cherts/pgscv/releases/download/v0.15.3/pgscv_0.15.3_linux_x86_64.tar.gz
root@pgscv-lab:~# tar tzf /tmp/pgscv_0.15.3_linux_x86_64.tar.gz
pgscv
pgscv.yaml
pgscv.service
pgscv.default

落位命令与 deb 等效：二进制到 /usr/sbin/pgscv、配置到 /etc/pgscv.yaml（chown postgres:postgres + chmod 640）、单元到 /etc/systemd/system/pgscv.service、环境文件到 /etc/default/pgscv，然后 systemctl daemon-reload && systemctl enable --now pgscv。

升级流程：下载新版 deb → dpkg -i → 对比新旧 /etc/pgscv.yaml（dpkg 会保留已修改的 conffile 并生成 .dpkg-dist 参考文件）→ systemctl restart pgscv。回滚用 apt install /tmp/pgscv_0.15.2_amd64.deb 降级。

九、排障实录

实录 1：deb 下载截断导致 sha256 不匹配（必做校验的直接原因）

现象：curl -sL -o pgscv.deb 两次分别停在 6,558,748 与 20,948,918 字节（curl exit 28，超时），直接 dpkg -i 会报 dpkg-deb 子进程错误。处理：用 -C - 续传 + sha256sum -c checksums.txt 闭环，直到输出 pgscv_0.15.3_amd64.deb: OK。教训：30 MB 级 Release 资产在跨境链路上截断是常态，安装脚本必须内建校验。

实录 2：dpkg 装完服务没起来

现象：安装后 systemctl status pgscv 显示 Active: inactive (dead) 且 Loaded: ... disabled。原因：官方包的 postinst 不做 enable（仅在安装输出中打印配置路径提示）。处理：systemctl enable --now pgscv。若此前手工跑过前台进程占用 9890 端口，服务会以「address already in use」崩溃重启，Restart=on-failure 导致每 10 秒一次循环——先 pkill -x pgscv 再 start。

实录 3：官方样例配置的 pgbouncer 条目刷连接告警

现象：首启即出现周期告警 pgbouncer@127.0.0.1:6432/pgbouncer: failed to connect to ... dial tcp 127.0.0.1:6432: connect: connection refused skip。原因：deb 自带样例默认启用 pgbouncer:6432 条目，conninfo 是占位口令。处理：注释掉该服务条目（或部署真实 PgBouncer 并改连接串），重启后告警消失。启示：样例配置是「全功能展示」，上线前应逐段裁剪。

实录 4（补充）：sysinfo 采集器的内核参数告警

现象：日志周期出现 read 'kernel.sched_migration_cost_ns' failed: open /proc/sys/kernel/sched_migration_cost_ns: no such file or directory; skip。原因：运行环境的内核未编译/未暴露该 sysctl 项（受限环境常见），采集器按设计跳过该指标。评估：仅告警噪音，可忽略，或在 disable_collectors 中关掉 system/sysinfo。

十、部署清单（Checklist）

  1. PGDG 源 + PostgreSQL 16 安装，pg_lsclusters 确认 online；
  2. 监控账号 pgscv + pg_monitor，口令符合基线；
  3. shared_preload_libraries='pg_stat_statements' + CREATE EXTENSION；
  4. deb 下载 + sha256sum -c 校验通过；
  5. /etc/pgscv.yaml 裁剪样例、写入真实服务清单；
  6. systemctl enable --now pgscv，postgres_up 1 验证；
  7. Prometheus 抓取 job up，Grafana 仪表盘 21409/21430/21429/21462 导入；
  8. 跨机部署补齐：防火墙放行 9890、启用认证与 TLS（见配置篇）。

十一、本系列导航