Pgpool-II 4.7.3 常用 CLI 命令与工具详解

目标：本篇是 Pgpool-II 4.7.3 的命令实战篇——对 PCP 运维接口 16 条命令与 5 个配套 CLI 工具逐条实测并保留原始回执，覆盖节点管理、进程观测、服务控制、watchdog、认证加密与协议调试六类场景，全部操作在 2026-10-20 于真实多机环境完成。

一、PCP 接口总览

1.1 接口与认证

PCP（Pgpool Control Protocol）是 pgpool 的运维通道，独立监听 pcp_port（本文实测 9898），账号存于 /etc/pgpool2/pcp.conf。实测环境账号：admin:c62d929e7b7e7b6165923a5dfc60cb56——该哈希为 md5(密码) 裸哈希无前缀（pg_md5 '密码' 直接产出），与 pool_passwd 中「带 md5 前缀且加盐用户名」的格式不同，混用是 PCP 认证失败的高频原因。

1.2 免交互口令文件 .pcppass

PCP 命令支持 .pcppass 免密（环境变量 PCPPASSFILE 可指定路径）：

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

必须为 4 段式 hostname:port:username:password（通配用 *），且权限必须 600。实测踩坑：误写成 5 段式（host:port:*:user:password 形式）时，PCP 把第 4、5 段整体当作密码，连续报认证失败。优先级：-w（空密码提示）< 环境变量 PCPPASSFILE < ~/.pcppass。

1.3 命令公共参数

-h  pgpool 主机（PCP 端口所在）      -p  PCP 端口
-U  pcp.conf 中的用户名             -w  强制密码提示
-d  debug 输出                      -v  详细输出

下文回执均在配置 ~/.pcppass 后取得，省略认证参数。

二、节点管理命令

2.1 pcp_node_count / pcp_node_info：池内节点清单

pcp_node_count -h 127.0.0.1 -p 9898 -U admin
# 2

pcp_node_info -h 127.0.0.1 -p 9898 -U admin -n 1
# Hostname: pg2  Port: 5432  ND: 0  Status: up  Role: standby  Weight: 1.000000

ND 是节点编号。pcp_node_info -v 输出多行详细版（含 replication delay、status change 时间等）。注意 pcp_node_count 统计的是定义的后端数（含 down 节点）。

2.2 pcp_detach_node：摘除节点（实测）

pcp_detach_node -h 127.0.0.1 -p 9898 -U admin -n 1
# pcp_detach_node -- Command Successful

摘除后节点从池内移除但后端 PostgreSQL 不停——show pool_nodes 中 status=down 而 pg_status=up，与故障摘除（两者皆 down）形成明显区别。摘除节点不再承接任何前端流量，恢复入池用 pcp_attach_node 或 pcp_recovery_node。

2.3 pcp_recovery_node：在线恢复（三轮实测）

pcp_recovery_node -h 127.0.0.1 -p 9898 -U admin -n 1
# pcp_recovery_node -- Command Successful

命令触发主库执行 recovery_1st_stage 脚本完成 pg_basebackup + 复制槽创建，随后自动执行 pgpool_remote_start 拉起备库，备库 pg.log 出现 started streaming WAL from primary，show pool_nodes 恢复 up/up, standby, replication_delay 0。

实测沉淀的三个前置/次生问题（详细分析见配置篇 §8）：

1. 主库需装 pgpool_recovery 扩展 + PGDATA 部署两个恢复脚本 + 免密 SSH；
2. 对 detach 但未停库 的节点直接恢复会失败：ERROR: executing remote start failed with error: "ERROR: pgpool_remote_start failed"——旧进程占端口所致，先停库再恢复；
3. 后端为 Alpine/官方镜像部署形态时需处理账户锁定、目录权限等四坑（配置篇 §8.3）。

