Ubuntu 22.04 安装 Pgpool-II 4.7.3 指南

目标：在 Ubuntu 22.04 服务器上从 0 到 1 安装 Pgpool-II 并跑通「前端 9999 连接 → PCP 9898 管理」的最小可用环境。本文给出三种实测方案——Ubuntu 官方仓库（4.1.4）、PGDG 官方仓库（4.7.3，推荐）、官方源码编译（4.7.3），全部命令与回显均在 Ubuntu 22.04 x86_64 真机实测照抄，含 systemd 托管、升级降级、排障实录与卸载清理。后端 PostgreSQL 流复制主备的搭建见《PostgreSQL 18 流复制（Streaming Replication）集群部署指南》。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64，内核 5.15）
Pgpool-II 版本：4.7.3（PGDG 仓库与源码方案）、4.1.4（Ubuntu 仓库方案），版本代号 tasukiboshi（4.7 系列）/ karasuboshi（4.1 系列）
后端数据库：PostgreSQL 17（两节点流复制主备，主机名 pg1 主 / pg2 备，端口 5432，testdb 测试库）
监听端口：Pgpool-II 前端 9999、PCP 管理接口 9898
相关路径：配置 /etc/pgpool2/（apt 方案）、/usr/local/pgpool-II-4.7.3/（源码方案）、systemd 单元 /lib/systemd/system/pgpool2.service
实测账号：PCP 管理账号 admin / q1w2e3r4

二、前置条件

一台 Ubuntu 22.04 服务器，具备 sudo 权限（本文命令均以 root 执行）。
可访问的网络（apt 仓库与官网下载；内网隔离环境直接看第六章源码方案并提前备好依赖包）。
至少一组可用的 PostgreSQL 后端（单节点也能装，本指南按一主一备流复制书写，后端 pg1:5432、pg2:5432，且已在主库建好测试库 testdb）。仅做安装验证可暂时不接后端，首次启动会告警但不影响 pgpool --version 等基本验证。
时间同步正常（timedatectl 确认），避免日志与证书时间错乱。

三、版本选型说明

Ubuntu 22.04（jammy）可用版本共三个来源，apt-cache policy 实测（方案 B 节）显示：

来源	可用版本	包名	适用场景
Ubuntu jammy/universe	4.1.4-6build1	pgpool2	只能用系统自带源、对版本无要求的保守环境
PGDG（apt.postgresql.org）	4.7.3-1.pgdg22.04+1（截至 2026-10-20 最新稳定版）	pgpool2	推荐：跟官方同步、含 4.7.3 安全修复（CVE-2026-92867/92868）
官方源码编译	4.7.3	—	需要自定义 prefix、离线部署或多版本并存

关键差异：Ubuntu 仓库的 4.1.4 与 PGDG 的 4.7.3 相差三个大版本——4.7 移除了 Slony 模式、支持协议 3.2、内置 PostgreSQL 18 SQL 解析器，且 4.7.3 修复了两个 2026-09 公告的高危 CVE。除非受限于内部镜像源，否则一律选 PGDG 或源码的 4.7.3。

四、方案 A：Ubuntu 官方仓库在线安装（pgpool2 4.1.4）

本方案用系统自带 universe 源安装，命令最少，但版本停在 4.1.4。先确认候选版本：

apt-get update
apt-cache policy pgpool2

实测回显：

pgpool2:
  Installed: (none)
  Candidate: 4.1.4-6build1
  Version table:
     4.1.4-6build1 500
        500 http://archive.ubuntu.com/ubuntu jammy/universe amd64 Packages

执行安装（输出节选，实测）：

apt-get install -y pgpool2

Setting up pgpool2 (4.1.4-6build1) ...

Creating config file /etc/pgpool2/pgpool.conf with new version
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

⚠️ 若在无 systemd 的环境（如某些最小化环境）安装，可能看到 invoke-rc.d: policy-rc.d denied execution of start. 提示——这只是包管理器放弃自动启动服务，安装本身成功，用 systemctl 或手工启动即可（真机有 systemd 时安装即自动拉起服务）。

