Ubuntu 22.04 安装 PgBouncer 1.26.1 指南

Ubuntu 22.04 安装 PgBouncer 1.26.1 三方案实测：universe apt 1.16.1 对照、PGDG 源 1.26.1（原生 systemd unit）、源码编译（sha256 校验+排障实录），含连接 PG 18.6 端到端验证与卸载清理。

PgBouncerPostgreSQL数据库安装部署2026/10/20

Ubuntu 22.04 安装 PgBouncer 1.26.1 指南

目标：在 Ubuntu 22.04 上以三种方式安装 PgBouncer 1.26.1（Ubuntu 官方仓库 apt、PostgreSQL 官方 PGDG 源 apt、官方源码编译），完成 systemd 托管、连接 PostgreSQL 18 后端的端到端验证，并沉淀安装过程中的真实排障记录。文中全部命令与回显均在「Ubuntu 22.04.5 LTS + PgBouncer 1.26.1 + PostgreSQL 18.6」环境实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（两台：应用侧 pgb-server 10.89.56.3、数据库侧 pg18-server 10.89.56.2，同一内网）
  • 系统架构：x86_64
  • 包管理器：apt
  • PgBouncer 版本：1.26.1（官方最新稳定版，2026-10-14 发布；apt 方式另实测了 Ubuntu universe 源的 1.16.1-1ubuntu1 作对照）
  • PostgreSQL 版本：18.6（PGDG 源安装，安装方式见本站 《Ubuntu 22.04 安装 PostgreSQL 18 指南》）
  • psql 客户端：psql (PostgreSQL) 14.24 (Ubuntu 14.24-0ubuntu0.22.04.1)
  • PgBouncer 监听端口：6432（PostgreSQL 默认 5432）
  • 源码安装路径：/usr/local（二进制 /usr/local/bin/pgbouncer）
  • 配置文件：/etc/pgbouncer/pgbouncer.ini 与 /etc/pgbouncer/userlist.txt
  • 日志/运行目录：/var/log/pgbouncer/、/var/run/pgbouncer/（PGDG 包默认日志落在 /var/log/postgresql/pgbouncer.log、运行目录 /var/run/postgresql）
  • 演示账号：PostgreSQL 超级用户 postgres、业务账号 appuser，密码均为 q1w2e3r4（示例演示值）

二、前置条件

本节列出安装前必须就绪的系统条件，逐项给出验证命令与预期输出。

  1. 系统为 Ubuntu 22.04（Server/Desktop 均可），具备 root 或 sudo 权限：
cat /etc/os-release | head -2

实测回显：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
  1. 已有一台可连通的 PostgreSQL 服务器（本文使用 PG 18.6）。在 pgb-server 上验证到后端 5432 端口可达：
psql -h 10.89.56.2 -p 5432 -U postgres -c "SELECT version();"

实测回显（密码 q1w2e3r4）：

                                                version
--------------------------------------------------------------------------------------------------------
 PostgreSQL 18.6 (Debian 18.6-1.pgdg13+2) on x86_64-pc-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit
(1 row)
  1. 更新 apt 索引（后续方案均依赖）：
apt-get update

实测回显（节选）：

Hit:1 http://archive.ubuntu.com/ubuntu jammy InRelease
Reading package lists... Done

⚠️ 注意：PgBouncer 本身不需要 libpq，但 psql 客户端用于验证，后端服务器上如无 psql 可执行 apt-get install -y postgresql-client 安装。

三、版本选型说明

先明确"装哪个版本、从哪装"，三种方案提供的版本差异很大：

安装源可用版本是否联网说明
Ubuntu 22.04 universe 仓库1.16.1-1ubuntu1是随发行版冻结，版本较老（1.16 系为 2021 年版本）
PostgreSQL PGDG 源（jammy-pgdg）1.26.1-1.pgdg22.04+1（查询日候选）是PGDG 打包，与官网最新稳定版同步，含原生 systemd unit
官方源码编译任意（本文 1.26.1）是（可离线拷包）版本完全自控，需自行处理依赖与 unit 文件

