健康检查

数据墙DBW 提供 /health 端点，用于实时检测服务和数据库的可用性。健康检查分布在三个层级——运行时全局、数据源和实体——每一层可以独立配置。

架构

健康检查的执行逻辑：

GET /health
  ├── 数据源检查：每个 data-source 执行一次简单查询（如 SELECT 1）
  │     └── 验证连接可用 + 响应时间是否在阈值内
  ├── 实体检查：每个启用的实体执行一次查询（取前 N 行）
  │     └── 验证表/视图可访问 + 响应时间在阈值内
  │     └── 存储过程：自动排除（需要参数，非确定性）
  └── 聚合报告：综合所有检查结果，返回统一状态

运行时健康配置

{
  "runtime": {
    "health": {
      "enabled": true,
      "roles": ["admin", "monitoring"],
      "cache-ttl-seconds": 10,
      "max-query-parallelism": 4
    }
  }
}

字段	说明	默认值
enabled	全局启用健康检查端点	true
roles	允许访问 /health 的角色数组	null
cache-ttl-seconds	健康检查结果缓存时间（秒），在此期间重复请求直接返回缓存	5
max-query-parallelism	并发执行健康检查查询的最大并行数（范围：1-8）	4

CLI 配置：

dab configure \
  --runtime.health.enabled true \
  --runtime.health.roles "admin,monitoring" \
  --runtime.health.cache-ttl-seconds 10 \
  --runtime.health.max-query-parallelism 4

基于角色的访问行为

条件	Development 行为	Production 行为
roles 省略或 null	所有用户可访问	返回 403 Forbidden
roles 包含指定角色	仅指定角色可访问	仅指定角色可访问
roles 包含 anonymous	公共访问	公共访问

IMPORTANT

生产模式下必须显式定义 roles，否则所有请求返回 403。要允许公共访问（如容器编排平台探测），设置 "roles": ["anonymous"]。

数据源健康检查

{
  "data-source": {
    "health": {
      "enabled": true,
      "name": "main-db",
      "threshold-ms": 1500
    }
  }
}

字段	说明	默认值
enabled	是否对数据源执行健康检查	true
name	在 /health 响应中的标识符	使用 database-type 值（如 mssql）
threshold-ms	响应时间阈值（毫秒），超时标记为降级	1000

数据源健康检查执行数据库特定的简单查询（SQL Server 执行 SELECT 1），验证连接可用且响应在阈值内。

name 属性是可选的，有助于在健康报告中区分共享相同数据库类型的多个数据源。

实体级健康检查

{
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 50,
        "threshold-ms": 500
      }
    }
  }
}

字段	说明	默认值
enabled	是否对此实体执行健康检查	true
first	每次健康检查查询返回的行数（范围：1-500）	100
threshold-ms	响应时间阈值（毫秒）	1000

first 值必须小于等于 runtime.pagination.max-page-size。较小的值可加快健康检查速度。

NOTE

存储过程实体自动从健康检查中排除，因为存储过程需要调用参数且执行结果可能不是确定性的。

如果实体同时启用了 REST 和 GraphQL，健康检查会为两者分别运行，在报告中显示为两个独立条目，分别带有 rest 和 graphql 标签。rest.enabled: false 或 graphql.enabled: false 的实体将被排除在对应检查之外。

根路径简化端点

根路径 / 提供一个简化的健康端点，始终公开可访问，无需认证。它返回基本服务信息（版本、状态），不运行任何健康检查：

curl http://localhost:5000/

{
  "version": "1.2.3",
  "status": "Running"
}

响应格式

全部健康

curl http://localhost:5000/health

