数据库连接池预热与保活操作手册 (.NET & PostgreSQL)

数据库连接池预热与保活操作手册 (.NET & PostgreSQL)

1. 核心概念与目标

概念	目标	解决痛点
连接池预热 (Warm-Up)	一次性支付成本：在应用启动时提前建立物理连接，填充连接池。	解决第一个用户请求极慢的问题（避免现场进行DNS、TCP、SSL、Auth）。
连接保活 (Keep-Alive)	周期性维持状态：防止数据库服务器因空闲超时而断开池中的连接。	解决运行一段时间后，连接失效导致的请求突然失败或变慢的问题。
查询预热 (Query Warm-Up)	优化数据库缓存：提前编译和缓存复杂查询的执行计划。	解决复杂查询第一次执行较慢的问题（避免查询优化器的开销）。

---

2. 连接字符串配置 (appsettings.json)

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=你的服务器;Port=5432;Database=你的数据库;Username=你的用户;Password=你的密码;Pooling=true;Minimum Pool Size=5;Maximum Pool Size=100;Connection Idle Lifetime=300;Timeout=15;CommandTimeout=30;"
  }
}

关键参数说明：

• Pooling=true: 启用连接池（默认true，但显式声明更清晰）。
• Minimum Pool Size=5: 核心参数 。指定连接池中始终保持的最小空闲连接数。必须与预热数量一致。
• Maximum Pool Size=100: 连接池允许的最大连接数。
• Connection Idle Lifetime=300: 空闲连接在池中的最大存活时间（秒），应与保活间隔配套（略小于保活间隔）。
• Timeout=15: 建立连接的超时时间（秒）。建议设置为15，优于默认30， fail fast。
• CommandTimeout=30: 执行SQL命令的超时时间（秒）。

---

3. 操作实施指南

3.1. 连接池预热 (启动时，同步执行)

位置： Startup.Configure 方法的最开始处。

.NET 5 代码示例 (Startup.cs):

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ===== 1. 连接池预热 (必须首先执行) =====
    PreWarmConnectionPool();
    // ===== 预热结束 =====

    // ... 其他中间件配置 (UseRouting, UseEndpoints等) ...
}

private void PreWarmConnectionPool()
{
    var connectionString = Configuration.GetConnectionString("DefaultConnection");
    int warmUpCount = 5; // 必须与连接字符串中的 `Minimum Pool Size` 值一致

    Console.WriteLine("[启动] 开始预热数据库连接池...");
    try
    {
        for (int i = 0; i < warmUpCount; i++)
        {
            // 使用同步操作，确保连接物理建立完成
            using (var connection = new NpgsqlConnection(connectionString))
            {
                connection.Open(); // 完成TCP/SSL/认证等昂贵操作
                // 执行一个最简单的查询，确保连接完全可用
                using (var cmd = new NpgsqlCommand("SELECT 1", connection))
                {
                    cmd.ExecuteNonQuery();
                }
            } // 连接关闭，物理连接被作为空闲连接放入池中
            Console.WriteLine($"[启动] 已预热连接 #{i + 1}/{warmUpCount}");
        }
        Console.WriteLine($"[启动] 连接池预热完成。{warmUpCount} 个连接已就绪。");
    }
    catch (Exception ex)
    {
        // 记录日志，根据实际情况决定是否阻止应用启动
        Console.WriteLine($"[启动] 连接池预热失败: {ex.Message}");
        // throw; // 如果数据库是必须的，可以抛出异常以阻止启动
    }
}

3.2. 连接保活 (运行时，周期性执行)

实现方式： 创建一个继承自 BackgroundService 的类。

代码示例 (DbKeepAliveService.cs):

public class DbKeepAliveService : BackgroundService
{
    private readonly IConfiguration _configuration;
    private readonly ILogger<DbKeepAliveService> _logger;

    public DbKeepAliveService(IConfiguration configuration, ILogger<DbKeepAliveService> logger)
    {
        _configuration = configuration;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation("数据库连接保活服务已启动。");

        // 等待应用启动和主预热完成
        await Task.Delay(TimeSpan.FromSeconds(10), stoppingToken);

        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                var connStr = _configuration.GetConnectionString("DefaultConnection");
                // 从池中借一个连接，执行保活查询后归还
                using (var connection = new NpgsqlConnection(connStr))
                {
                    await connection.OpenAsync(stoppingToken);
                    await connection.ExecuteAsync("SELECT 1;"); // 使用Dapper
                }
                _logger.LogDebug("连接保活成功执行。");
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "连接保活周期执行失败。");
            }

            // 每5分钟执行一次（应略小于数据库的 idle_in_transaction_session_timeout）
            await Task.Delay(TimeSpan.FromMinutes(5), stoppingToken);
        }
        _logger.LogInformation("数据库连接保活服务已停止。");
    }
}

注册服务 (Startup.ConfigureServices):

public void ConfigureServices(IServiceCollection services)
{
    // ... 其他服务 ...
    services.AddHostedService<DbKeepAliveService>(); // 添加这行
}

3.3. 查询预热 (可选，低频执行)

目的： 缓存高频复杂查询的执行计划。
位置： 可以放在保活服务中，但以更低的频率执行。

// 在 DbKeepAliveService 的循环中添加
// 例如：每小时的第0分钟执行一次（频率远低于保活）
if (DateTime.UtcNow.Minute == 0)
{
    await WarmUpCriticalQueries();
}

// 具体的预热方法
private async Task WarmUpCriticalQueries()
{
    try
    {
        var connStr = _configuration.GetConnectionString("DefaultConnection");
        using (var conn = new NpgsqlConnection(connStr))
        {
            await conn.OpenAsync();
            // 示例：使用绝不会命中的参数来预热SQL执行计划，避免磁盘I/O
            var userSql = @"SELECT * FROM sys_user WHERE user_id = @userId";
            await conn.QueryFirstOrDefaultAsync<UserInfo>(userSql, new { userId = "-999" });

            var orderSql = @"SELECT * FROM orders WHERE status = @status AND created_date > @date";
            await conn.QueryFirstOrDefaultAsync<Order>(orderSql, new { status = "INVALID_STATUS", date = DateTime.MaxValue });
        }
        _logger.LogInformation("高频查询执行计划预热完成。");
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "查询预热失败。");
    }
}

---

4. 检查清单与最佳实践

1. 确认连接字符串 ：已设置 Minimum Pool Size、Pooling=true 和合理的超时。
2. 实施同步预热 ：在 Startup.Configure 最开始处同步预热，数量与 Minimum Pool Size 一致。
3. 部署保活服务 ：已创建并注册 BackgroundService，以5分钟间隔运行 SELECT 1。
4. 网络优化：确保应用与数据库处于同一内网或可用区，最小化网络延迟。
5. 监控与日志：为预热和保活操作添加了足够的日志，便于排查问题。
6. 权限检查：确保应用使用的数据库账号只有必要权限，避免权限检查开销。

总结：预热解决"从无到有"的冷启动问题，保活解决"从有到优"的持续可用性问题。两者结合，方可确保数据库连接始终处于最佳性能状态。