4. PgBouncer 架构与安装

PgBouncer 是 PostgreSQL 生态中最成熟的轻量级连接池中间件。它通过代理模式接管客户端与数据库之间的连接，将大量短连接复用为少量长连接，从而显著降低数据库端的连接创建开销与内存占用。本章深入剖析 PgBouncer 的进程模型、三种主流安装方式以及核心配置文件结构，为后续连接池调优与对账流程集成打下坚实基础。

4.1 进程模型

PgBouncer 采用单进程、多线程的事件驱动架构，不依赖外部运行时或库。其核心进程模型包含以下关键组件：

  • 主线程（Main Thread）：负责监听客户端连接请求、解析协议、调度 I/O 事件，是整个引擎的调度中枢。
  • 工作线程（Worker Threads）：处理实际的数据包转发、查询解析、事务状态跟踪。默认数量等于 CPU 核心数，可通过 unix_socket_dir 和 listen_addr 绑定多个监听端点。
  • 管理控制台（Console）：通过 pgbouncer 数据库或 Unix 套接字提供实时管理接口，支持 SHOW POOLS、SHOW STATS、PAUSE、RESUME 等运维命令。
  • 连接槽（Connection Slots）：每个后端连接对应一个槽位，池内连接复用通过槽位分配实现，无额外线程切换开销。
关键设计原则：PgBouncer 不解析 SQL 语义，仅做传输层代理，因此性能极高（单核可达 10 万+ TPS），且对 PostgreSQL 协议完全透明。
PgBouncer 进程模型架构 客户端连接池 客户端连接池 客户端连接池 主线程：事件监听 / 协议解析 / 连接调度 Worker Thread 1 Worker Thread 2 Worker Thread N 连接槽池（复用后端连接） PostgreSQL 后端数据库

4.2 安装方式

PgBouncer 支持源码编译、RPM 包管理以及 Docker 容器化三种部署方式。下表对比了各方式的适用场景与操作要点：

安装方式 适用场景 核心命令 / 步骤 注意事项
源码编译 定制化编译选项、非标准路径、嵌入式环境 
./configure --prefix=/usr/local/pgbouncer
make && make install
 需安装 libevent、openssl、pkg-config 依赖；支持 --with-pam 等扩展
RPM 安装 RHEL/CentOS/Rocky Linux 生产环境 
yum install -y pgbouncer
# 或从 PGDG 仓库安装
yum install -y pgbouncer17
 建议从 PostgreSQL 官方 YUM 仓库（PGDG）获取最新版本；自动创建 pgbouncer 用户
Docker 部署 容器化微服务、Kubernetes 编排、快速测试 
docker run -d --name pgbouncer \
  -p 6432:6432 \
  -v /etc/pgbouncer:/etc/pgbouncer \
  bitnami/pgbouncer:latest
 官方镜像基于 Bitnami 或 edoburu；需挂载配置文件目录；注意网络模式与端口映射
生产建议：推荐使用 RPM 或 Docker 方式部署。源码编译适合需要启用 --enable-debug 或集成自定义认证模块的场景。无论哪种方式，安装后务必验证版本：pgbouncer --version。

4.3 配置文件结构

PgBouncer 的配置体系由三个核心文件组成，它们共同决定了连接池的行为、数据库映射关系以及用户认证策略。

4.3.1 主配置文件 pgbouncer.ini

该文件采用 INI 格式，分为 [databases]、[pgbouncer] 和 [users] 三个主要节区。以下是一个典型的生产配置示例：

[databases]
; 数据库映射：客户端连接 "mydb" 时，实际连接到 192.168.1.100:5432 的 mydb
mydb = host=192.168.1.100 port=5432 dbname=mydb
; 支持多个数据库映射
analytics = host=192.168.1.101 port=5432 dbname=analytics

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
unix_socket_dir = /var/run/pgbouncer

; 连接池模式：session / transaction / statement
pool_mode = transaction

; 默认池大小
default_pool_size = 25
max_client_conn = 100
max_db_connections = 50

; 认证方式
auth_type = md5
auth_file = /etc/pgbouncer/userlist.txt

; 日志与监控
logfile = /var/log/pgbouncer/pgbouncer.log
pidfile = /var/run/pgbouncer/pgbouncer.pid
stats_period = 60
admin_users = postgres, admin

[users]
; 用户级别的连接限制（可选）
postgres = pool_size=10
app_user = pool_size=5

4.3.2 用户认证文件 userlist.txt

该文件存储用户名与加密密码的映射关系，格式为 "username" "password"。密码必须使用 md5 或 scram-sha-256 加密：

"postgres" "md5a105990d3271a5d7a0f1e5a3e5a3e5a3"
"app_user" "md5b206991e4282b6e8b1f2e6b4f6b4f6b4"
"readonly" "md5c307992f5393c7f9c2f3e7c5g7c5g7c5"
安全提醒：切勿在 userlist.txt 中使用明文密码。生产环境建议结合 auth_type = hba 或对接 LDAP/RADIUS 实现集中认证。userlist.txt 文件权限应设置为 600，属主为 pgbouncer 用户。

4.3.3 日志与 PID 文件

PgBouncer 运行时还会生成以下动态文件：

  • 日志文件（pgbouncer.log）：记录连接建立、断开、错误、池状态变化等信息，是排查连接问题的第一手资料。
  • PID 文件（pgbouncer.pid）：存储主进程 PID，用于 systemd 或监控脚本进行进程管理。
  • 管理套接字（pgbouncer.ctl）：位于 unix_socket_dir 目录下，供 psql 连接管理数据库使用。
PgBouncer 配置文件关系与加载流程 pgbouncer.ini 主配置（数据库映射/池参数） userlist.txt 用户认证（加密密码） 运行时文件 日志 / PID / 套接字 auth_file 引用 logfile/pidfile 指定 PgBouncer 启动 → 读取 pgbouncer.ini → 加载 userlist.txt → 创建运行时文件 RELOAD; 或 kill -HUP → 热加载配置
配置热加载：修改 pgbouncer.ini 或 userlist.txt 后，无需重启进程。通过管理控制台执行 RELOAD; 命令或向进程发送 SIGHUP 信号即可生效。但注意 listen_addr、listen_port 等网络参数变更仍需重启。

4.3.4 关键配置参数速查表

参数名 默认值 说明 生产建议
pool_mode session 连接池复用模式：session（会话级）、transaction（事务级）、statement（语句级） 对账流程推荐 transaction 模式，兼顾复用率与事务隔离
default_pool_size 25 每个数据库池的默认后端连接数上限 根据数据库 CPU/内存调整，通常 20~50
max_client_conn 100 允许的最大客户端连接数 建议为 default_pool_size 的 4~10 倍
auth_type trust 认证方式：trust / md5 / scram-sha-256 / hba 生产环境必须设为 md5 或 scram-sha-256
server_idle_timeout 600 后端空闲连接超时（秒），超时后自动关闭 建议 300~600，避免长时间占用数据库连接
query_timeout 0 查询超时（秒），0 表示不限制 对账流程建议设置 30~60，防止慢查询拖垮池
对账流程特别关注：对账任务通常涉及大量短查询和批量事务，建议将 pool_mode 设为 transaction，并适当调大 default_pool_size（如 50~100）以应对并发对账线程。同时开启 log_connections = 1 和 log_disconnections = 1 便于审计连接行为。
← 上一章 📖 返回目录 下一章 →