ASP.NET Core中的健康检查是什么？如何配置？

小老鼠

发布时间：2025-09-13 08:44:01

1024人浏览过

来源于php中文网

原创

ASP.NET Core健康检查用于判断应用及依赖服务是否可正常处理请求，而不仅仅是进程是否运行。通过AddHealthChecks()注册服务，可添加数据库、URL等检查项，并支持自定义检查逻辑。利用MapHealthChecks()将终结点映射到HTTP管道，实现Liveness和Readiness探针区分。通过标签和自定义ResponseWriter可为不同环境定制报告，避免暴露敏感信息。需注意避免检查本身成为性能瓶颈、设置合理超时与缓存、防止假阳性/阴性、限制访问权限，并聚焦关键依赖，确保系统稳定可靠。

asp.net core中的健康检查是什么？如何配置？

ASP.NET Core中的健康检查，简单来说，就是一套内置的机制，用于报告你的应用程序及其所依赖服务的运行状态。它不仅仅是判断你的进程是否还活着，更重要的是，它能告诉你你的应用是否“健康到足以处理请求”，比如数据库连接是否正常、外部API是否可达、磁盘空间是否充足等。这对于部署在容器编排系统（如Kubernetes）或负载均衡器后的微服务架构来说至关重要，因为它们需要根据这些健康报告来决定是否将流量路由到某个实例，或者是否需要重启一个不健康的实例。

在ASP.NET Core中配置健康检查，其实比你想象的要直接。首先，你需要引入必要的NuGet包，主要是

Microsoft.Extensions.Diagnostics.HealthChecks

，如果需要UI，还有

AspNetCore.HealthChecks.UI

及其相关存储包。

基本配置流程：

在

Program.cs

中注册健康检查服务： 在

builder.Services

中调用

AddHealthChecks()

。

// Program.cs (Minimal API) 或 Startup.cs (旧版)
var builder = WebApplication.CreateBuilder(args);

// 注册健康检查服务
builder.Services.AddHealthChecks();

// ... 其他服务注册

添加具体的健康检查项：

AddHealthChecks()

方法返回一个

IHealthChecksBuilder

，你可以在其上链式调用各种

Add

方法来添加具体的检查项。

检查数据库连接 (例如 SQL Server): 你需要安装

AspNetCore.HealthChecks.SqlServer

或其他数据库对应的包。

builder.Services.AddHealthChecks()
    .AddSqlServer(builder.Configuration.GetConnectionString("DefaultConnection"), 
                  name: "SQL Server数据库", 
                  failureStatus: HealthStatus.Degraded, 
                  tags: new[] { "db", "critical" });

检查外部URL的可达性: 你需要安装

AspNetCore.HealthChecks.Uris

。

builder.Services.AddHealthChecks()
    .AddUrlGroup(new Uri("https://api.example.com/status"), 
                 name: "外部API", 
                 failureStatus: HealthStatus.Unhealthy, 
                 tags: new[] { "external", "api" });

自定义健康检查: 如果你需要检查一些非常规的东西，比如一个自定义的缓存状态，你可以实现

IHealthCheck

接口。

// MyCustomHealthCheck.cs
public class MyCustomHealthCheck : IHealthCheck
{
    public Task CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        // 模拟检查逻辑
        var isHealthy = DateTime.UtcNow.Second % 10 != 0; // 每10秒中有一秒不健康

        if (isHealthy)
        {
            return Task.FromResult(HealthCheckResult.Healthy("自定义服务运行正常。"));
        }

        return Task.FromResult(HealthCheckResult.Unhealthy("自定义服务出现问题。"));
    }
}

// Program.cs
builder.Services.AddHealthChecks()
    .AddCheck("我的自定义检查", 
                                  failureStatus: HealthStatus.Degraded, 
                                  tags: new[] { "custom" });

将健康检查终结点映射到HTTP请求管道： 在

app

对象上调用

MapHealthChecks()

。

var app = builder.Build();

// ... 其他中间件配置