版本核对命令（安装前确认候选版本）：

apt-cache policy pgbouncer

universe 源（未加 PGDG 前）实测回显：

pgbouncer:
  Installed: (none)
  Candidate: 1.16.1-1ubuntu1
  Version table:
     1.16.1-1ubuntu1 500
        500 http://archive.ubuntu.com/ubuntu jammy/universe amd64 Packages

选型建议：生产环境优先**方案 B（PGDG 源）**拿最新稳定版 1.26.1——1.26.0/1.26.1 修复了多个认证链路 CVE（CVE-2025-12819、CVE-2026-66646669、CVE-2026-107348107350），1.16.1 老版本不包含这些修复，仅建议用于极端受控的离线环境；源码编译（方案 C）适合需要自定义编译选项或无可用软件源的场景。

四、方案 A：Ubuntu 官方仓库 apt 安装（1.16.1）

4.1 方案说明

最省事的一条命令安装，包来自 Ubuntu universe 仓库。优点是依赖全自动、开机脚本就绪；缺点是版本冻结在 1.16.1，与本系列文档实测基准 1.26.1 行为有差异（例如 1.26.0 起移除了 SUSPEND 命令、1.25.0 起才有 LDAP 认证），仅作为快速体验或老系统兼容场景使用。

4.2 安装命令与回显

DEBIAN_FRONTEND=noninteractive apt-get install -y pgbouncer

实测回显（节选）：

Setting up pgbouncer (1.16.1-1ubuntu1) ...
invoke-rc.d: policy-rc.d denied execution of restart.
Processing triggers for libc-bin (2.35-0ubuntu3.14) ...

4.3 包结构确认

dpkg -L pgbouncer | grep -E "bin|etc|init"

实测回显：

/etc
/etc/default
/etc/default/pgbouncer
/etc/init.d
/etc/init.d/pgbouncer
/etc/pgbouncer
/etc/pgbouncer/pgbouncer.ini
/etc/pgbouncer/userlist.txt
/usr/sbin
/usr/sbin/pgbouncer

关键差异解读：该包只有 SysV init 脚本（/etc/init.d/pgbouncer），没有原生 systemd unit；Ubuntu 22.04 的 systemd 会通过 systemd-sysv-generator 自动生成兼容单元。启动参数通过 /etc/default/pgbouncer 的 OPTS 调整，默认值如下（实测原文件内容）：

# It is possible to change the options the daemon is started with.
# The default setting is shown below, uncomment and apply your changes
# if you need to modify it.

#OPTS="-d /etc/pgbouncer/pgbouncer.ini"

确认 systemd 侧看到的单元（实测回显，自动生成器产物）：

systemctl cat pgbouncer | head -8

# /run/systemd/generator.late/pgbouncer.service
# Automatically generated by systemd-sysv-generator

[Unit]
Documentation=man:systemd-sysv-generator(8)
SourcePath=/etc/init.d/pgbouncer
Description=LSB: start pgbouncer
Before=multi-user.target

4.4 版本验证

/usr/sbin/pgbouncer -V

实测回显：

PgBouncer 1.16.1
libevent 2.1.12-stable
adns: evdns2 (self-resolver)
tls: OpenSSL 3.0.2 15 Mar 2022

五、方案 B：PGDG 官方 apt 源安装 1.26.1（推荐）

5.1 方案说明

PostgreSQL 官方 apt 仓库（PGDG）为 Ubuntu 22.04 提供与上游同步的 pgbouncer 包，查询日候选版本即 1.26.1-1.pgdg22.04+1，且自带原生 systemd unit（Type=notify），是生产环境推荐的安装方式。

5.2 添加 PGDG 源

apt-get install -y curl ca-certificates gnupg
install -d /usr/share/postgresql-common/pgdg
curl -fsSL -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] https://apt.postgresql.org/pub/repos/apt jammy-pgdg main" > /etc/apt/sources.list.d/pgdg.list
apt-get update

实测回显（apt update 节选）：

