astronomerinc/ap-pgbouncer

Astronomer Platform Airflow PgBouncer 镜像文档

1. 镜像概述和主要用途

1.1 镜像概述

本镜像是为 Astronomer Platform 中 Airflow 部署提供的 PgBouncer 服务容器化实现。PgBouncer 是一款轻量级的 PostgreSQL 连接池工具，通过集中管理数据库连接、实现连接复用，降低数据库连接创建/销毁的开销，优化资源利用率。

1.2 主要用途

• 作为 Airflow 与 PostgreSQL 数据库之间的连接中间层，管理 Airflow 元数据库（如任务元数据、配置信息）的连接池
• 限制 Airflow 集群对 PostgreSQL 的并发连接数，防止数据库连接耗尽
• 提高连接复用率，减少短连接场景下的数据库性能损耗
• 简化 Airflow 多节点部署时的数据库连接配置

2. 核心功能和特性

2.1 连接池管理

• 多模式池支持：提供会话池（session）、事务池（transaction）、语句池（statement）三种模式，适配不同场景需求：
  • 会话池：连接与客户端会话绑定，会话结束后释放（适合长连接场景）
  • 事务池：连接在事务结束后释放并复用（适合短事务频繁的场景，如 Airflow 任务调度）
  • 语句池：每条 SQL 语句执行后释放连接（最小粒度复用，适合无状态查询场景）
• 连接复用：同一客户端或不同客户端可复用已建立的数据库连接，减少 TCP 握手和 PostgreSQL 会话初始化开销

2.2 资源控制与安全

• 连接数限制：可配置全局最大连接数、单个池最大连接数，防止数据库过载
• 连接超时管理：支持空闲连接超时、客户端连接超时配置，自动释放闲置资源
• 认证集成：支持 PostgreSQL 原生认证（通过 pg_hba.conf 或 users.txt），兼容 md5、scram-sha-256 等认证方式

2.3 可观测性与运维支持

• 监控接口：提供内置的 PostgreSQL 兼容监控数据库（pgbouncer），可通过 SQL 查询连接池状态（如 SHOW POOLS、SHOW CLIENTS）
• 日志输出：支持详细连接日志、错误日志，可配置日志级别（info/warn/debug）和输出格式
• 热重载配置：支持通过 RELOAD 命令或信号（SIGHUP）动态加载配置变更，无需重启服务

3. 使用场景和适用范围

3.1 适用场景

• Airflow 集群部署：多 Airflow Worker 节点、Scheduler 节点并发访问同一 PostgreSQL 元数据库时，通过 PgBouncer 统一管理连接池
• 高并发任务场景：Airflow 任务调度频繁（如分钟级调度、大量并行任务），导致数据库短连接请求密集，需通过连接复用降低数据库负载
• 数据库资源受限：PostgreSQL 实例最大连接数有限（如默认 100 连接），而 Airflow 集群节点数或任务并发数超过该限制时，通过 PgBouncer 压缩连接数
• 连接性能优化：Airflow 任务执行周期短（毫秒/秒级），频繁创建连接导致数据库 CPU/内存开销大，通过事务池或语句池模式提升连接效率

3.2 适用范围

• 部署环境：Astronomer Platform 管理的 Airflow 集群（兼容 Astronomer Certified Airflow 镜像）
• 数据库类型：PostgreSQL 数据库（Airflow 元数据库默认类型）
• 部署模式：Docker 容器化部署（单机或 Kubernetes 集群）

3.3 不适用场景

• 对连接隔离性要求极高的场景（如会话级临时表依赖，需使用会话池模式并谨慎评估）
• 非 PostgreSQL 数据库（PgBouncer 仅支持 PostgreSQL 协议）
• 无连接复用需求的小规模 Airflow 部署（单节点、低并发任务，直接连接数据库更简单）

4. 使用方法和配置说明

4.1 Docker 快速启动

4.1.1 基础 Docker Run 命令

bash
docker run -d \
  --name airflow-pgbouncer \
  -p 6432:6432 \  # PgBouncer 默认端口
  -e POSTGRES_HOST=postgres \
  -e POSTGRES_PORT=5432 \
  -e POSTGRES_DB=airflow \
  -e POSTGRES_USER=airflow \
  -e POSTGRES_PASSWORD=airflow_password \
  -e POOL_MODE=transaction \  # 事务池模式（适合 Airflow 短事务）
  -e MAX_CONNECTIONS=100 \  # PgBouncer 全局最大连接数
  -e DEFAULT_POOL_SIZE=20 \  # 每个数据库池默认连接数
  astronomer/pgbouncer:latest

4.1.2 Docker Compose 配置示例