pcp_promote_node（把备库提升为主库）本篇未纳入实测序列：流复制双节点下 promote 会使旧主库脱离复制关系形成双主孤立态，需要反向重建复制才能恢复对称拓扑，涉及破坏性变更；生产使用前请按官方文档 https://www.pgpool.net/docs/latest/en/html/pcp-promote-node.html 单独演练。

2.4 pcp_attach_node：重新入池（实测）

pcp_attach_node -h 127.0.0.1 -p 9898 -U admin -n 1
# pcp_attach_node -- Command Successful

适用于「后端已手工修好、只差重新入池」的场景（如健康检查摘除后重启了备库 PostgreSQL）。实测确认：健康检查把故障节点标 down 后，即使节点进程恢复，pgpool 也不会自动拉回，必须 attach。

三、进程与状态命令

3.1 pcp_proc_count / pcp_proc_info：子进程观测

pcp_proc_count -h 127.0.0.1 -p 9898 -U admin
# 17

pcp_proc_info -h 127.0.0.1 -p 9898 -U admin -p 12345 -v

-v 详细输出中可见 4.7.0 新增字段：client_host / client_port（前端来源）与 statement（子进程当前正执行的语句），排障时可直接定位「哪个客户端连接在跑哪条 SQL」。实测空闲子进程三字段为空，持有连接的子进程回显客户端 IP/端口与当前 statement。

3.2 pcp_pool_status：运行时参数全量

pcp_pool_status -h 127.0.0.1 -p 9898 -U admin
# item: listen_addresses     value: *
# item: port                 value: 9999
# item: num_init_children    value: 16
# ...（全量 pgpool.conf 运行时键值）

核对「改的配置是否生效」以本命令输出为准，逐条对应 pgpool.conf 参数名。

3.3 pcp_health_check_stats：健康检查明细（4.7）

pcp_health_check_stats -h 127.0.0.1 -p 9898 -U admin -n 0

输出最近健康检查轮次、成功/失败计数与耗时统计；必须带 -n 节点号，缺参会报参数错误（实测确认）。

3.4 pcp_invalidate_query_cache：清空内存缓存（实测）

pcp_invalidate_query_cache -h 127.0.0.1 -p 9898 -U admin
# pcp_invalidate_query_cache -- Command Successful

执行后 show pool_cache 的命中计数归零重新累计，用于调试 memqcache 或业务数据源被外部修改后的强制回源。

四、服务控制与维护命令

4.1 pcp_stop_pgpool：停止 pgpool（实测）

pcp_stop_pgpool -h 127.0.0.1 -p 9898 -U admin -m fast
# pcp_stop_pgpool -- Command Successful

-m 取值 smart（等连接退出）/ fast（回滚断连）/ immediate（立即）。实测 fast 停止后 systemd 视角 pgpool2 变 inactive，systemctl start pgpool2 拉回后 show pool_nodes 正常（连接池计数从零重建）。

4.2 pcp_reload_config：热加载配置（实测）

pcp_reload_config -h 127.0.0.1 -p 9898 -U admin
# pcp_reload_config -- Command Successful

多数参数（监听类、backend 权重类、健康检查类）可热加载；连接池规模、watchdog 拓扑等需重启。加载结果用 pcp_pool_status 复核。

4.3 pcp_log_rotate：日志轮转（实测边界）

pcp_log_rotate -h 127.0.0.1 -p 9898 -U admin
# ERROR:  log rotation requested but logging_collector is disabled

实测确认：logging_collector = off（默认走 stderr/systemd）时本命令返回上述错误，属预期行为；开启 collector 后执行成功并按 log_filename 模板切出新文件。

五、watchdog 命令

5.1 pcp_watchdog_info（实测）

pcp_watchdog_info -h 127.0.0.1 -p 9898 -U admin
# HOSTNAME    STANDBY  ...

在启用 watchdog 的 pgpool 上返回各 watchdog 节点的 LEADER/STANDBY/DEAD 状态与 VIP 持有者；未启用 watchdog 的实例上返回空/无数据（实测单节点实例回执为空表）。

5.2 wd_cli：watchdog 独立 CLI