Get:5 https://apt.postgresql.org/pub/repos/apt jammy-pgdg InRelease [129 kB]
Get:6 https://apt.postgresql.org/pub/repos/apt jammy-pgdg/main amd64 Packages [375 kB]
Reading package lists... Done

确认候选版本已变为 1.26.1：

apt-cache policy pgbouncer

实测回显：

pgbouncer:
  Installed: 1.16.1-1ubuntu1
  Candidate: 1.26.1-1.pgdg22.04+1
  Version table:
     1.26.1-1.pgdg22.04+1 500
        500 https://apt.postgresql.org/pub/repos/apt jammy-pgdg/main amd64 Packages
     1.26.0-4.pgdg22.04+1 500
        500 https://apt.postgresql.org/pub/repos/apt jammy-pgdg/main amd64 Packages

💡 说明：若此前已按方案 A 装过 1.16.1，直接执行下一步 install 即可原地升级（conffile 配置文件会被保留）。从零开始的读者跳过方案 A 也完全成立。

5.3 安装 1.26.1

DEBIAN_FRONTEND=noninteractive apt-get install -y pgbouncer

实测回显（节选，注意安装脚本已自动注册开机自启）：

Created symlink /etc/systemd/system/multi-user.target.wants/pgbouncer.service → /lib/systemd/system/pgbouncer.service.
/usr/sbin/policy-rc.d returned 101, not running 'restart pgbouncer.service'

确认版本与原生 unit：

/usr/sbin/pgbouncer -V | head -1

PgBouncer 1.26.1

systemctl cat pgbouncer

实测回显（PGDG 包自带的原生单元）：

# /lib/systemd/system/pgbouncer.service
[Unit]
Description=connection pooler for PostgreSQL
Documentation=man:pgbouncer(1)
Documentation=https://www.pgbouncer.org/
After=network.target
#Requires=pgbouncer.socket

[Service]
Type=notify
User=postgres
ExecStart=/usr/sbin/pgbouncer /etc/pgbouncer/pgbouncer.ini
ExecReload=/bin/kill -HUP $MAINPID
KillSignal=SIGINT
#LimitNOFILE=1024

[Install]
WantedBy=multi-user.target

配置要点解读：Type=notify 要求 PgBouncer 编译期带 systemd 支持（PGDG 包已启用），进程就绪后主动通知 systemd；User=postgres 表示服务以 postgres 用户运行，因此配置目录与日志目录权限需归 postgres 所有；ExecReload 走 SIGHUP，等价于管理控制台的 RELOAD。

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

6.1 方案说明

从 pgbouncer.org 下载官方源码包，本地校验 sha256 后编译安装到 /usr/local。适合无法访问软件源、需要自定义 prefix 或想体验 Meson 构建的场景。本方案完整记录了编译过程中遇到的两个真实报错与解决过程。

6.2 安装编译依赖

apt-get install -y --no-install-recommends build-essential libevent-dev libssl-dev pkg-config wget ca-certificates python3 pandoc libsystemd-dev

实测回显（节选）：

Setting up libsystemd-dev:amd64 (249.11-0ubuntu3.16) ...
Setting up pandoc (2.9.2.1-3ubuntu2) ...

⚠️ 注意：python3 与 pandoc 用于构建 man 手册页，libsystemd-dev 用于启用 systemd notify 支持，三者都不是可省略项——缺了它们 make 阶段必然失败（排障过程见 6.5）。

6.3 下载源码包并校验 sha256

mkdir -p /opt/src && cd /opt/src
wget https://www.pgbouncer.org/downloads/files/1.26.1/pgbouncer-1.26.1.tar.gz
wget https://www.pgbouncer.org/downloads/files/1.26.1/pgbouncer-1.26.1.tar.gz.sha256
cat pgbouncer-1.26.1.tar.gz.sha256
sha256sum pgbouncer-1.26.1.tar.gz

实测回显（两行一致，校验通过）：