{
  "status": "Healthy",
  "version": "1.2.3",
  "app-name": "dab_oss_1.2.3",
  "currentRole": "admin",
  "timestamp": "2025-01-15T10:30:00Z",
  "configuration": {
    "rest": true,
    "graphql": true,
    "mcp": true,
    "caching": false,
    "telemetry": true,
    "mode": "Production"
  },
  "checks": [
    {
      "status": "Healthy",
      "name": "main-db",
      "tags": ["data-source"],
      "data": {
        "response-ms": 12,
        "threshold-ms": 1500
      }
    },
    {
      "status": "Healthy",
      "name": "Book",
      "tags": ["rest", "endpoint"],
      "data": {
        "response-ms": 45,
        "threshold-ms": 500
      }
    },
    {
      "status": "Healthy",
      "name": "Book",
      "tags": ["graphql", "endpoint"],
      "data": {
        "response-ms": 38,
        "threshold-ms": 500
      }
    }
  ]
}

部分降级

{
  "status": "Degraded",
  "version": "1.2.3",
  "currentRole": "admin",
  "timestamp": "2025-01-15T10:30:00Z",
  "checks": [
    {
      "status": "Healthy",
      "name": "main-db",
      "tags": ["data-source"],
      "data": { "response-ms": 15, "threshold-ms": 1500 }
    },
    {
      "status": "Unhealthy",
      "name": "Author",
      "tags": ["rest", "endpoint"],
      "data": { "response-ms": 2100, "threshold-ms": 500 }
    }
  ]
}

全部不可用

{
  "status": "Unhealthy",
  "version": "1.2.3",
  "currentRole": "anonymous",
  "timestamp": "2025-01-15T10:30:00Z",
  "checks": [
    {
      "status": "Unhealthy",
      "name": "main-db",
      "tags": ["data-source"],
      "data": { "response-ms": 30000, "threshold-ms": 1500 }
    }
  ]
}

状态定义

状态	含义
Healthy	所有检查通过，响应在阈值内
Degraded	至少一个检查失败或超阈值，但服务仍可运行
Unhealthy	关键组件（如数据源）不可用，服务可能无法正常响应

currentRole 字段

健康响应包含 currentRole 字段，指示用于授权请求的角色。数据墙DBW 使用以下优先级解析当前角色：

1. X-MS-API-ROLE 头 — 如果存在，则使用指定的角色。
2. authenticated — 如果请求包含有效的主体（如 JWT 令牌）但没有 X-MS-API-ROLE 头。
3. anonymous — 如果没有主体存在。

NOTE

此功能为 数据墙DBW 2.0 预览版。

容器编排集成

/health 端点可直接用作容器编排平台的探测地址。

Kubernetes 示例

livenessProbe:
  httpGet:
    path: /health
    port: 5000
  initialDelaySeconds: 10
  periodSeconds: 30

readinessProbe:
  httpGet:
    path: /health
    port: 5000
  initialDelaySeconds: 5
  periodSeconds: 10

• 存活探测（livenessProbe）：确认进程未死锁或崩溃。/health 返回非 200 时重启容器。
• 就绪探测（readinessProbe）：确认服务已就绪可以接收流量。数据库连接未建立时 /health 返回不健康，不分配流量。

Docker 示例

docker run --health-cmd="curl -f http://localhost:5000/health || exit 1" ...

性能考量

• 缓存：通过 cache-ttl-seconds 设置健康检查结果缓存（默认 5 秒），避免短时间内大量探测请求并发执行数据库查询。设置为 0 可禁用缓存。
• 并行度：通过 max-query-parallelism 限制并发健康检查查询数（默认 4，范围 1-8），防止健康检查本身成为数据库负载来源。
• 实体检查范围：如果实体数量很多，仅对关键实体启用健康检查，非关键实体通过 health.enabled: false 关闭。
• first 值：实体健康检查的 first 设较小值（如 5-20），减少每次检查的查询量。

其他注意事项

• 健康检查遵守实体和端点授权。如果角色缺少访问实体的权限，健康检查会报告该实体失败，这是预期行为。
• 存储过程被排除，因为它们需要参数且可能有副作用。
• rest.enabled: false 或 graphql.enabled: false 的实体被排除在对应检查之外。
• 当 data-source.health.enabled: false 时，跳过数据源检查。

下一步

• 日志级别 — 通过日志诊断健康检查失败原因。
• 链路追踪与监控集成 — OpenTelemetry 追踪请求详情。