yaml
version: '3.8'
services:
  pgbouncer:
    image: astronomer/pgbouncer:latest
    ports:
      - "6432:6432"
    environment:
      # 数据库连接配置
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_DB: airflow
      POSTGRES_USER: airflow
      POSTGRES_PASSWORD: ${AIRFLOW_DB_PASSWORD}
      # 池配置
      POOL_MODE: transaction
      MAX_CONNECTIONS: 150
      DEFAULT_POOL_SIZE: 25
      RESERVE_POOL_SIZE: 5  # 池耗尽时可临时扩容的连接数
      RESERVE_POOL_TIMEOUT: 5  # 临时连接的超时时间（秒）
      # 连接超时配置
      IDLE_TIMEOUT: 300  # 空闲连接超时（秒）
      SERVER_LIFETIME: 3600  # 连接最大存活时间（秒）
    volumes:
      - ./pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini  # 自定义配置文件挂载（可选）
      - ./users.txt:/etc/pgbouncer/users.txt  # 认证用户文件（可选，优先级高于环境变量）
    depends_on:
      - postgres
    restart: unless-stopped

  postgres:
    image: postgres:14
    environment:
      POSTGRES_DB: airflow
      POSTGRES_USER: airflow
      POSTGRES_PASSWORD: ${AIRFLOW_DB_PASSWORD}
    volumes:
      - postgres-db-volume:/var/lib/postgresql/data

volumes:
  postgres-db-volume:

4.2 核心配置参数

4.2.1 配置文件（pgbouncer.ini）关键配置

PgBouncer 核心配置文件为 pgbouncer.ini，以下为 Airflow 场景常用配置项：

ini
[databases]
# 数据库连接配置（格式：<池名称> = host=<postgres_host> port=<port> dbname=<db> user=<user> password=<pass>）
airflow_meta = host=postgres port=5432 dbname=airflow user=airflow password=airflow_password

[pgbouncer]
# 池配置
pool_mode = transaction  # 连接池模式：session/transaction/statement
max_connections = 100    # 全局最大连接数（建议小于 PostgreSQL max_connections）
default_pool_size = 20   # 每个数据库池默认连接数
reserve_pool_size = 5    # 池耗尽时的临时扩容连接数
reserve_pool_timeout = 5 # 临时连接等待超时（秒）

# 连接超时
idle_timeout = 300       # 空闲连接超时（秒，超时后释放）
server_lifetime = 3600   # 连接最大存活时间（秒，防止连接长期占用）
server_idle_timeout = 600 # 数据库端空闲超时（需与 PostgreSQL 配置匹配）

# 网络配置
listen_addr = 0.0.0.0    # 监听地址（容器内需监听所有接口）
listen_port = 6432       # 监听端口
unix_socket_dir = /tmp   # Unix 套接字目录（可选）

# 认证配置
auth_type = md5          # 认证方式：md5/scram-sha-256/trust
auth_file = /etc/pgbouncer/users.txt  # 用户认证文件路径
auth_hba_file = /etc/pgbouncer/pg_hba.conf  # HBA 配置文件（可选，优先级高于 auth_file）

# 日志配置
log_level = info         # 日志级别：debug/info/warn/error
log_connections = 1      # 记录客户端连接日志
log_disconnections = 1   # 记录客户端断开日志
log_pooler_errors = 1    # 记录池操作错误

4.2.2 环境变量配置

容器化部署时，可通过环境变量覆盖默认配置（优先级：环境变量 > 挂载的 pgbouncer.ini > 镜像内置配置）：

4.3 监控与运维

4.3.1 连接状态查询

通过 psql 或 Airflow 数据库客户端连接 PgBouncer 监控接口（默认数据库名 pgbouncer）：

bash
psql -h localhost -p 6432 -U pgbouncer pgbouncer

常用监控命令：

• SHOW POOLS;：查看各数据库池状态（当前连接数、活跃数、等待数等）
• SHOW CLIENTS;：查看客户端连接详情
• SHOW SERVERS;：查看与 PostgreSQL 的后端连接详情
• SHOW STATS;：查看连接池统计信息（连接创建数、复用数、查询数等）

4.3.2 配置热重载

修改配置文件后，通过以下方式重载配置（无需重启容器）：

bash
# 进入容器执行
docker exec -it airflow-pgbouncer pgbouncer -R /etc/pgbouncer/pgbouncer.ini

# 或发送 SIGHUP 信号
docker kill -s SIGHUP airflow-pgbouncer

5. 注意事项

• 安全配置：生产环境中需禁用 auth_type=trust，建议使用 scram-sha-256 认证，并通过 users.txt 或 pg_hba.conf 严格限制访问来源
• 连接模式选择：Airflow 任务通常为短事务，推荐使用 transaction 模式；若任务包含会话级临时表（如 CREATE TEMP TABLE），需使用 session 模式
• 资源规划：MAX_CONNECTIONS 需小于 PostgreSQL 实例的 max_connections（建议预留 20% 余量），DEFAULT_POOL_SIZE 根据 Airflow 并发任务数调整（如每 10 个并发任务分配 1-2 个连接）
• 版本兼容性：确保 PgBouncer 版本与 PostgreSQL 版本兼容（如 PgBouncer 1.20+ 支持 PostgreSQL 14+ 的 scram-sha-256 认证）