00886a2994b4844cd37110970df777772cfc42a74c400522c82fba509a3f42d9  pgbouncer-1.26.1.tar.gz
00886a2994b4844cd37110970df777772cfc42a74c400522c82fba509a3f42d9  pgbouncer-1.26.1.tar.gz

6.4 解压、配置与编译安装

cd /opt/src
tar xzf pgbouncer-1.26.1.tar.gz
cd pgbouncer-1.26.1
./configure --prefix=/usr/local --with-systemd
make -j$(nproc)
make install

./configure 结束时的能力检测汇总（实测回显）：

Results:
  adns    = evdns2
  ldap    = no
  pam     = no
  systemd = yes
  tls     = yes

配置项解读：systemd = yes 来自 --with-systemd + libsystemd-dev，启用后可用 Type=notify 托管；ldap/pam 默认关闭，需要时分别加 --with-ldap（依赖 libldap-dev）与 --with-pam（依赖 libpam0g-dev）重新 configure；adns = evdns2 表示使用 libevent 内置异步 DNS（想用更完整的 c-ares 后端可 apt install libc-ares-dev 后加 --with-cares）。

pgbouncer -V 验证（实测回显）：

/usr/local/bin/pgbouncer -V

PgBouncer 1.26.1
libevent 2.1.12-stable
adns: evdns2
tls: OpenSSL 3.0.2 15 Mar 2022
systemd: yes

6.5 编译排障实录

报错一：man 页构建缺 python3。 未装 python3 时 make 报错（实测回显）：

make -C doc pgbouncer.1
python3 filter.py frag-usage-man.md usage.md >pgbouncer_1.md
/bin/sh: 1: python3: not found
make[1]: *** [Makefile:22: pgbouncer_1.md] Error 127
make: *** [Makefile:204: doc/pgbouncer.1] Error 2

解决：apt-get install -y python3 后重新 make。

报错二：man 页构建缺 pandoc。 装完 python3 后 make 继续报错（实测回显）：

make -C doc pgbouncer.1
pandoc -s -t man -o pgbouncer.1 pgbouncer_1.md
make[1]: pandoc: No such file or directory
make[1]: *** [Makefile:19: pgbouncer.1] Error 127
make: *** [Makefile:204: doc/pgbouncer.1] Error 2

解决：apt-get install -y pandoc 后重新 make。

提醒三：默认不带 systemd 支持。 不加 --with-systemd 时 configure 结果为 systemd = no，此时若在 unit 文件里写 Type=notify，服务会因无法通知 systemd 而启动超时失败。本文实测统一加了 --with-systemd 与 libsystemd-dev。

6.6 源码版的 systemd 托管

源码安装不自带 unit 文件，按官方源码 etc/pgbouncer.service 模板创建（需要先按第八章准备好运行目录与配置）：

cat > /etc/systemd/system/pgbouncer.service <<'EOF'
[Unit]
Description=connection pooler for PostgreSQL
Documentation=man:pgbouncer(1)
Documentation=https://www.pgbouncer.org/
After=network.target

[Service]
Type=notify
User=postgres
ExecStart=/usr/local/bin/pgbouncer /etc/pgbouncer/pgbouncer.ini
ExecReload=/bin/kill -HUP $MAINPID
KillSignal=SIGINT
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable pgbouncer

实测回显：

Created symlink /etc/systemd/system/pgbouncer.service → /usr/lib/systemd/system/pgbouncer.service.

七、方案对比与选择建议

维度方案 A：universe apt方案 B：PGDG apt（推荐）方案 C：源码编译
版本1.16.1（冻结）1.26.1（与上游同步）任意（实测 1.26.1）
是否需联网是是下载时可离线拷包
systemd 支持来源sysvinit 生成器兼容层原生 Type=notify unit手工 unit + --with-systemd
二进制路径/usr/sbin/pgbouncer/usr/sbin/pgbouncer/usr/local/bin/pgbouncer
配置文件/etc/pgbouncer/pgbouncer.ini/etc/pgbouncer/pgbouncer.ini/etc/pgbouncer/pgbouncer.ini（自管）
升级方式apt upgrade（跟随发行版）apt upgrade（跟随 PGDG）重编译 + 替换
适用场景老系统兼容、快速体验生产首选无源/定制编译选项