验证版本：

pgpool --version
dpkg -l pgpool2 | tail -2

pgpool-II version 4.1.4 (karasukiboshi)
+++-==============-=============-============-===========================================================
ii  pgpool2        4.1.4-6build1 amd64        connection pool server and replication proxy for PostgreSQL

配置文件落位 /etc/pgpool2/（pgpool.conf、pcp.conf、pool_hba.conf、pool_passwd），systemd 单元 /lib/systemd/system/pgpool2.service 已随包注册并 enable。

五、方案 B：PGDG 官方仓库在线安装 4.7.3（推荐）

PostgreSQL 官方软件源（PGDG）提供与 pgpool.net 同步的 4.7.3 包。全程实测如下。

5.1 配置 PGDG 软件源

apt-get update
apt-get install -y curl ca-certificates gnupg lsb-release
install -d /usr/share/postgresql-common/pgdg
curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc https://www.postgresql.org/media/keys/ACCC4CF8.asc
echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] http://apt.postgresql.org/pub/repos/apt jammy-pgdg main" > /etc/apt/sources.list.d/pgdg.list
apt-get update

5.2 确认候选版本

apt-cache policy pgpool2

实测回显：

pgpool2:
  Installed: (none)
  Candidate: 4.7.3-1.pgdg22.04+1
  Version table:
     4.7.3-1.pgdg22.04+1 500
        500 http://apt.postgresql.org/pub/repos/apt jammy-pgdg/main amd64 Packages
     4.7.2-2.pgdg22.04+2 500
        500 http://apt.postgresql.org/pub/repos/apt jammy-pgdg/main amd64 Packages
     4.7.2-1.pgdg22.04+1 500
        500 http://apt.postgresql.org/pub/repos/apt jammy-pgdg/main amd64 Packages
     4.1.4-6build1 500
        500 http://archive.ubuntu.com/ubuntu jammy/universe amd64 Packages

💡 说明：PGDG 源只提供 4.7 系列最新版，历史版本需源码编译；若同一台机器想保底 4.1.4，apt 会按版本优先级自动选 4.7.3（Candidate）。

5.3 安装并验证

apt-get install -y pgpool2
pgpool --version
dpkg -l pgpool2 | tail -2

安装输出（节选，实测）：

Setting up pgpool2 (4.7.3-1.pgdg22.04+1) ...

Creating config file /etc/pgpool2/pgpool.conf with new version
Created symlink /etc/systemd/system/multi-user.target.wants/pgpool2.service → /lib/systemd/system/pgpool2.service.

版本验证（实测）：

pgpool-II version 4.7.3 (tasukiboshi)
+++-==============-===================-============-===========================================================
ii  pgpool2        4.7.3-1.pgdg22.04+1 amd64        connection pool server and replication proxy for PostgreSQL

包内关键文件布局（dpkg -L pgpool2 节选）：

/etc/pgpool2/pcp.conf
/etc/pgpool2/pgpool.conf
/etc/pgpool2/pool_hba.conf
/etc/pgpool2/pool_passwd
/lib/systemd/system/pgpool2.service
/usr/sbin/pgpool
/usr/sbin/pcp_attach_node
/usr/sbin/pcp_detach_node
/usr/sbin/pcp_health_check_stats
/usr/sbin/pcp_invalidate_query_cache
/usr/sbin/pcp_log_rotate
/usr/sbin/pcp_node_count
/usr/sbin/pcp_node_info
/usr/sbin/pcp_pool_status
/usr/sbin/pcp_proc_count
/usr/sbin/pcp_proc_info
/usr/sbin/pcp_promote_node
/usr/sbin/pcp_recovery_node
/usr/sbin/pcp_reload_config
/usr/sbin/pcp_stop_pgpool
/usr/sbin/pcp_watchdog_info
/usr/sbin/pg_enc
/usr/sbin/pg_md5
/usr/sbin/pgpool_setup
/usr/sbin/pgproto
/usr/sbin/watchdog_setup
/usr/sbin/wd_cli

