System Initiative PG Bouncer容器文档

镜像概述

System Initiative PG Bouncer容器是基于轻量级PostgreSQL连接池工具PG Bouncer构建的Docker镜像，旨在简化PostgreSQL数据库连接管理。PG Bouncer通过维护数据库连接池，避免频繁创建和关闭连接带来的性能开销，有效提高数据库资源利用率和访问稳定性，适用于各类需要与PostgreSQL交互的应用场景。

核心功能与特性

连接池管理

支持三种连接池模式：
- 会话池（Session Pooling）：一个连接在整个客户端会话期间保持分配
- 事务池（Transaction Pooling）：连接仅在事务期间分配，事务结束后释放回池
- 语句池（Statement Pooling）：连接在单个SQL语句执行期间分配，适用于无状态查询场景

资源优化

限制并发连接数，防止数据库因连接过载导致性能下降或崩溃
减少连接建立/关闭的频繁系统调用，降低数据库服务器CPU和内存消耗
支持连接复用，提高连接利用率

高可用性支持

支持数据库连接重定向，适配主从切换、故障转移场景
可配置连接超时和重试机制，增强服务稳定性
兼容PostgreSQL高可用解决方案（如Patroni、Stolon）

配置灵活性

支持动态加载配置变更，无需重启容器
集成用户认证管理，兼容PostgreSQL认证机制（md5、scram-sha-256等）
可自定义连接池大小、超时参数、日志级别等

使用场景与适用范围

高并发PostgreSQL应用

Web服务后端（如电商平台、内容管理系统）
数据分析与处理平台
多用户协作系统

资源受限环境

云服务器或容器化部署环境（需要控制数据库连接资源）
开发/测试环境（限制本地数据库连接数）

连接复用需求场景

短连接频繁创建的应用（如微服务架构中的数据库访问）
多应用共享同一PostgreSQL实例的场景
需要降低数据库连接建立延迟的实时数据处理系统

使用方法与配置说明

基本使用（Docker Run）

前提条件

已安装Docker引擎（20.10+版本推荐）
可访问的PostgreSQL数据库实例
本地PG Bouncer配置文件（pgbouncer.ini）

基本启动命令

bash
docker run -d \
  --name pg-bouncer \
  -p 6432:6432 \  # PG Bouncer默认端口
  -v /path/to/local/pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini \  # 挂载配置文件
  -v /path/to/userlist.txt:/etc/pgbouncer/userlist.txt \  # 可选：用户认证文件
  --network=postgres-network \  # 若PostgreSQL在Docker网络内，指定网络
  systeminit/pg-bouncer

Docker Compose配置示例

创建docker-compose.yml文件：

yaml
version: '3.8'

services:
  pg-bouncer:
    image: systeminit/pg-bouncer
    container_name: pg-bouncer
    ports:
      - "6432:6432"
    volumes:
      - ./pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini
      - ./userlist.txt:/etc/pgbouncer/userlist.txt
    environment:
      - LOG_LEVEL=info  # 日志级别：debug/info/warn/error
      - MAX_CLIENT_CONN=500  # 最大客户端连接数
    depends_on:
      - postgres  # 若PostgreSQL也在Compose中定义
    restart: unless-stopped

  postgres:
    image: postgres:14
    container_name: postgres
    environment:
      - POSTGRES_USER=dbuser
      - POSTGRES_PASSWORD=dbpass
      - POSTGRES_DB=appdb
    ports:
      - "5432:5432"

核心配置参数说明

配置文件（pgbouncer.ini）主要部分

[databases] - 后端数据库配置

ini
# 格式：<数据库别名> = host=<postgres_host> port=<postgres_port> dbname=<dbname> user=<user> password=<pass>
appdb = host=postgres port=5432 dbname=appdb user=dbuser password=dbpass
# 支持通配符匹配所有数据库
* = host=postgres port=5432

[pgbouncer] - 连接池核心配置

ini
# 连接池模式：session/transaction/statement
pool_mode = transaction
# 最大客户端连接数
max_client_conn = 500
# 每个数据库的默认池大小
default_pool_size = 20
# 每个池的最小连接数（预热连接）
min_pool_size = 5
# 每个池的最大溢出连接数（临时扩容）
reserve_pool_size = 10
# 连接空闲超时（秒）
idle_timeout = 300
# 连接生存周期（秒），超时后强制关闭重建
server_lifetime = 3600
# 日志文件路径
logfile = /var/log/pgbouncer/pgbouncer.log
# 日志级别
log_level = info
# 监听地址和端口
listen_addr = 0.0.0.0
listen_port = 6432
# 管理控制台用户（用于执行状态查询等操作）
admin_users = postgres

环境变量配置

环境变量名	描述	默认值
`LOG_LEVEL`	日志输出级别	`info`
`MAX_CLIENT_CONN`	最大客户端连接数	`100`
`DEFAULT_POOL_SIZE`	默认池大小	`10`
`POOL_MODE`	连接池模式	`transaction`
`LISTEN_PORT`	监听端口	`6432`
`IDLE_TIMEOUT`	连接空闲超时（秒）	`300`

管理与监控

通过PG Bouncer管理控制台监控连接状态：

bash
# 连接到管理控制台
psql -p 6432 -h localhost -U postgres pgbouncer

# 查看连接池状态
pgbouncer=# show pools;

# 查看客户端连接
pgbouncer=# show clients;

# 查看服务器连接
pgbouncer=# show servers;

# 重新加载配置
pgbouncer=# reload;

注意事项

配置文件权限：挂载的pgbouncer.ini和userlist.txt文件需确保容器内用户可读（建议权限644）
网络配置：确保容器与PostgreSQL实例网络互通，防火墙规则允许6432（PG Bouncer）和5432（PostgreSQL）端口通信
密码管理：生产环境建议通过环境变量或Docker Secrets管理敏感信息，避免配置文件明文存储密码
性能调优：根据应用并发量调整default_pool_size和max_client_conn，建议default_pool_size不超过PostgreSQL的max_connections值的50%
日志管理：建议挂载日志目录到宿主机，便于问题排查和日志审计