.NET 8应用数据保护数据库连接失败无法显示错误页面的解决问询

问题根源 #

DataProtection的密钥加载逻辑默认触发于服务首次解析或应用启动阶段，这个阶段的异常不在常规请求管道的异常处理中间件覆盖范围内，因此UseExceptionHandler("/Error")无法捕获该场景下的CryptographicException，导致直接返回500原始错误。

解决方法 #

方案一：延迟密钥加载到请求管道阶段（推荐） #

通过自定义中间件将密钥初始化逻辑移到请求管道中，让异常能被常规异常处理中间件捕获：

1. 修改DataProtection配置，禁用自动密钥加载

builder.Services.AddDataProtection()
    .PersistKeysToDbContext<ApplicationDbContext>()
    .AddKeyManagementOptions(options =>
    {
        // 禁止启动时自动生成/加载密钥，改为手动触发
        options.AutoGenerateKeys = false;
    });

2. 编写密钥初始化中间件

public class DataProtectionInitializerMiddleware
{
    private readonly RequestDelegate _next;
    private readonly IDataProtectionProvider _dataProtectionProvider;
    private static bool _initialized;
    private static readonly object _lockObj = new();

    public DataProtectionInitializerMiddleware(RequestDelegate next, IDataProtectionProvider dataProtectionProvider)
    {
        _next = next;
        _dataProtectionProvider = dataProtectionProvider;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        if (!_initialized)
        {
            lock (_lockObj)
            {
                if (!_initialized)
                {
                    try
                    {
                        // 触发密钥加载逻辑
                        var protector = _dataProtectionProvider.CreateProtector("InitTrigger");
                        protector.Protect("test-init");
                        _initialized = true;
                    }
                    catch (Exception ex)
                    {
                        context.Items["DataProtectionInitError"] = ex;
                        throw; // 抛出异常让后续异常处理中间件捕获
                    }
                }
            }
        }

        await _next(context);
    }
}

// 注册中间件的扩展方法
public static class DataProtectionInitializerExtensions
{
    public static IApplicationBuilder UseDataProtectionInitializer(this IApplicationBuilder app)
    {
        return app.UseMiddleware<DataProtectionInitializerMiddleware>();
    }
}

3. 配置管道顺序
   确保异常处理中间件在初始化中间件之前，这样抛出的异常能被正确捕获：

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

// 注册初始化中间件，放在异常处理之后、路由之前
app.UseDataProtectionInitializer();

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();

app.MapRazorPages();

app.Run();

4. 在Error页面中处理自定义异常信息
   在Error.cshtml.cs中读取异常并显示针对性提示：

public class ErrorModel : PageModel
{
    private readonly ILogger<ErrorModel> _logger;

    public ErrorModel(ILogger<ErrorModel> logger)
    {
        _logger = logger;
    }

    public string? RequestId { get; set; }
    public string? CustomErrorMessage { get; set; }
    public bool ShowRequestId => !string.IsNullOrEmpty(RequestId);

    public void OnGet()
    {
        RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier;

        if (HttpContext.Items.TryGetValue("DataProtectionInitError", out var exObj) && exObj is Exception ex)
        {
            _logger.LogError(ex, "数据保护密钥加载失败（数据库连接异常）");
            CustomErrorMessage = "系统密钥服务暂时不可用，请检查数据库状态后重试。";
        }
    }
}

在Error.cshtml中添加自定义消息展示：

@page
@model ErrorModel
@{
    ViewData["Title"] = "系统错误";
}

<h1 class="text-danger">服务暂时不可用</h1>

@if (!string.IsNullOrEmpty(Model.CustomErrorMessage))
{
    <div class="alert alert-danger mt-3">@Model.CustomErrorMessage</div>
}

@if (Model.ShowRequestId)
{
    <p class="mt-3">
        <strong>请求ID:</strong> <code>@Model.RequestId</code>
    </p>
}

方案二：启动阶段捕获异常并替换管道 #

如果应用在启动时就依赖DataProtection（如后台服务提前使用加密），可以在启动时手动初始化并捕获异常，直接替换整个应用管道返回错误页面：

var builder = WebApplication.CreateBuilder(args);

// 常规服务配置
builder.Services.AddDataProtection()
    .PersistKeysToDbContext<ApplicationDbContext>();
builder.Services.AddRazorPages();

var app = builder.Build();

try
{
    // 启动时手动触发密钥加载
    var dpProvider = app.Services.GetRequiredService<IDataProtectionProvider>();
    var protector = dpProvider.CreateProtector("StartupInit");
    protector.Protect("startup-test");
}
catch (Exception)
{
    // 初始化失败，替换管道返回自定义错误页面
    app.Run(async context =>
    {
        context.Response.StatusCode = 500;
        context.Response.ContentType = "text/html";
        await context.Response.WriteAsync(@"
<!DOCTYPE html>
<html>
<head>
    <title>系统错误</title>
    <style>
        body { font-family: 'Segoe UI', Arial; margin: 60px auto; max-width: 600px; }
        .error-card { padding: 25px; border: 1px solid #dc3545; border-radius: 8px; background-color: #f8d7da; }
        h1 { color: #dc3545; margin-top: 0; }
    </style>
</head>
<body>
    <div class='error-card'>
        <h1>密钥服务连接失败</h1>
        <p>无法访问密钥存储数据库，请检查数据库服务状态后重试。</p>
    </div>
</body>
</html>");
    });
}

// 初始化成功则配置常规管道
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();

app.MapRazorPages();

app.Run();

内容的提问来源于stack exchange，提问作者Robert Galante