选择建议一句话版：能联网选 B；无源且需最新版选 C；A 仅在受控老环境使用。

八、配置说明（三种方案通用）

本节给出可跑通后端连接的最小配置，三种安装方案的差异只在二进制与 unit 路径，配置文件内容一致。

8.1 运行目录与运行用户

mkdir -p /etc/pgbouncer /var/log/pgbouncer /var/run/pgbouncer
useradd -m -s /bin/bash postgres 2>/dev/null || true   # PGDG 方案已自动创建，源码方案补建

8.2 pgbouncer.ini 最小配置

cat > /etc/pgbouncer/pgbouncer.ini <<'EOF'
[databases]
appdb = host=10.89.56.2 port=5432 dbname=appdb

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
admin_users = postgres
stats_users = postgres
pool_mode = session
default_pool_size = 20
min_pool_size = 5
reserve_pool_size = 2
max_client_conn = 100
log_connections = 1
log_disconnections = 1
log_pooler_errors = 1
logfile = /var/log/pgbouncer/pgbouncer.log
pidfile = /var/run/pgbouncer/pgbouncer.pid
unix_socket_dir = /var/run/pgbouncer
EOF

配置解读：[databases] 把客户端连接串里的库名 appdb 映射到后端 10.89.56.2:5432/appdb；auth_type = scram-sha-256 与 PostgreSQL 18 默认密码加密方式一致；admin_users 授权 postgres 用户进入管理控制台；池参数含义见本专栏《PgBouncer 1.26.1 配置参数详解》篇。PGDG 方案的默认日志/运行目录为 postgres 用户的 /var/log/postgresql/、/var/run/postgresql/，如沿用包默认 ini 只需改 [databases] 一行。

8.3 userlist.txt 凭据文件

cat > /etc/pgbouncer/userlist.txt <<'EOF'
"appuser" "q1w2e3r4"
"postgres" "q1w2e3r4"
EOF
chown -R postgres:postgres /etc/pgbouncer /var/log/pgbouncer /var/run/pgbouncer

💡 说明：auth_type 为 scram-sha-256 时，userlist.txt 中既可放明文口令（PgBouncer 自行完成 SCRAM 计算），也可放从 pg_authid.rolpassword 提取的 SCRAM secret（以 SCRAM-SHA-256$ 开头），生产环境建议后者。

8.4 启动与开机自启（PGDG 方案）

systemctl start pgbouncer
systemctl is-active pgbouncer

实测回显：

active

systemctl status pgbouncer --no-pager -l

实测回显（节选）：