// 映射健康检查终结点
app.MapHealthChecks("/health"); 
// 你也可以为Liveness和Readiness创建不同的终结点
app.MapHealthChecks("/health/ready", new HealthCheckOptions { 
    Predicate = healthCheck => healthCheck.Tags.Contains("ready") 
});
app.MapHealthChecks("/health/live", new HealthCheckOptions { 
    Predicate = healthCheck => healthCheck.Tags.Contains("live") 
});

app.Run();

现在，访问

/health

路径，你就能看到一个简单的健康报告。默认情况下，它会返回一个JSON，包含所有注册的检查项的状态。

为什么健康检查不仅仅是“服务还在跑”那么简单？

健康检查远不止是简单地确认你的应用程序进程是否在运行。如果仅仅是这样，那我们直接用操作系统的进程监控工具就好了。ASP.NET Core的健康检查机制，更侧重于深层健康和服务可用性。

想象一下，你的ASP.NET Core应用进程明明活着，CPU和内存看起来也正常，但它就是无法连接到数据库，或者它所依赖的某个关键第三方API突然抽风了。在这种情况下，虽然你的服务“还在跑”，但它根本无法正常处理用户的请求，对用户来说，它就是“挂了”。如果你的负载均衡器或Kubernetes只知道进程还活着就继续把流量导过来，那只会导致用户看到一堆错误，甚至可能加剧系统压力，造成雪崩效应。

这就是为什么我们需要区分“Liveness”（存活）和“Readiness”（就绪）。

播记

播客shownotes生成器 | 为播客创作者而生

下载

Liveness Probe（存活探针）通常只检查应用进程是否还在响应，比如一个简单的HTTP 200。如果失败，Kubernetes可能会重启这个Pod。
Readiness Probe（就绪探针）则更进一步，它会检查应用的所有关键依赖是否都已准备就绪，比如数据库连接、消息队列连接、必要的配置是否加载完成等等。只有当所有依赖都OK时，应用才被认为是“就绪”的，负载均衡器或Kubernetes才会开始向它发送流量。

所以，一个好的健康检查策略，是需要深入到应用内部，去探查那些真正影响服务功能的关键组件。它能帮助我们更智能地进行流量管理、故障恢复，避免将用户请求导向一个虽然活着但“病入膏肓”的服务实例。我个人在实践中，就遇到过很多次服务进程活着但功能完全失效的情况，深层健康检查就是那个救星，它能及时发现问题并让编排系统介入处理。

如何为不同环境定制健康检查报告？

为不同的环境（开发、测试、生产）定制健康检查报告，是一个非常实用的需求。你可能不希望在生产环境暴露过多的内部细节，或者在开发环境需要更详细的调试信息。ASP.NET Core的健康检查机制通过标签（Tags）和自定义响应写入器（ResponseWriter）提供了很好的灵活性。

利用标签进行过滤： 在注册健康检查时，你可以给每个检查项添加一个或多个标签。

builder.Services.AddHealthChecks()
    .AddSqlServer(builder.Configuration.GetConnectionString("DefaultConnection"), 
                  name: "主数据库", 
                  tags: new[] { "db", "production", "critical" }) // 生产环境和关键标签
    .AddUrlGroup(new Uri("http://localhost:5000/test-api"), 
                 name: "本地测试API", 
                 tags: new[] { "dev", "local" }); // 开发环境和本地标签

然后，在映射健康检查终结点时，你可以通过

Predicate

属性来过滤哪些检查项应该包含在这个报告中。

// 生产环境的健康检查，只包含标记为 "production" 和 "critical" 的项
app.MapHealthChecks("/health/prod", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("production") && check.Tags.Contains("critical"),
    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse // 可以使用UI的响应格式
});

// 开发环境的健康检查，包含所有项或特定的开发标签项
app.MapHealthChecks("/health/dev", new HealthCheckOptions
{
    Predicate = check => true, // 包含所有项
    ResponseWriter = WriteDetailedDevResponse // 自定义一个更详细的开发响应
});

自定义响应写入器 (ResponseWriter)： 默认的JSON输出可能不符合你的所有需求。你可以提供一个自定义的

ResponseWriter