wd_cli --info -a          # 查询全部 watchdog 节点状态
wd_cli --inform=ALIVE     # 向 watchdog 上报本机状态恢复

实测（未启用 watchdog 的实例）回执：

WARNING: pid 6519: get watchdog nodes command failed
ERROR: pid 6519: get node list command reply contains no data
（退出码 255）

wd_cli 通过 wd_port（默认 22200）或 wd_ipc socket 与 watchdog 通信，连接参数可用 -p/-s/-f/-k 覆盖 pgpool.conf 中的 wd_port/wd_ipc_socket_dir/wd_authkey。--inform=DEAD/ALIVE 用于外部探活系统（如 keepalived、k8s probe）向 watchdog 注入节点状态——这是构建自定义仲裁时的关键入口。

六、认证与加密工具

6.1 pg_md5：pcp.conf 与 pool_passwd 双用（实测）

pg_md5 'q1w2e3r4'
# c62d929e7b7e7b6165923a5dfc60cb56      ← pcp.conf 用：md5(密码) 裸哈希

pg_md5 -m -u admin -f /etc/pgpool2/pgpool.conf 'q1w2e3r4'
# 写入 pool_passwd：admin:md5xxxx        ← md5(密码+用户名)，带 md5 前缀

-m 需要 pgpool.conf 路径以定位 pool_passwd；不带 -m 时输出即 pcp.conf 所需哈希。交互式 -p 在无终端环境会失败，脚本化用位置参数传密码（注意 shell 历史，可用 HISTCONTROL=ignorespace）。

6.2 pg_enc：AES-256-CBC 加密（实测）

openssl rand -hex 32 > /etc/pgpool2/pool_key && chmod 600 /etc/pgpool2/pool_key
pg_enc -m -u appuser -k /etc/pgpool2/pool_key -f /etc/pgpool2/pgpool.conf 'secret123'
# trying to read key from file /etc/pgpool2/pool_key
# （pool_passwd 追加）appuser:AESWQ2KKG1ntHerL+GsZtGpEw==

pg_enc -k /etc/pgpool2/pool_key 'secret123'
# WQ2KKG1ntHerL+GsZtGpEw==
# pool_passwd string: AESWQ2KKG1ntHerL+GsZtGpEw==

实测结论：key 文件内容为 hex 编码（64 个十六进制字符 = 32 字节 AES-256 密钥）；-m 直接维护 pool_passwd（条目带 AES 前缀），缺省仅打印密文；常用参数 -u 用户名、-k 密钥文件（可用环境变量 PGPOOLKEYFILE）、-f pgpool.conf、-i 用户密码对文件（批量导入）、-P（交互输密钥）。后端 hba 为 md5/scram 时，pool_passwd 缺条目的用户将无法通过 pgpool 认证。

七、开发与搭建工具

7.1 pgpool_setup：一键搭建实验集群（实测）

pgpool_setup --help
# usage: pgpool_setup [-m r|s|n|l|i] [-n num_clusters] [-p base_port] [-pg pg_base_port] [--no-stop] [-d] [-s] [-r] [-e] [-t] [-c]

pgpool_setup -m n -n 1 -p 11000 -pg 11010
# pcp command user name is "root", password is "root".
# #1 port is 11010
# pgpool port is 11000
# pcp port is 11001

-m 模式：s 流复制 / r 复制模式 / n raw / l 逻辑复制 / i 独立；-n 后端数；端口按 11000/11001/11010 递增。产物目录：data0/ etc/ log/ run/ archivedir/ startall shutdownall README.port。

实测三个坑点（源码编译安装环境下）：

1. pgpool_setup 硬编码 /usr/bin/pg_md5，源码安装实际在 /usr/local/bin/pg_md5（或发行版 /usr/sbin），缺失时报 line 1415: /usr/bin/pg_md5: No such file or directory 且 pcp.conf 为空、pgpool 起不来——补软链后重跑；
2. 同理 /usr/bin/pgpool 可能缺链（安装到 sbin 布局），startall 报 not found，需 ln -sf /usr/sbin/pgpool /usr/bin/pgpool；
3. 必须以非特权用户运行（root 下 pg_ctl: cannot be run as root，initdb 同理）：su postgres -c 'pgpool_setup ...'，目录属主预先交给该用户。