💡 说明：Debian 包把二进制放 /usr/sbin/，root 默认 PATH 包含该目录；普通用户执行 pcp 命令需写全路径或补 PATH。

六、方案 C：官方源码编译安装 4.7.3

适合内网离线部署、自定义安装路径或多版本并存。实测从官方源下载并编译安装到 /usr/local/pgpool-II-4.7.3。

6.1 安装编译依赖

apt-get update
apt-get install -y gcc make bison flex libpq-dev libssl-dev libpam0g-dev libmemcached-dev curl

💡 依赖说明：libpq-dev 提供客户端库；libssl-dev 支持 TLS；libpam0g-dev 支持 PAM 认证；libmemcached-dev 支持把查询缓存放到 memcached；bison/flex 是内置 SQL 解析器构建所需。不需要在 pgpool 机器上装 PostgreSQL 服务端。

6.2 下载与校验

官方源码包地址（官网 Downloads 页 Source 表，查询日期 2026-10-20）：

curl -fsSLO https://www.pgpool.net/source/pgpool-II-4.7.3.tar.gz
ls -l pgpool-II-4.7.3.tar.gz
sha256sum pgpool-II-4.7.3.tar.gz

实测回显：

-rw-r--r-- 1 root root 5850112 Oct 19 16:29 pgpool-II-4.7.3.tar.gz
4bf9df3e13feb8e64bee486b4ea54c9076296c2d9406165b0b68d32086fce250  pgpool-II-4.7.3.tar.gz

⚠️ 旧文档里常见的 https://www.pgpool.net/mediawiki/images/pgpool-II-4.7.3.tar.gz 已随官网改版失效（302 跳回首页，下载到的是 HTML 而非 gzip，tar 报 stdin: not in gzip format）。当前有效地址是 https://www.pgpool.net/source/pgpool-II-4.7.3.tar.gz，下载后务必 file/sha256sum 校验。

6.3 解压、配置、编译、安装

tar xzf pgpool-II-4.7.3.tar.gz
cd pgpool-II-4.7.3
./configure --prefix=/usr/local/pgpool-II-4.7.3
make -j2
make install

configure 末段实测回显：

config.status: creating src/tools/watchdog/Makefile
config.status: creating src/watchdog/Makefile
config.status: creating src/include/config.h
config.status: executing libtool commands

验证版本：

/usr/local/pgpool-II-4.7.3/bin/pgpool --version

pgpool-II version 4.7.3 (tasukiboshi)

6.4 安装布局与收尾配置

ls /usr/local/pgpool-II-4.7.3/

bin  etc  include  lib  share

bin/：pgpool 主程序与 pcp_* 全套、pg_md5/pg_enc、pgpool_setup、pgproto、wd_cli。
etc/：pgpool.conf.sample、pcp.conf.sample、pool_hba.conf.sample 及 failover/recovery 脚本样例（failover.sh.sample、recovery_1st_stage.sample、follow_primary.sh.sample 等）。
需要手工复制样例生成配置：

cd /usr/local/pgpool-II-4.7.3/etc
cp pgpool.conf.sample pgpool.conf
cp pcp.conf.sample pcp.conf
cp pool_hba.conf.sample pool_hba.conf