来控制健康检查报告的输出格式和内容。

// 示例：一个更详细的开发环境响应写入器
private static Task WriteDetailedDevResponse(HttpContext httpContext, HealthReport report)
{
    httpContext.Response.ContentType = "application/json";

    var result = new
    {
        status = report.Status.ToString(),
        totalDuration = report.TotalDuration,
        checks = report.Entries.Select(e => new
        {
            name = e.Key,
            status = e.Value.Status.ToString(),
            duration = e.Value.Duration,
            description = e.Value.Description,
            exception = e.Value.Exception?.Message, // 在开发环境暴露异常信息
            tags = e.Value.Tags
        })
    };

    return httpContext.Response.WriteAsync(JsonSerializer.Serialize(result, new JsonSerializerOptions { WriteIndented = true }));
}

通过这种方式，你可以在开发环境显示详细的错误信息甚至堆栈跟踪（当然，生产环境绝对要避免），而在生产环境只显示简洁的状态码和有限的信息，甚至只显示一个简单的“OK”或“FAIL”，以保护敏感信息和减少攻击面。这种定制化能力让健康检查真正适应了不同部署场景的需求。

面对健康检查的常见陷阱与优化策略有哪些？

健康检查虽然强大，但在实际应用中也容易踩坑。理解这些陷阱并掌握优化策略，能让你的系统更稳定、更可靠。

陷阱：健康检查本身成为性能瓶颈。 如果你的健康检查逻辑过于复杂、耗时，或者过于频繁地查询高负载资源，它本身就可能给系统带来额外的压力，甚至导致假性不健康。比如，一个每秒都对数据库执行复杂查询的健康检查，可能会让数据库不堪重负。
- 优化策略：异步化和超时。 确保你的健康检查方法是异步的（
```
async/await
```
  ），这样不会阻塞线程池。同时，为每个检查项设置合理的超时时间 (
```
WithTimeout
```
  )，避免某个依赖响应慢导致整个健康检查卡住。对于某些不需要实时更新的检查，可以考虑在检查逻辑内部加入简单的缓存机制，比如每隔5秒才真正执行一次检查，其他时候返回缓存结果。
```
builder.Services.AddHealthChecks()
    .AddSqlServer(builder.Configuration.GetConnectionString("DefaultConnection"))
    .WithTimeout(TimeSpan.FromSeconds(5)); // 设置5秒超时
```
陷阱：假阳性或假阴性报告。 健康检查报告“健康”但服务实际不可用（假阳性），或者报告“不健康”但服务实际正常（假阴性）。这通常是因为检查逻辑不够精确，或者阈值设置不当。
- 优化策略：精确检查和阈值。 不要只检查“数据库连接成功”，而是尝试执行一个简单的读写操作，确认数据库确实可用。对于磁盘空间，不要等到完全满了才报告不健康，可以设置一个警告阈值（例如，剩余空间低于10%就报告
```
Degraded
```
  状态）。结合多个检查项来判断一个服务的整体健康状况，避免单一故障点导致误报。
陷阱：安全漏洞。 默认的健康检查终结点可能会暴露一些内部信息（如依赖名称、异常消息），如果未经保护地暴露给公共网络，可能成为潜在的安全风险。
- 优化策略：限制访问和信息过滤。 最好的做法是将健康检查终结点限制在内部网络或通过API网关进行访问。如果必须暴露，确保使用身份验证和授权。同时，使用自定义
```
ResponseWriter
```
  在生产环境中过滤掉所有敏感信息，只返回最简单的状态码。
陷阱：过度检查或检查不足。 检查项过多会增加维护成本和性能开销；检查项过少则可能无法发现真正的服务问题。
- 优化策略：平衡与关键性评估。 识别你应用最核心、最容易出问题的依赖，优先对它们进行健康检查。对于一些不那么关键的组件，可以考虑降低检查频率或只在
```
Degraded
```
  状态下才触发更深层次的检查。我的经验是，专注于那些一旦出问题就会导致服务完全不可用的依赖，比如主数据库、核心消息队列、身份认证服务等。