feat(health): 添加健康检查端点支持存活和就绪探针

添加健康检查功能，包含存活探针（/health/live）和就绪探针（/health/ready）端点，用于容器编排和负载均衡健康监控。存活探针仅检查进程运行状态，就绪探针会检查FreeSql业务库和SQLite日志数据库等关键依赖。同时提供汇总端点（/health, /healthz）并返回标准化的JSON响应格式。

Author: Deali-Axy

src/StarBlog.Api/Extensions/ConfigureHealthChecks.cs

@@ -0,0 +1,100 @@
+using System.Text.Json;
+using Microsoft.AspNetCore.Diagnostics.HealthChecks;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+using StarBlog.Api.HealthChecks;
+
+namespace StarBlog.Api.Extensions;
+
+public static class ConfigureHealthChecks {
+    /// <summary>
+    /// 为 StarBlog.Api 注册健康检查（Health Checks）。
+    /// - Liveness：仅用于判断进程是否还“活着”（不依赖外部资源）
+    /// - Readiness：用于判断服务是否“就绪”（会检查关键依赖是否可用，如数据库）
+    /// </summary>
+    public static void AddStarBlogHealthChecks(this IServiceCollection services) {
+        services
+            .AddHealthChecks()
+            .AddCheck<LiveHealthCheck>(
+                name: "live",
+                tags: new[] { HealthCheckTags.Live }
+            )
+            .AddCheck<SqliteLogHealthCheck>(
+                name: "sqlite-log",
+                tags: new[] { HealthCheckTags.Ready }
+            )
+            .AddCheck<FreeSqlHealthCheck>(
+                name: "freesql",
+                tags: new[] { HealthCheckTags.Ready }
+            );
+    }
+
+    /// <summary>
+    /// 映射健康检查端点：
+    /// - /health/live：存活探针
+    /// - /health/ready：就绪探针
+    /// - /health、/healthz：汇总探针（兼容别名）
+    /// </summary>
+    public static WebApplication MapStarBlogHealthChecks(this WebApplication app) {
+        // HealthChecks：最常见的三种探针（以及 /healthz 兼容别名）
+        app.MapHealthChecks(
+                "/health/live",
+                CreateHealthCheckOptions(r => r.Tags.Contains(HealthCheckTags.Live))
+            )
+            .AllowAnonymous();
+
+        app.MapHealthChecks(
+                "/health/ready",
+                CreateHealthCheckOptions(r => r.Tags.Contains(HealthCheckTags.Ready))
+            )
+            .AllowAnonymous();
+
+        app.MapHealthChecks(
+                "/health",
+                CreateHealthCheckOptions(_ => true)
+            )
+            .AllowAnonymous();
+
+        app.MapHealthChecks(
+                "/healthz",
+                CreateHealthCheckOptions(_ => true)
+            )
+            .AllowAnonymous();
+
+        return app;
+    }
+
+    /// <summary>
+    /// 统一的 HealthCheckOptions，输出 JSON，并按健康状态返回 HTTP 状态码。
+    /// </summary>
+    public static HealthCheckOptions CreateHealthCheckOptions(Func<HealthCheckRegistration, bool> predicate) {
+        return new HealthCheckOptions {
+            Predicate = predicate,
+            AllowCachingResponses = false,
+            ResultStatusCodes = {
+                [HealthStatus.Healthy] = StatusCodes.Status200OK,
+                [HealthStatus.Degraded] = StatusCodes.Status200OK,
+                [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
+            },
+            ResponseWriter = WriteResponseAsync
+        };
+    }
+
+    private static Task WriteResponseAsync(HttpContext context, HealthReport report) {
+        context.Response.ContentType = "application/json; charset=utf-8";
+
+        var payload = new {
+            status = report.Status.ToString(),
+            totalDurationMs = report.TotalDuration.TotalMilliseconds,
+            checks = report.Entries.Select(entry => new {
+                name = entry.Key,
+                status = entry.Value.Status.ToString(),
+                durationMs = entry.Value.Duration.TotalMilliseconds,
+                description = entry.Value.Description,
+                error = entry.Value.Exception?.Message,
+                data = entry.Value.Data.Count == 0 ? null : entry.Value.Data
+            })
+        };
+
+        return context.Response.WriteAsync(JsonSerializer.Serialize(payload));
+    }
+}

src/StarBlog.Api/HealthChecks/FreeSqlHealthCheck.cs

@@ -0,0 +1,30 @@
+using FreeSql;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+
+namespace StarBlog.Api.HealthChecks;
+
+/// <summary>
+/// Readiness：检查 FreeSql 业务库是否可用。
+/// 这里使用最轻量的探测语句（select 1），用于验证连接与执行通道正常。
+/// </summary>
+public sealed class FreeSqlHealthCheck : IHealthCheck {
+    private readonly IFreeSql _freeSql;
+
+    public FreeSqlHealthCheck(IFreeSql freeSql) {
+        _freeSql = freeSql;
+    }
+
+    public Task<HealthCheckResult> CheckHealthAsync(
+        HealthCheckContext context,
+        CancellationToken cancellationToken = default
+    ) {
+        try {
+            _freeSql.Ado.ExecuteScalar("select 1");
+            return Task.FromResult(HealthCheckResult.Healthy("FreeSql database is reachable."));
+        }
+        catch (Exception ex) {
+            return Task.FromResult(HealthCheckResult.Unhealthy("FreeSql database check failed.", ex));
+        }
+    }
+}
+

src/StarBlog.Api/HealthChecks/HealthCheckTags.cs

@@ -0,0 +1,12 @@
+namespace StarBlog.Api.HealthChecks;
+
+/// <summary>
+/// Health Check 标签：
+/// - Live：存活探针（不检查外部依赖）
+/// - Ready：就绪探针（检查关键依赖）
+/// </summary>
+public static class HealthCheckTags {
+    public const string Live = "live";
+    public const string Ready = "ready";
+}
+

src/StarBlog.Api/HealthChecks/LiveHealthCheck.cs

@@ -0,0 +1,17 @@
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+
+namespace StarBlog.Api.HealthChecks;
+
+/// <summary>
+/// 存活探针：只要进程能响应 HTTP，就返回 Healthy。
+/// 适合容器/负载均衡用于判断服务是否需要重启（不依赖数据库/缓存等外部资源）。
+/// </summary>
+public sealed class LiveHealthCheck : IHealthCheck {
+    public Task<HealthCheckResult> CheckHealthAsync(
+        HealthCheckContext context,
+        CancellationToken cancellationToken = default
+    ) {
+        return Task.FromResult(HealthCheckResult.Healthy("Service is running."));
+    }
+}
+

src/StarBlog.Api/HealthChecks/SqliteLogHealthCheck.cs

@@ -0,0 +1,30 @@
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+using StarBlog.Data;
+
+namespace StarBlog.Api.HealthChecks;
+
+/// <summary>
+/// Readiness：检查 EF Core 的 SQLite-Log（访问统计库）是否可连接。
+/// </summary>
+public sealed class SqliteLogHealthCheck : IHealthCheck {
+    private readonly AppDbContext _dbContext;
+
+    public SqliteLogHealthCheck(AppDbContext dbContext) {
+        _dbContext = dbContext;
+    }
+
+    public async Task<HealthCheckResult> CheckHealthAsync(
+        HealthCheckContext context,
+        CancellationToken cancellationToken = default
+    ) {
+        try {
+            var canConnect = await _dbContext.Database.CanConnectAsync(cancellationToken);
+            return canConnect
+                ? HealthCheckResult.Healthy("SQLite-Log database is reachable.")
+                : HealthCheckResult.Degraded("SQLite-Log database is not reachable (degraded).");
+        }
+        catch (Exception ex) {
+            return HealthCheckResult.Unhealthy("SQLite-Log database check failed.", ex);
+        }
+    }
+}

src/StarBlog.Api/Program.cs

@@ -59,6 +59,9 @@
 builder.Services.AddVisitRecord();
 builder.Services.AddHttpClient();
 
+// HealthChecks：提供 /health（汇总）、/health/live（存活）、/health/ready（就绪）端点
+builder.Services.AddStarBlogHealthChecks();
+
 // CORS：Next.js 前端跨域调用需要（带 Cookie/凭据时必须显式列出允许的 Origin）
 builder.Services.AddCors(options => {
     options.AddDefaultPolicy(policyBuilder => {
@@ -146,6 +149,8 @@
 // Swagger UI 默认需要已认证用户才能访问（避免生产环境直接暴露文档）
 app.UseSwaggerPkg();
 
+app.MapStarBlogHealthChecks();
+
 app.MapControllers();
 
 app.Run();