GitLab 项目中 PgBouncer 服务的配置与使用指南

GitLab 项目中 PgBouncer 服务的配置与使用指南

什么是 PgBouncer

PgBouncer 是一个轻量级的 PostgreSQL 连接池工具，在 GitLab 项目中扮演着重要角色。它主要提供两大功能：

1. 连接池管理：通过复用数据库连接，显著减少资源消耗并提高响应速度
2. 故障转移支持：在服务器故障切换场景中无缝迁移数据库连接

GitLab 企业版（EE）软件包中已捆绑了 PgBouncer，所有版本均可免费使用，但高级支持需要 Premium 订阅。

两种部署场景

1. 非容错环境下的 PgBouncer 配置

在标准 GitLab 安装中配置 PgBouncer 的步骤如下：

数据库节点配置

1. 生成密码哈希：

   gitlab-ctl pg-password-md5 pgbouncer  # 生成PGBOUNCER_USER_PASSWORD_HASH
   gitlab-ctl pg-password-md5 gitlab     # 生成SQL_USER_PASSWORD_HASH
   

2. 编辑 /etc/gitlab/gitlab.rb：

   postgresql['pgbouncer_user_password'] = '生成的PGBOUNCER密码哈希'
   postgresql['sql_user_password'] = '生成的GitLab用户密码哈希'
   postgresql['listen_address'] = '数据库节点IP'
   postgresql['md5_auth_cidr_addresses'] = %w(PgBouncer节点IP/32)
   

3. 应用配置：

   gitlab-ctl reconfigure
   gitlab-ctl restart postgresql  # 如果数据库已在运行
   

PgBouncer 节点配置

1. 编辑 /etc/gitlab/gitlab.rb：

   pgbouncer['enable'] = true
   pgbouncer['databases'] = {
     gitlabhq_production: {
       host: '数据库主机地址',
       user: 'pgbouncer',
       password: 'PGBOUNCER_USER_PASSWORD_HASH'
     }
   }
   

2. 可选的高级参数：

   pgbouncer['databases']['gitlabhq_production']['pool_mode'] = 'transaction'
   

3. 应用配置：

   gitlab-ctl reconfigure
   

应用节点配置

1. 编辑 /etc/gitlab/gitlab.rb：

   gitlab_rails['db_host'] = 'PgBouncer主机'
   gitlab_rails['db_port'] = '6432'
   gitlab_rails['db_password'] = 'SQL_USER_PASSWORD明文'
   

2. 应用配置：

   gitlab-ctl reconfigure
   

2. 容错环境下的 PgBouncer 配置

在容错环境中，PgBouncer 的配置更为复杂，涉及多节点协调。由于内容较多，建议参考专门的容错配置文档。

监控配置

要在所有 PgBouncer 服务器上启用监控：

1. 编辑 /etc/gitlab/gitlab.rb：

   consul['enable'] = true
   consul['monitoring_service_discovery'] = true
   consul['configuration'] = {
     retry_join: %w(Consul服务器节点IP或主机名列表)
   }
   
   node_exporter['listen_address'] = '0.0.0.0:9100'
   pgbouncer_exporter['listen_address'] = '0.0.0.0:9188'
   

2. 应用配置：

   sudo gitlab-ctl reconfigure
   

管理控制台使用

GitLab 提供了便捷的命令访问 PgBouncer 管理控制台：

sudo gitlab-ctl pgb-console

常用管理命令示例：

show databases;  -- 显示数据库信息
show clients;    -- 显示客户端连接
show servers;    -- 显示服务器连接

性能调优建议

PgBouncer 默认配置适合大多数场景，但在特殊情况下可能需要调整：

1. 关键参数：

   • max_client_conn（默认2048）：前端连接池大小
   • default_pool_size（默认100）：后端连接池大小

2. 连接池计算：

   • Puma：(max_threads + headroom)
   • Sidekiq：(max_concurrency + 1 + headroom)
   • Geo-logcursor：(1 + headroom)

   总连接数 = (Puma实例数 × 连接数) + (Sidekiq实例数 × 连接数) + (Geo-logcursor实例数 × 连接数)

3. 多 PgBouncer 场景：如果有多个 PgBouncer 实例，可将 default_pool_size 除以实例数实现负载均衡

常见问题排查

基本排查步骤

1. 检查日志：

   sudo gitlab-ctl tail pgbouncer
   

2. 在管理控制台中检查：

   • host 字段应有正确值
   • current_connections 应大于1

特定错误解决

1. 错误：invalid CIDR mask in address

   • 检查 postgresql['md5_auth_cidr_addresses'] 配置格式是否正确

2. 错误：invalid IP mask "md5"

   • 确保 CIDR 地址格式正确，如 192.168.1.1/32

重要注意事项

1. 备份恢复：不要通过 PgBouncer 进行 GitLab 备份恢复操作，这会导致服务中断

2. 绕过 PgBouncer 的场景：

   • 数据库恢复
   • GitLab 升级执行数据库迁移

   绕过方法：

   • 修改 gitlab_rails['db_host'] 直接指向主数据库
   • 执行任务后恢复为 PgBouncer 配置

最佳实践

1. 定期监控 PgBouncer 的连接数和性能指标
2. 根据实际负载情况调整连接池大小
3. 在进行重大变更前，先在测试环境验证配置
4. 保持 PgBouncer 版本与 GitLab 版本兼容

通过合理配置和使用 PgBouncer，可以显著提升 GitLab 实例的数据库性能和可靠性。