● pgbouncer.service - connection pooler for PostgreSQL
     Loaded: loaded (/lib/systemd/system/pgbouncer.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-19 16:40:35 UTC; 5ms ago
       Docs: man:pgbouncer(1)
             https://www.pgbouncer.org/
   Main PID: 4595 (pgbouncer)
      Tasks: 3 (limit: 5753)
     Memory: 8.0M

日常运维三件套（每行一个单元，逐条执行）：

systemctl reload pgbouncer
systemctl restart pgbouncer
systemctl is-enabled pgbouncer

实测回显依次为：

active
active
enabled

8.5 启动日志确认

tail -4 /var/log/pgbouncer/pgbouncer.log

实测回显（源码方案路径；PGDG 方案默认在 /var/log/postgresql/pgbouncer.log）：

2026-10-19 16:38:56.621 UTC [11323] LOG listening on 0.0.0.0:6432
2026-10-19 16:38:56.621 UTC [11323] LOG listening on unix:/var/run/pgbouncer/.s.PGSQL.6432
2026-10-19 16:38:56.621 UTC [11323] LOG process up: PgBouncer 1.26.1, libevent 2.1.12-stable (epoll), adns: evdns2, tls: OpenSSL 3.0.2 15 Mar 2022

九、端到端验证

目标是证明"客户端连的是 PgBouncer，查询在 PostgreSQL 上执行"——即多路复用生效。在客户端机器上执行：

PGPASSWORD=q1w2e3r4 psql -h 10.89.56.3 -p 6432 -U appuser appdb -c "SELECT current_user, current_database(), inet_server_addr() AS backend_ip, inet_server_port() AS backend_port;"

实测回显：

 current_user | current_database | backend_ip | backend_port
--------------+------------------+------------+--------------
 appuser      | appdb            | 10.89.56.2 |         5432
(1 row)

结果解读：连接目标是 10.89.56.3:6432（PgBouncer），而 inet_server_addr() 返回 10.89.56.2:5432——查询确实透传到了 PostgreSQL 后端，链路完整。再以管理账号连虚拟库确认控制台可用：

PGPASSWORD=q1w2e3r4 psql -h 10.89.56.3 -p 6432 -U postgres pgbouncer -c "SHOW VERSION;"

实测回显：

     version
------------------
 PgBouncer 1.26.1
(1 row)

十、常见问题（FAQ）

Q1：make 报 python3: not found 或 pandoc: No such file or directory 怎么办？ 这是源码构建 man 页时的两个真实报错（回显见 6.5），补装 python3、pandoc 后重新 make && make install 即可，无需重新 configure。

Q2：systemd 启动超时失败（Service never acquired its NOTIFY socket）？ unit 写了 Type=notify 但二进制编译时没有 systemd 支持（configure 结果 systemd = no）。要么重编译加 --with-systemd + libsystemd-dev，要么把 unit 改成 Type=simple（失去就绪通知，不推荐）。

Q3：启动报 FATAL PgBouncer cannot listen on 0.0.0.0:6432 或端口被占？ 6432 已被其他进程占用，用 ss -ltnp | grep 6432 找到占用者；更换 listen_port 或释放端口后重启。

Q4：连接报 FATAL: no more connections allowed (max_client_conn)？ 客户端连接总数达到 max_client_conn 上限（默认 100）。这是实测可复现的行为：把 max_client_conn 临时调成 1 后，第二个客户端连接被拒，实测报错即为此信息。处理方向是调大参数、排查连接泄漏（SHOW CLIENTS 观察异常连接）。

Q5：pgbouncer.log 报 login failed: FATAL password authentication failed？ auth_type 与凭据形态不匹配：后端用户是 SCRAM 密码而 userlist 放了 md5 hash（或反之）。用 SELECT rolname, rolpassword FROM pg_authid;（后端超级用户执行）核对，userlist.txt 中直接放明文口令可同时兼容 SCRAM/md5 校验（仅限受控环境）。

Q6：如何只升级小版本而不动配置？ PGDG 方案 apt-get install -y pgbouncer 后 systemctl restart pgbouncer，conffile（/etc/pgbouncer/*）由 dpkg 保护不会覆盖；源码方案在 /opt/src 解压新版本重编译 make install 后 restart，配置在 /etc/pgbouncer 不受影响。回滚同构：apt-get install pgbouncer=1.26.0-4.pgdg22.04+1（PGDG 源保留了 1.26.0 版本，见 5.2 的 apt-cache policy 回显）。

十一、卸载与清理

apt 方案（每行单独执行）：

systemctl stop pgbouncer
systemctl disable pgbouncer
apt-get remove --purge -y pgbouncer

实测回显（节选）：

Removed "/etc/systemd/system/multi-user.target.wants/pgbouncer.service".

源码方案：

systemctl stop pgbouncer
systemctl disable pgbouncer
rm -f /etc/systemd/system/pgbouncer.service
systemctl daemon-reload
rm -f /usr/local/bin/pgbouncer /usr/local/share/man/man1/pgbouncer.1 /usr/local/share/man/man5/pgbouncer.5

最后按需删除配置与日志目录：

rm -rf /etc/pgbouncer /var/log/pgbouncer /var/run/pgbouncer /opt/src/pgbouncer-1.26.1*

十二、参考链接