PgBouncer 生产型实践方案（单机 / 多应用 / 2C4G）

1. 设计目标

• 防止数据库连接雪崩
• 限制 PostgreSQL 实际连接数
• 支撑多应用高并发
• PgBouncer 本身不成为瓶颈
• 故障可快速定位、可回滚

核心原则：稳定优先于吞吐。

2. 推荐架构

[ App / Framework / ORM ]
          │
          ▼
   PgBouncer (6432)
          │
          ▼
 PostgreSQL 16 (5432)

• PgBouncer 与 PostgreSQL 同机部署
• 应用 禁止直连 5432
• PgBouncer 只做连接池，不做 SQL 路由

3. 安装

dnf install -y pgbouncer

4. pgbouncer.ini（生产基线配置）

[databases]
* = host=127.0.0.1 port=5432

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432

unix_socket_dir = /var/run/pgbouncer

auth_type = md5
auth_file = /etc/pgbouncer/userlist.txt

pool_mode = transaction

max_client_conn = 1000
default_pool_size = 20
reserve_pool_size = 5
reserve_pool_timeout = 3

server_idle_timeout = 60
server_lifetime = 3600

query_wait_timeout = 120
client_idle_timeout = 300

log_connections = 1
log_disconnections = 1
log_pooler_errors = 1

stats_period = 60

ignore_startup_parameters = extra_float_digits

参数解释（关键）

• pool_mode = transaction：唯一推荐生产模式
• default_pool_size = 20：对应 PostgreSQL 实际并发
• max_client_conn = 1000：允许应用暴增而不打死数据库

5. userlist.txt 管理规范

"app1_user" "md5xxxxxxxx"
"app2_user" "md5yyyyyyyy"

生成方式：

SELECT '"' || rolname || '" "md5' || md5(rolpassword || rolname) || '"'
FROM pg_authid
WHERE rolname = 'app1_user';

更新后热加载：

pgbouncer -R /etc/pgbouncer/pgbouncer.ini

6. PostgreSQL 侧强制配合配置

ALTER SYSTEM SET max_connections = 100;
SELECT pg_reload_conf();

原则：

• PostgreSQL max_connections 永远小于 PgBouncer max_client_conn
• 数据库只接受“被池化后的连接”

7. 应用接入规范（强制）

• 端口：6432
• 禁止：直连 5432

• 禁止：session 级特性

  • 临时表
  • SET LOCAL 以外的会话变量

推荐：

• 每个应用 1 用户 + 1 数据库
• 每个应用 connection limit ≤ pool_size

8. 监控与巡检（必做）

PgBouncer 状态

SHOW POOLS;
SHOW STATS;
SHOW CLIENTS;

重点指标

9. 常见生产事故与应对

1️⃣ cl_waiting 持续 > 0

处理顺序：

1. 查慢 SQL
2. 查长事务
3. 再考虑 pool_size +5

2️⃣ PgBouncer 重启影响？

• transaction 模式
• 正在执行的事务完成后断开
• 不会破坏数据一致性

10. 明确不支持清单（写给未来的你）

PgBouncer（transaction）不适合：

• 长时间持有 session
• 使用 prepared statement 跨事务
• 临时表依赖

11. 生产底线总结

PgBouncer 的职责只有一个： 把数据库从“连接不可控”变成“连接可治理”。

在 2C4G 单机场景：

• PgBouncer 是 必须品，不是优化项
• pool_size 是稳定阈值，不是性能旋钮

本文由 best 创作，采用 知识共享署名 3.0 中国大陆许可协议 进行许可。 可自由转载、引用，但需署名作者且注明文章出处。