实测还观察到：非交互模式下 pgpool_setup 收尾的 stop 验证环节可能长时间停留在 stop request sent to pgpool ... waiting for termination 循环（日志每 5 秒重试），人工中断后用其产出的 startall 手动启动即可。该工具定位是本地验证/教学用途，生产请按配置篇手写 pgpool.conf。

7.2 pgproto：前端协议调试器（实测）

pgproto -h 10.89.58.7 -p 9999 -u postgres -d postgres -f pgproto.data

按数据文件逐条回放 PostgreSQL 线协议消息（'Q' 简单查询、'B'/'D'/'E'/'S'/'Y' 扩展协议、'X' 终止），回执打印 FE/BE 双向流：

FE=> Execute(portal="")
FE=> Sync
<= BE BindComplete
<= BE DataRow
<= BE CommandComplete(SELECT 1)
<= BE ReadyForQuery(I)
FE=> Terminate

实测用官方回归用例 129.multi_prepare/pgproto.data 对 pgpool 9999 端口完整跑通。它是排查「pgpool 对某条 SQL 路由/缓存行为异常」的第一手工具——能看清 pgpool 是否转发、改写了哪条消息。数据文件语法：一行一条消息，# 注释，字符串带引号。

7.3 pgpool 主程序常用参数

pgpool -n -f /etc/pgpool2/pgpool.conf -F /etc/pgpool2/pcp.conf -a /etc/pgpool2/pool_hba.conf -d

-n 前台运行（以 systemd 单元托管、手工前台调试时必加）、-f/-F/-a 三份配置显式指定、-d 调试日志、--version 版本（实测输出 pgpool-II version 4.7.3 (tasukiboshi)）。

八、命令速查表

九、FAQ

1. PCP 一直认证失败：先查 pcp.conf 是否用了「带前缀加盐哈希」（应裸哈希）；.pcppass 是否 4 段式且 600 权限；-U 用户名是否在 pcp.conf 中存在。
2. recovery 报 remote start failed：detach 不停库导致端口占用（先停库）；Alpine 部署形态四坑见配置篇 §8.3。
3. log_rotate 报 disabled：开启 logging_collector 后再轮转（§4.3）。
4. pgpool_setup 起不来：三个坑逐一排查（pg_md5/pgpool 软链、root 运行），见 §7.1。
5. 想看某连接正在执行什么：pcp_proc_info -p <pid> -v 的 4.7 新字段 statement（§3.1）。
6. 怀疑 pgpool 改写了协议消息：用 pgproto 对同一 SQL 回放对比 FE/BE 流（§7.2）。

十、参考链接

• PCP 命令官方参考：https://www.pgpool.net/docs/latest/en/html/pcp-commands.html
• PCP 连接与认证：https://www.pgpool.net/docs/latest/en/html/pcp-connection.html
• pg_enc / pg_md5：https://www.pgpool.net/docs/latest/en/html/pg_enc.html 、 https://www.pgpool.net/docs/latest/en/html/pg_md5.html
• pgpool_setup：https://www.pgpool.net/docs/latest/en/html/pgpool-setup.html
• pgproto：https://www.pgpool.net/docs/latest/en/html/pgproto.html
• wd_cli：https://www.pgpool.net/docs/latest/en/html/wd-cli.html
• 4.7.0 Release Notes（proc_info 新字段等）：https://www.pgpool.net/docs/latest/en/html/release-4-7-0.html
• 本专栏同族文档：《Pgpool-II 4.7.3 介绍与选型指南》、《Ubuntu 22.04 安装 Pgpool-II 4.7.3 指南》、《Pgpool-II 4.7.3 配置参数详解》