健康检查

更新: 2026-10-16 15:20:09   字数: 0 字   时长: 0 分钟

健康检查回答的是「这个资源现在能用了吗」。Aspire 用它来判断资源何时就绪，并作为 WaitFor 等待的目标。

两种检查

类型	API	说明
容器存活检查	由集成自动配置	例如 PostgreSQL 容器就绪探测。
HTTP 健康检查	WithHttpHealthCheck("/health")	对资源的某个端点发起 HTTP 请求并校验状态码。

为资源添加 HTTP 健康检查

var builder = DistributedApplication.CreateBuilder(args);

var catalogApi = builder.AddContainer("catalog-api", "catalog-api")
    .WithHttpEndpoint(targetPort: 8080)
    .WithHttpHealthCheck("/health");

builder.AddProject<Projects.WebApp>("webapp")
    .WithReference(catalogApi)
    .WaitFor(catalogApi);   // 等待 /health 返回 200

WithHttpHealthCheck 也可以直接用在项目资源上：

var backend = builder.AddProject<Projects.Backend>("backend")
    .WithHttpHealthCheck("/health");

builder.AddProject<Projects.Frontend>("frontend")
    .WithReference(backend)
    .WaitFor(backend);

ASP.NET Core 项目不必手写端点

模板中的 ServiceDefaults 已经通过 MapDefaultEndpoints() 暴露了 /health 与 /alive，所以 .NET 项目通常只需要在 AppHost 里声明 WithHttpHealthCheck("/health") 即可。

WaitFor：等待依赖就绪

WaitFor 会让当前资源等待指定依赖进入就绪状态后再启动：

builder.AddProject<Projects.Web>("web")
    .WithReference(api)
    .WaitFor(api);

它与单纯 WithReference 的区别：

方式	注入连接信息	等待就绪
WithReference	✅	❌
WaitFor	❌	✅

两者通常成对使用：WithReference 负责「怎么连」，WaitFor 负责「什么时候启动」。

不要滥用 WaitFor

WaitFor 会把资源变成串行启动。如果两个服务互相独立，不要为了让日志好看而随意添加等待，否则会显著拉长启动时间。

自定义健康检查

对于更复杂的就绪判断（例如「数据库迁移完成」），可以在 AppHost 的服务集合中注册健康检查，再关联到资源：

var builder = DistributedApplication.CreateBuilder(args);

var startAfter = DateTime.Now.AddSeconds(30);

builder.Services.AddHealthChecks().AddCheck("mycheck", () =>
    DateTime.Now > startAfter
        ? HealthCheckResult.Healthy()
        : HealthCheckResult.Unhealthy());

var pg = builder.AddPostgres("pg")
    .WithHealthCheck("mycheck");

builder.AddProject<Projects.MyApp>("myapp")
    .WithReference(pg)
    .WaitFor(pg);   // 既要容器运行，也要 "mycheck" 通过

AddCheck 注册检查，WithHealthCheck 把它关联到具体资源。

TypeScript AppHost 的限制

TypeScript AppHost 目前尚不支持通过 builder.Services.AddHealthChecks() 注册自定义健康检查。

在服务端编写健康检查

在 ASP.NET Core 服务中注册自定义检查：

builder.Services.AddHealthChecks()
    .AddCheck<DatabaseReadyHealthCheck>("database-ready");

然后在 Program.cs 中映射端点（ServiceDefaults 已处理默认情况）：

app.MapHealthChecks("/health");

仪表板集成

资源健康状态会实时显示在 Aspire 仪表板中。当资源正在等待健康检查通过时，仪表板会显示当前状态与失败详情，便于快速定位问题。