建议 ln -s /usr/local/pgpool-II-4.7.3/bin/* /usr/local/bin/ 或把 bin 加入 PATH，避免每次写全路径。
源码方案不带 systemd 单元，按第八章模板自建。

七、多方案对比与选择建议

维度	A：Ubuntu 仓库	B：PGDG 仓库	C：源码编译
版本	4.1.4（旧三大版本）	4.7.3（最新稳定）	4.7.3
是否联网	是	是	可离线（提前备包）
安装方式	apt 一条命令	apt（先配源）	configure/make
systemd 单元	包内置自动注册	包内置自动注册	需自建
配置目录	/etc/pgpool2	/etc/pgpool2	<prefix>/etc
升级方式	随 Ubuntu（基本不动）	apt upgrade 即时跟进	重新下载编译
多版本并存	不支持	不支持（单版本包）	支持（不同 prefix）
适用	最保守环境	绝大多数生产	离线/定制/并存

选择建议：能联网选 B（apt 两分钟拿到 4.7.3 且随官方发版升级）；内网隔离、或要在同一台机器并行跑多个版本做灰度选 C；只有系统源可用且不介意 4.1.4 旧版才选 A。

八、配置文件与 systemd 服务说明

8.1 配置文件清单（apt 方案）

文件	作用
`/etc/pgpool2/pgpool.conf`	主配置：监听、后端、池、LB、watchdog 等全部参数（详解见《Pgpool-II 4.7.3 配置参数详解》）
`/etc/pgpool2/pcp.conf`	PCP 管理接口的用户口令文件（用户名:md5 哈希）
`/etc/pgpool2/pool_hba.conf`	前端连接的 HBA 访问控制（`enable_pool_hba` 开启后生效）
`/etc/pgpool2/pool_passwd`	后端认证用的用户口令文件（配合 md5/scram 认证）

8.2 systemd 单元解析

/lib/systemd/system/pgpool2.service 实测内容：

[Unit]
Description=pgpool-II
Documentation=man:pgpool(8)
Wants=postgresql.service
After=network.target

[Service]
User=postgres
ExecStart=/usr/sbin/pgpool -n
ExecReload=/bin/kill -HUP $MAINPID
KillSignal=SIGINT
StandardOutput=syslog
SyslogFacility=local0

[Install]
WantedBy=multi-user.target

要点：服务以 postgres 用户运行，前台模式（-n）交给 systemd 托管；ExecReload 用 SIGHUP 热加载配置；KillSignal=SIGINT 保证 stop 时优雅退出。系统提示 Standard output type syslog is obsolete 属 Ubuntu 22.04 对该单元的兼容性告警，不影响功能（journalctl 实测告警原文：/lib/systemd/system/pgpool2.service:12: Standard output type syslog is obsolete, automatically updating to journal.）。

8.3 首次最小配置与启动验证

把后端指向流复制主备（pg1 主、pg2 备），读写分离最小配置写入 /etc/pgpool2/pgpool.conf（原发行版配置先备份）：

cp /etc/pgpool2/pgpool.conf /etc/pgpool2/pgpool.conf.orig

# ---- 监听 ----
listen_addresses = '*'
port = 9999
socket_dir = '/var/run/postgresql'
pcp_listen_addresses = '*'
pcp_port = 9898
pcp_socket_dir = '/var/run/postgresql'
work_dir = '/var/log/postgresql'
pid_file_name = '/var/run/postgresql/pgpool.pid'
log_min_messages = info

# ---- 后端：pg1 主（读权重 0）/ pg2 备（读权重 1） ----
backend_hostname0 = 'pg1'
backend_port0 = 5432
backend_weight0 = 0
backend_data_directory0 = '/var/lib/postgresql/data'
backend_flag0 = 'ALLOW_TO_FAILOVER'
backend_hostname1 = 'pg2'
backend_port1 = 5432
backend_weight1 = 1
backend_data_directory1 = '/var/lib/postgresql/data'
backend_flag1 = 'ALLOW_TO_FAILOVER'

# ---- 流复制主备模式 ----
master_slave_mode = on
master_slave_sub_mode = 'stream'
sr_check_period = 10
sr_check_user = 'postgres'
health_check_period = 10
health_check_user = 'postgres'

# ---- 连接池与负载均衡 ----
num_init_children = 32
max_pool = 4
load_balance_mode = on
black_function_list = 'currval,nextval,setval'
memory_cache_enabled = off
use_watchdog = off

⚠️ 实测排障：pgpool.conf 的字符串值必须用单引号。写成 listen_addresses = "*" 启动即失败，journal 实测：FATAL: syntax error in configuration file "/etc/pgpool2/pgpool.conf"、DETAIL: parse error at line 2 '*' token = 8。改成单引号后正常。

启动并验证：

systemctl enable pgpool2
systemctl start pgpool2
systemctl is-active pgpool2
pg_isready -h 127.0.0.1 -p 9999

实测回显：

enabled
active
127.0.0.1:9999 - accepting connections

应用视角验证读写分离拓扑（pg_isready 探 PCP 端口 9898 会显示 no response——那是 PCP 私有协议端口，不是 PostgreSQL 协议，属正常现象）：

psql -h 127.0.0.1 -p 9999 -U postgres -d testdb -c "show pool_nodes"

实测回显：

 node_id | hostname | port | status | pg_status | lb_weight |  role   | pg_role | select_cnt | load_balance_node | replication_delay | replication_state | replication_sync_state | last_status_change
---------+----------+------+--------+-----------+-----------+---------+---------+------------+-------------------+-------------------+------------------------+---------------------
 0       | pg1      | 5432 | up     | up        | 0.000000  | primary | primary | 0          | false             | 0                 |                   |                        | 2026-10-19 16:39:05
 1       | pg2      | 5432 | up     | up        | 1.000000  | standby | standby | 0          | true              | 0                 |                   |                        | 2026-10-19 16:39:05
(2 rows)

两节点均 up，主库权重 0、备库权重 1 且 load_balance_node = true——读流量将全部走备库，拓扑符合预期。

8.4 配置 PCP 管理账号并冒烟验证

pcp.conf 每行 用户名:md5(密码)（裸 md5 十六进制、不带 md5 前缀；与 pool_passwd 的 md5(密码+用户名) 口径不同，两者极易混淆，见第十章排障）。用官方工具 pg_md5 生成：

pg_md5 q1w2e3r4

实测回显：

c62d929e7b7e7b6165923a5dfc60cb56

追加到 pcp.conf：

echo "admin:c62d929e7b7e7b6165923a5dfc60cb56" >> /etc/pgpool2/pcp.conf

客户端侧建议预置 ~/.pcppass（格式 主机:端口:用户:密码 四段），免每次交互输密码：

echo "*:*:admin:q1w2e3r4" > ~/.pcppass
chmod 600 ~/.pcppass

PCP 冒烟（实测）：

pcp_node_count -h 127.0.0.1 -p 9898 -U admin
pcp_node_info -h 127.0.0.1 -p 9898 -U admin 0

2
pg1 5432 2 0.000000 up up primary primary 0 none none 2026-10-19 16:40:54

PCP 全套命令逐条实测见《Pgpool-II 4.7.3 常用 CLI 命令与工具详解》。

九、升级、降级与多版本管理

PGDG 方案升级：apt-get update && apt-get upgrade pgpool2。PGDG 随官方发版即时提供新包（2026-09-29 的 4.7.3 已可直达）。升级前后用 pgpool --version 核对，并用 show pool_nodes/pcp_node_count 验证集群状态。
降级：apt-get install pgpool2=4.7.2-2.pgdg22.04+2（版本号取自 apt-cache policy 列表）。降级大版本前先备份 /etc/pgpool2/，跨大版本（4.7→4.1）配置参数差异大，不推荐。
版本锁定：apt-mark hold pgpool2 锁版本，apt-mark unhold pgpool2 解锁。
多版本并存：只有源码方案支持——不同 --prefix 各装一份（如 /usr/local/pgpool-II-4.7.2、/usr/local/pgpool-II-4.7.3），用不同 port/pcp_port 并行运行，灰度验证后切换 systemd 单元指向。
平滑重启：改配置后 systemctl reload pgpool2（SIGHUP 热加载多数运行参数）；涉及后端拓扑的改动建议 systemctl restart pgpool2，并注意 pgpool 会把重启前状态写入 pgpool_status，若后端角色已人工变更，用 pgpool -D（丢弃状态文件）方式重启一次。

十、常见问题（实测排障）

Q1：启动即失败，日志报 syntax error in configuration file ... parse error at line 2 '*' token = 8。 实测原因：pgpool.conf 字符串用了双引号（listen_addresses = "*"）。解决：所有字符串值改单引号 '*'，systemctl restart pgpool2 后 is-active 返回 active。

Q2：pcp 命令报 FATAL: authentication failed for user "admin" / DETAIL: username and/or password does not match。 实测三个独立坑，逐个核对：

pcp.conf 的哈希是 md5(密码) 的裸十六进制（pg_md5 <密码> 直接输出的值，不带 md5 前缀）；写成 pool_passwd 风格的 md5(密码+用户名) 必然失败。实测正确生成方式：pg_md5 q1w2e3r4 → c62d929e7b7e7b6165923a5dfc60cb56 → admin:c62d929e7b7e7b6165923a5dfc60cb56。
~/.pcppass 是四段式 主机:端口:用户:密码（如 *:*:admin:q1w2e3r4）。写成 pgpass 的五段式（多一段 database）时，客户端会把「admin:q1w2e3r4」整段当密码发送，同样报认证失败。
口令文件权限过宽会被客户端忽略：~/.pcppass 必须 chmod 600，否则实测警告 WARNING: password file ... has group or world access 并回落交互输入。

Q3：pg_isready -p 9898 显示 no response。 正常现象。9898 是 PCP 私有协议端口，只接受 pcp_* 客户端，用 pcp_node_count 验证；pg_isready 只适用于 9999。

Q4：安装时看到 invoke-rc.d: policy-rc.d denied execution of start.。 包管理器启动服务被环境策略拦下（无 systemd 的最小化环境常见）。安装无损，手工 systemctl start pgpool2（真机）或 pgpool -n（前台调试）即可。

Q5：下载源码包后 tar 报 stdin: not in gzip format。 官网 2026-05 改版后旧镜像地址失效（302 到首页返回 HTML）。改用 https://www.pgpool.net/source/pgpool-II-4.7.3.tar.gz 并用 sha256（4bf9df3e...）校验，见第六章。

Q6：改了 pgpool.conf 不生效。 systemctl reload pgpool2 只热加载部分运行参数；监听地址、后端拓扑、池参数等需 systemctl restart pgpool2。重启后 ss -ltn | grep -E '9999|9898' 确认端口。

十一、卸载与清理

apt 方案（保留配置用 remove，连配置一起删用 purge）：

systemctl stop pgpool2
apt-get remove --purge -y pgpool2
# 清理残留配置与 PGDG 源（不再使用时）
rm -rf /etc/pgpool2
rm -f /etc/apt/sources.list.d/pgdg.list /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc
apt-get update

源码方案：

# 若已注册自建 systemd 单元先停用
systemctl stop pgpool2 && systemctl disable pgpool2
rm -f /lib/systemd/system/pgpool2.service && systemctl daemon-reload
rm -rf /usr/local/pgpool-II-4.7.3

十二、参考链接

官网下载页（Apt Repository/Yum/Source）：https://www.pgpool.net/mediawiki/index.php/Downloads
PGDG apt 仓库使用说明：https://www.postgresql.org/download/linux/ubuntu/
Release 4.7.3（安全修复）：https://www.pgpool.net/docs/latest/en/html/release-4-7-3.html
官方源码包：https://www.pgpool.net/source/pgpool-II-4.7.3.tar.gz
PCP 认证说明（官方文档 pcp.conf 章节）：https://www.pgpool.net/docs/latest/en/html/pcp.html
站内相关：《PostgreSQL 18 流复制（Streaming Replication）集群部署指南》、《Pgpool-II 4.7.3 介绍与选型指南》
本专栏后续篇章：《Pgpool-II 4.7.3 配置参数详解》、《Pgpool-II 4.7.3 常用 CLI 命令与工具详解》